Skip to content

Add gateway architecture book - #42

Merged
dawid-nowak merged 14 commits into
mainfrom
user/luca/gateway-book
Jul 13, 2026
Merged

Add gateway architecture book#42
dawid-nowak merged 14 commits into
mainfrom
user/luca/gateway-book

Conversation

@lucarlig

@lucarlig lucarlig commented Jun 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • add an mdBook under docs/book for the gateway architecture guide with getting-started, architecture, MCP behavior, operations, and project sections
  • add a GitHub Pages workflow that builds the book on PRs and deploys it from main
  • sync book content with current main behavior: virtual_host_config_layer 404 handling, backend-federated list_resource_templates, configurable user-config cache expiry, and optional JWT teams/scopes claims
  • implement the MCP Method Reference, Failure Modes, Publishing This Book, Telemetry And Diagnostics, Testing, Performance, Deployment Notes, and Contributing chapters (including the cf-integration full-stack harness), and add Security Model, Control-Plane Integration (explicitly provisional — no formal contract stipulated yet), and Concurrency And Runtime Model pages — the book has no remaining drafts from verified code, workflow, and compose behavior; the remaining draft chapters keep the documented draft marker
  • port the root README telemetry walkthrough into the book and leave a pointer; link the book from the top of the README
  • fix the root README user-config seeding examples: the admin endpoint requires snake_case virtual_hosts and full backend objects, so the old camelCase url-only payloads were rejected
  • replace the duplicated (and partially stale) architecture notes in AGENTS.md with links to the book pages, keeping only working rules and logging guidance

Validation

  • mdbook build docs/book
  • mdbook test docs/book
  • git diff --check
  • relative links and anchors in book pages, README, and AGENTS.md checked against the tree
  • technical claims (layer order and status codes, cache and retry settings, CPEX hook names, transport constraints, compose ports and credentials, metric export interval, admin routes) verified against the current code and compose files

Notes

Repository Pages still needs the publishing source set to GitHub Actions in the repository settings if it is not already configured.

@lucarlig
lucarlig force-pushed the user/luca/gateway-book branch 10 times, most recently from de63197 to 749561b Compare June 24, 2026 09:48
@lucarlig
lucarlig force-pushed the user/luca/gateway-book branch 4 times, most recently from 6762548 to cf54ebf Compare July 4, 2026 20:34
@lucarlig
lucarlig marked this pull request as ready for review July 13, 2026 13:06
lucarlig added 14 commits July 13, 2026 14:22
@lucarlig
Add gateway architecture book
aa5e1c7 
Signed-off-by: lucarlig <luca.carlig@ibm.com>
@lucarlig
Implement getting started book section
79972cd 
Signed-off-by: lucarlig <luca.carlig@ibm.com>
@lucarlig
Expand gateway architecture book
37f1cfb 
Signed-off-by: lucarlig <luca.carlig@ibm.com>
@lucarlig
ci(pages): install mdbook prebuilt and split deploy concurrency
dbc31f2 
- Replace `cargo install mdbook` (source build) with taiki-e/install-action
  prebuilt binary so mdBook is no longer recompiled on every workflow run.
- Drop the now-unused rust-toolchain step (mdbook build needs no toolchain).
- Move concurrency to per-job: the build group cancels superseded runs per
  ref, while deploy uses a stable "pages" group with cancel-in-progress
  false so an in-flight GitHub Pages deployment is never cancelled.

Signed-off-by: lucarlig <luca.carlig@ibm.com>
@lucarlig
docs(book): improve readability of intro, tutorial, and routing pages
36598eb 
- Landing page: open with a plain-language description and an API-gateway
  analogy before the dense one-liner, define the downstream/upstream
  direction convention up front, add a "Key terms" table for the
  vocabulary reused across the book, and add a goal-based "Where to go
  next" pointer.
- Run the Gateway Locally: note that the numbered steps must run in order
  in the same terminal because later steps reuse ${TOKEN} and
  ${SESSION_ID} set by earlier ones.
- MCP Routing Semantics: explain why the name splitter does not cut on the
  first '-' (backend names contain hyphens), so the matching rule is no
  longer surprising.

Signed-off-by: lucarlig <luca.carlig@ibm.com>
@lucarlig
docs(book): add concrete examples, cross-links, and reference orienta…
f248094 
…tion

- Configuration Reference: open with what the page is, state that the
  command-line flag wins over the env var when both are set, and preview
  how the options are grouped.
- Authentication: add a concrete decoded JWT payload for the local
  admin@example.com subject so the abstract claim tables have a worked
  example; reiterate that only `sub` drives routing today.
- Runtime Configuration: link the UserConfig type sketch to the full JSON
  document in the local-run tutorial.
- Request Flow: point readers to the local-run tutorial to watch the same
  flow with real requests.
- Architecture: note the subpages are ordered for a first read.

Signed-off-by: lucarlig <luca.carlig@ibm.com>
@lucarlig
docs(book): sync with dataplane behavior and implement operations cha…
1301805 
…pters

Sync existing pages with current main:

- document virtual_host_config_layer and its 404 for unknown virtual hosts
- move list_resource_templates from local stub to backend fanout with
  prefixed names and URI templates
- replace the fixed 1-hour user config cache expiry with the configurable
  --user-config-cache-expiry-seconds flag (default 60s, 0 disables)
- note that JWT teams and scopes claims are optional
- carry the target pipeline and expected config growth notes into the
  system shape and runtime configuration pages
- add a book description to book.toml and update the two affected SVGs

Implement the reference and operations chapters from verified behavior:

- MCP Method Reference: per-method behavior for initialize, list, targeted,
  and local methods plus DELETE cleanup
- Failure Modes: failure tables per boundary with exact responses
- Publishing This Book: local build, validation, and Pages workflow behavior
- Telemetry And Diagnostics: signals, filters, the Langfuse/OTel-Collector/
  Prometheus verification stack, starter PromQL queries, and a debugging
  checklist
- Testing: workspace checks, in-repo integration tests, and the
  cf-integration full-stack harness with probe and test-all lanes
- Performance: dataplane-only Goose load testing, full-stack Locust runs,
  headless versus web UI, and benchmark settings

Signed-off-by: lucarlig <luca.carlig@ibm.com>
@lucarlig
docs: point README and AGENTS.md at the gateway book
2eef8c6 
- link the book from the top of the root README
- port the README telemetry walkthrough into the book and leave a pointer
- fix the README user-config examples: the admin endpoint requires
  snake_case virtual_hosts and full backend objects, so the old camelCase
  url-only payloads were rejected
- replace the AGENTS.md architecture notes, which duplicated the book and
  had drifted, with links to the book pages plus working rules and logging
  guidance

Signed-off-by: lucarlig <luca.carlig@ibm.com>
@lucarlig
ci(pages): pin install-action to the version used by CI
473f17d 
Signed-off-by: lucarlig <luca.carlig@ibm.com>
@lucarlig
docs(book): add security, integration, and concurrency pages; finish …
3cd5c17 
…drafts

New architecture pages, all from verified code and config:

- Security Model And Trust Boundaries: per-boundary trust table, identity
  and authorization rules, compromise impact, transport posture, local
  bootstrap and secrets rules
- Control-Plane Integration: the current, explicitly provisional
  integration surface (no formal contract stipulated yet) — route parity,
  404 shape, token and claims shape, Redis key/value encodings, schema
  generation, publisher cadence and staleness bound, front-door split
- Concurrency And Runtime Model: single versus multi runtime shapes, the
  per-runtime-thread session state consequence of SO_REUSEPORT mode,
  lock map, fanout and cancellation, listener behavior, allocator

Implement the two remaining drafts:

- Deployment Notes: front-door routing from the reference nginx config,
  TLS choices per leg, session affinity and failover, Redis availability,
  image publishing and sizing, deployment checklist
- Contributing To The Gateway: crate ownership, routing contract rules,
  plugin hook rules, validation gates matching pre-commit and CI, and
  book-sync expectations

Cross-link session ownership to the multi-runtime constraint and list the
new pages in the architecture index and AGENTS.md.

Signed-off-by: lucarlig <luca.carlig@ibm.com>
@lucarlig
docs(book): correct health endpoint and nginx retry statements
65c474e 
The /health route is a with_tools bootstrap helper served at
/contextforge-rs/health; production builds compile it out and the
reference nginx health location does not match the gateway's route.
State that plainly instead of suggesting /health can back external
checks, note that the bootstrap admin routes bypass the authentication
middleware, and tighten the nginx retry wording: non-idempotent MCP
POSTs are only retried on connection-stage failures.

Signed-off-by: lucarlig <luca.carlig@ibm.com>
@lucarlig
docs(book): document compose CPU overrides in the local run tutorial
7bd94a3 
The sample backend services default to cpus: 8 with a reservation of 4,
so step 1 fails on hosts with fewer CPUs. Document the existing
GATEWAY_CPU_LIMIT / GATEWAY_CPU_RESERVATION overrides. Found by running
the tutorial end to end; the rest of the flow (token mint, config seed,
401 and 404 negatives, initialize, merged prefixed tools/list from both
backends, tools/call, DELETE) verified live as written.

Signed-off-by: lucarlig <luca.carlig@ibm.com>
@lucarlig
docs(book): fix stale gateway behavior notes
73f4e23 
Signed-off-by: lucarlig <luca.carlig@ibm.com>
@lucarlig
docs(book): sync completion and JWT behavior
5ecfe33 
Signed-off-by: lucarlig <luca.carlig@ibm.com>
@lucarlig
lucarlig force-pushed the user/luca/gateway-book branch from e6d8889 to 5ecfe33 Compare July 13, 2026 13:23
@dawid-nowak
dawid-nowak merged commit 90b263a into main Jul 13, 2026
15 of 16 checks passed
@lucarlig lucarlig self-assigned this Jul 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer
@dawid-nowak dawid-nowak dawid-nowak approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

@lucarlig lucarlig

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@lucarlig @dawid-nowak