v1

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: 30 Imported by: 0

Documentation

Overview

Package v1 implements the v1 HTTP API for the sandbox daemon.

All v1 routes are registered under PathPrefix ("/v1") via RegisterRoutes. The package owns its wire contract: handlers in this package are the only code allowed to decode request bodies or shape response bodies for v1.

Versioning rules (soft freeze, see pr-review.md):

  • Behavioral changes to v1 wire bodies, status codes, or paths are forbidden once shipped. Add a new version package (pkg/api/vN) instead.
  • Bug and security fixes that preserve wire compatibility are allowed.

The service layer (internal/service) stays version-agnostic. v1 handlers translate v1 DTOs ↔ models.* and call into the shared service.

Index

Constants

View Source
const (

	// ClusterListRetryAfterSeconds is the Retry-After for a shed list.
	ClusterListRetryAfterSeconds = 2
)
View Source
const PathPrefix = "/v1"

PathPrefix is the URL prefix every v1 route is registered under. Keep this in sync with the v1 SDK clients (each SDK pins the same prefix in its internal/api/v1 module).

Variables

View Source
var ErrClusterListBusy = errors.New("cluster catalogue list is busy; retry shortly")

ErrClusterListBusy is returned when every sweep slot is taken. It is a backpressure signal, not a failure: the caller retries and usually lands on a warm cache entry left by the sweep that was already running.

Functions

func RegisterRoutes

func RegisterRoutes(mux *http.ServeMux, d Deps)

RegisterRoutes mounts every v1 route onto mux. Paths are written with the PathPrefix already baked in so this file is the single grep target for "what does v1 expose?".

Types

type AuditRateLimiter added in v0.6.1

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

AuditRateLimiter bounds GET /v1/sandboxes/{id}/audit fan-out amplification. Per-identity (OwnerRef; operator PAT → "operator") plus a per-node ceiling. On reject: 429 + Retry-After — never silent truncation.

func NewAuditRateLimiter added in v0.6.1

func NewAuditRateLimiter(cfg AuditRateLimiterConfig) *AuditRateLimiter

NewAuditRateLimiter builds limiters with the decided defaults when rates are zero/negative.

func (*AuditRateLimiter) Middleware added in v0.6.1

func (a *AuditRateLimiter) Middleware(next http.Handler) http.Handler

Middleware wraps only the public audit route.

func (*AuditRateLimiter) PeerMiddleware added in v0.6.1

func (a *AuditRateLimiter) PeerMiddleware(next http.Handler) http.Handler

PeerMiddleware wraps the cluster-internal audit slice endpoint. Peers are authenticated nodes, not tenants, so only the per-node peer bucket applies. Before this, one public request could amplify into unmetered full reads on every evidence node; the public limiter never saw those.

type AuditRateLimiterConfig added in v0.6.1

type AuditRateLimiterConfig struct {
	IdentityRate float64
	OperatorRate float64
	NodeRate     float64
}

AuditRateLimiterConfig holds token-bucket rates from config.

type Deps

type Deps struct {
	Service *service.Service
	Logger  *slog.Logger
	// Auth wraps each handler with bearer-token auth. The middleware lives in
	// pkg/api so all versions share one auth contract; the version package
	// only decides which routes need it.
	Auth func(http.Handler) http.Handler
	// AuditLimiter rate-limits GET /v1/sandboxes/{id}/audit only (E1b
	// amplification bound). Nil disables limiting (tests).
	AuditLimiter *AuditRateLimiter
	// ContainerEngine is the host engine (docker|containerd). Used for
	// Server-Timing engine tags and BuildKit-absent clear errors.
	ContainerEngine string
}

Deps holds the shared dependencies a version package needs from the top-level pkg/api router. Keeping these explicit (rather than reaching into pkg/api globals) lets future version packages coexist without coupling.

Jump to

Keyboard shortcuts

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