runtime

type BootAssets struct {
	Kernel string
	Initrd string
	// Named reports that BRIG_BOOT_ASSETS chose the directory. A directory
	// someone named is their build, and wrap weighs a digest that differs
	// from the verified bundle differently there (#234).
	Named bool
}

type BootFetch struct {
	// Ref is the boot bundle to fetch, pinned to the digest whose signature
	// brig verified, repo@sha256:... Fetching the tag instead lets a tag that
	// moved after the check deliver a bundle nobody checked. Empty fetches the
	// tag BootAssetsRef names, for a bundle brig had no signature to check.
	Ref string
	// Replace fetches even when both files are there, over them. wrap asks for
	// it when the files are an older bundle's, in a directory brig chose.
	Replace bool
}

type BootResolver interface {
	// ResolveBootAssets returns the paths for RunSpec.BootAssets, fetching
	// what fetch names when a file is missing or fetch.Replace asks. notice
	// and progress are the writers a download narrates to, the same pair
	// RunSpec.Notice and RunSpec.Progress carry.
	ResolveBootAssets(fetch BootFetch, notice, progress io.Writer) (BootAssets, error)
}

type Boundary string

type Capability string

type CapabilityError struct {
	Property Property
	Path     RunPath
	State    Capability
	// Why and Remedy come from the record. For a failed probe, Why names
	// the probe command.
	Why    string
	Remedy string
	// Err is what went wrong while asking, such as a probe that did not
	// run. Nil when the answer came from the table.
	Err error
}

type Egress struct {
	Default string
	Allow   []Rule
	Deny    []Rule
}

type ExecSpec struct {
	Name    string
	Cmd     []string
	Cwd     string
	TTY     bool
	Env     []Var
	Counted bool
	// Stdin, when set, is fed to the command inside the guest. It is how a
	// credential reaches the guest without appearing in argv: hull durably
	// logs every exec's argv to a host file, so a value there outlives the
	// sandbox in a file the user never sees. Only Feed reads it.
	Stdin io.Reader
	// User runs the command as a guest user other than the image's own --
	// "root", for the one privileged exec that mounts the tmpfs. Empty leaves
	// the image's configured user, which is what every other exec wants.
	User string
}

type Exister interface {
	Exists(name string) (bool, error)
}

type FallbackReporter interface {
	// Fallback is the one line to print, or "" when the binary is the first
	// choice or a setting named it.
	Fallback() string
}

type FeedLimiter interface {
	MaxFeed() int
}

type Instance struct {
	Name  string
	State string
}

type Isolation struct {
	Boundary Boundary
	// Detail is what establishes the boundary, in the reader's terms: which
	// runtime, which backend or shim, and for anything short of a microVM what
	// that costs them.
	Detail string
}

type LogsSpec struct {
	Name string
	// Follow streams the log until the reader interrupts it. brig reads a log
	// here and does not own the sandbox, so an interrupt that reaches the
	// runtime must leave the sandbox running -- see the note on Logs.
	Follow bool
	// Tail is how many trailing lines to show, or -1 for all. -1 is both
	// runtimes' own default; a container runtime with no notion of a negative
	// count reads it as "all" rather than passing it through.
	Tail int
	// Out is where the log is written, as it arrives. The caller wraps it to
	// filter the terminal control sequences a runtime may have captured, unless
	// asked for the raw bytes.
	Out io.Writer
	// Err is where the runtime's own standard error goes, kept apart from Out
	// rather than merged into it. On hull that stream carries the runtime's
	// diagnostics and nothing else, so merging would write "instance not
	// found" into a redirect that was meant to hold a log; on a container
	// runtime it carries the guest's stderr, which a reader redirecting stdout
	// expects to still see on the terminal. The caller wraps this one too, so
	// the control-sequence filter covers both halves of the stream.
	Err io.Writer
}

type NetworkChecker interface {
	// NetworkStale reports whether the running sandbox differs from what this
	// run asks for. False when they agree, and when the backend has no way to
	// tell -- a restart nobody needs costs a boot, but a restart that is
	// skipped costs the promise.
	NetworkStale(name, hypervisor, net string, e Egress) bool
}

type NetworkInspector interface {
	// SandboxNetwork returns shared, isolated or none. Empty with no error
	// means the runtime confirmed the sandbox is absent; missing or unknown
	// network metadata is an error, never evidence of a shared network.
	SandboxNetwork(name string) (string, error)
}

type NetworkPruner interface {
	// PruneNetworks removes the networks brig made that none of inUse is on,
	// and reports how many went.
	PruneNetworks(inUse []string) int
}

type Preference struct {
	// Bin is the runtime binary a profile named, if any.
	Bin string
}

type Property string

type Publication struct {
	// Protocol is tcp or udp. Empty means tcp, which is what a dev server is.
	Protocol string `json:"protocol,omitempty"`
	// HostAddr is the address on the host the port is offered at. Empty means
	// 127.0.0.1, which keeps it on this machine.
	HostAddr string `json:"hostAddr,omitempty"`
	// HostPort is the port on the host, and GuestPort the port inside the
	// sandbox it carries to.
	HostPort  int `json:"hostPort"`
	GuestPort int `json:"guestPort"`
}

type Publisher interface {
	// Publish offers a guest port on the host, and Unpublish withdraws one.
	Publish(name string, p Publication) error
	Unpublish(name string, p Publication) error
	// Published is what this sandbox is offering, as the gateway serving it
	// reports, not as brig recorded it. The two agreeing is the thing worth
	// checking, so this asks the side that would be wrong.
	Published(name string) ([]Publication, error)
}

type Record struct {
	Property Property
	Path     RunPath
	State    Capability
	// Why says what makes this the answer. A refusal quotes it.
	Why string
	// Remedy says what to do about a refusal on this path.
	Remedy string
}

type Rule struct {
	Host string
	CIDR string
}

type RunChecker interface {
	// CanRun reports what this backend cannot honour about the run, or nil.
	CanRun(spec RunSpec) error
}

type RunPath struct {
	Runtime string
	Backend string
}

type RunSpec struct {
	Name  string
	Image string
	// Digest is the registry digest verify resolved and checked for Image, or
	// "" when none was resolved. A runtime whose store is addressable by digest
	// boots Image@Digest instead of the tag, so the bytes that boot are the ones
	// that verified; one that is not ignores it and boots the tag. See
	// PinsDigest, and the note on the nerdctl and hull adapters.
	Digest   string
	Pull     string // missing (default) | always | never
	Net      string // none | shared | isolated
	Mem      int    // MB
	CPUs     int
	Shares   []Share
	Env      []Var
	GUI      bool
	GUITitle string
	// Hypervisor is the macOS backend to boot on: vz, hvi or qemu. Empty
	// means the runtime's own default. Already resolved by the caller, which
	// is where a setting beats a profile; see wrap.
	Hypervisor string
	// RootfsType is how the guest root reaches the VM: block (an ext4 image
	// the guest writes to), virtiofs or 9pfs. Empty leaves the runtime's own
	// default, which is what almost every profile wants; a profile sets it
	// when the sandbox installs packages and needs a real writable disk.
	// Meaningless to a container runtime, which ignores it.
	RootfsType string
	// Tmpfs are tmpfs mounts to create with the sandbox, as
	// "<path>:<options>". Only the container runtimes take these: hull has no
	// create-time tmpfs, so brig mounts one there with a privileged exec
	// instead. A runtime that cannot honour it ignores it, and the caller
	// verifies the result in the guest either way -- which is what makes the
	// asymmetry safe rather than merely tolerated.
	Tmpfs []string
	// GenericBoot asks the runtime to boot this image as an ordinary OCI
	// image rather than one built to be a guest -- no kernel inside it, no
	// urunc metadata. The runtime supplies the kernel and initrd. See
	// bootArtifacts and BootAssets below.
	GenericBoot bool
	// BootAssets are the kernel and initrd a GenericBoot run boots, when the
	// caller resolved them before Run. An adapter given both boots them as
	// they are. It does not ask where the assets live and does not fetch
	// them. wrap resolves them before the verify summary through
	// BootResolver, so the summary follows the resolve (#234). Left empty,
	// the adapter resolves them itself inside Run.
	BootAssets BootAssets
	// Egress is what this sandbox may open a connection to: the rules of
	// every policy bound to it, merged. The zero value is unfiltered, which
	// is what every sandbox got before anything read a policy at boot.
	//
	// Unlike the fields above it never reaches the run command line. The
	// rules belong to the network gateway serving this sandbox and are read
	// once, when that gateway starts, which is also why a sandbox carrying
	// one needs a network of its own. See gateway.go.
	Egress Egress
	// Publish are the guest ports this run offers on the host.
	//
	// Every one of them is a hole in the sandbox boundary, so they are named
	// in the execution envelope and default to loopback. What reaches a
	// runtime here is the whole set the sandbox publishes, which is the
	// record on disk and not only what this command line asked for: a
	// publication is part of a sandbox's configuration and outlives one run.
	// See publish.go.
	Publish []Publication
	// Counted marks a user action, whose boot and lifetime hull's telemetry
	// reports, rather than brig's own plumbing. See telemetryEnv.
	Counted bool
	// Progress is where the runtime's own output goes: the image pull, the
	// boot messages, whatever the binary underneath writes on its way up.
	//
	// nil holds it instead. It is captured and quoted back on the error if the
	// boot fails, where it is the evidence, and dropped if it does not -- see
	// narration. That is the default because the output is worth reading in
	// exactly two situations, and a boot that worked is neither of them.
	Progress io.Writer
	// Notice is where a long operation says, in one line, that it has started
	// and that it is done.
	//
	// Separate from Progress because the two answer different questions. The
	// stream is detail and waits to be asked for; a download that takes a
	// minute has to say so whether or not anyone asked, or the terminal looks
	// hung. nil is silence.
	//
	// A Notice that implements Spinner shows the operation while it runs
	// instead of printing the two lines. A writer wrapped around one prints
	// the lines. See announce.
	Notice io.Writer
}

type Runtime interface {
	// Kind is the backend name, e.g. "hull" or "nerdctl".
	Kind() string
	// Bin is the executable actually being driven.
	Bin() string
	// Isolation reports what a sandbox this runtime boots actually stands on:
	// a kernel of its own, the host's, or something brig cannot establish.
	//
	// hypervisor is the macOS backend the run resolved to, or "" for the
	// runtime's own default; a container runtime ignores it, the way it already
	// ignores RootfsType. It is a parameter rather than a field because the
	// backend is a property of the run and not of the binary in hand, and
	// because the envelope is printed before any RunSpec exists.
	//
	// On the interface rather than an optional one asserted for, unlike
	// NetworkPruner: every runtime knows what it gives a guest, and a backend
	// that silently reported nothing would be read as a sandbox with no
	// boundary worth naming.
	Isolation(hypervisor string) Isolation
	// Running reports whether a sandbox of this name is up, and returns an
	// error when it could not find out at all.
	//
	// Three answers, not two, because a runtime that cannot be asked -- a binary
	// that is not there, a permission error, a daemon that is down -- is not a
	// runtime saying no. Both adapters used to fold the failure into false, so a
	// broken runtime read as an empty machine and EnsureRunning booted a second
	// sandbox onto a workspace the first was still holding (#49). A caller that
	// cannot tell must not boot: false with a non-nil error means "unknown", and
	// the boolean says nothing.
	Running(name string) (bool, error)
	// List returns every sandbox the runtime knows about, running or not.
	List() ([]Instance, error)
	// Run boots a sandbox, detached.
	Run(spec RunSpec) error
	// PinsDigest reports whether Run honours RunSpec.Digest -- that is, whether
	// this runtime's store is addressable by digest, so that booting
	// Image@Digest boots that exact object and resolves it against the local
	// store the way containerd does. brig only claims digest-level verification
	// on a runtime that returns true; on one that returns false it verifies and
	// boots the tag, and says so, rather than promise bytes it cannot pin.
	PinsDigest() bool
	// LocalDigest reports the digest the local store already holds for ref, or
	// "" when it holds nothing under that reference or cannot say. It is how the
	// verify path learns that the copy on disk is a different object from the
	// one the registry serves. Only meaningful on a PinsDigest runtime; the
	// caller does not ask the others.
	LocalDigest(ref string) (string, error)
	// Probe runs a command and reports only whether it succeeded, with all
	// output discarded. Used for reachability checks.
	Probe(spec ExecSpec) bool
	// Output runs a command and returns its stdout.
	Output(spec ExecSpec) (string, error)
	// Feed runs a command with spec.Stdin on its standard input and discards
	// its output, returning only whether it succeeded. The one method that
	// carries a value into the guest off the command line.
	Feed(spec ExecSpec) error
	// Replace hands this process over to the runtime: the exec'd binary takes
	// the terminal, the signals and the exit status. It does not return on
	// success. This is how the agent's own TUI gets a real tty without brig
	// sitting in the middle of it.
	Replace(spec ExecSpec) error
	// Attach runs the exec as a child of brig instead of replacing brig with
	// it: brig's own stdin, stdout and stderr are inherited, brig waits, and the
	// child's exit status is returned. A child killed by a signal is reported as
	// 128 plus the signal number, the shell's convention.
	//
	// It is the counterpart to Replace for a caller that has to survive the exec
	// to report on it -- which is what --json needs and Replace, having left
	// nothing of brig behind, cannot do. Both build their command from the same
	// function, so the terminal handover and the child cannot drift. See
	// RunAttached and the note on Replace.
	Attach(spec ExecSpec) (int, error)
	// Stop stops a sandbox, and Remove clears the instance holding the name.
	Stop(name string) error
	Remove(name string) error
	// Logs streams a sandbox's log to spec.Out, following until interrupted
	// when spec.Follow is set. This reads a log; it does not own the sandbox, so
	// an interrupt reaching the runtime leaves the sandbox running.
	Logs(spec LogsSpec) error
	// LogsHint is the command to suggest when a sandbox will not come up. It is
	// kept beside Logs rather than replaced by it: a boot that never became a
	// sandbox brig can drive still has a runtime command worth naming, and it is
	// the second half of the advice `brig logs` leads.
	LogsHint(name string) string
}

type Share struct {
	Host  string
	Guest string
	// ReadOnly asks the runtime to export the directory the guest cannot
	// write to. Only meaningful for directories that belong to the host: the
	// workspace is the agent's own and stays writable.
	ReadOnly bool
}

type SharedNetworkPruner interface {
	// PruneSharedNetwork stops the shared network when nothing is on it, and
	// reports whether it did.
	PruneSharedNetwork() bool
}

type Spinner interface {
	// Spin shows what until stop is called, and stop clears it.
	Spin(what string) (stop func())
}

type Var struct {
	Name  string
	Value string
	// Secret marks a value brig resolved on the user's behalf from the store
	// it owns, so that BRIG_ENV_ARGV never puts it in argv whatever it says:
	// hull durably logs every exec's argv to a host file, and an ambient shell
	// value put there deliberately is one thing, but a stored credential
	// outliving the sandbox in a file the user never sees is a different
	// severity of leak.
	Secret bool
}