154 lines
10 KiB
Markdown
154 lines
10 KiB
Markdown
# package-updater — Claude context
|
|
|
|
Master/agent fleet updater. A master (UI behind OIDC, Postgres) shows every Compose
|
|
stack, Swarm service and container on every machine and starts updates; one agent per
|
|
machine (`/var/run/docker.sock` mounted) reports its inventory and runs the jobs.
|
|
Both are in one image: `updater-master` and `updater-agent`.
|
|
|
|
See `README.md` for user-facing docs. This file is for working ON the code.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
go test ./... # all tests, fast (no docker, no postgres)
|
|
go test -race ./internal/agent/... ./internal/master/... ./internal/e2e/
|
|
go test -run TestFoo ./internal/master/hub # single test
|
|
go build ./cmd/master ./cmd/agent # produce ./master and ./agent
|
|
docker build -t package-updater:dev . # multi-stage, builds golang:1.26-alpine
|
|
|
|
# Postgres tests (store), against any throwaway database:
|
|
DATABASE_URL=postgres://... go test -tags integration ./internal/master/store/
|
|
```
|
|
|
|
## Architecture (one-line per package)
|
|
|
|
- `cmd/master` — wiring only: config → store → hub → jobs → web + webhook, two listeners (UI, agents over pinned TLS)
|
|
- `cmd/agent` — wiring only: config → docker client → inventory → job runner → master connection
|
|
- `internal/protocol` — the WebSocket messages both sides speak (`Version`, `JobStart`, `JobResult`, ...)
|
|
- `internal/pin` — master key pair, certificate and fingerprint pinning
|
|
- `internal/agenttoken` — agent token generation and hashing
|
|
- `internal/imageref` — image reference parsing (repo, tag, digest)
|
|
- `internal/logging` — slog JSON, request-id context propagation
|
|
- `internal/agent/config` — env-var loading; fails fast on missing `MASTER_URL`/`MASTER_KEY`/`AGENT_TOKEN`
|
|
- `internal/agent/inventory` — reads Compose, Swarm and plain containers from the Docker daemon
|
|
- `internal/agent/conn` — dial, hello, snapshot, job messages, reconnect with backoff; one writer goroutine per session
|
|
- `internal/agent/updater` — job `Runner` (single FIFO worker, outbox until acked), Compose and Swarm executors, override file, mount-root check, registry auth
|
|
- `internal/master/config` — env-var loading
|
|
- `internal/master/store` — Postgres access and migrations
|
|
- `internal/master/hub` — agent connections: auth, per-connection writer, routing, job reconcile on hello
|
|
- `internal/master/registry` — HEAD-only digest lookup against a registry (go-containerregistry, `DOCKER_CONFIG` credentials)
|
|
- `internal/master/poller` — every `POLL_INTERVAL`: one lookup per followed `repo:tag`, sets the available version, starts auto jobs
|
|
- `internal/master/jobs` — decides whether a service may be updated and starts a job on the right agent
|
|
- `internal/master/webhook` — `POST /update`: records the available version, starts jobs for auto services, waits for them
|
|
- `internal/master/web`, `webauth` — HTMX UI behind OIDC login, SSE signals
|
|
- `internal/master/events` — in-process publish/subscribe for UI refresh signals
|
|
- `internal/master/model` — domain types shared by the above
|
|
|
|
## Design intent (do not break without discussion)
|
|
|
|
- **Single FIFO worker per agent by design** (`internal/agent/updater/runner.go`).
|
|
Two `docker compose` calls against the same stack race.
|
|
- **One queued or running job per service**, enforced by the unique index
|
|
`update_jobs_one_active` (not by application code).
|
|
- **The agent writes exactly one file**, `<stack dir>/compose.override.yaml`, and only
|
|
if it is absent or starts with the header line. It refuses the job when any other
|
|
auto-loaded override name exists.
|
|
- **Every config file and the override path must be inside a read-write bind mount of
|
|
the agent's own container whose source equals its destination.** Mounts are read per
|
|
job (`ContainerInspect(SELF_ID)`) and checked after symlink resolution. This replaces
|
|
the old `STACKS_ROOT`.
|
|
- **Self-protection on the master**: a service is refused when its image repo equals the
|
|
repo of `AGENT_IMAGE` or the row has the `self` flag. The agent does not re-check.
|
|
- **Unknown message types are logged and ignored; malformed messages close the connection.**
|
|
- **Reconcile before routable**: the hub fails a reconnecting agent's jobs it does not
|
|
list in `known_jobs`, and only then accepts jobs for that connection.
|
|
- **The webhook never creates services; new services always start `manual`.** The upsert
|
|
does not touch `update_mode`.
|
|
- **Auth**: agents by token over pinned TLS; people by OIDC; CI by the `UPDATER_API_KEY`
|
|
bearer token on `POST /update` only. Every state-changing UI request is a POST with a
|
|
CSRF token.
|
|
|
|
## Gotchas
|
|
|
|
- **Registry access is HEAD only** (`internal/master/registry`). Docker Hub counts a manifest
|
|
GET as a pull; the client never falls back to GET, and a test asserts this.
|
|
- **`image_versions` uses `''` instead of NULL** for a missing tag or digest, so
|
|
`UNIQUE (repo, tag, digest)` deduplicates. The webhook records `(repo, tag, '')`; that
|
|
row is hidden from `RecentVersions` when a row with the same tag and a digest was first
|
|
seen at or after it.
|
|
- **The UI picks a version by `image_versions.id`, never by a ref from the form**, and the row
|
|
must belong to the service's `image_repo`. A digest-pinned or tagless pick needs agent
|
|
protocol 3 (`protocol.MinPinnedRefVersion`); `Hub.Route` takes the minimum version.
|
|
- **Picking a tagless version (`repo@digest`) leaves the service following no tag:** it is no
|
|
longer polled and the plain Update button is refused.
|
|
- **`services.last_tag_digest`** is set by the poller when it starts an auto job and when it
|
|
sees the service already running the tag's digest, and by `FinishJob` after any successful
|
|
plain tag job (not pinned/tagless picks; the digest is the one the agent pinned). The poller
|
|
starts no job for that digest, nor for one `desired_ref` (`ref@digest`) already names, and
|
|
re-reads the service before `Start`; so a rollback of an auto service holds until the
|
|
registry shows a different digest. `ErrJobActive` and `NotUpdatableError` leave it unset so
|
|
the next cycle retries.
|
|
- **A bare image's running version is recorded with tag `latest`** (like `jobs.FollowedRef`);
|
|
`repo@digest` is recorded with tag `''`. Only `sha256:<64 hex>` digests are recorded.
|
|
- **Image matching is case-sensitive.** The tricky case is `localhost:5000/foo:v1` where
|
|
the first colon is a port, not a tag. See `internal/imageref`.
|
|
- **Path safety uses `filepath.Rel` + ".." prefix check**, NOT `strings.HasPrefix`.
|
|
Prevents the `/foo-evil` vs `/foo` confusion. See `internal/agent/updater/pathcheck.go`.
|
|
- **Go 1.26.3** (`go.mod`). Dockerfile pins `golang:1.26-alpine`. Bumping one
|
|
without the other has caused a fix commit already.
|
|
- **`<summary>` C# convention from global CLAUDE.md does not apply here** — this
|
|
is Go. Use idiomatic GoDoc (`// FuncName does X.`).
|
|
- **The override file gets the owner of the existing override, else of the stack's first
|
|
compose file.** The agent runs as root and renames a new file into place; it chowns it
|
|
afterwards. A failure is a `warning:` line in the job output, never a failed job.
|
|
- **Compose loads only one override file.** Of `compose.override.yml`,
|
|
`compose.override.yaml`, `docker-compose.override.yml`, `docker-compose.override.yaml`
|
|
only the first that exists is read. Hence the refusal described above.
|
|
- **Stacks started with explicit `-f` do not load the override on a manual `up`.** The
|
|
agent's own jobs always pass it explicitly.
|
|
- **Override entries are never pruned.** A service deleted from the stack file keeps its
|
|
`image:` line in `compose.override.yaml`.
|
|
- **There is no `STACKS_ROOT`.** Stack directories must be mounted read-write at the host
|
|
path (`/path:/path`), and `SELF_ID` must resolve to the agent's own container. On Docker
|
|
Desktop/OrbStack bind sources are translated, so Compose jobs fail there.
|
|
- **`job.start` carries no paths.** The agent reads working dir and config files from its
|
|
own Docker daemon at execution time.
|
|
- **`protocol.Service.ConfigFiles` is the raw comma-joined label string**, so `Service`
|
|
stays comparable with `==` (`inventory.Diff` depends on it).
|
|
- **Swarm "succeeded" means the daemon accepted the new spec**, not that tasks converged.
|
|
- **Swarm updates need manager-node API access** for the agent doing the update.
|
|
- **The image's default entrypoint is `updater-agent`.** The master overrides it with
|
|
`updater-master`.
|
|
- **The webhook waits via a broker signal plus a store re-read, with a fallback poll**
|
|
(the broker drops signals for slow subscribers). Marking and starting jobs runs on
|
|
`context.WithoutCancel`, so a client that disconnects cannot leave a queued job no agent
|
|
knows about; only the waiting stops. The master never fails or cancels a timed-out job.
|
|
- **A webhook job's target is `<image_repo>:<request tag>`**, built from the service's own
|
|
repo, never from the request's image string. With an explicit target the "follows no tag"
|
|
refusal does not apply; removed, self, built and container still do.
|
|
- **`available_*` is cleared by `FinishJob`** on success only when the job's `to_ref`
|
|
(as created, without `@digest`) equals `available_ref`, `available_at <= job.created_at`
|
|
(that version is now running) and, when the job's `to_ref` carries a digest, that digest
|
|
equals `available_digest`. A rollback to an older digest of the tag therefore keeps the
|
|
newer suggestion, and a digest-pinned pick does not clear a digest-less (webhook) one.
|
|
- **Job output is capped at `protocol.MaxJobOutput` (128 KiB, tail).** NUL bytes are
|
|
stripped by the hub because Postgres text rejects them.
|
|
|
|
## References
|
|
|
|
- Master/agent spec: `docs/superpowers/specs/2026-10-12-master-agent-design.md` (authoritative)
|
|
- Phase 1 plan: `docs/superpowers/plans/2026-10-12-master-agent-phase-1-inventory.md`
|
|
- Phase 2 plan: `docs/superpowers/plans/2026-10-12-master-agent-phase-2-jobs.md`
|
|
- Phase 3 plan: `docs/superpowers/plans/2026-10-12-master-agent-phase-3-webhook.md`
|
|
- Phase 4 plan: `docs/superpowers/plans/2026-10-13-master-agent-phase-4-polling.md`
|
|
- Original single-instance design (historical):
|
|
`docs/superpowers/specs/2026-05-22-package-updater-design.md`
|
|
- Consumer-side CI integration: `gitea-action/` (calls the master's `POST /update`)
|
|
|
|
## Conventions
|
|
|
|
- Conventional Commits (`feat:`, `fix:`, `docs:`, `ci:`, `build:`, `chore:`).
|
|
- One package = one responsibility; interfaces defined at consumer site
|
|
(`jobs.Store`, `jobs.Hub`, `conn.Jobs`, `hub.Store`) for testability.
|
|
- Table-driven tests with `stretchr/testify`. No mocks beyond hand-written fakes.
|