Documentation
¶
Overview ¶
Package reap implements the destroy logic behind the daemon-independent `boid reap` subcommand (cmd/reap.go): it talks to the docker engine directly, never through boid's own daemon API, so it can stop/destroy every sibling job container an install created even when the daemon itself is down or unreachable.
Run destroys the UNION of two independent sources, neither sufficient alone:
- live docker resources carrying the boid.install_id=<id> label — the primary job containers (and any volumes/networks) the daemon creates directly via containerBackend (internal/dispatcher/container_backend.go).
- the per-job ledger files (<runtimesDir>/<jobID>/docker-resources.jsonl, internal/sandbox/dockerproxy.Ledger) dockerproxy's sibling resources are recorded into. Those carry NO boid label at all — the *client* inside the sandbox (docker CLI, TestContainers, ...) creates them, not boid — so the label query alone would never find them.
Workspace HOME volumes are preserved by default ¶
Run takes a WorkspaceHomePolicy because "destroy everything this install created" and "do not destroy the workspace's credentials" are genuinely in tension. The contract: `boid reap` preserves persistent workspace HOME volumes by default, and `boid reap --include-workspace-homes` destroys them. containerBackend.ReapOrphans's startup pass ALWAYS preserves them — a daemon restart must never cost a workspace its harness authentication.
Index ¶
Constants ¶
const LabelInstallID = dockerres.LabelInstallID
LabelInstallID is the docker resource label reap's live query filters on. An alias of internal/dockerres.LabelInstallID, which stays import-free so this package remains importable from cmd (a daemon-independent CLI path) without pulling in internal/dispatcher's much larger dependency graph (DB, orchestrator, sqlite, ...).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Report ¶
type Report struct {
DestroyedContainers []string
DestroyedNetworks []string
DestroyedVolumes []string
// SkippedVolumes lists the workspace HOME volumes Run enumerated but did
// not destroy under PreserveWorkspaceHomes. Deliberately NOT part of
// Empty(): a skip is not a destruction, so a run that only skipped
// things is still "already clean" as far as Empty() is concerned.
// cmd/reap.go prints these lines before consulting Empty() so the
// preservation stays visible even in the "nothing to reap" case.
SkippedVolumes []string
Errors []string
}
Report summarizes what Run destroyed (Destroyed*), deliberately left alone (SkippedVolumes), or failed to destroy (Errors — one formatted line per failure, "<type> <id>: <error>", so a CLI caller can print it directly without re-deriving context).
func Run ¶
func Run(ctx context.Context, api dockerAPI, installID, runtimesDir string, homes WorkspaceHomePolicy) (Report, error)
Run destroys every docker resource belonging to installID: containers first (stop, best-effort, then force-remove — dependency order, matching dockerproxy.Reap and containerBackend.ReapOrphans), then networks (containers must be disconnected first), then volumes last (may still be referenced by a container mid-removal). Individual failures are recorded in Report.Errors and do not abort the rest — a single stuck container must not block reaping everything else.
A resource docker already reports as gone (404/NotFound, checked via errdefs.IsNotFound) is treated as successfully destroyed, not an error, since it may have already been removed some other way (typically a ledger-sourced entry — see unionResources). Every successfully destroyed id whose ledger entry can be traced (via unionResources' returned ledgerSource map) is drained from that ledger file afterward, so a subsequent reap run does not attempt it again.
runtimesDir may be empty (ledger union skipped; the label query still runs) — see ledgerEntries.
homes decides what happens to the persistent workspace HOME volumes among the enumerated set. The check is by NAME, not by label, because the ledger half of the union contributes bare ids with no labels attached at all — a label-based rule could not see them. Preserved volumes land in Report.SkippedVolumes.
type WorkspaceHomePolicy ¶
type WorkspaceHomePolicy int
WorkspaceHomePolicy tells Run what to do with the persistent workspace HOME volumes it enumerates. Its zero value is the fail-safe one: a caller that forgets to think about this preserves the data rather than destroying it.
const ( // PreserveWorkspaceHomes leaves every volume dockerres classifies as a // workspace HOME (boid-ws-home-*) alone, reporting it under // Report.SkippedVolumes instead. The default, and the only value // containerBackend.ReapOrphans's startup pass ever passes. PreserveWorkspaceHomes WorkspaceHomePolicy = iota // IncludeWorkspaceHomes destroys workspace HOME volumes along with // everything else — the explicit `boid reap --include-workspace-homes` // opt-in, for an operator who really is tearing the whole install down // and accepts losing every workspace's harness authentication and // toolchain with it. IncludeWorkspaceHomes )