Documentation
¶
Overview ¶
Package workspace is the seam between factory-agent supervise and the VM a task runs in (P1 §1, design/workstreams/agent/LLD/supervise.md): a Driver creates, starts, fills, runs, empties and destroys one workspace VM per task. The tart driver is in workspace/tart.
Index ¶
Constants ¶
const ( // BundleDir is where Put lays the run bundle in the VM: on the root disk, since the // bundle's skills hold executables and /run is a noexec tmpfs. vmrun.DefaultBundle agrees. BundleDir = "/var/lib/factory/run" // VMOutDir is factory-agent run's out/ in the VM (--work /work). VMOutDir = "/work/out" // AgentCommand is factory-agent in the VM (the base image puts it on PATH). AgentCommand = "factory-agent" )
The workspace runner's fixed places (supervise.md, "The workspace runner").
const ( // DefaultGatewayPort is the gateway's port on the VM's gateway address when GatewayPort is // zero: workspace.gatewayPort's default, which the host's firewall opens. DefaultGatewayPort = config.DefaultGatewayPort // DefaultOverrun is how long past the task's wall clock the runner lets the VM run before // it cancels it: the VM's own deadline (--remaining) fires first and writes the outcome. DefaultOverrun = 2 * time.Minute // DefaultDownBudget is how long the runner waits for factory-agent run to exit after its // outcome event (its environment's down, at most --down-timeout). DefaultDownBudget = pipeline.StackDownTimeout + 30*time.Second )
Defaults of RunnerOptions.
const ( DefaultCPU = 6 DefaultMemoryMiB = 8 << 10 )
The default workspace size (P1 §1: local-dev with kind used 1.9 GiB in the guest).
const Prefix = "ws-"
Prefix starts every workspace's name. A name is Prefix and the task id (tsk_…), so Phase 0's VMs (ws-1, ws-2, ws-gw) are never a workspace: no driver call accepts or lists them.
const TranscriptNote = "factory.workspace-transcript"
TranscriptNote is the transcript line the runner writes about the VM's transcript: lines it dropped (over the line cap, or a host-only line the VM forged) or why it has none.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Bundler ¶
type Bundler interface {
PrepareBundle(ctx context.Context, job *runner.Job, dir string, x pipeline.BundleExtras) error
StoreTranscript(ctx context.Context, job *runner.Job, parts [][]byte, extra ...string) (string, error)
StoreEnvironmentLog(ctx context.Context, job *runner.Job, log []byte, extra ...string) error
}
Bundler is what the runner needs of the host's run pipeline (*pipeline.Pipeline): the run bundle before the VM exists, and the transcript and environment log uploads after.
type Driver ¶
type Driver interface {
// Create makes the workspace from the driver's warm base, sized by spec (WithDefaults).
Create(ctx context.Context, name string, spec Spec) error
// Start boots it, waits until commands run in it, and returns its addresses.
Start(ctx context.Context, name string) (Network, error)
// Put copies the host directory srcDir to dstDir in the VM, replacing it, owned by root and
// read-only to everyone (files 0444, directories and executables 0555).
Put(ctx context.Context, name, srcDir, dstDir string) error
// Exec runs argv in the VM. stdin may be nil. A non-zero exit is an *ExitError. When ctx
// is done the remote process gets SIGTERM, then SIGKILL after the driver's grace; Exec
// returns, with ctx's error, once it has exited, or after the grace once the local side is
// stopped too.
Exec(ctx context.Context, name string, argv []string, stdin io.Reader, stdout, stderr io.Writer) error
// Get copies the VM directory srcDir to the host directory dstDir, which must not exist
// (its parent must): all of it, or only the named files when files is given (plain names
// in srcDir; a missing one is skipped). The copy is capped and refuses links out of dstDir
// and special files.
Get(ctx context.Context, name, srcDir, dstDir string, files ...string) error
// Stop shuts the workspace down and keeps it (--keep-workspace).
Stop(ctx context.Context, name string) error
// Destroy stops and deletes it; a workspace that doesn't exist is no error.
Destroy(ctx context.Context, name string) error
// List names the driver's workspaces that exist, for the orphan cleanup at start.
List(ctx context.Context) ([]string, error)
}
Driver runs workspace VMs. Every method takes a workspace name (Name) and refuses any other. Everything a VM returns (Exec's output, Get's files) is untrusted.
type ExitError ¶
type ExitError struct{ Code int }
ExitError is Exec's error when the remote command exits non-zero.
type Network ¶
Network is a started workspace's addresses: the VM's own, which its gateway pins as its only client, and the agent host's address on the VM's network, where the gateway listens.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner runs each leased task in its own workspace VM, behind a gateway that holds every credential (supervise.md, "The workspace runner"). It implements runner.Runner.
func NewRunner ¶
func NewRunner(o RunnerOptions) (*Runner, error)
NewRunner checks o and fills in the defaults.
type RunnerOptions ¶
type RunnerOptions struct {
Driver Driver
// Pipeline is the host's pipeline (WorkRoot, GitAuthHelper).
Pipeline Bundler
// StateDir is the agent's state dir: runs/<task>/ (the bundle and the VM's out/),
// gateway-ca/ and logins/.
StateDir string
// Spec is the agent's workspace size (WithDefaults): each workspace's, and the most a
// task's limits.cpus and limits.memory get (taskSize).
Spec Spec
// KeepWorkspace stops each workspace instead of destroying it, and keeps runs/<task>/.
KeepWorkspace bool
// GatewayPort is the gateway's port on the VM's gateway address: workspace.gatewayPort,
// the one the host's firewall (the pf anchor, the kata nft table) opens.
// DefaultGatewayPort when zero.
GatewayPort int
// Listen opens the gateway's listener on addr; default a TCP listener on it (tests listen
// elsewhere).
Listen func(ctx context.Context, addr netip.AddrPort) (net.Listener, error)
// Overrun and DownBudget: DefaultOverrun and DefaultDownBudget when zero.
Overrun, DownBudget time.Duration
Clock clock.Clock
Logger *slog.Logger
}
RunnerOptions configure a Runner. Driver, Pipeline and StateDir are required.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package kata is the workspace driver for Linux: each workspace is a Kata microVM made and run by the root helper (design/workstreams/agent/LLD/workspace-kata.md#the-driver-internalagentworkspacekata), which this driver runs as sudo -n kata-helper <verb>.
|
Package kata is the workspace driver for Linux: each workspace is a Kata microVM made and run by the root helper (design/workstreams/agent/LLD/workspace-kata.md#the-driver-internalagentworkspacekata), which this driver runs as sudo -n kata-helper <verb>. |
|
Package tart is the workspace driver for macOS: it drives the tart CLI (P1 §1, design/workstreams/agent/LLD/supervise.md).
|
Package tart is the workspace driver for macOS: it drives the tart CLI (P1 §1, design/workstreams/agent/LLD/supervise.md). |
|
Package vmexec is what the workspace drivers share (design/workstreams/agent/LLD/ workspace-kata.md#the-driver-internalagentworkspacekata): running commands in a workspace through the driver's exec command, and over it Put's and Get's tar streams, Exec with its pid-file cancel, and the network read.
|
Package vmexec is what the workspace drivers share (design/workstreams/agent/LLD/ workspace-kata.md#the-driver-internalagentworkspacekata): running commands in a workspace through the driver's exec command, and over it Put's and Get's tar streams, Exec with its pid-file cancel, and the network read. |