docs: improvements

[pi0x]

Docs scope of the v1 stabilization plan. Every technical claim was verified against the code. Does not touch trustProxy docs (PR #229), the ### error / gracefulShutdown rewrites (PR #230), @experimental code removals (PR #230), or 9.aws-lambda.md (AWS agent, F23).

T1 — docs promising APIs that don't exist

• F54 (delete): removed the server.addr and server.port sections from 3.server.md (neither exists; only server.url) plus the stale #port-required anchor.

T2 — wrong / missing docs

• F54 wrong docs: 2.handler.md req.path → req.url; 3.server.md "underlying Bun server instance when running in Deno" → Deno; 5.options.md maxHeadersize → maxHeaderSize.
• F54 missing options: documented manual, middleware, plugins, serviceWorker in 5.options.md (left error/gracefulShutdown to feat: v1 api freeze #230).
• F54 subpaths: table for srvx/static, srvx/log, srvx/loader, srvx/cli, srvx/generic, srvx/service-worker.
• F14: documented hostname ← HOST and silent ← TEST env defaults; fixed the types.ts "server with listen" JSDoc typo.
• Support matrix: close(true) ignored on Deno, trustProxy adapter scope, maxRequestBodySize (Bun 128 MiB / dropped in loader mode — F57), manual no-op on module workers, Cloudflare env only in module syntax (F29), and no upgrade/WebSocket on any runtime → crossws (locked).
• srvx/static is Node-API-only (node:fs/node:zlib) — noted in 10.cli.md and the subpaths table.
• Deno range: documented Deno 2.x (CI 2.7.x) and the mandatory explicit srvx/bunny import (root resolves the deno condition).

T3

• F53 (D7): _request / _url documented as supported API frozen at v1 (underscore is legacy naming).
• F11 (D5): toFetchHandler / fetchNodeHandler documented stable; srvx/tracing documented experimental — plus a new Semver policy section (also states F55: ERR_BODY_TOO_LARGE is the only guaranteed error code).
• F56: per-runtime @types packages (@types/bun, @types/deno, @cloudflare/workers-types, @types/aws-lambda) documented for full typing of options.bun/runtime.cloudflare/etc.
• CLI: srvx fetch non-2xx → exit 22 documented prominently (diverges from curl). usage.ts fixes: env wording "default" not "override", document --hostname, fetch --host/--tls, --method (+--request alias), exit-22 line; 10.cli.md precedence (flag > module > env > default) and Deno --import drop.
• Skipped tests: opened tracking issues for the three known protocol-test skips and linked each in a comment: test: enable "response stream error" test under HTTP/2 (TLS) #235 (HTTP/2 response stream error), test: enforce/verify "absolute path in request line" under HTTP/2 (TLS) #236 (HTTP/2 absolute path in request line), test: run HTTP/2 test suite on Deno and Bun #237 (Deno/Bun HTTP/2 suite).

Verification

pnpm lint:fix (automd regenerated the CLI usage block), pnpm typecheck, and the common + CLI vitest suites all pass (914 passed / 32 pre-existing skips). Deno/Bun-only suites not run locally (no runtimes installed; CI covers them).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Expanded CLI guidance for option precedence, exit codes, runtime behavior, static files, and programmatic server loading.
  • Clarified host defaults, service worker settings, middleware and plugin behavior, runtime support, and stable APIs.
  • Improved Node.js request examples and server property references.
  • Added details on built-in logging, static serving, mutual TLS, and tracing features.
• User Experience
  • Updated CLI help to document host aliases, fetch methods, TLS/host flags, and non-2xx exit behavior.

[coderabbitai]

Warning

Review limit reached

@pi0x, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 41 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

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.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bf44ce2f-cc86-4077-b838-0bddfe25235b

📥 Commits

Reviewing files that changed from the base of the PR and between 208a29b and ff86817.

📒 Files selected for processing (4)

• docs/1.guide/10.cli.md
• docs/1.guide/3.server.md
• docs/1.guide/4.middleware.md
• docs/1.guide/8.node.md

📝 Walkthrough

Walkthrough

The CLI help text and guides were updated to document current fetch, host, static-serving, loader, middleware, adapter, runtime, and API behavior. Documentation corrections also clarify public Node APIs, server properties, runtime examples, semver guarantees, and tracked HTTP/2/TLS test gaps.

Changes

CLI and server-entry loading

Layer / File(s)	Summary
CLI usage and fetch behavior src/cli/usage.ts, docs/1.guide/10.cli.md	Help output documents revised serve and fetch options, schemeless host/TLS flags, environment defaults, and non-2xx exit code 22.
Loader and static-serving guide docs/1.guide/10.cli.md	The guide documents host/port precedence, static asset resolution and protections, loadServerEntry, handler discovery, listen interception, reloading, result shapes, and TypeScript runtime constraints.
Hostname option documentation src/types.ts, docs/1.guide/5.options.md	Hostname behavior now documents HOST fallback and all-interface binding when no hostname is configured.

Middleware and adapter options

Layer / File(s)	Summary
Middleware and plugin execution docs/1.guide/4.middleware.md, docs/1.guide/5.options.md	Middleware wrapping, short-circuiting, plugin ordering, manual startup, and synchronous plugin registration are documented.
Built-in extensions and adapters docs/1.guide/4.middleware.md, docs/1.guide/5.options.md	Logging, static files, mutual TLS, tracing, Service Worker configuration, and per-runtime support are documented.

Runtime APIs and documentation corrections

Layer / File(s)	Summary
Node and server API references docs/1.guide/2.handler.md, docs/1.guide/3.server.md, docs/1.guide/8.node.md	Node request URL access, server property descriptions, public underscored request fields, stable utilities, and tracing’s experimental status are clarified.
HTTP/2 and TLS coverage references test/_tests.ts, test/node.test.ts	Existing TODO and skip comments now reference the corresponding tracked issues.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• h3js/srvx issue 237 — The test comment update references the HTTP/2 skip tracked by this issue.

Possibly related PRs

• h3js/srvx#175 — Both changes update CLI usage generation in src/cli/usage.ts.

Suggested reviewers: pi0

Poem

I’m a rabbit with docs in my paws,
Hopping through loaders and CLI laws.
Middleware twirls, static files bloom,
Runtime notes make errors less gloom.
“Hop hop!” says the guide, clear and bright—
New options are tucked in just right.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title is too generic and does not convey the main documentation changes in this PR.	Use a specific title that mentions the primary update, such as CLI and API documentation improvements for v1 stabilization.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/v1-stabilization

---

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

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/srvx@238

commit: ff86817

[pi0x]

.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/1.guide/10.cli.md`:
- Around line 139-145: Update the loadServerEntry example to handle both missing
entries and entries whose fetch handler is undefined. Add a guard for
loaded.fetch before calling serve, or change the example to use a server entry
guaranteed to export a supported handler, and remove the non-null assertion from
serve.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d500ea0c-d5aa-470c-83c8-edf3f0141c1d

📥 Commits

Reviewing files that changed from the base of the PR and between d8523dc and 208a29b.

📒 Files selected for processing (10)

• docs/1.guide/10.cli.md
• docs/1.guide/2.handler.md
• docs/1.guide/3.server.md
• docs/1.guide/4.middleware.md
• docs/1.guide/5.options.md
• docs/1.guide/8.node.md
• src/cli/usage.ts
• src/types.ts
• test/_tests.ts
• test/node.test.ts