Skip to content

Modern Docker Management, Designed for Everyone

refactor: add 'poll' edge agent type and more reliable edge agent data (#2008)

Kyle Mendellcd2119fdf838
diff --git a/backend/internal/bootstrap/bootstrap.go b/backend/internal/bootstrap/bootstrap.go
index 8eace8225..c405d420c 100644
--- a/backend/internal/bootstrap/bootstrap.go
+++ b/backend/internal/bootstrap/bootstrap.go
@@ -184,8 +184,8 @@ func startEdgeTunnelClientIfConfigured(appCtx context.Context, cfg *config.Confi
slog.InfoContext(appCtx, "Starting edge tunnel client",
"transport_mode", edge.NormalizeEdgeTransport(cfg.EdgeTransport),
- "attempt_grpc", edge.UseGRPCEdgeTransport(cfg),
- "attempt_websocket", edge.UseWebSocketEdgeTransport(cfg),
+ "live_tunnel_attempt_grpc", edge.UseGRPCEdgeTransport(cfg) || (edge.UsePollEdgeTransport(cfg) && strings.TrimSpace(cfg.GetManagerGRPCAddr()) != ""),
+ "live_tunnel_attempt_websocket", edge.UseWebSocketEdgeTransport(cfg) || (edge.UsePollEdgeTransport(cfg) && strings.TrimSpace(cfg.GetManagerBaseURL()) != ""),
"manager_url", cfg.ManagerApiUrl,
)
errCh, err := edge.StartTunnelClientWithErrors(appCtx, cfg, router)
diff --git a/backend/internal/bootstrap/edge_bootstrap.go b/backend/internal/bootstrap/edge_bootstrap.go
index d9e3d8609..f46507bd3 100644
--- a/backend/internal/bootstrap/edge_bootstrap.go
+++ b/backend/internal/bootstrap/edge_bootstrap.go
@@ -3,7 +3,6 @@ package bootstrap
import (
"context"
"encoding/json"
- "errors"
"fmt"
"log/slog"
@@ -25,15 +24,7 @@ func registerEdgeTunnelRoutes(
) *edge.TunnelServer {
// Resolver that validates API key and returns the environment ID
resolver := func(ctx context.Context, token string) (string, error) {
- // Use the ApiKeyService which properly validates the key hash
- envID, err := appServices.ApiKey.GetEnvironmentByApiKey(ctx, token)
- if err != nil {
- return "", err
- }
- if envID == nil {
- return "", errors.New("API key is not linked to an environment")
- }
- return *envID, nil
+ return appServices.Environment.ResolveEdgeEnvironmentByToken(ctx, token)
}
// Status callback to update environment status when agent connects/disconnects
@@ -93,8 +84,10 @@ func registerEdgeTunnelRoutes(
server := edge.NewTunnelServer(resolver, statusCallback)
server.SetEventCallback(eventCallback)
go server.StartCleanupLoop(ctx)
+ apiGroup.POST("/tunnel/poll", server.HandlePoll)
apiGroup.GET("/tunnel/connect", server.HandleConnect)
slog.InfoContext(ctx, "Configured edge tunnel server",
+ "poll_enabled", true,
"grpc_enabled", !cfg.AgentMode,
"websocket_enabled", true,
)
diff --git a/backend/internal/bootstrap/router_bootstrap.go b/backend/internal/bootstrap/router_bootstrap.go
index 1a7ef67af..b9d142f94 100644
--- a/backend/internal/bootstrap/router_bootstrap.go
+++ b/backend/internal/bootstrap/router_bootstrap.go
@@ -25,6 +25,7 @@ var (
)
var loggerSkipPatterns = []string{
+ "POST /api/tunnel/poll",
"GET /api/environments/*/ws/containers/*/logs",
"GET /api/environments/*/ws/containers/*/stats",
"GET /api/environments/*/ws/containers/*/terminal",
@@ -117,7 +118,6 @@ func setupRouter(ctx context.Context, cfg *config.Config, appServices *Services)
types.LOCAL_DOCKER_ENVIRONMENT_ID,
"id",
envResolver,
- appServices.Environment,
createAuthValidator(appServices),
))
diff --git a/backend/internal/huma/handlers/environments.go b/backend/internal/huma/handlers/environments.go
index 463fd4084..59eb2f502 100644
--- a/backend/internal/huma/handlers/environments.go
+++ b/backend/internal/huma/handlers/environments.go
@@ -626,20 +626,32 @@ func (h *EnvironmentHandler) applyEdgeRuntimeState(env *environment.Environment)
env.Connected = &connected
env.ConnectedAt = nil
env.LastHeartbeat = nil
+ env.LastPollAt = nil
env.EdgeTransport = nil
+ if pollState, ok := edge.GetPollRuntimeRegistry().Get(env.ID, time.Now()); ok {
+ env.LastPollAt = pollState.LastPollAt
+ }
+
if runtimeState, ok := edge.GetTunnelRuntimeState(env.ID); ok {
connected = true
env.Connected = &connected
env.Status = string(models.EnvironmentStatusOnline)
env.ConnectedAt = runtimeState.ConnectedAt
env.LastHeartbeat = runtimeState.LastHeartbeat
- if runtimeState.Transport != "" {
+ if transport, ok := edge.GetActiveTunnelTransport(env.ID); ok {
+ env.EdgeTransport = &transport
+ } else if runtimeState.Transport != "" {
env.EdgeTransport = &runtimeState.Transport
}
return
}
+ if env.LastPollAt != nil {
+ env.Status = string(models.EnvironmentStatusStandby)
+ return
+ }
+
if env.Status != string(models.EnvironmentStatusPending) {
env.Status = string(models.EnvironmentStatusOffline)
}
@@ -1009,7 +1021,9 @@ func (h *EnvironmentHandler) GetEnvironmentVersion(ctx context.Context, input *G
// For edge environments, route through the tunnel
if env.IsEdge {
if !edge.HasActiveTunnel(input.ID) {
- return nil, huma.Error503ServiceUnavailable("Edge agent is not connected")
+ if _, ok := edge.RequestTunnelAndWait(reqCtx, input.ID, edge.DefaultTunnelDemandTTL, edge.DefaultTunnelAcquireTimeout()); !ok {
+ return nil, huma.Error503ServiceUnavailable("Edge agent is not connected")
+ }
}
statusCode, respBody, err := edge.DoRequest(reqCtx, input.ID, http.MethodGet, "/api/app-version", nil)
diff --git a/backend/internal/huma/handlers/environments_test.go b/backend/internal/huma/handlers/environments_test.go
index 5ac8d9b6f..dfb96d63c 100644
--- a/backend/internal/huma/handlers/environments_test.go
+++ b/backend/internal/huma/handlers/environments_test.go
@@ -2,6 +2,7 @@ package handlers
import (
"testing"
+ "time"
"github.com/getarcaneapp/arcane/backend/internal/models"
"github.com/getarcaneapp/arcane/backend/pkg/libarcane/edge"
@@ -100,4 +101,30 @@ func TestEnvironmentHandlerApplyEdgeRuntimeState(t *testing.T) {
assert.NotNil(t, env.ConnectedAt)
assert.NotNil(t, env.LastHeartbeat)
})
+
+ t.Run("marks recently polled edge environments standby without a live tunnel", func(t *testing.T) {
+ handler := &EnvironmentHandler{}
+ envID := "env-edge-polled"
+ edge.GetRegistry().Unregister(envID)
+ t.Cleanup(func() { edge.GetRegistry().Unregister(envID) })
+
+ edge.GetPollRuntimeRegistry().Update(envID, edge.DefaultTunnelPollInterval, time.Now())
+
+ env := envtypes.Environment{
+ ID: envID,
+ Status: string(models.EnvironmentStatusOffline),
+ IsEdge: true,
+ }
+
+ handler.applyEdgeRuntimeState(&env)
+
+ assert.Equal(t, string(models.EnvironmentStatusStandby), env.Status)
+ if assert.NotNil(t, env.Connected) {
+ assert.False(t, *env.Connected)
+ }
+ assert.Nil(t, env.EdgeTransport)
+ assert.Nil(t, env.ConnectedAt)
+ assert.Nil(t, env.LastHeartbeat)
+ assert.NotNil(t, env.LastPollAt)
+ })
}
diff --git a/backend/internal/middleware/environment_middleware.go b/backend/internal/middleware/environment_middleware.go
index e1c076ebf..621d098f4 100644
--- a/backend/internal/middleware/environment_middleware.go
+++ b/backend/internal/middleware/environment_middleware.go
@@ -11,7 +11,6 @@ import (
"strings"
"time"
- "github.com/getarcaneapp/arcane/backend/internal/services"
"github.com/getarcaneapp/arcane/backend/internal/utils/remenv"
wsutil "github.com/getarcaneapp/arcane/backend/internal/utils/ws"
"github.com/getarcaneapp/arcane/backend/pkg/libarcane/edge"
@@ -32,9 +31,6 @@ const (
// proxyTimeout is intentionally generous because some proxied operations
// (e.g., image pulls with progress streaming) can take multiple minutes.
proxyTimeout = 30 * time.Minute
-
- edgeTunnelWaitTimeout = 2 * time.Second
- edgeTunnelPollEvery = 100 * time.Millisecond
)
// managementEndpointSet contains paths handled locally and never proxied to remote environments.
@@ -65,7 +61,6 @@ type EnvironmentMiddleware struct {
paramName string
resolver EnvResolver
authValidator AuthValidator
- envService *services.EnvironmentService
httpClient *http.Client
registry *edge.TunnelRegistry
}
@@ -76,8 +71,8 @@ type EnvironmentMiddleware struct {
// - resolver: function to resolve environment ID to connection details
// - envService: environment service for additional lookups
// - authValidator: function to validate authentication before proxying (required for security)
-func NewEnvProxyMiddlewareWithParam(localID, paramName string, resolver EnvResolver, envService *services.EnvironmentService, authValidator AuthValidator) gin.HandlerFunc {
- return NewEnvProxyMiddlewareWithParamAndRegistry(localID, paramName, resolver, envService, authValidator, edge.GetRegistry())
+func NewEnvProxyMiddlewareWithParam(localID, paramName string, resolver EnvResolver, authValidator AuthValidator) gin.HandlerFunc {
+ return NewEnvProxyMiddlewareWithParamAndRegistry(localID, paramName, resolver, authValidator, edge.GetRegistry())
}
// NewEnvProxyMiddlewareWithParamAndRegistry creates middleware with an injected tunnel registry.
@@ -85,7 +80,6 @@ func NewEnvProxyMiddlewareWithParamAndRegistry(
localID,
paramName string,
resolver EnvResolver,
- envService *services.EnvironmentService,
authValidator AuthValidator,
registry *edge.TunnelRegistry,
) gin.HandlerFunc {
@@ -98,7 +92,6 @@ func NewEnvProxyMiddlewareWithParamAndRegistry(
paramName: paramName,
resolver: resolver,
authValidator: authValidator,
- envService: envService,
httpClient: &http.Client{Timeout: proxyTimeout},
registry: registry,
}
@@ -184,7 +177,8 @@ func (m *EnvironmentMiddleware) Handle(c *gin.Context) {
}
if isEdgeEnvironment {
- tunnel, ok := m.waitForActiveEdgeTunnelInternal(c.Request.Context(), envID, edgeTunnelWaitTimeout)
+ edge.TouchTunnelDemand(envID, edge.DefaultTunnelDemandTTL)
+ tunnel, ok := m.waitForActiveEdgeTunnelInternal(c.Request.Context(), envID, edge.DefaultTunnelAcquireTimeout())
if ok {
slog.InfoContext(c.Request.Context(), "Recovered edge tunnel during request", "environment_id", envID)
// Inject agent token headers for the recovered tunnel path.
@@ -315,14 +309,10 @@ func (m *EnvironmentMiddleware) waitForActiveEdgeTunnelInternal(ctx context.Cont
return tunnel, true
}
- waitCtx := ctx
- cancel := func() {}
- if _, hasDeadline := ctx.Deadline(); !hasDeadline {
- waitCtx, cancel = context.WithTimeout(ctx, timeout)
- }
+ waitCtx, cancel := context.WithTimeout(ctx, timeout)
defer cancel()
- ticker := time.NewTicker(edgeTunnelPollEvery)
+ ticker := time.NewTicker(edge.DefaultTunnelAcquirePollEvery)
defer ticker.Stop()
for {
diff --git a/backend/internal/models/environment.go b/backend/internal/models/environment.go
index af9829442..0a4a77ec7 100644
--- a/backend/internal/models/environment.go
+++ b/backend/internal/models/environment.go
@@ -21,6 +21,7 @@ type EnvironmentStatus string
const (
EnvironmentStatusOnline EnvironmentStatus = "online"
+ EnvironmentStatusStandby EnvironmentStatus = "standby"
EnvironmentStatusOffline EnvironmentStatus = "offline"
EnvironmentStatusError EnvironmentStatus = "error"
EnvironmentStatusPending EnvironmentStatus = "pending"
diff --git a/backend/internal/services/api_key_service.go b/backend/internal/services/api_key_service.go
index 252bdeced..a18b9766b 100644
--- a/backend/internal/services/api_key_service.go
+++ b/backend/internal/services/api_key_service.go
@@ -23,9 +23,10 @@ var (
)
const (
- apiKeyPrefix = "arc_"
- apiKeyLength = 32
- apiKeyPrefixLen = 8
+ apiKeyPrefix = "arc_"
+ apiKeyLength = 32
+ apiKeyPrefixLen = 8
+ apiKeyLastUsedWriteWindow = 5 * time.Minute
)
type ApiKeyService struct {
@@ -62,7 +63,11 @@ func (s *ApiKeyService) markApiKeyUsedAsync(ctx context.Context, keyID string) {
go func(keyID string) {
bgCtx := context.WithoutCancel(ctx)
now := time.Now()
- s.db.WithContext(bgCtx).Model(&models.ApiKey{}).Where("id = ?", keyID).Update("last_used_at", now)
+ cutoff := now.Add(-apiKeyLastUsedWriteWindow)
+ s.db.WithContext(bgCtx).
+ Model(&models.ApiKey{}).
+ Where("id = ? AND (last_used_at IS NULL OR last_used_at < ?)", keyID, cutoff).
+ Update("last_used_at", now)
}(keyID)
}
diff --git a/backend/internal/services/api_key_service_test.go b/backend/internal/services/api_key_service_test.go
index 00373d99c..a1bf6721f 100644
--- a/backend/internal/services/api_key_service_test.go
+++ b/backend/internal/services/api_key_service_test.go
@@ -8,6 +8,7 @@ import (
"time"
glsqlite "github.com/glebarez/sqlite"
+ "github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"gorm.io/gorm"
@@ -75,6 +76,21 @@ func requireAPIKeyLastUsedEventually(t *testing.T, db *database.DB, keyID string
return apiKey
}
+func assertAPIKeyLastUsedStable(t *testing.T, db *database.DB, keyID string, expected *time.Time, duration time.Duration) {
+ t.Helper()
+
+ assert.Never(t, func() bool {
+ apiKey := fetchAPIKey(t, db, keyID)
+ if expected == nil {
+ return apiKey.LastUsedAt != nil
+ }
+ if apiKey.LastUsedAt == nil {
+ return true
+ }
+ return apiKey.LastUsedAt.UTC().UnixNano() != expected.UTC().UnixNano()
+ }, duration, 10*time.Millisecond)
+}
+
func invalidateAPIKey(rawKey string) string {
if rawKey == "" {
return rawKey
@@ -133,7 +149,7 @@ func TestValidateAPIKeyInvalidDoesNotUpdateLastUsedAt(t *testing.T) {
_, err = service.ValidateApiKey(ctx, invalidateAPIKey(created.Key))
require.ErrorIs(t, err, ErrApiKeyInvalid)
- time.Sleep(100 * time.Millisecond)
+ assertAPIKeyLastUsedStable(t, db, created.ApiKey.ID, nil, 500*time.Millisecond)
apiKey := fetchAPIKey(t, db, created.ApiKey.ID)
require.Nil(t, apiKey.LastUsedAt)
}
@@ -153,7 +169,33 @@ func TestGetEnvironmentByAPIKeyExpiredDoesNotUpdateLastUsedAt(t *testing.T) {
_, err = service.GetEnvironmentByApiKey(ctx, created.Key)
require.ErrorIs(t, err, ErrApiKeyExpired)
- time.Sleep(100 * time.Millisecond)
+ assertAPIKeyLastUsedStable(t, db, created.ApiKey.ID, nil, 500*time.Millisecond)
apiKey := fetchAPIKey(t, db, created.ApiKey.ID)
require.Nil(t, apiKey.LastUsedAt)
}
+
+func TestGetEnvironmentByAPIKeyRecentLastUsedAtDoesNotRewriteImmediately(t *testing.T) {
+ ctx := context.Background()
+ service, db, userService := setupAPIKeyService(t)
+ user := createTestAPIKeyUser(t, ctx, userService, "user-environment-recent")
+
+ created, err := service.CreateEnvironmentApiKey(ctx, "env-456", user.ID)
+ require.NoError(t, err)
+
+ recent := time.Now().Add(-time.Minute)
+ err = db.WithContext(ctx).Model(&models.ApiKey{}).Where("id = ?", created.ApiKey.ID).Update("last_used_at", recent).Error
+ require.NoError(t, err)
+
+ before := fetchAPIKey(t, db, created.ApiKey.ID)
+ require.NotNil(t, before.LastUsedAt)
+
+ environmentID, err := service.GetEnvironmentByApiKey(ctx, created.Key)
+ require.NoError(t, err)
+ require.NotNil(t, environmentID)
+ require.Equal(t, "env-456", *environmentID)
+
+ assertAPIKeyLastUsedStable(t, db, created.ApiKey.ID, before.LastUsedAt, 2*time.Second)
+ after := fetchAPIKey(t, db, created.ApiKey.ID)
+ require.NotNil(t, after.LastUsedAt)
+ require.Equal(t, before.LastUsedAt.UTC().Unix(), after.LastUsedAt.UTC().Unix())
+}
diff --git a/backend/internal/services/environment_service.go b/backend/internal/services/environment_service.go
index 1a15c1508..b4dfff4d5 100644
--- a/backend/internal/services/environment_service.go
+++ b/backend/internal/services/environment_service.go
@@ -9,6 +9,7 @@ import (
"log/slog"
"net/http"
"strings"
+ "sync"
"time"
"github.com/getarcaneapp/arcane/backend/internal/database"
@@ -32,8 +33,18 @@ type EnvironmentService struct {
dockerService *DockerClientService
eventService *EventService
settingsService *SettingsService
+ tokenCacheMu sync.RWMutex
+ tokenCache map[string]edgeTokenCacheEntry
+ tokenByEnvID map[string]string
}
+type edgeTokenCacheEntry struct {
+ EnvironmentID string
+ ExpiresAt time.Time
+}
+
+const edgeTokenCacheTTL = time.Minute
+
func NewEnvironmentService(db *database.DB, httpClient *http.Client, dockerService *DockerClientService, eventService *EventService, settingsService *SettingsService) *EnvironmentService {
if httpClient == nil {
httpClient = http.DefaultClient
@@ -44,6 +55,120 @@ func NewEnvironmentService(db *database.DB, httpClient *http.Client, dockerServi
dockerService: dockerService,
eventService: eventService,
settingsService: settingsService,
+ tokenCache: make(map[string]edgeTokenCacheEntry),
+ tokenByEnvID: make(map[string]string),
+ }
+}
+
+func (s *EnvironmentService) ResolveEdgeEnvironmentByToken(ctx context.Context, token string) (string, error) {
+ token = strings.TrimSpace(token)
+ if token == "" {
+ return "", errors.New("agent token required")
+ }
+
+ if envID, ok := s.getCachedEnvironmentIDForTokenInternal(token, time.Now()); ok {
+ return envID, nil
+ }
+
+ var env models.Environment
+ if err := s.db.WithContext(ctx).
+ Select("id", "access_token").
+ Where("is_edge = ?", true).
+ Where("access_token = ?", token).
+ First(&env).Error; err != nil {
+ if errors.Is(err, gorm.ErrRecordNotFound) {
+ return "", errors.New("invalid agent token")
+ }
+ return "", fmt.Errorf("failed to resolve edge environment by token: %w", err)
+ }
+
+ s.cacheEnvironmentTokenInternal(env.ID, token, time.Now())
+ return env.ID, nil
+}
+
+func (s *EnvironmentService) getCachedEnvironmentIDForTokenInternal(token string, now time.Time) (string, bool) {
+ if s == nil || token == "" {
+ return "", false
+ }
+ if now.IsZero() {
+ now = time.Now()
+ }
+
+ s.tokenCacheMu.RLock()
+ entry, ok := s.tokenCache[token]
+ s.tokenCacheMu.RUnlock()
+ if !ok {
+ return "", false
+ }
+ if entry.ExpiresAt.After(now) {
+ return entry.EnvironmentID, true
+ }
+
+ s.tokenCacheMu.Lock()
+ defer s.tokenCacheMu.Unlock()
+
+ entry, ok = s.tokenCache[token]
+ if !ok {
+ return "", false
+ }
+ if !entry.ExpiresAt.After(now) {
+ delete(s.tokenCache, token)
+ if currentToken, ok := s.tokenByEnvID[entry.EnvironmentID]; ok && currentToken == token {
+ delete(s.tokenByEnvID, entry.EnvironmentID)
+ }
+ return "", false
+ }
+
+ return entry.EnvironmentID, true
+}
+
+func (s *EnvironmentService) cacheEnvironmentTokenInternal(envID string, token string, now time.Time) {
+ if s == nil || envID == "" || token == "" {
+ return
+ }
+ if now.IsZero() {
+ now = time.Now()
+ }
+
+ s.tokenCacheMu.Lock()
+ defer s.tokenCacheMu.Unlock()
+
+ if previousToken, ok := s.tokenByEnvID[envID]; ok && previousToken != token {
+ delete(s.tokenCache, previousToken)
+ }
+
+ s.tokenByEnvID[envID] = token
+ s.tokenCache[token] = edgeTokenCacheEntry{
+ EnvironmentID: envID,
+ ExpiresAt: now.Add(edgeTokenCacheTTL),
+ }
+}
+
+func (s *EnvironmentService) invalidateEnvironmentTokenInternal(envID string) {
+ if s == nil || envID == "" {
+ return
+ }
+
+ s.tokenCacheMu.Lock()
+ defer s.tokenCacheMu.Unlock()
+
+ if token, ok := s.tokenByEnvID[envID]; ok {
+ delete(s.tokenByEnvID, envID)
+ delete(s.tokenCache, token)
+ }
+}
+
+func (s *EnvironmentService) syncEnvironmentTokenCacheInternal(envID string, token string) {
+ if s == nil || envID == "" {
+ return
+ }
+
+ s.invalidateEnvironmentTokenInternal(envID)
+
+ resolvedToken := strings.TrimSpace(token)
+
+ if resolvedToken != "" {
+ s.cacheEnvironmentTokenInternal(envID, resolvedToken, time.Now())
}
}
@@ -215,6 +340,11 @@ func (s *EnvironmentService) UpdateEnvironment(ctx context.Context, id string, u
return nil, err
}
+ if rawAccessToken, ok := updates["access_token"]; ok {
+ accessToken, _ := rawAccessToken.(string)
+ s.syncEnvironmentTokenCacheInternal(id, accessToken)
+ }
+
// Create event in background (skip for local environment)
if id != "0" {
go s.createEnvironmentEvent(context.WithoutCancel(ctx), id, updated.Name, models.EventTypeEnvironmentUpdate, "Environment Updated", fmt.Sprintf("Environment '%s' was updated", updated.Name), models.EventSeverityInfo, userID, username)
@@ -234,6 +364,8 @@ func (s *EnvironmentService) DeleteEnvironment(ctx context.Context, id string, u
return fmt.Errorf("failed to delete environment: %w", err)
}
+ s.invalidateEnvironmentTokenInternal(id)
+
// Create event in background
go s.createEnvironmentEvent(context.WithoutCancel(ctx), id, env.Name, models.EventTypeEnvironmentDelete, "Environment Deleted", fmt.Sprintf("Environment '%s' was deleted", env.Name), models.EventSeverityWarning, userID, username)
@@ -295,11 +427,11 @@ func (s *EnvironmentService) TestConnection(ctx context.Context, id string, cust
// testEdgeConnection tests connection to an edge agent via its tunnel
func (s *EnvironmentService) testEdgeConnection(ctx context.Context, id string) (string, error) {
- // Import edge package - this is a circular import issue, but we'll work around it
- // by checking if there's an active tunnel using the registry
if !edge.HasActiveTunnel(id) {
- _ = s.updateEnvironmentStatusInternal(ctx, id, string(models.EnvironmentStatusOffline))
- return "offline", fmt.Errorf("edge agent is not connected")
+ if _, ok := edge.RequestTunnelAndWait(ctx, id, edge.DefaultTunnelDemandTTL, edge.DefaultTunnelAcquireTimeout()); !ok {
+ _ = s.updateEnvironmentStatusInternal(ctx, id, string(models.EnvironmentStatusOffline))
+ return "offline", fmt.Errorf("edge agent is not connected")
+ }
}
reqCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
@@ -432,6 +564,10 @@ func (s *EnvironmentService) ReconcileEdgeStatusesOnStartup(ctx context.Context)
}
func (s *EnvironmentService) createEnvironmentEvent(ctx context.Context, envID, envName string, eventType models.EventType, title, description string, severity models.EventSeverity, userID, username *string) {
+ if s == nil || s.eventService == nil {
+ return
+ }
+
_, _ = s.eventService.CreateEvent(ctx, CreateEventRequest{
Type: eventType,
Severity: severity,
@@ -459,6 +595,8 @@ func (s *EnvironmentService) RegenerateEnvironmentApiKey(ctx context.Context, en
return fmt.Errorf("failed to update environment with new API key: %w", err)
}
+ s.syncEnvironmentTokenCacheInternal(envID, encryptedKey)
+
// Create event log in background
go s.createEnvironmentEvent(context.WithoutCancel(ctx), envID, envName, models.EventTypeEnvironmentApiKeyRegenerated, "API Key Regenerated", "Environment API key was regenerated and status set to pending", models.EventSeverityInfo, new(userID), new(username))
@@ -514,6 +652,7 @@ func (s *EnvironmentService) PairAndPersistAgentToken(ctx context.Context, envir
Update("access_token", token).Error; err != nil {
return "", fmt.Errorf("failed to persist agent token: %w", err)
}
+ s.syncEnvironmentTokenCacheInternal(environmentID, token)
return token, nil
}
@@ -564,6 +703,7 @@ func (s *EnvironmentService) GenerateDeploymentSnippets(ctx context.Context, env
--name arcane-agent \
--restart unless-stopped \
-e AGENT_MODE=true \
+ -e EDGE_TRANSPORT=poll \
-e AGENT_TOKEN=%s \
-e MANAGER_API_URL=%s \
-p 3553:3553 \
@@ -578,6 +718,7 @@ func (s *EnvironmentService) GenerateDeploymentSnippets(ctx context.Context, env
restart: unless-stopped
environment:
- AGENT_MODE=true
+ - EDGE_TRANSPORT=poll
- AGENT_TOKEN=%s
- MANAGER_API_URL=%s
ports:
@@ -604,6 +745,7 @@ func (s *EnvironmentService) GenerateEdgeDeploymentSnippets(ctx context.Context,
--name arcane-edge-agent \
--restart unless-stopped \
-e EDGE_AGENT=true \
+ -e EDGE_TRANSPORT=poll \
-e AGENT_TOKEN=%s \
-e MANAGER_API_URL=%s \
-v /var/run/docker.sock:/var/run/docker.sock \
@@ -618,6 +760,7 @@ services:
restart: unless-stopped
environment:
- EDGE_AGENT=true
+ - EDGE_TRANSPORT=poll
- AGENT_TOKEN=%s
- MANAGER_API_URL=%s
volumes:
diff --git a/backend/internal/services/environment_service_test.go b/backend/internal/services/environment_service_test.go
index 58c4affd8..9947b9347 100644
--- a/backend/internal/services/environment_service_test.go
+++ b/backend/internal/services/environment_service_test.go
@@ -5,6 +5,7 @@ import (
"encoding/json"
"net/http"
"net/http/httptest"
+ "strings"
"sync/atomic"
"testing"
"time"
@@ -260,3 +261,106 @@ func TestEnvironmentService_UpdateEnvironmentConnectionState(t *testing.T) {
require.NotNil(t, env.LastSeen)
require.Equal(t, *lastSeen, *env.LastSeen)
}
+
+func TestEnvironmentService_ResolveEdgeEnvironmentByToken_CachesAndInvalidatesOnUpdate(t *testing.T) {
+ ctx := context.Background()
+ db := setupEnvironmentServiceTestDB(t)
+ svc := NewEnvironmentService(db, nil, nil, nil, nil)
+
+ oldToken := "edge-token-old"
+ newToken := "edge-token-new"
+ createTestEnvironmentWithState(t, db, "edge-auth", "edge://auth", string(models.EnvironmentStatusPending), true, &oldToken)
+
+ envID, err := svc.ResolveEdgeEnvironmentByToken(ctx, oldToken)
+ require.NoError(t, err)
+ require.Equal(t, "edge-auth", envID)
+
+ _, err = svc.UpdateEnvironment(ctx, "edge-auth", map[string]any{"access_token": newToken}, nil, nil)
+ require.NoError(t, err)
+
+ _, err = svc.ResolveEdgeEnvironmentByToken(ctx, oldToken)
+ require.Error(t, err)
+ require.Contains(t, err.Error(), "invalid agent token")
+
+ envID, err = svc.ResolveEdgeEnvironmentByToken(ctx, newToken)
+ require.NoError(t, err)
+ require.Equal(t, "edge-auth", envID)
+
+ require.NoError(t, svc.DeleteEnvironment(ctx, "edge-auth", nil, nil))
+ _, err = svc.ResolveEdgeEnvironmentByToken(ctx, newToken)
+ require.Error(t, err)
+ require.Contains(t, err.Error(), "invalid agent token")
+}
+
+func TestEnvironmentService_UpdateEnvironment_ClearingAccessTokenInvalidatesCache(t *testing.T) {
+ ctx := context.Background()
+ db := setupEnvironmentServiceTestDB(t)
+ svc := NewEnvironmentService(db, nil, nil, nil, nil)
+
+ oldToken := "edge-token-clear"
+ createTestEnvironmentWithState(t, db, "edge-auth-clear", "edge://auth-clear", string(models.EnvironmentStatusPending), true, &oldToken)
+
+ envID, err := svc.ResolveEdgeEnvironmentByToken(ctx, oldToken)
+ require.NoError(t, err)
+ require.Equal(t, "edge-auth-clear", envID)
+
+ _, err = svc.UpdateEnvironment(ctx, "edge-auth-clear", map[string]any{"access_token": nil}, nil, nil)
+ require.NoError(t, err)
+
+ cachedEnvID, ok := svc.getCachedEnvironmentIDForTokenInternal(oldToken, time.Now())
+ require.False(t, ok)
+ require.Empty(t, cachedEnvID)
+
+ svc.tokenCacheMu.RLock()
+ _, tokenStillCached := svc.tokenCache[oldToken]
+ _, reverseIndexStillCached := svc.tokenByEnvID["edge-auth-clear"]
+ svc.tokenCacheMu.RUnlock()
+
+ require.False(t, tokenStillCached)
+ require.False(t, reverseIndexStillCached)
+
+ _, err = svc.ResolveEdgeEnvironmentByToken(ctx, oldToken)
+ require.Error(t, err)
+ require.Contains(t, err.Error(), "invalid agent token")
+}
+
+func TestEnvironmentService_getCachedEnvironmentIDForTokenInternal_ExpiresAndCleansReverseIndex(t *testing.T) {
+ svc := NewEnvironmentService(nil, nil, nil, nil, nil)
+ now := time.Now()
+
+ svc.cacheEnvironmentTokenInternal("env-expired", "expired-token", now.Add(-2*edgeTokenCacheTTL))
+
+ envID, ok := svc.getCachedEnvironmentIDForTokenInternal("expired-token", now)
+ require.False(t, ok)
+ require.Empty(t, envID)
+
+ svc.tokenCacheMu.RLock()
+ _, tokenStillCached := svc.tokenCache["expired-token"]
+ _, reverseIndexStillCached := svc.tokenByEnvID["env-expired"]
+ svc.tokenCacheMu.RUnlock()
+
+ require.False(t, tokenStillCached)
+ require.False(t, reverseIndexStillCached)
+}
+
+func TestEnvironmentService_GenerateDeploymentSnippets_ExplicitlyUsePollTransport(t *testing.T) {
+ svc := NewEnvironmentService(nil, nil, nil, nil, nil)
+
+ standard, err := svc.GenerateDeploymentSnippets(context.Background(), "env-1", "https://manager.example.com", "token-123")
+ require.NoError(t, err)
+ require.NotNil(t, standard)
+ require.NotContains(t, standard.DockerRun, "EDGE_TRANSPORT=websocket")
+ require.NotContains(t, standard.DockerCompose, "EDGE_TRANSPORT=websocket")
+ require.Contains(t, standard.DockerRun, "EDGE_TRANSPORT=poll")
+ require.Contains(t, standard.DockerCompose, "EDGE_TRANSPORT=poll")
+ require.True(t, strings.Contains(standard.DockerRun, "AGENT_TOKEN=token-123"))
+
+ edgeSnippets, err := svc.GenerateEdgeDeploymentSnippets(context.Background(), "env-2", "https://manager.example.com", "token-456")
+ require.NoError(t, err)
+ require.NotNil(t, edgeSnippets)
+ require.NotContains(t, edgeSnippets.DockerRun, "EDGE_TRANSPORT=websocket")
+ require.NotContains(t, edgeSnippets.DockerCompose, "EDGE_TRANSPORT=websocket")
+ require.Contains(t, edgeSnippets.DockerRun, "EDGE_TRANSPORT=poll")
+ require.Contains(t, edgeSnippets.DockerCompose, "EDGE_TRANSPORT=poll")
+ require.True(t, strings.Contains(edgeSnippets.DockerRun, "AGENT_TOKEN=token-456"))
+}
diff --git a/backend/internal/services/project_service.go b/backend/internal/services/project_service.go
index fe2776d19..4c7a7a4be 100644
--- a/backend/internal/services/project_service.go
+++ b/backend/internal/services/project_service.go
@@ -1927,18 +1927,14 @@ func (s *ProjectService) validateComposeContentForUpdate(ctx context.Context, pr
if fileEnv, envErr := projects.ParseProjectEnvContent(*envContent, fullEnvMap); envErr != nil {
return fmt.Errorf("parse provided env content: %w", envErr)
} else {
- for k, v := range fileEnv {
- fullEnvMap[k] = v
- }
+ maps.Copy(fullEnvMap, fileEnv)
}
} else {
projectEnvPath := filepath.Join(projectPath, ".env")
if fileEnv, envErr := projects.ParseProjectEnvFile(projectEnvPath, fullEnvMap); envErr != nil {
return fmt.Errorf("parse project env file: %w", envErr)
} else {
- for k, v := range fileEnv {
- fullEnvMap[k] = v
- }
+ maps.Copy(fullEnvMap, fileEnv)
}
}
diff --git a/backend/pkg/libarcane/edge/client.go b/backend/pkg/libarcane/edge/client.go
index a1aa38939..939406644 100644
--- a/backend/pkg/libarcane/edge/client.go
+++ b/backend/pkg/libarcane/edge/client.go
@@ -25,6 +25,13 @@ const (
DefaultWriteTimeout = 10 * time.Second
// DefaultRequestTimeout is the timeout for executing local requests
DefaultRequestTimeout = 5 * time.Minute
+ // DefaultGRPCRegistrationTimeout bounds how long the agent waits for the
+ // manager to acknowledge gRPC tunnel registration before treating it as a
+ // failed transport attempt.
+ DefaultGRPCRegistrationTimeout = 10 * time.Second
+ // DefaultWebSocketPreferenceTTL keeps websocket as the preferred transport
+ // for a short period after a successful auto-mode fallback.
+ DefaultWebSocketPreferenceTTL = 2 * time.Minute
)
// activeWSStream tracks an active WebSocket stream on the agent side.
@@ -43,17 +50,22 @@ type wsPayload struct {
// TunnelClient represents the agent-side tunnel client
type TunnelClient struct {
- cfg *config.Config
- handler http.Handler
- reconnectInterval time.Duration
- heartbeatInterval time.Duration
- managerURL string
- managerGRPCAddr string
- localPort string // Port the agent is running on locally
- conn TunnelConnection
- stopCh chan struct{}
- requestTimeout time.Duration
- activeStreams sync.Map // map[string]*activeWSStream
+ cfg *config.Config
+ handler http.Handler
+ reconnectInterval time.Duration
+ heartbeatInterval time.Duration
+ grpcRegistrationTimeout time.Duration
+ websocketPreferenceTTL time.Duration
+ managerURL string
+ managerGRPCAddr string
+ localPort string // Port the agent is running on locally
+ httpClient *http.Client
+ conn TunnelConnection
+ stopCh chan struct{}
+ requestTimeout time.Duration
+ activeStreams sync.Map // map[string]*activeWSStream
+ transportPreferenceMu sync.RWMutex
+ preferWebSocketUntil time.Time
}
// NewTunnelClient creates a new tunnel client
@@ -77,15 +89,18 @@ func NewTunnelClient(cfg *config.Config, handler http.Handler) *TunnelClient {
}
return &TunnelClient{
- cfg: cfg,
- handler: handler,
- reconnectInterval: reconnectInterval,
- heartbeatInterval: DefaultHeartbeatInterval,
- managerURL: managerURL,
- managerGRPCAddr: managerGRPCAddr,
- localPort: localPort,
- stopCh: make(chan struct{}),
- requestTimeout: DefaultRequestTimeout,
+ cfg: cfg,
+ handler: handler,
+ reconnectInterval: reconnectInterval,
+ heartbeatInterval: DefaultHeartbeatInterval,
+ grpcRegistrationTimeout: DefaultGRPCRegistrationTimeout,
+ websocketPreferenceTTL: DefaultWebSocketPreferenceTTL,
+ managerURL: managerURL,
+ managerGRPCAddr: managerGRPCAddr,
+ localPort: localPort,
+ httpClient: &http.Client{},
+ stopCh: make(chan struct{}),
+ requestTimeout: DefaultRequestTimeout,
}
}
@@ -94,8 +109,8 @@ func (c *TunnelClient) StartWithErrorChan(ctx context.Context, errCh chan error)
transport := NormalizeEdgeTransport(c.cfg.EdgeTransport)
slog.InfoContext(ctx, "Starting edge tunnel client",
"transport_mode", transport,
- "attempt_grpc", UseGRPCEdgeTransport(c.cfg),
- "attempt_websocket", UseWebSocketEdgeTransport(c.cfg),
+ "attempt_grpc", c.shouldAttemptGRPCTunnelInternal(),
+ "attempt_websocket", c.shouldAttemptWebSocketTunnelInternal(),
"manager_url", c.managerURL,
)
if errCh != nil {
@@ -137,8 +152,26 @@ func (c *TunnelClient) StartWithErrorChan(ctx context.Context, errCh chan error)
// connectAndServe establishes a connection and handles messages.
func (c *TunnelClient) connectAndServe(ctx context.Context) error {
- if UseGRPCEdgeTransport(c.cfg) {
+ if UsePollEdgeTransport(c.cfg) {
+ return c.connectAndServePoll(ctx)
+ }
+ return c.connectAndServeManagedTunnelInternal(ctx)
+}
+
+func (c *TunnelClient) connectAndServeManagedTunnelInternal(ctx context.Context) error {
+ if c.shouldAttemptGRPCTunnelInternal() {
+ if preferredUntil, ok := c.preferredWebSocketUntilInternal(time.Now()); ok {
+ slog.InfoContext(ctx, "Temporarily preferring websocket edge tunnel transport after recent websocket success",
+ "preferred_until", preferredUntil,
+ "manager_ws_url", c.managerWebSocketURLInternal(),
+ )
+ return c.connectAndServeWebSocket(ctx)
+ }
+
if err := c.connectAndServeGRPC(ctx); err != nil {
+ if ctx.Err() != nil {
+ return ctx.Err()
+ }
if c.shouldFallbackToWebSocketInternal() {
managerWSURL := c.managerWebSocketURLInternal()
slog.WarnContext(ctx, "gRPC edge tunnel connection failed, falling back to websocket transport",
@@ -155,16 +188,39 @@ func (c *TunnelClient) connectAndServe(ctx context.Context) error {
}
return nil
}
- return c.connectAndServeWebSocket(ctx)
+ if c.shouldAttemptWebSocketTunnelInternal() {
+ return c.connectAndServeWebSocket(ctx)
+ }
+ return fmt.Errorf("no edge tunnel transport is available")
}
func (c *TunnelClient) shouldFallbackToWebSocketInternal() bool {
- if !UseWebSocketEdgeTransport(c.cfg) {
+ if !c.shouldAttemptWebSocketTunnelInternal() {
return false
}
return c.managerWebSocketURLInternal() != ""
}
+func (c *TunnelClient) shouldAttemptGRPCTunnelInternal() bool {
+ if c == nil {
+ return false
+ }
+ if UsePollEdgeTransport(c.cfg) {
+ return strings.TrimSpace(c.managerGRPCAddr) != ""
+ }
+ return UseGRPCEdgeTransport(c.cfg)
+}
+
+func (c *TunnelClient) shouldAttemptWebSocketTunnelInternal() bool {
+ if c == nil {
+ return false
+ }
+ if UsePollEdgeTransport(c.cfg) {
+ return c.managerWebSocketURLInternal() != ""
+ }
+ return UseWebSocketEdgeTransport(c.cfg)
+}
+
func (c *TunnelClient) managerWebSocketURLInternal() string {
if c == nil {
return ""
@@ -182,6 +238,53 @@ func (c *TunnelClient) managerWebSocketURLInternal() string {
return remenv.HTTPToWebSocketURL(managerBaseURL) + "/api/tunnel/connect"
}
+func (c *TunnelClient) grpcRegistrationTimeoutInternal() time.Duration {
+ if c == nil || c.grpcRegistrationTimeout <= 0 {
+ return DefaultGRPCRegistrationTimeout
+ }
+ return c.grpcRegistrationTimeout
+}
+
+func (c *TunnelClient) websocketPreferenceTTLInternal() time.Duration {
+ if c == nil || c.websocketPreferenceTTL <= 0 {
+ return DefaultWebSocketPreferenceTTL
+ }
+ return c.websocketPreferenceTTL
+}
+
+func (c *TunnelClient) preferredWebSocketUntilInternal(now time.Time) (time.Time, bool) {
+ if c == nil || !c.shouldAttemptGRPCTunnelInternal() || !c.shouldAttemptWebSocketTunnelInternal() {
+ return time.Time{}, false
+ }
+
+ c.transportPreferenceMu.RLock()
+ defer c.transportPreferenceMu.RUnlock()
+
+ if c.preferWebSocketUntil.IsZero() || !now.Before(c.preferWebSocketUntil) {
+ return time.Time{}, false
+ }
+
+ return c.preferWebSocketUntil, true
+}
+
+func (c *TunnelClient) markTransportConnectedInternal(transport string) {
+ if c == nil {
+ return
+ }
+
+ c.transportPreferenceMu.Lock()
+ defer c.transportPreferenceMu.Unlock()
+
+ switch transport {
+ case EdgeTransportGRPC:
+ c.preferWebSocketUntil = time.Time{}
+ case EdgeTransportWebSocket:
+ if c.shouldAttemptGRPCTunnelInternal() && c.shouldAttemptWebSocketTunnelInternal() {
+ c.preferWebSocketUntil = time.Now().Add(c.websocketPreferenceTTLInternal())
+ }
+ }
+}
+
// heartbeatLoop sends periodic heartbeats
func (c *TunnelClient) heartbeatLoop(ctx context.Context) {
ticker := time.NewTicker(c.heartbeatInterval)
@@ -807,6 +910,10 @@ func StartTunnelClientWithErrors(ctx context.Context, cfg *config.Config, handle
return nil, fmt.Errorf("MANAGER_API_URL is required for websocket transport")
}
+ if UsePollEdgeTransport(cfg) && strings.TrimSpace(cfg.GetManagerBaseURL()) == "" {
+ return nil, fmt.Errorf("MANAGER_API_URL is required for poll transport")
+ }
+
if cfg.AgentToken == "" {
return nil, fmt.Errorf("AGENT_TOKEN is required")
}
diff --git a/backend/pkg/libarcane/edge/client_grpc_test.go b/backend/pkg/libarcane/edge/client_grpc_test.go
index 20b9dac1c..03fe47f46 100644
--- a/backend/pkg/libarcane/edge/client_grpc_test.go
+++ b/backend/pkg/libarcane/edge/client_grpc_test.go
@@ -3,11 +3,14 @@ package edge
import (
"context"
"errors"
+ "io"
"net"
"net/http"
"net/http/httptest"
"net/url"
"strings"
+ "sync"
+ "sync/atomic"
"testing"
"time"
@@ -23,6 +26,59 @@ import (
"google.golang.org/grpc"
)
+type stallingTunnelService struct {
+ tunnelpb.UnimplementedTunnelServiceServer
+ connectCount atomic.Int32
+}
+
+type blockingRegistrationConn struct {
+ closeCount atomic.Int32
+ closedCh chan struct{}
+}
+
+func newBlockingRegistrationConn() *blockingRegistrationConn {
+ return &blockingRegistrationConn{closedCh: make(chan struct{})}
+}
+
+func (c *blockingRegistrationConn) Send(*TunnelMessage) error { return nil }
+
+func (c *blockingRegistrationConn) Receive() (*TunnelMessage, error) {
+ <-c.closedCh
+ return nil, io.EOF
+}
+
+func (c *blockingRegistrationConn) IsExpectedReceiveError(error) bool { return false }
+
+func (c *blockingRegistrationConn) Close() error {
+ if c.closeCount.Add(1) == 1 {
+ close(c.closedCh)
+ }
+ return nil
+}
+
+func (c *blockingRegistrationConn) IsClosed() bool {
+ select {
+ case <-c.closedCh:
+ return true
+ default:
+ return false
+ }
+}
+
+func (c *blockingRegistrationConn) SendRequest(context.Context, *TunnelMessage, *sync.Map) (*TunnelMessage, error) {
+ return nil, errors.New("not implemented")
+}
+
+func (s *stallingTunnelService) Connect(stream grpc.BidiStreamingServer[tunnelpb.AgentMessage, tunnelpb.ManagerMessage]) error {
+ s.connectCount.Add(1)
+ if _, err := stream.Recv(); err != nil {
+ return err
+ }
+
+ <-stream.Context().Done()
+ return stream.Context().Err()
+}
+
func TestTunnelClient_GRPC_EndToEnd(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
@@ -193,6 +249,45 @@ func TestTunnelClient_connectAndServeGRPC_RegistrationRejected(t *testing.T) {
assert.Contains(t, err.Error(), "invalid agent token")
}
+func TestTunnelClient_connectAndServeGRPC_TimesOutWithoutRegisterResponse(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer cancel()
+
+ service := &stallingTunnelService{}
+ managerURL, stopManager := startTestTunnelServiceOnAPIPathInternal(t, ctx, service)
+ defer stopManager()
+
+ client := NewTunnelClient(&config.Config{
+ EdgeTransport: EdgeTransportGRPC,
+ ManagerApiUrl: managerURL,
+ AgentToken: "valid-token",
+ }, http.NotFoundHandler())
+ client.grpcRegistrationTimeout = 100 * time.Millisecond
+
+ err := client.connectAndServeGRPC(ctx)
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "timed out waiting for gRPC tunnel registration response")
+ assert.EqualValues(t, 1, service.connectCount.Load())
+ assert.True(t, client.conn == nil || client.conn.IsClosed())
+}
+
+func TestTunnelClient_awaitGRPCRegistrationInternal_ClosesConnOnContextDone(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+ defer cancel()
+
+ conn := newBlockingRegistrationConn()
+ client := &TunnelClient{
+ conn: conn,
+ grpcRegistrationTimeout: time.Second,
+ }
+
+ msg, err := client.awaitGRPCRegistrationInternal(ctx)
+ require.Nil(t, msg)
+ require.ErrorIs(t, err, context.DeadlineExceeded)
+ assert.True(t, conn.IsClosed())
+ assert.EqualValues(t, 1, conn.closeCount.Load())
+}
+
func TestTunnelClient_GRPC_WebSocketProxyEndToEnd(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
@@ -373,7 +468,7 @@ func TestTunnelClient_connectAndServe_WebSocketConfigFallsBackToWebSocket(t *tes
}
}
-func TestTunnelClient_connectAndServe_AutoTransportFallsBackToWebSocket(t *testing.T) {
+func TestTunnelClient_connectAndServe_AutoTransportFallsBackToWebSocketWhenGRPCUnavailable(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
@@ -413,11 +508,11 @@ func TestTunnelClient_connectAndServe_AutoTransportFallsBackToWebSocket(t *testi
select {
case <-wsConnectedCh:
case <-time.After(2 * time.Second):
- t.Fatal("expected websocket fallback connection for grpc-configured client")
+ t.Fatal("expected auto transport to fall back to websocket")
}
}
-func TestTunnelClient_connectAndServe_AutoTransportFallsBackToWebSocket_WhenManagerURLUnset(t *testing.T) {
+func TestTunnelClient_connectAndServe_AutoTransportDerivesWebSocketFallbackURL(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
@@ -459,15 +554,66 @@ func TestTunnelClient_connectAndServe_AutoTransportFallsBackToWebSocket_WhenMana
select {
case <-wsConnectedCh:
case <-time.After(2 * time.Second):
- t.Fatal("expected websocket fallback connection when managerURL is unset")
+ t.Fatal("expected auto transport to derive websocket fallback URL")
}
}
+func TestTunnelClient_connectAndServe_AutoTransportOpensGRPCWhenAvailable(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
+ defer cancel()
+
+ envID := "env-auto-poll-grpc"
+ GetRegistry().Unregister(envID)
+ defer GetRegistry().Unregister(envID)
+
+ resolver := func(ctx context.Context, token string) (string, error) {
+ if token != "valid-token" {
+ return "", errors.New("invalid token")
+ }
+ return envID, nil
+ }
+
+ tunnelServer := NewTunnelServer(resolver, nil)
+ go tunnelServer.StartCleanupLoop(ctx)
+ defer tunnelServer.WaitForCleanupDone()
+
+ managerURL, stopManager := startTestGRPCTunnelServerOnAPIPathInternal(t, ctx, tunnelServer)
+ defer stopManager()
+
+ client := NewTunnelClient(&config.Config{
+ EdgeTransport: EdgeTransportAuto,
+ ManagerApiUrl: managerURL,
+ AgentToken: "valid-token",
+ }, http.NotFoundHandler())
+
+ errCh := make(chan error, 1)
+ go func() {
+ errCh <- client.connectAndServe(ctx)
+ }()
+
+ require.Eventually(t, func() bool {
+ tunnel, ok := GetRegistry().Get(envID)
+ if !ok || tunnel == nil || tunnel.Conn == nil || tunnel.Conn.IsClosed() {
+ return false
+ }
+ _, isGRPC := tunnel.Conn.(*GRPCManagerTunnelConn)
+ return isGRPC
+ }, 3*time.Second, 20*time.Millisecond)
+
+ err := <-errCh
+ assert.ErrorIs(t, err, context.DeadlineExceeded)
+}
+
func startTestGRPCTunnelServerOnAPIPathInternal(t *testing.T, ctx context.Context, tunnelServer *TunnelServer) (string, func()) {
t.Helper()
+ return startTestTunnelServiceOnAPIPathInternal(t, ctx, tunnelServer)
+}
+
+func startTestTunnelServiceOnAPIPathInternal(t *testing.T, ctx context.Context, service tunnelpb.TunnelServiceServer) (string, func()) {
+ t.Helper()
grpcServer := grpc.NewServer()
- tunnelpb.RegisterTunnelServiceServer(grpcServer, tunnelServer)
+ tunnelpb.RegisterTunnelServiceServer(grpcServer, service)
var lc net.ListenConfig
lis, err := lc.Listen(ctx, "tcp", "127.0.0.1:0")
diff --git a/backend/pkg/libarcane/edge/client_poll_test.go b/backend/pkg/libarcane/edge/client_poll_test.go
new file mode 100644
index 000000000..b2e732fad
--- /dev/null
+++ b/backend/pkg/libarcane/edge/client_poll_test.go
@@ -0,0 +1,370 @@
+package edge
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "net"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "sync/atomic"
+ "testing"
+ "time"
+
+ "github.com/getarcaneapp/arcane/backend/internal/config"
+ tunnelpb "github.com/getarcaneapp/arcane/backend/pkg/libarcane/edge/proto/tunnel/v1"
+ "github.com/gorilla/websocket"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+ "golang.org/x/net/http2"
+ "golang.org/x/net/http2/h2c"
+ "google.golang.org/grpc"
+)
+
+func TestTunnelClient_connectAndServePoll_OpensGRPCWhenRequired(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
+ defer cancel()
+
+ envID := "env-poll-grpc"
+ GetRegistry().Unregister(envID)
+ defer GetRegistry().Unregister(envID)
+
+ resolver := func(ctx context.Context, token string) (string, error) {
+ if token != "valid-token" {
+ return "", errors.New("invalid token")
+ }
+ return envID, nil
+ }
+
+ tunnelServer := NewTunnelServer(resolver, nil)
+ go tunnelServer.StartCleanupLoop(ctx)
+ defer tunnelServer.WaitForCleanupDone()
+
+ managerURL, stopManager := startTestPollAndGRPCManagerInternal(t, ctx, tunnelServer, TunnelPollResponse{
+ Status: TunnelStatusRequired,
+ PollIntervalSeconds: 1,
+ })
+ defer stopManager()
+
+ client := NewTunnelClient(&config.Config{
+ EdgeTransport: EdgeTransportPoll,
+ ManagerApiUrl: managerURL,
+ AgentToken: "valid-token",
+ }, http.NotFoundHandler())
+
+ errCh := make(chan error, 1)
+ go func() {
+ errCh <- client.connectAndServe(ctx)
+ }()
+
+ require.Eventually(t, func() bool {
+ tunnel, ok := GetRegistry().Get(envID)
+ if !ok || tunnel == nil || tunnel.Conn == nil || tunnel.Conn.IsClosed() {
+ return false
+ }
+ _, isGRPC := tunnel.Conn.(*GRPCManagerTunnelConn)
+ return isGRPC
+ }, 3*time.Second, 20*time.Millisecond)
+
+ err := <-errCh
+ require.Error(t, err)
+ assert.ErrorIs(t, err, context.DeadlineExceeded)
+}
+
+func TestTunnelClient_connectAndServePoll_OpensWebSocketWhenRequired(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 300*time.Millisecond)
+ defer cancel()
+
+ var pollCount atomic.Int32
+ wsConnectedCh := make(chan struct{}, 1)
+
+ managerServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/api/tunnel/poll":
+ pollCount.Add(1)
+ w.Header().Set("Content-Type", "application/json")
+ require.NoError(t, json.NewEncoder(w).Encode(TunnelPollResponse{
+ Status: TunnelStatusRequired,
+ PollIntervalSeconds: 1,
+ }))
+ case "/api/tunnel/connect":
+ upgrader := websocket.Upgrader{}
+ conn, err := upgrader.Upgrade(w, r, nil)
+ if err != nil {
+ return
+ }
+ defer func() { _ = conn.Close() }()
+
+ select {
+ case wsConnectedCh <- struct{}{}:
+ default:
+ }
+
+ <-ctx.Done()
+ default:
+ http.NotFound(w, r)
+ }
+ }))
+ defer managerServer.Close()
+
+ client := NewTunnelClient(&config.Config{
+ EdgeTransport: EdgeTransportPoll,
+ ManagerApiUrl: managerServer.URL,
+ AgentToken: "valid-token",
+ }, http.NotFoundHandler())
+
+ err := client.connectAndServe(ctx)
+ require.Error(t, err)
+ assert.ErrorIs(t, err, context.DeadlineExceeded)
+
+ select {
+ case <-wsConnectedCh:
+ case <-time.After(2 * time.Second):
+ t.Fatal("expected poll transport to open websocket tunnel when required")
+ }
+
+ assert.GreaterOrEqual(t, pollCount.Load(), int32(1))
+}
+
+func TestTunnelClient_pollTunnelControlInternal_UsesConfiguredHTTPClient(t *testing.T) {
+ t.Parallel()
+
+ managerServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ require.NoError(t, json.NewEncoder(w).Encode(TunnelPollResponse{
+ Status: TunnelStatusIdle,
+ PollIntervalSeconds: 1,
+ }))
+ }))
+ defer managerServer.Close()
+
+ baseClient := managerServer.Client()
+ rewriteTransport := roundTripperFunc(func(req *http.Request) (*http.Response, error) {
+ clone := req.Clone(req.Context())
+ clone.URL.Scheme = "http"
+ clone.URL.Host = strings.TrimPrefix(managerServer.URL, "http://")
+ return baseClient.Transport.RoundTrip(clone)
+ })
+
+ client := NewTunnelClient(&config.Config{AgentToken: "valid-token"}, http.NotFoundHandler())
+ client.httpClient = &http.Client{Transport: rewriteTransport}
+
+ resp, err := client.pollTunnelControlInternal(context.Background(), "http://127.0.0.1:1/api/tunnel/poll", false)
+ require.NoError(t, err)
+ assert.Equal(t, TunnelStatusIdle, resp.Status)
+ assert.Equal(t, 1, resp.PollIntervalSeconds)
+ assert.NotNil(t, client.httpClient)
+ assert.NotSame(t, http.DefaultClient, client.httpClient)
+
+ defaultReq, err := http.NewRequestWithContext(context.Background(), http.MethodPost, "http://127.0.0.1:1/api/tunnel/poll", nil)
+ require.NoError(t, err)
+ _, err = http.DefaultClient.Do(defaultReq)
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), "127.0.0.1:1")
+}
+
+func TestTunnelClient_connectAndServePoll_DoesNotOpenWebSocketWhenIdle(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+ defer cancel()
+
+ wsConnectedCh := make(chan struct{}, 1)
+
+ managerServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/api/tunnel/poll":
+ w.Header().Set("Content-Type", "application/json")
+ require.NoError(t, json.NewEncoder(w).Encode(TunnelPollResponse{
+ Status: TunnelStatusIdle,
+ PollIntervalSeconds: 1,
+ }))
+ case "/api/tunnel/connect":
+ select {
+ case wsConnectedCh <- struct{}{}:
+ default:
+ }
+ http.Error(w, "unexpected websocket connect", http.StatusInternalServerError)
+ default:
+ http.NotFound(w, r)
+ }
+ }))
+ defer managerServer.Close()
+
+ client := NewTunnelClient(&config.Config{
+ EdgeTransport: EdgeTransportPoll,
+ ManagerApiUrl: managerServer.URL,
+ AgentToken: "valid-token",
+ }, http.NotFoundHandler())
+
+ err := client.connectAndServe(ctx)
+ require.Error(t, err)
+ assert.ErrorIs(t, err, context.DeadlineExceeded)
+
+ select {
+ case <-wsConnectedCh:
+ t.Fatal("did not expect idle poll transport to open websocket tunnel")
+ default:
+ }
+}
+
+func TestTunnelClient_connectAndServePoll_RetriesAfterTransientPollError(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+ defer cancel()
+
+ var pollCount atomic.Int32
+ wsConnectedCh := make(chan struct{}, 1)
+
+ managerServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ switch r.URL.Path {
+ case "/api/tunnel/poll":
+ currentPoll := pollCount.Add(1)
+ if currentPoll == 1 {
+ http.Error(w, "temporary failure", http.StatusBadGateway)
+ return
+ }
+
+ w.Header().Set("Content-Type", "application/json")
+ require.NoError(t, json.NewEncoder(w).Encode(TunnelPollResponse{
+ Status: TunnelStatusRequired,
+ PollIntervalSeconds: 1,
+ }))
+ case "/api/tunnel/connect":
+ upgrader := websocket.Upgrader{}
+ conn, err := upgrader.Upgrade(w, r, nil)
+ if err != nil {
+ return
+ }
+ defer func() { _ = conn.Close() }()
+
+ select {
+ case wsConnectedCh <- struct{}{}:
+ default:
+ }
+
+ <-ctx.Done()
+ default:
+ http.NotFound(w, r)
+ }
+ }))
+ defer managerServer.Close()
+
+ client := NewTunnelClient(&config.Config{
+ EdgeTransport: EdgeTransportPoll,
+ ManagerApiUrl: managerServer.URL,
+ AgentToken: "valid-token",
+ }, http.NotFoundHandler())
+
+ err := client.connectAndServe(ctx)
+ require.Error(t, err)
+ assert.ErrorIs(t, err, context.DeadlineExceeded)
+
+ select {
+ case <-wsConnectedCh:
+ case <-time.After(2 * time.Second):
+ t.Fatal("expected poll transport to recover after transient poll error")
+ }
+
+ assert.GreaterOrEqual(t, pollCount.Load(), int32(2))
+}
+
+func TestTunnelClient_stopPollManagedSessionInternal_DeadlineExceededReturnsTimeoutMessage(t *testing.T) {
+ t.Parallel()
+
+ session := &pollManagedTunnelSession{
+ cancel: func() {},
+ done: make(chan error),
+ }
+
+ ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
+ defer cancel()
+
+ err := (&TunnelClient{}).stopPollManagedSessionInternal(ctx, session)
+ require.Error(t, err)
+ assert.EqualError(t, err, "timed out waiting for poll-managed websocket session to stop")
+}
+
+func TestTunnelClient_syncPollManagedSessionInternal_IdleUsesBoundedStopTimeout(t *testing.T) {
+ previousTimeout := defaultPollManagedSessionStopTimeout
+ defaultPollManagedSessionStopTimeout = 20 * time.Millisecond
+ defer func() {
+ defaultPollManagedSessionStopTimeout = previousTimeout
+ }()
+
+ session := &pollManagedTunnelSession{
+ cancel: func() {},
+ done: make(chan error),
+ }
+
+ nextSession, err := (&TunnelClient{}).syncPollManagedSessionInternal(context.Background(), session, TunnelStatusIdle)
+ require.Nil(t, nextSession)
+ require.Error(t, err)
+ assert.EqualError(t, err, "timed out waiting for poll-managed websocket session to stop")
+}
+
+func startTestPollAndGRPCManagerInternal(t *testing.T, ctx context.Context, service tunnelpb.TunnelServiceServer, pollResp TunnelPollResponse) (string, func()) {
+ t.Helper()
+
+ grpcServer := grpc.NewServer()
+ tunnelpb.RegisterTunnelServiceServer(grpcServer, service)
+
+ var lc net.ListenConfig
+ lis, err := lc.Listen(ctx, "tcp", "127.0.0.1:0")
+ require.NoError(t, err)
+
+ handler := h2c.NewHandler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path == "/api/tunnel/poll" {
+ w.Header().Set("Content-Type", "application/json")
+ require.NoError(t, json.NewEncoder(w).Encode(pollResp))
+ return
+ }
+
+ if !strings.HasPrefix(r.Header.Get("Content-Type"), "application/grpc") {
+ http.NotFound(w, r)
+ return
+ }
+ if !strings.HasPrefix(r.URL.Path, "/api/") {
+ http.NotFound(w, r)
+ return
+ }
+
+ clone := r.Clone(r.Context())
+ cloneURL := *clone.URL
+ if r.URL.Path == "/api/tunnel/connect" {
+ cloneURL.Path = tunnelpb.TunnelService_Connect_FullMethodName
+ } else {
+ cloneURL.Path = strings.TrimPrefix(r.URL.Path, "/api")
+ }
+ clone.URL = &cloneURL
+ clone.RequestURI = cloneURL.Path
+ grpcServer.ServeHTTP(w, clone)
+ }), &http2.Server{})
+
+ httpServer := &http.Server{
+ Handler: handler,
+ ReadHeaderTimeout: 5 * time.Second,
+ }
+
+ go func() {
+ _ = httpServer.Serve(lis)
+ }()
+
+ cleanup := func() {
+ shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
+ defer shutdownCancel()
+ _ = httpServer.Shutdown(shutdownCtx)
+ grpcServer.Stop()
+ _ = lis.Close()
+ }
+
+ return "http://" + lis.Addr().String(), cleanup
+}
+
+type roundTripperFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripperFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+ if f == nil {
+ return nil, fmt.Errorf("round tripper is nil")
+ }
+ return f(req)
+}
diff --git a/backend/pkg/libarcane/edge/client_transport_grpc.go b/backend/pkg/libarcane/edge/client_transport_grpc.go
index a28ded030..5acb234d5 100644
--- a/backend/pkg/libarcane/edge/client_transport_grpc.go
+++ b/backend/pkg/libarcane/edge/client_transport_grpc.go
@@ -58,17 +58,19 @@ func (c *TunnelClient) connectAndServeGRPC(ctx context.Context) error {
}
defer func() { _ = conn.Close() }()
- streamCtx := metadata.NewOutgoingContext(ctx, metadata.Pairs(
+ streamCtx, streamCancel := context.WithCancel(metadata.NewOutgoingContext(ctx, metadata.Pairs(
strings.ToLower(remenv.HeaderAgentToken), c.cfg.AgentToken,
strings.ToLower(remenv.HeaderAPIKey), c.cfg.AgentToken,
- ))
+ )))
+ defer streamCancel()
+
method := c.grpcConnectMethodInternal()
stream, err := c.openTunnelConnectStreamInternal(streamCtx, conn, method)
if err != nil {
return fmt.Errorf("failed to open tunnel stream: %w", err)
}
- c.conn = NewGRPCAgentTunnelConn(stream)
+ c.conn = NewGRPCAgentTunnelConn(stream, streamCancel)
setActiveAgentTunnelConn(c.conn)
defer clearActiveAgentTunnelConn(c.conn)
if err := c.conn.Send(&TunnelMessage{
@@ -78,6 +80,17 @@ func (c *TunnelClient) connectAndServeGRPC(ctx context.Context) error {
return fmt.Errorf("failed to send register message: %w", err)
}
+ registerMsg, err := c.awaitGRPCRegistrationInternal(ctx)
+ if err != nil {
+ return err
+ }
+
+ slog.InfoContext(ctx, "Edge gRPC tunnel connected to manager",
+ "manager_addr", c.managerGRPCAddr,
+ "environment_id", registerMsg.EnvironmentID,
+ )
+ c.markTransportConnectedInternal(EdgeTransportGRPC)
+
heartbeatCtx, heartbeatCancel := context.WithCancel(ctx)
defer heartbeatCancel()
go c.heartbeatLoop(heartbeatCtx)
@@ -85,6 +98,58 @@ func (c *TunnelClient) connectAndServeGRPC(ctx context.Context) error {
return c.messageLoop(ctx)
}
+func (c *TunnelClient) awaitGRPCRegistrationInternal(ctx context.Context) (*TunnelMessage, error) {
+ if c == nil || c.conn == nil {
+ return nil, fmt.Errorf("gRPC tunnel connection is not initialized")
+ }
+
+ type registrationResult struct {
+ msg *TunnelMessage
+ err error
+ }
+
+ timeout := c.grpcRegistrationTimeoutInternal()
+ recvCh := make(chan registrationResult, 1)
+ go func() {
+ msg, err := c.conn.Receive()
+ recvCh <- registrationResult{msg: msg, err: err}
+ }()
+
+ timer := time.NewTimer(timeout)
+ defer timer.Stop()
+
+ select {
+ case <-ctx.Done():
+ if err := c.conn.Close(); err != nil {
+ slog.DebugContext(ctx, "Failed to close gRPC edge tunnel after context cancellation", "error", err)
+ }
+ return nil, ctx.Err()
+ case <-timer.C:
+ slog.WarnContext(ctx, "Timed out waiting for gRPC edge tunnel registration response",
+ "manager_addr", c.managerGRPCAddr,
+ "timeout", timeout,
+ )
+ if err := c.conn.Close(); err != nil {
+ slog.DebugContext(ctx, "Failed to close gRPC edge tunnel after registration timeout", "error", err)
+ }
+ return nil, fmt.Errorf("timed out waiting for gRPC tunnel registration response after %s", timeout)
+ case result := <-recvCh:
+ if result.err != nil {
+ return nil, fmt.Errorf("failed to receive gRPC tunnel registration response: %w", result.err)
+ }
+ if result.msg == nil {
+ return nil, fmt.Errorf("received empty gRPC tunnel registration response")
+ }
+ if result.msg.Type != MessageTypeRegisterResponse {
+ return nil, fmt.Errorf("unexpected first gRPC tunnel message: %s", result.msg.Type)
+ }
+ if !result.msg.Accepted {
+ return nil, fmt.Errorf("manager rejected tunnel registration: %s", result.msg.Error)
+ }
+ return result.msg, nil
+ }
+}
+
func (c *TunnelClient) openTunnelConnectStreamInternal(
ctx context.Context,
conn *grpc.ClientConn,
diff --git a/backend/pkg/libarcane/edge/client_transport_poll.go b/backend/pkg/libarcane/edge/client_transport_poll.go
new file mode 100644
index 000000000..0978ff084
--- /dev/null
+++ b/backend/pkg/libarcane/edge/client_transport_poll.go
@@ -0,0 +1,231 @@
+package edge
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "log/slog"
+ "net/http"
+ "strings"
+ "time"
+
+ "github.com/getarcaneapp/arcane/backend/internal/utils/remenv"
+)
+
+const defaultTunnelPollRequestTimeout = 15 * time.Second
+
+var defaultPollManagedSessionStopTimeout = 5 * time.Second
+
+type pollManagedTunnelSession struct {
+ cancel context.CancelFunc
+ done chan error
+}
+
+func (c *TunnelClient) connectAndServePoll(ctx context.Context) error {
+ managerBaseURL := strings.TrimRight(strings.TrimSpace(c.cfg.GetManagerBaseURL()), "/")
+ if managerBaseURL == "" {
+ return fmt.Errorf("manager base URL is empty")
+ }
+
+ pollURL := managerBaseURL + "/api/tunnel/poll"
+ interval := DefaultTunnelPollInterval
+ var session *pollManagedTunnelSession
+ defer func() {
+ shutdownCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), defaultPollManagedSessionStopTimeout)
+ defer cancel()
+
+ if err := c.stopPollManagedSessionInternal(shutdownCtx, session); err != nil {
+ slog.WarnContext(ctx, "Failed to stop poll-managed websocket session during shutdown", "error", err)
+ }
+ }()
+
+ for {
+ var err error
+ session, err = consumePollManagedSessionInternal(session)
+ if err != nil {
+ return err
+ }
+
+ if ctx.Err() != nil {
+ return ctx.Err()
+ }
+
+ status, err := c.pollTunnelControlInternal(ctx, pollURL, session != nil)
+ if err != nil {
+ if ctx.Err() != nil {
+ return ctx.Err()
+ }
+
+ slog.WarnContext(ctx, "Poll control request failed, retrying after interval",
+ "error", err,
+ "interval", interval,
+ )
+
+ session, err = waitForNextPollCycleInternal(ctx, session, interval)
+ if err != nil {
+ return err
+ }
+ continue
+ }
+
+ if status.PollIntervalSeconds > 0 {
+ interval = time.Duration(status.PollIntervalSeconds) * time.Second
+ }
+
+ session, err = c.syncPollManagedSessionInternal(ctx, session, status.Status)
+ if err != nil {
+ return err
+ }
+
+ session, err = waitForNextPollCycleInternal(ctx, session, interval)
+ if err != nil {
+ return err
+ }
+ }
+}
+
+func consumePollManagedSessionInternal(session *pollManagedTunnelSession) (*pollManagedTunnelSession, error) {
+ if session == nil {
+ return nil, nil
+ }
+
+ select {
+ case err := <-session.done:
+ if err != nil {
+ return nil, fmt.Errorf("poll-managed websocket session ended: %w", err)
+ }
+ return nil, nil
+ default:
+ return session, nil
+ }
+}
+
+func (c *TunnelClient) syncPollManagedSessionInternal(ctx context.Context, session *pollManagedTunnelSession, status string) (*pollManagedTunnelSession, error) {
+ switch status {
+ case TunnelStatusRequired, TunnelStatusActive:
+ if session != nil {
+ return session, nil
+ }
+
+ slog.InfoContext(ctx, "Poll control plane requested edge tunnel",
+ "status", status,
+ "manager_grpc_addr", c.managerGRPCAddr,
+ "manager_ws_url", c.managerWebSocketURLInternal(),
+ )
+ return c.startPollManagedSessionInternal(ctx), nil
+ case TunnelStatusIdle:
+ if session == nil {
+ return nil, nil
+ }
+
+ slog.InfoContext(ctx, "Poll control plane marked edge tunnel idle; closing session")
+ idleCtx, idleCancel := context.WithTimeout(ctx, defaultPollManagedSessionStopTimeout)
+ err := c.stopPollManagedSessionInternal(idleCtx, session)
+ idleCancel()
+ if err != nil {
+ return nil, err
+ }
+ return nil, nil
+ default:
+ slog.WarnContext(ctx, "Received unknown poll control status", "status", status)
+ return session, nil
+ }
+}
+
+func waitForNextPollCycleInternal(ctx context.Context, session *pollManagedTunnelSession, interval time.Duration) (*pollManagedTunnelSession, error) {
+ waitTimer := time.NewTimer(interval)
+ defer waitTimer.Stop()
+
+ var sessionDone <-chan error
+ if session != nil {
+ sessionDone = session.done
+ }
+
+ select {
+ case <-ctx.Done():
+ return session, ctx.Err()
+ case err := <-sessionDone:
+ if err != nil {
+ return nil, fmt.Errorf("poll-managed websocket session ended: %w", err)
+ }
+ return nil, nil
+ case <-waitTimer.C:
+ return session, nil
+ }
+}
+
+func (c *TunnelClient) pollTunnelControlInternal(ctx context.Context, pollURL string, connected bool) (*TunnelPollResponse, error) {
+ pollReq := TunnelPollRequest{
+ Transport: EdgeTransportPoll,
+ Connected: connected,
+ }
+
+ body, err := json.Marshal(pollReq)
+ if err != nil {
+ return nil, fmt.Errorf("failed to marshal poll request: %w", err)
+ }
+
+ reqCtx, cancel := context.WithTimeout(ctx, defaultTunnelPollRequestTimeout)
+ defer cancel()
+
+ req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, pollURL, bytes.NewReader(body))
+ if err != nil {
+ return nil, fmt.Errorf("failed to create poll request: %w", err)
+ }
+ req.Header.Set("Content-Type", "application/json")
+ req.Header.Set(remenv.HeaderAgentToken, c.cfg.AgentToken)
+ req.Header.Set(remenv.HeaderAPIKey, c.cfg.AgentToken)
+
+ resp, err := c.httpClient.Do(req)
+ if err != nil {
+ return nil, fmt.Errorf("poll request failed: %w", err)
+ }
+ defer func() { _ = resp.Body.Close() }()
+
+ if resp.StatusCode != http.StatusOK {
+ respBody, _ := io.ReadAll(resp.Body)
+ return nil, fmt.Errorf("poll request failed with status %d: %s", resp.StatusCode, string(respBody))
+ }
+
+ var pollResp TunnelPollResponse
+ if err := json.NewDecoder(resp.Body).Decode(&pollResp); err != nil {
+ return nil, fmt.Errorf("failed to decode poll response: %w", err)
+ }
+ return &pollResp, nil
+}
+
+func (c *TunnelClient) startPollManagedSessionInternal(ctx context.Context) *pollManagedTunnelSession {
+ sessionCtx, cancel := context.WithCancel(ctx) //nolint:gosec // helper intentionally returns the cancel func via the managed session.
+ done := make(chan error, 1)
+
+ go func() {
+ err := c.connectAndServeManagedTunnelInternal(sessionCtx)
+ if sessionCtx.Err() != nil {
+ err = nil
+ }
+ done <- err
+ close(done)
+ }()
+
+ return &pollManagedTunnelSession{cancel: cancel, done: done}
+}
+
+func (c *TunnelClient) stopPollManagedSessionInternal(ctx context.Context, session *pollManagedTunnelSession) error {
+ if session == nil {
+ return nil
+ }
+ session.cancel()
+
+ select {
+ case err := <-session.done:
+ return err
+ case <-ctx.Done():
+ if errors.Is(ctx.Err(), context.DeadlineExceeded) {
+ return fmt.Errorf("timed out waiting for poll-managed websocket session to stop")
+ }
+ return ctx.Err()
+ }
+}
diff --git a/backend/pkg/libarcane/edge/client_transport_websocket.go b/backend/pkg/libarcane/edge/client_transport_websocket.go
index 74dfeb7fe..58625b974 100644
--- a/backend/pkg/libarcane/edge/client_transport_websocket.go
+++ b/backend/pkg/libarcane/edge/client_transport_websocket.go
@@ -45,6 +45,7 @@ func (c *TunnelClient) connectAndServeWebSocket(ctx context.Context) error {
setActiveAgentTunnelConn(c.conn)
defer clearActiveAgentTunnelConn(c.conn)
slog.InfoContext(ctx, "WebSocket edge tunnel connected to manager", "manager_url", managerWSURL)
+ c.markTransportConnectedInternal(EdgeTransportWebSocket)
heartbeatCtx, heartbeatCancel := context.WithCancel(ctx)
defer heartbeatCancel()
diff --git a/backend/pkg/libarcane/edge/http_client.go b/backend/pkg/libarcane/edge/http_client.go
index c41b2daf1..96804e420 100644
--- a/backend/pkg/libarcane/edge/http_client.go
+++ b/backend/pkg/libarcane/edge/http_client.go
@@ -58,8 +58,10 @@ func (c *EdgeAwareClient) DoForEnvironment(
return c.doViaTunnel(ctx, envID, method, path, headers, body)
}
- // For edge environments without active tunnel, return error
if isEdge {
+ if _, ok := RequestTunnelAndWait(ctx, envID, DefaultTunnelDemandTTL, DefaultTunnelAcquireTimeout()); ok {
+ return c.doViaTunnel(ctx, envID, method, path, headers, body)
+ }
return nil, fmt.Errorf("edge agent is not connected (no active tunnel)")
}
diff --git a/backend/pkg/libarcane/edge/poll_control.go b/backend/pkg/libarcane/edge/poll_control.go
new file mode 100644
index 000000000..b836b1843
--- /dev/null
+++ b/backend/pkg/libarcane/edge/poll_control.go
@@ -0,0 +1,298 @@
+package edge
+
+import (
+ "encoding/json"
+ "errors"
+ "io"
+ "log/slog"
+ "net/http"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/getarcaneapp/arcane/backend/internal/utils/remenv"
+ "github.com/gin-gonic/gin"
+)
+
+const (
+ // DefaultTunnelPollInterval is how often poll-mode agents should check in.
+ DefaultTunnelPollInterval = 2 * time.Second
+ // DefaultPollRuntimeTTL is how long a poll check-in is considered fresh for
+ // runtime status reporting when no live tunnel is currently open.
+ DefaultPollRuntimeTTL = 6 * time.Second
+ // DefaultTunnelDemandTTL is how long the manager should keep an edge tunnel
+ // marked as required after a user/API request touches the environment.
+ DefaultTunnelDemandTTL = 2 * time.Minute
+
+ // TunnelStatusIdle indicates that no reverse tunnel is currently needed.
+ TunnelStatusIdle = "IDLE"
+ // TunnelStatusRequired indicates that the manager needs the agent to open a tunnel.
+ TunnelStatusRequired = "REQUIRED"
+ // TunnelStatusActive indicates that the manager still needs the tunnel and it is already open.
+ TunnelStatusActive = "ACTIVE"
+)
+
+// TunnelPollRequest is a forward-compatible control-plane check-in request.
+type TunnelPollRequest struct {
+ Transport string `json:"transport,omitempty"`
+ Connected bool `json:"connected,omitempty"`
+}
+
+// TunnelPollResponse is a forward-compatible control-plane response.
+type TunnelPollResponse struct {
+ Status string `json:"status"`
+ PollIntervalSeconds int `json:"pollIntervalSeconds"`
+ ActiveTransport string `json:"activeTransport,omitempty"`
+ Connected bool `json:"connected,omitempty"`
+}
+
+// PollRuntimeState describes the most recent poll-based control-plane activity
+// observed for an edge environment.
+type PollRuntimeState struct {
+ LastPollAt *time.Time
+ PollIntervalSeconds int
+}
+
+// TunnelDemandRegistry tracks short-lived tunnel demand on the manager side.
+type TunnelDemandRegistry struct {
+ demands map[string]time.Time
+ mu sync.RWMutex
+}
+
+// PollRuntimeRegistry tracks recent poll check-ins from edge agents.
+type PollRuntimeRegistry struct {
+ states map[string]PollRuntimeState
+ mu sync.RWMutex
+}
+
+func pollRuntimeTTLInternal(state PollRuntimeState) time.Duration {
+ ttl := DefaultPollRuntimeTTL
+ if state.PollIntervalSeconds > 0 {
+ intervalTTL := time.Duration(state.PollIntervalSeconds) * time.Second * 3
+ if intervalTTL > ttl {
+ ttl = intervalTTL
+ }
+ }
+ return ttl
+}
+
+// NewTunnelDemandRegistry creates a new tunnel demand registry.
+func NewTunnelDemandRegistry() *TunnelDemandRegistry {
+ return &TunnelDemandRegistry{demands: make(map[string]time.Time)}
+}
+
+// NewPollRuntimeRegistry creates a new poll runtime registry.
+func NewPollRuntimeRegistry() *PollRuntimeRegistry {
+ return &PollRuntimeRegistry{states: make(map[string]PollRuntimeState)}
+}
+
+// Touch marks an environment as requiring a reverse tunnel for the specified TTL.
+func (r *TunnelDemandRegistry) Touch(envID string, ttl time.Duration) time.Time {
+ if r == nil || strings.TrimSpace(envID) == "" {
+ return time.Time{}
+ }
+ if ttl <= 0 {
+ ttl = DefaultTunnelDemandTTL
+ }
+
+ expiresAt := time.Now().Add(ttl)
+ r.mu.Lock()
+ r.demands[envID] = expiresAt
+ r.mu.Unlock()
+ return expiresAt
+}
+
+// DesiredStatus returns the desired manager-side tunnel state for an environment.
+func (r *TunnelDemandRegistry) DesiredStatus(envID string, hasActiveTunnel bool, now time.Time) string {
+ if r == nil || strings.TrimSpace(envID) == "" {
+ if hasActiveTunnel {
+ return TunnelStatusActive
+ }
+ return TunnelStatusIdle
+ }
+ if now.IsZero() {
+ now = time.Now()
+ }
+
+ r.mu.RLock()
+ expiresAt, ok := r.demands[envID]
+ r.mu.RUnlock()
+
+ if ok && !now.Before(expiresAt) {
+ r.mu.Lock()
+ expiresAt, ok = r.demands[envID]
+ if ok && !now.Before(expiresAt) {
+ delete(r.demands, envID)
+ ok = false
+ }
+ r.mu.Unlock()
+ }
+
+ if !ok {
+ return TunnelStatusIdle
+ }
+ if hasActiveTunnel {
+ return TunnelStatusActive
+ }
+ return TunnelStatusRequired
+}
+
+var (
+ defaultDemandRegistry = NewTunnelDemandRegistry()
+ defaultPollRuntime = NewPollRuntimeRegistry()
+)
+
+// GetDemandRegistry returns the process-wide tunnel demand registry.
+func GetDemandRegistry() *TunnelDemandRegistry {
+ return defaultDemandRegistry
+}
+
+// GetPollRuntimeRegistry returns the process-wide poll runtime registry.
+func GetPollRuntimeRegistry() *PollRuntimeRegistry {
+ return defaultPollRuntime
+}
+
+// TouchTunnelDemand marks an edge environment as requiring an on-demand tunnel.
+func TouchTunnelDemand(envID string, ttl time.Duration) time.Time {
+ return GetDemandRegistry().Touch(envID, ttl)
+}
+
+// Update records a poll check-in for an environment.
+func (r *PollRuntimeRegistry) Update(envID string, interval time.Duration, now time.Time) PollRuntimeState {
+ if r == nil || strings.TrimSpace(envID) == "" {
+ return PollRuntimeState{}
+ }
+ if now.IsZero() {
+ now = time.Now()
+ }
+ seconds := int(interval / time.Second)
+ if seconds <= 0 {
+ seconds = int(DefaultTunnelPollInterval / time.Second)
+ }
+
+ state := PollRuntimeState{
+ LastPollAt: &now,
+ PollIntervalSeconds: seconds,
+ }
+
+ r.mu.Lock()
+ r.states[envID] = state
+ r.mu.Unlock()
+
+ return state
+}
+
+// Get returns the most recent poll runtime state if it is still fresh.
+func (r *PollRuntimeRegistry) Get(envID string, now time.Time) (PollRuntimeState, bool) {
+ if r == nil || strings.TrimSpace(envID) == "" {
+ return PollRuntimeState{}, false
+ }
+ if now.IsZero() {
+ now = time.Now()
+ }
+
+ r.mu.RLock()
+ state, ok := r.states[envID]
+ r.mu.RUnlock()
+ if !ok || state.LastPollAt == nil {
+ return PollRuntimeState{}, false
+ }
+
+ ttl := pollRuntimeTTLInternal(state)
+
+ if now.Sub(*state.LastPollAt) > ttl {
+ r.mu.Lock()
+ state, ok = r.states[envID]
+ if !ok || state.LastPollAt == nil {
+ r.mu.Unlock()
+ return PollRuntimeState{}, false
+ }
+ ttl = pollRuntimeTTLInternal(state)
+ if now.Sub(*state.LastPollAt) > ttl {
+ delete(r.states, envID)
+ r.mu.Unlock()
+ return PollRuntimeState{}, false
+ }
+ r.mu.Unlock()
+ }
+
+ return state, true
+}
+
+func decodeTunnelPollRequestInternal(c *gin.Context) (*TunnelPollRequest, error) {
+ if c == nil || c.Request == nil || c.Request.Body == nil {
+ return &TunnelPollRequest{}, nil
+ }
+
+ defer func() { _ = c.Request.Body.Close() }()
+
+ var req TunnelPollRequest
+ if err := json.NewDecoder(c.Request.Body).Decode(&req); err != nil {
+ if errors.Is(err, http.ErrBodyReadAfterClose) {
+ return &TunnelPollRequest{}, nil
+ }
+ if errors.Is(err, io.EOF) {
+ return &TunnelPollRequest{}, nil
+ }
+ return nil, err
+ }
+
+ return &req, nil
+}
+
+func (s *TunnelServer) pollStatusInternal(envID string) TunnelPollResponse {
+ hasActiveTunnel := false
+ activeTransport := ""
+
+ if tunnel, ok := s.registry.Get(envID); ok && tunnel != nil && tunnel.Conn != nil && !tunnel.Conn.IsClosed() {
+ hasActiveTunnel = true
+ switch tunnel.Conn.(type) {
+ case *GRPCManagerTunnelConn:
+ activeTransport = EdgeTransportGRPC
+ case *TunnelConn:
+ activeTransport = EdgeTransportWebSocket
+ }
+ }
+
+ status := GetDemandRegistry().DesiredStatus(envID, hasActiveTunnel, time.Now())
+ return TunnelPollResponse{
+ Status: status,
+ PollIntervalSeconds: int(DefaultTunnelPollInterval / time.Second),
+ ActiveTransport: activeTransport,
+ Connected: hasActiveTunnel,
+ }
+}
+
+// HandlePoll is the HTTP control-plane endpoint used by poll-mode agents.
+func (s *TunnelServer) HandlePoll(c *gin.Context) {
+ ctx := c.Request.Context()
+
+ if _, err := decodeTunnelPollRequestInternal(c); err != nil {
+ c.JSON(http.StatusBadRequest, gin.H{"error": "invalid poll payload"})
+ return
+ }
+
+ token := c.GetHeader(remenv.HeaderAgentToken)
+ if token == "" {
+ token = c.GetHeader(remenv.HeaderAPIKey)
+ }
+ if token == "" {
+ slog.WarnContext(ctx, "Edge poll request without token")
+ c.JSON(http.StatusUnauthorized, gin.H{"error": "agent token required"})
+ return
+ }
+
+ envID, err := s.resolveEnvironment(ctx, token)
+ if err != nil {
+ slog.WarnContext(ctx, "Failed to resolve agent token for edge poll", "error", err)
+ c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid agent token"})
+ return
+ }
+
+ pollInterval := DefaultTunnelPollInterval
+ GetPollRuntimeRegistry().Update(envID, pollInterval, time.Now())
+
+ resp := s.pollStatusInternal(envID)
+ resp.PollIntervalSeconds = int(pollInterval / time.Second)
+ c.JSON(http.StatusOK, resp)
+}
diff --git a/backend/pkg/libarcane/edge/poll_control_test.go b/backend/pkg/libarcane/edge/poll_control_test.go
new file mode 100644
index 000000000..ec0dada96
--- /dev/null
+++ b/backend/pkg/libarcane/edge/poll_control_test.go
@@ -0,0 +1,87 @@
+package edge
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "errors"
+ "net/http"
+ "net/http/httptest"
+ "testing"
+ "time"
+
+ "github.com/getarcaneapp/arcane/backend/internal/utils/remenv"
+ "github.com/gin-gonic/gin"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestTunnelDemandRegistryDesiredStatus(t *testing.T) {
+ r := NewTunnelDemandRegistry()
+ now := time.Now()
+
+ assert.Equal(t, TunnelStatusIdle, r.DesiredStatus("env-1", false, now))
+
+ r.Touch("env-1", time.Minute)
+ assert.Equal(t, TunnelStatusRequired, r.DesiredStatus("env-1", false, now))
+ assert.Equal(t, TunnelStatusActive, r.DesiredStatus("env-1", true, now))
+ assert.Equal(t, TunnelStatusIdle, r.DesiredStatus("env-1", false, now.Add(2*time.Minute)))
+}
+
+func TestTunnelServer_HandlePoll(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+
+ registry := NewTunnelRegistry()
+ server := NewTunnelServerWithRegistry(registry, func(ctx context.Context, token string) (string, error) {
+ if token != "valid-token" {
+ return "", errors.New("invalid token")
+ }
+ return "env-poll-1", nil
+ }, nil)
+
+ router := gin.New()
+ router.POST("/api/tunnel/poll", server.HandlePoll)
+
+ TouchTunnelDemand("env-poll-1", time.Minute)
+
+ req := httptest.NewRequest(http.MethodPost, "/api/tunnel/poll", bytes.NewBufferString(`{"transport":"poll"}`))
+ req.Header.Set(remenv.HeaderAgentToken, "valid-token")
+ rec := httptest.NewRecorder()
+ router.ServeHTTP(rec, req)
+
+ require.Equal(t, http.StatusOK, rec.Code)
+ var resp TunnelPollResponse
+ require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+ assert.Equal(t, TunnelStatusRequired, resp.Status)
+ assert.Equal(t, int(DefaultTunnelPollInterval/time.Second), resp.PollIntervalSeconds)
+ assert.False(t, resp.Connected)
+ if state, ok := GetPollRuntimeRegistry().Get("env-poll-1", time.Now()); assert.True(t, ok) {
+ assert.NotNil(t, state.LastPollAt)
+ assert.Equal(t, int(DefaultTunnelPollInterval/time.Second), state.PollIntervalSeconds)
+ }
+
+ registry.Register("env-poll-1", NewAgentTunnelWithConn("env-poll-1", NewGRPCManagerTunnelConn(nil)))
+ t.Cleanup(func() { registry.Unregister("env-poll-1") })
+
+ req = httptest.NewRequest(http.MethodPost, "/api/tunnel/poll", bytes.NewBufferString(`{"transport":"poll","connected":true}`))
+ req.Header.Set(remenv.HeaderAgentToken, "valid-token")
+ rec = httptest.NewRecorder()
+ router.ServeHTTP(rec, req)
+
+ require.Equal(t, http.StatusOK, rec.Code)
+ require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+ assert.Equal(t, TunnelStatusActive, resp.Status)
+ assert.Equal(t, int(DefaultTunnelPollInterval/time.Second), resp.PollIntervalSeconds)
+ assert.True(t, resp.Connected)
+ assert.Equal(t, EdgeTransportGRPC, resp.ActiveTransport)
+}
+
+func TestPollRuntimeRegistryGetExpiresStaleState(t *testing.T) {
+ r := NewPollRuntimeRegistry()
+ now := time.Now()
+ r.Update("env-stale", DefaultTunnelPollInterval, now)
+
+ state, ok := r.Get("env-stale", now.Add(DefaultPollRuntimeTTL+time.Second))
+ assert.False(t, ok)
+ assert.Nil(t, state.LastPollAt)
+}
diff --git a/backend/pkg/libarcane/edge/proxy.go b/backend/pkg/libarcane/edge/proxy.go
index c98894ad0..212a1a016 100644
--- a/backend/pkg/libarcane/edge/proxy.go
+++ b/backend/pkg/libarcane/edge/proxy.go
@@ -16,8 +16,17 @@ import (
const (
// DefaultProxyTimeout is the default timeout for proxied requests
DefaultProxyTimeout = 5 * time.Minute
+ // DefaultTunnelAcquirePollEvery is how frequently the manager checks for a
+ // newly activated edge tunnel while waiting for poll mode to connect.
+ DefaultTunnelAcquirePollEvery = 100 * time.Millisecond
)
+// DefaultTunnelAcquireTimeout returns a poll-aware wait timeout for acquiring
+// an on-demand edge tunnel.
+func DefaultTunnelAcquireTimeout() time.Duration {
+ return DefaultTunnelPollInterval + 2*time.Second
+}
+
// ProxyRequest sends an HTTP request through an edge tunnel
// Returns the response status, headers, and body
func ProxyRequest(ctx context.Context, tunnel *AgentTunnel, method, path, query string, headers map[string]string, body []byte) (int, map[string]string, []byte, error) {
@@ -266,11 +275,52 @@ func stripInternalTunnelHeaders(headers map[string]string) map[string]string {
// HasActiveTunnel checks if an environment has an active edge tunnel
func HasActiveTunnel(envID string) bool {
+ _, ok := GetActiveTunnel(envID)
+ return ok
+}
+
+// GetActiveTunnel returns the active tunnel for an environment, if one exists.
+func GetActiveTunnel(envID string) (*AgentTunnel, bool) {
tunnel, ok := GetRegistry().Get(envID)
- if !ok {
- return false
+ if !ok || tunnel == nil || tunnel.Conn == nil || tunnel.Conn.IsClosed() {
+ return nil, false
}
- return !tunnel.Conn.IsClosed()
+ return tunnel, true
+}
+
+// WaitForActiveTunnel waits for an environment to establish a live tunnel.
+func WaitForActiveTunnel(ctx context.Context, envID string, timeout time.Duration) (*AgentTunnel, bool) {
+ if timeout <= 0 {
+ return GetActiveTunnel(envID)
+ }
+
+ if tunnel, ok := GetActiveTunnel(envID); ok {
+ return tunnel, true
+ }
+
+ waitCtx, cancel := context.WithTimeout(ctx, timeout)
+ defer cancel()
+
+ ticker := time.NewTicker(DefaultTunnelAcquirePollEvery)
+ defer ticker.Stop()
+
+ for {
+ select {
+ case <-waitCtx.Done():
+ return nil, false
+ case <-ticker.C:
+ if tunnel, ok := GetActiveTunnel(envID); ok {
+ return tunnel, true
+ }
+ }
+ }
+}
+
+// RequestTunnelAndWait marks an edge environment as needed and waits for the
+// agent to establish a live tunnel.
+func RequestTunnelAndWait(ctx context.Context, envID string, demandTTL, timeout time.Duration) (*AgentTunnel, bool) {
+ TouchTunnelDemand(envID, demandTTL)
+ return WaitForActiveTunnel(ctx, envID, timeout)
}
// DoRequest performs an HTTP request through an edge tunnel.
diff --git a/backend/pkg/libarcane/edge/server.go b/backend/pkg/libarcane/edge/server.go
index afd7c2eef..cf909ea9c 100644
--- a/backend/pkg/libarcane/edge/server.go
+++ b/backend/pkg/libarcane/edge/server.go
@@ -204,12 +204,6 @@ func tokenFromMetadata(ctx context.Context) string {
func (s *TunnelServer) manageConnectedTunnel(ctx context.Context, callbackCtx context.Context, tunnel *AgentTunnel) {
slog.InfoContext(ctx, "Edge agent connected", "environment_id", tunnel.EnvironmentID)
- s.registry.Register(tunnel.EnvironmentID, tunnel)
-
- if s.statusCallback != nil {
- s.statusCallback(callbackCtx, tunnel.EnvironmentID, true)
- }
-
if _, ok := tunnel.Conn.(*GRPCManagerTunnelConn); ok {
if err := tunnel.Conn.Send(&TunnelMessage{
Type: MessageTypeRegisterResponse,
@@ -217,9 +211,17 @@ func (s *TunnelServer) manageConnectedTunnel(ctx context.Context, callbackCtx co
EnvironmentID: tunnel.EnvironmentID,
}); err != nil {
slog.WarnContext(ctx, "Failed to send register response", "environment_id", tunnel.EnvironmentID, "error", err)
+ _ = tunnel.Close()
+ return
}
}
+ s.registry.Register(tunnel.EnvironmentID, tunnel)
+
+ if s.statusCallback != nil {
+ s.statusCallback(callbackCtx, tunnel.EnvironmentID, true)
+ }
+
defer func() {
s.registry.Unregister(tunnel.EnvironmentID)
slog.InfoContext(ctx, "Edge agent disconnected", "environment_id", tunnel.EnvironmentID)
diff --git a/backend/pkg/libarcane/edge/server_test.go b/backend/pkg/libarcane/edge/server_test.go
index 890be0ebb..7051a110f 100644
--- a/backend/pkg/libarcane/edge/server_test.go
+++ b/backend/pkg/libarcane/edge/server_test.go
@@ -360,3 +360,53 @@ func (f *fakeServerTunnelConn) IsClosed() bool { return false }
func (f *fakeServerTunnelConn) SendRequest(ctx context.Context, msg *TunnelMessage, pending *sync.Map) (*TunnelMessage, error) {
return nil, errors.New("not implemented")
}
+
+type registerResponseOrderConn struct {
+ sendHook func(*TunnelMessage) error
+ recvErr error
+}
+
+func (f *registerResponseOrderConn) Send(msg *TunnelMessage) error {
+ if f.sendHook != nil {
+ return f.sendHook(msg)
+ }
+ return nil
+}
+
+func (f *registerResponseOrderConn) Receive() (*TunnelMessage, error) {
+ if f.recvErr != nil {
+ return nil, f.recvErr
+ }
+ return nil, io.EOF
+}
+
+func (f *registerResponseOrderConn) IsExpectedReceiveError(error) bool { return false }
+
+func (f *registerResponseOrderConn) Close() error { return nil }
+
+func (f *registerResponseOrderConn) IsClosed() bool { return false }
+
+func (f *registerResponseOrderConn) SendRequest(ctx context.Context, msg *TunnelMessage, pending *sync.Map) (*TunnelMessage, error) {
+ return nil, errors.New("not implemented")
+}
+
+func TestTunnelServer_ManageConnectedTunnel_SendsGRPCRegisterResponseBeforeRegistering(t *testing.T) {
+ server := NewTunnelServer(nil, nil)
+ envID := "env-grpc-register-order"
+ server.registry.Unregister(envID)
+ t.Cleanup(func() { server.registry.Unregister(envID) })
+
+ conn := &registerResponseOrderConn{recvErr: io.EOF}
+ conn.sendHook = func(msg *TunnelMessage) error {
+ require.Equal(t, MessageTypeRegisterResponse, msg.Type)
+ _, ok := server.registry.Get(envID)
+ assert.False(t, ok, "gRPC tunnel should not be routable before register response is sent")
+ return nil
+ }
+
+ tunnel := NewAgentTunnelWithConn(envID, conn)
+ server.manageConnectedTunnel(context.Background(), context.Background(), tunnel)
+
+ _, ok := server.registry.Get(envID)
+ assert.False(t, ok)
+}
diff --git a/backend/pkg/libarcane/edge/transport.go b/backend/pkg/libarcane/edge/transport.go
index b4347ac6f..8fffe30d4 100644
--- a/backend/pkg/libarcane/edge/transport.go
+++ b/backend/pkg/libarcane/edge/transport.go
@@ -19,17 +19,24 @@ const (
EdgeTransportWebSocket = "websocket"
// EdgeTransportGRPC forces gRPC transport without WebSocket fallback.
EdgeTransportGRPC = "grpc"
- // EdgeTransportAuto prefers gRPC and falls back to WebSocket automatically.
+ // EdgeTransportPoll uses an HTTP polling control plane with the existing
+ // websocket tunnel as an on-demand data plane.
+ EdgeTransportPoll = "poll"
+ // EdgeTransportAuto preserves the legacy managed tunnel behavior: try gRPC
+ // first and fall back to websocket when available.
EdgeTransportAuto = "auto"
)
-// NormalizeEdgeTransport normalizes transport config and defaults to auto-negotiation.
+// NormalizeEdgeTransport normalizes transport config and defaults to the legacy
+// managed tunnel auto mode for backwards compatibility.
func NormalizeEdgeTransport(value string) string {
switch strings.ToLower(strings.TrimSpace(value)) {
case EdgeTransportWebSocket:
return EdgeTransportWebSocket
case EdgeTransportGRPC:
return EdgeTransportGRPC
+ case EdgeTransportPoll:
+ return EdgeTransportPoll
case EdgeTransportAuto:
return EdgeTransportAuto
default:
@@ -37,7 +44,7 @@ func NormalizeEdgeTransport(value string) string {
}
}
-// UseGRPCEdgeTransport reports whether gRPC should be attempted.
+// UseGRPCEdgeTransport reports whether gRPC managed tunnel mode should be attempted.
func UseGRPCEdgeTransport(cfg *config.Config) bool {
if cfg == nil {
return false
@@ -46,7 +53,7 @@ func UseGRPCEdgeTransport(cfg *config.Config) bool {
return transport == EdgeTransportGRPC || transport == EdgeTransportAuto
}
-// UseWebSocketEdgeTransport reports whether WebSocket transport is allowed.
+// UseWebSocketEdgeTransport reports whether websocket managed tunnel mode is allowed.
func UseWebSocketEdgeTransport(cfg *config.Config) bool {
if cfg == nil {
return false
@@ -55,6 +62,15 @@ func UseWebSocketEdgeTransport(cfg *config.Config) bool {
return transport == EdgeTransportWebSocket || transport == EdgeTransportAuto
}
+// UsePollEdgeTransport reports whether the Portainer-style polling control plane
+// should be used.
+func UsePollEdgeTransport(cfg *config.Config) bool {
+ if cfg == nil {
+ return false
+ }
+ return NormalizeEdgeTransport(cfg.EdgeTransport) == EdgeTransportPoll
+}
+
// GetActiveTunnelTransport returns the currently active tunnel transport for an environment.
func GetActiveTunnelTransport(envID string) (string, bool) {
tunnel, ok := GetRegistry().Get(envID)
diff --git a/backend/pkg/libarcane/edge/transport_test.go b/backend/pkg/libarcane/edge/transport_test.go
index ebccbb461..6635619e1 100644
--- a/backend/pkg/libarcane/edge/transport_test.go
+++ b/backend/pkg/libarcane/edge/transport_test.go
@@ -13,6 +13,7 @@ func TestNormalizeEdgeTransport(t *testing.T) {
assert.Equal(t, EdgeTransportAuto, NormalizeEdgeTransport(""))
assert.Equal(t, EdgeTransportGRPC, NormalizeEdgeTransport("grpc"))
assert.Equal(t, EdgeTransportGRPC, NormalizeEdgeTransport("GRPC"))
+ assert.Equal(t, EdgeTransportPoll, NormalizeEdgeTransport("poll"))
assert.Equal(t, EdgeTransportWebSocket, NormalizeEdgeTransport("websocket"))
assert.Equal(t, EdgeTransportAuto, NormalizeEdgeTransport("invalid"))
assert.Equal(t, EdgeTransportAuto, NormalizeEdgeTransport("auto"))
@@ -31,9 +32,19 @@ func TestUseWebSocketEdgeTransport(t *testing.T) {
assert.True(t, UseWebSocketEdgeTransport(&config.Config{EdgeTransport: ""}))
assert.True(t, UseWebSocketEdgeTransport(&config.Config{EdgeTransport: "auto"}))
assert.False(t, UseWebSocketEdgeTransport(&config.Config{EdgeTransport: "grpc"}))
+ assert.False(t, UseWebSocketEdgeTransport(&config.Config{EdgeTransport: "poll"}))
assert.True(t, UseWebSocketEdgeTransport(&config.Config{EdgeTransport: "websocket"}))
}
+func TestUsePollEdgeTransport(t *testing.T) {
+ assert.False(t, UsePollEdgeTransport(nil))
+ assert.False(t, UsePollEdgeTransport(&config.Config{EdgeTransport: ""}))
+ assert.False(t, UsePollEdgeTransport(&config.Config{EdgeTransport: "auto"}))
+ assert.False(t, UsePollEdgeTransport(&config.Config{EdgeTransport: "grpc"}))
+ assert.False(t, UsePollEdgeTransport(&config.Config{EdgeTransport: "websocket"}))
+ assert.True(t, UsePollEdgeTransport(&config.Config{EdgeTransport: "poll"}))
+}
+
func TestGetActiveTunnelTransport(t *testing.T) {
t.Run("returns false when tunnel is missing", func(t *testing.T) {
transport, ok := GetActiveTunnelTransport("env-missing")
diff --git a/backend/pkg/libarcane/edge/tunnel.go b/backend/pkg/libarcane/edge/tunnel.go
index f0aebb575..913a65c2d 100644
--- a/backend/pkg/libarcane/edge/tunnel.go
+++ b/backend/pkg/libarcane/edge/tunnel.go
@@ -301,14 +301,20 @@ func (t *GRPCManagerTunnelConn) markClosed() {
// GRPCAgentTunnelConn wraps the agent-side gRPC tunnel stream.
type GRPCAgentTunnelConn struct {
stream grpcAgentStream
+ cancel context.CancelFunc
mu sync.Mutex
closed bool
closedMu sync.RWMutex
}
// NewGRPCAgentTunnelConn creates an agent-side gRPC tunnel wrapper.
-func NewGRPCAgentTunnelConn(stream grpcAgentStream) *GRPCAgentTunnelConn {
- return &GRPCAgentTunnelConn{stream: stream}
+func NewGRPCAgentTunnelConn(stream grpcAgentStream, cancelFns ...context.CancelFunc) *GRPCAgentTunnelConn {
+ var cancel context.CancelFunc
+ if len(cancelFns) > 0 {
+ cancel = cancelFns[0]
+ }
+
+ return &GRPCAgentTunnelConn{stream: stream, cancel: cancel}
}
// Send sends an agent->manager tunnel message over gRPC.
@@ -357,6 +363,12 @@ func (t *GRPCAgentTunnelConn) IsExpectedReceiveError(err error) bool {
// Close closes the client send stream.
func (t *GRPCAgentTunnelConn) Close() error {
t.markClosed()
+ if t.cancel != nil {
+ t.cancel()
+ }
+ if t.stream == nil {
+ return nil
+ }
return t.stream.CloseSend()
}
diff --git a/frontend/messages/en.json b/frontend/messages/en.json
index 8a6c6b4b0..c43ca474a 100644
--- a/frontend/messages/en.json
+++ b/frontend/messages/en.json
@@ -116,6 +116,7 @@
"common_disable": "Disable",
"common_current": "Current",
"common_online": "Online",
+ "common_standby": "Standby",
"common_offline": "Offline",
"common_copy": "Copy",
"common_copy_json": "Copy JSON",
@@ -880,6 +881,22 @@
"environments_regenerate_dialog_message": "This will create a new API key for this environment. The current API key will be invalidated immediately, and the agent will lose connection until you update it with the new key.",
"environments_regenerate_key_success": "API key regenerated successfully",
"environments_regenerate_key_failed": "Failed to regenerate API key",
+ "environments_edge_polling_label": "Polling",
+ "environments_edge_control_plane_label": "Control Plane",
+ "environments_edge_polling_active": "Polling Active",
+ "environments_edge_polling_standby": "Polling Standby",
+ "environments_edge_polling_inactive": "Polling Inactive",
+ "environments_edge_last_poll_label": "Last Poll Check-in",
+ "environments_edge_live_tunnel_label": "Live Tunnel",
+ "environments_edge_tunnel_type_label": "Tunnel Type",
+ "environments_edge_tunnel_type_inactive": "Inactive",
+ "environments_edge_tunnel_transmitting": "Transmitting",
+ "environments_edge_tunnel_dormant": "Dormant",
+ "environments_edge_tunnel_negotiating": "Negotiating",
+ "environments_edge_tunnel_disconnected": "Disconnected",
+ "environments_edge_connected_since_label": "Connected Since",
+ "environments_edge_last_heartbeat_label": "Last Heartbeat",
+ "environments_version_unavailable": "Version information unavailable",
"_comment_users": "=== USERS ===",
"users_title": "Users",
"users_subtitle": "Manage system users and permissions",
diff --git a/frontend/src/lib/components/progress-popover.svelte b/frontend/src/lib/components/progress-popover.svelte
index 476cf4abb..4ef6dc569 100644
--- a/frontend/src/lib/components/progress-popover.svelte
+++ b/frontend/src/lib/components/progress-popover.svelte
@@ -285,11 +285,14 @@
</div>
{/if}
{/snippet}
-
{#if isMobile.current}
<Dialog.Root bind:open onOpenChange={handleOpenChange}>
- <Dialog.Trigger class={triggerClass}>
- {@render children()}
+ <Dialog.Trigger>
+ {#snippet child({ props })}
+ <span {...props} class={cn('inline-flex w-fit', triggerClass)}>
+ {@render children()}
+ </span>
+ {/snippet}
</Dialog.Trigger>
<Dialog.Content class={cn('p-2', error && 'max-w-[600px]', className)} showCloseButton={!loading}>
{@render content()}
@@ -297,8 +300,12 @@
</Dialog.Root>
{:else}
<Popover.Root bind:open onOpenChange={handleOpenChange}>
- <Popover.Trigger class={triggerClass}>
- {@render children()}
+ <Popover.Trigger>
+ {#snippet child({ props })}
+ <span {...props} class={cn('inline-flex w-fit', triggerClass)}>
+ {@render children()}
+ </span>
+ {/snippet}
</Popover.Trigger>
<Popover.Content class={cn('w-80 p-2', error && 'w-auto max-w-[600px]', className)} {align} {sideOffset}>
diff --git a/frontend/src/lib/types/environment.type.ts b/frontend/src/lib/types/environment.type.ts
index dd1bc687a..61987e807 100644
--- a/frontend/src/lib/types/environment.type.ts
+++ b/frontend/src/lib/types/environment.type.ts
@@ -1,4 +1,4 @@
-export type EnvironmentStatus = 'online' | 'offline' | 'error' | 'pending';
+export type EnvironmentStatus = 'online' | 'standby' | 'offline' | 'error' | 'pending';
export type Environment = {
id: string;
@@ -11,6 +11,7 @@ export type Environment = {
connected?: boolean;
connectedAt?: string;
lastHeartbeat?: string;
+ lastPollAt?: string;
lastSeen?: string;
apiKey?: string;
};
diff --git a/frontend/src/lib/utils/environment-status.ts b/frontend/src/lib/utils/environment-status.ts
index d34da694c..c65e0d20d 100644
--- a/frontend/src/lib/utils/environment-status.ts
+++ b/frontend/src/lib/utils/environment-status.ts
@@ -1,6 +1,6 @@
import type { Environment, EnvironmentStatus } from '$lib/types/environment.type';
-type RuntimeEnvironmentState = Pick<Environment, 'isEdge' | 'connected' | 'status'>;
+type RuntimeEnvironmentState = Pick<Environment, 'isEdge' | 'connected' | 'status' | 'lastPollAt'>;
export function resolveEnvironmentStatus(
environment: RuntimeEnvironmentState,
@@ -12,12 +12,20 @@ export function resolveEnvironmentStatus(
return status;
}
+ if (environment.connected === true) {
+ return 'online';
+ }
+
+ if (environment.lastPollAt) {
+ return 'standby';
+ }
+
if (status === 'pending') {
return 'pending';
}
- if (environment.connected === true) {
- return 'online';
+ if (status === 'standby') {
+ return 'standby';
}
if (environment.connected === false) {
@@ -28,13 +36,16 @@ export function resolveEnvironmentStatus(
}
export function isEnvironmentOnline(environment: RuntimeEnvironmentState, overrideStatus?: EnvironmentStatus | null): boolean {
- return resolveEnvironmentStatus(environment, overrideStatus) === 'online';
+ const resolved = resolveEnvironmentStatus(environment, overrideStatus);
+ return resolved === 'online' || resolved === 'standby';
}
-export function getEnvironmentStatusVariant(status: EnvironmentStatus): 'green' | 'amber' | 'red' {
+export function getEnvironmentStatusVariant(status: EnvironmentStatus): 'green' | 'blue' | 'amber' | 'red' {
switch (status) {
case 'online':
return 'green';
+ case 'standby':
+ return 'blue';
case 'pending':
return 'amber';
default:
diff --git a/frontend/src/routes/(app)/environments/[id]/+page.svelte b/frontend/src/routes/(app)/environments/[id]/+page.svelte
index 1f58630c4..a69bdad24 100644
--- a/frontend/src/routes/(app)/environments/[id]/+page.svelte
+++ b/frontend/src/routes/(app)/environments/[id]/+page.svelte
@@ -1,4 +1,5 @@
<script lang="ts">
+ import { onMount } from 'svelte';
import { z } from 'zod/v4';
import * as Tabs from '$lib/components/ui/tabs/index.js';
import { TabBar, type TabItem } from '$lib/components/tab-bar';
@@ -12,7 +13,7 @@
import { settingsService } from '$lib/services/settings-service';
import { environmentStore } from '$lib/stores/environment.store.svelte';
import type { AppVersionInformation } from '$lib/types/application-configuration';
- import type { EnvironmentStatus } from '$lib/types/environment.type';
+ import type { Environment, EnvironmentStatus } from '$lib/types/environment.type';
import { isEnvironmentOnline, resolveEnvironmentStatus } from '$lib/utils/environment-status';
import MobileFloatingFormActions from '$lib/components/form/mobile-floating-form-actions.svelte';
import { createSettingsForm } from '$lib/utils/settings-form.util';
@@ -35,6 +36,11 @@
let { data } = $props();
let { environment, settings, versionInformation } = $derived(data);
+ let refreshedEnvironment: Environment | null = $state(null);
+ let runtimeEnvironment: Environment = $derived.by(() => {
+ const refreshed = refreshedEnvironment;
+ return refreshed && refreshed.id === environment.id ? refreshed : environment;
+ });
let currentEnvironment = $derived(environmentStore.selected);
@@ -122,8 +128,9 @@
// Only non-edge custom URL tests should temporarily override the displayed status.
let statusOverride = $state<EnvironmentStatus | null>(null);
- let currentStatus = $derived(resolveEnvironmentStatus(environment, statusOverride));
- let isCurrentlyOnline = $derived(isEnvironmentOnline(environment, statusOverride));
+ let currentStatus = $derived(resolveEnvironmentStatus(runtimeEnvironment, statusOverride));
+ let isCurrentlyOnline = $derived(isEnvironmentOnline(runtimeEnvironment, statusOverride));
+ let isCurrentlyStandby = $derived(currentStatus === 'standby');
// Form schema combining environment info and settings
const formSchema = z.object({
@@ -282,6 +289,30 @@
}
});
+ onMount(() => {
+ if (environment.isEdge) {
+ void refreshRuntimeEnvironment();
+ }
+
+ const interval = window.setInterval(() => {
+ if (!environment.isEdge) return;
+ void refreshRuntimeEnvironment();
+ }, 5000);
+
+ return () => window.clearInterval(interval);
+ });
+
+ async function refreshRuntimeEnvironment() {
+ try {
+ const latestEnvironment = await environmentManagementService.get(environment.id);
+ if (latestEnvironment.id === environment.id) {
+ refreshedEnvironment = latestEnvironment;
+ }
+ } catch (error) {
+ console.debug('Failed to refresh environment runtime state:', error);
+ }
+ }
+
async function fetchVersion() {
try {
isLoadingVersion = true;
@@ -444,7 +475,16 @@
</div>
</div>
- {#if !environment.enabled || currentStatus !== 'online' || !settings}
+ {#if environment.enabled && settings && isCurrentlyStandby}
+ <div
+ class="flex items-start gap-3 rounded-lg border border-blue-500/30 bg-blue-500/10 p-4 text-blue-900 dark:text-blue-200"
+ >
+ <AlertIcon class="mt-0.5 size-5 shrink-0 text-blue-600 dark:text-blue-400" />
+ <div class="flex-1 space-y-1">
+ <p class="text-sm font-medium">{m.common_status()}: {m.common_standby()}</p>
+ </div>
+ </div>
+ {:else if !environment.enabled || !isCurrentlyOnline || !settings}
<div
class="flex items-start gap-3 rounded-lg border border-amber-500/30 bg-amber-500/10 p-4 text-amber-900 dark:text-amber-200"
>
@@ -453,7 +493,7 @@
<p class="text-sm font-medium">
{#if !environment.enabled}
{m.environments_warning_disabled()}
- {:else if currentStatus !== 'online'}
+ {:else if !isCurrentlyOnline}
{m.common_status()}: {currentStatus === 'pending'
? m.common_pending()
: currentStatus === 'error'
@@ -475,7 +515,7 @@
<Tabs.Content value="details">
<DetailsTab
- {environment}
+ environment={runtimeEnvironment}
{formInputs}
{currentStatus}
{isLoadingVersion}
diff --git a/frontend/src/routes/(app)/environments/[id]/components/DetailsTab.svelte b/frontend/src/routes/(app)/environments/[id]/components/DetailsTab.svelte
index 0545ecb98..8e4b90aca 100644
--- a/frontend/src/routes/(app)/environments/[id]/components/DetailsTab.svelte
+++ b/frontend/src/routes/(app)/environments/[id]/components/DetailsTab.svelte
@@ -28,6 +28,10 @@
return { text: 'HTTP', variant: 'gray' };
}
+ if (environment.lastPollAt) {
+ return { text: m.environments_edge_polling_label(), variant: 'blue' };
+ }
+
if (!environment.connected || !environment.edgeTransport) {
return { text: 'Edge', variant: 'gray' };
}
@@ -39,6 +43,22 @@
return { text: 'gRPC', variant: 'blue' };
});
+ let controlPlaneBadge = $derived.by((): { text: string; variant: 'blue' | 'green' | 'gray' } | null => {
+ if (!environment.isEdge || !environment.lastPollAt) {
+ return null;
+ }
+
+ if (environment.connected) {
+ return { text: m.environments_edge_polling_active(), variant: 'green' };
+ }
+
+ if (currentStatus === 'standby') {
+ return { text: m.environments_edge_polling_standby(), variant: 'blue' };
+ }
+
+ return { text: m.environments_edge_polling_inactive(), variant: 'gray' };
+ });
+
let localDisplayVersion = $derived(
versionInformation?.displayVersion || versionInformation?.currentTag || versionInformation?.currentVersion || 'Unknown'
);
@@ -47,10 +67,12 @@
remoteVersion?.displayVersion || remoteVersion?.currentTag || remoteVersion?.currentVersion || ''
);
- let statusBadge = $derived.by((): { text: string; variant: 'green' | 'amber' | 'red' } => {
+ let statusBadge = $derived.by((): { text: string; variant: 'green' | 'blue' | 'amber' | 'red' } => {
switch (currentStatus) {
case 'online':
return { text: m.common_online(), variant: 'green' };
+ case 'standby':
+ return { text: m.common_standby(), variant: 'blue' };
case 'pending':
return { text: m.common_pending(), variant: 'amber' };
case 'error':
@@ -60,17 +82,36 @@
}
});
- let tunnelBadge = $derived.by((): { text: string; variant: 'green' | 'amber' | 'red' } => {
+ let tunnelBadge = $derived.by((): { text: string; variant: 'green' | 'blue' | 'gray' | 'amber' | 'red' } => {
if (!environment.isEdge) {
return statusBadge;
}
if (environment.connected) {
- return { text: m.common_online(), variant: 'green' };
+ return { text: m.environments_edge_tunnel_transmitting(), variant: 'green' };
+ }
+ if (currentStatus === 'standby') {
+ return { text: m.environments_edge_tunnel_dormant(), variant: 'gray' };
}
if (currentStatus === 'pending') {
- return { text: m.common_pending(), variant: 'amber' };
+ return { text: m.environments_edge_tunnel_negotiating(), variant: 'amber' };
}
- return { text: m.common_offline(), variant: 'red' };
+ return { text: m.environments_edge_tunnel_disconnected(), variant: 'red' };
+ });
+
+ let tunnelTypeBadge = $derived.by((): { text: string; variant: 'blue' | 'purple' | 'gray' } | null => {
+ if (!environment.isEdge || !environment.lastPollAt) {
+ return null;
+ }
+
+ if (environment.edgeTransport === 'websocket') {
+ return { text: 'WebSocket', variant: 'purple' };
+ }
+
+ if (environment.edgeTransport === 'grpc') {
+ return { text: 'gRPC', variant: 'blue' };
+ }
+
+ return { text: m.environments_edge_tunnel_type_inactive(), variant: 'gray' };
});
function formatDateTime(value?: string): string {
@@ -190,18 +231,38 @@
</div>
</div>
{#if environment.isEdge}
+ {#if controlPlaneBadge}
+ <div>
+ <Label class="text-muted-foreground text-xs font-medium">{m.environments_edge_control_plane_label()}</Label>
+ <div class="mt-1">
+ <StatusBadge text={controlPlaneBadge.text} variant={controlPlaneBadge.variant} />
+ </div>
+ </div>
+ <div>
+ <Label class="text-muted-foreground text-xs font-medium">{m.environments_edge_last_poll_label()}</Label>
+ <div class="mt-1 font-mono text-sm">{formatDateTime(environment.lastPollAt)}</div>
+ </div>
+ {/if}
<div>
- <Label class="text-muted-foreground text-xs font-medium">Tunnel</Label>
+ <Label class="text-muted-foreground text-xs font-medium">{m.environments_edge_live_tunnel_label()}</Label>
<div class="mt-1">
<StatusBadge text={tunnelBadge.text} variant={tunnelBadge.variant} />
</div>
</div>
+ {#if tunnelTypeBadge}
+ <div>
+ <Label class="text-muted-foreground text-xs font-medium">{m.environments_edge_tunnel_type_label()}</Label>
+ <div class="mt-1">
+ <StatusBadge text={tunnelTypeBadge.text} variant={tunnelTypeBadge.variant} />
+ </div>
+ </div>
+ {/if}
<div>
- <Label class="text-muted-foreground text-xs font-medium">Connected Since</Label>
+ <Label class="text-muted-foreground text-xs font-medium">{m.environments_edge_connected_since_label()}</Label>
<div class="mt-1 font-mono text-sm">{formatDateTime(environment.connectedAt)}</div>
</div>
<div>
- <Label class="text-muted-foreground text-xs font-medium">Last Heartbeat</Label>
+ <Label class="text-muted-foreground text-xs font-medium">{m.environments_edge_last_heartbeat_label()}</Label>
<div class="mt-1 font-mono text-sm">{formatDateTime(environment.lastHeartbeat)}</div>
</div>
{/if}
@@ -235,8 +296,8 @@
</a>
{/if}
{/if}
- {:else if currentStatus === 'online'}
- <span class="text-muted-foreground text-sm">Version information unavailable</span>
+ {:else if currentStatus === 'online' || currentStatus === 'standby'}
+ <span class="text-muted-foreground text-sm">{m.environments_version_unavailable()}</span>
{:else}
<span class="text-muted-foreground text-sm">{m.common_offline()}</span>
{/if}
diff --git a/frontend/src/routes/(app)/environments/environment-table.svelte b/frontend/src/routes/(app)/environments/environment-table.svelte
index 0477eeaf2..88a75a9ad 100644
--- a/frontend/src/routes/(app)/environments/environment-table.svelte
+++ b/frontend/src/routes/(app)/environments/environment-table.svelte
@@ -265,9 +265,11 @@
<div
class="border-background absolute -top-1 -right-1 size-3 rounded-full border-2 {statusValue === 'online'
? 'bg-green-500'
- : statusValue === 'pending'
- ? 'bg-amber-500'
- : 'bg-red-500'}"
+ : statusValue === 'standby'
+ ? 'bg-blue-500'
+ : statusValue === 'pending'
+ ? 'bg-amber-500'
+ : 'bg-red-500'}"
></div>
</div>
{#if environmentStore.selected?.id === item.id}
@@ -297,18 +299,22 @@
{@const env = value as Environment}
{@const typeLabel = !env.isEdge
? 'HTTP'
- : !env.connected || !env.edgeTransport
- ? 'Edge'
- : env.edgeTransport === 'websocket'
- ? 'WebSocket'
- : 'gRPC'}
+ : env.lastPollAt
+ ? m.environments_edge_polling_label()
+ : !env.connected || !env.edgeTransport
+ ? 'Edge'
+ : env.edgeTransport === 'websocket'
+ ? 'WebSocket'
+ : 'gRPC'}
{@const typeVariant = !env.isEdge
? 'gray'
- : !env.connected || !env.edgeTransport
- ? 'gray'
- : env.edgeTransport === 'websocket'
- ? 'purple'
- : 'blue'}
+ : env.lastPollAt
+ ? 'blue'
+ : !env.connected || !env.edgeTransport
+ ? 'gray'
+ : env.edgeTransport === 'websocket'
+ ? 'purple'
+ : 'blue'}
<StatusBadge text={typeLabel} variant={typeVariant} />
{/snippet}
@@ -349,11 +355,13 @@
getValue: (item: Environment) =>
!item.isEdge
? 'HTTP'
- : !item.connected || !item.edgeTransport
- ? 'Edge'
- : item.edgeTransport === 'websocket'
- ? 'WebSocket'
- : 'gRPC',
+ : item.lastPollAt
+ ? m.environments_edge_polling_label()
+ : !item.connected || !item.edgeTransport
+ ? 'Edge'
+ : item.edgeTransport === 'websocket'
+ ? 'WebSocket'
+ : 'gRPC',
icon: StatsIcon,
iconVariant: 'gray' as const,
show: mobileFieldVisibility.type ?? true
diff --git a/tests/spec/edge-agent.spec.ts b/tests/spec/edge-agent.spec.ts
index 4e7ff29d7..1714678dc 100644
--- a/tests/spec/edge-agent.spec.ts
+++ b/tests/spec/edge-agent.spec.ts
@@ -1,77 +1,77 @@
-import { test, expect, type Page } from "@playwright/test";
+import { test, expect, type Page } from '@playwright/test';
const ROUTES = {
- environments: "/environments",
+ environments: '/environments',
};
async function openNewEnvironmentSheet(page: Page) {
await page.goto(ROUTES.environments);
- await page.waitForLoadState("networkidle");
+ await page.waitForLoadState('networkidle');
- const addButton = page.getByRole("button", { name: "Add Environment", exact: true });
+ const addButton = page.getByRole('button', { name: 'Add Environment', exact: true });
await expect(addButton).toBeVisible();
await addButton.click();
- await expect(page.getByText("Create New Agent Environment")).toBeVisible();
+ await expect(page.getByText('Create New Agent Environment')).toBeVisible();
}
async function switchToEdgeMode(page: Page) {
- await page.getByRole("tab", { name: "Edge", exact: true }).click();
- await expect(page.getByText("Agent connects outbound to the manager.")).toBeVisible();
+ await page.getByRole('tab', { name: 'Edge', exact: true }).click();
+ await expect(page.getByText('Agent connects outbound to the manager.')).toBeVisible();
}
-test.describe("Edge Agent Environment", () => {
- test("should display the edge agent form", async ({ page }) => {
+test.describe('Edge Agent Environment', () => {
+ test('should display the edge agent form', async ({ page }) => {
await openNewEnvironmentSheet(page);
await switchToEdgeMode(page);
- await expect(page.getByPlaceholder("Remote Docker Host")).toBeVisible();
- await expect(page.getByRole("button", { name: "Generate Agent Configuration", exact: true })).toBeVisible();
+ await expect(page.getByPlaceholder('Remote Docker Host')).toBeVisible();
+ await expect(page.getByRole('button', { name: 'Generate Agent Configuration', exact: true })).toBeVisible();
});
- test("should switch between direct and edge connection modes", async ({ page }) => {
+ test('should switch between direct and edge connection modes', async ({ page }) => {
await openNewEnvironmentSheet(page);
- await expect(page.locator("#new-agent-api-url")).toBeVisible();
- await expect(page.getByPlaceholder("Remote Docker Host")).toBeHidden();
+ await expect(page.locator('#new-agent-api-url')).toBeVisible();
+ await expect(page.getByPlaceholder('Remote Docker Host')).toBeHidden();
await switchToEdgeMode(page);
- await expect(page.locator("#new-agent-api-url")).toBeHidden();
- await expect(page.getByPlaceholder("Remote Docker Host")).toBeVisible();
+ await expect(page.locator('#new-agent-api-url')).toBeHidden();
+ await expect(page.getByPlaceholder('Remote Docker Host')).toBeVisible();
- await page.getByRole("tab", { name: "Direct", exact: true }).click();
- await expect(page.locator("#new-agent-api-url")).toBeVisible();
- await expect(page.getByPlaceholder("Remote Docker Host")).toBeHidden();
+ await page.getByRole('tab', { name: 'Direct', exact: true }).click();
+ await expect(page.locator('#new-agent-api-url')).toBeVisible();
+ await expect(page.getByPlaceholder('Remote Docker Host')).toBeHidden();
});
- test("should validate required fields for edge and direct modes", async ({ page }) => {
+ test('should validate required fields for edge and direct modes', async ({ page }) => {
await openNewEnvironmentSheet(page);
let createRequests = 0;
- await page.route("**/api/environments", async (route) => {
- if (route.request().method() === "POST") {
+ await page.route('**/api/environments', async (route) => {
+ if (route.request().method() === 'POST') {
createRequests += 1;
}
await route.continue();
});
// Direct mode: missing name and URL
- await page.getByRole("button", { name: "Generate Agent Configuration", exact: true }).click();
+ await page.getByRole('button', { name: 'Generate Agent Configuration', exact: true }).click();
await expect.poll(() => createRequests).toBe(0);
// Edge mode: missing name
await switchToEdgeMode(page);
- await page.getByRole("button", { name: "Generate Agent Configuration", exact: true }).click();
+ await page.getByRole('button', { name: 'Generate Agent Configuration', exact: true }).click();
await expect.poll(() => createRequests).toBe(0);
});
- test("should create an edge agent environment and show deployment snippets", async ({ page }) => {
+ test('should create an edge agent environment and show deployment snippets', async ({ page }) => {
const environmentName = `edge-agent-${Date.now().toString().slice(-6)}`;
let createdEnvironmentId: string | null = null;
- await page.route("**/api/environments", async (route) => {
- if (route.request().method() === "POST") {
+ await page.route('**/api/environments', async (route) => {
+ if (route.request().method() === 'POST') {
const response = await route.fetch();
const body = await response.text();
try {
@@ -96,41 +96,41 @@ test.describe("Edge Agent Environment", () => {
await openNewEnvironmentSheet(page);
await switchToEdgeMode(page);
- await page.getByPlaceholder("Remote Docker Host").fill(environmentName);
- const submitButton = page.getByRole("button", { name: "Generate Agent Configuration", exact: true });
+ await page.getByPlaceholder('Remote Docker Host').fill(environmentName);
+ const submitButton = page.getByRole('button', { name: 'Generate Agent Configuration', exact: true });
await submitButton.click();
const sheetTitle = page.locator('[data-slot="sheet-title"]');
await expect(sheetTitle).toContainText(/Environment Created/i);
- await expect(page.getByText("Edge agent - connects outbound to manager", { exact: true })).toBeVisible();
- await expect(page.getByText("API Key", { exact: true })).toBeVisible();
- await expect(page.getByText("Docker Run Command", { exact: true })).toBeVisible();
- await expect(page.getByText("Docker Compose", { exact: true })).toBeVisible();
+ await expect(page.getByText('Edge agent - connects outbound to manager', { exact: true })).toBeVisible();
+ await expect(page.getByText('API Key', { exact: true })).toBeVisible();
+ await expect(page.getByText('Docker Run Command', { exact: true })).toBeVisible();
+ await expect(page.getByText('Docker Compose', { exact: true })).toBeVisible();
- const snippetBlocks = page.locator("pre code").filter({ hasText: "EDGE_AGENT=true" });
+ const snippetBlocks = page.locator('pre code').filter({ hasText: 'EDGE_AGENT=true' });
await expect(snippetBlocks.first()).toBeVisible();
const dockerRunSnippet = snippetBlocks.first();
- await expect(dockerRunSnippet).toContainText("arcane-edge-agent");
- await expect(dockerRunSnippet).not.toContainText("-p 3553:3553");
+ await expect(dockerRunSnippet).toContainText('arcane-edge-agent');
+ await expect(dockerRunSnippet).not.toContainText('-p 3553:3553');
- await page.getByRole("button", { name: "Done", exact: true }).click();
+ await page.getByRole('button', { name: 'Done', exact: true }).click();
- await expect(page.getByRole("button", { name: environmentName, exact: true })).toBeVisible();
- const environmentRow = page.locator("tr").filter({
- has: page.getByRole("button", { name: environmentName, exact: true }),
+ await expect(page.getByRole('button', { name: environmentName, exact: true })).toBeVisible();
+ const environmentRow = page.locator('tr').filter({
+ has: page.getByRole('button', { name: environmentName, exact: true }),
});
- await expect(environmentRow.getByText("edge://edge-agent-").first()).toBeVisible();
- await expect(environmentRow.getByText("Edge", { exact: true })).toBeVisible();
+ await expect(environmentRow.getByText('edge://edge-agent-').first()).toBeVisible();
+ await expect(environmentRow.getByText('Edge', { exact: true })).toBeVisible();
- await page.getByRole("button", { name: environmentName, exact: true }).click();
+ await page.getByRole('button', { name: environmentName, exact: true }).click();
if (createdEnvironmentId) {
await expect(page).toHaveURL(new RegExp(`/environments/${createdEnvironmentId}`));
}
- await expect(page.locator("#api-url")).toHaveValue(/edge:\/\/edge-agent-/);
- await expect(page.getByText("Edge", { exact: true }).first()).toBeVisible();
- await expect(page.getByText("Tunnel", { exact: true })).toBeVisible();
+ await expect(page.locator('#api-url')).toHaveValue(/edge:\/\/edge-agent-/);
+ await expect(page.getByText('Edge', { exact: true }).first()).toBeVisible();
+ await expect(page.getByText('Live Tunnel', { exact: true })).toBeVisible();
} finally {
if (createdEnvironmentId) {
await page.request.delete(`/api/environments/${createdEnvironmentId}`);
diff --git a/tests/spec/project.spec.ts b/tests/spec/project.spec.ts
index ab9295591..d789fd707 100644
--- a/tests/spec/project.spec.ts
+++ b/tests/spec/project.spec.ts
@@ -421,10 +421,10 @@ test.describe('New Compose Project Page', () => {
await expect(deployMenuTrigger).toBeVisible();
- await deployMenuTrigger.click();
+ await deployMenuTrigger.click({ force: true });
await page.getByRole('menuitemradio', { name: /Always/i }).click();
- await deployMenuTrigger.click();
+ await deployMenuTrigger.click({ force: true });
await page.getByRole('menuitemcheckbox', { name: /Force recreate containers/i }).click();
await page.getByRole('button', { name: 'Up', exact: true }).click();
diff --git a/tests/spec/settings-notifications.spec.ts b/tests/spec/settings-notifications.spec.ts
index 65b224cff..8e77c1d92 100644
--- a/tests/spec/settings-notifications.spec.ts
+++ b/tests/spec/settings-notifications.spec.ts
@@ -88,7 +88,7 @@ test.describe('Notification settings', () => {
await page.goto('/settings/notifications');
await page.waitForLoadState('networkidle');
- await expect(page.getByRole('tab', { name: 'Built-in' })).toBeVisible();
+ await expect(page.getByRole('tab', { name: 'Built-in Notifications' })).toBeVisible();
await expect(page.getByRole('tab', { name: 'Email' })).toBeVisible();
return {
diff --git a/tests/spec/volumes.spec.ts b/tests/spec/volumes.spec.ts
index 0cefbffdb..2eafc7f3b 100644
--- a/tests/spec/volumes.spec.ts
+++ b/tests/spec/volumes.spec.ts
@@ -9,11 +9,26 @@ test.beforeEach(async ({ page }) => {
volumeCount = await fetchVolumeCountsWithRetry(page);
});
-async function createVolumeViaUI(page: Page, volumeName: string) {
+async function openCreateVolumeSheet(page: Page) {
await page.goto('/volumes');
await page.waitForLoadState('networkidle');
- await page.getByRole('button', { name: 'Create Volume' }).first().click();
+ await expect(page.getByRole('heading', { name: 'Volumes', level: 1 })).toBeVisible();
+
+ const createButton = page.getByRole('button', { name: 'Create Volume' }).first();
+ if (await createButton.isVisible().catch(() => false)) {
+ await createButton.click();
+ } else {
+ const overflowButton = page.getByRole('button', { name: 'More actions' }).first();
+ await expect(overflowButton).toBeVisible();
+ await overflowButton.click();
+ await page.getByRole('menuitem', { name: 'Create Volume', exact: true }).click();
+ }
+
await expect(page.getByRole('dialog')).toBeVisible();
+}
+
+async function createVolumeViaUI(page: Page, volumeName: string) {
+ await openCreateVolumeSheet(page);
await page.getByRole('dialog').locator('input[type="text"]').first().fill(volumeName);
await page.getByRole('dialog').getByRole('button', { name: 'Create Volume' }).click();
await expect(page.locator('li[data-sonner-toast][data-type="success"] div[data-title]')).toBeVisible();
@@ -89,11 +104,7 @@ test.describe('Volumes Page', () => {
});
test('Create Volume Sheet Opens', async ({ page }) => {
- await page.goto('/volumes');
- await page.waitForLoadState('networkidle');
-
- await page.getByRole('button', { name: 'Create Volume' }).first().click();
- await expect(page.getByRole('dialog')).toBeVisible();
+ await openCreateVolumeSheet(page);
await expect(page.getByText('Create New Volume')).toBeVisible();
});
diff --git a/types/environment/environment.go b/types/environment/environment.go
index ca095ab6a..53d6ada62 100644
--- a/types/environment/environment.go
+++ b/types/environment/environment.go
@@ -145,6 +145,12 @@ type Environment struct {
// Required: false
LastHeartbeat *time.Time `json:"lastHeartbeat,omitempty"`
+ // LastPollAt is the timestamp of the most recent poll control-plane check-in
+ // received from a poll-mode edge agent.
+ //
+ // Required: false
+ LastPollAt *time.Time `json:"lastPollAt,omitempty"`
+
// ApiKey is returned only when creating or regenerating
//
// Required: false