Skip to content

Modern Docker Management, Designed for Everyone

14.7 KB
Raw Blame
package dashboard

import (
	"context"
	"errors"
	"log/slog"
	"net/http"
	"net/url"
	"time"

	"github.com/danielgtaylor/huma/v2"
	"github.com/getarcaneapp/arcane/types/v2/base"
	"github.com/getarcaneapp/arcane/types/v2/container"
	"github.com/getarcaneapp/arcane/types/v2/dashboard"
	"github.com/getarcaneapp/arcane/types/v2/image"
	"github.com/getarcaneapp/arcane/types/v2/version"
	"github.com/getarcaneapp/arcane/types/v2/volume"
	kit "go.getarcane.app/kit/pkg"
	"go.getarcane.app/streams/agg"

	"github.com/getarcaneapp/arcane/backend/v2/internal/common"
	"github.com/getarcaneapp/arcane/backend/v2/internal/environment"
	"github.com/getarcaneapp/arcane/backend/v2/pkg/authz"
	"github.com/getarcaneapp/arcane/backend/v2/pkg/remenv"
	"github.com/getarcaneapp/arcane/backend/v2/pkg/utils/handlerutil"
)

type DashboardHandler struct {
	dashboardService   *DashboardService
	environmentService *environment.EnvironmentService

	// remoteStreamHub shares one poller per remote environment across every
	// connected stream client instead of polling per client × environment.
	remoteStreamHub *agg.Hub[dashboard.StreamEvent]
	localStreamHub  *agg.Hub[dashboard.StreamEvent]
}

type GetDashboardInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	DebugAllGood  bool   `query:"debugAllGood" default:"false" doc:"Debug mode: force an empty action item list"`
	IncludeTables bool   `query:"includeTables" default:"true" doc:"Include the first-page container and image tables"`
}

const (
	dashboardStreamHeartbeatInterval    = 15 * time.Second
	dashboardStreamLocalPollInterval    = 15 * time.Second
	dashboardStreamRemotePollInterval   = 15 * time.Second
	dashboardStreamEnvReconcileInterval = 30 * time.Second
	dashboardStreamRemotePollTimeout    = 15 * time.Second
	dashboardStreamEventBuffer          = 64
)

// NewHandler builds the dashboard HTTP handler. Cross-domain handlers (the
// multiplexed client stream) compose it rather than reaching into its fields.
func NewHandler(dashboardService *DashboardService, environmentService *environment.EnvironmentService) *DashboardHandler {
	return &DashboardHandler{
		dashboardService:   dashboardService,
		environmentService: environmentService,
		remoteStreamHub:    agg.NewHub[dashboard.StreamEvent](),
		localStreamHub:     agg.NewHub[dashboard.StreamEvent](),
	}
}

func (h *DashboardHandler) GetDashboard(ctx context.Context, input *GetDashboardInput) (*handlerutil.Out[dashboard.Snapshot], error) {
	// EnvironmentID is consumed by env proxy/auth middleware for routing/validation.
	_ = input.EnvironmentID

	snapshot, err := h.dashboardService.GetSnapshot(ctx, DashboardActionItemsOptions{
		DebugAllGood: input.DebugAllGood,
	}, input.IncludeTables)
	if err != nil {
		return nil, huma.Error500InternalServerError(err.Error())
	}

	if snapshot == nil {
		return nil, huma.Error500InternalServerError("dashboard snapshot not available")
	}

	return &handlerutil.Out[dashboard.Snapshot]{
		Body: base.ApiResponse[dashboard.Snapshot]{
			Success: true,
			Data:    *snapshot,
		},
	}, nil
}

// trimDashboardStreamSnapshotInternal drops the first-page container/image
// tables: the all-environments dashboard only reads the aggregate counters,
// and re-sending table rows for every environment on every poll would bloat
// the stream. Only remote snapshots (decoded fresh per poll) pass through
// here; the local producer gets a snapshot built without tables instead.
func trimDashboardStreamSnapshotInternal(snapshot *dashboard.Snapshot) *dashboard.Snapshot {
	if snapshot == nil {
		return nil
	}
	snapshot.Containers.Data = nil
	snapshot.Images.Data = nil
	return snapshot
}

func (h *DashboardHandler) RunLocalStreamProducer(ctx context.Context, debugAllGood bool, events chan<- dashboard.StreamEvent) {
	h.localStreamHub.Subscribe(ctx, kit.Ternary(debugAllGood, "local:debugAllGood", "local"),
		func(runCtx context.Context, publish func(dashboard.StreamEvent)) {
			lastError := ""

			poll := func() {
				snapshot, err := h.dashboardService.GetSnapshot(runCtx, DashboardActionItemsOptions{
					DebugAllGood: debugAllGood,
				}, false)
				if err == nil && snapshot == nil {
					err = common.Classify(common.ErrUnavailable, errors.New("dashboard snapshot not available"))
				}
				if err != nil {
					if runCtx.Err() != nil {
						return
					}
					// A failing snapshot must not end the stream; surface the error
					// once per distinct message and keep polling.
					if msg := err.Error(); msg != lastError {
						lastError = msg
						publish(dashboard.StreamEvent{
							Type:          "error",
							EnvironmentID: "0",
							Error:         msg,
							Timestamp:     time.Now(),
						})
					}
					return
				}
				lastError = ""
				// Already built without tables; shared with other subscribers, so it
				// must not be trimmed (mutated) here.
				publish(dashboard.StreamEvent{
					Type:          "snapshot",
					EnvironmentID: "0",
					Snapshot:      snapshot,
					Timestamp:     time.Now(),
				})
			}

			poll()

			ticker := time.NewTicker(dashboardStreamLocalPollInterval)
			defer ticker.Stop()

			for {
				select {
				case <-runCtx.Done():
					return
				case <-ticker.C:
					poll()
				}
			}
		},
		func(event dashboard.StreamEvent) bool {
			return agg.Send(ctx, events, event)
		})
}

// RunRemoteStreamPollers keeps one poller goroutine per
// enabled remote environment, re-listing periodically so environments added
// or removed while the stream is open are picked up without a reconnect.
func (h *DashboardHandler) RunRemoteStreamPollers(ctx context.Context, ps *authz.PermissionSet, debugAllGood bool, events chan<- dashboard.StreamEvent) {
	agg.ReconcilePollersByKey(ctx,
		func(ctx context.Context) ([]environment.Environment, error) {
			environments, err := h.environmentService.ListActiveRemoteEnvironments(ctx)
			if err != nil {
				return nil, err
			}
			allowed := environments[:0]
			for _, environment := range environments {
				if ps.Allows(authz.PermDashboardRead, environment.ID) {
					allowed = append(allowed, environment)
				}
			}
			return allowed, nil
		},
		func(environment environment.Environment) string {
			return environment.ID
		},
		dashboardStreamEnvironmentVersionInternal,
		dashboardStreamEnvReconcileInterval,
		"dashboard stream",
		func(pollCtx context.Context, environment environment.Environment) {
			// One shared poller per environment (and debug variant) serves
			// every connected client; this subscriber only forwards its
			// events onto this client's stream.
			key := dashboardStreamEnvironmentVersionInternal(environment)
			if debugAllGood {
				key += ":debugAllGood"
			}
			h.remoteStreamHub.Subscribe(pollCtx, key,
				func(runCtx context.Context, publish func(dashboard.StreamEvent)) {
					h.runRemoteDashboardStreamPollerInternal(runCtx, environment, debugAllGood, publish)
				},
				func(event dashboard.StreamEvent) bool {
					return agg.Send(pollCtx, events, event)
				})
		})
}

func dashboardStreamEnvironmentVersionInternal(localEnvironment environment.Environment) string {
	if localEnvironment.UpdatedAt == nil {
		return localEnvironment.ID
	}
	return localEnvironment.ID + ":" + localEnvironment.UpdatedAt.UTC().Format(time.RFC3339Nano)
}

func (h *DashboardHandler) runRemoteDashboardStreamPollerInternal(ctx context.Context, localEnvironment environment.Environment, debugAllGood bool, publish func(dashboard.StreamEvent)) {
	environmentID := localEnvironment.ID
	// Tell the client this environment is covered before the first poll
	// completes so it can hold skeletons instead of assuming no data exists.
	publish(dashboard.StreamEvent{
		Type:          "pending",
		EnvironmentID: environmentID,
		Timestamp:     time.Now(),
	})

	lastError := ""

	poll := func() {
		pollCtx, cancelPoll := context.WithTimeout(ctx, dashboardStreamRemotePollTimeout)
		defer cancelPoll()

		currentEnvironment := localEnvironment
		if h.environmentService != nil {
			var ok bool
			currentEnvironment, ok = h.environmentService.GetActiveRemoteEnvironmentSnapshot(environmentID).Get()
			if !ok {
				return
			}
		}

		snapshot, err := h.fetchRemoteDashboardSnapshotInternal(pollCtx, currentEnvironment, debugAllGood)
		if err != nil && isDashboardEndpointMissingInternal(err) {
			// The agent runs a version without (or with an incompatible)
			// aggregate dashboard endpoint; the underlying data is still
			// there, so compose the snapshot from the granular endpoints.
			snapshot, err = h.fetchLegacyDashboardSnapshotInternal(pollCtx, currentEnvironment)
		}
		if err != nil {
			if ctx.Err() != nil {
				return
			}
			// A failing environment must not end the stream; surface the error
			// once per distinct message and keep polling.
			message, code := classifyDashboardStreamErrorInternal(err)
			if message != lastError {
				lastError = message
				publish(dashboard.StreamEvent{
					Type:          "error",
					EnvironmentID: environmentID,
					Error:         message,
					ErrorCode:     code,
					Timestamp:     time.Now(),
				})
			}
			return
		}
		lastError = ""
		// A successful snapshot proves the manager reaches this direct agent; edge liveness comes from the tunnel.
		if !currentEnvironment.IsEdge {
			// Legacy snapshots may succeed after the fetch deadline.
			heartbeatCtx, cancelHeartbeat := context.WithTimeout(ctx, 5*time.Second)
			defer cancelHeartbeat()
			if heartbeatErr := h.environmentService.UpdateEnvironmentHeartbeat(heartbeatCtx, environmentID); heartbeatErr != nil {
				slog.WarnContext(ctx, "Failed to update environment heartbeat", "environmentId", environmentID, "error", heartbeatErr)
			}
		}
		publish(dashboard.StreamEvent{
			Type:          "snapshot",
			EnvironmentID: environmentID,
			Snapshot:      trimDashboardStreamSnapshotInternal(snapshot),
			Timestamp:     time.Now(),
		})
	}

	poll()

	ticker := time.NewTicker(dashboardStreamRemotePollInterval)
	defer ticker.Stop()

	for {
		select {
		case <-ctx.Done():
			return
		case <-ticker.C:
			poll()
		}
	}
}

// fetchRemoteDashboardSnapshotInternal proxies the per-environment dashboard
// endpoint directly through the environment service so the raw remenv error
// survives for classification (proxyRemoteJSONInternal would translate it
// into a huma error first).
func (h *DashboardHandler) fetchRemoteDashboardSnapshotInternal(ctx context.Context, localEnvironment environment.Environment, debugAllGood bool) (*dashboard.Snapshot, error) {
	// The all-environments dashboard only reads the aggregate counters, so the
	// agent is asked to leave the container/image tables out of the payload.
	query := url.Values{"includeTables": {"false"}}
	if debugAllGood {
		query.Set("debugAllGood", "true")
	}
	path := "/api/environments/0/dashboard?" + query.Encode()

	var out base.ApiResponse[dashboard.Snapshot]
	if err := h.environmentService.ProxyJSONRequestForEnvironment(ctx, localEnvironment, http.MethodGet, path, nil, &out); err != nil {
		return nil, err
	}
	if !out.Success {
		return nil, common.Classify(common.ErrUnavailable, errors.New("dashboard snapshot not available"))
	}
	return &out.Data, nil
}

// fetchLegacyDashboardSnapshotInternal composes a dashboard snapshot from the
// granular endpoints (container counts, image usage counts, app version) that
// agents have exposed for far longer than the aggregate dashboard endpoint.
// Each piece is fetched independently so a partially compatible agent still
// yields partial data; only when every piece fails is an error returned.
func (h *DashboardHandler) fetchLegacyDashboardSnapshotInternal(ctx context.Context, localEnvironment environment.Environment) (*dashboard.Snapshot, error) {
	snapshot := &dashboard.Snapshot{
		ActionItems: dashboard.ActionItems{Items: []dashboard.ActionItem{}},
	}
	var errs []error
	attempted := 0

	attempted++
	var containerCounts base.ApiResponse[container.StatusCounts]
	if err := h.environmentService.ProxyJSONRequestForEnvironment(ctx, localEnvironment, http.MethodGet, "/api/environments/0/containers/counts", nil, &containerCounts); err != nil {
		errs = append(errs, err)
	} else {
		snapshot.Containers.Counts = containerCounts.Data
		if stopped := containerCounts.Data.StoppedContainers; stopped > 0 {
			snapshot.ActionItems.Items = append(snapshot.ActionItems.Items, dashboard.ActionItem{
				Kind:     dashboard.ActionItemKindStoppedContainers,
				Count:    stopped,
				Severity: dashboard.ActionItemSeverityWarning,
			})
		}
	}

	attempted++
	var imageCounts base.ApiResponse[image.UsageCounts]
	if err := h.environmentService.ProxyJSONRequestForEnvironment(ctx, localEnvironment, http.MethodGet, "/api/environments/0/images/counts", nil, &imageCounts); err != nil {
		errs = append(errs, err)
	} else {
		snapshot.ImageUsageCounts = imageCounts.Data
	}

	attempted++
	var volumeCounts base.ApiResponse[volume.UsageCounts]
	if err := h.environmentService.ProxyJSONRequestForEnvironment(ctx, localEnvironment, http.MethodGet, "/api/environments/0/volumes/counts", nil, &volumeCounts); err != nil {
		errs = append(errs, err)
	} else {
		snapshot.VolumeUsageCounts = &volumeCounts.Data
	}

	attempted++
	var versionInfo version.Info
	if err := h.environmentService.ProxyJSONRequestForEnvironment(ctx, localEnvironment, http.MethodGet, "/api/app-version", nil, &versionInfo); err != nil {
		errs = append(errs, err)
	} else {
		snapshot.VersionInfo = &versionInfo
	}

	if len(errs) == attempted {
		return nil, errors.Join(errs...)
	}
	return snapshot, nil
}

// isDashboardEndpointMissingInternal reports whether the aggregate dashboard
// endpoint is absent (404 on older agents) or speaks an incompatible payload
// shape (decode failure) — the cases the legacy composition can recover from.
func isDashboardEndpointMissingInternal(err error) bool {
	if statusErr, ok := errors.AsType[*remenv.StatusError](err); ok && statusErr.StatusCode == http.StatusNotFound {
		return true
	}
	_, ok := errors.AsType[*remenv.DecodeError](err)
	return ok
}

// classifyDashboardStreamErrorInternal maps remote fetch failures to a
// user-facing message and a stable error code. A 404 means the agent predates
// the dashboard endpoint; a decode failure means its payload shape differs —
// both indicate a version mismatch between manager and agent.
func classifyDashboardStreamErrorInternal(err error) (string, string) {
	if isDashboardEndpointMissingInternal(err) {
		return "Agent does not provide the dashboard endpoint — the agent is likely running an older Arcane version and should be upgraded", dashboard.StreamErrorCodeAgentIncompatible
	}
	if transportErr, ok := errors.AsType[*remenv.TransportError](err); ok {
		return transportErr.Error(), dashboard.StreamErrorCodeUnreachable
	}
	if statusErr, ok := errors.AsType[*remenv.StatusError](err); ok && (statusErr.StatusCode == http.StatusUnauthorized || statusErr.StatusCode == http.StatusForbidden) {
		return "Agent rejected the environment access token — regenerate the API key and update the agent", dashboard.StreamErrorCodeAuthFailed
	}
	return err.Error(), ""
}