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?".
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 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.