Documentation
¶
Overview ¶
Package api wires the top-level HTTP server. It is intentionally thin — per-version routing lives in subpackages (pkg/api/v1, ...) and shared HTTP helpers live in pkg/api/apihttp. This file's job is:
- construct the *Server with its dependencies,
- mount unversioned routes (/health),
- delegate /v1/... (and any future version) to that version's RegisterRoutes function.
To add a new version: create pkg/api/vN mirroring pkg/api/v1, then add a single vN.RegisterRoutes(...) call below. Versions coexist on the same mux without modifying each other.
Index ¶
Constants ¶
const HeaderClientIP = "X-AerolVM-Client-IP"
HeaderClientIP is the client address Caddy sets on every request it proxies to sandboxd (`header_up X-AerolVM-Client-IP {remote_host}`, written by install.sh with the PROXY-protocol wrapper). Caddy overwrites whatever the client sent, so it is the peer Caddy saw, never a client claim; sandboxd never reads X-Forwarded-For.
const HeaderTeam = cluster.HeaderTeam
HeaderTeam selects which of a credential's teams a request acts for (CEO review D13). It is an ordinary header: a reverse-proxied forward keeps it, a fan-out request gets it from cluster.StampForward, and the owner node applies the same selection offline.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Authenticator ¶ added in v0.6.8
type Authenticator interface {
Authenticate(r *http.Request, bearer string) (controlplane.Access, bool, error)
}
Authenticator recognises one credential kind. matched=false means "not mine": the next authenticator gets the credential. matched=true decides the request: err refuses it, otherwise the Access is the caller. The first match wins, so no later authenticator ever sees a credential an earlier one claimed. Task T3 (avm_ tokens) and T6 (OIDC) each add one with WithCredentialAuthenticator; nothing else changes.
A named-credential authenticator refuses with *controlplane.CredentialError to give the caller a D17 reason. Any other error is a bare 401.
type MCPResource ¶ added in v0.6.8
MCPResource is what the identity file says about /mcp: its protected- resource URL (mcp.resource), the issuers that set mcp: true, and the scopes a connector should ask for. A zero Resource means none is configured: no metadata, no challenge.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
func NewServer ¶
func NewServer(logger *slog.Logger, service *service.Service, dockerClient *docker.Client, builder service.ImageBuilder, cfg config.Config, patToken string, validator controlplane.Validator, opts ...ServerOption) *Server
NewServer constructs the API server. validator is the second-token (non-PAT) validation path; pass controlplane.Noop().Validator (or any rejecting validator) for the open-source PAT-only behavior. A nil validator is treated as reject-all so callers can't accidentally open the door by omission. opts adds named-credential authenticators (WithCredentialAuthenticator), which take effect only with cfg.IdentityEnabled.
builder is the image builder the service builds with (every surface's builds go through service.BuildImage). On the dockerd engine this is the *docker.Client; on the containerd engine the daemon passes a buildkit-backed builder. A nil builder falls back to dockerClient so existing docker-only callers are unaffected; when both are nil the build endpoints return 503 (builder not configured).
func (*Server) PublicHandler ¶ added in v0.6.8
PublicHandler is the API handler for the public Unix socket (SB_PUBLIC_API_SOCKET) Caddy uses under SB_PAT_SCOPE=host. Every request on it is public, whatever its RemoteAddr says, so a PAT there is refused. The mark rides the request context, which no client can set.
func (*Server) StartBackground ¶ added in v0.6.9
StartBackground starts the server's background work, which runs until ctx ends or StopBackground is called: the loop that writes the auth_denied records owed for folded 401s. It starts nothing when api records are off. Call it once, before serving.
func (*Server) StopBackground ¶ added in v0.6.9
func (s *Server) StopBackground()
StopBackground ends the background work, then writes every auth_denied record still owed, window closed or not. Call it after the HTTP listeners have drained, so 401s folded during the drain are written too, and before the audit writer closes. Safe to call twice, and without StartBackground.
type ServerOption ¶ added in v0.6.8
type ServerOption func(*serverOptions)
ServerOption configures NewServer.
func WithAuthDiscovery ¶ added in v0.6.8
func WithAuthDiscovery(issuers func() []identitywire.DiscoveryIssuer) ServerOption
WithAuthDiscovery supplies the issuers GET /.well-known/aerolvm-auth publishes, read at each request so a reloaded identity file shows at once. The daemon passes the identity-file watcher's issuers; without it (or with identity off) the document lists none.
func WithCredentialAuthenticator ¶ added in v0.6.8
func WithCredentialAuthenticator(kind controlplane.PrincipalKind, a Authenticator) ServerOption
WithCredentialAuthenticator adds a named-credential authenticator: the avm_ token mirror (T3, kind controlplane.PrincipalToken) or the OIDC verifier (T6, kind controlplane.PrincipalOIDC). They run after the PAT and before the managed provider, in the order the options are given.
They run only when SB_IDENTITY_ENABLED=true. With identity off NewServer drops them, so a bearer that looks like an avm_ token or a JWT still reaches the managed provider exactly as before (L8). The daemon refuses to boot with identity on and a non-noop provider Validator, so the two never compete.
func WithMCPResource ¶ added in v0.6.8
func WithMCPResource(resource func() MCPResource) ServerOption
WithMCPResource supplies the identity file's /mcp resource, read at each request so a reloaded file shows at once. The daemon passes the identity- file watcher's; NewServer drops it with identity off (L8), and the metadata routes exist only with remote MCP on as well.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package apihttp holds HTTP helpers shared by every version of the public API (pkg/api/v1, ...).
|
Package apihttp holds HTTP helpers shared by every version of the public API (pkg/api/v1, ...). |
|
Package clusterlist aggregates sandbox list reads across cluster owners.
|
Package clusterlist aggregates sandbox list reads across cluster owners. |
|
Package clusterroute holds the one cluster owner-forwarding wrapper every API surface shares.
|
Package clusterroute holds the one cluster owner-forwarding wrapper every API surface shares. |
|
Package ingressproxy implements the loopback HTTP listener that fronts wake-aware Caddy port routes.
|
Package ingressproxy implements the loopback HTTP listener that fronts wake-aware Caddy port routes. |
|
Package remotemcp serves the AerolVM MCP tools over Streamable HTTP at /mcp on sandboxd (plans/mcp-server-and-agent-cli.md §5.7, Phase 2b).
|
Package remotemcp serves the AerolVM MCP tools over Streamable HTTP at /mcp on sandboxd (plans/mcp-server-and-agent-cli.md §5.7, Phase 2b). |
|
Package runloop is a compatibility facade for the official Runloop SDKs (@runloop/api-client, runloop_api_client).
|
Package runloop is a compatibility facade for the official Runloop SDKs (@runloop/api-client, runloop_api_client). |
|
Package v1 implements the v1 HTTP API for the sandbox daemon.
|
Package v1 implements the v1 HTTP API for the sandbox daemon. |