alee/rutster
0
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

deploy-epoch: deployment topology — one binary, three blessed shapes #27

Merged
alee merged 6 commits from docs/deployment-topology-spec into main 2026-07-09 21:11:27 +00:00
Conversation 1 Commits 6 Files Changed 69 +14771 -36
alee commented 2026-07-06 20:01:53 +00:00
Owner
Copy Link

What lands

The full deploy-epoch integration: 6 commits merging the deployment topology spec + 4 implementation slices.

Slice breakdown

  • 12af2f8 docs(spec): deployment topology — one binary, three blessed shapes — the design spec (ADR-0011 chapter)
  • fae9fcc docs(plans): four deployment-epoch implementation plans (slices A–G) — the 4 implementation plans
  • 7e2ae6d (PR #24) deploy slice A: engine hygiene — TCP_NODELAY + WS pings + trunk config — TCP_NODELAY + TCP_QUICKACK-suppression + WS pings + trunk config fixes
  • 0c307ac (PR #23) deploy slice G (docs + ADR-0011): docs/deploy/ tree + ADR-0011 Proposed — docs/deploy/ + ADR-0011
  • 838ecdf (PR #25) deploy slice C+D+E (binary features): rustls Phase 1 + /metrics + ValkeyEventSink — rustls TLS, /metrics endpoint, ValkeyEventSink
  • c772485 (PR #26) deploy slice B + F: deploy/ artifacts + image-build + container smoke CI + tag-push publish — Dockerfile + compose.yaml + Caddyfile + smoke harness + ci.yml image-build/smoke/smoke-compose/smoke-reload jobs + publish-images.yml

Stats

  • 69 files changed, 14771 insertions(+), 36 deletions(-)
  • 4 Docker images (rutster-engine/brain/edge/allinone) buildable via docker buildx build --target
  • 4 new CI jobs (image-build + smoke + smoke-compose + smoke-reload)
  • 1 new workflow file (publish-images.yml — slice F tag-push publish)
  • ADR-0011 (deployment topology) Proposed

Pre-tag verification (PM-executed on integration tip c772485)

  • Seam gate: loop_driver.rs = 744bf314edf7f4925c8bb3bd0f5176dbc88f8113, rtc_session.rs = f47d63b9a2883d37066a93c9daa0e2cf8816bec4 — UNCHANGED
  • cargo fmt --check — exit 0
  • cargo clippy --all -- -D warnings — exit 0
  • cargo clippy --all --all-targets --features=sim-bench -- -D warnings — exit 0
  • cargo test --all — exit 0
  • cargo test --all --features=sim-bench -- --test-threads=1 — exit 0
  • cargo doc --no-deps — exit 0 (4 Rustdoc lint warnings, unrelated to deploy slices — no Rust touched)
  • cargo deny check — bans FAILED + licenses FAILED PRE-EXISTING at main tip 6340e63 (transitive hashbrown 0.14.5 vs 0.17.1 + cargo-deny 0.18.3 license-syntax limitation). CI uses EmbarkStudios/cargo-deny-action@v2 (cargo-deny 0.19.x) which handles the syntax. Not introduced by this epoch.

DCO note

The 4 intermediate PR-merge commits (7e2ae6d, 0c307ac, 838ecdf, c772485) show NO Signed-off-by trailer — Gitea's squash-merge replaced the original branch commits' signoffs with Co-authored-by + Co-committed-by trailers. The 2 pre-epoch commits (12af2f8, fae9fcc) retain their signoffs. tea has no --signoff flag on pulls merge, so this slipped through per-PR.

Remediation: this main-target PR will be squash-merged via tea pulls merge --style squash --message with the full Signed-off-by: Aaron D. Lee <himself@adlee.work> trailer appended to the merge commit message. This lands ONE DCO-compliant commit on main; the 4 DCO-defective intermediate commits are squashed away and never appear on main's history.

Reviews

  • Spec: docs/superpowers/specs/2026-07-05-deployment-topology-design.md (full design —§1.2 out-of-scope table is the named-deferral boundary)
  • TLS brief: docs/superpowers/specs/2026-07-05-tls-edge-decision-brief.md
  • ADR-0011: docs/adr/0011-deployment-topology.md (Proposed)
  • Plans: docs/superpowers/plans/2026-07-05-deploy-{a,b,c,d}-*.md
  • PRs #23, #24, #25, #26 (all verified + merged into docs/deployment-topology-spec individually)

Merge instructions

Squash-merge (default). PM will execute the merge via:

tea pulls merge <this-PR-index> --style squash --message "deploy-epoch: deployment topology — one binary, three blessed shapes

Signed-off-by: Aaron D. Lee <himself@adlee.work>"

This ensures the main commit carries the DCO signoff trailer. The 6 integration-branch commits collapse to 1 DCO-clean commit on main.

Out of scope (named deferrals per spec §1.2 / ADR-0011)

  • arm64 images (linux/amd64 only this epoch)
  • T3 fleet artifacts (presence heartbeats, directory redirects, placement code)
  • Object-storage CDR pipeline
  • In-binary ACME (rustls Phase 2) — behind the four named triggers
  • Cargo-deny-adjacent image license scan

After this lands, the deploy-epoch tag is the next user decision (PM will ask, not assume).

## What lands The full deploy-epoch integration: 6 commits merging the deployment topology spec + 4 implementation slices. ### Slice breakdown - **12af2f8** `docs(spec): deployment topology — one binary, three blessed shapes` — the design spec (ADR-0011 chapter) - **fae9fcc** `docs(plans): four deployment-epoch implementation plans (slices A–G)` — the 4 implementation plans - **7e2ae6d (PR #24)** `deploy slice A: engine hygiene — TCP_NODELAY + WS pings + trunk config` — TCP_NODELAY + TCP_QUICKACK-suppression + WS pings + trunk config fixes - **0c307ac (PR #23)** `deploy slice G (docs + ADR-0011): docs/deploy/ tree + ADR-0011 Proposed` — docs/deploy/ + ADR-0011 - **838ecdf (PR #25)** `deploy slice C+D+E (binary features): rustls Phase 1 + /metrics + ValkeyEventSink` — rustls TLS, /metrics endpoint, ValkeyEventSink - **c772485 (PR #26)** `deploy slice B + F: deploy/ artifacts + image-build + container smoke CI + tag-push publish` — Dockerfile + compose.yaml + Caddyfile + smoke harness + ci.yml image-build/smoke/smoke-compose/smoke-reload jobs + publish-images.yml ### Stats - 69 files changed, 14771 insertions(+), 36 deletions(-) - 4 Docker images (rutster-engine/brain/edge/allinone) buildable via `docker buildx build --target` - 4 new CI jobs (image-build + smoke + smoke-compose + smoke-reload) - 1 new workflow file (publish-images.yml — slice F tag-push publish) - ADR-0011 (deployment topology) Proposed ## Pre-tag verification (PM-executed on integration tip c772485) - Seam gate: `loop_driver.rs` = `744bf314edf7f4925c8bb3bd0f5176dbc88f8113`, `rtc_session.rs` = `f47d63b9a2883d37066a93c9daa0e2cf8816bec4` — UNCHANGED - `cargo fmt --check` — exit 0 - `cargo clippy --all -- -D warnings` — exit 0 - `cargo clippy --all --all-targets --features=sim-bench -- -D warnings` — exit 0 - `cargo test --all` — exit 0 - `cargo test --all --features=sim-bench -- --test-threads=1` — exit 0 - `cargo doc --no-deps` — exit 0 (4 Rustdoc lint warnings, unrelated to deploy slices — no Rust touched) - `cargo deny check` — `bans FAILED + licenses FAILED` PRE-EXISTING at main tip `6340e63` (transitive hashbrown 0.14.5 vs 0.17.1 + cargo-deny 0.18.3 license-syntax limitation). CI uses `EmbarkStudios/cargo-deny-action@v2` (cargo-deny 0.19.x) which handles the syntax. Not introduced by this epoch. ## DCO note The 4 intermediate PR-merge commits (7e2ae6d, 0c307ac, 838ecdf, c772485) show NO `Signed-off-by` trailer — Gitea's squash-merge replaced the original branch commits' signoffs with `Co-authored-by` + `Co-committed-by` trailers. The 2 pre-epoch commits (12af2f8, fae9fcc) retain their signoffs. tea has no `--signoff` flag on `pulls merge`, so this slipped through per-PR. Remediation: this main-target PR will be **squash-merged via `tea pulls merge --style squash --message`** with the full `Signed-off-by: Aaron D. Lee <himself@adlee.work>` trailer appended to the merge commit message. This lands ONE DCO-compliant commit on main; the 4 DCO-defective intermediate commits are squashed away and never appear on main's history. ## Reviews - Spec: `docs/superpowers/specs/2026-07-05-deployment-topology-design.md` (full design —§1.2 out-of-scope table is the named-deferral boundary) - TLS brief: `docs/superpowers/specs/2026-07-05-tls-edge-decision-brief.md` - ADR-0011: `docs/adr/0011-deployment-topology.md` (Proposed) - Plans: `docs/superpowers/plans/2026-07-05-deploy-{a,b,c,d}-*.md` - PRs #23, #24, #25, #26 (all verified + merged into docs/deployment-topology-spec individually) ## Merge instructions **Squash-merge (default).** PM will execute the merge via: ```bash tea pulls merge <this-PR-index> --style squash --message "deploy-epoch: deployment topology — one binary, three blessed shapes Signed-off-by: Aaron D. Lee <himself@adlee.work>" ``` This ensures the main commit carries the DCO signoff trailer. The 6 integration-branch commits collapse to 1 DCO-clean commit on main. ## Out of scope (named deferrals per spec §1.2 / ADR-0011) - arm64 images (linux/amd64 only this epoch) - T3 fleet artifacts (presence heartbeats, directory redirects, placement code) - Object-storage CDR pipeline - In-binary ACME (rustls Phase 2) — behind the four named triggers - Cargo-deny-adjacent image license scan After this lands, the `deploy-epoch` tag is the next user decision (PM will ask, not assume).
alee added 6 commits 2026-07-06 20:01:55 +00:00
docs(spec): deployment topology — one binary, three blessed shapes 12af2f88b3 
Closes the deployment-topology design ADR-0008 reserved: T1 all-in-one /
T2 modular compose / T3 fleet-on-paper, same FOB binary, config-only
differences. Companion TLS/edge decision brief (six-family research
survey) included; spec produces ADR-0011 plus slices A–G.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012QndwfhjyTiZcUYp87dwW8
Signed-off-by: Aaron D. Lee <himself@adlee.work>
docs(plans): four deployment-epoch implementation plans (slices A–G) fae9fcc82a 
Plan A: engine hygiene (TCP_NODELAY via axum 0.7.9 Serve::tcp_nodelay,
trunk WS pings, webhook-base TwiML derivation, trusted-proxy posture).
Plan B: packaging + CI (four images, s6 all-in-one, compose, Caddyfile,
smoke suite incl. reload-during-call, slice-F publish workflow).
Plan C: in-binary features (rustls Phase 1 BYO-cert, /metrics,
ValkeyEventSink + smoke hook fill).
Plan G: docs/deploy tree + ADR-0011 drafting.

Authored by parallel plan-writers (this session + omo rescue after a
session-limit interruption); verified: placeholder scan, cited-path
existence, cross-plan image/env-var consistency, seam-gate compliance.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012QndwfhjyTiZcUYp87dwW8
Signed-off-by: Aaron D. Lee <himself@adlee.work>
deploy slice A: engine hygiene — TCP_NODELAY + WS pings + trunk config (#24) 7e2ae6d2d2 
Co-authored-by: Aaron D. Lee <himself@adlee.work>
Co-committed-by: Aaron D. Lee <himself@adlee.work>
deploy slice G (docs + ADR-0011): docs/deploy/ tree + ADR-0011 Proposed (#23) 0c307acdb5 
Co-authored-by: Aaron D. Lee <himself@adlee.work>
Co-committed-by: Aaron D. Lee <himself@adlee.work>
deploy slice C+D+E (binary features): rustls Phase 1 + /metrics + ValkeyEventSink (#25) 838ecdf5e6 
Co-authored-by: Aaron D. Lee <himself@adlee.work>
Co-committed-by: Aaron D. Lee <himself@adlee.work>
deploy slice B + F: deploy/ artifacts + image-build + container smoke CI + tag-push publish (#26)
Some checks failed
CI / fmt (pull_request) Successful in 1m22s
Details
CI / clippy (pull_request) Successful in 3m46s
Details
CI / test (1.85) (pull_request) Failing after 8m22s
Details
CI / test (stable) (pull_request) Failing after 8m25s
Details
CI / deny (pull_request) Failing after 1m24s
Details
CI / sim-bench (stable) (pull_request) Failing after 11m2s
Details
CI / image-build (4 images) (pull_request) Has been skipped
Details
CI / smoke (all-in-one TLS sim call) (pull_request) Has been skipped
Details
CI / smoke (T2 compose four-service) (pull_request) Has been skipped
Details
CI / smoke (caddy reload during live call, zero drops) (pull_request) Has been skipped
Details
CI / twilio-live (manual only) (pull_request) Has been skipped
Details
c772485f92 
Co-authored-by: Aaron D. Lee <himself@adlee.work>
Co-committed-by: Aaron D. Lee <himself@adlee.work>
alee merged commit cc25e80310 into main 2026-07-09 21:11:27 +00:00
alee commented 2026-07-09 21:52:03 +00:00
Author
Owner
Copy Link

Code review

Integration review of the squashed epoch (cross-slice defects only; per-slice findings are posted on #23/#24/#25/#26 — most notably the TLS double-bind panic on #25 and the T1/T2 boot-blockers on #26). Found 3 issues:

  1. The T1 bundled brain is inert: the engine's default RUTSTER_TAP_URL is the slice-2 dev value ws://127.0.0.1:8081/echo, while the bundled rutster-brain-realtime binds 127.0.0.1:8082. Neither the rutster-allinone Dockerfile stage nor the s6 engine run script sets RUTSTER_TAP_URL, and the quickstart's docker run omits it — so T1 taps a port nothing listens on, and every call runs brainless.

rutster/deploy/Dockerfile Lines 200 to 211 in c772485f92
# §5 risk 5) + Valkey /var/lib/valkey (stream/state persistence per
# ADR-0005).
VOLUME /data /var/lib/valkey
# Caddy :80/:443 public; FOB :8080 behind Caddy; brain :8082 loopback;
# valkey :6379 loopback; media UDP direct.
EXPOSE 80 443 8080 8082 6379 49152-49407/udp
# s6-overlay v3 entrypoint — the binary `s6-overlay-init` (symlinked from
# /s6-init in the noarch tarball) runs the service bundle in
# /etc/s6-overlay/s6-rc.d/ via s6-rc.
ENTRYPOINT ["/s6-init"]

  1. ValkeyEventSink shipped inert everywhere: plan B's named # TODO slice-C: assert lifecycle event in Valkey stream hook in compose_smoke.sh was never filled at integration, and no shipped artifact (compose.yaml, .env.example active section, s6 run scripts) sets RUTSTER_VALKEY_URL. The epoch's first Valkey consumer exists in code, is unit-tested, and is switched off in every deployment shape.

rutster/deploy/smoke/compose_smoke.sh Lines 78 to 84 in c772485f92
# TODO slice-C: assert lifecycle event in Valkey stream.
# Slice C lands ValkeyEventSink (spec §5.6) + the assert-event-lands-in-
# Valkey-stream smoke addition. The hook here documents the contract:
# Once slice C lands, this smoke runs:
# docker compose exec valkey valkey-cli XLEN rutster:events
# and asserts > 0 after a sim call completes (an EventSink::on_event

  1. Stale cross-slice commentary shipped in the squash: .env.example's "Future vars — land with sibling slices, NOT this slice" section describes RUTSTER_TLS_CERT/KEY (slice C), RUTSTER_METRICS_BIND (slice D), and RUTSTER_VALKEY_URL (slice E) as not yet landed — all three landed in this same commit — and cites a nonexistent plan file (2026-07-05-deploy-c-rustls-tls.md; actual: 2026-07-05-deploy-c-binary-features.md).

rutster/deploy/.env.example Lines 130 to 140 in c772485f92
################################################################################
# Future vars — land with sibling slices, NOT this slice
################################################################################
# RUTSTER_TLS_CERT / RUTSTER_TLS_KEY — land with slice C (rustls Phase 1,
# BYO-cert in-process TLS). The engine binary stays compiled-with-rustls
# from slice C onward; runtime-gated by these vars. See the slice-C plan
# at docs/superpowers/plans/2026-07-05-deploy-c-rustls-tls.md (path may
# vary — check the plans dir).
# RUTSTER_TLS_CERT=/etc/rutster/tls/fullchain.pem
# RUTSTER_TLS_KEY=/etc/rutster/tls/privkey.pem

🤖 Generated with Claude Code

- If this code review was useful, please react with 👍. Otherwise, react with 👎.

### Code review Integration review of the squashed epoch (cross-slice defects only; per-slice findings are posted on #23/#24/#25/#26 — most notably the TLS double-bind panic on #25 and the T1/T2 boot-blockers on #26). Found 3 issues: 1. The T1 bundled brain is inert: the engine's default `RUTSTER_TAP_URL` is the slice-2 dev value `ws://127.0.0.1:8081/echo`, while the bundled `rutster-brain-realtime` binds `127.0.0.1:8082`. Neither the `rutster-allinone` Dockerfile stage nor the s6 engine run script sets `RUTSTER_TAP_URL`, and the quickstart's `docker run` omits it — so T1 taps a port nothing listens on, and every call runs brainless. https://git.adlee.work/alee/rutster/src/commit/c772485f92dfdc4daff4a14b6afe9b5f01480150/deploy/Dockerfile#L200-L212 2. ValkeyEventSink shipped inert everywhere: plan B's named `# TODO slice-C: assert lifecycle event in Valkey stream` hook in compose_smoke.sh was never filled at integration, and no shipped artifact (compose.yaml, .env.example active section, s6 run scripts) sets `RUTSTER_VALKEY_URL`. The epoch's first Valkey consumer exists in code, is unit-tested, and is switched off in every deployment shape. https://git.adlee.work/alee/rutster/src/commit/c772485f92dfdc4daff4a14b6afe9b5f01480150/deploy/smoke/compose_smoke.sh#L78-L84 3. Stale cross-slice commentary shipped in the squash: `.env.example`'s "Future vars — land with sibling slices, NOT this slice" section describes `RUTSTER_TLS_CERT/KEY` (slice C), `RUTSTER_METRICS_BIND` (slice D), and `RUTSTER_VALKEY_URL` (slice E) as not yet landed — all three landed in this same commit — and cites a nonexistent plan file (`2026-07-05-deploy-c-rustls-tls.md`; actual: `2026-07-05-deploy-c-binary-features.md`). https://git.adlee.work/alee/rutster/src/commit/c772485f92dfdc4daff4a14b6afe9b5f01480150/deploy/.env.example#L130-L140 🤖 Generated with [Claude Code](https://claude.ai/code) <sub>- If this code review was useful, please react with 👍. Otherwise, react with 👎.</sub>
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
alee
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: alee/rutster#27
Delete Branch "docs/deployment-topology-spec"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?