Skip to content

Modern Docker Management, Designed for Everyone

fix: improve environment proxy error handling (#2649)

Kyle Mendelledb4e96891d6
diff --git a/backend/api/handlers/environments.go b/backend/api/handlers/environments.go
index 1b63a08e6..af747fa6a 100644
--- a/backend/api/handlers/environments.go
+++ b/backend/api/handlers/environments.go
@@ -23,6 +23,7 @@ import (
"github.com/getarcaneapp/arcane/backend/pkg/libarcane/edge"
"github.com/getarcaneapp/arcane/backend/pkg/pagination"
"github.com/getarcaneapp/arcane/backend/pkg/utils"
+ httputils "github.com/getarcaneapp/arcane/backend/pkg/utils/httpx"
"github.com/getarcaneapp/arcane/backend/pkg/utils/mapper"
"github.com/getarcaneapp/arcane/types/base"
"github.com/getarcaneapp/arcane/types/environment"
@@ -1127,8 +1128,15 @@ func (h *EnvironmentHandler) GetEnvironmentVersion(ctx context.Context, input *G
}
} else {
// Direct HTTP request for non-edge environments
- url := strings.TrimRight(env.ApiUrl, "/") + "/api/app-version"
- req, err := http.NewRequestWithContext(reqCtx, http.MethodGet, url, nil)
+ validatedURL, validateErr := httputils.ValidateOutboundHTTPURL(env.ApiUrl)
+ if validateErr != nil {
+ return nil, huma.Error400BadRequest("Invalid environment API URL")
+ }
+ validatedURL.RawQuery = ""
+ validatedURL.Fragment = ""
+ validatedURL.Path = strings.TrimRight(validatedURL.Path, "/") + "/api/app-version"
+
+ req, err := http.NewRequestWithContext(reqCtx, http.MethodGet, validatedURL.String(), nil)
if err != nil {
return nil, huma.Error500InternalServerError("Failed to create request")
}
diff --git a/backend/internal/common/errors.go b/backend/internal/common/errors.go
index fa4e23f4c..94b7656df 100644
--- a/backend/internal/common/errors.go
+++ b/backend/internal/common/errors.go
@@ -371,6 +371,50 @@ func (e *EnvironmentNotFoundError) Error() string {
return "Environment not found"
}
+type EnvironmentDisabledError struct{}
+
+func (e *EnvironmentDisabledError) Error() string {
+ return "Environment is disabled"
+}
+
+type EnvironmentUnauthorizedError struct{}
+
+func (e *EnvironmentUnauthorizedError) Error() string {
+ return "Authentication required to access remote environments"
+}
+
+type EnvironmentInvalidProxyTargetError struct {
+ Err error
+}
+
+func (e *EnvironmentInvalidProxyTargetError) Error() string {
+ return fmt.Sprintf("Invalid proxy target URL: %v", e.Err)
+}
+
+func (e *EnvironmentInvalidProxyTargetError) Unwrap() error { return e.Err }
+
+type EnvironmentProxyRequestCreationError struct {
+ Err error
+}
+
+func (e *EnvironmentProxyRequestCreationError) Error() string {
+ return fmt.Sprintf("Failed to create proxy request: %v", e.Err)
+}
+
+type EnvironmentProxyRequestFailedError struct {
+ Err error
+}
+
+func (e *EnvironmentProxyRequestFailedError) Error() string {
+ return fmt.Sprintf("Proxy request failed: %v", e.Err)
+}
+
+type EdgeAgentNotConnectedError struct{}
+
+func (e *EdgeAgentNotConnectedError) Error() string {
+ return "Edge agent is not connected"
+}
+
type AgentTokenPersistenceError struct {
Err error
}
diff --git a/backend/internal/middleware/environment_middleware.go b/backend/internal/middleware/environment_middleware.go
index 1501fb1e8..f79e76439 100644
--- a/backend/internal/middleware/environment_middleware.go
+++ b/backend/internal/middleware/environment_middleware.go
@@ -3,6 +3,7 @@ package middleware
import (
"bytes"
"context"
+ "errors"
"fmt"
"io"
"log/slog"
@@ -11,8 +12,10 @@ import (
"strings"
"time"
+ "github.com/getarcaneapp/arcane/backend/internal/common"
"github.com/getarcaneapp/arcane/backend/pkg/libarcane/edge"
wsutil "github.com/getarcaneapp/arcane/backend/pkg/libarcane/ws"
+ httputils "github.com/getarcaneapp/arcane/backend/pkg/utils/httpx"
"github.com/gorilla/websocket"
"github.com/labstack/echo/v4"
)
@@ -21,12 +24,6 @@ const (
apiEnvironmentsPrefix = "/api/environments/"
environmentsPathMarker = "/environments/"
- errEnvironmentNotFound = "Environment not found"
- errEnvironmentDisabled = "Environment is disabled"
- errFailedCreateProxyRequest = "Failed to create proxy request"
- errProxyRequestFailedPrefix = "Proxy request failed:"
- errUnauthorized = "Authentication required to access remote environments"
-
// proxyTimeout is intentionally generous because some proxied operations
// (e.g., image pulls with progress streaming) can take multiple minutes.
proxyTimeout = 30 * time.Minute
@@ -112,7 +109,7 @@ func (m *EnvironmentMiddleware) Handle(c echo.Context, next echo.HandlerFunc) er
if m.authValidator != nil && !m.authValidator(c.Request().Context(), c) {
return c.JSON(http.StatusUnauthorized, map[string]any{
"success": false,
- "data": map[string]any{"error": errUnauthorized},
+ "data": map[string]any{"error": (&common.EnvironmentUnauthorizedError{}).Error()},
})
}
@@ -120,14 +117,14 @@ func (m *EnvironmentMiddleware) Handle(c echo.Context, next echo.HandlerFunc) er
if err != nil || apiURL == "" {
return c.JSON(http.StatusNotFound, map[string]any{
"success": false,
- "data": map[string]any{"error": errEnvironmentNotFound},
+ "data": map[string]any{"error": (&common.EnvironmentNotFoundError{}).Error()},
})
}
if !enabled {
return c.JSON(http.StatusBadRequest, map[string]any{
"success": false,
- "data": map[string]any{"error": errEnvironmentDisabled},
+ "data": map[string]any{"error": (&common.EnvironmentDisabledError{}).Error()},
})
}
@@ -314,7 +311,7 @@ func (m *EnvironmentMiddleware) abortEdgeTunnelUnavailable(c echo.Context) error
return c.JSON(http.StatusBadGateway, map[string]any{
"success": false,
"data": map[string]any{
- "error": "Edge agent is not connected",
+ "error": (&common.EdgeAgentNotConnectedError{}).Error(),
},
})
}
@@ -344,9 +341,14 @@ func (m *EnvironmentMiddleware) proxyHTTP(c echo.Context, target string, accessT
req, err := m.createProxyRequest(c, target, accessToken)
if err != nil {
+ errMessage := (&common.EnvironmentProxyRequestCreationError{Err: err}).Error()
+ var invalidTargetErr *common.EnvironmentInvalidProxyTargetError
+ if errors.As(err, &invalidTargetErr) {
+ errMessage = invalidTargetErr.Error()
+ }
return c.JSON(http.StatusInternalServerError, map[string]any{
"success": false,
- "data": map[string]any{"error": errFailedCreateProxyRequest},
+ "data": map[string]any{"error": errMessage},
})
}
@@ -354,7 +356,7 @@ func (m *EnvironmentMiddleware) proxyHTTP(c echo.Context, target string, accessT
if err != nil {
return c.JSON(http.StatusBadGateway, map[string]any{
"success": false,
- "data": map[string]any{"error": fmt.Sprintf("%s %v", errProxyRequestFailedPrefix, err)},
+ "data": map[string]any{"error": (&common.EnvironmentProxyRequestFailedError{Err: err}).Error()},
})
}
defer func() { _ = resp.Body.Close() }()
@@ -366,6 +368,11 @@ func (m *EnvironmentMiddleware) proxyHTTP(c echo.Context, target string, accessT
// createProxyRequest builds the HTTP request to forward to the remote environment.
func (m *EnvironmentMiddleware) createProxyRequest(c echo.Context, target string, accessToken *string) (*http.Request, error) {
srcReq := c.Request()
+ validatedTarget, err := httputils.ValidateOutboundHTTPURL(target)
+ if err != nil {
+ return nil, &common.EnvironmentInvalidProxyTargetError{Err: err}
+ }
+
var bodyBytes []byte
if srcReq.Body != nil {
var err error
@@ -378,14 +385,23 @@ func (m *EnvironmentMiddleware) createProxyRequest(c echo.Context, target string
slog.DebugContext(srcReq.Context(), "Creating proxy request", "method", srcReq.Method, "target", target, "contentLength", srcReq.ContentLength, "contentType", srcReq.Header.Get("Content-Type"), "bodyLength", len(bodyBytes), "body", string(bodyBytes))
- var body io.Reader
+ var requestBody io.ReadCloser
+ var getBody func() (io.ReadCloser, error)
if len(bodyBytes) > 0 {
- body = bytes.NewReader(bodyBytes)
- }
- req, err := http.NewRequestWithContext(srcReq.Context(), srcReq.Method, target, body)
- if err != nil {
- return nil, err
+ requestBody = io.NopCloser(bytes.NewReader(bodyBytes))
+ getBody = func() (io.ReadCloser, error) {
+ return io.NopCloser(bytes.NewReader(bodyBytes)), nil
+ }
}
+ requestURL := *validatedTarget
+ req := (&http.Request{
+ Method: srcReq.Method,
+ URL: &requestURL,
+ Host: requestURL.Host,
+ Header: make(http.Header),
+ Body: requestBody,
+ GetBody: getBody,
+ }).WithContext(srcReq.Context())
skip := edge.GetSkipHeaders()
edge.CopyRequestHeaders(srcReq.Header, req.Header, skip)
diff --git a/backend/internal/middleware/environment_middleware_test.go b/backend/internal/middleware/environment_middleware_test.go
index a069985ac..3d3f91ed2 100644
--- a/backend/internal/middleware/environment_middleware_test.go
+++ b/backend/internal/middleware/environment_middleware_test.go
@@ -230,3 +230,15 @@ func TestIsWebSocketUpgrade(t *testing.T) {
})
}
}
+
+func TestEnvironmentMiddleware_CreateProxyRequest_RejectsInvalidProxyTarget(t *testing.T) {
+ middleware := newTestEnvironmentMiddleware()
+ e := echo.New()
+ recorder := httptest.NewRecorder()
+ req := httptest.NewRequest(http.MethodGet, "/api/environments/env-edge/containers", nil)
+ c := e.NewContext(req, recorder)
+
+ _, err := middleware.createProxyRequest(c, "ftp://example.com/containers", nil)
+ assert.Error(t, err)
+ assert.Contains(t, err.Error(), "Invalid proxy target URL")
+}
diff --git a/backend/internal/services/environment_service.go b/backend/internal/services/environment_service.go
index 1a9ac3469..312acf0d1 100644
--- a/backend/internal/services/environment_service.go
+++ b/backend/internal/services/environment_service.go
@@ -19,6 +19,7 @@ import (
"github.com/getarcaneapp/arcane/backend/pkg/libarcane/timeouts"
"github.com/getarcaneapp/arcane/backend/pkg/pagination"
"github.com/getarcaneapp/arcane/backend/pkg/remenv"
+ httputils "github.com/getarcaneapp/arcane/backend/pkg/utils/httpx"
"github.com/getarcaneapp/arcane/backend/pkg/utils/mapper"
"github.com/getarcaneapp/arcane/types/containerregistry"
"github.com/getarcaneapp/arcane/types/environment"
@@ -743,10 +744,17 @@ func (s *EnvironmentService) TestConnection(ctx context.Context, id string, cust
apiUrl = *customApiUrl
}
+ healthURL, err := buildEnvironmentEndpointURLInternal(apiUrl, "/api/health")
+ if err != nil {
+ if customApiUrl == nil {
+ _ = s.updateEnvironmentStatusInternal(ctx, id, string(models.EnvironmentStatusOffline))
+ }
+ return "offline", fmt.Errorf("invalid environment API URL: %w", err)
+ }
+
reqCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
- url := strings.TrimRight(apiUrl, "/") + "/api/health"
- req, err := http.NewRequestWithContext(reqCtx, http.MethodGet, url, nil)
+ req, err := http.NewRequestWithContext(reqCtx, http.MethodGet, healthURL, nil)
if err != nil {
if customApiUrl == nil {
_ = s.updateEnvironmentStatusInternal(ctx, id, string(models.EnvironmentStatusOffline))
@@ -965,9 +973,14 @@ func (s *EnvironmentService) RegenerateEnvironmentApiKey(ctx context.Context, en
// Deprecated - Use the Api Key flow
func (s *EnvironmentService) PairAgentWithBootstrap(ctx context.Context, apiUrl, bootstrapToken string) (string, error) {
+ pairURL, err := buildEnvironmentEndpointURLInternal(apiUrl, "/api/environments/0/agent/pair")
+ if err != nil {
+ return "", fmt.Errorf("invalid agent API URL: %w", err)
+ }
+
reqCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
- req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, strings.TrimRight(apiUrl, "/")+"/api/environments/0/agent/pair", nil)
+ req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, pairURL, nil)
if err != nil {
return "", fmt.Errorf("create request: %w", err)
}
@@ -1319,15 +1332,45 @@ func (s *EnvironmentService) resolveRemoteEnvironmentTargetInternal(ctx context.
return nil, fmt.Errorf("cannot proxy request to local environment")
}
+ targetURL := strings.TrimRight(environment.ApiUrl, "/")
+ if !environment.IsEdge {
+ validatedTargetURL, err := normalizeEnvironmentBaseURLInternal(environment.ApiUrl)
+ if err != nil {
+ return nil, fmt.Errorf("invalid environment API URL: %w", err)
+ }
+ targetURL = validatedTargetURL
+ }
+
return &remoteEnvironmentTargetInternal{
ID: environment.ID,
Name: environment.Name,
IsEdge: environment.IsEdge,
AccessToken: environment.AccessToken,
- TargetURL: strings.TrimRight(environment.ApiUrl, "/"),
+ TargetURL: targetURL,
}, nil
}
+func normalizeEnvironmentBaseURLInternal(apiURL string) (string, error) {
+ parsed, err := httputils.ValidateOutboundHTTPURL(apiURL)
+ if err != nil {
+ return "", err
+ }
+
+ parsed.RawQuery = ""
+ parsed.Fragment = ""
+ parsed.Path = strings.TrimRight(parsed.Path, "/")
+ return parsed.String(), nil
+}
+
+func buildEnvironmentEndpointURLInternal(apiURL, endpointPath string) (string, error) {
+ baseURL, err := normalizeEnvironmentBaseURLInternal(apiURL)
+ if err != nil {
+ return "", err
+ }
+
+ return strings.TrimRight(baseURL, "/") + endpointPath, nil
+}
+
func (s *EnvironmentService) getProxyRequestContextInternal(ctx context.Context) (context.Context, context.CancelFunc) {
if s != nil && s.settingsService != nil {
settings := s.settingsService.GetSettingsConfig()
diff --git a/backend/internal/services/environment_service_test.go b/backend/internal/services/environment_service_test.go
index 1c47c95d3..4ad417464 100644
--- a/backend/internal/services/environment_service_test.go
+++ b/backend/internal/services/environment_service_test.go
@@ -928,3 +928,37 @@ func TestEnvironmentService_GenerateEdgeDeploymentSnippets_ReturnsBasicSnippetsW
require.Contains(t, snippets.DockerRun, "EDGE_TRANSPORT=poll")
require.Contains(t, snippets.DockerCompose, "MANAGER_API_URL=https://manager.example.com")
}
+
+func TestEnvironmentService_PairAgentWithBootstrap_RejectsInvalidURL(t *testing.T) {
+ svc := NewEnvironmentService(nil, nil, nil, nil, nil, nil)
+
+ _, err := svc.PairAgentWithBootstrap(context.Background(), "ftp://example.com", "bootstrap-token")
+ require.Error(t, err)
+ require.Contains(t, err.Error(), "invalid agent API URL")
+}
+
+func TestEnvironmentService_TestConnection_RejectsInvalidCustomURL(t *testing.T) {
+ ctx := context.Background()
+ db := setupEnvironmentServiceTestDB(t)
+ svc := NewEnvironmentService(db, nil, nil, nil, nil, nil)
+
+ createTestEnvironment(t, db, "env-1", "http://example.com", nil)
+ customURL := "ftp://example.com"
+
+ status, err := svc.TestConnection(ctx, "env-1", &customURL)
+ require.Error(t, err)
+ require.Equal(t, "offline", status)
+ require.Contains(t, err.Error(), "invalid environment API URL")
+}
+
+func TestEnvironmentService_ExecuteRemoteRequest_RejectsInvalidEnvironmentURL(t *testing.T) {
+ ctx := context.Background()
+ db := setupEnvironmentServiceTestDB(t)
+ svc := NewEnvironmentService(db, nil, nil, nil, nil, nil)
+
+ createTestEnvironment(t, db, "env-invalid-url", "http://user:[email protected]", nil)
+
+ _, err := svc.ExecuteRemoteRequest(ctx, "env-invalid-url", http.MethodGet, "/api/health", nil)
+ require.Error(t, err)
+ require.Contains(t, err.Error(), "invalid environment API URL")
+}
diff --git a/backend/pkg/utils/httpx/outbound_url.go b/backend/pkg/utils/httpx/outbound_url.go
new file mode 100644
index 000000000..cec77efd7
--- /dev/null
+++ b/backend/pkg/utils/httpx/outbound_url.go
@@ -0,0 +1,38 @@
+package httpx
+
+import (
+ "fmt"
+ "net/url"
+ "strings"
+)
+
+// ValidateOutboundHTTPURL parses and validates an outbound HTTP(S) target URL.
+// It intentionally performs syntactic hardening (scheme/host/credentials)
+// without restricting private network ranges, because environment agents may be
+// deployed on trusted private subnets.
+func ValidateOutboundHTTPURL(rawURL string) (*url.URL, error) {
+ trimmed := strings.TrimSpace(rawURL)
+ if trimmed == "" {
+ return nil, fmt.Errorf("URL is required")
+ }
+
+ parsed, err := url.Parse(trimmed)
+ if err != nil {
+ return nil, fmt.Errorf("failed to parse URL: %w", err)
+ }
+
+ scheme := strings.ToLower(parsed.Scheme)
+ if scheme != "http" && scheme != "https" {
+ return nil, fmt.Errorf("unsupported scheme %q", parsed.Scheme)
+ }
+
+ if parsed.User != nil {
+ return nil, fmt.Errorf("embedded credentials are not allowed")
+ }
+
+ if parsed.Host == "" || parsed.Hostname() == "" {
+ return nil, fmt.Errorf("URL host is required")
+ }
+
+ return parsed, nil
+}
diff --git a/backend/pkg/utils/httpx/outbound_url_test.go b/backend/pkg/utils/httpx/outbound_url_test.go
new file mode 100644
index 000000000..88867c8b5
--- /dev/null
+++ b/backend/pkg/utils/httpx/outbound_url_test.go
@@ -0,0 +1,36 @@
+package httpx
+
+import (
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestValidateOutboundHTTPURL(t *testing.T) {
+ tests := []struct {
+ name string
+ rawURL string
+ wantErr bool
+ }{
+ {name: "allow https URL", rawURL: "https://example.com/api/health"},
+ {name: "allow private network URL", rawURL: "http://10.0.0.5:3553/api/health"},
+ {name: "reject empty URL", rawURL: "", wantErr: true},
+ {name: "reject unsupported scheme", rawURL: "ftp://example.com", wantErr: true},
+ {name: "reject missing host", rawURL: "https:///api/health", wantErr: true},
+ {name: "reject embedded credentials", rawURL: "https://user:[email protected]/api/health", wantErr: true},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ parsed, err := ValidateOutboundHTTPURL(tt.rawURL)
+ if tt.wantErr {
+ require.Error(t, err)
+ require.Nil(t, parsed)
+ return
+ }
+
+ require.NoError(t, err)
+ require.NotNil(t, parsed)
+ })
+ }
+}