Skip to content

docs: teach Rafter layers with a standalone TLS counter - #13

Open
zsumz wants to merge 6 commits into
mainfrom
docs/layered-stack-readme
Open

zsumz wants to merge 6 commits into
mainfrom
docs/layered-stack-readme

Conversation

@zsumz

@zsumz zsumz commented Sep 9, 2026

Copy link
Copy Markdown
Owner

Explain how to build with Rafter's optional crates and which responsibilities belong to the application. The README describes the available layers while preserving its original header, description, and navigation links.

The getting-started guide follows six integration decisions: choose a starting layer, implement application behavior, connect durable storage and recovery, configure TLS peers, submit requests through the service, and drive the server loop. Short excerpts from one standalone counter explain the actual public APIs and distinguish Rafter's types from application helpers. A write walkthrough follows one increment through the stack, then shows how to adapt the counter or replace individual components.

The complete counter runs three separate server processes with disk-backed state and mutually authenticated TLS. Setup commands and the expandable full-source reference come after the teaching sections. The guide explains application state versus Raft storage, saved applied progress, request outcomes, client versus peer traffic, and the remaining deployment choices. The starter keeps fixed membership and its full log; HTTP binds only to loopback.

Validation:

  • python3 scripts/check-counter-guide checks all 11 teaching excerpts against the standalone source, extracts the complete source reference into a fresh project outside the repository, and passes Rust 1.88 formatting, Clippy with warnings denied, unit tests, build, and the real-process smoke test. CI runs this check.
  • All three application tests pass, covering durable applied progress, failed publication, and snapshot restoration.
  • Process checks pass for peer TLS authentication, writes and redirected reads, leader loss and catch-up, full-cluster crash recovery, missing or corrupt saved state, quorum loss with uncertain write outcomes, and clean shutdown. After quorum restoration, the smoke test waits for a successful read rather than treating local leader status as proof that reads can already complete; it never retries an uncertain increment.
  • All 37 local links and anchors resolve; code fences and nested source sections are balanced; the complete README header matches main.
  • Zrail 0.0.3-rc.8 passes. The only architecture lock change in this PR is the previously reviewed CI gate hash: approved because it adds the walkthrough check without removing existing checks or changing architecture policy.
  • git diff --cached --check passes.

@zsumz zsumz changed the title docs(readme): explain layered stack choices docs: explain Rafter layers and add a getting started guide Sep 9, 2026
@zsumz zsumz changed the title docs: explain Rafter layers and add a getting started guide docs: explain Rafter layers with a standalone TLS walkthrough Sep 9, 2026
@zsumz
zsumz requested a deployment to architecture-policy-review September 9, 2026 15:55 — with GitHub Actions Waiting
@zsumz zsumz changed the title docs: explain Rafter layers with a standalone TLS walkthrough docs: teach Rafter layers with a standalone TLS counter Sep 9, 2026
@zsumz
zsumz requested a deployment to architecture-policy-review September 9, 2026 16:11 — with GitHub Actions Waiting
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant