crossbar/docs/plans/v1/08-smoke-readme.md

v1 task 08: the smoke run and the README

Branch: v1 (run git switch v1; git status --short must be empty, otherwise stop) Commit subject: Smoke run for v1; README for leases, admin and accounting

Goal

Prove v1 end to end with the given tools/smoke.sh — leases, header route, pin, queue, drain, failover and recovery, streaming with the usage chunk intact, usage and metrics — and bring the README up to date.

Files

• Copy (replaces v0's): tools/smoke.sh, cmd/fakeupstream/main.go
• Modify: README.md, docs/implementer-log.md

Steps

• 1. Copy and run.

git switch v1
cp docs/plans/v1/_files/tools/smoke.sh tools/
cp docs/plans/v1/_files/cmd/fakeupstream/main.go cmd/fakeupstream/
make smoke

Expected last line: smoke: ok (stream spread N ms), N ≥ 600. The script prints which numbered check failed and crossbar's log. A failure is a defect in tasks 01–07 or in the script: fix code only when a rule from an earlier task was broken; if the script's expectation contradicts a task rule, stop and report which.

• 2. Update README.md. Keep the seven v0 sections; change: the intro (leases, not "first healthy host"); ## Configure gets db, lease_idle, retention, queue_max in the table and the new example.toml; ## Point clients at it adds the X-Crossbar-Route header alternative; ## Inspect becomes ## Operate and documents all six endpoints with one example each (GET hosts, GET routes, POST routes/{route} pin and release, POST hosts/{host} drain, GET usage JSON and text, GET metrics), taken from the smoke run; ## What v1 does not do: context-size guard, wake-on-LAN, Tailscale identity, /slots — see PLAN.md v2.
• 3. Run the gate. make gate. 4. Log and commit. Row v1/08-smoke-readme, with the smoke line in Notes.

git add tools/smoke.sh cmd/fakeupstream/main.go README.md docs/implementer-log.md
git commit

Done when

• make smoke prints smoke: ok (…); make gate prints gate: ok; both copied files byte-identical.

Stop and report if

• make smoke fails twice in the same way.