From fef631eecaa003070953b5c4084fd206088f45ad Mon Sep 17 00:00:00 2001 From: tweinmann Date: Wed, 28 Oct 2026 22:38:13 +0000 Subject: [PATCH 1/2] Propose phase 3: snapshots and queue (v0.3) Proposal, delta specs, design and tasks for snapshots, up --seed and dev.siding.seed, waiting in line for memory, build slots and learned memory peaks. Co-Authored-By: Claude Opus 5.5 --- .../.openspec.yaml | 1 - .../phase-3-snapshots-and-queue/design.md | 130 ++++++++++++++++++ .../phase-3-snapshots-and-queue/proposal.md | 59 ++++++-- .../specs/build-limit/spec.md | 34 +++++ .../specs/cli-contract/spec.md | 42 ++++++ .../specs/memory-budget/spec.md | 40 ++++++ .../specs/proxy/spec.md | 48 +++++++ .../specs/seeding/spec.md | 54 ++++++++ .../specs/snapshots/spec.md | 56 ++++++++ .../specs/stack-gc/spec.md | 29 ++++ .../specs/stack-list/spec.md | 17 +++ .../specs/stack-status/spec.md | 21 +++ .../specs/start-queue/spec.md | 43 ++++++ .../phase-3-snapshots-and-queue/tasks.md | 53 +++++++ 14 files changed, 612 insertions(+), 15 deletions(-) create mode 100644 openspec/changes/phase-3-snapshots-and-queue/design.md create mode 100644 openspec/changes/phase-3-snapshots-and-queue/specs/build-limit/spec.md create mode 100644 openspec/changes/phase-3-snapshots-and-queue/specs/cli-contract/spec.md create mode 100644 openspec/changes/phase-3-snapshots-and-queue/specs/memory-budget/spec.md create mode 100644 openspec/changes/phase-3-snapshots-and-queue/specs/proxy/spec.md create mode 100644 openspec/changes/phase-3-snapshots-and-queue/specs/seeding/spec.md create mode 100644 openspec/changes/phase-3-snapshots-and-queue/specs/snapshots/spec.md create mode 100644 openspec/changes/phase-3-snapshots-and-queue/specs/stack-gc/spec.md create mode 100644 openspec/changes/phase-3-snapshots-and-queue/specs/stack-list/spec.md create mode 100644 openspec/changes/phase-3-snapshots-and-queue/specs/stack-status/spec.md create mode 100644 openspec/changes/phase-3-snapshots-and-queue/specs/start-queue/spec.md create mode 100644 openspec/changes/phase-3-snapshots-and-queue/tasks.md diff --git a/openspec/changes/phase-3-snapshots-and-queue/.openspec.yaml b/openspec/changes/phase-3-snapshots-and-queue/.openspec.yaml index 0d31f8b..1bb6456 100644 --- a/openspec/changes/phase-3-snapshots-and-queue/.openspec.yaml +++ b/openspec/changes/phase-3-snapshots-and-queue/.openspec.yaml @@ -1,3 +1,2 @@ schema: spec-driven created: 2026-10-28 -skip_specs: true diff --git a/openspec/changes/phase-3-snapshots-and-queue/design.md b/openspec/changes/phase-3-snapshots-and-queue/design.md new file mode 100644 index 0000000..fd7737c --- /dev/null +++ b/openspec/changes/phase-3-snapshots-and-queue/design.md @@ -0,0 +1,130 @@ +# Design + +## Context + +v0.2 (archived as `2026-10-28-phase-2-overview-and-budget`) estimates a stack from limits and a +256 MiB default, refuses with exit 3 when it does not fit, starts every stack with empty +volumes, and lets every `up` build at once. The pieces this phase builds on: `budget.Check` and +`checkBudget` in `up`, `a.memory` (one-shot stats in parallel), the proxy's labels as settings +(`dev.siding.budget`), the losable cache `~/.siding`, and `status`'s polling loop. Motivation +and scope: see proposal.md; behaviour: see the delta specs. Constraints from CLAUDE.md: Docker +is the database, no background service, never lose work, the compose file is never edited. + +## Goals / Non-Goals + +**Goals:** +- Snapshots and seeding built only from Docker volumes, a helper container and `docker compose + exec`; no file format of siding's own. +- Queue and build slots without a service: the waiting `up` processes coordinate through files + under `~/.siding`, and a killed process never blocks the others. +- Every new behaviour testable with fakes; `just smoke-stacks` covers save, seed, the queue and + a build slot against the inner daemon. + +**Non-Goals:** +- Sharing snapshots between machines, exporting them as files, incremental snapshots. +- Seeding a stack that already has data (that is `down --volumes`, then `up --seed`). +- Priorities in the queue, or a queue across machines (v0.5 has remote hosts). +- Limiting anything but builds (pulls, starts). + +## Decisions + +### D1. Snapshots are Docker volumes (maintainer's decision) +A snapshot of repository `` named `` is one volume per own named volume of the +stack, `siding-snap---`, labelled `dev.siding.snapshot=`, +`dev.siding.snapshot-volume=`, `dev.siding.repo`, `dev.siding.machine`, and the time in +`dev.siding.snapshot-created`. Copies run in a short-lived helper container from the image +pinned in the binary (`busybox:1.37.0`, the devcontainer's `SIDING_BUSYBOX_IMAGE`) with +`cp -a /from/. /to/`, created, waited for and removed through the Engine API, pulled first when +missing. `save` stops the services that mount the volumes (`docker compose stop `), +copies, and starts them again (`docker compose start`), also when the copy fails. Alternatives, +asked: tar files in a directory the user picks (portable, but data outside Docker); seeding only +from the default branch's running stack (no command, but one state and only while that stack +exists). A live copy without stopping was rejected: a database copied mid-write may not start. + +### D2. "First up" instead of a marker (refines the approved option) +The approved option said siding would mark a seeded stack with a label on its volume. Docker +cannot change a volume's labels after creation, so the marker would need a second volume per +stack. A first `up` is instead detected before Compose runs: the project has neither containers +nor volumes. It is the same moment the marker would have recorded, with nothing to store. + +### D3. Seeding before Compose starts +For a first `up --seed `, siding resolves the snapshot (`SnapshotNotFound` otherwise), +then for each own named volume of the normalised config that the snapshot holds and no service +with `dev.siding.seed: none` uses, creates the volume under its Compose name with the labels +Compose sets itself (`com.docker.compose.project`, `com.docker.compose.volume`) plus siding's, +and copies the snapshot into it. Then Compose starts the stack and adopts the volumes. Tried +with Compose 5.6.1 before this proposal: with both Compose labels the volume is adopted +silently; without them Compose warns that it "was not created by Docker Compose". + +### D4. The seed command (maintainer's decision: a command in the service) +After `docker compose up -d` of a first `up`, siding waits for each service with +`dev.siding.seed: script` to be running (and healthy, if it has a healthcheck), at most +`--timeout`, then runs `docker compose exec -T sh -c `, +keeping the last 20 output lines. A non-zero exit becomes a failure with reason `SeedFailed` +that `verdict.Evaluate` reports before everything else; `up` without `--wait` then prints that +`Status` document and exits 1 instead of the `Stack` document. Alternatives, asked: a separate +seed service that runs once (needs the user to add a service); no `script` in v0.3. + +### D5. The queue (maintainer's decision: wait with `--wait`, else exit 3) +A waiting `up` writes `~/.siding/queue/-.json` (project, pid, estimate, +start time) and removes it when it ends, by any path, `defer` and the signal context included. +Every two seconds it lists the directory, drops entries whose process is gone (`kill -0`), +and only when it is the oldest entry checks the budget again; once the stack fits, it removes its +entry and starts as usual. A non-waiting `up` does not take part: it starts when it fits and +refuses otherwise, so it never waits behind a line it is not in. Alternatives, asked: always +wait (an `up` without `--wait` could hang unexpectedly); wait only with `--queue` (agents would +have to know the flag). Rejected: a lock-holding daemon (a background service). + +### D6. Build slots (maintainer's decision: slots around `compose up`) +`internal/compose` reads `build:`. If any service has it, `up` takes one of N files +`~/.siding/builds/slot-.lock` with a non-blocking `flock`, trying again every second and +printing once that it waits; the kernel releases the lock when the process ends, so a killed +`up` frees its slot at once. The slot is held for the whole `docker compose up`, which also +covers the start; precise build-only slots would need siding to run `docker compose build` +itself, which the maintainer rejected. N is the label `dev.siding.builds` on the proxy, set by +`setup --builds`, else half of the Docker daemon's CPUs (`docker info`'s `NCPU`, the VM's on +Docker Desktop), at least 1. Alternatives, asked: siding builds itself, then `up --no-build`; +a fixed N without a setting. + +### D7. Learned peaks +`internal/budget` gains a cache `~/.siding/peaks.json`: `{"/": bytes}`. Every +memory read (`ps`, `ui` through `ps`, `checkBudget`, and `status` once when the verdict is +Ready) records `max(old, now)` per container's repository and service, written atomically by +rename; a lost update between two siding processes only loses a sample. The estimate per +service is `min(peak × 1.25, limit)` with a peak, else the limit, else 256 MiB. Keyed by +repository and service, not branch, so every new branch profits from what `main` used. The +margin covers that one-shot stats see the current use, not the maximum. Alternatives: a peak +per branch (new branches would learn nothing); averaging (underestimates spikes); cgroup +`max_usage` (only cgroup v1). + +### D8. teardown and gc +`teardown --snapshots` lists and removes the volumes labelled `dev.siding.snapshot` of this +machine; without the flag it names them. `gc` and `down --volumes` select volumes by Compose +project, which snapshot volumes do not carry, so they cannot remove snapshots; a test pins it. + +### D9. Labels, codes, documents +New labels `dev.siding.snapshot`, `dev.siding.snapshot-volume`, `dev.siding.snapshot-created` +(volumes), `dev.siding.seed.command` (service), `dev.siding.builds` (proxy); they go into the +conventions of CLAUDE.md and `openspec/config.yaml`. New error codes `SnapshotNotFound`, +`SnapshotExists`; new kinds `Snapshot` (save, rm) and `SnapshotList`; `Setup` gains `builds`, +`StackList` gains `waiting`, `Teardown` gains `snapshots`. The verdict gains `SeedFailed`. + +## Risks / Trade-offs + +- [Saving stops the services of a running stack] → `save` says so before it stops them; + agents rarely save, humans do it between tasks. +- [Copying big volumes takes long] → `cp -a` inside the daemon, no data passes through siding; + progress is the helper container's runtime, printed every 10 seconds. +- [A peak from a heavy test run inflates estimates] → capped at the limit; `peaks.json` can be + deleted, it is a cache. +- [Compose changes how it adopts volumes] → the labels are what Compose 5.6 sets itself; the + end-to-end test seeds a stack and checks that Compose prints no warning. +- [`flock` on a network home directory] → `~/.siding` is local on macOS and Linux desktops; + noted in the README. +- [Two waiting `up`s on different machines with one remote daemon] → out of scope until v0.5. + +## Migration Plan + +Nothing to migrate. A proxy of v0.2 has no `dev.siding.builds` label and uses the default; the +next `setup --builds` adds it. `~/.siding` gains `peaks.json`, `queue/` and `builds/` on first +use. diff --git a/openspec/changes/phase-3-snapshots-and-queue/proposal.md b/openspec/changes/phase-3-snapshots-and-queue/proposal.md index d5af81a..ee613e1 100644 --- a/openspec/changes/phase-3-snapshots-and-queue/proposal.md +++ b/openspec/changes/phase-3-snapshots-and-queue/proposal.md @@ -1,27 +1,58 @@ # Proposal -> Draft. This change holds the roadmap text only and is marked `skip_specs: true`. -> `/opsx:propose` turns it into a full change: it writes the delta specs, `design.md` and -> `tasks.md`, revises this proposal, and removes `skip_specs` from `.openspec.yaml`. - ## Why -New stacks start empty and many at once overload the machine. Seeded data and a queue make -parallel branches cheap to start. +v0.2 keeps the machine usable, but new stacks start empty, every agent has to wait until its +database is filled by hand, and a stack that does not fit is simply refused. With several +agents starting at once, the machine also stalls on parallel image builds. v0.3 makes parallel +branches cheap to start: with data from a snapshot or a seed command, in turn when memory is +short, a few builds at a time, and with estimates learned from what stacks really use. ## What Changes -Roadmap v0.3: - -- Snapshots of volumes and `--seed` (`dev.siding.seed`: `volume|script|none`). -- A queue for capacity instead of refusing. -- A limit on parallel builds. -- Learned memory peaks, kept in the losable cache under `~/.siding`. +- `siding snapshot save `, `snapshot ls`, `snapshot rm `: copies of a stack's named + volumes, kept as Docker volumes labelled `dev.siding.snapshot`, per repository. `save` stops + the services using the volumes while it copies, so databases are consistent. +- `siding up --seed `: on a stack's first `up`, its volumes start as copies of the + snapshot. The service label `dev.siding.seed` chooses per service: `volume` (the default with + `--seed`), `none`, or `script` with `dev.siding.seed.command`, a command siding runs once in + the service on the first `up`; a failing command gives the verdict reason `SeedFailed`. +- Queue: `up --wait` that does not fit into the budget waits in line, in order of arrival, + until memory frees or `--timeout` is up (then exit 3). Without `--wait`, `up` still refuses + with exit 3. `ps`, `siding ui` and the `StackList` document show who waits. +- Build limit: `up` of a project with `build:` services holds one of N build slots while Compose + runs; `siding setup --builds N` sets N (default: half the CPUs) as a label on the proxy. +- Learned peaks: whenever siding reads a stack's memory, it keeps the highest use per + repository and service in `~/.siding/peaks.json` (a losable cache); the estimate prefers a + learned peak with a margin over the 256 MiB default. +- `siding teardown --snapshots` also removes this machine's snapshots; `gc` never does. ## Capabilities -To be decided at `/opsx:propose`. +### New Capabilities +- `snapshots`: `siding snapshot save|ls|rm`, how snapshots are named, labelled and copied. +- `seeding`: `up --seed`, `dev.siding.seed` (`volume`, `none`, `script`) and + `dev.siding.seed.command`, and what "first `up`" means. +- `start-queue`: waiting in line for memory with `up --wait`, its order and timeout. +- `build-limit`: build slots, `setup --builds`. + +### Modified Capabilities +- `memory-budget`: the estimate uses learned peaks; a new requirement for learning them. +- `stack-status`: the reason `SeedFailed`. +- `cli-contract`: exit 3 after waiting in line; the error codes `SnapshotNotFound` and + `SnapshotExists`. +- `proxy`: `setup --builds` and the builds in the `Setup` document; `teardown --snapshots`. +- `stack-list`: the queue in `ps` and in the `StackList` document. +- `stack-gc`: gc never removes snapshots. ## Impact -To be decided at `/opsx:propose`. +- New packages for snapshots and seeding (helper containers through the Docker API), the + queue and build slots (file locks under `~/.siding`, no service), learned peaks; new + commands `snapshot save|ls|rm`. +- `internal/compose` reads `build:`; `internal/docker` creates and copies volumes and runs + `exec` through Compose. +- New labels `dev.siding.snapshot`, `dev.siding.snapshot-volume`, `dev.siding.snapshot-created`, + `dev.siding.seed.command`, + `dev.siding.builds`: CLAUDE.md and `openspec/config.yaml` conventions; `~/.siding` holds + `peaks.json`, `queue/` and `builds/`, all losable. diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/build-limit/spec.md b/openspec/changes/phase-3-snapshots-and-queue/specs/build-limit/spec.md new file mode 100644 index 0000000..1dae010 --- /dev/null +++ b/openspec/changes/phase-3-snapshots-and-queue/specs/build-limit/spec.md @@ -0,0 +1,34 @@ +# Spec Delta + +## Purpose + +Defines the limit on image builds that run at the same time, so that many agents starting at +once do not stall the machine with parallel builds. + +## ADDED Requirements + +### Requirement: Build slots +`siding up` of a project with at least one service with `build:` SHALL hold one of N build +slots on this machine while `docker compose up` runs, waiting for a free one first, and print +on stderr that it waits. A project without `build:` MUST NOT need a slot. Waiting for a slot +counts against `--timeout`. + +#### Scenario: Two builds, one slot +- **WHEN** N is 1 and two `up`s of projects with `build:` start at the same moment +- **THEN** one runs `docker compose up` while the other waits, then the other runs + +#### Scenario: No build +- **WHEN** all build slots are held and `up` runs for a project of images only +- **THEN** it starts without waiting + +#### Scenario: A killed build +- **WHEN** the process holding a slot is killed +- **THEN** the slot is free again at once + +### Requirement: Number of slots +N SHALL be the label `dev.siding.builds` on `siding-proxy`, set with `siding setup --builds N` +and kept by later `setup`s, and half the CPUs of this machine (at least 1) without the label. + +#### Scenario: Default +- **WHEN** the machine has 8 CPUs and the proxy has no builds label +- **THEN** N is 4 diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/cli-contract/spec.md b/openspec/changes/phase-3-snapshots-and-queue/specs/cli-contract/spec.md new file mode 100644 index 0000000..f64ea80 --- /dev/null +++ b/openspec/changes/phase-3-snapshots-and-queue/specs/cli-contract/spec.md @@ -0,0 +1,42 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Error document +A command that fails SHALL exit 1, or 3 for `NoCapacity`. With `--json` it SHALL print a +document of kind `Error` with a stable `code` and a human-readable `message`; without `--json` +it SHALL print `error: ` on stderr, followed by a hint line when there is one. + +#### Scenario: An unknown flag with --json +- **WHEN** `siding version --json --nope` runs +- **THEN** it exits 1 and prints an `Error` document with `code` `InvalidArguments`, even though flag parsing failed before `--json` was read + +#### Scenario: A failure without --json +- **WHEN** `siding up` runs outside a git repository +- **THEN** it exits 1 and prints `error: …` and a hint on stderr, and nothing on stdout + +#### Scenario: The error codes +- **WHEN** a command fails +- **THEN** its code is one of `InvalidArguments`, `NotAGitRepository`, `NoBranch`, `ComposeFileNotFound`, `ComposeFailed`, `DockerUnavailable`, `ProxyNotRunning`, `PortInUse`, `InvalidRoute`, `AmbiguousPort`, `SlugCollision`, `StackNotFound`, `UnmergedBranch`, `DirtyWorktree`, `NoCapacity`, `NotInteractive`, `SnapshotNotFound`, `SnapshotExists`, or `Internal` for an unexpected error + +#### Scenario: No capacity +- **WHEN** `siding up --json` refuses because the stack does not fit into the memory budget +- **THEN** it prints an `Error` document with `code` `NoCapacity` and exits 3 + +### Requirement: Exit codes +siding SHALL exit 0 on success and when a stack is Ready, 1 when a command fails or a stack is +Failed, 2 when a stack is not Ready in time (TimedOut, or Starting without `--wait`), 3 when +`up` refuses for lack of memory or waited in line until `--timeout` (NoCapacity), and 130 +without a message when interrupted. + +#### Scenario: A verdict decides the exit code +- **WHEN** `siding status --wait` ends with the verdict Failed +- **THEN** it exits 1, and with Ready it exits 0 + +#### Scenario: Interrupted +- **WHEN** the user presses Ctrl-C during `siding logs -f` +- **THEN** siding stops docker compose and exits 130 without an error message + +#### Scenario: Over budget +- **WHEN** `siding up --wait` waits in line for memory until `--timeout` is up +- **THEN** it exits 3 without starting a container diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/memory-budget/spec.md b/openspec/changes/phase-3-snapshots-and-queue/specs/memory-budget/spec.md new file mode 100644 index 0000000..562715a --- /dev/null +++ b/openspec/changes/phase-3-snapshots-and-queue/specs/memory-budget/spec.md @@ -0,0 +1,40 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Estimate of a stack +The estimate of a stack SHALL be the sum over its services, once per replica, of the learned +peak of the service plus a quarter, capped at its memory limit; without a learned peak, of the +memory limit (`deploy.resources.limits.memory`, else `mem_limit`); without either, 256 MiB. + +#### Scenario: Limits and defaults +- **WHEN** a stack has `db` with `mem_limit: 1g`, `web` with no limit and `api` with `deploy.resources.limits.memory: 512m`, and siding has learned no peak +- **THEN** its estimate is 1 GiB + 256 MiB + 512 MiB + +#### Scenario: A learned peak +- **WHEN** siding has seen `web` of the repository `shop` use at most 400 MiB, and `web` has no limit +- **THEN** `web` counts 500 MiB + +#### Scenario: Capped by the limit +- **WHEN** `db` has `mem_limit: 1g` and a learned peak of 900 MiB +- **THEN** `db` counts 1 GiB, not 1125 MiB + +## ADDED Requirements + +### Requirement: Learned peaks +Whenever siding reads the memory of running containers (`ps`, `ui`, `status`, `up`), it SHALL +keep the highest use seen per repository and service in `~/.siding/peaks.json`. The file is a +losable cache: without it, or when it cannot be read, estimates fall back to limits and +defaults, and siding writes a new one. + +#### Scenario: A peak is learned +- **WHEN** `siding ps` reads 400 MiB for `web` of `shop`, and later 300 MiB +- **THEN** `peaks.json` holds 400 MiB for `shop/web` + +#### Scenario: Branches share what they learn +- **WHEN** siding learned 400 MiB for `web` from the stack of `main` +- **THEN** the estimate for a new stack of `feature/x` of `shop` uses it + +#### Scenario: The cache is lost +- **WHEN** `~/.siding/peaks.json` is deleted or holds no valid JSON +- **THEN** siding works as without learned peaks and starts learning anew diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/proxy/spec.md b/openspec/changes/phase-3-snapshots-and-queue/specs/proxy/spec.md new file mode 100644 index 0000000..9e2c193 --- /dev/null +++ b/openspec/changes/phase-3-snapshots-and-queue/specs/proxy/spec.md @@ -0,0 +1,48 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Setup starts the proxy +`siding setup` SHALL create the network `siding` if it is missing and run the Compose project +`siding` with one container `siding-proxy`: Traefik with the Docker provider on the network +`siding`, restarting unless stopped. It SHALL print the proxy's address, budget and number of +build slots, with `--json` as a `Setup` document. + +#### Scenario: First setup +- **WHEN** `siding setup` runs on a machine without the proxy +- **THEN** the network `siding` and the running container `siding-proxy` exist, and it prints `http://*.localhost` as the address + +#### Scenario: JSON +- **WHEN** `siding setup --json` runs +- **THEN** it prints a `Setup` document with the proxy's container name, network, image, port, budget in bytes and build slots + +#### Scenario: Build slots +- **WHEN** `siding setup --builds 2` runs, and later `siding setup` without `--builds` +- **THEN** `siding-proxy` carries `dev.siding.builds=2` after both + +### Requirement: Teardown removes the proxy +`siding teardown` SHALL remove `siding-proxy`, its files under `~/.siding/proxy/`, and the +network `siding` unless a container still uses it, and with `--snapshots` also every snapshot of +this machine. It MUST NOT touch any stack: running stacks keep running as plain Compose +projects, and teardown names them. `--dry-run` removes nothing; with `--json` it prints a +`Teardown` document. + +#### Scenario: Nothing runs but the proxy +- **WHEN** `siding teardown` runs and no stack exists +- **THEN** `siding-proxy`, the network `siding` and `~/.siding/proxy/` are gone, and `~/.siding/machine-id` stays + +#### Scenario: A stack still runs +- **WHEN** `siding teardown` runs while the stack `shop-main` runs +- **THEN** the proxy is removed, the network `siding` stays because `shop-main` uses it, `shop-main` keeps running, and the output names it with the hint `siding down` or `siding gc` + +#### Scenario: Dry run +- **WHEN** `siding teardown --dry-run --json` runs +- **THEN** it prints a `Teardown` document with `dryRun: true` listing the proxy and the network, and removes nothing + +#### Scenario: No proxy +- **WHEN** `siding teardown` runs on a machine without `siding-proxy` +- **THEN** it reports that there is nothing to remove and exits 0 + +#### Scenario: Snapshots +- **WHEN** `siding teardown` runs without `--snapshots` and snapshots exist +- **THEN** the snapshots stay and teardown names them; with `--snapshots` they are removed too diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/seeding/spec.md b/openspec/changes/phase-3-snapshots-and-queue/specs/seeding/spec.md new file mode 100644 index 0000000..f865a86 --- /dev/null +++ b/openspec/changes/phase-3-snapshots-and-queue/specs/seeding/spec.md @@ -0,0 +1,54 @@ +# Spec Delta + +## Purpose + +Defines how a new stack starts with data: its volumes copied from a snapshot, or a seed command +run once in a service, chosen per service with `dev.siding.seed`. + +## ADDED Requirements + +### Requirement: First up +A stack's first `up` SHALL be one where its Compose project has neither containers nor volumes +before siding starts it. Seeding happens only on a first `up`; later `up`s never seed again. + +#### Scenario: Second up +- **WHEN** `siding up --seed base` runs for a stack whose volumes exist +- **THEN** nothing is seeded, the data stays, and a warning says the stack already has data and names `siding down --volumes` + +### Requirement: Seed from a snapshot +On a first `up --seed `, siding SHALL create each own named volume of the project +that the snapshot holds as a copy of it, before Compose starts the stack, labelled so that +Compose adopts it. Volumes the snapshot lacks start empty. An unknown snapshot MUST fail with +`SnapshotNotFound` before anything starts. + +#### Scenario: A new branch with data +- **WHEN** `siding up --seed base --wait` runs in a new worktree of `shop` +- **THEN** the stack's `data` volume holds what `data` held when `base` was saved, and the verdict is Ready + +#### Scenario: Unknown snapshot +- **WHEN** `siding up --seed nope` runs +- **THEN** it fails with `SnapshotNotFound`, lists the repository's snapshots in the hint, and starts nothing + +### Requirement: Seed per service +The service label `dev.siding.seed` SHALL choose how a service's volumes are seeded: `volume` +(from the snapshot given with `--seed`; also when the label is missing), `none` (never), or +`script`. A volume used by a service with `none` MUST NOT be seeded. Another value MUST fail +`up` with `InvalidArguments`, naming the service. + +#### Scenario: none +- **WHEN** `cache` carries `dev.siding.seed: none` and `up --seed base` runs first +- **THEN** the volume of `cache` starts empty, and the others come from `base` + +### Requirement: Seed command +A service with `dev.siding.seed: script` SHALL carry `dev.siding.seed.command`, which siding runs +once in the service with `docker compose exec` on the first `up`, as soon as the service is +running and healthy if it has a healthcheck. Without the command label, `up` MUST fail with +`InvalidArguments`. + +#### Scenario: A seed command +- **WHEN** `db` carries `dev.siding.seed: script` and `dev.siding.seed.command: "psql -f /seed.sql"`, and the first `up --wait` runs +- **THEN** siding runs the command in `db` once, then reports the verdict + +#### Scenario: The command fails +- **WHEN** the seed command exits with code 2 +- **THEN** the verdict is `Failed` with service `db`, reason `SeedFailed`, the exit code in the hint and the command's last output lines as the log tail diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/snapshots/spec.md b/openspec/changes/phase-3-snapshots-and-queue/specs/snapshots/spec.md new file mode 100644 index 0000000..601cd3f --- /dev/null +++ b/openspec/changes/phase-3-snapshots-and-queue/specs/snapshots/spec.md @@ -0,0 +1,56 @@ +# Spec Delta + +## Purpose + +Defines snapshots: named copies of a stack's volumes, kept in Docker, from which new stacks of +the same repository can start with data instead of empty. + +## ADDED Requirements + +### Requirement: Save a snapshot +`siding snapshot save ` SHALL copy every own named volume of the worktree's stack into a +new volume per volume, labelled `dev.siding.snapshot=`, `dev.siding.snapshot-volume=`, +`dev.siding.repo` and `dev.siding.machine`. It MUST stop the services that use those volumes +while copying and start them again afterwards. + +#### Scenario: Save +- **WHEN** `siding snapshot save base` runs in the stack `shop-main` with the volumes `data` and `uploads` +- **THEN** two snapshot volumes with `dev.siding.snapshot=base` exist, and `db` and `web`, which use them, run again + +#### Scenario: No volumes +- **WHEN** the stack has no named volumes +- **THEN** `snapshot save` fails with `InvalidArguments` and says there is nothing to save + +### Requirement: Snapshot names +A snapshot name SHALL be unique per repository and consist of lowercase letters, digits and +`-`. `save` MUST fail with `SnapshotExists` when the name is taken, unless `--force` replaces it. + +#### Scenario: Taken +- **WHEN** `siding snapshot save base` runs and `base` exists for the repository +- **THEN** it fails with `SnapshotExists`, and with `--force` the old snapshot is replaced + +#### Scenario: Another repository +- **WHEN** the repositories `shop` and `blog` both save a snapshot `base` +- **THEN** both exist side by side + +### Requirement: List and remove +`siding snapshot ls` SHALL list the snapshots of this machine, of the current repository when +run in one, with name, repository, volumes, size where Docker reports it, and creation time; +`--json` prints a `SnapshotList` document. `siding snapshot rm ` SHALL remove one, with +`--dry-run`, and fail with `SnapshotNotFound` for an unknown name. + +#### Scenario: List +- **WHEN** `siding snapshot ls --json` runs in the repository `shop` with the snapshots `base` and `big` +- **THEN** it prints a `SnapshotList` document with both and their volumes + +#### Scenario: Remove +- **WHEN** `siding snapshot rm big` runs +- **THEN** the volumes of `big` are gone and `base` stays + +### Requirement: Snapshots outlive stacks +Snapshots MUST NOT be removed by `down --volumes` or `gc`; only `snapshot rm` and +`teardown --snapshots` remove them. + +#### Scenario: The stack goes +- **WHEN** `siding down --volumes --force` removes the stack a snapshot was saved from +- **THEN** the snapshot still exists and can seed a new stack diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/stack-gc/spec.md b/openspec/changes/phase-3-snapshots-and-queue/specs/stack-gc/spec.md new file mode 100644 index 0000000..dd570d2 --- /dev/null +++ b/openspec/changes/phase-3-snapshots-and-queue/specs/stack-gc/spec.md @@ -0,0 +1,29 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: What gc removes +`siding gc` SHALL consider the stacks of this machine and remove: for a merged branch, the +stack's containers, networks and volumes (reason `Merged`); for a stack whose worktree no +longer exists, its containers and networks, and its volumes only if the branch is merged +(reason `WorktreeGone`). It MUST NOT touch git worktrees, branches or snapshots. + +#### Scenario: A deleted worktree with an unmerged branch +- **WHEN** the worktree of `feature/wip` was deleted, but the branch has commits `main` lacks +- **THEN** gc removes its containers and networks, keeps its volumes, and reports them as kept + +#### Scenario: A stack from an older siding +- **WHEN** a stack without the label `dev.siding.gitdir` has lost its worktree +- **THEN** gc removes its containers and networks and keeps its volumes, since it cannot tell whether the branch is merged + +#### Scenario: Work in progress +- **WHEN** a worktree has uncommitted changes or its branch is not merged +- **THEN** gc removes nothing of its stack and lists it as kept with the reason `Dirty` or `Unmerged` + +#### Scenario: Worktrees stay +- **WHEN** gc removes the stack of a merged branch +- **THEN** the worktree directory and the branch still exist + +#### Scenario: Snapshots stay +- **WHEN** gc removes the stack of a merged branch from which the snapshot `base` was saved +- **THEN** `base` still exists diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/stack-list/spec.md b/openspec/changes/phase-3-snapshots-and-queue/specs/stack-list/spec.md new file mode 100644 index 0000000..e2eecb2 --- /dev/null +++ b/openspec/changes/phase-3-snapshots-and-queue/specs/stack-list/spec.md @@ -0,0 +1,17 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: StackList document +With `--json`, `ps` SHALL print one `StackList` document with one entry per stack: project, +repository, branch, worktree, machine, agent, state, address, memory in bytes, and +`worktreeMissing` when the worktree is gone; the total memory and the budget in bytes; and the +stacks waiting in line, with project, place, memory needed and since when. + +#### Scenario: No stacks +- **WHEN** `siding ps --json` runs and no stack exists +- **THEN** it prints a `StackList` document without stacks, with the budget, and exits 0 + +#### Scenario: A stack waits +- **WHEN** `shop-feature-x` waits in line for memory +- **THEN** the `StackList` document lists it under `waiting` with place 1 diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/stack-status/spec.md b/openspec/changes/phase-3-snapshots-and-queue/specs/stack-status/spec.md new file mode 100644 index 0000000..eaabe78 --- /dev/null +++ b/openspec/changes/phase-3-snapshots-and-queue/specs/stack-status/spec.md @@ -0,0 +1,21 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Failed +A stack SHALL be `Failed` as soon as a service has exited with a non-zero code, is unhealthy, +keeps restarting, has no container, or its seed command failed; the failure MUST name the +service, a reason (`Exited`, `Unhealthy`, `Restarting`, `Missing`, `NotAnswering`, +`SeedFailed`), a hint, and the last 20 log lines of that service or of its seed command. + +#### Scenario: A service exits +- **WHEN** `api` exits with code 1 after printing `cannot connect to db` +- **THEN** the verdict is `Failed` with service `api`, reason `Exited`, the exit code in the hint, and the log tail containing `cannot connect to db` + +#### Scenario: Unhealthy +- **WHEN** `db`'s healthcheck reports unhealthy +- **THEN** the verdict is `Failed` with reason `Unhealthy`, and the hint contains the last healthcheck output + +#### Scenario: Seed failed +- **WHEN** the seed command of `db` exits with code 2 on the first `up --wait` +- **THEN** the verdict is `Failed` with service `db`, reason `SeedFailed`, and the command's output as the log tail diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/start-queue/spec.md b/openspec/changes/phase-3-snapshots-and-queue/specs/start-queue/spec.md new file mode 100644 index 0000000..ecbbc29 --- /dev/null +++ b/openspec/changes/phase-3-snapshots-and-queue/specs/start-queue/spec.md @@ -0,0 +1,43 @@ +# Spec Delta + +## Purpose + +Defines how stacks that do not fit into the memory budget wait their turn instead of being +refused, without a background service. + +## ADDED Requirements + +### Requirement: Waiting in line +When a stack does not fit into the budget, `siding up --wait` SHALL wait in line instead of +refusing, until it fits or `--timeout` is up, and then start it as usual. Without `--wait`, +`up` SHALL refuse with `NoCapacity` and exit 3 as before. + +#### Scenario: Memory frees +- **WHEN** `siding up --wait` waits because the budget is full, and another stack is taken down +- **THEN** the waiting stack starts within a few seconds and the command ends with its verdict + +#### Scenario: Time is up +- **WHEN** nothing frees memory before `--timeout` +- **THEN** `up` exits 3 with `NoCapacity`, its place in line and the memory it needs, and starts nothing + +### Requirement: First come, first served +Stacks SHALL start in the order they began to wait: only the first one in line may start, even +if a later one would fit. A waiting `up` that ended (stopped, killed, timed out) MUST leave the +line. + +#### Scenario: Order +- **WHEN** `a` began to wait before `b`, and memory frees enough for `b` but not for `a` +- **THEN** `b` keeps waiting until `a` has started + +#### Scenario: A killed waiter +- **WHEN** the process of the first waiting `up` was killed +- **THEN** the next one moves up within a few seconds + +### Requirement: The line is visible +`siding ps` and `siding ui` SHALL list the stacks waiting in line with project, place, memory +needed and since when they wait, and the waiting `up` SHALL print its place on stderr when it +changes. + +#### Scenario: ps while waiting +- **WHEN** `shop-feature-x` waits in line +- **THEN** `siding ps` shows it under "waiting" with its place and the memory it needs diff --git a/openspec/changes/phase-3-snapshots-and-queue/tasks.md b/openspec/changes/phase-3-snapshots-and-queue/tasks.md new file mode 100644 index 0000000..70a3e43 --- /dev/null +++ b/openspec/changes/phase-3-snapshots-and-queue/tasks.md @@ -0,0 +1,53 @@ +# Tasks + +## 1. Foundations + +- [ ] 1.1 Add the error codes `SnapshotNotFound` and `SnapshotExists`; verify with the error-code table test +- [ ] 1.2 Read `build:` in `internal/compose` (a `Build` flag per service); verify with a captured config with and without `build:` +- [ ] 1.3 Add to `internal/docker`: create a volume with labels, volumes by label with sizes from `/system/df`, remove a volume, run a helper container (pull if missing, create, start, wait, remove) and `NCPU` from `docker info`; verify with unit tests of the mappings and the helper's container config +- [ ] 1.4 Add the new labels (D9) to the conventions in CLAUDE.md and `openspec/config.yaml`; verify `openspec validate --all --strict` passes + +## 2. Learned peaks + +- [ ] 2.1 Implement `~/.siding/peaks.json` in `internal/budget` (read, record max, atomic write, a missing or broken file is empty) and the estimate of D7; verify with table tests for the spec scenarios of `memory-budget`, a broken file and a cap at the limit +- [ ] 2.2 Record peaks from `ps`, `checkBudget` and a Ready `status`, and use them in `up`'s estimate; verify with fake-based tests that a peak seen by `ps` changes the next `up`'s estimate +- [ ] 2.3 Document learned peaks in the README's budget section; verify the shown path and behaviour match the code + +## 3. Snapshots + +- [ ] 3.1 Implement snapshot naming, labels and the copy plan in a pure package (D1); verify with table tests for names, slugs, repositories and `SnapshotExists` +- [ ] 3.2 Implement `siding snapshot save [--force] [--json]`: stop the services that mount the volumes, copy with the helper, start them again also on failure; verify with fake-based tests (order of compose stop, copies, compose start; failure in the middle; no volumes) and a `snapshot.json` golden +- [ ] 3.3 Implement `siding snapshot ls [--json]` and `siding snapshot rm [--dry-run] [--json]`; verify with fake-based tests and a `snapshotlist.json` golden +- [ ] 3.4 Add `teardown --snapshots` and the snapshots `teardown` names without it; verify with fake-based tests and the updated `teardown*.json` goldens +- [ ] 3.5 Document snapshots in the README; verify the shown commands run as written in the devcontainer + +## 4. Seeding + +- [ ] 4.1 Detect a first `up` (D2) and validate `dev.siding.seed` and `dev.siding.seed.command`; verify with fake-based tests for first and later `up`s and the `InvalidArguments` cases +- [ ] 4.2 Implement `up --seed ` (D3): resolve the snapshot, create the volumes with Compose's labels, copy, then run Compose; a later `up` warns and seeds nothing; verify with fake-based tests per scenario of the spec `seeding` +- [ ] 4.3 Implement the seed command (D4) and the reason `SeedFailed` in `internal/verdict`; verify with verdict table tests and fake-based tests of `up` and `up --wait` with a failing command +- [ ] 4.4 Document seeding in the README (`--seed`, `dev.siding.seed`, `dev.siding.seed.command`); verify the example labels are accepted by `siding lint` + +## 5. Queue + +- [ ] 5.1 Implement the line in `~/.siding/queue` (D5): enter, leave on every exit path, drop dead entries, the oldest entry first; verify with unit tests using fake pids and a temporary home +- [ ] 5.2 Make `up --wait` wait in line when the stack does not fit, recheck every two seconds, print its place on stderr, and exit 3 at `--timeout`; `up` without `--wait` keeps refusing; verify with fake-based tests using the fake clock (memory frees, time is up, order, a killed waiter) +- [ ] 5.3 Show the line in `ps` (text and `waiting` in `StackList`) and in `siding ui`; verify with the updated `stacklist.json` golden and the page golden +- [ ] 5.4 Document the queue in the README; verify the shown behaviour matches the tests + +## 6. Build limit + +- [ ] 6.1 Implement build slots with `flock` under `~/.siding/builds` (D6); verify with unit tests that N holders exclude the N+1st and that closing a holder frees its slot +- [ ] 6.2 Hold a slot around `docker compose up` for projects with `build:`, count waiting against `--timeout`, and add `setup --builds` with the label carried forward and `builds` in `Setup`; verify with fake-based tests and the updated `setup.json` golden +- [ ] 6.3 Document the build limit in the README; verify the commands run as written + +## 7. End-to-end and integration + +- [ ] 7.1 Extend `internal/e2e`: save a snapshot of a stack with data, seed a new branch from it and read the data back, a seed command that writes a file and one that fails with `SeedFailed`, `gc` and `down --volumes` leaving the snapshot, `snapshot rm`; a second `up --wait` that waits in line and starts after `down` of the first; two builds with `--builds 1` running one after the other; verify with `just smoke-stacks` and that no `siding-test-*` object is left, snapshots included +- [ ] 7.2 Run the flow by hand in the devcontainer and on the Mac (`just build-darwin`): `snapshot save`, `up --seed` in a second worktree, a queue with a small budget, `ps` and `siding ui` showing the line; record the result in the phase summary +- [ ] 7.3 Update the status in CLAUDE.md, the README and `openspec/config.yaml` to v0.3; verify `just test` passes + +## Workflow follow-up + +- Stop and show the result; wait for the maintainer's approval of Phase 3. +- `/opsx:archive` merges the deltas into `openspec/specs/`. From da54cdfd5609fe0b0a81b3d9eb4e7debeddc4571 Mon Sep 17 00:00:00 2001 From: tweinmann Date: Thu, 29 Oct 2026 15:11:00 +0000 Subject: [PATCH 2/2] Implement and archive phase 3: snapshots and queue (v0.3) - siding snapshot save|ls|rm: copies of a stack's named volumes as Docker volumes labelled dev.siding.snapshot, per repository - siding up --seed on a stack's first up; dev.siding.seed (volume, none, script) and dev.siding.seed.command, verdict SeedFailed - up --wait waits in line for memory, first come first served; ps, ui and StackList show the line - build slots around docker compose up for projects with build:, set by siding setup --builds - learned memory peaks per repository and service in ~/.siding/peaks.json - teardown --snapshots; gc and down --volumes never remove snapshots - down finds a stack by its volumes when only its data is left - small fixes from the manual run on macOS: README on curl and *.localhost, up --seed says what it seeds, <1 MiB, down mentions kept volumes only when there are any The deltas are merged into openspec/specs/ and the change is archived as openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 22 +- README.md | 76 ++++- cmd/siding/main.go | 9 + hack/smoke/stacks.sh | 7 +- internal/budget/budget.go | 20 +- internal/budget/peaks.go | 101 +++++++ internal/budget/peaks_test.go | 67 ++++ internal/buildslot/buildslot.go | 49 +++ internal/buildslot/buildslot_test.go | 34 +++ internal/cli/buildslot_test.go | 75 +++++ internal/cli/cli.go | 9 + internal/cli/cli_test.go | 3 +- internal/cli/down.go | 26 +- internal/cli/down_test.go | 29 ++ internal/cli/env_test.go | 78 ++++- internal/cli/json.go | 78 ++++- internal/cli/ps.go | 51 +++- internal/cli/ps_test.go | 20 ++ internal/cli/queue_test.go | 103 +++++++ internal/cli/seed_test.go | 121 ++++++++ internal/cli/setup.go | 38 ++- internal/cli/setup_test.go | 22 +- internal/cli/snapshot.go | 285 ++++++++++++++++++ internal/cli/snapshot_test.go | 168 +++++++++++ internal/cli/stack.go | 17 ++ internal/cli/status.go | 23 +- internal/cli/teardown.go | 35 ++- internal/cli/teardown_test.go | 22 ++ internal/cli/testdata/json/setup.json | 3 +- internal/cli/testdata/json/snapshot.json | 14 + internal/cli/testdata/json/snapshotlist.json | 25 ++ internal/cli/testdata/json/stacklist.json | 10 +- internal/cli/testdata/ui/page.html | 10 + internal/cli/ui.go | 3 +- internal/cli/ui/page.html | 10 + internal/cli/up.go | 256 ++++++++++++++-- internal/cli/up_test.go | 29 +- internal/compose/compose.go | 25 +- internal/compose/config.go | 16 +- internal/compose/config_test.go | 21 +- .../compose/testdata/build/app/Dockerfile | 1 + internal/compose/testdata/build/compose.yaml | 6 + internal/compose/testdata/build/config.json | 30 ++ internal/docker/docker.go | 127 +++++++- internal/docker/docker_test.go | 14 + internal/e2e/e2e_test.go | 25 +- internal/e2e/phase3_test.go | 225 ++++++++++++++ internal/fail/fail.go | 4 + internal/proxy/proxy.go | 5 + internal/queue/queue.go | 98 ++++++ internal/queue/queue_test.go | 62 ++++ internal/seed/seed.go | 85 ++++++ internal/seed/seed_test.go | 59 ++++ internal/snapshot/snapshot.go | 139 +++++++++ internal/snapshot/snapshot_test.go | 73 +++++ internal/stack/identity.go | 1 + internal/verdict/verdict.go | 7 + internal/verdict/verdict_test.go | 9 + justfile | 2 + .../.openspec.yaml | 0 .../design.md | 7 +- .../proposal.md | 2 + .../specs/build-limit/spec.md | 0 .../specs/cli-contract/spec.md | 0 .../specs/memory-budget/spec.md | 0 .../specs/proxy/spec.md | 0 .../specs/seeding/spec.md | 0 .../specs/snapshots/spec.md | 0 .../specs/stack-gc/spec.md | 0 .../specs/stack-lifecycle/spec.md | 26 ++ .../specs/stack-list/spec.md | 0 .../specs/stack-status/spec.md | 0 .../specs/start-queue/spec.md | 0 .../tasks.md | 55 ++-- openspec/config.yaml | 12 +- openspec/specs/build-limit/spec.md | 33 ++ openspec/specs/cli-contract/spec.md | 7 +- openspec/specs/memory-budget/spec.md | 34 ++- openspec/specs/proxy/spec.md | 21 +- openspec/specs/seeding/spec.md | 53 ++++ openspec/specs/snapshots/spec.md | 55 ++++ openspec/specs/stack-gc/spec.md | 6 +- openspec/specs/stack-lifecycle/spec.md | 12 +- openspec/specs/stack-list/spec.md | 7 +- openspec/specs/stack-status/spec.md | 10 +- openspec/specs/start-queue/spec.md | 42 +++ 86 files changed, 3179 insertions(+), 185 deletions(-) create mode 100644 internal/budget/peaks.go create mode 100644 internal/budget/peaks_test.go create mode 100644 internal/buildslot/buildslot.go create mode 100644 internal/buildslot/buildslot_test.go create mode 100644 internal/cli/buildslot_test.go create mode 100644 internal/cli/queue_test.go create mode 100644 internal/cli/seed_test.go create mode 100644 internal/cli/snapshot.go create mode 100644 internal/cli/snapshot_test.go create mode 100644 internal/cli/testdata/json/snapshot.json create mode 100644 internal/cli/testdata/json/snapshotlist.json create mode 100644 internal/compose/testdata/build/app/Dockerfile create mode 100644 internal/compose/testdata/build/compose.yaml create mode 100644 internal/compose/testdata/build/config.json create mode 100644 internal/e2e/phase3_test.go create mode 100644 internal/queue/queue.go create mode 100644 internal/queue/queue_test.go create mode 100644 internal/seed/seed.go create mode 100644 internal/seed/seed_test.go create mode 100644 internal/snapshot/snapshot.go create mode 100644 internal/snapshot/snapshot_test.go rename openspec/changes/{phase-3-snapshots-and-queue => archive/2026-10-29-phase-3-snapshots-and-queue}/.openspec.yaml (100%) rename openspec/changes/{phase-3-snapshots-and-queue => archive/2026-10-29-phase-3-snapshots-and-queue}/design.md (93%) rename openspec/changes/{phase-3-snapshots-and-queue => archive/2026-10-29-phase-3-snapshots-and-queue}/proposal.md (96%) rename openspec/changes/{phase-3-snapshots-and-queue => archive/2026-10-29-phase-3-snapshots-and-queue}/specs/build-limit/spec.md (100%) rename openspec/changes/{phase-3-snapshots-and-queue => archive/2026-10-29-phase-3-snapshots-and-queue}/specs/cli-contract/spec.md (100%) rename openspec/changes/{phase-3-snapshots-and-queue => archive/2026-10-29-phase-3-snapshots-and-queue}/specs/memory-budget/spec.md (100%) rename openspec/changes/{phase-3-snapshots-and-queue => archive/2026-10-29-phase-3-snapshots-and-queue}/specs/proxy/spec.md (100%) rename openspec/changes/{phase-3-snapshots-and-queue => archive/2026-10-29-phase-3-snapshots-and-queue}/specs/seeding/spec.md (100%) rename openspec/changes/{phase-3-snapshots-and-queue => archive/2026-10-29-phase-3-snapshots-and-queue}/specs/snapshots/spec.md (100%) rename openspec/changes/{phase-3-snapshots-and-queue => archive/2026-10-29-phase-3-snapshots-and-queue}/specs/stack-gc/spec.md (100%) create mode 100644 openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/stack-lifecycle/spec.md rename openspec/changes/{phase-3-snapshots-and-queue => archive/2026-10-29-phase-3-snapshots-and-queue}/specs/stack-list/spec.md (100%) rename openspec/changes/{phase-3-snapshots-and-queue => archive/2026-10-29-phase-3-snapshots-and-queue}/specs/stack-status/spec.md (100%) rename openspec/changes/{phase-3-snapshots-and-queue => archive/2026-10-29-phase-3-snapshots-and-queue}/specs/start-queue/spec.md (100%) rename openspec/changes/{phase-3-snapshots-and-queue => archive/2026-10-29-phase-3-snapshots-and-queue}/tasks.md (58%) create mode 100644 openspec/specs/build-limit/spec.md create mode 100644 openspec/specs/seeding/spec.md create mode 100644 openspec/specs/snapshots/spec.md create mode 100644 openspec/specs/start-queue/spec.md diff --git a/CLAUDE.md b/CLAUDE.md index 85c4ac6..5f56d7f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,11 +16,13 @@ changing architecture. Phase 0 approved (2026-10-28). Phase 1 (v0.1) and Phase 2 (v0.2) approved and archived (2026-10-28, `openspec/changes/archive/2026-10-28-phase-1-stacks-and-routing` and -`…-phase-2-overview-and-budget`). siding today: `setup [--port] [--budget]`, `teardown`, -`up [--wait] [--force]`, `status [--wait]`, `ps`, `logs`, `open`, `down [--volumes]`, `gc`, -`lint`, `ui`, `skill`; routing by host and path through `siding-proxy`; a memory budget; -`just smoke-stacks`, `just build-darwin`. Next: Phase 3 (`phase-3-snapshots-and-queue`, v0.3), -starting with `/opsx:propose`. +`…-phase-2-overview-and-budget`). Phase 3 (v0.3) approved and archived (2026-10-29, +`…/2026-10-29-phase-3-snapshots-and-queue`). siding today: `setup [--port] [--budget] +[--builds]`, `teardown [--snapshots]`, `up [--wait] [--force] [--seed]`, `status [--wait]`, +`ps`, `logs`, `open`, `down [--volumes]`, `snapshot save|ls|rm`, `gc`, `lint`, `ui`, `skill`; +routing by host and path through `siding-proxy`; a memory budget with a start queue and learned +peaks; build slots; `just smoke-stacks`, `just build-darwin`. Next: Phase 4 +(`phase-4-idle-and-wake`, v0.4), starting with `/opsx:propose`. ## Working agreements @@ -112,7 +114,8 @@ requests and on `main`, all inside the devcontainer image. `siding`, the user's stacks, `~/.siding`) is not development footprint. `hack/nuke.sh` never removes it; siding's own commands and `docker compose -p siding down` do. - Tests create stacks only as Compose projects with the prefix `siding-test-` and remove them by - their exact name. The smoke tests' proxies listen on 18080, never on 8080; the end-to-end + their exact name. Their snapshots are therefore named `siding-snap_siding-test-…` and are + removed by exact name too; `just smoke-stacks` checks that none of either is left. The smoke tests' proxies listen on 18080, never on 8080; the end-to-end tests run their own proxy `siding-test-e2e-proxy` on the network `siding-test-e2e`, so a developer's `siding-proxy` is never touched. - No real secrets in the repo, in golden files or in logs; golden files may contain obvious @@ -132,8 +135,11 @@ requests and on `main`, all inside the devcontainer image. and `dev.siding.agent` (optional), never on networks or volumes, whose labels must not change between two `up`s. Service labels: `dev.siding.route` (`/`, `/`, `false`), `dev.siding.port` (the HTTP port of a service with several), `dev.siding.seed` - (`volume|script|none`). Volume label `dev.siding.shared`. On `siding-proxy`: - `dev.siding.budget` (the memory budget in bytes) and `dev.siding.host-alias` (what + (`volume|script|none`), `dev.siding.seed.command` (the seed command of `script`). Volume + label `dev.siding.shared`. Snapshot volumes: `dev.siding.snapshot` (name), + `dev.siding.snapshot-volume` (the stack's volume key), `dev.siding.snapshot-created`, plus + `dev.siding.repo` and `dev.siding.machine`. On `siding-proxy`: `dev.siding.budget` (the memory + budget in bytes), `dev.siding.builds` (build slots) and `dev.siding.host-alias` (what `host.docker.internal` resolves to in the proxy). - Compose project `-`, host `..localhost`, proxy `siding-proxy` on the network `siding`, override `.siding/override.yml`. diff --git a/README.md b/README.md index 03eeb49..6a8b9d1 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,9 @@ siding gives every git worktree its own Docker Compose stack, at its own `*.localhost` address, and tells you and your coding agents whether it actually runs and what it costs. -> **Pre-alpha (v0.2).** Stacks per worktree, routing through one local proxy, the verdict of -> `siding status`, the overview `siding ui`, a memory budget, `gc` and `lint` work; expect +> **Pre-alpha (v0.3).** Stacks per worktree, routing through one local proxy, the verdict of +> `siding status`, the overview `siding ui`, a memory budget with a queue and learned peaks, +> snapshots and seeding, a build limit, `gc` and `lint` work; expect > rough edges and changes before v1. There are no releases > yet: build it from source (see below). The plan is in [openspec/changes/](openspec/changes) > (one change per phase), what siding does today in [openspec/specs/](openspec/specs). @@ -22,8 +23,10 @@ siding teardown # remove the proxy again; stacks keep running, --dr ``` Every stack is reached through this one proxy at `http://..localhost`. Browsers -and curl resolve `*.localhost` to your machine by themselves; for other tools add the host to -`/etc/hosts`. Running `siding setup` again changes nothing unless the port differs. +resolve `*.localhost` to your machine by themselves, and so does curl on Linux. The curl of +macOS does not: there, use `curl -H "Host: shop.feature-login.localhost" http://127.0.0.1/`, or +add the host to `/etc/hosts`, as for other tools. Running `siding setup` again changes nothing +unless the port differs. ### In a worktree: start the stack @@ -79,6 +82,47 @@ siding lint # exits 1 when it finds an error; --json for a Lint | `PublishedPort` | info | published ports, which siding resets | | `NoRoot` | info | HTTP services, but none at `/` | +### Snapshots + +```sh +siding snapshot save base # copy this stack's named volumes into the snapshot "base" +siding snapshot ls # the snapshots of this repository +siding snapshot rm base # --dry-run lists it first +``` + +A snapshot is a copy of every named volume of a stack, kept as Docker volumes on this machine +per repository. While it copies, `save` stops the services that use those volumes, so a +database is copied in a consistent state, and starts them again. Snapshots outlive stacks: +`down --volumes` and `gc` never remove them; `siding teardown --snapshots` does. + +### Seeding a new stack + +```sh +siding up --seed base # on the stack's first up: its volumes start as copies of "base" +``` + +A new worktree's stack can start with data instead of empty. On its first `up` (the project +has no containers and no volumes yet), `--seed ` creates its volumes as copies of the +snapshot before Compose starts it; a later `up` never seeds again. Per service, the label +`dev.siding.seed` chooses: + +```yaml +services: + db: + image: postgres:17 + labels: + dev.siding.seed: script # run a command once on the first up + dev.siding.seed.command: "psql -U app -f /seed/dev.sql" + cache: + image: redis:7 + labels: + dev.siding.seed: none # never seeded, starts empty + # without the label, or with dev.siding.seed: volume, the volumes come from --seed +``` + +The seed command runs with `docker compose exec` as soon as the service is ready. If it fails, +the verdict is `Failed` with the reason `SeedFailed` and the command's output. + ### Memory budget ```sh @@ -87,9 +131,16 @@ siding up --force # start even if the stack does not fit ``` Before `up` starts a stack, siding adds the memory the other stacks use now to what this -stack will need: per service its `mem_limit` (or `deploy.resources.limits.memory`), or -256 MiB without a limit. If that exceeds the budget, `up` refuses with exit code 3 and says -how much is missing. Setting `mem_limit` on big services makes the estimate right. `siding ps` +stack will need: per service the highest use siding has seen for it in this repository, plus a +quarter and at most its limit; else its `mem_limit` (or `deploy.resources.limits.memory`); else +256 MiB. siding learns those peaks whenever it reads memory (`ps`, `ui`, `up`, a Ready `status`) +and keeps them in `~/.siding/peaks.json`, a cache you can delete at any time. If that exceeds the budget, `up` refuses with exit code 3 and says +how much is missing. Setting `mem_limit` on big services makes the estimate right. + +With `siding up --wait`, a stack that does not fit waits in line instead, until another stack +frees memory or `--timeout` (3 minutes) is up; then it exits 3. Stacks start in the order they +began to wait. `siding ps` and `siding ui` show the line. A waiting `up` that you stop with +Ctrl-C, or that is killed, leaves the line. `siding ps` shows the total against the budget. ### Overview @@ -104,6 +155,17 @@ return the documents of `siding ps --json` and `siding gc --dry-run --json`. It machine only, and nothing of it keeps running after Ctrl-C. After upgrading siding, run `siding setup` once, so the proxy knows the route. +### Builds + +```sh +siding setup --builds 2 # at most two stacks build images at once; "default" is half the CPUs +``` + +When a stack has services with `build:`, `up` takes one of these build slots while Compose +builds and starts it, and waits for a free one first (within `--timeout`). Stacks of images +only never wait. The slots are lock files under `~/.siding/builds`; a stopped or killed `up` +frees its slot at once. + ### Logs, address, and taking it down ```sh diff --git a/cmd/siding/main.go b/cmd/siding/main.go index a277ccb..b145bd4 100644 --- a/cmd/siding/main.go +++ b/cmd/siding/main.go @@ -4,6 +4,7 @@ package main import ( "context" + "errors" "fmt" "os" "os/signal" @@ -41,6 +42,8 @@ func main() { Getenv: os.Getenv, OSMachineID: stack.OSMachineID, Stdin: os.Stdin, + PID: os.Getpid(), + Alive: processAlive, IsLocalAddress: overview.IsLocalAddress, IsTerminal: stdinIsTerminal, Git: git.Client{}, @@ -56,6 +59,12 @@ func main() { os.Exit(code) } +// processAlive reports whether the process pid still runs: signal 0 checks without sending. +func processAlive(pid int) bool { + err := syscall.Kill(pid, 0) + return err == nil || errors.Is(err, syscall.EPERM) +} + // stdinIsTerminal reports whether stdin is a terminal, i.e. a human can answer a question. func stdinIsTerminal() bool { fi, err := os.Stdin.Stat() diff --git a/hack/smoke/stacks.sh b/hack/smoke/stacks.sh index 5e3ed37..7b1f6f0 100755 --- a/hack/smoke/stacks.sh +++ b/hack/smoke/stacks.sh @@ -20,8 +20,11 @@ left="$( docker ps -a --format '{{.Names}}' docker network ls --format '{{.Name}}' docker volume ls --format '{{.Name}}' + docker images --format '{{.Repository}}' )" -if grep -q "^${SIDING_TEST_PREFIX}" <<<"$left"; then - die "objects named ${SIDING_TEST_PREFIX}* are left in the inner daemon: $(grep "^${SIDING_TEST_PREFIX}" <<<"$left" | tr '\n' ' ')" +# Snapshot volumes are named siding-snap__..., and the tests' repositories siding-test-*. +pattern="^(${SIDING_TEST_PREFIX}|siding-snap_${SIDING_TEST_PREFIX})" +if grep -Eq "$pattern" <<<"$left"; then + die "test objects are left in the inner daemon: $(grep -E "$pattern" <<<"$left" | tr '\n' ' ')" fi echo "smoke-stacks: ok" diff --git a/internal/budget/budget.go b/internal/budget/budget.go index 2882f95..80d507c 100644 --- a/internal/budget/budget.go +++ b/internal/budget/budget.go @@ -45,23 +45,9 @@ func ParseSize(s string) (int64, error) { return n << shift, nil } -// Estimate is the memory a project will need: per service and replica its memory limit, or -// ServiceDefault without one. -func Estimate(p *compose.Project) int64 { - var sum int64 - for _, s := range p.Services { - per := s.MemoryLimit - if per <= 0 { - per = ServiceDefault - } - replicas := s.Replicas - if replicas < 1 { - replicas = 1 - } - sum += per * int64(replicas) - } - return sum -} +// Estimate is the memory a project will need without learned peaks: per service and replica its +// memory limit, or ServiceDefault without one. +func Estimate(p *compose.Project) int64 { return EstimateLearned(p, "", nil) } // Check is the outcome of fitting a stack into the budget. type Check struct { diff --git a/internal/budget/peaks.go b/internal/budget/peaks.go new file mode 100644 index 0000000..483c80b --- /dev/null +++ b/internal/budget/peaks.go @@ -0,0 +1,101 @@ +package budget + +import ( + "encoding/json" + "fmt" + "os" + "path/filepath" + + "github.com/tweinmann/siding/internal/compose" +) + +// PeakMargin is added to a learned peak: one-shot stats see the use now, not the maximum. +const PeakMargin = 1.25 + +// Peaks is the highest memory use siding has seen per "/". It is kept in +// ~/.siding/peaks.json, a losable cache. +type Peaks map[string]int64 + +// PeakKey is the key of a service of a repository. +func PeakKey(repo, service string) string { return repo + "/" + service } + +func peaksPath(home string) string { return filepath.Join(home, ".siding", "peaks.json") } + +// LoadPeaks reads the cache; a missing or broken file is an empty cache. +func LoadPeaks(home string) Peaks { + data, err := os.ReadFile(peaksPath(home)) + if err != nil { + return Peaks{} + } + var p Peaks + if err := json.Unmarshal(data, &p); err != nil || p == nil { + return Peaks{} + } + return p +} + +// Learn records samples, keeping the highest value per key, and writes the cache atomically. A +// sample another siding process wrote meanwhile may be lost; it is a cache. +func Learn(home string, samples Peaks) error { + if len(samples) == 0 { + return nil + } + p := LoadPeaks(home) + changed := false + for k, v := range samples { + if v > p[k] { + p[k] = v + changed = true + } + } + if !changed { + return nil + } + data, err := json.MarshalIndent(p, "", " ") + if err != nil { + return err + } + path := peaksPath(home) + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + return fmt.Errorf("write learned peaks: %w", err) + } + tmp, err := os.CreateTemp(filepath.Dir(path), ".peaks-*.json") + if err != nil { + return fmt.Errorf("write learned peaks: %w", err) + } + if _, err := tmp.Write(append(data, '\n')); err != nil { + _ = tmp.Close() + _ = os.Remove(tmp.Name()) + return fmt.Errorf("write learned peaks: %w", err) + } + if err := tmp.Close(); err != nil { + _ = os.Remove(tmp.Name()) + return err + } + return os.Rename(tmp.Name(), path) +} + +// EstimateLearned is the memory a project of repo will need: per service and replica its +// learned peak plus PeakMargin, capped at its memory limit; else the limit; else +// ServiceDefault. +func EstimateLearned(p *compose.Project, repo string, peaks Peaks) int64 { + var sum int64 + for name, s := range p.Services { + per := s.MemoryLimit + if peak, ok := peaks[PeakKey(repo, name)]; ok && peak > 0 { + per = int64(float64(peak) * PeakMargin) + if s.MemoryLimit > 0 && per > s.MemoryLimit { + per = s.MemoryLimit + } + } + if per <= 0 { + per = ServiceDefault + } + replicas := s.Replicas + if replicas < 1 { + replicas = 1 + } + sum += per * int64(replicas) + } + return sum +} diff --git a/internal/budget/peaks_test.go b/internal/budget/peaks_test.go new file mode 100644 index 0000000..97bf636 --- /dev/null +++ b/internal/budget/peaks_test.go @@ -0,0 +1,67 @@ +package budget + +import ( + "os" + "path/filepath" + "testing" + + "github.com/tweinmann/siding/internal/compose" +) + +func TestEstimateLearned(t *testing.T) { + t.Parallel() + p := &compose.Project{Services: map[string]compose.Service{ + "db": {MemoryLimit: 1024 * mib, Replicas: 1}, + "web": {Replicas: 2}, + "api": {MemoryLimit: 512 * mib, Replicas: 1}, + }} + tests := []struct { + name string + peaks Peaks + want int64 + }{ + {name: "nothing learned", want: (1024 + 2*256 + 512) * mib}, + {name: "a learned peak plus a quarter", peaks: Peaks{"shop/web": 400 * mib}, want: (1024 + 2*500 + 512) * mib}, + {name: "capped at the limit", peaks: Peaks{"shop/db": 900 * mib}, want: (1024 + 2*256 + 512) * mib}, + {name: "below the limit", peaks: Peaks{"shop/api": 200 * mib}, want: (1024 + 2*256 + 250) * mib}, + {name: "another repository's peak does not count", peaks: Peaks{"blog/web": 400 * mib}, want: (1024 + 2*256 + 512) * mib}, + } + for _, tt := range tests { + if got := EstimateLearned(p, "shop", tt.peaks); got != tt.want { + t.Errorf("%s: %d MiB, want %d MiB", tt.name, got/mib, tt.want/mib) + } + } +} + +func TestLearn(t *testing.T) { + t.Parallel() + home := t.TempDir() + if got := LoadPeaks(home); len(got) != 0 { + t.Errorf("no file: %v", got) + } + if err := Learn(home, Peaks{"shop/web": 400 * mib}); err != nil { + t.Fatal(err) + } + if err := Learn(home, Peaks{"shop/web": 300 * mib, "shop/db": 100 * mib}); err != nil { + t.Fatal(err) + } + got := LoadPeaks(home) + if got["shop/web"] != 400*mib || got["shop/db"] != 100*mib { + t.Errorf("peaks %v", got) + } + entries, _ := os.ReadDir(filepath.Join(home, ".siding")) + if len(entries) != 1 { + t.Errorf("temporary files left: %v", entries) + } + + // A broken cache is an empty one, and learning starts anew. + if err := os.WriteFile(filepath.Join(home, ".siding", "peaks.json"), []byte("{not json"), 0o644); err != nil { + t.Fatal(err) + } + if got := LoadPeaks(home); len(got) != 0 { + t.Errorf("broken file: %v", got) + } + if err := Learn(home, Peaks{"shop/web": 10 * mib}); err != nil || LoadPeaks(home)["shop/web"] != 10*mib { + t.Errorf("after a broken file: %v, %v", err, LoadPeaks(home)) + } +} diff --git a/internal/buildslot/buildslot.go b/internal/buildslot/buildslot.go new file mode 100644 index 0000000..bc5ed6f --- /dev/null +++ b/internal/buildslot/buildslot.go @@ -0,0 +1,49 @@ +// Package buildslot limits how many siding processes build images at the same time: N lock +// files under ~/.siding/builds, held with flock. The kernel releases a lock when its process +// ends, so a killed up frees its slot at once, and there is no service. +package buildslot + +import ( + "errors" + "fmt" + "os" + "path/filepath" + "syscall" +) + +// Slot is a held build slot. +type Slot struct { + f *os.File +} + +// TryAcquire takes a free one of n slots under home without waiting; ok is false when all are +// held. +func TryAcquire(home string, n int) (s *Slot, ok bool, err error) { + dir := filepath.Join(home, ".siding", "builds") + if err := os.MkdirAll(dir, 0o755); err != nil { + return nil, false, fmt.Errorf("build slots: %w", err) + } + for i := range max(n, 1) { + f, err := os.OpenFile(filepath.Join(dir, fmt.Sprintf("slot-%d.lock", i)), os.O_CREATE|os.O_RDWR, 0o644) + if err != nil { + return nil, false, fmt.Errorf("build slots: %w", err) + } + err = syscall.Flock(int(f.Fd()), syscall.LOCK_EX|syscall.LOCK_NB) + if err == nil { + return &Slot{f: f}, true, nil + } + _ = f.Close() + if !errors.Is(err, syscall.EWOULDBLOCK) { + return nil, false, fmt.Errorf("build slots: %w", err) + } + } + return nil, false, nil +} + +// Release frees the slot. +func (s *Slot) Release() { + if s != nil && s.f != nil { + _ = s.f.Close() // closing the file drops the lock + s.f = nil + } +} diff --git a/internal/buildslot/buildslot_test.go b/internal/buildslot/buildslot_test.go new file mode 100644 index 0000000..7d6d4ea --- /dev/null +++ b/internal/buildslot/buildslot_test.go @@ -0,0 +1,34 @@ +package buildslot + +import "testing" + +// flock locks belong to open files, so two acquisitions in one process exclude each other like +// two processes would. +func TestSlots(t *testing.T) { + t.Parallel() + home := t.TempDir() + a, ok, err := TryAcquire(home, 2) + if err != nil || !ok { + t.Fatalf("first: %v %v", ok, err) + } + b, ok, err := TryAcquire(home, 2) + if err != nil || !ok { + t.Fatalf("second: %v %v", ok, err) + } + if _, ok, err := TryAcquire(home, 2); err != nil || ok { + t.Fatalf("third of two: %v %v", ok, err) + } + a.Release() + c, ok, err := TryAcquire(home, 2) + if err != nil || !ok { + t.Fatalf("after a release: %v %v", ok, err) + } + b.Release() + c.Release() + c.Release() // twice is fine + if s, ok, _ := TryAcquire(home, 0); !ok { + t.Error("n below 1 still has one slot") + } else { + s.Release() + } +} diff --git a/internal/cli/buildslot_test.go b/internal/cli/buildslot_test.go new file mode 100644 index 0000000..27e3589 --- /dev/null +++ b/internal/cli/buildslot_test.go @@ -0,0 +1,75 @@ +package cli + +import ( + "strings" + "testing" + + "github.com/tweinmann/siding/internal/buildslot" +) + +// buildConfig is a project with one service built from a Dockerfile. +const buildConfig = `{"name": "shop-main", "services": {"app": {"build": {"context": "/src/shop/app"}, "networks": {"default": null}}}, + "networks": {"default": {"name": "shop-main_default"}}}` + +func TestBuildSlots(t *testing.T) { + t.Parallel() + + // All slots are held by other ups; the 1st sleep frees one. + holdAll := func(t *testing.T, e *env) []*buildslot.Slot { + setupDoc(t, e, "--builds", "2") + var held []*buildslot.Slot + for range 2 { + s, ok, err := buildslot.TryAcquire(e.opts.Home, 2) + if err != nil || !ok { + t.Fatalf("holding a slot: %v %v", ok, err) + } + held = append(held, s) + } + return held + } + + t.Run("waits for a slot", func(t *testing.T) { + t.Parallel() + e := newEnv(t) + e.compose.config = buildConfig + held := holdAll(t, e) + e.clock.onSleep = func(n int) { + if n == 1 { + held[0].Release() + } + } + code, _, stderr := e.run("up") + // At least one round: a git child of a parallel test may hold the freed lock for a moment + // between its fork and exec, and up simply tries again. + if code != exitOK || !strings.Contains(stderr, "Waiting for a build slot: 2 stacks build at once") || e.clock.slept < 1 { + t.Errorf("exit %d, slept %d, stderr %q", code, e.clock.slept, stderr) + } + held[1].Release() + }) + + t.Run("time is up", func(t *testing.T) { + t.Parallel() + e := newEnv(t) + e.compose.config = buildConfig + held := holdAll(t, e) + code, stdout, _ := e.run("up", "--timeout", "5s", "--json") + if code != exitNoCapacity || !strings.Contains(stdout, "build slot") || len(e.compose.recorded()) != 1 { // only setup's + t.Errorf("exit %d, %s", code, stdout) + } + for _, s := range held { + s.Release() + } + }) + + t.Run("images only need no slot", func(t *testing.T) { + t.Parallel() + e := newEnv(t) + held := holdAll(t, e) + if code, _, stderr := e.run("up"); code != exitOK || strings.Contains(stderr, "build slot") || e.clock.slept != 0 { + t.Errorf("exit %d, stderr %q", code, stderr) + } + for _, s := range held { + s.Release() + } + }) +} diff --git a/internal/cli/cli.go b/internal/cli/cli.go index f226ed1..b35a334 100644 --- a/internal/cli/cli.go +++ b/internal/cli/cli.go @@ -45,6 +45,9 @@ type Options struct { Getenv func(string) string // OSMachineID returns the operating system's machine id, or "". OSMachineID func() string + // PID is siding's process id, and Alive reports whether a process still runs (the queue). + PID int + Alive func(pid int) bool // IsLocalAddress reports whether an IP address belongs to this machine. IsLocalAddress func(ip string) bool // Stdin is where questions are answered; IsTerminal reports whether a human is there. @@ -86,6 +89,11 @@ type Docker interface { NetworkGateway(ctx context.Context, name string) (string, error) NetworkUsers(ctx context.Context, name string) (exists bool, users []string, err error) RemoveNetwork(ctx context.Context, name string) error + NCPU(ctx context.Context) (int, error) + CreateVolume(ctx context.Context, name string, labels map[string]string) error + RemoveVolume(ctx context.Context, name string) error + VolumeSizes(ctx context.Context) (map[string]int64, error) + RunHelper(ctx context.Context, h docker.Helper) (exit int, output []string, err error) Logs(ctx context.Context, id string, tail int) ([]string, error) Memory(ctx context.Context, id string) (uint64, error) } @@ -134,6 +142,7 @@ func New(opts Options) *cobra.Command { newLintCommand(a), newUICommand(a), newTeardownCommand(a), + newSnapshotCommand(a), newSkillCommand(), ) return root diff --git a/internal/cli/cli_test.go b/internal/cli/cli_test.go index 3a66dad..9924782 100644 --- a/internal/cli/cli_test.go +++ b/internal/cli/cli_test.go @@ -113,7 +113,8 @@ func TestErrorCodes(t *testing.T) { fail.InvalidArguments, fail.NotAGitRepository, fail.NoBranch, fail.ComposeFileNotFound, fail.ComposeFailed, fail.DockerUnavailable, fail.ProxyNotRunning, fail.PortInUse, fail.InvalidRoute, fail.AmbiguousPort, fail.SlugCollision, fail.StackNotFound, - fail.UnmergedBranch, fail.DirtyWorktree, fail.NoCapacity, fail.NotInteractive, fail.Internal, + fail.UnmergedBranch, fail.DirtyWorktree, fail.NoCapacity, fail.NotInteractive, + fail.SnapshotNotFound, fail.SnapshotExists, fail.Internal, } for _, code := range codes { t.Run(code, func(t *testing.T) { diff --git a/internal/cli/down.go b/internal/cli/down.go index 61971a4..d7b79ec 100644 --- a/internal/cli/down.go +++ b/internal/cli/down.go @@ -36,7 +36,7 @@ default branch or the worktree has uncommitted changes, unless --force.`, if asJSON { return printJSON(cmd.OutOrStdout(), doc) } - return printDownText(cmd, doc, f.volumes) + return printDownText(cmd, doc) }, } cmd.Flags().BoolVar(&f.volumes, "volumes", false, "also remove the stack's volumes and their data") @@ -48,7 +48,7 @@ default branch or the worktree has uncommitted changes, unless --force.`, func (a *app) down(cmd *cobra.Command, f downFlags) (downDocument, error) { ctx := cmd.Context() - st, err := a.findStack(ctx) + st, err := a.findStackOrData(ctx, true) if err != nil { return downDocument{}, err } @@ -119,14 +119,16 @@ func (a *app) downPlan(ctx context.Context, st existing, f downFlags) (downDocum for _, n := range ns { doc.Networks = append(doc.Networks, n.Name) } - if f.volumes { - vs, err := a.opts.Docker.Volumes(ctx, byProject) - if err != nil { - return doc, err - } - for _, v := range vs { - doc.Volumes = append(doc.Volumes, v.Name) - } + vs, err := a.opts.Docker.Volumes(ctx, byProject) + if err != nil { + return doc, err + } + if !f.volumes { + doc.keptVolumes = len(vs) + vs = nil + } + for _, v := range vs { + doc.Volumes = append(doc.Volumes, v.Name) } sort.Strings(doc.Containers) sort.Strings(doc.Networks) @@ -134,7 +136,7 @@ func (a *app) downPlan(ctx context.Context, st existing, f downFlags) (downDocum return doc, nil } -func printDownText(cmd *cobra.Command, doc downDocument, volumes bool) error { +func printDownText(cmd *cobra.Command, doc downDocument) error { var b strings.Builder verb := "Removed" if doc.DryRun { @@ -149,7 +151,7 @@ func printDownText(cmd *cobra.Command, doc downDocument, volumes bool) error { fmt.Fprintf(&b, " %s %s\n", list.kind, n) } } - if !volumes { + if doc.keptVolumes > 0 { b.WriteString("Volumes stay; siding down --volumes removes them.\n") } if doc.DryRun { diff --git a/internal/cli/down_test.go b/internal/cli/down_test.go index 6bec782..e00b202 100644 --- a/internal/cli/down_test.go +++ b/internal/cli/down_test.go @@ -65,6 +65,15 @@ func TestDown(t *testing.T) { } }) + t.Run("no volumes to keep", func(t *testing.T) { + t.Parallel() + e := downEnv(t, "main") + e.docker.volumes = nil + if _, text, _ := e.run("down"); strings.Contains(text, "Volumes stay") { + t.Errorf("a stack without volumes was told they stay:\n%s", text) + } + }) + t.Run("volumes of a merged, clean branch", func(t *testing.T) { t.Parallel() e := downEnv(t, "main") @@ -129,3 +138,23 @@ func TestDown(t *testing.T) { } }) } + +// After siding down only the volumes are left; down --volumes still finds the stack by them. +func TestDownOnlyData(t *testing.T) { + t.Parallel() + e := newEnv(t) + id := e.id() + labels := id.Labels() + labels[stack.LabelProject] = id.Project() + e.docker.volumes = []docker.Volume{{Name: "shop-main_data", Labels: labels}} + if code, stdout, _ := e.run("down", "--volumes", "--json"); code != exitOK || !strings.Contains(stdout, "shop-main_data") { + t.Errorf("exit %d, %s", code, stdout) + } + if runs := e.compose.recorded(); len(runs) != 1 || !slices.Equal(runs[0].args, []string{"down", "--remove-orphans", "--volumes"}) { + t.Errorf("compose %+v", runs) + } + // status still says there is no stack. + if code, stdout, _ := e.run("status", "--json"); code != exitFailed || !strings.Contains(stdout, `"code": "StackNotFound"`) { + t.Errorf("status: exit %d, %s", code, stdout) + } +} diff --git a/internal/cli/env_test.go b/internal/cli/env_test.go index 6f51d52..a396a2d 100644 --- a/internal/cli/env_test.go +++ b/internal/cli/env_test.go @@ -10,6 +10,7 @@ import ( "os/exec" "path/filepath" "regexp" + "slices" "strconv" "strings" "sync" @@ -32,7 +33,8 @@ const testConfig = `{ "services": { "api": {"expose": ["8080", "9229"], "labels": {"dev.siding.route": "/api", "dev.siding.port": "8080"}, "networks": {"default": null}, "environment": {"API_TOKEN": "not-a-real-api-token"}}, - "db": {"networks": {"default": null}, "environment": {"POSTGRES_PASSWORD": "not-a-real-token"}}, + "db": {"networks": {"default": null}, "environment": {"POSTGRES_PASSWORD": "not-a-real-token"}, + "volumes": [{"type": "volume", "source": "data", "target": "/var/lib/data"}]}, "mail": {"expose": ["8025"], "networks": {"default": null}}, "web": {"ports": [{"target": 3000, "published": "3000", "protocol": "tcp"}], "labels": {"dev.siding.route": "/"}, "networks": {"default": null}} @@ -54,6 +56,8 @@ type env struct { browser *fakeBrowser clock *fakeClock envVars map[string]string + // dead are the pids the queue sees as gone. + dead map[int]bool } func newEnv(t *testing.T) *env { @@ -73,6 +77,7 @@ func newEnv(t *testing.T) *env { browser: &fakeBrowser{}, clock: &fakeClock{now: time.Date(2026, 10, 28, 12, 0, 0, 0, time.UTC)}, envVars: map[string]string{}, + dead: map[int]bool{}, } if err := os.MkdirAll(e.repo, 0o755); err != nil { t.Fatal(err) @@ -90,6 +95,8 @@ func newEnv(t *testing.T) *env { OSMachineID: func() string { return "not-a-real-machine-id" }, Stdin: strings.NewReader(""), IsTerminal: func() bool { return false }, + PID: 4242, + Alive: func(pid int) bool { return !e.dead[pid] }, // The daemon runs on this machine, as in the devcontainer. IsLocalAddress: func(ip string) bool { return ip == "172.19.0.1" }, Git: git.Client{}, @@ -106,6 +113,7 @@ func newEnv(t *testing.T) *env { var publishedPort = regexp.MustCompile(`"127\.0\.0\.1:(\d+):80"`) var budgetLabel = regexp.MustCompile(`dev\.siding\.budget: "(\d+)"`) +var buildsLabel = regexp.MustCompile(`dev\.siding\.builds: "(\d+)"`) var hostAliasLabel = regexp.MustCompile(`dev\.siding\.host-alias: "([^"]+)"`) // composeProxy does what docker compose up does for the proxy's project: it recreates the @@ -135,6 +143,9 @@ func (e *env) composeProxy(r composeRun) { if m := budgetLabel.FindStringSubmatch(string(data)); m != nil { labels[stack.LabelBudget] = m[1] } + if m := buildsLabel.FindStringSubmatch(string(data)); m != nil { + labels[stack.LabelBuilds] = m[1] + } if m := hostAliasLabel.FindStringSubmatch(string(data)); m != nil { labels[stack.LabelHostAlias] = m[1] } @@ -219,12 +230,15 @@ type fakeDocker struct { // container. sidingNetwork bool removedNetworks []string - containers []docker.Container - networks []docker.Network - volumes []docker.Volume - logs map[string][]string - memory map[string]uint64 - ensured []string + // calls records volume and helper calls in order; helperExit is the exit of every copy. + calls []string + helperExit int + containers []docker.Container + networks []docker.Network + volumes []docker.Volume + logs map[string][]string + memory map[string]uint64 + ensured []string } func (d *fakeDocker) add(c docker.Container) { @@ -344,6 +358,47 @@ func (d *fakeDocker) RemoveNetwork(_ context.Context, name string) error { return nil } +func (d *fakeDocker) NCPU(context.Context) (int, error) { return 8, nil } + +func (d *fakeDocker) CreateVolume(_ context.Context, name string, labels map[string]string) error { + d.mu.Lock() + defer d.mu.Unlock() + d.volumes = append(d.volumes, docker.Volume{Name: name, Labels: maps.Clone(labels)}) + d.calls = append(d.calls, "create "+name) + return nil +} + +func (d *fakeDocker) RemoveVolume(_ context.Context, name string) error { + d.mu.Lock() + defer d.mu.Unlock() + d.volumes = slices.DeleteFunc(d.volumes, func(v docker.Volume) bool { return v.Name == name }) + d.calls = append(d.calls, "remove "+name) + return nil +} + +func (d *fakeDocker) VolumeSizes(context.Context) (map[string]int64, error) { + d.mu.Lock() + defer d.mu.Unlock() + sizes := map[string]int64{} + for _, v := range d.volumes { + sizes[v.Name] = 1 << 20 + } + return sizes, nil +} + +// RunHelper records a copy as "copy "; helperExit fails the next copies. +func (d *fakeDocker) RunHelper(_ context.Context, h docker.Helper) (int, []string, error) { + d.mu.Lock() + defer d.mu.Unlock() + from, _, _ := strings.Cut(h.Binds[0], ":") + to, _, _ := strings.Cut(h.Binds[1], ":") + d.calls = append(d.calls, "copy "+from+" "+to) + if d.helperExit != 0 { + return d.helperExit, []string{"cp: write error: No space left on device"}, nil + } + return 0, nil, nil +} + func (d *fakeDocker) Logs(_ context.Context, id string, tail int) ([]string, error) { d.mu.Lock() defer d.mu.Unlock() @@ -370,6 +425,9 @@ type fakeCompose struct { config string runs []composeRun runErr error + // execErr fails runs of docker compose exec, after writing execOutput. + execErr error + execOutput string // onRun, if set, runs after each recorded run, e.g. to start containers; onProxy instead // for runs of the proxy's project. onRun, onProxy func(composeRun) @@ -379,11 +437,15 @@ func (c *fakeCompose) Config(context.Context, compose.Invocation) ([]byte, error return []byte(c.config), nil } -func (c *fakeCompose) Run(_ context.Context, inv compose.Invocation, args []string, _, _ io.Writer) error { +func (c *fakeCompose) Run(_ context.Context, inv compose.Invocation, args []string, stdout, _ io.Writer) error { c.mu.Lock() r := composeRun{inv: inv, args: args} c.runs = append(c.runs, r) onRun, err := c.onRun, c.runErr + if args[0] == "exec" { + _, _ = io.WriteString(stdout, c.execOutput) + onRun, err = nil, c.execErr + } if inv.Project == "siding" { onRun = c.onProxy } diff --git a/internal/cli/json.go b/internal/cli/json.go index c6f070d..1ff591b 100644 --- a/internal/cli/json.go +++ b/internal/cli/json.go @@ -18,19 +18,21 @@ import ( const documentAPIVersion = "siding.dev/v1alpha1" const ( - kindAddress = "Address" - kindDown = "Down" - kindError = "Error" - kindGC = "GC" - kindLintReport = "LintReport" - kindLogs = "Logs" - kindSetup = "Setup" - kindSkill = "Skill" - kindStack = "Stack" - kindStackList = "StackList" - kindStatus = "Status" - kindTeardown = "Teardown" - kindVersion = "Version" + kindAddress = "Address" + kindDown = "Down" + kindError = "Error" + kindGC = "GC" + kindLintReport = "LintReport" + kindLogs = "Logs" + kindSetup = "Setup" + kindSkill = "Skill" + kindSnapshot = "Snapshot" + kindSnapshotList = "SnapshotList" + kindStack = "Stack" + kindStackList = "StackList" + kindStatus = "Status" + kindTeardown = "Teardown" + kindVersion = "Version" ) // jsonFlag is the name of the flag, looked up again by Execute to report an error as a document. @@ -111,6 +113,8 @@ type setupDocument struct { State string `json:"state"` // BudgetBytes is the memory budget for all stacks. BudgetBytes int64 `json:"budgetBytes"` + // Builds is how many stacks may build images at once. + Builds int `json:"builds"` } // stackDocument is what up prints without --wait. @@ -164,6 +168,16 @@ type stackListDocument struct { Stacks []stackEntry `json:"stacks,omitempty"` MemoryBytes uint64 `json:"memoryBytes,omitempty"` BudgetBytes int64 `json:"budgetBytes"` + // Waiting are the stacks waiting in line for memory, first first. + Waiting []waitingEntry `json:"waiting,omitempty"` +} + +type waitingEntry struct { + Project string `json:"project"` + Place int `json:"place"` + // MemoryBytes is the memory the stack needs. + MemoryBytes int64 `json:"memoryBytes"` + Since string `json:"since"` } type stackEntry struct { @@ -207,6 +221,8 @@ type downDocument struct { Containers []string `json:"containers,omitempty"` Networks []string `json:"networks,omitempty"` Volumes []string `json:"volumes,omitempty"` + // keptVolumes counts the volumes a down without --volumes leaves, for the text only. + keptVolumes int } // skillDocument is what skill --json prints. @@ -273,4 +289,40 @@ type teardownDocument struct { KeptNetwork string `json:"keptNetwork,omitempty"` // Stacks keep running as plain Compose projects. Stacks []string `json:"stacks,omitempty"` + // Snapshots are removed with --snapshots, as "/"; KeptSnapshots stay without it. + Snapshots []string `json:"snapshots,omitempty"` + KeptSnapshots []string `json:"keptSnapshots,omitempty"` +} + +// snapshotDocument is what snapshot save and snapshot rm print. +type snapshotDocument struct { + header + Name string `json:"name"` + Repo string `json:"repo"` + Created string `json:"created,omitempty"` + DryRun bool `json:"dryRun,omitempty"` + Volumes []snapshotVolume `json:"volumes,omitempty"` +} + +type snapshotVolume struct { + // Key is the volume's name in the compose file. + Key string `json:"key"` + // Source is the stack's volume it was copied from, when saving. + Source string `json:"source,omitempty"` + Snapshot string `json:"snapshot"` +} + +// snapshotListDocument is what snapshot ls prints. +type snapshotListDocument struct { + header + Snapshots []snapshotEntry `json:"snapshots,omitempty"` +} + +type snapshotEntry struct { + Name string `json:"name"` + Repo string `json:"repo"` + Created string `json:"created,omitempty"` + Volumes []string `json:"volumes"` + // SizeBytes is -1 when Docker does not know the size. + SizeBytes int64 `json:"sizeBytes"` } diff --git a/internal/cli/ps.go b/internal/cli/ps.go index 11217f1..0917e57 100644 --- a/internal/cli/ps.go +++ b/internal/cli/ps.go @@ -8,10 +8,13 @@ import ( "os" "sort" "sync" + "time" "github.com/spf13/cobra" + "github.com/tweinmann/siding/internal/budget" "github.com/tweinmann/siding/internal/docker" + "github.com/tweinmann/siding/internal/queue" "github.com/tweinmann/siding/internal/stack" ) @@ -91,6 +94,14 @@ func (a *app) ps(ctx context.Context) (stackListDocument, error) { doc.Stacks = append(doc.Stacks, e) } sort.Slice(doc.Stacks, func(i, j int) bool { return doc.Stacks[i].Project < doc.Stacks[j].Project }) + line, err := queue.Open(a.opts.Home, a.opts.Alive).List() + if err != nil { + return doc, err + } + for i, w := range line { + doc.Waiting = append(doc.Waiting, waitingEntry{Project: w.Project, Place: i + 1, MemoryBytes: w.Estimate, + Since: w.Since.UTC().Format(time.RFC3339)}) + } return doc, nil } @@ -120,12 +131,30 @@ func (a *app) memory(ctx context.Context, cs []docker.Container) (map[string]uin }(c.ID) } wg.Wait() + a.learnPeaks(cs, out) return out, firstErr } +// learnPeaks keeps the highest memory per repository and service in the losable cache; a +// cache that cannot be written is not worth failing a command for. +func (a *app) learnPeaks(cs []docker.Container, memory map[string]uint64) { + samples := budget.Peaks{} + for _, c := range cs { + m, ok := memory[c.ID] + repo, service := c.Labels[stack.LabelRepo], c.Labels[stack.LabelService] + if !ok || repo == "" || service == "" { + continue + } + if k := budget.PeakKey(repo, service); int64(m) > samples[k] { + samples[k] = int64(m) + } + } + _ = budget.Learn(a.opts.Home, samples) +} + func printPsText(cmd *cobra.Command, doc stackListDocument) error { if len(doc.Stacks) == 0 { - _, err := fmt.Fprintf(cmd.OutOrStdout(), "No stacks. Start one with siding up in a worktree. Memory budget %s.\n", bytesText(uint64(doc.BudgetBytes))) + _, err := fmt.Fprintf(cmd.OutOrStdout(), "No stacks. Start one with siding up in a worktree. Memory budget %s.\n%s", bytesText(uint64(doc.BudgetBytes)), waitingText(doc.Waiting)) return err } rows := [][]string{{"REPO", "BRANCH", "STATE", "URL", "MEMORY", "WORKTREE"}} @@ -136,13 +165,29 @@ func printPsText(cmd *cobra.Command, doc stackListDocument) error { } rows = append(rows, []string{s.Repo, s.Branch, s.State, s.URL, bytesText(s.MemoryBytes), worktree}) } - _, err := fmt.Fprintf(cmd.OutOrStdout(), "%stotal: %s of %s\n", table("", rows), bytesText(doc.MemoryBytes), bytesText(uint64(doc.BudgetBytes))) + text := fmt.Sprintf("%stotal: %s of %s\n", table("", rows), bytesText(doc.MemoryBytes), bytesText(uint64(doc.BudgetBytes))) + _, err := fmt.Fprint(cmd.OutOrStdout(), text+waitingText(doc.Waiting)) return err } -// bytesText shows memory in MiB, or GiB from 1 GiB on. +func waitingText(waiting []waitingEntry) string { + if len(waiting) == 0 { + return "" + } + rows := [][]string{} + for _, w := range waiting { + rows = append(rows, []string{fmt.Sprintf("%d.", w.Place), w.Project, "needs " + bytesText(uint64(w.MemoryBytes)), "since " + w.Since}) + } + return "waiting for memory:\n" + table(" ", rows) +} + +// bytesText shows memory in MiB, or GiB from 1 GiB on; less than half a MiB, but not nothing, is +// "<1 MiB". func bytesText(n uint64) string { const mib, gib = 1 << 20, 1 << 30 + if n > 0 && n < mib/2 { + return "<1 MiB" + } if n >= gib { return fmt.Sprintf("%.1f GiB", float64(n)/gib) } diff --git a/internal/cli/ps_test.go b/internal/cli/ps_test.go index 522c253..d81198f 100644 --- a/internal/cli/ps_test.go +++ b/internal/cli/ps_test.go @@ -5,6 +5,7 @@ import ( "testing" "github.com/tweinmann/siding/internal/docker" + "github.com/tweinmann/siding/internal/queue" "github.com/tweinmann/siding/internal/testutil" ) @@ -31,6 +32,11 @@ func TestPs(t *testing.T) { e.docker.memory["shop-main-db-1"] = 100 * mib e.docker.memory["shop-feature-login-web-1"] = 500 * mib + // An up waits in line for memory. + if _, err := queue.Open(e.opts.Home, e.opts.Alive).Enter(queue.Entry{Project: "shop-feature-x", PID: 777, Estimate: 768 * mib, Since: e.clock.now}); err != nil { + t.Fatal(err) + } + code, stdout, _ := e.run("ps", "--json") if code != exitOK { t.Fatalf("exit %d", code) @@ -42,6 +48,8 @@ func TestPs(t *testing.T) { shop feature/login partial http://shop.feature-login.localhost:8080/ 500 MiB /src/shop-login (missing) shop main running http://shop.main.localhost:8080/ 300 MiB /src/shop total: 800 MiB of 12.0 GiB +waiting for memory: + 1. shop-feature-x needs 768 MiB since 2026-10-28T12:00:00Z ` if text != want { t.Errorf("text:\n%s\nwant:\n%s", text, want) @@ -68,3 +76,15 @@ total: 800 MiB of 12.0 GiB } }) } + +func TestBytesText(t *testing.T) { + t.Parallel() + for _, tt := range []struct { + n uint64 + want string + }{{0, "0 MiB"}, {16, "<1 MiB"}, {1 << 19, "1 MiB"}, {7 << 20, "7 MiB"}, {3 << 29, "1.5 GiB"}} { + if got := bytesText(tt.n); got != tt.want { + t.Errorf("bytesText(%d) = %q, want %q", tt.n, got, tt.want) + } + } +} diff --git a/internal/cli/queue_test.go b/internal/cli/queue_test.go new file mode 100644 index 0000000..671c1ae --- /dev/null +++ b/internal/cli/queue_test.go @@ -0,0 +1,103 @@ +package cli + +import ( + "fmt" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/tweinmann/siding/internal/queue" +) + +// queueEnv: a 4 GiB budget, another repository's stack using 3.5 GiB, and this stack's estimate +// of 1 GiB: it does not fit until the other stack shrinks. +func queueEnv(t *testing.T) *env { + t.Helper() + const mib = 1 << 20 + e := newEnv(t) + e.proxyUp(80) + e.docker.proxy.Labels["dev.siding.budget"] = fmt.Sprint(4096 * mib) + other := e.id() + other.Repo, other.Branch, other.Worktree = "blog", "main", "/src/blog" + e.stackUp(other, "web") + e.docker.memory["blog-main-web-1"] = 3584 * mib + e.compose.onRun = func(r composeRun) { + if r.args[0] == "up" && r.inv.Project == "shop-main" { + e.stackUp(e.id(), "api", "db", "mail", "web") + } + } + return e +} + +func (e *env) shrinkOther() { + e.docker.mu.Lock() + defer e.docker.mu.Unlock() + e.docker.memory["blog-main-web-1"] = 1000 << 20 +} + +func TestQueue(t *testing.T) { + t.Parallel() + + t.Run("memory frees", func(t *testing.T) { + t.Parallel() + e := queueEnv(t) + e.clock.onSleep = func(n int) { + if n == 2 { + e.shrinkOther() + } + } + code, stdout, stderr := e.run("up", "--wait", "--json") + if code != exitOK || verdictOf(t, stdout) != "Ready" || !strings.Contains(stderr, "Waiting for memory: place 1 in line") { + t.Errorf("exit %d, stderr %q\n%s", code, stderr, stdout) + } + if files, _ := os.ReadDir(filepath.Join(e.opts.Home, ".siding", "queue")); len(files) != 0 { + t.Errorf("still in line: %v", files) + } + }) + + t.Run("time is up", func(t *testing.T) { + t.Parallel() + e := queueEnv(t) + code, stdout, _ := e.run("up", "--wait", "--timeout", "10s", "--json") + if code != exitNoCapacity || !strings.Contains(stdout, `"code": "NoCapacity"`) || !strings.Contains(stdout, "at place 1 in line") || len(e.compose.recorded()) != 0 { + t.Errorf("exit %d, compose runs %d\n%s", code, len(e.compose.recorded()), stdout) + } + if files, _ := os.ReadDir(filepath.Join(e.opts.Home, ".siding", "queue")); len(files) != 0 { + t.Errorf("still in line: %v", files) + } + }) + + t.Run("first come, first served", func(t *testing.T) { + t.Parallel() + e := queueEnv(t) + // Another up began to wait before this one. + line := queue.Open(e.opts.Home, e.opts.Alive) + if _, err := line.Enter(queue.Entry{Project: "big-main", PID: 1111, Estimate: 8 << 30, Since: e.clock.now.Add(-1)}); err != nil { + t.Fatal(err) + } + e.clock.onSleep = func(n int) { + switch n { + case 1: + e.shrinkOther() // this stack would fit now, but it is second + case 3: + if runs := len(e.compose.recorded()); runs != 0 { + t.Errorf("started before the first in line: %d compose runs", runs) + } + e.dead[1111] = true // the first waiter was killed + } + } + code, stdout, stderr := e.run("up", "--wait", "--json") + if code != exitOK || verdictOf(t, stdout) != "Ready" || !strings.Contains(stderr, "place 2 in line") || !strings.Contains(stderr, "place 1 in line") { + t.Errorf("exit %d, stderr %q", code, stderr) + } + }) + + t.Run("without --wait it refuses", func(t *testing.T) { + t.Parallel() + e := queueEnv(t) + if code, _, _ := e.run("up"); code != exitNoCapacity || e.clock.slept != 0 { + t.Errorf("exit %d, slept %d", code, e.clock.slept) + } + }) +} diff --git a/internal/cli/seed_test.go b/internal/cli/seed_test.go new file mode 100644 index 0000000..277f0ab --- /dev/null +++ b/internal/cli/seed_test.go @@ -0,0 +1,121 @@ +package cli + +import ( + "slices" + "strings" + "testing" + + "github.com/tweinmann/siding/internal/fail" +) + +// seedConfig is testConfig with seed labels on db (a seed command) and on a cache service +// (never seeded); web and api use the volume data. +const seedConfig = `{ + "name": "shop-main", + "services": { + "db": {"labels": {"dev.siding.seed": "script", "dev.siding.seed.command": "psql -f /seed.sql"}, "networks": {"default": null}, + "volumes": [{"type": "volume", "source": "pgdata", "target": "/var/lib/postgresql"}]}, + "cache": {"labels": {"dev.siding.seed": "none"}, "networks": {"default": null}, + "volumes": [{"type": "volume", "source": "cache", "target": "/cache"}]}, + "web": {"expose": ["80"], "labels": {"dev.siding.route": "/"}, "networks": {"default": null}, + "volumes": [{"type": "volume", "source": "data", "target": "/data"}]} + }, + "networks": {"default": {"name": "shop-main_default"}}, + "volumes": {"data": {"name": "shop-main_data"}, "pgdata": {"name": "shop-main_pgdata"}, "cache": {"name": "shop-main_cache"}} +}` + +// seedEnv is snapshotEnv with seedConfig, and Compose's up starting every service. +func seedEnv(t *testing.T) *env { + t.Helper() + e := snapshotEnv(t) + e.proxyUp(80) + e.compose.config = seedConfig + e.compose.onRun = func(r composeRun) { + if r.args[0] == "up" { + e.stackUp(e.id(), "cache", "db", "web") + } + } + return e +} + +func TestSeedPlanAndFirstUp(t *testing.T) { + t.Parallel() + + t.Run("invalid labels", func(t *testing.T) { + t.Parallel() + e := seedEnv(t) + e.compose.config = `{"services": {"db": {"labels": {"dev.siding.seed": "script"}}}}` + if code, stdout, _ := e.run("up", "--json"); code != exitFailed || !strings.Contains(stdout, `"code": "InvalidArguments"`) || len(e.compose.recorded()) != 0 { + t.Errorf("exit %d, %s", code, stdout) + } + }) + + t.Run("a later up seeds nothing", func(t *testing.T) { + t.Parallel() + e := seedEnv(t) + e.stackUp(e.id(), "web") // the stack ran before + code, _, stderr := e.run("up", "--seed", "base") + if code != exitOK || !strings.Contains(stderr, "already has data, so --seed base seeds nothing") { + t.Errorf("exit %d, stderr %q", code, stderr) + } + if len(e.docker.calls) != 0 || slices.ContainsFunc(composeCalls(e), func(c string) bool { return strings.Contains(c, " exec ") }) { + t.Errorf("seeded on a later up: docker %q, compose %q", e.docker.calls, composeCalls(e)) + } + }) + + t.Run("unknown snapshot", func(t *testing.T) { + t.Parallel() + e := seedEnv(t) + code, stdout, _ := e.run("up", "--seed", "nope", "--json") + if code != exitFailed || !strings.Contains(stdout, `"code": "`+fail.SnapshotNotFound+`"`) || !strings.Contains(stdout, "big") || len(e.compose.recorded()) != 0 { + t.Errorf("exit %d, %s", code, stdout) + } + }) +} + +func TestSeedFromSnapshot(t *testing.T) { + t.Parallel() + e := seedEnv(t) + code, _, stderr := e.run("up", "--seed", "base") + if code != exitOK { + t.Fatalf("exit %d: %s", code, stderr) + } + if !strings.Contains(stderr, "Seeding shop-main from the snapshot base: data\n") { + t.Errorf("up does not say what it seeds:\n%s", stderr) + } + // Only data: base has no pgdata (db seeds with its command anyway) and cache says none. + if want := []string{"create shop-main_data", "copy siding-snap_shop_base_data shop-main_data"}; !slices.Equal(e.docker.calls, want) { + t.Errorf("docker %q, want %q", e.docker.calls, want) + } + var created map[string]string + for _, v := range e.docker.volumes { + if v.Name == "shop-main_data" { + created = v.Labels + } + } + if created["com.docker.compose.project"] != "shop-main" || created["com.docker.compose.volume"] != "data" || created["dev.siding.repo"] != "shop" { + t.Errorf("labels of the seeded volume: %v", created) + } + calls := composeCalls(e) + if len(calls) != 2 || !strings.HasPrefix(calls[0], "shop-main up -d") || calls[1] != "shop-main exec -T db sh -c psql -f /seed.sql" { + t.Errorf("compose %q: want up, then the seed command", calls) + } +} + +func TestSeedCommandFails(t *testing.T) { + t.Parallel() + for _, wait := range []bool{false, true} { + e := seedEnv(t) + e.compose.execErr = fail.New(fail.ComposeFailed, "docker compose exec -T db sh -c psql -f /seed.sql failed with exit code 2") + e.compose.execOutput = "psql: ERROR: relation \"users\" already exists\npassword not-a-real-token\n" + args := []string{"up", "--json"} + if wait { + args = append(args, "--wait") + } + code, stdout, _ := e.run(args...) + if code != exitFailed || verdictOf(t, stdout) != "Failed" || !strings.Contains(stdout, `"reason": "SeedFailed"`) || + !strings.Contains(stdout, "relation") || strings.Contains(stdout, "not-a-real-token") || !strings.Contains(stdout, "exit code 2") { + t.Errorf("wait %v: exit %d\n%s", wait, code, stdout) + } + } +} diff --git a/internal/cli/setup.go b/internal/cli/setup.go index 234a716..cfb04d1 100644 --- a/internal/cli/setup.go +++ b/internal/cli/setup.go @@ -42,20 +42,21 @@ when something differs.`, return printJSON(cmd.OutOrStdout(), doc) } verb := map[string]string{"created": "started", "updated": "restarted", "unchanged": "already runs"}[doc.State] - _, err = fmt.Fprintf(cmd.OutOrStdout(), "%s %s on %s, memory budget %s\n", doc.Container, verb, - address("*.localhost", doc.Port, "/"), bytesText(uint64(doc.BudgetBytes))) + _, err = fmt.Fprintf(cmd.OutOrStdout(), "%s %s on %s, memory budget %s, %d build slots\n", doc.Container, verb, + address("*.localhost", doc.Port, "/"), bytesText(uint64(doc.BudgetBytes)), doc.Builds) return err }, } cmd.Flags().IntVar(&f.port, "port", 0, "port on 127.0.0.1 for the proxy (default: the running proxy's, else 80)") + cmd.Flags().StringVar(&f.builds, "builds", "", "how many stacks may build images at once; \"default\" for half of Docker's CPUs (default: the number set before)") cmd.Flags().StringVar(&f.budget, "budget", "", "memory budget for all stacks, e.g. 12g; \"default\" for 75% of Docker's memory (default: the budget set before)") registerJSON(cmd, &asJSON) return cmd } type setupFlags struct { - port int - budget string + port int + budget, builds string } func (a *app) setup(cmd *cobra.Command, f setupFlags) (setupDocument, error) { @@ -91,6 +92,18 @@ func (a *app) setup(cmd *cobra.Command, f setupFlags) (setupDocument, error) { } } + switch f.builds { + case "": + if current != nil { + settings.Builds, _ = strconv.Atoi(current.Labels[stack.LabelBuilds]) + } + case "default": + default: + if settings.Builds, err = strconv.Atoi(f.builds); err != nil || settings.Builds < 1 { + return setupDocument{}, fail.New(fail.InvalidArguments, "--builds must be a number of at least 1 or \"default\", got %q", f.builds) + } + } + if _, err := a.opts.Docker.EnsureNetwork(ctx, cfg.Network, map[string]string{stack.LabelMachine: machine}); err != nil { return setupDocument{}, err } @@ -135,9 +148,26 @@ func (a *app) setup(cmd *cobra.Command, f setupFlags) (setupDocument, error) { if doc.BudgetBytes, err = a.budget(ctx, after); err != nil { return setupDocument{}, err } + if doc.Builds, err = a.builds(ctx, after); err != nil { + return setupDocument{}, err + } return doc, nil } +// builds is the number of build slots: the proxy's label, else half of Docker's CPUs, at least 1. +func (a *app) builds(ctx context.Context, proxyContainer *docker.Container) (int, error) { + if proxyContainer != nil { + if n, err := strconv.Atoi(proxyContainer.Labels[stack.LabelBuilds]); err == nil && n > 0 { + return n, nil + } + } + cpus, err := a.opts.Docker.NCPU(ctx) + if err != nil { + return 0, err + } + return max(1, cpus/2), nil +} + // hostPort is the port on the host a proxy container publishes, or 0. func hostPort(c *docker.Container) int { if c == nil { diff --git a/internal/cli/setup_test.go b/internal/cli/setup_test.go index c2eae29..f94710c 100644 --- a/internal/cli/setup_test.go +++ b/internal/cli/setup_test.go @@ -66,7 +66,7 @@ func TestSetup(t *testing.T) { e := newEnv(t) setupDoc(t, e) code, stdout, _ := e.run("setup") - if code != exitOK || stdout != "siding-proxy already runs on http://*.localhost/, memory budget 12.0 GiB\n" { + if code != exitOK || stdout != "siding-proxy already runs on http://*.localhost/, memory budget 12.0 GiB, 4 build slots\n" { t.Errorf("exit %d, stdout %q", code, stdout) } }) @@ -110,6 +110,26 @@ func TestSetup(t *testing.T) { } }) + t.Run("build slots", func(t *testing.T) { + t.Parallel() + e := newEnv(t) + if doc := setupDoc(t, e); doc.Builds != 4 { + t.Errorf("default with 8 CPUs: %d", doc.Builds) + } + if doc := setupDoc(t, e, "--builds", "2"); doc.Builds != 2 || e.docker.proxy.Labels["dev.siding.builds"] != "2" { + t.Errorf("set: %+v", doc) + } + if doc := setupDoc(t, e); doc.State != "unchanged" || doc.Builds != 2 { + t.Errorf("kept: %+v", doc) + } + if doc := setupDoc(t, e, "--builds", "default"); doc.Builds != 4 { + t.Errorf("default: %+v", doc) + } + if code, stdout, _ := e.run("setup", "--builds", "0", "--json"); code != exitFailed || !strings.Contains(stdout, `"code": "InvalidArguments"`) { + t.Errorf("--builds 0: exit %d, %s", code, stdout) + } + }) + t.Run("a proxy of siding v0.1", func(t *testing.T) { t.Parallel() e := newEnv(t) diff --git a/internal/cli/snapshot.go b/internal/cli/snapshot.go new file mode 100644 index 0000000..84c3128 --- /dev/null +++ b/internal/cli/snapshot.go @@ -0,0 +1,285 @@ +package cli + +import ( + "context" + "fmt" + "slices" + "sort" + "strings" + + "github.com/spf13/cobra" + + "github.com/tweinmann/siding/internal/compose" + "github.com/tweinmann/siding/internal/fail" + "github.com/tweinmann/siding/internal/snapshot" + "github.com/tweinmann/siding/internal/stack" +) + +func newSnapshotCommand(a *app) *cobra.Command { + cmd := &cobra.Command{ + Use: "snapshot", + Short: "Save, list and remove snapshots of a stack's volumes", + Long: `Snapshots are copies of a stack's named volumes, kept as Docker volumes per repository. A new +stack of the same repository can start from one with siding up --seed . Snapshots outlive +stacks: down --volumes and gc never remove them.`, + } + cmd.AddCommand(newSnapshotSaveCommand(a), newSnapshotLsCommand(a), newSnapshotRmCommand(a)) + return cmd +} + +func newSnapshotSaveCommand(a *app) *cobra.Command { + var asJSON, force bool + var file string + cmd := &cobra.Command{ + Use: "save ", + Short: "Copy the worktree's stack's volumes into a snapshot", + Long: `Copy every named volume of the worktree's stack into the snapshot . The services that use +those volumes are stopped while copying, so databases are consistent, and started again.`, + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + doc, err := a.snapshotSave(cmd, args[0], file, force) + if err != nil { + return err + } + if asJSON { + return printJSON(cmd.OutOrStdout(), doc) + } + _, err = fmt.Fprintf(cmd.OutOrStdout(), "Saved the snapshot %s of %s: %s\n", doc.Name, doc.Repo, strings.Join(snapshotVolumeKeys(doc), ", ")) + return err + }, + } + cmd.Flags().BoolVar(&force, "force", false, "replace a snapshot of the same name") + cmd.Flags().StringVarP(&file, "file", "f", "", "compose file (default: compose.yaml or another name Compose looks for)") + registerJSON(cmd, &asJSON) + return cmd +} + +func (a *app) snapshotSave(cmd *cobra.Command, name, file string, force bool) (snapshotDocument, error) { + ctx := cmd.Context() + if err := snapshot.ValidName(name); err != nil { + return snapshotDocument{}, err + } + st, err := a.findStack(ctx) + if err != nil { + return snapshotDocument{}, err + } + _, p, err := a.loadProject(ctx, st.wt.Top, file, st.project) + if err != nil { + return snapshotDocument{}, err + } + var keys []string + for key, v := range p.Volumes { + if !v.External { + keys = append(keys, key) + } + } + sort.Strings(keys) + if len(keys) == 0 { + return snapshotDocument{}, fail.New(fail.InvalidArguments, "the stack %s has no named volumes: there is nothing to save", st.project) + } + existing, err := a.snapshots(ctx, false) + if err != nil { + return snapshotDocument{}, err + } + if old, err := snapshot.Find(existing, st.id.Repo, name); err == nil { + if !force { + return snapshotDocument{}, snapshot.ExistsError(st.id.Repo, name) + } + for _, v := range old.Volumes { + if err := a.opts.Docker.RemoveVolume(ctx, v); err != nil { + return snapshotDocument{}, err + } + } + } + machine, err := a.machineID() + if err != nil { + return snapshotDocument{}, err + } + + // Stop the services that write into the volumes, and start them again whatever happens. + var services []string + for _, svc := range p.ServiceNames() { + if slices.ContainsFunc(p.Services[svc].Volumes, func(k string) bool { return slices.Contains(keys, k) }) { + services = append(services, svc) + } + } + inv := compose.Invocation{Dir: st.wt.Top, Project: st.project} + stderr := cmd.ErrOrStderr() + if len(services) > 0 { + _, _ = fmt.Fprintf(stderr, "Stopping %s while copying their volumes\n", strings.Join(services, ", ")) + if err := a.opts.Compose.Run(ctx, inv, append([]string{"stop"}, services...), stderr, stderr); err != nil { + return snapshotDocument{}, err + } + defer func() { + _ = a.opts.Compose.Run(context.WithoutCancel(ctx), inv, append([]string{"start"}, services...), stderr, stderr) + }() + } + + created := a.opts.Clock.Now() + doc := snapshotDocument{header: newHeader(kindSnapshot), Name: name, Repo: st.id.Repo, Created: created.UTC().Format("2006-01-02T15:04:05Z")} + for _, key := range keys { + to := snapshot.VolumeName(st.id.Repo, name, key) + if err := a.opts.Docker.CreateVolume(ctx, to, snapshot.Labels(st.id.Repo, name, key, machine, created)); err != nil { + return snapshotDocument{}, err + } + exit, out, err := a.opts.Docker.RunHelper(ctx, snapshot.CopyHelper(p.Volumes[key].Name, to, machine)) + if err == nil && exit != 0 { + err = fail.New(fail.Internal, "copying %s into the snapshot failed with exit code %d: %s", key, exit, strings.Join(out, "; ")) + } + if err != nil { + _ = a.opts.Docker.RemoveVolume(context.WithoutCancel(ctx), to) + for _, v := range doc.Volumes { + _ = a.opts.Docker.RemoveVolume(context.WithoutCancel(ctx), v.Snapshot) + } + return snapshotDocument{}, err + } + doc.Volumes = append(doc.Volumes, snapshotVolume{Key: key, Source: p.Volumes[key].Name, Snapshot: to}) + } + return doc, nil +} + +// snapshots lists the snapshots of this machine, with sizes when withSizes. +func (a *app) snapshots(ctx context.Context, withSizes bool) ([]snapshot.Snapshot, error) { + if err := a.opts.Docker.Ping(ctx); err != nil { + return nil, err + } + machine, err := a.machineID() + if err != nil { + return nil, err + } + vols, err := a.opts.Docker.Volumes(ctx, map[string]string{snapshot.LabelName: "", stack.LabelMachine: machine}) + if err != nil { + return nil, err + } + var sizes map[string]int64 + if withSizes { + if sizes, err = a.opts.Docker.VolumeSizes(ctx); err != nil { + return nil, err + } + } + return snapshot.Group(vols, sizes), nil +} + +func snapshotVolumeKeys(doc snapshotDocument) []string { + var keys []string + for _, v := range doc.Volumes { + keys = append(keys, v.Key) + } + return keys +} + +// currentRepo is the repository the current directory belongs to, as siding names it: the +// label of the worktree's stack (which --repo may have set), else the main worktree's +// directory. Outside a repository it is "". +func (a *app) currentRepo(ctx context.Context) string { + if st, err := a.findStack(ctx); err == nil { + return st.id.Repo + } + if wt, err := a.opts.Git.Worktree(ctx, a.opts.Dir); err == nil { + return wt.RepoName() + } + return "" +} + +func newSnapshotLsCommand(a *app) *cobra.Command { + var asJSON bool + cmd := &cobra.Command{ + Use: "ls", + Short: "List the snapshots of this repository, or of every repository outside one", + Args: noArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + ctx := cmd.Context() + all, err := a.snapshots(ctx, true) + if err != nil { + return err + } + repo := a.currentRepo(ctx) + doc := snapshotListDocument{header: newHeader(kindSnapshotList)} + for _, s := range all { + if repo != "" && s.Repo != repo { + continue + } + e := snapshotEntry{Name: s.Name, Repo: s.Repo, Created: s.Created, SizeBytes: s.Size} + for key := range s.Volumes { + e.Volumes = append(e.Volumes, key) + } + sort.Strings(e.Volumes) + doc.Snapshots = append(doc.Snapshots, e) + } + if asJSON { + return printJSON(cmd.OutOrStdout(), doc) + } + if len(doc.Snapshots) == 0 { + _, err := fmt.Fprintln(cmd.OutOrStdout(), "No snapshots. Save one with siding snapshot save in a stack.") + return err + } + rows := [][]string{{"REPO", "NAME", "VOLUMES", "SIZE", "CREATED"}} + for _, e := range doc.Snapshots { + size := "?" + if e.SizeBytes >= 0 { + size = bytesText(uint64(e.SizeBytes)) + } + rows = append(rows, []string{e.Repo, e.Name, strings.Join(e.Volumes, ", "), size, e.Created}) + } + _, err = fmt.Fprint(cmd.OutOrStdout(), table("", rows)) + return err + }, + } + registerJSON(cmd, &asJSON) + return cmd +} + +func newSnapshotRmCommand(a *app) *cobra.Command { + var asJSON, dryRun bool + cmd := &cobra.Command{ + Use: "rm ", + Short: "Remove a snapshot of this repository", + Args: cobra.ExactArgs(1), + RunE: func(cmd *cobra.Command, args []string) error { + ctx := cmd.Context() + all, err := a.snapshots(ctx, false) + if err != nil { + return err + } + repo := a.currentRepo(ctx) + if repo == "" { + return fail.New(fail.NotAGitRepository, "%s is not inside a git worktree", a.opts.Dir). + WithHint("run siding snapshot rm in a worktree of the snapshot's repository") + } + s, err := snapshot.Find(all, repo, args[0]) + if err != nil { + return err + } + doc := snapshotDocument{header: newHeader(kindSnapshot), Name: s.Name, Repo: s.Repo, Created: s.Created, DryRun: dryRun} + for _, key := range sortedVolumeKeys(s) { + doc.Volumes = append(doc.Volumes, snapshotVolume{Key: key, Snapshot: s.Volumes[key]}) + if !dryRun { + if err := a.opts.Docker.RemoveVolume(ctx, s.Volumes[key]); err != nil { + return err + } + } + } + if asJSON { + return printJSON(cmd.OutOrStdout(), doc) + } + verb := "Removed" + if dryRun { + verb = "Would remove" + } + _, err = fmt.Fprintf(cmd.OutOrStdout(), "%s the snapshot %s of %s: %s\n", verb, s.Name, s.Repo, strings.Join(snapshotVolumeKeys(doc), ", ")) + return err + }, + } + cmd.Flags().BoolVar(&dryRun, "dry-run", false, "list what would be removed, remove nothing") + registerJSON(cmd, &asJSON) + return cmd +} + +func sortedVolumeKeys(s snapshot.Snapshot) []string { + keys := make([]string, 0, len(s.Volumes)) + for k := range s.Volumes { + keys = append(keys, k) + } + sort.Strings(keys) + return keys +} diff --git a/internal/cli/snapshot_test.go b/internal/cli/snapshot_test.go new file mode 100644 index 0000000..0b5df88 --- /dev/null +++ b/internal/cli/snapshot_test.go @@ -0,0 +1,168 @@ +package cli + +import ( + "path/filepath" + "slices" + "strings" + "testing" + + "github.com/tweinmann/siding/internal/docker" + "github.com/tweinmann/siding/internal/fail" + "github.com/tweinmann/siding/internal/snapshot" + "github.com/tweinmann/siding/internal/testutil" +) + +// composeCalls are the compose runs as " ". +func composeCalls(e *env) []string { + var out []string + for _, r := range e.compose.recorded() { + out = append(out, r.inv.Project+" "+strings.Join(r.args, " ")) + } + return out +} + +func TestSnapshotSave(t *testing.T) { + t.Parallel() + + t.Run("save", func(t *testing.T) { + t.Parallel() + e := newEnv(t) + e.stackUp(e.id(), "db", "web") + code, stdout, stderr := e.run("snapshot", "save", "base", "--json") + if code != exitOK { + t.Fatalf("exit %d: %s %s", code, stdout, stderr) + } + testutil.Golden(t, filepath.Join("testdata", "json", "snapshot.json"), []byte(stdout)) + if got, want := composeCalls(e), []string{"shop-main stop db", "shop-main start db"}; !slices.Equal(got, want) { + t.Errorf("compose %q, want %q", got, want) + } + if got, want := e.docker.calls, []string{"create siding-snap_shop_base_data", "copy shop-main_data siding-snap_shop_base_data"}; !slices.Equal(got, want) { + t.Errorf("docker %q, want %q", got, want) + } + if !strings.Contains(stderr, "Stopping db while copying") { + t.Errorf("stderr %q", stderr) + } + }) + + t.Run("a taken name", func(t *testing.T) { + t.Parallel() + e := newEnv(t) + e.stackUp(e.id(), "db") + if code, _, _ := e.run("snapshot", "save", "base"); code != exitOK { + t.Fatal("first save failed") + } + if code, stdout, _ := e.run("snapshot", "save", "base", "--json"); code != exitFailed || !strings.Contains(stdout, `"code": "SnapshotExists"`) { + t.Errorf("second save: exit %d, %s", code, stdout) + } + e.docker.calls = nil + if code, _, _ := e.run("snapshot", "save", "base", "--force"); code != exitOK { + t.Fatal("--force failed") + } + if got, want := e.docker.calls, []string{"remove siding-snap_shop_base_data", "create siding-snap_shop_base_data", "copy shop-main_data siding-snap_shop_base_data"}; !slices.Equal(got, want) { + t.Errorf("--force: %q, want %q", got, want) + } + }) + + t.Run("the copy fails", func(t *testing.T) { + t.Parallel() + e := newEnv(t) + e.stackUp(e.id(), "db") + e.docker.helperExit = 1 + code, _, stderr := e.run("snapshot", "save", "base") + if code != exitFailed || !strings.Contains(stderr, "No space left on device") { + t.Errorf("exit %d, stderr %q", code, stderr) + } + if got := composeCalls(e); !slices.Equal(got, []string{"shop-main stop db", "shop-main start db"}) { + t.Errorf("the services were not started again: %q", got) + } + if slices.ContainsFunc(e.docker.volumes, func(v docker.Volume) bool { return strings.HasPrefix(v.Name, "siding-snap_") }) { + t.Error("a half snapshot is left") + } + }) + + for _, tt := range []struct { + name, config string + args []string + }{ + {name: "no volumes", config: `{"services": {"web": {"expose": ["80"]}}}`, args: []string{"snapshot", "save", "base", "--json"}}, + {name: "a bad name", args: []string{"snapshot", "save", "Base_1", "--json"}}, + } { + t.Run(tt.name, func(t *testing.T) { + t.Parallel() + e := newEnv(t) + if tt.config != "" { + e.compose.config = tt.config + } + e.stackUp(e.id(), "web") + code, stdout, _ := e.run(tt.args...) + if code != exitFailed || !strings.Contains(stdout, `"code": "`+fail.InvalidArguments+`"`) || len(e.docker.calls) != 0 { + t.Errorf("exit %d, %s, docker %q", code, stdout, e.docker.calls) + } + }) + } +} + +// snapshotEnv has the snapshots shop/base, shop/big and blog/base of this machine and one of +// another machine. +func snapshotEnv(t *testing.T) *env { + t.Helper() + e := newEnv(t) + machine := e.id().Machine + add := func(repo, name, key, m string) { + e.docker.volumes = append(e.docker.volumes, docker.Volume{Name: snapshot.VolumeName(repo, name, key), + Labels: snapshot.Labels(repo, name, key, m, e.clock.now)}) + } + add("shop", "base", "data", machine) + add("shop", "base", "uploads", machine) + add("shop", "big", "data", machine) + add("blog", "base", "data", machine) + add("shop", "remote", "data", "another-machine") + return e +} + +func TestSnapshotLsRm(t *testing.T) { + t.Parallel() + + t.Run("ls in a repository", func(t *testing.T) { + t.Parallel() + e := snapshotEnv(t) + code, stdout, _ := e.run("snapshot", "ls", "--json") + if code != exitOK { + t.Fatalf("exit %d", code) + } + testutil.Golden(t, filepath.Join("testdata", "json", "snapshotlist.json"), []byte(stdout)) + _, text, _ := e.run("snapshot", "ls") + want := "REPO NAME VOLUMES SIZE CREATED\nshop base data, uploads 2 MiB 2026-10-28T12:00:00Z\nshop big data 1 MiB 2026-10-28T12:00:00Z\n" + if text != want { + t.Errorf("text:\n%s\nwant:\n%s", text, want) + } + }) + + t.Run("ls outside a repository", func(t *testing.T) { + t.Parallel() + e := snapshotEnv(t) + e.opts.Dir = t.TempDir() + _, stdout, _ := e.run("snapshot", "ls") + if !strings.Contains(stdout, "blog base") || strings.Contains(stdout, "remote") { + t.Errorf("stdout:\n%s", stdout) + } + }) + + t.Run("rm", func(t *testing.T) { + t.Parallel() + e := snapshotEnv(t) + if code, stdout, _ := e.run("snapshot", "rm", "base", "--dry-run"); code != exitOK || !strings.HasPrefix(stdout, "Would remove the snapshot base of shop: data, uploads") || len(e.docker.calls) != 0 { + t.Errorf("dry run: exit %d, %q, %q", code, stdout, e.docker.calls) + } + if code, _, _ := e.run("snapshot", "rm", "base"); code != exitOK { + t.Fatal("rm failed") + } + want := []string{"remove siding-snap_shop_base_data", "remove siding-snap_shop_base_uploads"} + if !slices.Equal(e.docker.calls, want) { + t.Errorf("removed %q, want %q", e.docker.calls, want) + } + if code, stdout, _ := e.run("snapshot", "rm", "nope", "--json"); code != exitFailed || !strings.Contains(stdout, `"code": "SnapshotNotFound"`) || !strings.Contains(stdout, "big") { + t.Errorf("unknown: exit %d, %s", code, stdout) + } + }) +} diff --git a/internal/cli/stack.go b/internal/cli/stack.go index a43897e..eb7cf9b 100644 --- a/internal/cli/stack.go +++ b/internal/cli/stack.go @@ -37,6 +37,12 @@ func (s existing) ref(port int) stackRef { // whose containers carry this worktree and branch. Asking Docker rather than recomputing the // name keeps --repo, given once to up, out of every later command. func (a *app) findStack(ctx context.Context) (existing, error) { + return a.findStackOrData(ctx, false) +} + +// findStackOrData is findStack, and with data also a stack of which only volumes are left (after +// siding down), found by the labels on its volumes. +func (a *app) findStackOrData(ctx context.Context, data bool) (existing, error) { wt, err := a.opts.Git.Worktree(ctx, a.opts.Dir) if err != nil { return existing{}, err @@ -48,6 +54,17 @@ func (a *app) findStack(ctx context.Context) (existing, error) { if err != nil { return existing{}, err } + if len(cs) == 0 && data { + vs, err := a.opts.Docker.Volumes(ctx, map[string]string{stack.LabelWorktree: wt.Top, stack.LabelBranch: wt.Branch}) + if err != nil { + return existing{}, err + } + for _, v := range vs { + if p := v.Labels[stack.LabelProject]; p != "" { + return existing{wt: wt, id: stack.FromLabels(v.Labels), project: p}, nil + } + } + } if len(cs) == 0 { return existing{}, fail.New(fail.StackNotFound, "the worktree %s has no stack for the branch %s", wt.Top, wt.Branch). WithHint("start it with siding up") diff --git a/internal/cli/status.go b/internal/cli/status.go index 88d822f..1795339 100644 --- a/internal/cli/status.go +++ b/internal/cli/status.go @@ -62,7 +62,7 @@ Exit codes: 0 Ready, 1 Failed, 2 TimedOut (or Starting without --wait).`, if err != nil { return err } - doc, err := a.status(ctx, st, p, port, w) + doc, err := a.status(ctx, st, p, port, w, nil) if err != nil { return err } @@ -76,7 +76,9 @@ Exit codes: 0 Ready, 1 Failed, 2 TimedOut (or Starting without --wait).`, } // status evaluates the stack once, or until it is Ready or Failed or the time is up. -func (a *app) status(ctx context.Context, st existing, p *compose.Project, port int, w waitFlags) (statusDocument, error) { +// seedFailure, when set, is a failed seed command of the up that called status; it decides the +// verdict. +func (a *app) status(ctx context.Context, st existing, p *compose.Project, port int, w waitFlags, seedFailure *verdict.Failure) (statusDocument, error) { routes, _, err := stack.Routes(p) if err != nil { return statusDocument{}, err @@ -104,9 +106,12 @@ func (a *app) status(ctx context.Context, st existing, p *compose.Project, port final := w.wait && a.opts.Clock.Now().Sub(start) >= w.timeout res := verdict.Evaluate(verdict.Input{ Services: p.ServiceNames(), Containers: cs, Routes: routed, Answering: answering, - RestartBase: base, Final: final, Timeout: w.timeout, + RestartBase: base, Final: final, Timeout: w.timeout, Seed: seedFailure, }) if !w.wait || final || res.Verdict == verdict.Ready || res.Verdict == verdict.Failed { + if res.Verdict == verdict.Ready { + _, _ = a.memory(ctx, cs) // learns this stack's peaks (design D7) + } return a.statusDocument(ctx, st, p, routes, port, cs, res) } if err := a.opts.Clock.Sleep(ctx, pollInterval); err != nil { @@ -147,15 +152,17 @@ func (a *app) statusDocument(ctx context.Context, st existing, p *compose.Projec } if f := res.Failure; f != nil { doc.Failure = &failureDocument{Service: f.Service, Reason: f.Reason, Hint: f.Hint} - if containers := byService(cs)[f.Service]; len(containers) > 0 { + r, err := redactor(st.wt.Top, p) + if err != nil { + return statusDocument{}, err + } + if f.Output != nil { + doc.Failure.Logs = r.Lines(f.Output) + } else if containers := byService(cs)[f.Service]; len(containers) > 0 { lines, err := a.opts.Docker.Logs(ctx, failing(containers).ID, logTail) if err != nil { return statusDocument{}, err } - r, err := redactor(st.wt.Top, p) - if err != nil { - return statusDocument{}, err - } doc.Failure.Logs = r.Lines(lines) } } diff --git a/internal/cli/teardown.go b/internal/cli/teardown.go index 9c7e822..2cb545e 100644 --- a/internal/cli/teardown.go +++ b/internal/cli/teardown.go @@ -17,7 +17,7 @@ import ( ) func newTeardownCommand(a *app) *cobra.Command { - var asJSON, dryRun bool + var asJSON, dryRun, snapshots bool cmd := &cobra.Command{ Use: "teardown", Short: "Remove siding-proxy and its network; stacks keep running", @@ -26,7 +26,7 @@ network "siding" unless a stack still uses it. Stacks are never touched: they ke plain Compose projects, without the proxy. Remove them first with siding down or siding gc.`, Args: noArgs, RunE: func(cmd *cobra.Command, _ []string) error { - doc, err := a.teardown(cmd, dryRun) + doc, err := a.teardown(cmd, dryRun, snapshots) if err != nil { return err } @@ -37,11 +37,12 @@ plain Compose projects, without the proxy. Remove them first with siding down or }, } cmd.Flags().BoolVar(&dryRun, "dry-run", false, "list what would be removed, remove nothing") + cmd.Flags().BoolVar(&snapshots, "snapshots", false, "also remove every snapshot of this machine") registerJSON(cmd, &asJSON) return cmd } -func (a *app) teardown(cmd *cobra.Command, dryRun bool) (teardownDocument, error) { +func (a *app) teardown(cmd *cobra.Command, dryRun, withSnapshots bool) (teardownDocument, error) { ctx := cmd.Context() cfg := a.opts.Proxy doc := teardownDocument{header: newHeader(kindTeardown), DryRun: dryRun} @@ -76,9 +77,29 @@ func (a *app) teardown(cmd *cobra.Command, dryRun bool) (teardownDocument, error case exists: doc.KeptNetwork = cfg.Network } + snaps, err := a.snapshots(ctx, false) + if err != nil { + return doc, err + } + for _, s := range snaps { + if withSnapshots { + doc.Snapshots = append(doc.Snapshots, s.String()) + } else { + doc.KeptSnapshots = append(doc.KeptSnapshots, s.String()) + } + } if dryRun { return doc, nil } + if withSnapshots { + for _, s := range snaps { + for _, v := range s.Volumes { + if err := a.opts.Docker.RemoveVolume(ctx, v); err != nil { + return doc, err + } + } + } + } dir := filepath.Join(a.opts.Home, ".siding", "proxy", cfg.Project) if doc.Container != "" { @@ -107,7 +128,7 @@ func printTeardownText(cmd *cobra.Command, doc teardownDocument) error { if doc.DryRun { verb = "Would remove" } - if doc.Container == "" && doc.Network == "" { + if doc.Container == "" && doc.Network == "" && len(doc.Snapshots) == 0 { b.WriteString("Nothing to remove: siding-proxy does not run here.\n") } if doc.Container != "" { @@ -122,6 +143,12 @@ func printTeardownText(cmd *cobra.Command, doc teardownDocument) error { if len(doc.Stacks) > 0 { fmt.Fprintf(&b, "These stacks keep running, without the proxy: %s\nRemove them with siding down in their worktree, or siding gc.\n", strings.Join(doc.Stacks, ", ")) } + if len(doc.Snapshots) > 0 { + fmt.Fprintf(&b, "%s the snapshots %s\n", verb, strings.Join(doc.Snapshots, ", ")) + } + if len(doc.KeptSnapshots) > 0 { + fmt.Fprintf(&b, "Kept the snapshots %s; siding teardown --snapshots removes them.\n", strings.Join(doc.KeptSnapshots, ", ")) + } if doc.DryRun { b.WriteString("Dry run: nothing was removed.\n") } diff --git a/internal/cli/teardown_test.go b/internal/cli/teardown_test.go index 71fe128..2cd097a 100644 --- a/internal/cli/teardown_test.go +++ b/internal/cli/teardown_test.go @@ -78,3 +78,25 @@ func TestTeardown(t *testing.T) { } }) } + +func TestTeardownSnapshots(t *testing.T) { + t.Parallel() + e := snapshotEnv(t) + setupDoc(t, e) + code, stdout, _ := e.run("teardown", "--dry-run") + if code != exitOK || !strings.Contains(stdout, "Kept the snapshots blog/base, shop/base, shop/big; siding teardown --snapshots removes them.") { + t.Errorf("without --snapshots: exit %d\n%s", code, stdout) + } + if code, _, _ := e.run("teardown", "--snapshots"); code != exitOK { + t.Fatal("teardown --snapshots failed") + } + var removed []string + for _, c := range e.docker.calls { + removed = append(removed, strings.TrimPrefix(c, "remove ")) + } + slices.Sort(removed) + want := []string{"siding-snap_blog_base_data", "siding-snap_shop_base_data", "siding-snap_shop_base_uploads", "siding-snap_shop_big_data"} + if !slices.Equal(removed, want) { + t.Errorf("removed %q, want %q (the other machine's snapshot stays)", removed, want) + } +} diff --git a/internal/cli/testdata/json/setup.json b/internal/cli/testdata/json/setup.json index 5a9b417..503c434 100644 --- a/internal/cli/testdata/json/setup.json +++ b/internal/cli/testdata/json/setup.json @@ -7,5 +7,6 @@ "port": 80, "url": "http://*.localhost/", "state": "created", - "budgetBytes": 12884901888 + "budgetBytes": 12884901888, + "builds": 4 } diff --git a/internal/cli/testdata/json/snapshot.json b/internal/cli/testdata/json/snapshot.json new file mode 100644 index 0000000..5e935ab --- /dev/null +++ b/internal/cli/testdata/json/snapshot.json @@ -0,0 +1,14 @@ +{ + "apiVersion": "siding.dev/v1alpha1", + "kind": "Snapshot", + "name": "base", + "repo": "shop", + "created": "2026-10-28T12:00:00Z", + "volumes": [ + { + "key": "data", + "source": "shop-main_data", + "snapshot": "siding-snap_shop_base_data" + } + ] +} diff --git a/internal/cli/testdata/json/snapshotlist.json b/internal/cli/testdata/json/snapshotlist.json new file mode 100644 index 0000000..e4bd24d --- /dev/null +++ b/internal/cli/testdata/json/snapshotlist.json @@ -0,0 +1,25 @@ +{ + "apiVersion": "siding.dev/v1alpha1", + "kind": "SnapshotList", + "snapshots": [ + { + "name": "base", + "repo": "shop", + "created": "2026-10-28T12:00:00Z", + "volumes": [ + "data", + "uploads" + ], + "sizeBytes": 2097152 + }, + { + "name": "big", + "repo": "shop", + "created": "2026-10-28T12:00:00Z", + "volumes": [ + "data" + ], + "sizeBytes": 1048576 + } + ] +} diff --git a/internal/cli/testdata/json/stacklist.json b/internal/cli/testdata/json/stacklist.json index efe7450..fdf0dad 100644 --- a/internal/cli/testdata/json/stacklist.json +++ b/internal/cli/testdata/json/stacklist.json @@ -26,5 +26,13 @@ } ], "memoryBytes": 838860800, - "budgetBytes": 12884901888 + "budgetBytes": 12884901888, + "waiting": [ + { + "project": "shop-feature-x", + "place": 1, + "memoryBytes": 805306368, + "since": "2026-10-28T12:00:00Z" + } + ] } diff --git a/internal/cli/testdata/ui/page.html b/internal/cli/testdata/ui/page.html index ced5d3a..1592a0e 100644 --- a/internal/cli/testdata/ui/page.html +++ b/internal/cli/testdata/ui/page.html @@ -49,6 +49,16 @@

Stacks

+ +

Waiting for memory

+ + + + + +
PlaceStackNeedsSince
1shop-feature-x768 MiB2026-10-28T12:00:00Z
+ +

Can go

diff --git a/internal/cli/ui.go b/internal/cli/ui.go index c0209d7..7323aba 100644 --- a/internal/cli/ui.go +++ b/internal/cli/ui.go @@ -24,7 +24,8 @@ import ( var pageHTML string var pageTemplate = template.Must(template.New("page").Funcs(template.FuncMap{ - "bytes": bytesText, + "bytes": bytesText, + "bytes64": func(n int64) string { return bytesText(uint64(n)) }, }).Parse(pageHTML)) type pageData struct { diff --git a/internal/cli/ui/page.html b/internal/cli/ui/page.html index 64fc2c4..0fa30d2 100644 --- a/internal/cli/ui/page.html +++ b/internal/cli/ui/page.html @@ -45,6 +45,16 @@

Stacks

No stacks. Start one with siding up in a worktree.

{{end}} +{{if .Stacks.Waiting}} +

Waiting for memory

+
+ +{{range .Stacks.Waiting}} + +{{end}} +
PlaceStackNeedsSince
{{.Place}}{{.Project}}{{bytes64 .MemoryBytes}}{{.Since}}
+{{end}} +

Can go

{{if .GC.Stacks}} diff --git a/internal/cli/up.go b/internal/cli/up.go index 86678d3..8fbd795 100644 --- a/internal/cli/up.go +++ b/internal/cli/up.go @@ -8,14 +8,20 @@ import ( "path/filepath" "slices" "strings" + "time" "github.com/spf13/cobra" "github.com/tweinmann/siding/internal/budget" + "github.com/tweinmann/siding/internal/buildslot" "github.com/tweinmann/siding/internal/compose" "github.com/tweinmann/siding/internal/docker" "github.com/tweinmann/siding/internal/fail" + "github.com/tweinmann/siding/internal/queue" + "github.com/tweinmann/siding/internal/seed" + "github.com/tweinmann/siding/internal/snapshot" "github.com/tweinmann/siding/internal/stack" + "github.com/tweinmann/siding/internal/verdict" ) func newUpCommand(a *app) *cobra.Command { @@ -52,6 +58,7 @@ With --wait, up ends like siding status --wait, with its verdict and exit code.` cmd.Flags().StringVar(&f.repo, "repo", "", "repository name (default: the main worktree's directory name)") cmd.Flags().StringVar(&f.agent, "agent", "", "agent name for the label dev.siding.agent (default: $SIDING_AGENT)") cmd.Flags().BoolVar(&f.force, "force", false, "start the stack even if it does not fit into the memory budget") + cmd.Flags().StringVar(&f.seed, "seed", "", "on the stack's first up, start its volumes as copies of this snapshot") w.register(cmd) registerJSON(cmd, &asJSON) return cmd @@ -60,50 +67,106 @@ With --wait, up ends like siding status --wait, with its verdict and exit code.` type upFlags struct { file, repo, agent string force bool + seed string compose []string } -// checkBudget refuses with NoCapacity when the memory of every other stack plus the estimate of -// this one exceeds the budget; with force it only warns. -func (a *app) checkBudget(ctx context.Context, project string, p *compose.Project, force bool, stderr io.Writer) error { +// fit compares the memory of every other stack plus the estimate of this one with the budget. +func (a *app) fit(ctx context.Context, project, repo string, p *compose.Project) (budget.Check, error) { proxyContainer, err := a.opts.Docker.Container(ctx, a.opts.Proxy.Container) if err != nil { - return err + return budget.Check{}, err } b, err := a.budget(ctx, proxyContainer) if err != nil { - return err + return budget.Check{}, err } cs, err := a.opts.Docker.Containers(ctx, map[string]string{stack.LabelRepo: ""}) if err != nil { - return err + return budget.Check{}, err } // This stack's current use does not count: its estimate replaces it. others := slices.DeleteFunc(cs, func(c docker.Container) bool { return c.Labels[stack.LabelProject] == project }) memory, err := a.memory(ctx, others) if err != nil { - return err + return budget.Check{}, err } - check := budget.Check{Budget: b, Estimate: budget.Estimate(p)} + check := budget.Check{Budget: b, Estimate: budget.EstimateLearned(p, repo, budget.LoadPeaks(a.opts.Home))} for _, m := range memory { check.Used += int64(m) } - if check.Fits() { - return nil + return check, nil +} + +func capacityMessage(project string, c budget.Check) string { + return fmt.Sprintf("%s needs about %s, and the other stacks use %s of the memory budget %s", + project, bytesText(uint64(c.Estimate)), bytesText(uint64(c.Used)), bytesText(uint64(c.Budget))) +} + +const capacityHint = "free memory with siding gc or siding down in another worktree, raise it with siding setup --budget, or start anyway with --force" + +// checkBudget lets a stack start when it fits into the budget. Otherwise force starts it with a +// warning, wait puts it in line until it fits or the time is up (spec start-queue), and else +// it refuses with NoCapacity. +func (a *app) checkBudget(ctx context.Context, project, repo string, p *compose.Project, force bool, w waitFlags, stderr io.Writer) error { + check, err := a.fit(ctx, project, repo, p) + if err != nil || check.Fits() { + return err } - msg := fmt.Sprintf("%s needs about %s, and the other stacks use %s of the memory budget %s", - project, bytesText(uint64(check.Estimate)), bytesText(uint64(check.Used)), bytesText(uint64(check.Budget))) - if force { - warnf(stderr, "%s; starting it anyway (--force)", msg) + switch { + case force: + warnf(stderr, "%s; starting it anyway (--force)", capacityMessage(project, check)) return nil + case w.wait: + return a.waitInLine(ctx, project, repo, p, check, w.timeout, stderr) + } + return fail.New(fail.NoCapacity, "%s", capacityMessage(project, check)).WithHint(capacityHint) +} + +// queueInterval is how often a waiting up looks at the line and the budget again. +const queueInterval = 2 * time.Second + +// waitInLine waits until this up is first in line and its stack fits, at most timeout. +func (a *app) waitInLine(ctx context.Context, project, repo string, p *compose.Project, check budget.Check, timeout time.Duration, stderr io.Writer) error { + line := queue.Open(a.opts.Home, a.opts.Alive) + start := a.opts.Clock.Now() + leave, err := line.Enter(queue.Entry{Project: project, PID: a.opts.PID, Estimate: check.Estimate, Since: start}) + if err != nil { + return err + } + defer leave() + shown := 0 + for { + entries, err := line.List() + if err != nil { + return err + } + place := queue.Place(entries, a.opts.PID) + if place != shown { + _, _ = fmt.Fprintf(stderr, "Waiting for memory: place %d in line; %s\n", place, capacityMessage(project, check)) + shown = place + } + if place == 1 { + if check, err = a.fit(ctx, project, repo, p); err != nil { + return err + } + if check.Fits() { + return nil + } + } + if !a.opts.Clock.Now().Before(start.Add(timeout)) { + return fail.New(fail.NoCapacity, "waited %s at place %d in line, and %s", timeout, place, capacityMessage(project, check)).WithHint(capacityHint) + } + if err := a.opts.Clock.Sleep(ctx, queueInterval); err != nil { + return err + } } - return fail.New(fail.NoCapacity, "%s", msg). - WithHint("free memory with siding gc or siding down in another worktree, raise it with siding setup --budget, or start anyway with --force") } func (a *app) up(cmd *cobra.Command, f upFlags, w waitFlags, asJSON bool) error { ctx := cmd.Context() stderr := cmd.ErrOrStderr() + start := a.opts.Clock.Now() wt, err := a.opts.Git.Worktree(ctx, a.opts.Dir) if err != nil { return err @@ -153,7 +216,11 @@ func (a *app) up(cmd *cobra.Command, f upFlags, w waitFlags, asJSON bool) error for _, w := range warnings { warnf(stderr, "%s", w) } - if err := a.checkBudget(ctx, project, p, f.force, stderr); err != nil { + plan, snap, err := a.seedPlan(ctx, project, id.Repo, p, f.seed, len(existingContainers), stderr) + if err != nil { + return err + } + if err := a.checkBudget(ctx, project, id.Repo, p, f.force, w, stderr); err != nil { return err } override, err := writeOverride(wt.Top, stack.Override(p, id, routes, a.opts.Proxy.Network)) @@ -161,16 +228,30 @@ func (a *app) up(cmd *cobra.Command, f upFlags, w waitFlags, asJSON bool) error return err } + if err := a.seedVolumes(ctx, id, project, p, plan, snap, stderr); err != nil { + return err + } + + slot, err := a.buildSlot(ctx, p, start.Add(w.timeout), stderr) + if err != nil { + return err + } inv := compose.Invocation{Dir: wt.Top, Project: project, Files: []string{file, override}} args := append([]string{"up", "-d", "--remove-orphans"}, f.compose...) // Compose's progress, and anything it prints, goes to stderr: stdout is for siding's result. - if err := a.opts.Compose.Run(ctx, inv, args, stderr, stderr); err != nil { + err = a.opts.Compose.Run(ctx, inv, args, stderr, stderr) + slot.Release() + if err != nil { + return err + } + seedFailure, err := a.runSeeds(ctx, inv, plan, w.timeout, stderr) + if err != nil { return err } st := existing{wt: wt, id: id, project: project} - if w.wait { - doc, err := a.status(ctx, st, p, port, w) + if w.wait || seedFailure != nil { + doc, err := a.status(ctx, st, p, port, w, seedFailure) if err != nil { return err } @@ -219,3 +300,138 @@ func printStackText(cmd *cobra.Command, doc stackDocument) error { _, err := fmt.Fprint(cmd.OutOrStdout(), b.String()) return err } + +// seedPlan validates the seed labels and plans the seeding of a first up (spec seeding); a later +// up seeds nothing. The snapshot is resolved here, before anything starts. +func (a *app) seedPlan(ctx context.Context, project, repo string, p *compose.Project, seedName string, containers int, stderr io.Writer) (seed.Plan, snapshot.Snapshot, error) { + plan, err := seed.Make(p, seedName != "") + if err != nil { + return seed.Plan{}, snapshot.Snapshot{}, err + } + vols, err := a.opts.Docker.Volumes(ctx, map[string]string{stack.LabelProject: project}) + if err != nil { + return seed.Plan{}, snapshot.Snapshot{}, err + } + if !seed.FirstUp(containers, len(vols)) { + if seedName != "" { + warnf(stderr, "%s already has data, so --seed %s seeds nothing; siding down --volumes removes its data", project, seedName) + } + return seed.Plan{}, snapshot.Snapshot{}, nil + } + if seedName == "" { + return plan, snapshot.Snapshot{}, nil + } + all, err := a.snapshots(ctx, false) + if err != nil { + return seed.Plan{}, snapshot.Snapshot{}, err + } + snap, err := snapshot.Find(all, repo, seedName) + return plan, snap, err +} + +// seedVolumes creates the planned volumes as copies of the snapshot, with the labels Compose +// sets itself, so Compose adopts them (design D3). Volumes the snapshot lacks start empty. +func (a *app) seedVolumes(ctx context.Context, id stack.Identity, project string, p *compose.Project, plan seed.Plan, snap snapshot.Snapshot, stderr io.Writer) error { + var keys []string + for _, key := range plan.Volumes { + if _, ok := snap.Volumes[key]; ok { + keys = append(keys, key) + } + } + if len(keys) > 0 { + _, _ = fmt.Fprintf(stderr, "Seeding %s from the snapshot %s: %s\n", project, snap.Name, strings.Join(keys, ", ")) + } + for _, key := range keys { + from := snap.Volumes[key] + name := p.Volumes[key].Name + labels := id.Labels() + labels["com.docker.compose.project"] = project + labels["com.docker.compose.volume"] = key + if err := a.opts.Docker.CreateVolume(ctx, name, labels); err != nil { + return err + } + exit, out, err := a.opts.Docker.RunHelper(ctx, snapshot.CopyHelper(from, name, id.Machine)) + if err == nil && exit != 0 { + err = fail.New(fail.Internal, "seeding %s from the snapshot %s failed with exit code %d: %s", key, snap.Name, exit, strings.Join(out, "; ")) + } + if err != nil { + return err + } + } + return nil +} + +// runSeeds runs the seed commands of a first up in their services, each as soon as the service +// is ready, at most timeout altogether. A failure is returned as the verdict's failure. +func (a *app) runSeeds(ctx context.Context, inv compose.Invocation, plan seed.Plan, timeout time.Duration, stderr io.Writer) (*verdict.Failure, error) { + deadline := a.opts.Clock.Now().Add(timeout) + for _, r := range plan.Scripts { + for { + cs, err := a.opts.Docker.Containers(ctx, map[string]string{stack.LabelProject: inv.Project, stack.LabelService: r.Service}) + if err != nil { + return nil, err + } + ready, broken := false, false + for _, c := range cs { + ready = ready || (c.State == "running" && (c.Health == "" || c.Health == "healthy")) + broken = broken || c.State == "exited" || c.State == "dead" || c.Health == "unhealthy" + } + if ready { + break + } + if broken || !a.opts.Clock.Now().Before(deadline) { + return &verdict.Failure{Service: r.Service, Reason: verdict.SeedFailed, + Hint: fmt.Sprintf("%s did not become ready, so its seed command did not run; see its last log lines", r.Service)}, nil + } + if err := a.opts.Clock.Sleep(ctx, pollInterval); err != nil { + return nil, err + } + } + _, _ = fmt.Fprintf(stderr, "Seeding %s: %s\n", r.Service, r.Command) + out := &compose.TailBuffer{Max: logTail} + if err := a.opts.Compose.Run(ctx, inv, []string{"exec", "-T", r.Service, "sh", "-c", r.Command}, out, out); err != nil { + if ctx.Err() != nil { + return nil, ctx.Err() + } + return &verdict.Failure{Service: r.Service, Reason: verdict.SeedFailed, Output: out.Lines(), + Hint: fmt.Sprintf("its seed command %q failed: %v; fix it and start again with siding down --volumes and siding up", r.Command, err)}, nil + } + } + return nil, nil +} + +// buildSlot takes one of the build slots for a project that builds images (spec build-limit), +// waiting for a free one until deadline. A project of images only needs none: the nil slot. +func (a *app) buildSlot(ctx context.Context, p *compose.Project, deadline time.Time, stderr io.Writer) (*buildslot.Slot, error) { + builds := false + for _, s := range p.Services { + builds = builds || s.Build + } + if !builds { + return nil, nil + } + proxyContainer, err := a.opts.Docker.Container(ctx, a.opts.Proxy.Container) + if err != nil { + return nil, err + } + n, err := a.builds(ctx, proxyContainer) + if err != nil { + return nil, err + } + for told := false; ; told = true { + slot, ok, err := buildslot.TryAcquire(a.opts.Home, n) + if err != nil || ok { + return slot, err + } + if !told { + _, _ = fmt.Fprintf(stderr, "Waiting for a build slot: %d stacks build at once (siding setup --builds)\n", n) + } + if !a.opts.Clock.Now().Before(deadline) { + return nil, fail.New(fail.NoCapacity, "waited for a build slot until --timeout; all %d are taken", n). + WithHint("raise --timeout, or allow more builds at once with siding setup --builds") + } + if err := a.opts.Clock.Sleep(ctx, time.Second); err != nil { + return nil, err + } + } +} diff --git a/internal/cli/up_test.go b/internal/cli/up_test.go index 3dd415f..71c01db 100644 --- a/internal/cli/up_test.go +++ b/internal/cli/up_test.go @@ -9,6 +9,7 @@ import ( "strings" "testing" + "github.com/tweinmann/siding/internal/budget" "github.com/tweinmann/siding/internal/fail" "github.com/tweinmann/siding/internal/testutil" ) @@ -171,10 +172,11 @@ func TestUpBudget(t *testing.T) { e := newEnv(t) e.proxyUp(80) e.docker.proxy.Labels["dev.siding.budget"] = fmt.Sprint(budgetMiB * mib) + // Another repository, so its use is not learned as this stack's peak. other := e.id() - other.Branch, other.Worktree = "feature/other", "/src/other" + other.Repo, other.Branch, other.Worktree = "blog", "feature/other", "/src/other" e.stackUp(other, "web") - e.docker.memory["shop-feature-other-web-1"] = 3584 * mib + e.docker.memory["blog-feature-other-web-1"] = 3584 * mib return e } @@ -222,3 +224,26 @@ func TestUpBudget(t *testing.T) { } }) } + +// A peak siding learned from one branch's stack makes the estimate of the next branch's. +func TestUpLearnedPeak(t *testing.T) { + t.Parallel() + const mib = 1 << 20 + e := newEnv(t) + e.proxyUp(80) + e.docker.proxy.Labels["dev.siding.budget"] = fmt.Sprint(2048 * mib) + main := e.id() + main.Branch, main.Worktree = "feature/other", "/src/other" + e.stackUp(main, "web") + e.docker.memory["shop-feature-other-web-1"] = 1200 * mib + if code, _, _ := e.run("ps"); code != exitOK { + t.Fatal("ps failed") + } + if got := budget.LoadPeaks(e.opts.Home)["shop/web"]; got != 1200*mib { + t.Fatalf("learned %d MiB, want 1200", got/mib) + } + // 1200 MiB used by the other stack, plus 1500 MiB for web and 3 × 256 MiB: over 2 GiB. + if code, stdout, _ := e.run("up", "--json"); code != exitNoCapacity || !strings.Contains(stdout, "needs about 2.2 GiB") { + t.Errorf("exit %d: %s", code, stdout) + } +} diff --git a/internal/compose/compose.go b/internal/compose/compose.go index 7961e1b..04fe45e 100644 --- a/internal/compose/compose.go +++ b/internal/compose/compose.go @@ -104,7 +104,7 @@ func (c *CLI) Run(ctx context.Context, inv Invocation, args []string, stdout, st if err := c.checkVersion(ctx); err != nil { return err } - tail := &tailBuffer{max: 20} + tail := &TailBuffer{Max: 20} if err := c.exec(ctx, inv, inv.args(args...), stdout, io.MultiWriter(stderr, tail)); err != nil { if ctx.Err() != nil { return ctx.Err() // interrupted, e.g. Ctrl-C during logs --follow @@ -168,31 +168,34 @@ func errorLines(output string) string { return strings.Join(lines, "\n") } -// tailBuffer keeps the last max lines written to it. -type tailBuffer struct { - max int +// TailBuffer keeps the last Max lines written to it. +type TailBuffer struct { + Max int lines []string partial string } -func (t *tailBuffer) Write(p []byte) (int, error) { +func (t *TailBuffer) Write(p []byte) (int, error) { s := t.partial + string(p) parts := strings.Split(s, "\n") t.partial = parts[len(parts)-1] t.lines = append(t.lines, parts[:len(parts)-1]...) - if len(t.lines) > t.max { - t.lines = t.lines[len(t.lines)-t.max:] + if len(t.lines) > t.Max { + t.lines = t.lines[len(t.lines)-t.Max:] } return len(p), nil } -func (t *tailBuffer) String() string { +func (t *TailBuffer) String() string { return strings.Join(t.Lines(), "\n") } + +// Lines returns the kept lines, the unfinished last one included. +func (t *TailBuffer) Lines() []string { lines := slices.Clone(t.lines) if t.partial != "" { lines = append(lines, t.partial) } - if len(lines) > t.max { - lines = lines[len(lines)-t.max:] + if len(lines) > t.Max { + lines = lines[len(lines)-t.Max:] } - return strings.Join(lines, "\n") + return lines } diff --git a/internal/compose/config.go b/internal/compose/config.go index cb5a579..8158aff 100644 --- a/internal/compose/config.go +++ b/internal/compose/config.go @@ -73,6 +73,8 @@ type Service struct { ContainerName string // Binds are the absolute host paths of the service's bind mounts. Binds []string + // Volumes are the keys of the named volumes the service mounts. + Volumes []string // Healthcheck is set when the compose file gives the service a healthcheck. One from the // image is not visible here. Healthcheck bool @@ -80,6 +82,8 @@ type Service struct { MemoryLimit int64 // Replicas is deploy.replicas, else scale, else 1. Replicas int + // Build is set when the service is built from a Dockerfile. + Build bool } // Resource is a top-level network or volume. @@ -102,7 +106,8 @@ type rawService struct { Published string `json:"published"` Protocol string `json:"protocol"` } `json:"ports"` - ContainerName string `json:"container_name"` + ContainerName string `json:"container_name"` + Build json.RawMessage `json:"build"` Volumes []struct { Type string `json:"type"` Source string `json:"source"` @@ -143,7 +148,7 @@ func ParseConfig(data []byte) (*Project, error) { p := &Project{Name: raw.Name, Services: map[string]Service{}, Networks: map[string]Resource{}, Volumes: map[string]Resource{}} for name, rs := range raw.Services { s := Service{Labels: rs.Labels, NetworkMode: rs.NetworkMode, Environment: map[string]string{}, - ContainerName: rs.ContainerName, Replicas: 1} + ContainerName: rs.ContainerName, Replicas: 1, Build: len(rs.Build) > 0 && string(rs.Build) != "null"} if s.Labels == nil { s.Labels = map[string]string{} } @@ -157,8 +162,13 @@ func ParseConfig(data []byte) (*Project, error) { } } for _, v := range rs.Volumes { - if v.Type == "bind" { + switch v.Type { + case "bind": s.Binds = append(s.Binds, v.Source) + case "volume": + if v.Source != "" { + s.Volumes = append(s.Volumes, v.Source) + } } } if h := rs.Healthcheck; h != nil && !h.Disable && len(h.Test) > 0 && h.Test[0] != "NONE" { diff --git a/internal/compose/config_test.go b/internal/compose/config_test.go index 073081c..1e3d069 100644 --- a/internal/compose/config_test.go +++ b/internal/compose/config_test.go @@ -110,7 +110,7 @@ func TestAtLeast(t *testing.T) { func TestTailBuffer(t *testing.T) { t.Parallel() - b := &tailBuffer{max: 2} + b := &TailBuffer{Max: 2} _, _ = b.Write([]byte("one\ntwo\nthr")) _, _ = b.Write([]byte("ee\nfour")) if got := b.String(); got != "three\nfour" { @@ -160,6 +160,9 @@ func TestParseConfigDetails(t *testing.T) { t.Errorf("%s: %+v\nwant %+v", want.name, s, want) } } + if got := p.Services["db"].Volumes; !reflect.DeepEqual(got, []string{"pgdata", "cache"}) { + t.Errorf("db mounts the named volumes %v", got) + } if got := p.Volumes["cache"]; got.Name != "pip-cache" || got.Labels["dev.siding.shared"] != "true" { t.Errorf("volume cache %+v", got) } @@ -189,3 +192,19 @@ Error response from daemon: Conflict. The container name "/demo-db" is already i t.Errorf("without an error line: %q", got) } } + +// testdata/build/config.json is captured like the others, from testdata/build/compose.yaml. +func TestParseConfigBuild(t *testing.T) { + t.Parallel() + data, err := os.ReadFile(filepath.Join("testdata", "build", "config.json")) + if err != nil { + t.Fatal(err) + } + p, err := ParseConfig(data) + if err != nil { + t.Fatal(err) + } + if !p.Services["app"].Build || p.Services["db"].Build { + t.Errorf("app build %v, db build %v; want true, false", p.Services["app"].Build, p.Services["db"].Build) + } +} diff --git a/internal/compose/testdata/build/app/Dockerfile b/internal/compose/testdata/build/app/Dockerfile new file mode 100644 index 0000000..6b96463 --- /dev/null +++ b/internal/compose/testdata/build/app/Dockerfile @@ -0,0 +1 @@ +FROM busybox:1.37.0 diff --git a/internal/compose/testdata/build/compose.yaml b/internal/compose/testdata/build/compose.yaml new file mode 100644 index 0000000..2a637ab --- /dev/null +++ b/internal/compose/testdata/build/compose.yaml @@ -0,0 +1,6 @@ +# One service built from a Dockerfile, one from an image only. +services: + app: + build: ./app + db: + image: busybox:1.37.0 diff --git a/internal/compose/testdata/build/config.json b/internal/compose/testdata/build/config.json new file mode 100644 index 0000000..f03adef --- /dev/null +++ b/internal/compose/testdata/build/config.json @@ -0,0 +1,30 @@ +{ + "name": "shop-main", + "networks": { + "default": { + "name": "shop-main_default", + "ipam": {} + } + }, + "services": { + "app": { + "command": null, + "entrypoint": null, + "networks": { + "default": null + }, + "build": { + "context": "/src/shop/app", + "dockerfile": "Dockerfile" + } + }, + "db": { + "command": null, + "entrypoint": null, + "image": "busybox:1.37.0", + "networks": { + "default": null + } + } + } +} \ No newline at end of file diff --git a/internal/docker/docker.go b/internal/docker/docker.go index a8ae065..02c276e 100644 --- a/internal/docker/docker.go +++ b/internal/docker/docker.go @@ -56,7 +56,19 @@ type Network struct { // Volume is a Docker volume. type Volume struct { - Name string + Name string + Labels map[string]string + Created string + // Size in bytes, set only by VolumeSizes; -1 when Docker does not know it. + Size int64 +} + +// Helper is a short-lived container that works on volumes, such as copying one into another. +type Helper struct { + Image string + // Binds are volume mounts, ":[:ro]". + Binds []string + Cmd []string Labels map[string]string } @@ -116,6 +128,117 @@ func labelFilters(labels map[string]string) client.Filters { return f } +// NCPU returns the CPUs the Docker daemon has, the VM's on Docker Desktop. +func (c *Client) NCPU(ctx context.Context) (int, error) { + api, err := c.connect() + if err != nil { + return 0, err + } + res, err := api.Info(ctx, client.InfoOptions{}) + if err != nil { + return 0, unavailable(err) + } + return res.Info.NCPU, nil +} + +// CreateVolume creates a new volume with labels. It fails when the name is taken: Docker would +// silently hand back the existing volume, and siding would write into someone else's data. +func (c *Client) CreateVolume(ctx context.Context, name string, labels map[string]string) error { + api, err := c.connect() + if err != nil { + return err + } + if _, err := api.VolumeInspect(ctx, name, client.VolumeInspectOptions{}); err == nil { + return fail.New(fail.Internal, "the volume %s already exists", name). + WithHint("it may belong to another machine or an older snapshot; remove it by name with docker volume rm if it is not needed") + } else if !cerrdefs.IsNotFound(err) { + return unavailable(err) + } + if _, err := api.VolumeCreate(ctx, client.VolumeCreateOptions{Name: name, Labels: labels}); err != nil { + return fmt.Errorf("create volume %s: %w", name, err) + } + return nil +} + +// RemoveVolume removes a volume by its exact name. +func (c *Client) RemoveVolume(ctx context.Context, name string) error { + api, err := c.connect() + if err != nil { + return err + } + if _, err := api.VolumeRemove(ctx, name, client.VolumeRemoveOptions{}); err != nil { + return fmt.Errorf("remove volume %s: %w", name, err) + } + return nil +} + +// VolumeSizes returns the size of every volume by name, as docker system df -v reports it. +func (c *Client) VolumeSizes(ctx context.Context) (map[string]int64, error) { + api, err := c.connect() + if err != nil { + return nil, err + } + res, err := api.DiskUsage(ctx, client.DiskUsageOptions{Volumes: true, Verbose: true}) + if err != nil { + return nil, unavailable(err) + } + sizes := map[string]int64{} + for _, v := range res.Volumes.Items { + sizes[v.Name] = -1 + if v.UsageData != nil { + sizes[v.Name] = v.UsageData.Size + } + } + return sizes, nil +} + +// RunHelper runs a helper container to its end, pulling its image first when it is missing, +// and removes it. It returns the exit code and the last lines of its output. +func (c *Client) RunHelper(ctx context.Context, h Helper) (exit int, output []string, err error) { + api, err := c.connect() + if err != nil { + return 0, nil, err + } + if _, err := api.ImageInspect(ctx, h.Image); cerrdefs.IsNotFound(err) { + pull, err := api.ImagePull(ctx, h.Image, client.ImagePullOptions{}) + if err != nil { + return 0, nil, fmt.Errorf("pull %s: %w", h.Image, err) + } + if err := pull.Wait(ctx); err != nil { + return 0, nil, fmt.Errorf("pull %s: %w", h.Image, err) + } + } else if err != nil { + return 0, nil, unavailable(err) + } + created, err := api.ContainerCreate(ctx, helperOptions(h)) + if err != nil { + return 0, nil, fmt.Errorf("create helper container: %w", err) + } + id := created.ID + defer func() { + _, _ = api.ContainerRemove(context.WithoutCancel(ctx), id, client.ContainerRemoveOptions{Force: true}) + }() + if _, err := api.ContainerStart(ctx, id, client.ContainerStartOptions{}); err != nil { + return 0, nil, fmt.Errorf("start helper container: %w", err) + } + wait := api.ContainerWait(ctx, id, client.ContainerWaitOptions{Condition: container.WaitConditionNotRunning}) + select { + case res := <-wait.Result: + exit = int(res.StatusCode) + case err := <-wait.Error: + return 0, nil, fmt.Errorf("wait for helper container: %w", err) + } + output, err = c.Logs(ctx, id, 20) + return exit, output, err +} + +func helperOptions(h Helper) client.ContainerCreateOptions { + return client.ContainerCreateOptions{ + Config: &container.Config{Image: h.Image, Cmd: h.Cmd, Labels: h.Labels}, + HostConfig: &container.HostConfig{Binds: h.Binds, NetworkMode: "none"}, + } +} + // MemTotal returns the memory the Docker daemon has, the VM's on Docker Desktop. func (c *Client) MemTotal(ctx context.Context) (int64, error) { api, err := c.connect() @@ -312,7 +435,7 @@ func (c *Client) Volumes(ctx context.Context, labels map[string]string) ([]Volum } out := make([]Volume, 0, len(list.Items)) for _, v := range list.Items { - out = append(out, Volume{Name: v.Name, Labels: v.Labels}) + out = append(out, Volume{Name: v.Name, Labels: v.Labels, Created: v.CreatedAt}) } return out, nil } diff --git a/internal/docker/docker_test.go b/internal/docker/docker_test.go index e9a35f2..1c87556 100644 --- a/internal/docker/docker_test.go +++ b/internal/docker/docker_test.go @@ -62,3 +62,17 @@ func TestMemoryUsage(t *testing.T) { } } } + +func TestHelperOptions(t *testing.T) { + t.Parallel() + h := Helper{Image: "busybox:1.37.0", Binds: []string{"shop-main_data:/from:ro", "siding-snap-shop-base-data:/to"}, + Cmd: []string{"cp", "-a", "/from/.", "/to/"}, Labels: map[string]string{"dev.siding.machine": "m"}} + o := helperOptions(h) + if o.Config.Image != h.Image || !reflect.DeepEqual(o.Config.Cmd, h.Cmd) || !reflect.DeepEqual(o.Config.Labels, h.Labels) { + t.Errorf("config %+v", o.Config) + } + // No network: a copy needs none, and nothing in it can reach out. + if !reflect.DeepEqual(o.HostConfig.Binds, h.Binds) || o.HostConfig.NetworkMode != "none" { + t.Errorf("host config %+v", o.HostConfig) + } +} diff --git a/internal/e2e/e2e_test.go b/internal/e2e/e2e_test.go index 03db8c0..8127bf5 100644 --- a/internal/e2e/e2e_test.go +++ b/internal/e2e/e2e_test.go @@ -16,6 +16,7 @@ import ( "os/exec" "path/filepath" "strings" + "sync/atomic" "testing" "time" @@ -78,11 +79,13 @@ const brokenCompose = `services: type machine struct { t *testing.T home string + // pids gives every siding run its own pid in the queue: they all share this process. + pids *atomic.Int32 } func newMachine(t *testing.T) *machine { t.Helper() - m := &machine{t: t, home: t.TempDir()} + m := &machine{t: t, home: t.TempDir(), pids: &atomic.Int32{}} t.Cleanup(func() { // By exact name only. run(t, "", "docker", "compose", "-p", testProxy.Project, "down", "-v", "--remove-orphans") @@ -98,12 +101,20 @@ func (m *machine) siding(dir string, args ...string) (int, string) { } func (m *machine) sidingCtx(ctx context.Context, dir string, args ...string) (int, string) { + m.t.Helper() + code, stdout, _ := m.sidingFull(ctx, dir, args...) + return code, stdout +} + +// sidingFull is siding with stderr too. +func (m *machine) sidingFull(ctx context.Context, dir string, args ...string) (int, string, string) { m.t.Helper() // A machine id of its own: gc acts on every stack of "this machine", and must only ever see // the tests' stacks, never one a developer started in the same daemon. opts := cli.Options{ Dir: dir, Home: m.home, Getenv: os.Getenv, OSMachineID: func() string { return "siding-test-e2e" }, IsLocalAddress: overview.IsLocalAddress, Stdin: strings.NewReader(""), IsTerminal: func() bool { return false }, + PID: os.Getpid() + int(m.pids.Add(1))*1000000, Alive: func(int) bool { return true }, Git: git.Client{}, Compose: &compose.CLI{}, Docker: &docker.Client{}, Probe: probe.HTTP{Header: stack.ServiceHeader}, Browser: noBrowser{}, Clock: cli.SystemClock{}, Proxy: testProxy, @@ -111,7 +122,7 @@ func (m *machine) sidingCtx(ctx context.Context, dir string, args ...string) (in var out, errOut bytes.Buffer code := cli.Execute(ctx, cli.New(opts), args, &out, &errOut) m.t.Logf("siding %s: exit %d\n%s", strings.Join(args, " "), code, errOut.String()) - return code, out.String() + return code, out.String(), errOut.String() } type noBrowser struct{} @@ -293,6 +304,13 @@ func TestStacks(t *testing.T) { if out := run(t, "", "docker", "ps", "-aq", "--filter", "label=com.docker.compose.project=siding-test-shop-feature-x"); strings.TrimSpace(out) != "" { t.Errorf("containers left: %q", out) } + // Only the data is left; down --volumes still finds the stack by its volumes. + if code, out := m.siding(shop, "down", "--volumes", "--force", "--json"); code != 0 || !strings.Contains(out, "siding-test-shop-feature-x_data") { + t.Errorf("down --volumes after down: exit %d\n%s", code, out) + } + if out := run(t, "", "docker", "volume", "ls", "-q", "--filter", "name=siding-test-shop-feature-x_data"); strings.TrimSpace(out) != "" { + t.Errorf("the volume survived: %q", out) + } }) t.Run("down --volumes keeps unmerged and dirty work", func(t *testing.T) { @@ -337,7 +355,8 @@ func TestStacks(t *testing.T) { if code, out := m.siding(t.TempDir(), "setup", "--budget", "64m", "--json"); code != 0 { t.Fatalf("setup --budget: exit %d\n%s", code, out) } - code, out := m.siding(budgeted, "up", "--repo", "siding-test-budget", "--wait", "--json") + // With --wait it waits in line; a short timeout ends it with exit 3 as well. + code, out := m.siding(budgeted, "up", "--repo", "siding-test-budget", "--wait", "--timeout", "5s", "--json") if code != 3 || decode(t, out).Code != "NoCapacity" { t.Errorf("over budget: exit %d\n%s", code, out) } diff --git a/internal/e2e/phase3_test.go b/internal/e2e/phase3_test.go new file mode 100644 index 0000000..c647b2a --- /dev/null +++ b/internal/e2e/phase3_test.go @@ -0,0 +1,225 @@ +//go:build docker + +package e2e + +import ( + "context" + "os" + "path/filepath" + "strings" + "sync" + "testing" + "time" +) + +// db keeps a file in its volume; worker seeds its own volume with a command. +const snapCompose = `services: + db: + image: busybox:1.37.0 + command: ["sh", "-c", "[ -f /data/hello ] || echo first > /data/hello; exec sleep 600"] + volumes: [data:/data] + healthcheck: {test: ["CMD", "test", "-f", "/data/hello"], interval: 1s, retries: 30} + worker: + image: busybox:1.37.0 + command: ["sleep", "600"] + volumes: [marks:/marks] + labels: + dev.siding.seed: script + dev.siding.seed.command: "echo seeded > /marks/marker" +volumes: + data: {} + marks: {} +` + +const failingSeedCompose = `services: + db: + image: busybox:1.37.0 + command: ["sleep", "600"] + labels: + dev.siding.seed: script + dev.siding.seed.command: "echo the seed broke; exit 2" +` + +// hog holds about 300 MB once it is healthy. Not exec sleep: the shell must stay, it holds x. +const hogCompose = `services: + hog: + image: busybox:1.37.0 + command: ["sh", "-c", "x=$$(yes | head -c 300000000); touch /tmp/ready; while true; do sleep 60; done"] + healthcheck: {test: ["CMD", "test", "-f", "/tmp/ready"], interval: 1s, retries: 60} +` + +// small needs 300 MiB by its limits. +const smallCompose = `services: + a: + image: busybox:1.37.0 + command: ["sleep", "600"] + mem_limit: 150m + b: + image: busybox:1.37.0 + command: ["sleep", "600"] + mem_limit: 150m +` + +const buildCompose = `services: + app: + build: ./app + command: ["sleep", "600"] +` + +func composeExec(t *testing.T, project, service string, cmd ...string) string { + t.Helper() + return strings.TrimSpace(run(t, "", "docker", append([]string{"compose", "-p", project, "exec", "-T", service}, cmd...)...)) +} + +func TestSnapshotsQueueAndBuilds(t *testing.T) { + m := newMachine(t) + if code, out := m.siding(t.TempDir(), "setup", "--json"); code != 0 { + t.Fatalf("setup: exit %d\n%s", code, out) + } + removeSnapshot := func(volumes ...string) { + t.Cleanup(func() { + for _, v := range volumes { + run(t, "", "docker", "volume", "rm", v) // by exact name + } + }) + } + removeSnapshot("siding-snap_siding-test-snap_base_data", "siding-snap_siding-test-snap_base_marks") + + t.Run("save, seed, and the snapshot outlives the stack", func(t *testing.T) { + a := repo(t, "snap", snapCompose, "", "feature/a") + if code, out := m.siding(a, "up", "--repo", "siding-test-snap", "--wait", "--json"); code != 0 { + t.Fatalf("up a: exit %d\n%s", code, out) + } + if got := composeExec(t, "siding-test-snap-feature-a", "worker", "cat", "/marks/marker"); got != "seeded" { + t.Errorf("the seed command did not run on the first up: %q", got) + } + composeExec(t, "siding-test-snap-feature-a", "db", "sh", "-c", "echo from-a > /data/hello") + if code, out := m.siding(a, "snapshot", "save", "base", "--json"); code != 0 || !strings.Contains(out, "siding-snap_siding-test-snap_base_data") { + t.Fatalf("save: exit %d\n%s", code, out) + } + if code, out := m.siding(a, "snapshot", "save", "base", "--json"); code != 1 || decode(t, out).Code != "SnapshotExists" { + t.Errorf("save again: exit %d\n%s", code, out) + } + + b := repo(t, "snap", snapCompose, "", "feature/b") + code, out, stderr := m.sidingFull(context.Background(), b, "up", "--repo", "siding-test-snap", "--seed", "base", "--wait", "--json") + if code != 0 || decode(t, out).Verdict != "Ready" { + t.Fatalf("up --seed: exit %d\n%s", code, out) + } + if strings.Contains(stderr, "not created by Docker Compose") { + t.Errorf("Compose did not adopt the seeded volume:\n%s", stderr) + } + if got := composeExec(t, "siding-test-snap-feature-b", "db", "cat", "/data/hello"); got != "from-a" { + t.Errorf("seeded data %q, want from-a", got) + } + + if code, out := m.siding(a, "down", "--volumes", "--force", "--json"); code != 0 { + t.Fatalf("down a: exit %d\n%s", code, out) + } + if code, out := m.siding(b, "snapshot", "ls", "--json"); code != 0 || !strings.Contains(out, `"name": "base"`) { + t.Errorf("the snapshot did not outlive its stack: exit %d\n%s", code, out) + } + if code, out := m.siding(b, "snapshot", "rm", "base", "--json"); code != 0 { + t.Errorf("rm: exit %d\n%s", code, out) + } + if out := run(t, "", "docker", "volume", "ls", "-q", "--filter", "label=dev.siding.snapshot=base"); strings.TrimSpace(out) != "" { + t.Errorf("snapshot volumes left: %q", out) + } + }) + + t.Run("a failing seed command", func(t *testing.T) { + dir := repo(t, "seedfail", failingSeedCompose, "", "feature/f") + code, out := m.siding(dir, "up", "--repo", "siding-test-seedfail", "--wait", "--json") + s := decode(t, out) + if code != 1 || s.Failure.Reason != "SeedFailed" || !strings.Contains(strings.Join(s.Failure.Logs, "\n"), "the seed broke") { + t.Errorf("exit %d\n%s", code, out) + } + }) + + t.Run("waiting in line", func(t *testing.T) { + if code, out := m.siding(t.TempDir(), "setup", "--budget", "500m", "--json"); code != 0 { + t.Fatalf("setup --budget: exit %d\n%s", code, out) + } + t.Cleanup(func() { m.siding(t.TempDir(), "setup", "--budget", "default") }) + hog := repo(t, "hog", hogCompose, "", "feature/h") + if code, out := m.siding(hog, "up", "--repo", "siding-test-hog", "--force", "--wait", "--json"); code != 0 { + t.Fatalf("up hog: exit %d\n%s", code, out) + } + small := repo(t, "small", smallCompose, "", "feature/s") + done := make(chan int, 1) + go func() { + code, _ := m.siding(small, "up", "--repo", "siding-test-small", "--wait", "--timeout", "90s", "--json") + done <- code + }() + // Wait until small is in line, then free the memory. + queued := false + for i := 0; i < 60 && !queued; i++ { + time.Sleep(500 * time.Millisecond) + entries, _ := os.ReadDir(filepath.Join(m.home, ".siding", "queue")) + queued = len(entries) > 0 + } + if !queued { + t.Fatal("small never waited in line") + } + if code, out := m.siding(t.TempDir(), "ps", "--json"); code != 0 || !strings.Contains(out, `"waiting"`) || !strings.Contains(out, "siding-test-small-feature-s") { + t.Errorf("ps does not show the line: exit %d\n%s", code, out) + } + if code, out := m.siding(hog, "down", "--json"); code != 0 { + t.Fatalf("down hog: exit %d\n%s", code, out) + } + select { + case code := <-done: + if code != 0 { + t.Errorf("small ended with %d, want 0", code) + } + case <-time.After(2 * time.Minute): + t.Fatal("small never started") + } + }) + + t.Run("one build at a time", func(t *testing.T) { + if code, out := m.siding(t.TempDir(), "setup", "--builds", "1", "--json"); code != 0 { + t.Fatalf("setup --builds: exit %d\n%s", code, out) + } + t.Cleanup(func() { m.siding(t.TempDir(), "setup", "--builds", "default") }) + var stderrs []string + var mu sync.Mutex + var wg sync.WaitGroup + for _, name := range []string{"builda", "buildb"} { + project := "siding-test-" + name + "-feature-x" + // Registered before repo's cleanup, so it runs after it: the image is free once the + // stack is down. + t.Cleanup(func() { run(t, "", "docker", "image", "rm", project+"-app") }) + dir := repo(t, name, buildCompose, "", "feature/x") + if err := os.MkdirAll(filepath.Join(dir, "app"), 0o755); err != nil { + t.Fatal(err) + } + // A build of a few seconds, different per repository so neither is cached. + dockerfile := "FROM busybox:1.37.0\nRUN echo " + name + " > /built && sleep 4\n" + if err := os.WriteFile(filepath.Join(dir, "app", "Dockerfile"), []byte(dockerfile), 0o644); err != nil { + t.Fatal(err) + } + wg.Add(1) + go func(dir, name string) { + defer wg.Done() + code, out, stderr := m.sidingFull(context.Background(), dir, "up", "--repo", "siding-test-"+name, "--json") + if code != 0 { + t.Errorf("up %s: exit %d\n%s", name, code, out) + } + mu.Lock() + stderrs = append(stderrs, stderr) + mu.Unlock() + }(dir, name) + } + wg.Wait() + waited := 0 + for _, s := range stderrs { + if strings.Contains(s, "Waiting for a build slot") { + waited++ + } + } + if waited != 1 { + t.Errorf("%d of the two ups waited for the build slot, want 1", waited) + } + }) +} diff --git a/internal/fail/fail.go b/internal/fail/fail.go index 60de4df..842a8ea 100644 --- a/internal/fail/fail.go +++ b/internal/fail/fail.go @@ -59,6 +59,10 @@ const ( NoCapacity = "NoCapacity" // NotInteractive: a command would ask a question, but nobody can answer it. NotInteractive = "NotInteractive" + // SnapshotNotFound: the repository has no snapshot of that name. + SnapshotNotFound = "SnapshotNotFound" + // SnapshotExists: the repository already has a snapshot of that name. + SnapshotExists = "SnapshotExists" // Internal: an unexpected error without a code of its own. Internal = "Internal" ) diff --git a/internal/proxy/proxy.go b/internal/proxy/proxy.go index 0edcb20..f17c55e 100644 --- a/internal/proxy/proxy.go +++ b/internal/proxy/proxy.go @@ -39,6 +39,8 @@ type Settings struct { Machine string // Budget is the memory budget in bytes, 0 for the default. Budget int64 + // Builds is the number of build slots, 0 for the default. + Builds int // RoutesDir is the directory on this machine with the route files of siding ui. RoutesDir string // HostAlias is what host.docker.internal resolves to in the proxy: the proxy network's @@ -55,6 +57,9 @@ func ComposeFile(c Config, s Settings) []byte { if s.Budget > 0 { labels += fmt.Sprintf(" dev.siding.budget: \"%d\"\n", s.Budget) } + if s.Builds > 0 { + labels += fmt.Sprintf(" dev.siding.builds: \"%d\"\n", s.Builds) + } var b strings.Builder fmt.Fprintf(&b, `# Written by siding setup. Do not edit: siding setup rewrites it. services: diff --git a/internal/queue/queue.go b/internal/queue/queue.go new file mode 100644 index 0000000..7e1a6d5 --- /dev/null +++ b/internal/queue/queue.go @@ -0,0 +1,98 @@ +// Package queue is the line of up --wait processes waiting for memory. It has no service: each +// waiting process keeps one file under ~/.siding/queue, and every process reads the directory to +// learn its place. The order is the order of arrival; a process that ended leaves the line, also +// when it was killed, because a file whose process is gone counts as gone. +package queue + +import ( + "encoding/json" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "sort" + "time" +) + +// Entry is one waiting up. +type Entry struct { + Project string `json:"project"` + PID int `json:"pid"` + Estimate int64 `json:"estimate"` + Since time.Time `json:"since"` + file string +} + +// Line is the queue directory of one machine. +type Line struct { + dir string + alive func(pid int) bool +} + +// Open returns the line under home; alive tells whether a process still runs. +func Open(home string, alive func(pid int) bool) Line { + return Line{dir: filepath.Join(home, ".siding", "queue"), alive: alive} +} + +// Enter puts a process at the end of the line and returns the function that takes it out. +func (l Line) Enter(e Entry) (leave func(), err error) { + if err := os.MkdirAll(l.dir, 0o755); err != nil { + return nil, fmt.Errorf("enter the queue: %w", err) + } + data, err := json.Marshal(e) + if err != nil { + return nil, err + } + // The name sorts by arrival; the pid keeps two arrivals in the same nanosecond apart. + name := fmt.Sprintf("%020d-%d.json", e.Since.UnixNano(), e.PID) + path := filepath.Join(l.dir, name) + if err := os.WriteFile(path+".tmp", data, 0o644); err != nil { + return nil, fmt.Errorf("enter the queue: %w", err) + } + if err := os.Rename(path+".tmp", path); err != nil { + return nil, fmt.Errorf("enter the queue: %w", err) + } + return func() { _ = os.Remove(path) }, nil +} + +// List returns the line in order of arrival. It removes the files of processes that are gone. +func (l Line) List() ([]Entry, error) { + files, err := os.ReadDir(l.dir) + if errors.Is(err, fs.ErrNotExist) { + return nil, nil + } + if err != nil { + return nil, fmt.Errorf("read the queue: %w", err) + } + var line []Entry + for _, f := range files { + if filepath.Ext(f.Name()) != ".json" { + continue + } + path := filepath.Join(l.dir, f.Name()) + data, err := os.ReadFile(path) + if err != nil { + continue // left meanwhile + } + var e Entry + if json.Unmarshal(data, &e) != nil || !l.alive(e.PID) { + _ = os.Remove(path) + continue + } + e.file = f.Name() + line = append(line, e) + } + sort.Slice(line, func(i, j int) bool { return line[i].file < line[j].file }) + return line, nil +} + +// Place is the 1-based place of the process pid in line, or 0 when it is not in it. +func Place(line []Entry, pid int) int { + for i, e := range line { + if e.PID == pid { + return i + 1 + } + } + return 0 +} diff --git a/internal/queue/queue_test.go b/internal/queue/queue_test.go new file mode 100644 index 0000000..da7e442 --- /dev/null +++ b/internal/queue/queue_test.go @@ -0,0 +1,62 @@ +package queue + +import ( + "os" + "path/filepath" + "testing" + "time" +) + +func TestLine(t *testing.T) { + t.Parallel() + home := t.TempDir() + dead := map[int]bool{} + l := Open(home, func(pid int) bool { return !dead[pid] }) + t0 := time.Date(2026, 10, 28, 12, 0, 0, 0, time.UTC) + + if line, err := l.List(); err != nil || len(line) != 0 { + t.Fatalf("empty: %v, %v", line, err) + } + leaveA, err := l.Enter(Entry{Project: "a", PID: 101, Estimate: 1, Since: t0}) + if err != nil { + t.Fatal(err) + } + if _, err := l.Enter(Entry{Project: "b", PID: 102, Estimate: 2, Since: t0.Add(time.Second)}); err != nil { + t.Fatal(err) + } + if _, err := l.Enter(Entry{Project: "c", PID: 103, Estimate: 3, Since: t0.Add(2 * time.Second)}); err != nil { + t.Fatal(err) + } + line, _ := l.List() + if len(line) != 3 || line[0].Project != "a" || Place(line, 103) != 3 || Place(line, 999) != 0 { + t.Fatalf("line %+v", line) + } + + // a leaves; b is killed: c moves to the front, and b's file is cleaned up. + leaveA() + dead[102] = true + line, _ = l.List() + if len(line) != 1 || Place(line, 103) != 1 { + t.Fatalf("after leaving and a kill: %+v", line) + } + files, _ := os.ReadDir(filepath.Join(home, ".siding", "queue")) + if len(files) != 1 { + t.Errorf("files left: %v", files) + } +} + +func TestBrokenEntry(t *testing.T) { + t.Parallel() + home := t.TempDir() + l := Open(home, func(int) bool { return true }) + dir := filepath.Join(home, ".siding", "queue") + if err := os.MkdirAll(dir, 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(dir, "00000000000000000001-1.json"), []byte("{broken"), 0o644); err != nil { + t.Fatal(err) + } + if line, err := l.List(); err != nil || len(line) != 0 { + t.Errorf("a broken entry: %v, %v", line, err) + } +} diff --git a/internal/seed/seed.go b/internal/seed/seed.go new file mode 100644 index 0000000..79f30c8 --- /dev/null +++ b/internal/seed/seed.go @@ -0,0 +1,85 @@ +// Package seed decides how a stack's first up fills it with data: which volumes come from a +// snapshot, and which services run a seed command. Everything here is a pure function. +package seed + +import ( + "slices" + "sort" + + "github.com/tweinmann/siding/internal/compose" + "github.com/tweinmann/siding/internal/fail" +) + +// Labels on a service. +const ( + Label = "dev.siding.seed" + LabelCommand = "dev.siding.seed.command" +) + +// Values of Label. +const ( + Volume = "volume" + None = "none" + Script = "script" +) + +// Run is a seed command to run once in a service. +type Run struct { + Service string + Command string +} + +// Plan is what a first up seeds. +type Plan struct { + // Volumes are the keys of the own named volumes that come from the snapshot. + Volumes []string + // Scripts run in compose order once their service is ready. + Scripts []Run +} + +// Make validates the seed labels of p and returns the plan of a first up. Volumes are only +// planned when there is a snapshot to seed from; scripts always run on a first up. +func Make(p *compose.Project, withSnapshot bool) (Plan, error) { + var plan Plan + notFromSnapshot := map[string]bool{} + for _, name := range p.ServiceNames() { + s := p.Services[name] + switch mode := s.Labels[Label]; mode { + case "", Volume: + case None: + for _, v := range s.Volumes { + notFromSnapshot[v] = true + } + case Script: + cmd := s.Labels[LabelCommand] + if cmd == "" { + return Plan{}, fail.New(fail.InvalidArguments, "service %s has %s: %s but no %s", name, Label, Script, LabelCommand). + WithHint("add the label %s with the command to run once, e.g. \"npm run db:seed\"", LabelCommand) + } + plan.Scripts = append(plan.Scripts, Run{Service: name, Command: cmd}) + for _, v := range s.Volumes { + notFromSnapshot[v] = true + } + default: + return Plan{}, fail.New(fail.InvalidArguments, "service %s: %s must be %s, %s or %s, got %q", name, Label, Volume, None, Script, mode) + } + } + if withSnapshot { + for key, v := range p.Volumes { + if !v.External && !notFromSnapshot[key] { + plan.Volumes = append(plan.Volumes, key) + } + } + sort.Strings(plan.Volumes) + } + return plan, nil +} + +// FirstUp reports whether the project has never run: no containers and no volumes yet. +func FirstUp(containers, volumes int) bool { return containers == 0 && volumes == 0 } + +// Uses reports whether the plan seeds anything. +func (p Plan) Uses() bool { return len(p.Volumes) > 0 || len(p.Scripts) > 0 } + +// Has reports whether the plan seeds the volume key. +func (p Plan) Has(key string) bool { return slices.Contains(p.Volumes, key) } diff --git a/internal/seed/seed_test.go b/internal/seed/seed_test.go new file mode 100644 index 0000000..efccc6d --- /dev/null +++ b/internal/seed/seed_test.go @@ -0,0 +1,59 @@ +package seed + +import ( + "errors" + "reflect" + "testing" + + "github.com/tweinmann/siding/internal/compose" + "github.com/tweinmann/siding/internal/fail" +) + +func project(services map[string]compose.Service) *compose.Project { + return &compose.Project{Services: services, Volumes: map[string]compose.Resource{ + "data": {Name: "shop-main_data"}, "cache": {Name: "shop-main_cache"}, "seeded": {Name: "shop-main_seeded"}, + "shared": {Name: "shared", External: true}, + }} +} + +func TestMake(t *testing.T) { + t.Parallel() + p := project(map[string]compose.Service{ + "db": {Labels: map[string]string{Label: Script, LabelCommand: "psql -f /seed.sql"}, Volumes: []string{"seeded"}}, + "cache": {Labels: map[string]string{Label: None}, Volumes: []string{"cache"}}, + "web": {Labels: map[string]string{}, Volumes: []string{"data", "shared"}}, + }) + plan, err := Make(p, true) + if err != nil { + t.Fatal(err) + } + want := Plan{Volumes: []string{"data"}, Scripts: []Run{{Service: "db", Command: "psql -f /seed.sql"}}} + if !reflect.DeepEqual(plan, want) { + t.Errorf("plan %+v, want %+v", plan, want) + } + // Without a snapshot only the scripts run. + if plan, _ := Make(p, false); len(plan.Volumes) != 0 || len(plan.Scripts) != 1 { + t.Errorf("without a snapshot: %+v", plan) + } +} + +func TestMakeInvalid(t *testing.T) { + t.Parallel() + for name, labels := range map[string]map[string]string{ + "script without command": {Label: Script}, + "unknown mode": {Label: "always"}, + } { + _, err := Make(project(map[string]compose.Service{"db": {Labels: labels}}), true) + var e *fail.Error + if !errors.As(err, &e) || e.Code != fail.InvalidArguments { + t.Errorf("%s: %v", name, err) + } + } +} + +func TestFirstUp(t *testing.T) { + t.Parallel() + if !FirstUp(0, 0) || FirstUp(1, 0) || FirstUp(0, 1) { + t.Error("FirstUp") + } +} diff --git a/internal/snapshot/snapshot.go b/internal/snapshot/snapshot.go new file mode 100644 index 0000000..036a9ec --- /dev/null +++ b/internal/snapshot/snapshot.go @@ -0,0 +1,139 @@ +// Package snapshot names, labels and groups snapshots: copies of a stack's named volumes, kept +// as Docker volumes. Everything here is a pure function; copying happens through a helper +// container (see internal/docker). +package snapshot + +import ( + "fmt" + "regexp" + "sort" + "time" + + "github.com/tweinmann/siding/internal/docker" + "github.com/tweinmann/siding/internal/fail" + "github.com/tweinmann/siding/internal/stack" +) + +// Image is the helper image that copies volumes; the devcontainer's SIDING_BUSYBOX_IMAGE is the +// same. +const Image = "busybox:1.37.0" + +// Labels of a snapshot volume. +const ( + LabelName = "dev.siding.snapshot" + LabelVolume = "dev.siding.snapshot-volume" + LabelCreated = "dev.siding.snapshot-created" +) + +var validName = regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`) + +// ValidName fails with InvalidArguments unless name is lowercase letters, digits and single +// dashes, at most 40 characters. +func ValidName(name string) error { + if len(name) > 40 || !validName.MatchString(name) { + return fail.New(fail.InvalidArguments, "snapshot name %q: use lowercase letters, digits and dashes, at most 40 characters", name) + } + return nil +} + +// VolumeName is the volume holding one volume of a snapshot. The parts are separated by "_", +// which neither slugs nor snapshot names contain, so two snapshots never share a volume. +func VolumeName(repo, name, key string) string { + return "siding-snap_" + stack.Slug(repo) + "_" + name + "_" + stack.Slug(key) +} + +// Labels are the labels of a snapshot volume. +func Labels(repo, name, key, machine string, created time.Time) map[string]string { + return map[string]string{ + LabelName: name, + LabelVolume: key, + LabelCreated: created.UTC().Format(time.RFC3339), + stack.LabelRepo: repo, + stack.LabelMachine: machine, + } +} + +// Snapshot is one snapshot with its volumes. +type Snapshot struct { + Name string + Repo string + Created string + // Volumes maps the stack's volume key to the snapshot volume. + Volumes map[string]string + // Size is the sum of the volumes' sizes, -1 when Docker does not know one of them. + Size int64 +} + +// Group turns snapshot volumes into snapshots, sorted by repository and name. sizes may be nil. +func Group(vols []docker.Volume, sizes map[string]int64) []Snapshot { + byKey := map[string]*Snapshot{} + for _, v := range vols { + name, repo := v.Labels[LabelName], v.Labels[stack.LabelRepo] + if name == "" { + continue + } + k := repo + "\x00" + name + s, ok := byKey[k] + if !ok { + s = &Snapshot{Name: name, Repo: repo, Created: v.Labels[LabelCreated], Volumes: map[string]string{}} + byKey[k] = s + } + s.Volumes[v.Labels[LabelVolume]] = v.Name + switch size, known := sizes[v.Name]; { + case sizes == nil: + case !known || size < 0 || s.Size < 0: + s.Size = -1 + default: + s.Size += size + } + } + out := make([]Snapshot, 0, len(byKey)) + for _, s := range byKey { + out = append(out, *s) + } + sort.Slice(out, func(i, j int) bool { + if out[i].Repo != out[j].Repo { + return out[i].Repo < out[j].Repo + } + return out[i].Name < out[j].Name + }) + return out +} + +// Find returns the snapshot name of repo, failing with SnapshotNotFound. +func Find(all []Snapshot, repo, name string) (Snapshot, error) { + var names []string + for _, s := range all { + if s.Repo != repo { + continue + } + if s.Name == name { + return s, nil + } + names = append(names, s.Name) + } + e := fail.New(fail.SnapshotNotFound, "the repository %s has no snapshot %q", repo, name) + if len(names) == 0 { + return Snapshot{}, e.WithHint("save one with siding snapshot save in a stack of %s", repo) + } + return Snapshot{}, e.WithHint("its snapshots are: %v", names) +} + +// CopyHelper copies the volume from into the volume to. +func CopyHelper(from, to, machine string) docker.Helper { + return docker.Helper{ + Image: Image, + Binds: []string{from + ":/from:ro", to + ":/to"}, + Cmd: []string{"sh", "-c", "cp -a /from/. /to/"}, + Labels: map[string]string{stack.LabelMachine: machine, "dev.siding.helper": "copy"}, + } +} + +// ExistsError is the error of saving a snapshot whose name is taken. +func ExistsError(repo, name string) error { + return fail.New(fail.SnapshotExists, "the repository %s already has a snapshot %q", repo, name). + WithHint("choose another name, or replace it with --force") +} + +// String is used in messages. +func (s Snapshot) String() string { return fmt.Sprintf("%s/%s", s.Repo, s.Name) } diff --git a/internal/snapshot/snapshot_test.go b/internal/snapshot/snapshot_test.go new file mode 100644 index 0000000..92bb049 --- /dev/null +++ b/internal/snapshot/snapshot_test.go @@ -0,0 +1,73 @@ +package snapshot + +import ( + "errors" + "reflect" + "testing" + "time" + + "github.com/tweinmann/siding/internal/docker" + "github.com/tweinmann/siding/internal/fail" +) + +func code(err error) string { + var e *fail.Error + if errors.As(err, &e) { + return e.Code + } + return "" +} + +func TestValidName(t *testing.T) { + t.Parallel() + for name, ok := range map[string]bool{"base": true, "big-2": true, "Base": false, "a--b": false, "-a": false, "a_b": false, "": false, + "0123456789012345678901234567890123456789": true, "01234567890123456789012345678901234567890": false} { + if err := ValidName(name); (err == nil) != ok || (!ok && code(err) != fail.InvalidArguments) { + t.Errorf("ValidName(%q) = %v, want ok %v", name, err, ok) + } + } +} + +func TestVolumeName(t *testing.T) { + t.Parallel() + if got := VolumeName("shop", "base", "pg_data"); got != "siding-snap_shop_base_pg-data" { + t.Errorf("got %q", got) + } + // Dashes in repositories and names cannot make two snapshots share a volume. + if VolumeName("a-b", "c", "d") == VolumeName("a", "b-c", "d") { + t.Error("collision") + } +} + +func TestGroupAndFind(t *testing.T) { + t.Parallel() + created := time.Date(2026, 10, 28, 12, 0, 0, 0, time.UTC) + vol := func(repo, name, key string) docker.Volume { + return docker.Volume{Name: VolumeName(repo, name, key), Labels: Labels(repo, name, key, "m", created)} + } + vols := []docker.Volume{vol("shop", "base", "data"), vol("shop", "base", "uploads"), vol("blog", "base", "data"), vol("shop", "big", "data"), + {Name: "shop-main_data", Labels: map[string]string{"dev.siding.repo": "shop"}}} // a stack volume, not a snapshot + sizes := map[string]int64{VolumeName("shop", "base", "data"): 100, VolumeName("shop", "base", "uploads"): 20, VolumeName("blog", "base", "data"): -1} + all := Group(vols, sizes) + var names []string + for _, s := range all { + names = append(names, s.String()) + } + if !reflect.DeepEqual(names, []string{"blog/base", "shop/base", "shop/big"}) { + t.Fatalf("snapshots %v", names) + } + if all[1].Size != 120 || all[0].Size != -1 || all[2].Size != -1 || all[1].Created != "2026-10-28T12:00:00Z" || + all[1].Volumes["uploads"] != "siding-snap_shop_base_uploads" { + t.Errorf("shop/base %+v, blog/base %+v, shop/big %+v", all[1], all[0], all[2]) + } + + if s, err := Find(all, "shop", "big"); err != nil || s.Name != "big" { + t.Errorf("Find big: %+v, %v", s, err) + } + if _, err := Find(all, "shop", "nope"); code(err) != fail.SnapshotNotFound { + t.Errorf("Find nope: %v", err) + } + if code(ExistsError("shop", "base")) != fail.SnapshotExists { + t.Error("ExistsError has the wrong code") + } +} diff --git a/internal/stack/identity.go b/internal/stack/identity.go index e472aae..9c292df 100644 --- a/internal/stack/identity.go +++ b/internal/stack/identity.go @@ -18,6 +18,7 @@ const ( LabelAgent = "dev.siding.agent" LabelGitDir = "dev.siding.gitdir" LabelBudget = "dev.siding.budget" + LabelBuilds = "dev.siding.builds" LabelShared = "dev.siding.shared" // LabelHostAlias, on siding-proxy, is what host.docker.internal resolves to in it. LabelHostAlias = "dev.siding.host-alias" diff --git a/internal/verdict/verdict.go b/internal/verdict/verdict.go index 346fc6a..6526030 100644 --- a/internal/verdict/verdict.go +++ b/internal/verdict/verdict.go @@ -27,6 +27,7 @@ const ( Missing = "Missing" NotAnswering = "NotAnswering" NotReady = "NotReady" + SeedFailed = "SeedFailed" ) // restartLimit is how many restarts while waiting count as a crash loop. @@ -52,6 +53,8 @@ type Input struct { // Final is set when the time is up: what is not ready now is TimedOut. Final bool Timeout time.Duration + // Seed is set when a seed command of this up failed; it decides the verdict. + Seed *Failure } // Service is the state of one service. @@ -69,6 +72,8 @@ type Failure struct { Service string Reason string Hint string + // Output replaces the service's log tail, e.g. with a failed seed command's output. + Output []string } // Result is a verdict with the state of every service. @@ -113,6 +118,8 @@ func Evaluate(in Input) Result { } } switch { + case in.Seed != nil: + res.Verdict, res.Failure = Failed, in.Seed case firstFailed != nil: res.Verdict, res.Failure = Failed, firstFailed case allReady: diff --git a/internal/verdict/verdict_test.go b/internal/verdict/verdict_test.go index 8de31e3..0fcad7f 100644 --- a/internal/verdict/verdict_test.go +++ b/internal/verdict/verdict_test.go @@ -129,6 +129,15 @@ func TestEvaluate(t *testing.T) { } } +func TestSeedFailed(t *testing.T) { + t.Parallel() + seed := &Failure{Service: "db", Reason: SeedFailed, Hint: "the seed command failed", Output: []string{"ERROR: relation exists"}} + res := Evaluate(Input{Services: []string{"db"}, Containers: []docker.Container{ct("db", "running", "healthy", 0)}, Seed: seed}) + if res.Verdict != Failed || res.Failure != seed || len(res.Services) != 1 || !res.Services[0].Ready { + t.Errorf("%+v", res) + } +} + func TestHints(t *testing.T) { t.Parallel() res := Evaluate(Input{Services: []string{"db"}, Containers: []docker.Container{ diff --git a/justfile b/justfile index 77bb5b7..312ec82 100644 --- a/justfile +++ b/justfile @@ -28,6 +28,8 @@ test: # (every package with golden files; a package without the -update flag would fail on it) golden: go test ./internal/cli ./internal/stack -update + # The page is rendered from stacklist.json and gc-dryrun.json, so write it once they are new. + go test ./internal/cli -run TestRenderPage -update # Build a static siding binary for this container (linux) into bin/ build: diff --git a/openspec/changes/phase-3-snapshots-and-queue/.openspec.yaml b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/.openspec.yaml similarity index 100% rename from openspec/changes/phase-3-snapshots-and-queue/.openspec.yaml rename to openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/.openspec.yaml diff --git a/openspec/changes/phase-3-snapshots-and-queue/design.md b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/design.md similarity index 93% rename from openspec/changes/phase-3-snapshots-and-queue/design.md rename to openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/design.md index fd7737c..ed3cb00 100644 --- a/openspec/changes/phase-3-snapshots-and-queue/design.md +++ b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/design.md @@ -30,7 +30,12 @@ is the database, no background service, never lose work, the compose file is nev ### D1. Snapshots are Docker volumes (maintainer's decision) A snapshot of repository `` named `` is one volume per own named volume of the -stack, `siding-snap---`, labelled `dev.siding.snapshot=`, +stack, `siding-snap___` (with `_`, which neither slugs nor +snapshot names contain, so repository `a-b` with snapshot `c` and repository `a` with snapshot +`b-c` never share a volume; and siding creates a volume only after checking that the name is +free, because Docker's volume create silently returns an existing volume of that name, and a +snapshot would then write into another machine's or another snapshot's data, as the end-to-end +test showed with two machines on one daemon), labelled `dev.siding.snapshot=`, `dev.siding.snapshot-volume=`, `dev.siding.repo`, `dev.siding.machine`, and the time in `dev.siding.snapshot-created`. Copies run in a short-lived helper container from the image pinned in the binary (`busybox:1.37.0`, the devcontainer's `SIDING_BUSYBOX_IMAGE`) with diff --git a/openspec/changes/phase-3-snapshots-and-queue/proposal.md b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/proposal.md similarity index 96% rename from openspec/changes/phase-3-snapshots-and-queue/proposal.md rename to openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/proposal.md index ee613e1..4130070 100644 --- a/openspec/changes/phase-3-snapshots-and-queue/proposal.md +++ b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/proposal.md @@ -44,6 +44,8 @@ short, a few builds at a time, and with estimates learned from what stacks reall - `proxy`: `setup --builds` and the builds in the `Setup` document; `teardown --snapshots`. - `stack-list`: the queue in `ps` and in the `StackList` document. - `stack-gc`: gc never removes snapshots. +- `stack-lifecycle`: `down` finds a stack by its volumes when only its data is left (a bug of + v0.1 found while testing this phase). ## Impact diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/build-limit/spec.md b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/build-limit/spec.md similarity index 100% rename from openspec/changes/phase-3-snapshots-and-queue/specs/build-limit/spec.md rename to openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/build-limit/spec.md diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/cli-contract/spec.md b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/cli-contract/spec.md similarity index 100% rename from openspec/changes/phase-3-snapshots-and-queue/specs/cli-contract/spec.md rename to openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/cli-contract/spec.md diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/memory-budget/spec.md b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/memory-budget/spec.md similarity index 100% rename from openspec/changes/phase-3-snapshots-and-queue/specs/memory-budget/spec.md rename to openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/memory-budget/spec.md diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/proxy/spec.md b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/proxy/spec.md similarity index 100% rename from openspec/changes/phase-3-snapshots-and-queue/specs/proxy/spec.md rename to openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/proxy/spec.md diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/seeding/spec.md b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/seeding/spec.md similarity index 100% rename from openspec/changes/phase-3-snapshots-and-queue/specs/seeding/spec.md rename to openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/seeding/spec.md diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/snapshots/spec.md b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/snapshots/spec.md similarity index 100% rename from openspec/changes/phase-3-snapshots-and-queue/specs/snapshots/spec.md rename to openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/snapshots/spec.md diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/stack-gc/spec.md b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/stack-gc/spec.md similarity index 100% rename from openspec/changes/phase-3-snapshots-and-queue/specs/stack-gc/spec.md rename to openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/stack-gc/spec.md diff --git a/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/stack-lifecycle/spec.md b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/stack-lifecycle/spec.md new file mode 100644 index 0000000..64e55a3 --- /dev/null +++ b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/stack-lifecycle/spec.md @@ -0,0 +1,26 @@ +# Spec Delta + +## MODIFIED Requirements + +### Requirement: Down +`siding down` SHALL remove the stack's containers and networks by project name, also when the +compose file is gone, and keep its volumes. A stack whose containers are already gone but whose +volumes remain SHALL still be found by the labels of its volumes, so its data can be removed. It +SHALL print what it removed, with `--json` as a `Down` document, and with `--dry-run` remove +nothing. + +#### Scenario: Data survives +- **WHEN** `siding down` and then `siding up` run +- **THEN** the stack's named volumes still hold their data + +#### Scenario: Dry run +- **WHEN** `siding down --dry-run --json` runs +- **THEN** it prints a `Down` document listing the containers and networks with `dryRun: true`, and everything still runs + +#### Scenario: Nothing running +- **WHEN** `siding down` runs in a worktree whose stack has neither containers nor volumes +- **THEN** it fails with `StackNotFound` + +#### Scenario: Only the data is left +- **WHEN** `siding down` ran before, and now `siding down --volumes` runs in the same worktree +- **THEN** it finds the stack by its volumes and removes them, with the guard for unmerged and dirty work diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/stack-list/spec.md b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/stack-list/spec.md similarity index 100% rename from openspec/changes/phase-3-snapshots-and-queue/specs/stack-list/spec.md rename to openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/stack-list/spec.md diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/stack-status/spec.md b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/stack-status/spec.md similarity index 100% rename from openspec/changes/phase-3-snapshots-and-queue/specs/stack-status/spec.md rename to openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/stack-status/spec.md diff --git a/openspec/changes/phase-3-snapshots-and-queue/specs/start-queue/spec.md b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/start-queue/spec.md similarity index 100% rename from openspec/changes/phase-3-snapshots-and-queue/specs/start-queue/spec.md rename to openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/specs/start-queue/spec.md diff --git a/openspec/changes/phase-3-snapshots-and-queue/tasks.md b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/tasks.md similarity index 58% rename from openspec/changes/phase-3-snapshots-and-queue/tasks.md rename to openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/tasks.md index 70a3e43..5b7653d 100644 --- a/openspec/changes/phase-3-snapshots-and-queue/tasks.md +++ b/openspec/changes/archive/2026-10-29-phase-3-snapshots-and-queue/tasks.md @@ -2,50 +2,53 @@ ## 1. Foundations -- [ ] 1.1 Add the error codes `SnapshotNotFound` and `SnapshotExists`; verify with the error-code table test -- [ ] 1.2 Read `build:` in `internal/compose` (a `Build` flag per service); verify with a captured config with and without `build:` -- [ ] 1.3 Add to `internal/docker`: create a volume with labels, volumes by label with sizes from `/system/df`, remove a volume, run a helper container (pull if missing, create, start, wait, remove) and `NCPU` from `docker info`; verify with unit tests of the mappings and the helper's container config -- [ ] 1.4 Add the new labels (D9) to the conventions in CLAUDE.md and `openspec/config.yaml`; verify `openspec validate --all --strict` passes +- [x] 1.1 Add the error codes `SnapshotNotFound` and `SnapshotExists`; verify with the error-code table test +- [x] 1.2 Read `build:` in `internal/compose` (a `Build` flag per service); verify with a captured config with and without `build:` +- [x] 1.3 Add to `internal/docker`: create a volume with labels, volumes by label with sizes from `/system/df`, remove a volume, run a helper container (pull if missing, create, start, wait, remove) and `NCPU` from `docker info`; verify with unit tests of the mappings and the helper's container config +- [x] 1.4 Add the new labels (D9) to the conventions in CLAUDE.md and `openspec/config.yaml`; verify `openspec validate --all --strict` passes ## 2. Learned peaks -- [ ] 2.1 Implement `~/.siding/peaks.json` in `internal/budget` (read, record max, atomic write, a missing or broken file is empty) and the estimate of D7; verify with table tests for the spec scenarios of `memory-budget`, a broken file and a cap at the limit -- [ ] 2.2 Record peaks from `ps`, `checkBudget` and a Ready `status`, and use them in `up`'s estimate; verify with fake-based tests that a peak seen by `ps` changes the next `up`'s estimate -- [ ] 2.3 Document learned peaks in the README's budget section; verify the shown path and behaviour match the code +- [x] 2.1 Implement `~/.siding/peaks.json` in `internal/budget` (read, record max, atomic write, a missing or broken file is empty) and the estimate of D7; verify with table tests for the spec scenarios of `memory-budget`, a broken file and a cap at the limit +- [x] 2.2 Record peaks from `ps`, `checkBudget` and a Ready `status`, and use them in `up`'s estimate; verify with fake-based tests that a peak seen by `ps` changes the next `up`'s estimate +- [x] 2.3 Document learned peaks in the README's budget section; verify the shown path and behaviour match the code ## 3. Snapshots -- [ ] 3.1 Implement snapshot naming, labels and the copy plan in a pure package (D1); verify with table tests for names, slugs, repositories and `SnapshotExists` -- [ ] 3.2 Implement `siding snapshot save [--force] [--json]`: stop the services that mount the volumes, copy with the helper, start them again also on failure; verify with fake-based tests (order of compose stop, copies, compose start; failure in the middle; no volumes) and a `snapshot.json` golden -- [ ] 3.3 Implement `siding snapshot ls [--json]` and `siding snapshot rm [--dry-run] [--json]`; verify with fake-based tests and a `snapshotlist.json` golden -- [ ] 3.4 Add `teardown --snapshots` and the snapshots `teardown` names without it; verify with fake-based tests and the updated `teardown*.json` goldens -- [ ] 3.5 Document snapshots in the README; verify the shown commands run as written in the devcontainer +- [x] 3.1 Implement snapshot naming, labels and the copy plan in a pure package (D1); verify with table tests for names, slugs, repositories and `SnapshotExists` +- [x] 3.2 Implement `siding snapshot save [--force] [--json]`: stop the services that mount the volumes, copy with the helper, start them again also on failure; verify with fake-based tests (order of compose stop, copies, compose start; failure in the middle; no volumes) and a `snapshot.json` golden +- [x] 3.3 Implement `siding snapshot ls [--json]` and `siding snapshot rm [--dry-run] [--json]`; verify with fake-based tests and a `snapshotlist.json` golden +- [x] 3.4 Add `teardown --snapshots` and the snapshots `teardown` names without it; verify with fake-based tests and the updated `teardown*.json` goldens +- [x] 3.5 Document snapshots in the README; verify the shown commands run as written in the devcontainer ## 4. Seeding -- [ ] 4.1 Detect a first `up` (D2) and validate `dev.siding.seed` and `dev.siding.seed.command`; verify with fake-based tests for first and later `up`s and the `InvalidArguments` cases -- [ ] 4.2 Implement `up --seed ` (D3): resolve the snapshot, create the volumes with Compose's labels, copy, then run Compose; a later `up` warns and seeds nothing; verify with fake-based tests per scenario of the spec `seeding` -- [ ] 4.3 Implement the seed command (D4) and the reason `SeedFailed` in `internal/verdict`; verify with verdict table tests and fake-based tests of `up` and `up --wait` with a failing command -- [ ] 4.4 Document seeding in the README (`--seed`, `dev.siding.seed`, `dev.siding.seed.command`); verify the example labels are accepted by `siding lint` +- [x] 4.1 Detect a first `up` (D2) and validate `dev.siding.seed` and `dev.siding.seed.command`; verify with fake-based tests for first and later `up`s and the `InvalidArguments` cases +- [x] 4.2 Implement `up --seed ` (D3): resolve the snapshot, create the volumes with Compose's labels, copy, then run Compose; a later `up` warns and seeds nothing; verify with fake-based tests per scenario of the spec `seeding` +- [x] 4.3 Implement the seed command (D4) and the reason `SeedFailed` in `internal/verdict`; verify with verdict table tests and fake-based tests of `up` and `up --wait` with a failing command +- [x] 4.4 Document seeding in the README (`--seed`, `dev.siding.seed`, `dev.siding.seed.command`); verify the example labels are accepted by `siding lint` ## 5. Queue -- [ ] 5.1 Implement the line in `~/.siding/queue` (D5): enter, leave on every exit path, drop dead entries, the oldest entry first; verify with unit tests using fake pids and a temporary home -- [ ] 5.2 Make `up --wait` wait in line when the stack does not fit, recheck every two seconds, print its place on stderr, and exit 3 at `--timeout`; `up` without `--wait` keeps refusing; verify with fake-based tests using the fake clock (memory frees, time is up, order, a killed waiter) -- [ ] 5.3 Show the line in `ps` (text and `waiting` in `StackList`) and in `siding ui`; verify with the updated `stacklist.json` golden and the page golden -- [ ] 5.4 Document the queue in the README; verify the shown behaviour matches the tests +- [x] 5.1 Implement the line in `~/.siding/queue` (D5): enter, leave on every exit path, drop dead entries, the oldest entry first; verify with unit tests using fake pids and a temporary home +- [x] 5.2 Make `up --wait` wait in line when the stack does not fit, recheck every two seconds, print its place on stderr, and exit 3 at `--timeout`; `up` without `--wait` keeps refusing; verify with fake-based tests using the fake clock (memory frees, time is up, order, a killed waiter) +- [x] 5.3 Show the line in `ps` (text and `waiting` in `StackList`) and in `siding ui`; verify with the updated `stacklist.json` golden and the page golden +- [x] 5.4 Document the queue in the README; verify the shown behaviour matches the tests ## 6. Build limit -- [ ] 6.1 Implement build slots with `flock` under `~/.siding/builds` (D6); verify with unit tests that N holders exclude the N+1st and that closing a holder frees its slot -- [ ] 6.2 Hold a slot around `docker compose up` for projects with `build:`, count waiting against `--timeout`, and add `setup --builds` with the label carried forward and `builds` in `Setup`; verify with fake-based tests and the updated `setup.json` golden -- [ ] 6.3 Document the build limit in the README; verify the commands run as written +- [x] 6.1 Implement build slots with `flock` under `~/.siding/builds` (D6); verify with unit tests that N holders exclude the N+1st and that closing a holder frees its slot +- [x] 6.2 Hold a slot around `docker compose up` for projects with `build:`, count waiting against `--timeout`, and add `setup --builds` with the label carried forward and `builds` in `Setup`; verify with fake-based tests and the updated `setup.json` golden +- [x] 6.3 Document the build limit in the README; verify the commands run as written ## 7. End-to-end and integration -- [ ] 7.1 Extend `internal/e2e`: save a snapshot of a stack with data, seed a new branch from it and read the data back, a seed command that writes a file and one that fails with `SeedFailed`, `gc` and `down --volumes` leaving the snapshot, `snapshot rm`; a second `up --wait` that waits in line and starts after `down` of the first; two builds with `--builds 1` running one after the other; verify with `just smoke-stacks` and that no `siding-test-*` object is left, snapshots included -- [ ] 7.2 Run the flow by hand in the devcontainer and on the Mac (`just build-darwin`): `snapshot save`, `up --seed` in a second worktree, a queue with a small budget, `ps` and `siding ui` showing the line; record the result in the phase summary -- [ ] 7.3 Update the status in CLAUDE.md, the README and `openspec/config.yaml` to v0.3; verify `just test` passes +- [x] 7.1 Extend `internal/e2e`: save a snapshot of a stack with data, seed a new branch from it and read the data back, a seed command that writes a file and one that fails with `SeedFailed`, `gc` and `down --volumes` leaving the snapshot, `snapshot rm`; a second `up --wait` that waits in line and starts after `down` of the first; two builds with `--builds 1` running one after the other; verify with `just smoke-stacks` and that no `siding-test-*` object is left, snapshots included +- [x] 7.2 Run the flow by hand in the devcontainer and on the Mac (`just build-darwin`): `snapshot save`, `up --seed` in a second worktree, a queue with a small budget, `ps` and `siding ui` showing the line; record the result in the phase summary + - Result (2026-10-29): devcontainer and macOS with Docker Desktop (arm64) both passed. `save` stopped and restarted the service; the second worktree's `up --seed` served the snapshot's data, and Compose adopted the volume without a warning; with `--budget 500m` a second `up --wait` waited at place 1, shown by `ps` and `siding ui`, and started after `down` of the first. Found: `down` after only `down` (7.4) and four small issues (7.5). +- [x] 7.4 Let `down` find a stack by its volumes when its containers are gone, so `down --volumes` after `down` removes the data (found in 7.2); verify with a fake-based test and the end-to-end down case +- [x] 7.5 Fix the small issues found in 7.2: the README's claim that curl resolves `*.localhost` (macOS curl does not), `up --seed` saying what it seeds, `<1 MiB` for a tiny but non-empty size, and `down` mentioning kept volumes only when there are any; verify with unit tests +- [x] 7.3 Update the status in CLAUDE.md, the README and `openspec/config.yaml` to v0.3; verify `just test` passes ## Workflow follow-up diff --git a/openspec/config.yaml b/openspec/config.yaml index b823bca..9d53b81 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -23,7 +23,9 @@ context: | Status: pre-alpha. Phase 0 (repository, devcontainer, OpenSpec, CI) and Phase 1 (v0.1: stacks per worktree, routing through siding-proxy, the verdict of status) are done; Phase 2 - (v0.2: the overview siding ui, the memory budget, gc, lint, teardown) is done. OpenSpec is the only planning source: `openspec/specs/` is what siding + (v0.2: the overview siding ui, the memory budget, gc, lint, teardown) is done; Phase 3 + (v0.3: snapshots and seeding, the start queue, the build limit, learned peaks) is done. + OpenSpec is the only planning source: `openspec/specs/` is what siding does today, `openspec/changes/` what it is about to do (the roadmap is the `phase--` changes), `openspec/changes/archive/` how it got here. CLAUDE.md holds the working agreements, guardrails, safety rules and conventions in full; read it before @@ -87,9 +89,11 @@ context: | `dev.siding.agent` (optional), never on networks or volumes, whose labels must not change between two `up`s, since Compose recreates a network whose labels changed. Service labels: `dev.siding.route` (`/`, `/`, `false`), `dev.siding.port` (the HTTP port of a - service with several), `dev.siding.seed` (`volume|script|none`). Volume label - `dev.siding.shared`. On `siding-proxy`: `dev.siding.budget` (bytes) and - `dev.siding.host-alias` (what `host.docker.internal` resolves to). The machine and + service with several), `dev.siding.seed` (`volume|script|none`), `dev.siding.seed.command`. + Volume label `dev.siding.shared`. Snapshot volumes: `dev.siding.snapshot`, + `dev.siding.snapshot-volume`, `dev.siding.snapshot-created`. On `siding-proxy`: + `dev.siding.budget` (bytes), `dev.siding.builds` (build slots) and `dev.siding.host-alias` + (what `host.docker.internal` resolves to). The machine and worktree labels exist from v0.1 so that remote hosts need no migration later. - Development and every test run in a devcontainer with its own Docker daemon (Docker-in-Docker); see the spec `dev-environment`. There is no Docker-outside-of-Docker diff --git a/openspec/specs/build-limit/spec.md b/openspec/specs/build-limit/spec.md new file mode 100644 index 0000000..8160671 --- /dev/null +++ b/openspec/specs/build-limit/spec.md @@ -0,0 +1,33 @@ +# build-limit Specification + +## Purpose +Defines the limit on image builds that run at the same time, so that many agents starting at +once do not stall the machine with parallel builds. + +## Requirements + +### Requirement: Build slots +`siding up` of a project with at least one service with `build:` SHALL hold one of N build +slots on this machine while `docker compose up` runs, waiting for a free one first, and print +on stderr that it waits. A project without `build:` MUST NOT need a slot. Waiting for a slot +counts against `--timeout`. + +#### Scenario: Two builds, one slot +- **WHEN** N is 1 and two `up`s of projects with `build:` start at the same moment +- **THEN** one runs `docker compose up` while the other waits, then the other runs + +#### Scenario: No build +- **WHEN** all build slots are held and `up` runs for a project of images only +- **THEN** it starts without waiting + +#### Scenario: A killed build +- **WHEN** the process holding a slot is killed +- **THEN** the slot is free again at once + +### Requirement: Number of slots +N SHALL be the label `dev.siding.builds` on `siding-proxy`, set with `siding setup --builds N` +and kept by later `setup`s, and half the CPUs of this machine (at least 1) without the label. + +#### Scenario: Default +- **WHEN** the machine has 8 CPUs and the proxy has no builds label +- **THEN** N is 4 diff --git a/openspec/specs/cli-contract/spec.md b/openspec/specs/cli-contract/spec.md index 93c9172..6eee52c 100644 --- a/openspec/specs/cli-contract/spec.md +++ b/openspec/specs/cli-contract/spec.md @@ -46,7 +46,7 @@ it SHALL print `error: ` on stderr, followed by a hint line when there #### Scenario: The error codes - **WHEN** a command fails -- **THEN** its code is one of `InvalidArguments`, `NotAGitRepository`, `NoBranch`, `ComposeFileNotFound`, `ComposeFailed`, `DockerUnavailable`, `ProxyNotRunning`, `PortInUse`, `InvalidRoute`, `AmbiguousPort`, `SlugCollision`, `StackNotFound`, `UnmergedBranch`, `DirtyWorktree`, `NoCapacity`, `NotInteractive`, or `Internal` for an unexpected error +- **THEN** its code is one of `InvalidArguments`, `NotAGitRepository`, `NoBranch`, `ComposeFileNotFound`, `ComposeFailed`, `DockerUnavailable`, `ProxyNotRunning`, `PortInUse`, `InvalidRoute`, `AmbiguousPort`, `SlugCollision`, `StackNotFound`, `UnmergedBranch`, `DirtyWorktree`, `NoCapacity`, `NotInteractive`, `SnapshotNotFound`, `SnapshotExists`, or `Internal` for an unexpected error #### Scenario: No capacity - **WHEN** `siding up --json` refuses because the stack does not fit into the memory budget @@ -55,7 +55,8 @@ it SHALL print `error: ` on stderr, followed by a hint line when there ### Requirement: Exit codes siding SHALL exit 0 on success and when a stack is Ready, 1 when a command fails or a stack is Failed, 2 when a stack is not Ready in time (TimedOut, or Starting without `--wait`), 3 when -`up` refuses for lack of memory (NoCapacity), and 130 without a message when interrupted. +`up` refuses for lack of memory or waited in line until `--timeout` (NoCapacity), and 130 +without a message when interrupted. #### Scenario: A verdict decides the exit code - **WHEN** `siding status --wait` ends with the verdict Failed @@ -66,7 +67,7 @@ Failed, 2 when a stack is not Ready in time (TimedOut, or Starting without `--wa - **THEN** siding stops docker compose and exits 130 without an error message #### Scenario: Over budget -- **WHEN** `siding up --wait` refuses because the memory budget is exhausted +- **WHEN** `siding up --wait` waits in line for memory until `--timeout` is up - **THEN** it exits 3 without starting a container ### Requirement: Version diff --git a/openspec/specs/memory-budget/spec.md b/openspec/specs/memory-budget/spec.md index cebedc8..120c048 100644 --- a/openspec/specs/memory-budget/spec.md +++ b/openspec/specs/memory-budget/spec.md @@ -25,14 +25,22 @@ Without the label the budget SHALL be 75 % of the memory the Docker daemon repor - **THEN** the budget set before stays ### Requirement: Estimate of a stack -The estimate of a stack SHALL be the sum over its services of the memory limit -(`deploy.resources.limits.memory`, else `mem_limit`), or 256 MiB for a service without a -limit; a service scaled to several replicas counts once per replica. +The estimate of a stack SHALL be the sum over its services, once per replica, of the learned +peak of the service plus a quarter, capped at its memory limit; without a learned peak, of the +memory limit (`deploy.resources.limits.memory`, else `mem_limit`); without either, 256 MiB. #### Scenario: Limits and defaults -- **WHEN** a stack has `db` with `mem_limit: 1g`, `web` with no limit and `api` with `deploy.resources.limits.memory: 512m` +- **WHEN** a stack has `db` with `mem_limit: 1g`, `web` with no limit and `api` with `deploy.resources.limits.memory: 512m`, and siding has learned no peak - **THEN** its estimate is 1 GiB + 256 MiB + 512 MiB +#### Scenario: A learned peak +- **WHEN** siding has seen `web` of the repository `shop` use at most 400 MiB, and `web` has no limit +- **THEN** `web` counts 500 MiB + +#### Scenario: Capped by the limit +- **WHEN** `db` has `mem_limit: 1g` and a learned peak of 900 MiB +- **THEN** `db` counts 1 GiB, not 1125 MiB + ### Requirement: up refuses over budget `siding up` SHALL refuse with `NoCapacity` and exit 3, before starting anything, when the memory in use by every other siding stack on the machine plus the estimate of this stack @@ -54,3 +62,21 @@ starts it anyway. #### Scenario: Within budget - **WHEN** the other stacks and the estimate fit into the budget - **THEN** `siding up` behaves as without a budget + +### Requirement: Learned peaks +Whenever siding reads the memory of running containers (`ps`, `ui`, `status`, `up`), it SHALL +keep the highest use seen per repository and service in `~/.siding/peaks.json`. The file is a +losable cache: without it, or when it cannot be read, estimates fall back to limits and +defaults, and siding writes a new one. + +#### Scenario: A peak is learned +- **WHEN** `siding ps` reads 400 MiB for `web` of `shop`, and later 300 MiB +- **THEN** `peaks.json` holds 400 MiB for `shop/web` + +#### Scenario: Branches share what they learn +- **WHEN** siding learned 400 MiB for `web` from the stack of `main` +- **THEN** the estimate for a new stack of `feature/x` of `shop` uses it + +#### Scenario: The cache is lost +- **WHEN** `~/.siding/peaks.json` is deleted or holds no valid JSON +- **THEN** siding works as without learned peaks and starts learning anew diff --git a/openspec/specs/proxy/spec.md b/openspec/specs/proxy/spec.md index d877277..1dceafa 100644 --- a/openspec/specs/proxy/spec.md +++ b/openspec/specs/proxy/spec.md @@ -9,8 +9,8 @@ on the network `siding`, started by `siding setup` and bound to the loopback int ### Requirement: Setup starts the proxy `siding setup` SHALL create the network `siding` if it is missing and run the Compose project `siding` with one container `siding-proxy`: Traefik with the Docker provider on the network -`siding`, restarting unless stopped. It SHALL print the proxy's address and budget, with -`--json` as a `Setup` document. +`siding`, restarting unless stopped. It SHALL print the proxy's address, budget and number of +build slots, with `--json` as a `Setup` document. #### Scenario: First setup - **WHEN** `siding setup` runs on a machine without the proxy @@ -18,7 +18,11 @@ on the network `siding`, started by `siding setup` and bound to the loopback int #### Scenario: JSON - **WHEN** `siding setup --json` runs -- **THEN** it prints a `Setup` document with the proxy's container name, network, image, port and budget in bytes +- **THEN** it prints a `Setup` document with the proxy's container name, network, image, port, budget in bytes and build slots + +#### Scenario: Build slots +- **WHEN** `siding setup --builds 2` runs, and later `siding setup` without `--builds` +- **THEN** `siding-proxy` carries `dev.siding.builds=2` after both ### Requirement: Loopback port The proxy SHALL publish exactly one port, on `127.0.0.1` only, `80` unless `--port ` names @@ -85,9 +89,10 @@ proxy SHALL reach the machine siding runs on as `host.docker.internal`. ### Requirement: Teardown removes the proxy `siding teardown` SHALL remove `siding-proxy`, its files under `~/.siding/proxy/`, and the -network `siding` unless a container still uses it. It MUST NOT touch any stack: running stacks -keep running as plain Compose projects, and teardown names them. `--dry-run` removes nothing; -with `--json` it prints a `Teardown` document. +network `siding` unless a container still uses it, and with `--snapshots` also every snapshot of +this machine. It MUST NOT touch any stack: running stacks keep running as plain Compose +projects, and teardown names them. `--dry-run` removes nothing; with `--json` it prints a +`Teardown` document. #### Scenario: Nothing runs but the proxy - **WHEN** `siding teardown` runs and no stack exists @@ -104,3 +109,7 @@ with `--json` it prints a `Teardown` document. #### Scenario: No proxy - **WHEN** `siding teardown` runs on a machine without `siding-proxy` - **THEN** it reports that there is nothing to remove and exits 0 + +#### Scenario: Snapshots +- **WHEN** `siding teardown` runs without `--snapshots` and snapshots exist +- **THEN** the snapshots stay and teardown names them; with `--snapshots` they are removed too diff --git a/openspec/specs/seeding/spec.md b/openspec/specs/seeding/spec.md new file mode 100644 index 0000000..5a6f27c --- /dev/null +++ b/openspec/specs/seeding/spec.md @@ -0,0 +1,53 @@ +# seeding Specification + +## Purpose +Defines how a new stack starts with data: its volumes copied from a snapshot, or a seed command +run once in a service, chosen per service with `dev.siding.seed`. + +## Requirements + +### Requirement: First up +A stack's first `up` SHALL be one where its Compose project has neither containers nor volumes +before siding starts it. Seeding happens only on a first `up`; later `up`s never seed again. + +#### Scenario: Second up +- **WHEN** `siding up --seed base` runs for a stack whose volumes exist +- **THEN** nothing is seeded, the data stays, and a warning says the stack already has data and names `siding down --volumes` + +### Requirement: Seed from a snapshot +On a first `up --seed `, siding SHALL create each own named volume of the project +that the snapshot holds as a copy of it, before Compose starts the stack, labelled so that +Compose adopts it. Volumes the snapshot lacks start empty. An unknown snapshot MUST fail with +`SnapshotNotFound` before anything starts. + +#### Scenario: A new branch with data +- **WHEN** `siding up --seed base --wait` runs in a new worktree of `shop` +- **THEN** the stack's `data` volume holds what `data` held when `base` was saved, and the verdict is Ready + +#### Scenario: Unknown snapshot +- **WHEN** `siding up --seed nope` runs +- **THEN** it fails with `SnapshotNotFound`, lists the repository's snapshots in the hint, and starts nothing + +### Requirement: Seed per service +The service label `dev.siding.seed` SHALL choose how a service's volumes are seeded: `volume` +(from the snapshot given with `--seed`; also when the label is missing), `none` (never), or +`script`. A volume used by a service with `none` MUST NOT be seeded. Another value MUST fail +`up` with `InvalidArguments`, naming the service. + +#### Scenario: none +- **WHEN** `cache` carries `dev.siding.seed: none` and `up --seed base` runs first +- **THEN** the volume of `cache` starts empty, and the others come from `base` + +### Requirement: Seed command +A service with `dev.siding.seed: script` SHALL carry `dev.siding.seed.command`, which siding runs +once in the service with `docker compose exec` on the first `up`, as soon as the service is +running and healthy if it has a healthcheck. Without the command label, `up` MUST fail with +`InvalidArguments`. + +#### Scenario: A seed command +- **WHEN** `db` carries `dev.siding.seed: script` and `dev.siding.seed.command: "psql -f /seed.sql"`, and the first `up --wait` runs +- **THEN** siding runs the command in `db` once, then reports the verdict + +#### Scenario: The command fails +- **WHEN** the seed command exits with code 2 +- **THEN** the verdict is `Failed` with service `db`, reason `SeedFailed`, the exit code in the hint and the command's last output lines as the log tail diff --git a/openspec/specs/snapshots/spec.md b/openspec/specs/snapshots/spec.md new file mode 100644 index 0000000..1e94ccf --- /dev/null +++ b/openspec/specs/snapshots/spec.md @@ -0,0 +1,55 @@ +# snapshots Specification + +## Purpose +Defines snapshots: named copies of a stack's volumes, kept in Docker, from which new stacks of +the same repository can start with data instead of empty. + +## Requirements + +### Requirement: Save a snapshot +`siding snapshot save ` SHALL copy every own named volume of the worktree's stack into a +new volume per volume, labelled `dev.siding.snapshot=`, `dev.siding.snapshot-volume=`, +`dev.siding.repo` and `dev.siding.machine`. It MUST stop the services that use those volumes +while copying and start them again afterwards. + +#### Scenario: Save +- **WHEN** `siding snapshot save base` runs in the stack `shop-main` with the volumes `data` and `uploads` +- **THEN** two snapshot volumes with `dev.siding.snapshot=base` exist, and `db` and `web`, which use them, run again + +#### Scenario: No volumes +- **WHEN** the stack has no named volumes +- **THEN** `snapshot save` fails with `InvalidArguments` and says there is nothing to save + +### Requirement: Snapshot names +A snapshot name SHALL be unique per repository and consist of lowercase letters, digits and +`-`. `save` MUST fail with `SnapshotExists` when the name is taken, unless `--force` replaces it. + +#### Scenario: Taken +- **WHEN** `siding snapshot save base` runs and `base` exists for the repository +- **THEN** it fails with `SnapshotExists`, and with `--force` the old snapshot is replaced + +#### Scenario: Another repository +- **WHEN** the repositories `shop` and `blog` both save a snapshot `base` +- **THEN** both exist side by side + +### Requirement: List and remove +`siding snapshot ls` SHALL list the snapshots of this machine, of the current repository when +run in one, with name, repository, volumes, size where Docker reports it, and creation time; +`--json` prints a `SnapshotList` document. `siding snapshot rm ` SHALL remove one, with +`--dry-run`, and fail with `SnapshotNotFound` for an unknown name. + +#### Scenario: List +- **WHEN** `siding snapshot ls --json` runs in the repository `shop` with the snapshots `base` and `big` +- **THEN** it prints a `SnapshotList` document with both and their volumes + +#### Scenario: Remove +- **WHEN** `siding snapshot rm big` runs +- **THEN** the volumes of `big` are gone and `base` stays + +### Requirement: Snapshots outlive stacks +Snapshots MUST NOT be removed by `down --volumes` or `gc`; only `snapshot rm` and +`teardown --snapshots` remove them. + +#### Scenario: The stack goes +- **WHEN** `siding down --volumes --force` removes the stack a snapshot was saved from +- **THEN** the snapshot still exists and can seed a new stack diff --git a/openspec/specs/stack-gc/spec.md b/openspec/specs/stack-gc/spec.md index bb48c4e..ac700ba 100644 --- a/openspec/specs/stack-gc/spec.md +++ b/openspec/specs/stack-gc/spec.md @@ -31,7 +31,7 @@ moved past it, or its upstream branch is gone (deleted after a merge, a squash m `siding gc` SHALL consider the stacks of this machine and remove: for a merged branch, the stack's containers, networks and volumes (reason `Merged`); for a stack whose worktree no longer exists, its containers and networks, and its volumes only if the branch is merged -(reason `WorktreeGone`). It MUST NOT touch git worktrees or branches. +(reason `WorktreeGone`). It MUST NOT touch git worktrees, branches or snapshots. #### Scenario: A deleted worktree with an unmerged branch - **WHEN** the worktree of `feature/wip` was deleted, but the branch has commits `main` lacks @@ -49,6 +49,10 @@ longer exists, its containers and networks, and its volumes only if the branch i - **WHEN** gc removes the stack of a merged branch - **THEN** the worktree directory and the branch still exist +#### Scenario: Snapshots stay +- **WHEN** gc removes the stack of a merged branch from which the snapshot `base` was saved +- **THEN** `base` still exists + ### Requirement: Ask before removing `siding gc` SHALL list what it would remove and ask before removing it. `--yes` removes without asking, and `--dry-run` only lists. Without a terminal, or with `--json`, it MUST fail with diff --git a/openspec/specs/stack-lifecycle/spec.md b/openspec/specs/stack-lifecycle/spec.md index fad5fce..1c8f82f 100644 --- a/openspec/specs/stack-lifecycle/spec.md +++ b/openspec/specs/stack-lifecycle/spec.md @@ -70,8 +70,10 @@ message when Compose fails. ### Requirement: Down `siding down` SHALL remove the stack's containers and networks by project name, also when the -compose file is gone, and keep its volumes. It SHALL print what it removed, with `--json` as a -`Down` document, and with `--dry-run` remove nothing. +compose file is gone, and keep its volumes. A stack whose containers are already gone but whose +volumes remain SHALL still be found by the labels of its volumes, so its data can be removed. It +SHALL print what it removed, with `--json` as a `Down` document, and with `--dry-run` remove +nothing. #### Scenario: Data survives - **WHEN** `siding down` and then `siding up` run @@ -82,9 +84,13 @@ compose file is gone, and keep its volumes. It SHALL print what it removed, with - **THEN** it prints a `Down` document listing the containers and networks with `dryRun: true`, and everything still runs #### Scenario: Nothing running -- **WHEN** `siding down` runs in a worktree without a stack +- **WHEN** `siding down` runs in a worktree whose stack has neither containers nor volumes - **THEN** it fails with `StackNotFound` +#### Scenario: Only the data is left +- **WHEN** `siding down` ran before, and now `siding down --volumes` runs in the same worktree +- **THEN** it finds the stack by its volumes and removes them, with the guard for unmerged and dirty work + ### Requirement: Removing data keeps work `siding down --volumes` SHALL also remove the stack's volumes, but MUST refuse with `UnmergedBranch` when the branch is neither merged into the default branch nor has a deleted diff --git a/openspec/specs/stack-list/spec.md b/openspec/specs/stack-list/spec.md index 0b4c8a1..2d71861 100644 --- a/openspec/specs/stack-list/spec.md +++ b/openspec/specs/stack-list/spec.md @@ -47,8 +47,13 @@ API reports it, and the total over all stacks against the memory budget. ### Requirement: StackList document With `--json`, `ps` SHALL print one `StackList` document with one entry per stack: project, repository, branch, worktree, machine, agent, state, address, memory in bytes, and -`worktreeMissing` when the worktree is gone; and the total memory and the budget in bytes. +`worktreeMissing` when the worktree is gone; the total memory and the budget in bytes; and the +stacks waiting in line, with project, place, memory needed and since when. #### Scenario: No stacks - **WHEN** `siding ps --json` runs and no stack exists - **THEN** it prints a `StackList` document without stacks, with the budget, and exits 0 + +#### Scenario: A stack waits +- **WHEN** `shop-feature-x` waits in line for memory +- **THEN** the `StackList` document lists it under `waiting` with place 1 diff --git a/openspec/specs/stack-status/spec.md b/openspec/specs/stack-status/spec.md index b069b37..90d7110 100644 --- a/openspec/specs/stack-status/spec.md +++ b/openspec/specs/stack-status/spec.md @@ -48,9 +48,9 @@ own (no router yet, 502, 503, 504) MUST NOT count. ### Requirement: Failed A stack SHALL be `Failed` as soon as a service has exited with a non-zero code, is unhealthy, -keeps restarting, or has no container; the failure MUST name the service, a reason -(`Exited`, `Unhealthy`, `Restarting`, `Missing`, `NotAnswering`), a hint, and the last 20 log -lines of that service. +keeps restarting, has no container, or its seed command failed; the failure MUST name the +service, a reason (`Exited`, `Unhealthy`, `Restarting`, `Missing`, `NotAnswering`, +`SeedFailed`), a hint, and the last 20 log lines of that service or of its seed command. #### Scenario: A service exits - **WHEN** `api` exits with code 1 after printing `cannot connect to db` @@ -60,6 +60,10 @@ lines of that service. - **WHEN** `db`'s healthcheck reports unhealthy - **THEN** the verdict is `Failed` with reason `Unhealthy`, and the hint contains the last healthcheck output +#### Scenario: Seed failed +- **WHEN** the seed command of `db` exits with code 2 on the first `up --wait` +- **THEN** the verdict is `Failed` with service `db`, reason `SeedFailed`, and the command's output as the log tail + ### Requirement: Waiting `siding status --wait` SHALL check until the verdict is `Ready` or `Failed`, at most for `--timeout` (default 3 minutes). When the time is up it SHALL report `TimedOut`, naming the diff --git a/openspec/specs/start-queue/spec.md b/openspec/specs/start-queue/spec.md new file mode 100644 index 0000000..817577e --- /dev/null +++ b/openspec/specs/start-queue/spec.md @@ -0,0 +1,42 @@ +# start-queue Specification + +## Purpose +Defines how stacks that do not fit into the memory budget wait their turn instead of being +refused, without a background service. + +## Requirements + +### Requirement: Waiting in line +When a stack does not fit into the budget, `siding up --wait` SHALL wait in line instead of +refusing, until it fits or `--timeout` is up, and then start it as usual. Without `--wait`, +`up` SHALL refuse with `NoCapacity` and exit 3 as before. + +#### Scenario: Memory frees +- **WHEN** `siding up --wait` waits because the budget is full, and another stack is taken down +- **THEN** the waiting stack starts within a few seconds and the command ends with its verdict + +#### Scenario: Time is up +- **WHEN** nothing frees memory before `--timeout` +- **THEN** `up` exits 3 with `NoCapacity`, its place in line and the memory it needs, and starts nothing + +### Requirement: First come, first served +Stacks SHALL start in the order they began to wait: only the first one in line may start, even +if a later one would fit. A waiting `up` that ended (stopped, killed, timed out) MUST leave the +line. + +#### Scenario: Order +- **WHEN** `a` began to wait before `b`, and memory frees enough for `b` but not for `a` +- **THEN** `b` keeps waiting until `a` has started + +#### Scenario: A killed waiter +- **WHEN** the process of the first waiting `up` was killed +- **THEN** the next one moves up within a few seconds + +### Requirement: The line is visible +`siding ps` and `siding ui` SHALL list the stacks waiting in line with project, place, memory +needed and since when they wait, and the waiting `up` SHALL print its place on stderr when it +changes. + +#### Scenario: ps while waiting +- **WHEN** `shop-feature-x` waits in line +- **THEN** `siding ps` shows it under "waiting" with its place and the memory it needs