firecracker

type EgressAware ¶

type EgressAware interface {
	AttachEgress(p EgressProvider)
}

EgressAware is implemented by both the Linux and fallback supervisors. Callers obtain a *fc.Supervisor and type-assert to EgressAware before plugging in a provider — this keeps the core Supervisor interface unchanged and avoids forcing a second method onto callers (like fake supervisors in tests) that don't need it.

type EgressProvider ¶

type EgressProvider interface {
	Effective(ctx context.Context, wsid string) ([]egress.Rule, error)
}

EgressProvider is the supervisor-side view of the egress policy store. We accept the narrow Effective() surface rather than the full egress.Store so callers can plug in any source — the in-mem store under test, the SQL-backed store in production, a stub that always returns Defaults() for cold-start.

The supervisor calls Effective once per VM Start and stamps the result onto the per-VM nftables table. TTL-aware refresh is a follow-up (see report).

type LifecycleAuditor ¶

type LifecycleAuditor interface {
	VMEvent(ctx context.Context, event string, payload map[string]any)
}

LifecycleAuditor is the narrow audit hook the supervisor calls on Start success / Stop completion (gm-o9t8.3.2.7). Modeled as an interface to avoid the supervisor importing the audit package directly — the server wires a tiny adapter.

type Manifest ¶

type Manifest struct {
	KernelSHA256    string `json:"kernel_sha256"`
	RootfsSHA256    string `json:"rootfs_sha256"`
	BuiltAt         string `json:"built_at"`
	Builder         string `json:"builder"`
	KernelVersion   string `json:"kernel_version"`
	RootfsSizeBytes int64  `json:"rootfs_size_bytes"`
	Signature       string `json:"signature,omitempty"`
}

Manifest is the on-disk schema for `manifest.json` shipped alongside the kernel + rootfs. KernelSHA256 / RootfsSHA256 are lower-case hex digests. BuiltAt is RFC 3339. KernelVersion is the upstream Linux version string (e.g. "6.1.123"). RootfsSizeBytes is the byte length of the rootfs file at build time and is informational only — the authoritative integrity check is the sha256.

Signature is optional; when present it is the base64-encoded ed25519 signature over the canonical JSON of the *unsigned* manifest (i.e. the manifest with Signature emptied). The signing pubkey distribution model lives in `docs/server/vm-image.md` and is out of scope for v1.

func LoadManifest(path string) (*Manifest, error)

type Options ¶

type Options struct {
	// Logger may be nil — slog.Default() is used in that case.
	Logger any // *slog.Logger; "any" to avoid platform-specific imports here

	// Vault is the secrets provider for boot-time injection. When nil,
	// only explicit Spec.Secrets are passed to the guest.
	Vault VaultInjector

	// Auditor receives VM lifecycle events (Spawn/Destroy). Nil-safe.
	Auditor LifecycleAuditor
}

Options is the construction surface for the Supervisor that wants dependencies wired explicitly (vault for boot-time secret injection, audit for lifecycle events — see gm-o9t8.3.2.5 and gm-o9t8.3.2.7). Existing callers can keep using NewSupervisor(log) which routes through Options with nil dependencies.

type Ruleset ¶

type Ruleset struct {
	TableName  string      `json:"table_name"`
	Family     string      `json:"family"`
	ChainName  string      `json:"chain_name"`
	Hook       string      `json:"hook"`
	Priority   int         `json:"priority"`
	Statements []Statement `json:"statements"`
}

Ruleset is the full translated plan for a single VM. It also carries the per-VM nftables table name so the applier and the cleanup path agree on what to add and remove.

func (rs Ruleset) JSON() string

type Spec ¶

type Spec struct {
	WorkspaceID     string
	KernelPath      string
	RootfsPath      string
	VolumeMounts    []VolumeMount
	Secrets         map[string]string
	MemMB           int
	CPUCount        int
	FallbackCommand string
}

Spec describes a single VM to start. WorkspaceID identifies the workspace this VM belongs to and feeds into the generated VM ID for observability. KernelPath / RootfsPath are the host paths to the vmlinux + ext4 image artifacts (gm-o9t8.3.2.2). Secrets are injected via MMDS on Linux and via subprocess env on the fallback — both paths land them in the guest before the dispatch command runs. MemMB and CPUCount default to 512MB / 1 vCPU when zero.

FallbackCommand is the bash -c command the non-Linux fallback uses as the VM stand-in. Production Linux callers do not set this. Empty on the fallback means "sleep until killed" — i.e. a passive VM that outlives a Start/Stop pair but does nothing useful.

type Statement ¶

type Statement struct {
	// RuleID echoes egress.Rule.ID so operators can map a drop event
	// in the kernel log back to the policy row that produced it.
	RuleID string `json:"rule_id"`

	// Priority is copied from the source rule so the test fixture
	// can assert the IR sort matches Effective() order.
	Priority int `json:"priority"`

	// Proto is "tcp", "udp", or "" for any.
	Proto string `json:"proto,omitempty"`

	// DestIPs is the resolved-at-apply-time IPv4/IPv6 set for the
	// rule's host pattern. Empty when the pattern is a wildcard that
	// can't be eagerly resolved.
	DestIPs []string `json:"dest_ips,omitempty"`

	// HostPattern is preserved verbatim so the Linux applier can
	// stamp it onto the rule comment (and the log prefix when the
	// rule fires a drop event).
	HostPattern string `json:"host_pattern"`

	// PortStart / PortEnd are inclusive; both zero == any port.
	PortStart int `json:"port_start"`
	PortEnd   int `json:"port_end"`

	// Verdict is the terminal verdict the rule applies.
	Verdict Verdict `json:"verdict"`

	// Log toggles a `log prefix "gemba-egress-drop:<rule_id>"`
	// statement before the verdict — set on every deny so kernel
	// ringbuffer / nflog readers can attribute the drop.
	Log bool `json:"log,omitempty"`

	// Note is a free-form annotation used when a rule's pattern
	// can't be expressed as concrete IP literals; the applier emits
	// a degraded log-only rule and warns the operator.
	Note string `json:"note,omitempty"`
}

Statement is one translated rule plan entry — what the Linux applier will emit as a single nftables rule. Fields are exported so tests can introspect them and so the JSON form is stable across builds (no map iteration ordering, no unexported reflection).

type Supervisor ¶

type Supervisor interface {
	// Start launches a new VM described by spec. It blocks until the
	// VM is reachable / dispatch-ready or ctx is cancelled. Each call
	// returns a distinct *VM; callers are expected to track their own
	// VM handles.
	Start(ctx context.Context, spec Spec) (*VM, error)

	// Stop terminates a previously-started VM gracefully, then force-
	// kills anything still alive after timeout elapses. Idempotent —
	// calling Stop twice on the same *VM returns nil the second time.
	Stop(ctx context.Context, vm *VM, timeout time.Duration) error

	// Wait returns a channel that emits a single error when the
	// underlying VM process terminates. A clean Stop results in a nil
	// send. Unexpected exits surface the wait error (e.g. exit-status
	// non-zero). The channel is closed after the single send.
	Wait(ctx context.Context, vm *VM) <-chan error
}

Supervisor is the lifecycle interface for a Firecracker-style VM host. It mirrors `internal/adapter/dolt/supervisor.Supervisor` in spirit — Start launches, Stop terminates, Wait surfaces termination — but is a *factory* for many independent VMs rather than a wrapper around a single long-lived child like dolt-sql-server.

func NewSupervisor(log *slog.Logger) Supervisor

func NewSupervisorWithOptions(opts Options) Supervisor

type VM ¶

type VM struct {
	ID        string
	IPAddr    string
	StartedAt time.Time
	// contains filtered or unexported fields
}

VM is the opaque handle returned by Start. Fields are read-only after Start returns; mutation is the Supervisor's job.

state is exported via getter methods so the fallback and Linux implementations share the bookkeeping without leaking platform- specific fields into the public surface.

type VaultInjector ¶

type VaultInjector interface {
	Inject(ctx context.Context, wsid string) (map[string]string, error)
}

VaultInjector is the narrow surface the supervisor uses to pull boot-time secrets out of the workspace vault (gm-o9t8.3.2.5). It is satisfied by *vault.boltVault — keeping the dependency as an interface lets tests inject fakes and avoids an import cycle on internal/vault from this low-level adapter package.

type Verdict ¶

type Verdict string

Verdict is the action a rule emits when it matches: accept, drop, or log+drop. Allow rules become accept; deny rules become drop (with an embedded log statement when the operator wants visibility, which v1 always does so we get the audit ingest path for free).

const (
	VerdictAccept Verdict = "accept"
	VerdictDrop   Verdict = "drop"
)

type VolumeMount ¶

type VolumeMount struct {
	HostPath  string
	GuestPath string
	ReadOnly  bool
}

VolumeMount is a stub for virtio-fs mount semantics. The real host-path / guest-path / read-only / cache-mode shape lands in gm-o9t8.3.2.4; for now the field exists so callers can compile against the final Spec shape.