guest

type Client struct {
	// Dial opens a new control connection to the box's guest.
	Dial func(ctx context.Context) (net.Conn, error)
}

type Guest struct {
	// contains filtered or unexported fields
}

type InitReq struct {
	Files []sandbox.InjectFile `json:"files,omitempty"`
	Env   []string             `json:"env,omitempty"`
	// CopyFiles are host files a spoke copies into every box during Init (its
	// --copy flag). Unlike Files (per-box secrets the caller owns, written with the
	// UID/GID they carry), these are written OWNED BY THE BOX USER regardless of the
	// UID/GID they carry, so the box's workload can read and write them — a spoke
	// staging config or seed data into the box without baking it into the image.
	CopyFiles []sandbox.InjectFile `json:"copy_files,omitempty"`
	// InitScript is an optional provisioning script run inside the box during Init,
	// as the same (unprivileged) user the box's workload runs as. Empty runs
	// nothing. A non-zero exit reports a broken box (see InitResp.ScriptFailed).
	InitScript []byte `json:"init_script,omitempty"`
	// InitScriptTimeout bounds how long the init script may run. A non-positive
	// value uses the guest default (defaultInitScriptTimeout).
	InitScriptTimeout time.Duration `json:"init_script_timeout,omitempty"`
}

type InitResp struct {
	ScriptFailed bool   `json:"script_failed,omitempty"`
	ScriptError  string `json:"script_error,omitempty"`
	ScriptOutput string `json:"script_output,omitempty"`
}

type Options struct {
	// Home overrides $HOME for the box's Exec commands and init script. Empty
	// inherits the home the guest itself was started with (a real container sets
	// HOME=/root); the in-process test fake sets a per-box home so concurrent boxes
	// stay isolated.
	Home string
	// InitScriptPath is where the host-provided init script is written inside the
	// box before it is run. Empty uses defaultInitScriptPath; tests override it to a
	// writable temp path so they need no privileged location.
	InitScriptPath string
	// Credential, when non-nil, is the OS credential (uid/gid and supplementary
	// groups) the guest drops to when running the box's init script and Exec
	// commands. The guest itself keeps its own privileges (root, to serve the
	// control channel and inject files); only those child processes run as this
	// credential — so the box's own workload runs unprivileged yet can still
	// escalate via sudo. Nil runs children as the guest's own user. Pair it with
	// Home so the dropped processes get that user's home.
	Credential *syscall.Credential
	// Log records best-effort failures; nil falls back to slog.Default().
	Log *slog.Logger
}