Documentation
¶
Overview ¶
Package apihttp holds HTTP helpers shared by every version of the public API (pkg/api/v1, ...). It is intentionally a leaf package with no dependencies on pkg/api so version subpackages can import it without creating an import cycle through the top-level router.
Index ¶
- Constants
- func BearerToken(r *http.Request) string
- func CallerCan(ctx context.Context, p controlplane.Permission) bool
- func CorrelationID(r *http.Request) string
- func DecodeAndBufferJSON(w http.ResponseWriter, r *http.Request, dst any) ([]byte, error)
- func DecodeJSON(w http.ResponseWriter, r *http.Request, dst any) error
- func DecodeJSONLimit(w http.ResponseWriter, r *http.Request, dst any, maxBytes int64) error
- func IncludeEnvRequested(r *http.Request) bool
- func PreAuth(outer http.Handler, route http.Handler) http.Handler
- func ReadJSONBody(w http.ResponseWriter, r *http.Request) ([]byte, error)
- func ReadOrSecrets(r *http.Request) controlplane.Permission
- func WriteError(w http.ResponseWriter, status int, message string)
- func WriteErrorCode(w http.ResponseWriter, status int, code, message string)
- func WriteForbidden(w http.ResponseWriter, _ *http.Request, d Denial)
- func WriteJSON(w http.ResponseWriter, status int, value any)
- func WriteStoreAwareError(logger *slog.Logger, w http.ResponseWriter, err error)
- type AuditHook
- type Classification
- type Denial
- type DenyWriter
- type ErrKind
- type Mux
- type RouteCall
- type RouteHandler
- type Router
Constants ¶
const MaxJSONBodyBytes = 1 << 20 // 1 MiB
MaxJSONBodyBytes caps JSON request bodies decoded via DecodeJSON. Control requests are small (a create payload with env vars is well under 64 KiB); the cap exists so an authed caller can't balloon daemon memory with a multi-GiB body. Bulk payloads (file uploads, build contexts) stream through dedicated handlers and don't go through DecodeJSON.
const OperatorRequiredMessage = "operator authorization required"
OperatorRequiredMessage is the 403 text the PAT-era operator gate wrote for a fleet route. Managed callers still get exactly this body (L8).
const ReadOrSecretsTag = string(controlplane.PermSandboxRead) + "|" + string(controlplane.PermSandboxSecrets) + " with include_env"
ReadOrSecretsTag is the registry tag of a ReadOrSecrets route.
Variables ¶
This section is empty.
Functions ¶
func BearerToken ¶ added in v0.6.8
BearerToken returns the caller's credential from the Authorization header or, failing that, the WebSocket subprotocol. It is the ONE extraction used both by the API's authenticate and by remote MCP's tool runner, so the token that authenticated a request is always the token the MCP tools act with (plans/identity-and-access.md eng review D5). Two drifted copies used to live in pkg/api/middleware.go and pkg/api/remotemcp/handler.go.
- Authorization: the scheme matches case-insensitively (RFC 7235 §2.1), so "Bearer", "bearer" and "BEARER" are all accepted; surrounding whitespace is trimmed from the header and from the token.
- An Authorization header with any other scheme, or with an empty bearer, falls through to the subprotocol.
- Sec-WebSocket-Protocol: the first entry that is neither empty nor the sandbox.bearer marker, across every header value.
X-API-KEY is NOT read here: only the E2B surface accepts it, and it falls back to that header itself when this returns "".
func CallerCan ¶ added in v0.6.8
func CallerCan(ctx context.Context, p controlplane.Permission) bool
CallerCan reports whether the request's caller holds p, for a handler that trims a response by permission rather than refusing it (E2B's envd token). No Access is an internal or in-process call, which holds everything.
func CorrelationID ¶ added in v0.6.8
CorrelationID returns the caller's correlation id: X-Correlation-ID, else X-Request-ID, else "". A forwarded request carries the edge's id in X-Correlation-ID (cluster.StampForward), so the owner node reads the same id the edge recorded.
func DecodeAndBufferJSON ¶ added in v0.6.7
DecodeAndBufferJSON reads the request body (bounded), decodes it into dst with the same single-value strictness as DecodeJSON, and restores r.Body to the original bytes. A create handler uses it so that when clustercreate forwards the request to the placement target, the target re-reads the full body instead of an empty one (plan B2). Returns the raw bytes.
func DecodeJSON ¶ added in v0.5.3
DecodeJSON decodes a JSON request body into dst with the body capped at MaxJSONBodyBytes. All versioned handlers must use this instead of json.NewDecoder(r.Body) directly so the size cap is uniform across v1 and the facades. The caller writes its own error envelope on failure.
func DecodeJSONLimit ¶ added in v0.6.1
DecodeJSONLimit decodes a JSON request using an endpoint-specific maximum. Keep exceptional limits at the handler so the shared public API default does not grow merely because one internal wire format contains base64 expansion.
func IncludeEnvRequested ¶ added in v0.6.8
IncludeEnvRequested reports whether the request asked for the sandbox env (include_env=true|1|yes, case-insensitive), the audited secret read.
func PreAuth ¶ added in v0.6.8
PreAuth registers a handler that runs checks of its own before handing the request to a Route-built handler, as remote MCP's origin and host checks do. outer must serve every request it accepts through route; the registry test follows Unwrap to route to find its permission.
func ReadJSONBody ¶ added in v0.6.1
ReadJSONBody applies the same cap for cluster wrappers that must buffer and replay a request before choosing a local or peer handler.
func ReadOrSecrets ¶ added in v0.6.8
func ReadOrSecrets(r *http.Request) controlplane.Permission
ReadOrSecrets is the RouteBy classifier of a sandbox read that can return env: sandbox.secrets with include_env, sandbox.read otherwise.
func WriteError ¶
func WriteError(w http.ResponseWriter, status int, message string)
WriteError writes an error envelope using models.ErrorResponse so all API versions return errors in the same shape.
func WriteErrorCode ¶ added in v0.6.1
func WriteErrorCode(w http.ResponseWriter, status int, code, message string)
WriteErrorCode is WriteError with a stable machine-readable code for errors a client is expected to act on (see models.ErrorCode*).
func WriteForbidden ¶ added in v0.6.8
func WriteForbidden(w http.ResponseWriter, _ *http.Request, d Denial)
WriteForbidden is the v1 403 (also the dashboard's and /mcp's). A token or OIDC caller's body adds required_permission and role next to the hint (D9); every other caller gets the plain {"error": …} body it always had.
func WriteJSON ¶
func WriteJSON(w http.ResponseWriter, status int, value any)
WriteJSON serializes value as JSON and writes it with the given status.
func WriteStoreAwareError ¶
func WriteStoreAwareError(logger *slog.Logger, w http.ResponseWriter, err error)
WriteStoreAwareError maps the small set of well-known service-layer error kinds to HTTP responses. The mapping (404 for missing sandboxes, 503 for capacity/topology admission failures, 400 for everything else) is a contract clients depend on regardless of API version, so it lives here in the shared helper package.
Types ¶
type AuditHook ¶ added in v0.6.8
AuditHook is the seam task T5 fills with kind "api" chain records (§5.9). When set, Route hands it every request after authorization: an allowed call with next, which the hook must serve (so it can tee the body and record the final status); a refused call with next nil, after its 403 is written. nil (T2) records nothing and serves next directly.
type Classification ¶ added in v0.6.7
type Classification struct {
Status int
Code string // models.ErrorResponse.Code; "" when none
Message string // canonical message, already truncated
RetryAfter int // seconds; 0 = no Retry-After header
Kind ErrKind
LogLevel slog.Level
Log bool // emit LogLevel with the error; false = no log line
}
Classification is one service error's HTTP rendering, independent of which surface serves it: the single source of truth every facade's error writer shares (plan D1). A facade turns it into its own envelope shape and adds any envelope-specific header (Runloop's x-should-retry), but never decides the status, the Retry-After or whether to log.
func Classify ¶ added in v0.6.7
func Classify(err error) Classification
Classify maps a service-layer error to its HTTP rendering. The mapping is the one that used to live inline in WriteStoreAwareError; it now has one home so v1, Daytona, E2B and Runloop cannot drift (plan D1).
func (Classification) Apply ¶ added in v0.6.7
func (c Classification) Apply(logger *slog.Logger, err error)
Apply sets the Retry-After header and emits the classification's log line.
func (Classification) SetRetryAfter ¶ added in v0.6.7
func (c Classification) SetRetryAfter(w http.ResponseWriter)
type Denial ¶ added in v0.6.8
type Denial struct {
Permission controlplane.Permission
Access controlplane.Access
}
Denial is one refused authorization, handed to the surface's 403 writer.
func (Denial) Hint ¶ added in v0.6.8
Hint is the D9 hint for a token or OIDC caller ("role viewer on team payments cannot sandbox.exec; ask an admin for role runner on team payments") and "" for everyone else.
func (Denial) Message ¶ added in v0.6.8
Message is the 403 text every surface writes: the hint for a token or OIDC caller, otherwise the text that caller already got before roles existed. Every route that is not a team verb was behind the operator gate, so a managed caller keeps "operator authorization required" there byte for byte; a team verb a managed viewer lacks (new with T1's managed roles) names the permission.
type DenyWriter ¶ added in v0.6.8
type DenyWriter func(w http.ResponseWriter, r *http.Request, d Denial)
DenyWriter writes one surface's 403 for d, in that surface's body shape.
type ErrKind ¶ added in v0.6.7
type ErrKind int
ErrKind names the few service errors a facade words differently for its own SDK (otherwise it uses Classification.Message verbatim). Every other error is ErrKindOther.
const ( ErrKindOther ErrKind = iota ErrKindNotFound ErrKindSandboxNameConflict ErrKindSnapshotNameConflict ErrKindSandboxExists // ErrKindSandboxNotRunning / ErrKindSandboxNotResumable are the two // lifecycle-precondition 409s (pause a non-running sandbox, resume a // non-stopped one); a facade words them for its own SDK ("devbox is not // running" vs "Sandbox is not running"). ErrKindSandboxNotRunning ErrKindSandboxNotResumable // ErrKindUnclassified is the catch-all 400: an error no sentinel matched. // A facade may keep its own default wording for it. ErrKindUnclassified )
type Mux ¶ added in v0.6.8
Mux is where an API package mounts its routes. *http.ServeMux satisfies it; the registry test passes a recording one.
type RouteCall ¶ added in v0.6.8
type RouteCall struct {
Permission controlplane.Permission
// Access is the authenticated caller; HasAccess is false only for a
// Router built without an authenticator (unit tests).
Access controlplane.Access
HasAccess bool
// Allowed is false for a refused call; its 403 is already written.
Allowed bool
}
RouteCall is what the audit seam learns about one request Route decided.
type RouteHandler ¶ added in v0.6.8
type RouteHandler struct {
// contains filtered or unexported fields
}
RouteHandler is the handler Route returns. It carries its permission so the registry test can tell a tagged route from a bare one.
func RouteOf ¶ added in v0.6.8
func RouteOf(h http.Handler) (*RouteHandler, bool)
RouteOf finds the RouteHandler h was built from, following PreAuth.
func (*RouteHandler) Authenticates ¶ added in v0.6.8
func (h *RouteHandler) Authenticates() bool
Authenticates reports whether the route authenticates before authorizing.
func (*RouteHandler) PermissionFor ¶ added in v0.6.8
func (h *RouteHandler) PermissionFor(r *http.Request) controlplane.Permission
PermissionFor returns the permission r needs on this route.
func (*RouteHandler) PermissionTag ¶ added in v0.6.8
func (h *RouteHandler) PermissionTag() string
PermissionTag is the permission (or, for RouteBy, the rule) the route was registered with.
func (*RouteHandler) ServeHTTP ¶ added in v0.6.8
func (h *RouteHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
type Router ¶ added in v0.6.8
type Router struct {
// Authenticate is the surface's auth middleware (pkg/api withAuth). It
// attaches the caller's Access or refuses with 401. nil only in unit
// tests; the registry test pins that every production route has one.
Authenticate func(http.Handler) http.Handler
// Deny writes the surface's 403. nil means WriteForbidden (v1 shape).
Deny DenyWriter
// Audit is the T5 seam (AuditHook).
Audit AuditHook
}
Router builds the handler for every API route of one surface.
func (Router) Route ¶ added in v0.6.8
func (rt Router) Route(perm controlplane.Permission, next http.Handler) http.Handler
Route returns next behind authenticate → authorize(perm) → audit seam.
func (Router) RouteBy ¶ added in v0.6.8
func (rt Router) RouteBy(tag string, classify func(*http.Request) controlplane.Permission, next http.Handler) http.Handler
RouteBy is Route for a route whose permission depends on the request: GET /v1/sandboxes/{id} needs sandbox.secrets only with include_env, and the Runloop facade dispatches many verbs below one mux pattern. tag describes the rule for the registry test and reviewers ("sandbox.read|sandbox.secrets"). classify must return a permission for every request; an unknown path should get the strictest team verb, never authenticated.