[FumingPower3925]

Second batch of the symbol-citation change: routing helpers, data stores, performance, deployment and graceful shutdown. Draft. Stacked on the first batch (#104, the base of this PR); PR 3 is stacked on this one.

#N in this body means goceleris/celeris#N, except where it says goceleris/docs. The items are the checklist items of goceleris/celeris#891 numbered as in the DOCSSITE PR (items 8 and 10). The checklist issue stays open and its boxes are not ticked here.

What changed

• Item 8 (symbol citations). middleware-routing-helpers.md (37 locators), data-stores.md (37), performance.md (36), deployment.md (34) and graceful-shutdown.md (4) cite celeris/<path>.go (Symbol) in place of path.go:N[-M]. That is 148 locators. With PR 1 (165), 313 of the 515 locators are done; 202 remain on 12 pages (PR 3).
• Item 8, the checklist examples, measured at goceleris/docs 7ecb763 (after docs: shutdown, deployment, getting-started, error-handling and data-stores match v1.6.0 #102):
  • deployment.md:504 (celeris/server.go:1035-1066, the listener-ownership sentence) now cites celeris/server.go (Server.StartWithListener).
  • deployment.md:600 (celeris/server.go:1148-1166, celeris/server.go:1035-1066) now cites celeris/server.go (InheritListener) and celeris/server.go (Server.StartWithListener), the two names the paragraph uses.
  • graceful-shutdown.md: the checklist's resource/config.go:152-161 ("now elsewhere") is already gone at 7ecb763. docs: shutdown, deployment, getting-started, error-handling and data-stores match v1.6.0 #102 moved that sentence to celeris/internal/resource/config.go:210-224, and 152-161 appears nowhere under src/content/docs. This batch cites that sentence as Config.Validate. Evidence: the quoted "ambiguous configuration" error is at internal/resource/config.go:246 on celeris origin/main, inside Config.Validate (173-253 there). The listener-ownership section was already symbolic at 7ecb763 (prepareWithListener already present, no locator), so this batch does not touch it.
  • Lines this batch changes in graceful-shutdown.md (the four remaining locators): session.go:319,395 (Handler.Close, NewWithCloser), errors.go:29-31 (ErrAcceptControlNotSupported), internal/engine/engine.go:38-62 (AcceptController), and resource/config.go:210-224 (Config.Validate).
• Item 8, the #747 sentence (deployment.md, after the ownership sentence). A start that fails before its engine runs (a configuration error, or an engine that cannot be created) releases the handed listener when it returns the error, so the caller has nothing to release. ErrAlreadyStarted is the exception: the server is already running and the listener stays with the caller. Checked on celeris origin/main: the doc comment of StartWithListener says this, and start_failure_release_test.go (TestFailedStartClosesTheSuppliedListener) pins it. The sentence links celeris issue #737 and the change PR #747 (see Review round 1: graceful-shutdown.md now links both as well).
• Item 10 (prefix). Bare citations in these pages get celeris/ and the repository path: data-stores.md (37 bare), performance.md (2), deployment.md (2). Each bare name is resolved from its own sentence, not from the root package: in deployment.md, config.go:10-15 is celeris/middleware/healthcheck/config.go (DefaultStartPath) and config.go:69-75 is celeris/middleware/healthcheck/config.go (FastPathTimeout); in performance.md, config.go:48-55 is celeris/middleware/overload/config.go (Thresholds). Bare server.go and router.go in data-stores.md are the root files.
• Test (scripts/docs-symbol-citations.test.ts). The allowlist drops these five pages. The continuation check now also catches comma lists (x.go:1-2,3-4, x.go:1-2, 3-4) and a range wrapped onto the next line.

Special cases handled by hand

• data-stores.md:150 and :151 (middleware/session/config.go:63-66,205-206 and middleware/cache/config.go:12-13,107-108): comma lists, two symbols each.
• data-stores.md:173: the locator is inside a Go code block, without backticks ("(middleware/idempotency/config.go:15-18)" in a comment). It is written as "(celeris/middleware/idempotency/config.go, KVStore)", because backticks would print literally in the code block.
• deployment.md:204 (proxy.go:97-117, 215-226), deployment.md:254 (healthcheck.go:13-16, wrapped onto the next line as 163-174) and graceful-shutdown.md:445 (session.go:319,395): two symbols each; the wrapped one is one citation now.
• performance.md:688: the same symbol twice in one parenthesis, collapsed to one.

Checks run in the first version (head b63329f, tree as a9b4afc; current head under Review round 1)

• Ratchet: bun test scripts/docs-symbol-citations.test.ts passes (3 tests). Control, run on the batch before the last two corrections: one `celeris/middleware/proxy/proxy.go:97-117, 215-226` line appended to deployment.md makes the offender and continuation tests fail; restored and passing again.
• Every citation on the docs tree: work/verify_all.py parses each `celeris/<path>.go` (`Sym`, ...) group and checks the path exists on celeris origin/main and each symbol is declared there (a method name matches Type.Name or Name). Output in work/verify-all-pr2.log: 323 citations, 0 bad.
• CI steps from ci.yml on a9b4afc, run from the lane: bun run validate, bun run build, bun run check, bun test, all exit 0 (logs work/ci-*-pr2.log). bun test ran 25 tests across 2 files.
• Stale restatements: the grep in the first PR found none; this batch adds no new line-number text.

Review round 1 (head 8167681)

Refs #891 item 8. This branch is rebased onto the new head of #104 (cb88174), which carries the widened ratchet (detector shapes and failing-first evidence are in the body of #104).

• Orphan fragments. None of this batch's five pages held one: the reviewer's grep (work/r1/reviewer-grep-5a27611.log) has no hit in them, and the widened detector passes on this tree.
• Mislabeled citations. The strict control described in docs: cite celeris symbols, not line numbers (configuration, middleware-traffic, websocket) #104 (work/r1/strict.log) flagged no row in this batch's pages that needed a different symbol, with one widening: performance.md:84 cited jsonSafeValue for a range that also holds Context.JSON; it now names both. The five continuation ranges of these pages (205-206, 107-108, 215-226, 163-174, session.go:319,395) were re-resolved at their introducing revisions (work/r1/contranges2.log) and agree with the symbols cited.
• Prefix (item 10). Path-only mentions in data-stores.md and performance.md that had no .go:N locator now carry the celeris/ prefix and the full path: middleware/store/kv.go, middleware/session/session.go, driver/redis/options.go, driver/redis/commands.go, driver/postgres/pool.go and the overload config.go. The ratchet's prefix guard (PR 3) flags dir/x.go and (x.go). It does not flag a bare backticked file name such as `config.go`, so the claim is that the two shapes it checks are clean, not that every mention is guarded.
• Issue and PR link. deployment.md linked celeris#747 (the change) and graceful-shutdown.md linked #737 (the issue). Both pages now link the issue (#737) and the change (PR #747), so the earlier statement in this body that graceful-shutdown.md is unchanged for that sentence no longer holds.

Checks on head 8167681 (work/r1/): bun run validate, bun run build, bun run check and bun test exit 0 (ci-*-pr2-8167681.log; 27 tests across 2 files); verify_all.py 342 symbol citations, 0 bad (verify-all-pr2-8167681.log).

Neighbours changed in the same paragraphs

• deployment.md: the StartWithListener paragraph gets the #747 sentence. The sentence before it (the one about not accepting on the passed listener) is unchanged; the new sentence names the one exception.
• performance.md: the two citations of Server.doPrepare in one parenthesis are one citation.

Review round 2 (head 10ed9f5)

Refs #891 item 8. Plain merge of #104's head 20380a0 into this branch (no force-push), then:

• Minor. data-stores.md:55 cited Counter for the optional capability interfaces; the sentence covers six interfaces and Counter is the last, so the first named, GetAndDeleter, is cited. data-stores.md:334 now names Connector.WithEngine as well as NewConnector (the sentence rebinds the Connector with WithEngine, then sql.OpenDB).
• Sentence-level pass over the rows of this PR's pages (the full pass is described in the body of docs: cite celeris symbols, not line numbers (configuration, middleware-traffic, websocket) #104).

Checks on head 10ed9f5: validate, build, check, test all exit 0 (logs ci-*-pr2.log in the lane).

Open points (not blocking)

• Quoted literals: 46 quoted error or prose strings in the pages were git-grepped on celeris origin/main and their enclosing declaration compared with the new citation (work/literals.json). Matches include memoryLimitBytes must be >= 0 (Config.Validate), ambiguous configuration (Config.Validate), websocket: origin not allowed (New), and engine epoll requires Linux (inside Config.Validate, internal/resource/config.go:229). The 33 with no hit are signatures and code samples, not literals. This is a sample, not a full check of every sentence; the introducing-commit check was done in Review round 1 (see the PR body of docs: cite celeris symbols, not line numbers (configuration, middleware-traffic, websocket) #104).
• Symbol choice works as in PR 1: the declaration covering the cited range at the revision the line was blamed to. The verify step checks that each symbol exists in its file on celeris origin/main, not that it is the right one.
• Some symbols are prose-kept (for example "(WithDefaults)" in PR 1 and "Shutdown", "Start" in this batch): the path is replaced and the existing name is kept. These are methods on the named type; the verify step matches them by method name.
• Not run: nothing Linux, amd64 or cluster related applies to a docs-only change.

Refs #891 item 8
Refs #891 item 10

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	goceleris-docs	dd222f8	Commit Preview URL Branch Preview URL	Oct 19 2026, 11:07 AM

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 56 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: goceleris/docs/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: e3e4fd01-b57b-4961-9afd-d8dc37435f98

📥 Commits

Reviewing files that changed from the base of the PR and between 0f6dc3b and dd222f8.

📒 Files selected for processing: 6

• scripts/docs-symbol-citations.test.ts
• src/content/docs/data-stores.md
• src/content/docs/deployment.md
• src/content/docs/graceful-shutdown.md
• src/content/docs/middleware-routing-helpers.md
• src/content/docs/performance.md

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}

[FumingPower3925]

Merging with every required check green (build, coverage, CodeQL, codecov/patch, Workers Builds). The CodeRabbit review is advisory and had not finished.