Skip to content

Add user guide and adoption-helpful README signposts#48

Merged
iainmcgin merged 1 commit intomainfrom
feat/user-guide-and-readme
Apr 5, 2026
Merged

Add user guide and adoption-helpful README signposts#48
iainmcgin merged 1 commit intomainfrom
feat/user-guide-and-readme

Conversation

@iainmcgin
Copy link
Copy Markdown
Collaborator

@iainmcgin iainmcgin commented Apr 3, 2026

Closes #47

Adds `docs/guide.md` as the long-form companion to the crate README, plus README updates that surface the guide and the examples directory near the top.

Stacked on #46 - this PR's base is `feat/examples-streaming-middleware` because the guide and README reference `examples/streaming-tour/` and `examples/middleware/` from #46. Once #46 merges, GitHub will rebase this onto main automatically (or I'll do it manually).

docs/guide.md

801 lines covering:

Section What it covers
Installation Crates, MSRV (1.88), feature flags, common combinations
Quick start One runnable unary example end-to-end
Code generation Both build paths (`connectrpc-build` for build-time, `buf generate` for checked-in code)
Implementing servers Handler signatures, the `Context` parameter (headers/trailers/extensions/deadline/compression), `ConnectError` returns, `Router` composition
Streaming RPCs Server / client / bidi handler signatures with snippets, plus client-side calling patterns
Tower middleware `ServiceBuilder` composition mounted on `axum::Router::layer()`, identity passthrough from layer extensions to `Context::extensions`, short-circuit responses
Hosting axum (recommended), standalone `Server`, TLS for both
Clients `HttpClient` plaintext + TLS, `ClientConfig` defaults, `CallOptions` per-call overrides, three response access patterns (`view()`, `into_view()`, `into_owned()`), custom transports
Errors and status codes `ConnectError` shape, `ErrorCode` set, automatic protocol-specific serialization
Compression Per-RPC override via `Context::set_compression`, custom `CompressionProvider` registration
Examples directory tour One-line summary of every example crate

The guide references the streaming-tour and middleware examples (PR #46) for runnable patterns rather than duplicating handler code inline. Each section is self-contained enough to land via search or external link.

README updates

  • New Status / MSRV / Documentation block right after the tagline, with pointers to the guide, examples directory, and docs.rs.
  • New Streaming, middleware, TLS subsection at the end of Quick Start with focused links into specific guide sections and example crates.

19 line diff to README; everything else stays as it was.

Merge dependencies

@iainmcgin iainmcgin force-pushed the feat/user-guide-and-readme branch from 114a004 to c3014b4 Compare April 3, 2026 19:04
@iainmcgin iainmcgin changed the base branch from main to feat/examples-streaming-middleware April 3, 2026 19:04
@iainmcgin iainmcgin force-pushed the feat/examples-streaming-middleware branch from ffe56f7 to 69bea69 Compare April 3, 2026 19:29
@iainmcgin iainmcgin force-pushed the feat/user-guide-and-readme branch from c3014b4 to d980e7d Compare April 3, 2026 19:29
@iainmcgin iainmcgin force-pushed the feat/examples-streaming-middleware branch from 69bea69 to 1dff769 Compare April 3, 2026 19:33
@iainmcgin iainmcgin force-pushed the feat/user-guide-and-readme branch from d980e7d to 8cee641 Compare April 3, 2026 19:34
@iainmcgin iainmcgin force-pushed the feat/examples-streaming-middleware branch from 1dff769 to 7095451 Compare April 3, 2026 20:17
@iainmcgin iainmcgin force-pushed the feat/user-guide-and-readme branch from 8cee641 to 968ed2b Compare April 3, 2026 20:18
@iainmcgin iainmcgin force-pushed the feat/examples-streaming-middleware branch from 7095451 to 484cf3a Compare April 3, 2026 20:28
@iainmcgin iainmcgin force-pushed the feat/user-guide-and-readme branch from 968ed2b to c8e2172 Compare April 3, 2026 20:28
@iainmcgin iainmcgin force-pushed the feat/examples-streaming-middleware branch from 484cf3a to b2b499e Compare April 3, 2026 20:31
@iainmcgin iainmcgin force-pushed the feat/user-guide-and-readme branch from c8e2172 to 4a94693 Compare April 3, 2026 20:32
@iainmcgin iainmcgin force-pushed the feat/examples-streaming-middleware branch from b2b499e to a2c412a Compare April 3, 2026 20:35
@iainmcgin iainmcgin force-pushed the feat/user-guide-and-readme branch 3 times, most recently from 20b1678 to 86022da Compare April 3, 2026 20:53
@iainmcgin iainmcgin changed the base branch from feat/examples-streaming-middleware to main April 3, 2026 20:53
@iainmcgin iainmcgin force-pushed the feat/user-guide-and-readme branch from 86022da to 242d01c Compare April 3, 2026 20:54
docs/guide.md is the long-form companion to the crate README, covering
installation, code generation, server and client usage, streaming, tower
middleware, hosting, TLS, errors, and compression. The guide references
the streaming-tour and middleware examples as canonical patterns and
delegates protocol-specific detail to the existing examples READMEs.

README updates:
- Adds a Status / MSRV / Documentation block near the top, pointing
  readers at the guide, examples directory, and docs.rs.
- Adds a Streaming, middleware, TLS subsection at the end of Quick
  Start with focused links into the guide and examples for each.
@iainmcgin iainmcgin force-pushed the feat/user-guide-and-readme branch from 242d01c to 4788a7f Compare April 3, 2026 20:58
@iainmcgin iainmcgin marked this pull request as ready for review April 3, 2026 21:01
@iainmcgin iainmcgin requested a review from asacamano April 3, 2026 21:01
@iainmcgin iainmcgin enabled auto-merge (squash) April 3, 2026 21:12
Copy link
Copy Markdown

@asacamano asacamano left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is so awesome! Just reading over it I was think "yes, this is exactly what it should be like."

@iainmcgin iainmcgin merged commit ffdd1fe into main Apr 5, 2026
12 checks passed
@github-actions github-actions bot locked and limited conversation to collaborators Apr 5, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add user guide and adoption-helpful README signposts

2 participants