apihttp

package
v0.6.13 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 28 Imported by: 0

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

View Source
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.

View Source
const OperatorFlow = "operator"

OperatorFlow is the flow of every unscoped caller: the operator PAT, a fleet-wide token or binding, and a call that carries no Access (internal). They all act for the operator and list under owner "", so they share one share of the node, like one tenant.

View Source
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).

View Source
const OverloadedRetryAfterSeconds = 1

OverloadedRetryAfterSeconds is the Retry-After sent with ErrOverloaded. A slot frees as soon as one request in flight ends, usually well inside a second, so a short hint is enough; every SDK also backs off on its own.

View Source
const RateLimitedRetryAfterSeconds = 1

RateLimitedRetryAfterSeconds is the Retry-After sent with ErrRateLimited: the tenant's own slot frees as soon as one of its requests ends.

View Source
const ReadOrSecretsTag = string(controlplane.PermSandboxRead) + "|" + string(controlplane.PermSandboxSecrets) + " with include_env"

ReadOrSecretsTag is the registry tag of a ReadOrSecrets route.

Variables

View Source
var ErrOverloaded = errors.New("this node is serving as many cluster list requests as it is configured to; retry shortly")

ErrOverloaded is load shedding: this node already runs as many requests of one expensive kind as it is configured to, the caller's tenant is within its share, and a short wait freed no slot. It is answered at once with 503 and Retry-After (Classify) instead of being queued behind the others. On the bank flagship (2026-11-01) queued cluster lists reached a 37 s p99 and ended in 502s from a restarted node; a fast, retryable refusal keeps the node, and every request it is already serving, alive.

View Source
var ErrRateLimited = errors.New("your tenant is running as many cluster list requests on this node as its share allows; retry shortly")

ErrRateLimited is the per-tenant half of the same gate: the caller's own tenant already holds its share of the node's slots, and none of them freed within the queue wait. Answered 429 with Retry-After and code rate_limited (Classify), so the noisy tenant learns it is the one to slow down, while every other tenant keeps its own share of the node.

Functions

func BearerToken added in v0.6.8

func BearerToken(r *http.Request) string

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

func CorrelationID(r *http.Request) string

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

func DecodeAndBufferJSON(w http.ResponseWriter, r *http.Request, dst any) ([]byte, error)

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

func DecodeJSON(w http.ResponseWriter, r *http.Request, dst any) error

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

func DecodeJSONLimit(w http.ResponseWriter, r *http.Request, dst any, maxBytes int64) error

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 FlowOf added in v0.6.9

func FlowOf(ctx context.Context) string

FlowOf names the fairness flow a request belongs to: the tenant (owner) its credential acts for, never the credential itself, so a tenant that mints a hundred tokens still gets one share. A team token, an OIDC identity acting for a team and a managed account map to "owner:<owner ref>"; unscoped callers to OperatorFlow. The "owner:" prefix keeps a managed account literally named "operator" out of the operator's flow.

func IncludeEnvRequested added in v0.6.8

func IncludeEnvRequested(r *http.Request) bool

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

func PreAuth(outer http.Handler, route http.Handler) http.Handler

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

func ReadJSONBody(w http.ResponseWriter, r *http.Request) ([]byte, error)

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

type AuditHook func(w http.ResponseWriter, r *http.Request, call RouteCall, next http.Handler)

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

func (d Denial) Hint() string

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

func (d Denial) Message() string

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 Gate added in v0.6.9

type Gate struct {
	// contains filtered or unexported fields
}

Gate bounds how many requests of one expensive kind run at once on this node, and how many of them one flow (tenant, FlowOf) may hold.

A request that finds a free slot within its flow's share takes it at once. Otherwise it queues in its flow's FIFO for at most the gate's queue wait. A freed slot goes to the flows with waiters in round-robin order, skipping a flow that already holds its share, so a tenant with 100 requests queued and one with 1 queued each get the next turn in step, not first-come first-served across everyone. A waiter that times out is refused with ErrRateLimited when its own flow holds its share (that tenant is the one to slow down), else with ErrOverloaded (the node is full).

Refusals happen only after the queue wait, never at once (unless the wait is 0): a client that ignores Retry-After then costs at most two requests a second per connection, where an instant refusal would invite a tight retry loop that spends the node's CPU on refusals.

Cost per decision is O(1), plus O(flows with waiters) when a release scans for the next eligible flow. State exists only for a flow with a request in flight or queued and is dropped the moment it has neither, so memory is bounded by the requests the server is already holding. A nil *Gate admits everything.

func NewGate added in v0.6.9

func NewGate(limit, perFlow int, wait time.Duration, metrics GateMetrics) *Gate

NewGate returns a gate of limit slots, of which one flow may hold at most perFlow. limit <= 0 means no gate (nil); perFlow <= 0 or >= limit means no per-flow share (any flow may take every slot), with round-robin turns across flows still in force.

func (*Gate) Acquire added in v0.6.9

func (g *Gate) Acquire(ctx context.Context) (release func(), err error)

Acquire takes a slot for the request's flow (FlowOf(ctx)).

func (*Gate) AcquireFlow added in v0.6.9

func (g *Gate) AcquireFlow(ctx context.Context, flow string) (release func(), err error)

AcquireFlow takes a slot for flow. On success release must be called once (more is safe). It returns ErrRateLimited or ErrOverloaded when no slot freed for this flow within the queue wait, and ErrOverloaded wrapping the context's error when the caller left while waiting (not counted as a refusal: the writer answers it silently, for a client that is gone).

func (*Gate) Limit added in v0.6.9

func (g *Gate) Limit() int

Limit is the number of slots; 0 for a nil gate.

func (*Gate) PerFlowLimit added in v0.6.9

func (g *Gate) PerFlowLimit() int

PerFlowLimit is how many slots one flow may hold (Limit when no share is in force); 0 for a nil gate.

func (*Gate) Snapshot added in v0.6.9

func (g *Gate) Snapshot(top int) GateSnapshot

Snapshot returns the gate's totals and its top busiest flows: most refused first, then most queued, then most in flight. The zero snapshot for a nil gate.

type GateFlowSnapshot added in v0.6.9

type GateFlowSnapshot struct {
	Flow     string `json:"flow"`
	InFlight int    `json:"in_flight"`
	Queued   int    `json:"queued"`
	// Refused counts this flow's 429s and 503s since its state was created,
	// which is since the flow last had nothing in flight or queued.
	Refused int64 `json:"refused"`
}

GateFlowSnapshot is one flow's state at the moment of a Snapshot.

type GateMetrics added in v0.6.9

type GateMetrics struct {
	InFlight    *expvar.Int // requests holding a slot now
	Admitted    *expvar.Int // requests that got a slot
	Shed        *expvar.Int // refused 503: the node was full, the flow within its share
	RateLimited *expvar.Int // refused 429: the flow already held its share
	Queued      *expvar.Int // requests waiting for a slot now
	Flows       *expvar.Int // flows (tenants) holding or waiting for a slot now
}

GateMetrics are a Gate's counters and gauges. Any of them may be nil. None is labelled by tenant: a flow's name is in Snapshot (the operator-only /debug/vars), never in a metric, so the series count stays fixed however many tenants call.

type GateSnapshot added in v0.6.9

type GateSnapshot struct {
	Limit        int                `json:"limit"`
	PerFlowLimit int                `json:"per_tenant_limit"`
	QueueWaitMS  int64              `json:"queue_wait_ms"`
	InFlight     int                `json:"in_flight"`
	Queued       int                `json:"queued"`
	Flows        int                `json:"tenants"`
	Busiest      []GateFlowSnapshot `json:"busiest"`
}

GateSnapshot is the gate's state for an operator chasing a noisy tenant: the totals and the busiest flows by name. It is for /debug/vars (fleet admin only), never a metric: flow names would be unbounded labels.

type Mux added in v0.6.8

type Mux interface {
	Handle(pattern string, handler http.Handler)
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL