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 ¶
const (
// ClusterListRetryAfterSeconds is the Retry-After for a shed list.
ClusterListRetryAfterSeconds = 2
)
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 ¶
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 ¶
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, and which permission does each route need?".
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
AuditRateLimiterConfig holds token-bucket rates from config.
type Deps ¶
type Deps struct {
Service *service.Service
Logger *slog.Logger
// Auth authenticates a request: it attaches the caller's Access or
// refuses with 401. The middleware lives in pkg/api so all versions share
// one auth contract. Routes never call it directly: Route composes it
// with the permission check.
Auth func(http.Handler) http.Handler
// Audit is the seam task T5 fills with kind "api" records
// (apihttp.AuditHook). nil records nothing.
Audit apihttp.AuditHook
// 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
// ListGate bounds the cluster-wide lists this node runs at once
// (clusterlist.Admit); nil admits every list. One gate is shared by v1
// and every facade: they cost the same fan-out.
ListGate *apihttp.Gate
}
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.
func (Deps) Route ¶ added in v0.6.8
func (d Deps) Route(perm controlplane.Permission, h http.Handler) http.Handler
Route returns h behind authenticate → authorize(perm) → audit seam (plans/identity-and-access.md §5.3). Every v1 route is registered through it; the registry test fails on one that is not.