agent

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

type ApplyOptions struct {
	// Installer applies the upgrade, and answers which channel the device
	// follows; nil uses the real one.
	Installer *install.Installer
	// Fetch is the staging options. Tests set the verifier and the mirror.
	Fetch upgrade.Options
	// Now is the clock, for the request's age; nil uses time.Now.
	Now func() time.Time
	// Progress receives one line per step; nil discards them.
	Progress func(string)
}

type AttachedDevice interface {
	// Done is closed once the attachment has ended.
	Done() <-chan struct{}
	// Close detaches it. Idempotent.
	Close() error
	// Opened describes it for the device_opened answer.
	Opened() remote.DeviceOpenedPayload
	// Give is what a sandbox is given for it: device nodes for USB, an
	// interface for L2. name is the sandbox-facing handle; iface is the
	// segment's sandbox-side shape.
	Give(name string, iface executor.HostInterface) ([]executor.HostDevice, *executor.HostInterface)
}

type Config struct {
	// Server is the control-plane WebSocket URL,
	// e.g. wss://cloop.example.com/api/executors/connect.
	Server string
	// Token is an enrollment token, used only until a credential is issued.
	Token string
	// TokenFile is the file Token was read from, when it came from one.
	//
	// The agent deletes it once the token has been redeemed. An enrollment
	// token is single-use, so after redemption the file holds a dead secret
	// that still looks live: it would be carried into every backup and disk
	// image of the device, and an operator finding it later cannot tell
	// whether it is spent. Removing it makes the credential's lifetime match
	// its usefulness. Set by `cloop executor agent --token-file`, which is
	// how the installed service receives its token without it appearing in
	// ExecStart.
	TokenFile string
	// CredentialPath is where the long-lived credential is persisted.
	// Empty uses DefaultCredentialPath().
	CredentialPath string
	// WorkDirRoot confines every workload. Empty uses ~/.cloop/work.
	WorkDirRoot string
	// MaxConcurrent bounds simultaneous workloads. Zero means NumCPU.
	MaxConcurrent int
	// Labels are operator-supplied scheduler selectors.
	Labels map[string]string
	// RetainBytes overrides DefaultRetainBytes per workload.
	RetainBytes int
	// Pin is the control plane's expected SPKI fingerprint,
	// "sha256:<base64>". Several may be given comma-separated so a key
	// rotation can be staged. Empty means ordinary PKI verification only.
	// Taken from the stored credential when the flag is not passed.
	Pin string
	// RootCAFile adds a PEM bundle to the trusted roots, for a control plane
	// whose certificate the system store does not know — a private CA, or a
	// `cloop hub tls-init` development certificate. This is the supported way
	// to reach such a server; there is deliberately no way to disable
	// verification instead.
	RootCAFile string
	// InsecureTransport permits plaintext ws:// to a non-loopback host.
	// It exists for links already protected some other way (an established
	// mTLS tunnel, a lab with no network). Every connection attempt logs a
	// warning while it is on.
	InsecureTransport bool
	// Logf receives operational messages. Nil discards them.
	Logf func(format string, args ...any)
	// Now overrides the clock for tests.
	Now func() time.Time
	// Dial overrides connection establishment, so tests can drive the agent
	// over an in-memory pipe instead of a real socket.
	Dial func(ctx context.Context, server, token string) (remote.Conn, error)
	// HostProbes turns on the capability probes that run programs — nft(8)
	// for the packet filter, the container engine for its OCI runtimes (Task
	// 20345). The CLI sets it; tests leave it off, so building a hello does
	// not shell out to whatever tooling the test machine happens to have.
	HostProbes bool
	// SysfsRoot and DevRoot override where USB hardware is read from and
	// where device nodes are stat'ed. Tests point them at fixture trees; empty
	// means /sys and /dev.
	SysfsRoot string
	DevRoot   string
	// InstallTarget overrides where this device's managed install is looked
	// for — the unit, the helper and the binary an upgrade replaces. Tests
	// point it at a staged tree; nil is the real install under /etc and
	// /usr/local/bin.
	InstallTarget func() (install.Spec, install.Output, error)
	// UnitActive overrides how the agent asks systemd whether a unit is
	// active, and whether it could tell. Tests set it so that nothing they run
	// queries the machine's systemd; nil asks `systemctl is-active`.
	UnitActive func(unit string) (active, known bool)
	// Devices attaches forwarded devices on this host (Task 20430). Nil is
	// the host's own kernel — vhci_hcd for USB, a TAP for L2 — which is what
	// every caller but a test wants.
	Devices DeviceAttacher
	// ContainerDriver builds the driver for a container-mode payload outside
	// a virtual executor. Nil is the container driver; tests substitute one
	// that needs no engine, to exercise what the agent hands a sandbox.
	ContainerDriver func(executor.SandboxSettings) (executor.Executor, error)
	// Channel is the update channel this device follows (Task 20376), from
	// the unit's channel drop-in by way of CLOOP_UPDATE_CHANNEL. Empty is
	// stable. It is reported in the hello, so the hub knows what to offer,
	// and an edge target is refused without it. Nothing the hub sends sets
	// it.
	Channel provenance.Channel
}

type Credential struct {
	// Server is the control-plane WebSocket URL this credential is valid for.
	// Stored alongside the secret so `cloop executor agent` can be re-run with
	// no flags at all once enrolled.
	Server string `json:"server"`
	// AgentID is the control plane's identifier for this device. It is also
	// the executor ID projects bind to.
	AgentID string `json:"agent_id"`
	// Name is the operator-facing label chosen at enrollment.
	Name string `json:"name,omitempty"`
	// Credential is the long-lived secret. The control plane stores only its
	// hash, so this file is the only copy in existence.
	Credential string `json:"credential"`
	// WorkDirRoot is the filesystem root every workload is confined beneath.
	WorkDirRoot string `json:"workdir_root,omitempty"`
	// Pin is the control plane's SPKI fingerprint ("sha256:<base64>"), or
	// "" when the device was enrolled without one.
	//
	// It is persisted alongside the secret because pinning that only applied
	// to the enrollment connection would protect the least valuable moment
	// and leave every subsequent one — thousands of reconnects carrying a
	// long-lived credential, over years, from a device nobody visits —
	// trusting whatever answers DNS. Storing it makes the pin a property of
	// the device's identity rather than of one command line.
	Pin string `json:"pin,omitempty"`
	// EnrolledAt records when the credential was issued.
	EnrolledAt time.Time `json:"enrolled_at"`
}

type DetectOptions struct {
	// WorkDirRoot is the confinement root to advertise.
	WorkDirRoot string
	// MaxConcurrent is the agent's workload ceiling.
	MaxConcurrent int
	// Labels are operator-supplied scheduler selectors.
	Labels map[string]string
	// LookPath overrides exec.LookPath for tests.
	LookPath func(string) (string, error)
	// MemoryMB overrides memory detection for tests; -1 forces "unknown".
	MemoryMB int
	// KVMDevice overrides the virtualization device probed by
	// detectVirtualization. Tests point it at a temp file; empty means
	// KVMDevice.
	KVMDevice string
	// SysfsRoot and DevRoot override where the USB inventory is read from
	// (Task 20345). Tests point them at fixture trees; empty means /sys and
	// /dev.
	SysfsRoot string
	DevRoot   string
	// ProbePacketFilter reports whether a host-side packet filter can be
	// installed, and why not. Nil skips the probe and reports none, which is
	// what every caller but the agent itself wants: the probe runs nft(8).
	ProbePacketFilter func() (bool, string)
	// ProbeOCIRuntimes lists the OCI runtimes a container engine has
	// registered. Nil skips it, for the same reason: the probe runs the
	// engine.
	ProbeOCIRuntimes func(engine string) []string
}

type DeviceAttacher interface {
	// Support reports whether this host can attach each kind, and why not.
	Support() (usb bool, usbIssue string, l2 bool, l2Issue string)
	// AttachUSB imports the USB device behind stream, whose forwarder exports
	// it as busid. The attachment owns the stream from then on.
	AttachUSB(ctx context.Context, stream io.ReadWriteCloser, busid string) (AttachedDevice, error)
	// AttachL2 bridges stream to a new TAP named tap.
	AttachL2(stream io.ReadWriteCloser, tap string) (AttachedDevice, error)
}

type UpgradeTarget struct {
	// Target is a release tag, "latest", or "edge:<commit>".
	Target string
	// Channel is the device's update channel, from root-owned configuration.
	Channel provenance.Channel
	// Install carries everything else install.Upgrade takes — Force, DryRun,
	// SettleTimeout, and any unit changes an operator asked for in the same
	// command. Source, the provenance fields and the Expect* fields are filled
	// in here from what was staged. AllowRollback is passed through as the
	// caller set it, and only an operator's own command may set it: a
	// request the agent filed, or a frame the hub sent, never does.
	Install install.UpgradeOptions
	// Fetch is the staging options: verification against the release
	// identity can be skipped for a release (an operator's --insecure-skip-
	// verify on the device), never for an edge build. Tests set the verifier
	// and the edge mirror.
	Fetch upgrade.Options
	// Installer applies the upgrade; nil uses the real one.
	Installer *install.Installer
	// Progress receives one line per step; nil discards them.
	Progress func(string)
}