Modern Docker Management, Designed for Everyone
Go composecontainer-managementcontainersdockerdocker-composedocker-managementgoself-hostedsveltekittypescriptweb-ui
package bootstrap
import (
"context"
"encoding/json/v2"
"errors"
"fmt"
"log/slog"
notificationdto "github.com/getarcaneapp/arcane/types/v2/notification"
"github.com/labstack/echo/v5"
kit "go.getarcane.app/kit/pkg"
"go.uber.org/fx"
"github.com/getarcaneapp/arcane/backend/v2/internal/config"
"github.com/getarcaneapp/arcane/backend/v2/internal/database"
"github.com/getarcaneapp/arcane/backend/v2/internal/environment"
"github.com/getarcaneapp/arcane/backend/v2/internal/event"
"github.com/getarcaneapp/arcane/backend/v2/internal/middleware"
"github.com/getarcaneapp/arcane/backend/v2/internal/notification"
"github.com/getarcaneapp/arcane/backend/v2/pkg/libarcane/edge"
"github.com/getarcaneapp/arcane/backend/v2/pkg/utils/concurrency"
)
// registerEdgeTunnelRoutes configures the manager-side edge tunnel server.
// It registers the WebSocket route and prepares gRPC service state on the shared listener.
// Returns the TunnelServer for graceful shutdown.
func registerEdgeTunnelRoutes(
ctx context.Context,
lifecycle fx.Lifecycle,
cfg *config.Config,
apiGroup *echo.Group,
environmentService *environment.EnvironmentService,
eventService *event.EventService,
notificationService *notification.NotificationService,
registry *edge.TunnelRegistry,
) *edge.TunnelServer {
// Resolver that validates API key and returns the environment ID
resolver := func(ctx context.Context, token string) (string, error) {
return environmentService.ResolveEdgeEnvironmentByToken(ctx, token)
}
// Status callback to update environment status when agent connects/disconnects
statusCallback := func(ctx context.Context, envID string, connected bool) {
handleEdgeStatusChange(ctx, environmentService, eventService, envID, connected)
}
eventCallback := func(ctx context.Context, envID string, evt *edge.TunnelEvent) error {
return handleEdgeEventInternal(ctx, envID, evt, eventService, notificationService)
}
server := edge.NewTunnelServerWithRegistry(registry, resolver, statusCallback)
server.Config = &edge.Config{
EdgeMTLSMode: cfg.EdgeMTLSMode,
EdgeMTLSCAFile: cfg.EdgeMTLSCAFile,
EdgeMTLSCertFile: cfg.EdgeMTLSCertFile,
EdgeMTLSKeyFile: cfg.EdgeMTLSKeyFile,
EdgeMTLSServerName: cfg.EdgeMTLSServerName,
EdgeMTLSAssetsDir: cfg.EdgeMTLSAssetsDir,
AppURL: cfg.GetAppURL(),
ManagerApiUrl: cfg.ManagerApiUrl,
}
server.NameResolver = func(ctx context.Context, envID string) (string, error) {
env, err := environmentService.GetEnvironmentByID(ctx, envID)
if err != nil {
return "", err
}
if env == nil {
return "", nil
}
return env.Name, nil
}
server.EventCallback = eventCallback
server.EnrollmentCallback = func(ctx context.Context, envID, remoteAddr string, certIssued, caGenerated, reenrolled bool) {
if eventService == nil {
return
}
envName := ""
if env, err := environmentService.GetEnvironmentByID(ctx, envID); err == nil && env != nil {
envName = env.Name
}
envIDCopy := envID
envNameCopy := envName
_, _ = eventService.CreateEvent(ctx, event.CreateEventRequest{
Type: event.EventTypeEnvironmentMTLSEnroll,
Severity: kit.Ternary(reenrolled, event.EventSeverityWarning, event.EventSeverityInfo),
Title: "Edge mTLS enrollment",
Description: "Edge agent completed mTLS enrollment from " + remoteAddr,
ResourceType: new("environment"),
ResourceID: &envIDCopy,
ResourceName: &envNameCopy,
EnvironmentID: &envIDCopy,
Metadata: database.JSON{"remoteAddr": remoteAddr, "reenrollment": reenrolled},
})
createEdgeMTLSIssueEventsInternal(ctx, eventService, envIDCopy, envNameCopy, remoteAddr, certIssued, caGenerated, reenrolled)
}
var stopCleanup func(context.Context) error
lifecycle.Append(fx.Hook{
OnStart: func(context.Context) error {
var err error
stopCleanup, err = concurrency.StartSupervised(ctx, "edge tunnel cleanup", func(runCtx context.Context) error {
server.StartCleanupLoop(runCtx)
return nil
})
return err
},
OnStop: func(stopCtx context.Context) error {
if stopCleanup == nil {
return nil
}
return stopCleanup(stopCtx)
},
})
apiGroup.POST("/tunnel/poll", server.HandlePoll, middleware.PerIPRateLimit(6000, 1200), middleware.PerAgentTokenRateLimit(60, 30))
// Rate-limit agent mTLS enrollment per-IP. Enrollment is authenticated
// only by the agent token, so we cap bursts to mitigate brute-force or
// token-abuse attempts without impacting normal agent lifecycles.
apiGroup.POST("/tunnel/mtls/enroll", server.HandleMTLSEnroll, middleware.PerIPRateLimit(10, 3), middleware.PerAgentTokenRateLimit(10, 3))
apiGroup.GET("/tunnel/connect", server.HandleConnect, middleware.PerIPRateLimit(60, 30), middleware.PerAgentTokenRateLimit(10, 3))
slog.InfoContext(ctx, "Configured edge tunnel server",
"pollEnabled", true,
"grpcEnabled", !cfg.AgentMode,
"websocketEnabled", true,
"muxEnabled", !cfg.EdgeMuxDisabled,
)
return server
}
func createEdgeMTLSIssueEventsInternal(ctx context.Context, eventService *event.EventService, envID, envName, remoteAddr string, certIssued, caGenerated, reenrolled bool) {
if eventService == nil {
return
}
if caGenerated {
_, _ = eventService.CreateEvent(ctx, event.CreateEventRequest{
Type: event.EventTypeEnvironmentMTLSCAGenerated,
Severity: event.EventSeverityInfo,
Title: "Edge mTLS CA generated",
Description: "Arcane generated a new edge mTLS certificate authority",
Metadata: database.JSON{"remoteAddr": remoteAddr, "kind": "ca"},
})
}
if certIssued {
_, _ = eventService.CreateEvent(ctx, event.CreateEventRequest{
Type: event.EventTypeEnvironmentMTLSCertIssued,
Severity: kit.Ternary(reenrolled, event.EventSeverityWarning, event.EventSeverityInfo),
Title: "Edge mTLS certificate issued",
Description: fmt.Sprintf("Arcane issued an edge mTLS client certificate for environment '%s'", envName),
ResourceType: new("environment"),
ResourceID: &envID,
ResourceName: &envName,
EnvironmentID: &envID,
Metadata: database.JSON{"remoteAddr": remoteAddr, "kind": "client", "reenrollment": reenrolled},
})
}
}
// handleEdgeStatusChange records a tunnel up/down transition: it updates the
// stored connection state, logs an event when the state actually changed, and
// wakes any open status streams.
func handleEdgeStatusChange(ctx context.Context, environmentService *environment.EnvironmentService, eventService *event.EventService, envID string, connected bool) {
envName := envID
env, getErr := environmentService.GetEnvironmentByID(ctx, envID)
if getErr != nil {
slog.WarnContext(ctx, "Failed to load environment before edge status update", "environmentId", envID, "error", getErr)
} else if env != nil && env.Name != "" {
envName = env.Name
}
if err := environmentService.UpdateEnvironmentConnectionState(ctx, envID, connected); err != nil {
slog.WarnContext(ctx, "Failed to update environment status on edge connect/disconnect", "environmentId", envID, "connected", connected, "error", err)
} else {
slog.InfoContext(ctx, "Updated edge environment connection state", "environmentId", envID, "connected", connected)
}
// Only log an event on an actual state transition; poll-mode tunnels can
// re-register without the environment ever having gone offline (session
// replacement, transport reconnects), and those are not worth an event.
alreadyInState := env != nil &&
((connected && env.Status == string(environment.EnvironmentStatusOnline)) ||
(!connected && env.Status == string(environment.EnvironmentStatusOffline)))
if !alreadyInState {
if err := createEdgeConnectionEvent(ctx, eventService, envID, envName, connected); err != nil {
slog.WarnContext(ctx, "Failed to create edge connection event", "environmentId", envID, "connected", connected, "error", err)
}
}
// This is the only funnel for "an edge tunnel came up or went down"
// (register, unregister and stale reaping all route through it), so it
// is where open status streams learn about it without polling.
environmentService.NotifyRuntimeStateChanged()
}
func createEdgeConnectionEvent(ctx context.Context, eventService *event.EventService, envID, envName string, connected bool) error {
if eventService == nil {
return nil
}
eventType := event.EventTypeEnvironmentDisconnect
title := "Edge Agent Disconnected"
description := fmt.Sprintf("Edge agent for environment '%s' disconnected", envName)
severity := event.EventSeverityWarning
if connected {
eventType = event.EventTypeEnvironmentConnect
title = "Edge Agent Connected"
description = fmt.Sprintf("Edge agent for environment '%s' connected", envName)
severity = event.EventSeveritySuccess
}
_, err := eventService.CreateEvent(ctx, event.CreateEventRequest{
Type: eventType,
Severity: severity,
Title: title,
Description: description,
ResourceType: new("environment"),
ResourceID: &envID,
ResourceName: &envName,
EnvironmentID: &envID,
})
if err != nil {
return fmt.Errorf("failed to create edge lifecycle event: %w", err)
}
return nil
}
func handleEdgeEventInternal(ctx context.Context, envID string, evt *edge.TunnelEvent, eventService *event.EventService, notificationService *notification.NotificationService) error {
if evt == nil {
return errors.New("event payload is required")
}
if evt.Type == edge.TunnelEventTypeNotificationDispatch {
if notificationService == nil {
return errors.New("notification service is not available for edge dispatch")
}
var payload notificationdto.DispatchRequest
if err := json.Unmarshal(evt.MetadataJSON, &payload); err != nil {
return fmt.Errorf("failed to decode edge notification dispatch payload: %w", err)
}
_, err := notificationService.DispatchNotificationForEnvironment(ctx, envID, payload)
if err != nil {
return fmt.Errorf("failed to dispatch edge notification: %w", err)
}
return nil
}
var metadata database.JSON
if len(evt.MetadataJSON) > 0 {
metadata = database.JSON{}
if err := json.Unmarshal(evt.MetadataJSON, &metadata); err != nil {
return fmt.Errorf("failed to decode event metadata: %w", err)
}
}
req := event.CreateEventRequest{
Type: event.EventType(evt.Type),
Severity: event.EventSeverity(evt.Severity),
Title: evt.Title,
Description: evt.Description,
ResourceType: new(evt.ResourceType),
ResourceID: new(evt.ResourceID),
ResourceName: new(evt.ResourceName),
UserID: new(evt.UserID),
Username: new(evt.Username),
EnvironmentID: &envID,
Metadata: metadata,
}
_, err := eventService.CreateEvent(ctx, req)
if err != nil {
return fmt.Errorf("failed to persist synced event: %w", err)
}
return nil
}