apihttp

package
v0.6.7 Latest Latest
Warning

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

Go to latest
Published: Oct 16, 2026 License: MIT Imports: 15 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.

Variables

This section is empty.

Functions

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 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 RequireOperator added in v0.6.7

func RequireOperator(next http.Handler) http.Handler

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
)

Jump to

Keyboard shortcuts

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