reap

package
v0.3.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 14, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package reap implements the destroy logic behind the daemon-independent `boid reap` subcommand (cmd/reap.go — docs/plans/phase6-container-backend.md §PR6, §決定6). Its entire reason to exist is the plan doc's "deploy-level rollback reaper" contract: rollback from the compose (container backend) deploy to the host-daemon (userns backend) "旧デプロイ" must be able to stop/destroy every sibling job container the compose daemon created even when that daemon itself is down or unreachable — so Run talks to the docker engine directly, never through boid's own daemon API.

§決定6 requires 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 (§決定6: "従来 どおり per-job ledger... 管理").

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 (docs/plans/workspace-home-volume-persistence.md 論点 a asks for this to be declared as a contract rather than left implicit). The declared 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, which is the exact regression this policy exists to prevent.

Index

Constants

View Source
const LabelInstallID = dockerres.LabelInstallID

LabelInstallID is the docker resource label reap's live query filters on. An alias of internal/dockerres.LabelInstallID, which internal/dispatcher's own label emission reads too — the previous hand-copied literal (and the doc comment warning about drift between the two copies) is gone now that there is a leaf package both sides can import. internal/dockerres is import-free by construction precisely so this package stays importable from cmd (a daemon-independent CLI path — see cmd/reap.go) without pulling in internal/dispatcher's much larger dependency graph (DB, orchestrator, sqlite, ...), which would defeat "works even when the daemon — and everything it needs to build — is unable to start".

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 (the deploy-level-rollback contract this exists for has no room for "reap partially worked, try again never").

A resource docker already reports as gone (404/NotFound, checked via errdefs.IsNotFound — Major 8, PR6 codex review) is treated as successfully destroyed, not an error: the pre-fix code reported it as a failure on every single reap run after the first, forever, once a resource this run's own union found (typically via the ledger — see unionResources) had already been removed some other way. 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 even 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 (docs/plans/workspace-home-volume-persistence.md 論点 a 経路 1). 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.

func (Report) Empty

func (r Report) Empty() bool

Empty reports whether Run found (and so, modulo failures, destroyed) nothing at all — the "already clean" case cmd/reap.go prints specially. SkippedVolumes is intentionally excluded; see its own doc comment.

type WorkspaceHomePolicy

type WorkspaceHomePolicy int

WorkspaceHomePolicy tells Run what to do with the persistent workspace HOME volumes it enumerates (docs/plans/workspace-home-volume-persistence.md 論点 a). 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
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL