api

package
v0.6.9 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 48 Imported by: 0

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:

  1. construct the *Server with its dependencies,
  2. mount unversioned routes (/health),
  3. 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

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

View Source
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

type MCPResource struct {
	Resource             string
	AuthorizationServers []string
	Scopes               []string
}

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) Handler

func (s *Server) Handler() http.Handler

func (*Server) PublicHandler added in v0.6.8

func (s *Server) PublicHandler() http.Handler

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

func (s *Server) StartBackground(ctx context.Context)

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.

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.

Jump to

Keyboard shortcuts

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