docs: readiness patterns and workers ColdBrew integration#80
Conversation
…tion - New howto/readiness.md with 4 patterns: simple, PreStart-blocked, worker-managed, dynamic DB-driven - Replace workers.md ColdBrew Integration placeholder with actual content: CBWorkerProvider, lifecycle, delegation pattern, readiness link - Add Playwright tests for readiness page (patterns, table) and workers ColdBrew Integration section - Add readiness to navigation test list
|
Warning Rate limit exceeded
To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the 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 configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (5)
📝 WalkthroughWalkthroughThis PR extends the ColdBrew documentation with new how-to guides on readiness patterns and worker integration, adds troubleshooting sections and cross-reference links throughout the documentation, updates navigation ordering, and expands test coverage to validate the new content. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
There was a problem hiding this comment.
Pull request overview
Adds documentation and test coverage for service readiness approaches and the new/updated Workers ↔ ColdBrew integration guidance.
Changes:
- Introduces a new How-To page describing four readiness patterns and how they relate to workers.
- Replaces the “ColdBrew Integration” placeholder in the workers howto with concrete
CBWorkerProviderusage, lifecycle notes, and a delegation pattern. - Extends Playwright coverage to include the new readiness page and updated workers section, and adds readiness to navigation checks.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| tests/navigation.spec.ts | Adds /howto/readiness/ to the list of how-to pages that must load successfully. |
| tests/content.spec.ts | Adds assertions that the readiness page and the updated workers integration section render expected content. |
| howto/workers.md | Documents ColdBrew lifecycle integration via CBWorkerProvider, including a lifecycle diagram and delegation pattern, with a readiness cross-link. |
| howto/readiness.md | New readiness patterns page with examples and a pattern selection table. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Fix nav_order duplicates (readiness 16→17, local-dev 17→18, auth 18→19) - Add quick reference table to howto/index.md (19 guides mapped to goals) - Add Related sections to production.md, interceptors.md, APIs.md - Add 3 new FAQ entries (streaming, workers, slow gateway) - Expand Playwright link tests from 4 to 9 pages - Add SEO meta description tests for 14 key pages - Add table of contents existence tests for 10 howto pages
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
tests/content.spec.ts (1)
191-204: TOC presence test passes trivially due to.no_tocselector.
.no_tocis the kramdown class applied to the "Table of contents" heading itself (via{: .no_toc .text-delta }) to exclude it from the generated TOC — it is not a class on the TOC list. Every howto page with the standard boilerplate has this heading, sohasTOCis true regardless of whether the{:toc}directive actually rendered any links. The OR withtocLinks.count() > 0then makes the assertion always succeed.Tightening the selector to require actual TOC anchor links (e.g., the
<ul>produced after{:toc}) would catch a regression where someone removes the{:toc}marker but leaves the heading.♻️ Suggested tightening
for (const pagePath of howtoPages) { test(`${pagePath} has table of contents`, async ({ page }) => { await page.goto(pagePath); - const toc = page.locator("#table-of-contents, .no_toc, `#toc`"); - const hasTOC = (await toc.count()) > 0; - // just-the-docs renders TOC as a list with anchor links - const tocLinks = page.locator('nav[aria-label="Table of contents"] a, .no_toc + ol a, .no_toc + ul a'); - expect( - hasTOC || (await tocLinks.count()) > 0, - `${pagePath} missing table of contents` - ).toBeTruthy(); + // kramdown {:toc} renders a <ul>/<ol> immediately after the + // heading marked with {: .no_toc} containing in-page anchor links. + const tocLinks = page.locator('.no_toc + ul a[href^="#"], .no_toc + ol a[href^="#"]'); + expect( + await tocLinks.count(), + `${pagePath} missing table of contents` + ).toBeGreaterThan(0); }); }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tests/content.spec.ts` around lines 191 - 204, The current TOC test in the howtoPages loop (`test(\`${pagePath} has table of contents\`)`) falsely passes because the `toc` locator includes the `.no_toc` heading; update the locators so the assertion requires actual TOC links/lists rather than the heading: remove `.no_toc` from the `toc` selector and change the check to assert that a TOC list or anchor links exist (e.g., look for `#table-of-contents`, `#toc`, `nav[aria-label="Table of contents"]`, or an adjacent `<ul>`/`<ol>` with `a` children) by relying on `tocLinks.count() > 0` or verifying the list element exists, replacing the current `hasTOC || (await tocLinks.count()) > 0` logic in the test that defines `toc` and `tocLinks`.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@FAQ.md`:
- Around line 244-245: The FAQ line incorrectly states that grpc-gateway "does
not support streaming"; update the text to say grpc-gateway v2 does support
server-, client- and bidi-streaming by translating gRPC streams to HTTP
newline-delimited JSON streams, and add brief notes about practical constraints:
proxy buffering may require configuration, use runtime.WithStreamErrorHandler
for correct error propagation, and note grpc-gateway cannot provide arbitrary
concurrent interleaving like WebSockets—refer readers to the official
grpc-gateway streaming examples for implementation details and configuration
guidance.
In `@howto/readiness.md`:
- Around line 172-173: The Pattern 4 example incorrectly treats
info.GetChild(cfg.Name) as nullable; fix the existence check to use the
two-value return (Worker, bool) from GetChild by capturing the boolean (e.g., _,
ok := info.GetChild(cfg.Name)) and then testing if !ok before calling
info.Add(...) so the example compiles and correctly checks for presence.
---
Nitpick comments:
In `@tests/content.spec.ts`:
- Around line 191-204: The current TOC test in the howtoPages loop
(`test(\`${pagePath} has table of contents\`)`) falsely passes because the `toc`
locator includes the `.no_toc` heading; update the locators so the assertion
requires actual TOC links/lists rather than the heading: remove `.no_toc` from
the `toc` selector and change the check to assert that a TOC list or anchor
links exist (e.g., look for `#table-of-contents`, `#toc`, `nav[aria-label="Table
of contents"]`, or an adjacent `<ul>`/`<ol>` with `a` children) by relying on
`tocLinks.count() > 0` or verifying the list element exists, replacing the
current `hasTOC || (await tocLinks.count()) > 0` logic in the test that defines
`toc` and `tocLinks`.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 6536f139-3227-4035-a7ae-eca30a2b14ed
📒 Files selected for processing (12)
FAQ.mdhowto/APIs.mdhowto/auth.mdhowto/index.mdhowto/interceptors.mdhowto/local-dev.mdhowto/production.mdhowto/readiness.mdhowto/workers.mdtests/content.spec.tstests/links.spec.tstests/navigation.spec.ts
- Fix GetChild API usage in Pattern 4 to use (Worker, bool) return - Fix Pattern 3 type assertions to use *svc instead of *cbSvc - Replace SetDefaultTimeout example with auth.Setup + note about env vars - Correct FAQ streaming entry — grpc-gateway v2 supports streaming via newline-delimited JSON with practical constraints - Update signals.md shutdown sequence with PreStop/PostStop hooks and worker shutdown step
There was a problem hiding this comment.
Pull request overview
Adds and cross-links new operational documentation around readiness and background workers in ColdBrew, and extends Playwright coverage to ensure the new/updated pages render and internal navigation remains healthy.
Changes:
- Added a new
howto/readiness.mdguide describing four readiness patterns and how they relate to workers and lifecycle hooks. - Replaced the “ColdBrew Integration” placeholder in
howto/workers.mdwith concreteCBWorkerProviderintegration guidance (lifecycle + delegation pattern) and added related-links sections across multiple docs. - Expanded Playwright coverage (navigation, internal link crawl targets, and content assertions) to include the new readiness doc and updated workers content.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/navigation.spec.ts | Adds /howto/readiness/ to the set of How-To pages that must load successfully. |
| tests/links.spec.ts | Expands internal-link crawling to cover more key docs pages including readiness/workers/production. |
| tests/content.spec.ts | Adds content assertions for readiness patterns and workers integration section; adds readiness to SEO/TOC checks. |
| howto/workers.md | Documents CBWorkerProvider usage, lifecycle ordering, delegation pattern, and readiness cross-link. |
| howto/signals.md | Updates shutdown sequence + lifecycle interface table to include PreStop/PostStop and worker shutdown. |
| howto/readiness.md | New readiness patterns guide (simple, PreStart blocking, worker-managed readiness, dynamic workers). |
| howto/production.md | Adds “Related” links pointing to readiness, interceptors, signals, and workers docs. |
| howto/local-dev.md | Adjusts nav order to make space for the new readiness page in the How-To sidebar. |
| howto/interceptors.md | Adds a “Related” section linking to adjacent operational/howto topics. |
| howto/index.md | Replaces intro text with a “I want to…” table linking to key How-To guides including readiness. |
| howto/auth.md | Adjusts nav order due to the insertion of readiness into the How-To nav. |
| howto/APIs.md | Adds a “Related” section linking to adjacent howtos. |
| FAQ.md | Adds FAQ entries covering streaming RPCs, background workers via CBWorkerProvider, and gateway performance troubleshooting. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Fix signals.md step numbering (1-8 → 1-11, step 2 → step 3)
- Reword callout to mention PreStop/PostStop alongside Stop
- Fix readiness Pattern 1 wording ("after InitGRPC" → "during initialization")
There was a problem hiding this comment.
Pull request overview
Adds a new “Readiness Patterns” guide and replaces the “ColdBrew Integration” placeholder in the Workers how-to with concrete lifecycle + delegation documentation, then updates Playwright coverage to validate the new/updated docs pages and navigation.
Changes:
- Introduce
howto/readiness.mddescribing four readiness patterns and how they relate to workers and lifecycle hooks. - Expand
howto/workers.mdwithCBWorkerProviderintegration guidance (examples, lifecycle diagram, delegation pattern) and cross-links to readiness. - Update/extend Playwright navigation, internal-link crawling targets, and content assertions for the new/updated pages.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/navigation.spec.ts | Adds /howto/readiness/ to the navigation smoke list. |
| tests/links.spec.ts | Expands internal-link crawl coverage to include readiness/workers/production and more key pages. |
| tests/content.spec.ts | Adds assertions for readiness patterns content and workers integration section; includes readiness in SEO/TOC checks. |
| howto/workers.md | Replaces placeholder “ColdBrew Integration” with real CBWorkerProvider docs, lifecycle diagram, and delegation guidance. |
| howto/signals.md | Updates shutdown sequence and lifecycle hook interface table to include PreStop/PostStop and worker stop ordering. |
| howto/readiness.md | New page documenting four readiness patterns and related links. |
| howto/production.md | Adds a “Related” section linking to readiness/workers/signals/interceptors. |
| howto/local-dev.md | Adjusts nav_order to make room for the new readiness page. |
| howto/interceptors.md | Adds a “Related” section to improve cross-navigation. |
| howto/index.md | Replaces generic intro with a “I want to…” table including readiness and other how-tos. |
| howto/auth.md | Adjusts nav_order to preserve sidebar ordering after inserting readiness. |
| howto/APIs.md | Adds a “Related” section for discoverability of adjacent topics. |
| FAQ.md | Adds FAQ entries for gRPC streaming and background workers; links out to workers/readiness docs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Add CBPreStarter and CBPostStarter to signals.md lifecycle table - Clarify FAQ streaming: server streaming works well, bidi is limited
There was a problem hiding this comment.
Pull request overview
Adds documentation and test coverage for ColdBrew readiness patterns and the workers lifecycle integration, improving cross-linking and navigation across the How-To section.
Changes:
- Added new
howto/readiness.mddescribing four readiness patterns and a “Choosing a Pattern” table. - Replaced the “ColdBrew Integration” placeholder in
howto/workers.mdwithCBWorkerProviderguidance, lifecycle notes, and readiness linkage. - Expanded Playwright coverage and navigation/link crawling to include the new readiness content and updated related pages.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/navigation.spec.ts | Adds /howto/readiness/ to the list of How-To pages that must load successfully. |
| tests/links.spec.ts | Expands internal-link crawling to include readiness/workers/production and key reference pages. |
| tests/content.spec.ts | Adds assertions for readiness patterns, the choosing-a-pattern table, and the workers integration section; includes readiness in SEO + TOC checks. |
| howto/workers.md | Documents CBWorkerProvider integration, lifecycle ordering, delegation pattern, and readiness cross-link. |
| howto/signals.md | Updates shutdown sequence and lifecycle hook interface documentation to align with worker lifecycle integration. |
| howto/readiness.md | New page documenting readiness patterns and how they relate to workers + lifecycle hooks. |
| howto/production.md | Adds “Related” section linking to readiness, interceptors, signals, and workers. |
| howto/local-dev.md | Bumps nav_order to make room for the new readiness page in navigation ordering. |
| howto/interceptors.md | Adds “Related” links section for improved doc navigation. |
| howto/index.md | Replaces the brief intro with a task→guide table, including readiness as a first-class topic. |
| howto/auth.md | Bumps nav_order to preserve intended sidebar ordering after inserting readiness. |
| howto/APIs.md | Adds a “Related” section to connect readers to adjacent how-tos. |
| FAQ.md | Adds FAQ entries for gRPC streaming, background workers (CBWorkerProvider), and gateway performance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| --- | ||
|
|
||
| [TraceId interceptor]: https://pkg.go.dev/github.com/go-coldbrew/interceptors#TraceIdInterceptor | ||
| [go-coldbrew/tracing]: https://pkg.go.dev/github.com/go-coldbrew/tracing | ||
| ## Related | ||
|
|
||
| - [Production](/howto/production) — rate limiting, TLS, security hardening for deployment | ||
| - [Debugging](/howto/Debugging) — per-request debug logging via DebugLogInterceptor | ||
| - [Tracing](/howto/Tracing) — distributed tracing with OpenTelemetry | ||
| - [Architecture](/architecture) — full interceptor chain diagram and request lifecycle |
There was a problem hiding this comment.
Fixed — moved Related section before the reference link definitions.
| go workers.Run(ctx, []*workers.Worker{ | ||
| workers.NewWorker("cleanup").HandlerFunc(s.cleanup).Every(5 * time.Minute), | ||
| }) |
There was a problem hiding this comment.
Fixed — wrapped in goroutine with error handling and slog.Error.
There was a problem hiding this comment.
Pull request overview
Adds first-class documentation for service readiness patterns and integrates workers lifecycle/readiness guidance across the ColdBrew docs, with Playwright coverage to keep navigation/content/link integrity intact.
Changes:
- Introduces a new How-To page documenting four readiness implementation patterns.
- Replaces the “ColdBrew Integration” placeholder in the Workers How-To with concrete
CBWorkerProviderlifecycle and delegation guidance (plus readiness cross-linking). - Expands Playwright navigation/content/link checks to cover the new readiness page and updated related sections.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/navigation.spec.ts | Adds /howto/readiness/ to the How-To navigation smoke test list. |
| tests/links.spec.ts | Crawls additional key pages (incl. readiness/workers/production/config/architecture) for internal link validity. |
| tests/content.spec.ts | Adds assertions for readiness patterns content, the choosing-a-pattern table, and the updated Workers integration section; includes readiness in SEO + TOC checks. |
| howto/workers.md | Documents CBWorkerProvider usage, lifecycle ordering, delegation pattern, and readiness linkage (replacing placeholder). |
| howto/signals.md | Updates shutdown sequence and lifecycle hook interface table to include PreStop/PostStop and worker shutdown ordering. |
| howto/readiness.md | New guide describing four readiness patterns plus a selection table and related links. |
| howto/production.md | Adds “Related” links including readiness/workers/signals/interceptors. |
| howto/local-dev.md | Bumps nav_order to make room for the new readiness page. |
| howto/interceptors.md | Adds “Related” links for operational cross-navigation. |
| howto/index.md | Replaces the generic intro with a topic table that links to key How-To guides including readiness. |
| howto/auth.md | Bumps nav_order to accommodate readiness insertion. |
| howto/APIs.md | Adds a “Related” section to guide readers to adjacent How-Tos. |
| FAQ.md | Adds guidance on gRPC streaming and background workers + readiness cross-links, plus HTTP gateway troubleshooting. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Move Related section before reference links in interceptors.md - Handle workers.Run() error in example, use consistent callable form - Close db on ping failure in readiness Pattern 2 example
Summary
howto/readiness.mdpage with 4 readiness patterns:howto/workers.md— replaced "ColdBrew Integration" placeholder with: CBWorkerProvider usage, lifecycle diagram, delegation pattern, readiness cross-linkDepends on
Test plan
npx playwright testpasses (requires local Jekyll server)Summary by CodeRabbit
Documentation
CBWorkerProvider), and HTTP gateway performance troubleshooting.Tests