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

Review limit reached

@ankurs, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 57 minutes and 48 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, 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 include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2b2ac24c-a2ea-4230-b223-98f9c2b576cc

📥 Commits

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

📒 Files selected for processing (9)

• config-reference.md
• howto/cache.md
• howto/database.md
• howto/gateway-extensions.md
• howto/index.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.

[ankurs]

Fixed in fc41c0d: the SSE bullet now explicitly notes that browser EventSource only works for endpoints exposed via HTTP GET, and points POST-mapped streams at fetch + microsoft/fetch-event-source (the wire format is identical either way).

[ankurs]

Fixed in fc41c0d. The intro now says "any rpc Foo(Req) returns (stream Resp) endpoint is SSE-consumable when the client sends Accept: text/event-stream" (without the EventSource framing) and adds a separate paragraph explaining that EventSource itself is GET-only, with the fetch / fetch-event-source workaround for POST-mapped streams. The duplicate caveat in the Browser EventSource section is tightened to a single back-reference.

[ankurs]

Skipping in this PR — the inconsistency is at the env-var level in core: DISABLE_SSE_MARSHALER uses single-l (matches the Go type SSEMarshaler), while USE_JSON_BUILTIN_MARSHALLER uses double-l. My row matches its env var; the existing rows match theirs. Editing the docs to use one spelling everywhere would misrepresent the actual variable name. The right fix is to standardize the env-var spelling in core in a separate change (it would be a breaking env-var rename, so worth its own discussion).

[ankurs]

Fixed in fc41c0d — added a row to howto/index.md under Build: "Stream tokens to the browser (AI/LLM, progress feeds) → Server-Sent Events", next to the Streaming RPCs entry.

[ankurs]

Fixed in fc41c0d.