v1

package
v0.6.13 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 34 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 apihttp.Mux, 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, 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

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

func (Deps) RouteBy added in v0.6.8

func (d Deps) RouteBy(tag string, classify func(*http.Request) controlplane.Permission, h http.Handler) http.Handler

RouteBy is Route for a route whose permission depends on the request.

Jump to

Keyboard shortcuts

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