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.

• 1b. One known owner finding to fix before the smoke can pass. proxy.Chooser (task 05, internal/proxy/hosts.go) computes Free with lim.FreeSlots(host), which sums the slots of every model on the host; the rule now reads: Free = free slots for the requested model = cfg.Hosts[host].Models[model].Parallel - lim.InFlight(host, model), floored at 0, and 0 when the host does not list the model. Make that change (only that), run go test -race -count=1 ./internal/proxy/ (must stay ok), then re-run make smoke. This is the one code change this task makes; record it in Deviations as an owner-directed fix.
• 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 internal/proxy 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.