app

Documentation

Overview

Package app wires together the Aileron control plane components and exposes them as an http.Handler. It is imported by the standalone server binary.

Index

• func NewHandlerWithConfig(log *slog.Logger, cfg Config) (http.Handler, error)
• func RequestID(ctx context.Context) string
• type Config

Functions

func NewHandlerWithConfig

func NewHandlerWithConfig(log *slog.Logger, cfg Config) (http.Handler, error)

NewHandlerWithConfig is the configurable entry point. The launcher uses this with a passphrase-unlocked Vault; the standalone server binary uses NewHandler (dev-mode fallback).

func RequestID

func RequestID(ctx context.Context) string

RequestID returns the request ID from the context, or empty string if none.

Types

type Config

type Config struct {
	// Vault overrides the default in-memory random-KEK vault. Pass a
	// vault produced by [vault.Init] / [vault.Unlock] when the
	// runtime is being driven by `aileron launch`, so credentials
	// land in the user's encrypted file at ~/.aileron/secrets.json
	// rather than in a process-lifetime memory vault.
	Vault vault.Vault

	// WebappURL is the base URL of the Aileron webapp the user opens to
	// approve / deny gated actions (#418). When set, the action-approval
	// notification's ReviewURL is built as
	// `<WebappURL>/approvals?focus=<id>` so the terminal-printed block
	// carries a per-approval deep link the operator can click or
	// re-open via `aileron open approval <id>`.
	//
	// Empty falls back to the AILERON_WEBAPP_URL environment variable.
	// Both empty means notifications fire with a generic prompt
	// instead of a URL — the operator at least learns something needs
	// attention.
	//
	// Launch sets this to the embedded gateway's own URL so the
	// notification points at the same daemon the agent is talking to.
	// Once the daemon serves `ui/build` directly (post-MVP cleanup),
	// that URL becomes the working webapp entry point automatically.
	// Until then, users running the webapp dev server elsewhere can
	// override via AILERON_WEBAPP_URL.
	WebappURL string

	// Notifier overrides the default notification dispatcher (log +
	// terminal multi). Production wiring leaves this nil; tests inject
	// a recorder to observe the action-approval notification payload
	// without writing to stderr. The injected notifier replaces the
	// default — when set, no log / terminal notifications fire from
	// this handler, only the supplied notifier.
	Notifier notify.Notifier

	// LocalVaultPath, when set, runs the daemon with a deferred-unlock
	// local file vault (#429): NewHandlerWithConfig wraps the supplied
	// Vault in a [vault.LockableVault] and marks vaultLocked = true.
	// Vault-needing endpoints return 423 Locked until the user POSTs
	// their passphrase to /v1/vault/unlock — typically via the webapp
	// passphrase modal.
	//
	// Distinct from Vault: when LocalVaultPath is set, Vault is the
	// initial (locked) inner — usually nil, so the LockableVault
	// returns ErrCredentialUnavailable on credential reads until
	// unlock. Setting Vault to a pre-unlocked vault while also
	// setting LocalVaultPath is supported (`vaultLocked` stays false)
	// for tests that want to drive the UnlockLocalVault handler
	// without provisioning a real vault file.
	LocalVaultPath string

	// ActionApprovals overrides the default in-process action-
	// approval queue. Production wiring under `aileron launch`
	// passes a shared queue here so the embedded gateway *and* the
	// CommsServer (which fields `aileron-mcp`'s send-shaped tool
	// calls per #428) register their pending entries on the same
	// queue — one webapp surface, one SSE stream, one decision path.
	// Nil falls back to a fresh queue, preserving the historic
	// behaviour for callers that don't need cross-component sharing.
	ActionApprovals *approval.ActionApprovalQueue

	// Sessions is the persistent store for `aileron launch` session
	// records (ADR-0012). The daemon constructs a JSONL-backed store
	// pointed at ~/.aileron/sessions.jsonl and passes it here. Nil
	// disables the /v1/sessions endpoints — they return 503 — which
	// is the right behavior for cloud-shaped deployments and tests
	// that don't exercise the launch session surface.
	Sessions sessions.Store

	// NotifyQueue is the daemon-wide queue of incoming channel
	// messages (ADR-0012, step 9B-2). Populated by listener goroutines
	// after [OnVaultUnlock] resolves credentials; consumed by the
	// `/v1/sessions/{id}/comms/messages` endpoint that powers
	// `aileron-mcp`'s `read_messages` tool. Nil disables every comms
	// endpoint.
	NotifyQueue *comms.NotifyQueue

	// Listeners is the registry of active channel listeners keyed
	// by service name. Populated by the vault-unlock callback;
	// consumed by `/comms/send` and `/comms/draft` to dispatch
	// outbound messages after the user approves. Pair with
	// [NotifyQueue] — both nil or both set.
	Listeners *comms.ListenerRegistry

	// OnVaultUnlock fires after a successful POST /v1/vault/unlock,
	// stamped with the freshly-unlocked vault. The daemon registers
	// a callback here when channel listeners need credentials
	// resolved at unlock time. Nil is fine for tests / cloud
	// daemons that have nothing to do on unlock.
	//
	// Synchronous from the perspective of the unlock handler — the
	// HTTP response holds open until the callback returns. Listener
	// startup itself is fire-and-forget inside the callback so the
	// handler never blocks on remote handshakes.
	OnVaultUnlock func(vault.Vault)

	// AuditStateDir scopes the daily-rotated `audit-YYYY-MM-DD.jsonl`
	// files that `message_received` events land in. Empty disables
	// audit emission for inbound messages. Production passes
	// ~/.aileron; tests pass t.TempDir().
	AuditStateDir string
}

Config customizes NewHandlerWithConfig. The zero value is valid: every field is optional and defaults reproduce the historic [NewHandler] behaviour.