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 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 ReadJSONBody(w http.ResponseWriter, r *http.Request) ([]byte, error)
- func RequireOperator(next http.Handler) http.Handler
- func WriteError(w http.ResponseWriter, status int, message string)
- func WriteErrorCode(w http.ResponseWriter, status int, code, message string)
- func WriteJSON(w http.ResponseWriter, status int, value any)
- func WriteStoreAwareError(logger *slog.Logger, w http.ResponseWriter, err error)
- type Classification
- type ErrKind
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.
Variables ¶
This section is empty.
Functions ¶
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 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 RequireOperator ¶ added in v0.6.7
RequireOperator rejects a caller that is not an operator with 403. It sits inside an auth middleware, which marks PAT and cluster-peer calls as the operator; a user token authenticates but is scoped to its account, so it never reaches what this wraps: fleet-wide and cluster-internal routes.
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 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 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 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 )