docs: Server-Sent Events how-to + built-in SSE marshaler references

[ankurs]

Summary

Documents the auto-registered SSE marshaler shipped in core#92, which makes every server-streaming gateway RPC browser-EventSource-consumable out of the box.

New page — howto/server-sent-events.md:

• When to reach for SSE vs. native gRPC, WebSocket, or unary.
• Wire format (data: <json>\n\n) + the gateway {"result": ...} wrapping behaviour.
• EventSource and curl examples (covers the GET-only browser API caveat and the microsoft/fetch-event-source workaround for POST streams).
• Handler patterns: context-cancellation propagation into LLM SDKs, TTFT as a distinct metric, per-outcome counters with OutcomeCanceled.
• Opt-out via DISABLE_SSE_MARSHALER=true, plus how to register a custom text/event-stream marshaler that wins over the default.
• Pitfalls — compression, reverse-proxy buffering, mid-stream errors, gateway envelope.

Cross-cutting updates:

• config-reference.md — DISABLE_SSE_MARSHALER row added in the HTTP Gateway section.
• howto/streaming-rpcs.md — gateway-shape table now lists SSE alongside NDJSON; a new bullet calls out the default behaviour and links to the new page; Related section gains the cross-link.
• howto/gateway-extensions.md — built-ins list mentions the auto-registered text/event-stream marshaler and the override path.

Nav + tests:

• nav_order: 22 for server-sent-events.md; database/cache/messaging each bumped by one (now 23/24/25) to keep streaming and SSE adjacent in the sidebar.
• tests/pages.ts updated to match.

Test plan

• cd docs.coldbrew.cloud && bundle exec jekyll serve — verify the new page renders, nav order is correct, internal links resolve.
• npx playwright test against a local Jekyll server — tests/navigation.spec.ts walks every entry in allHowtoPages and asserts a 200 + visible heading on each, so the new page is covered automatically.
• Confirm cross-references render correctly: /howto/streaming-rpcs/ → /howto/server-sent-events/, and vice versa; /howto/gateway-extensions/ and /config-reference/ both link to the new page.

[coderabbitai]

Warning

Rate limit exceeded

@ankurs has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 59 minutes and 22 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ce50d7ee-729a-443e-b966-16c714fecb96

📥 Commits

Reviewing files that changed from the base of the PR and between 141b516 and 0b19a80.

📒 Files selected for processing (8)

• config-reference.md
• howto/cache.md
• howto/database.md
• howto/gateway-extensions.md
• howto/messaging.md
• howto/server-sent-events.md
• howto/streaming-rpcs.md
• tests/pages.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/sse-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Adds documentation for ColdBrew’s built-in Server-Sent Events (SSE) gateway marshaler (Accept-driven text/event-stream), including a new how-to page and cross-references from related docs, plus updates to Playwright’s How To page list and nav ordering.

Changes:

• Add a new howto/server-sent-events.md page covering SSE framing, client examples, operational pitfalls, and customization/opt-out (DISABLE_SSE_MARSHALER).
• Update streaming and gateway-extension docs to mention SSE as a first-class gateway streaming shape and link to the new guide.
• Update config reference and test page lists to include the new page and adjusted How To sidebar ordering.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/pages.ts	Inserts the new SSE how-to page into allHowtoPages in nav order.
howto/streaming-rpcs.md	Documents SSE as an alternative server-streaming HTTP shape and links to the new how-to.
howto/server-sent-events.md	New end-to-end SSE how-to documentation (wire format, clients, ops pitfalls, customization).
howto/messaging.md	Bumps nav_order to keep sidebar ordering consistent after inserting SSE.
howto/gateway-extensions.md	Mentions the built-in SSE marshaler and links to the SSE how-to.
howto/database.md	Bumps nav_order to keep sidebar ordering consistent after inserting SSE.
howto/cache.md	Bumps nav_order to keep sidebar ordering consistent after inserting SSE.
config-reference.md	Adds DISABLE_SSE_MARSHALER to the HTTP Gateway config table.

Comments suppressed due to low confidence (1)

howto/server-sent-events.md:58

• The proto example exposes the stream as post: "/api/v1/stream/tokens", but the immediately-following browser EventSource example calls the same path (and EventSource can only GET). To keep the examples consistent, either add a GET mapping in the proto snippet, or update the browser section to demonstrate a POST-capable SSE client instead of EventSource for this endpoint.

```protobuf
rpc StreamTokens(StreamTokensRequest) returns (stream Token) {
  option (google.api.http) = {
    post: "/api/v1/stream/tokens"
    body: "*"
  };

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.