docs: require close-code rejection for websocket auth/policy failures

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(rivetkit-core): gate startup until runtime is ready #4736 : 2 dependent PRs (#4737 , #4739 )
• fix(rivetkit-sqlite): preserve text with embedded nul bytes #4735
• chore(rivetkit): add child spans for logging #4734
• fix(rivetkit-core): orphan engine process and detect crashes #4733
• fix(rivetkit-core): return None for empty inspector state to avoid frontend CBOR decode error #4732
• fix(rivetkit-core): don't install tokio::signal::ctrl_c() handler inside serve_with_config #4731
• refactor(rivetkit-core): use subtle::ConstantTimeEq for inspector token verify #4730
• fix(rivetkit): drop is_read_only_sql classifier, surface RETURNING rows #4728
• docs: require close-code rejection for websocket auth/policy failures #4727 👈 (View in Graphite)
• fix(rivetkit): inspector reports actual config state + real queue messages #4726
• fix(rivetkit-napi): plumb ctx through serializeState TSF and stop panicking on runtime_state Ref drop #4725
• chore(rivetkit): remove legacy metrics & prometheus auth #4724
• chore(rivetkit): remove legacy metrics #4723
• chore(rivetkit): impl inspector token #4722
• chore: disable auth on serverless #4721
• chore: fix cors for envoys #4720
• chore: fix serverless in rivetkit-core #4719
• chore(rivetkit): impl follow up review #4711
• chore: rivetkit core/napi/typescript follow up review #4702
• chore: fix remaining issues with rivetkit-core #4701
• chore: sqlite v1 to v2 data migration #4692 : 1 other dependent PR (#4640 )
• chore: move rivetkit to task model #4680
• chore: rivetkit to rust #4679
• feat(rivetkit): sqlite vfs v2 #4673
• chore: rename sandbox -> kitchen sink #4671 : 1 other dependent PR (#4672 )
• chore: configure TLS trust roots for rustls clients #4667
• fix(rivetkit): update config to match envoys & remove manager references #4663
• chore(publish): pin docker base image refs #4652
• chore(engine): publish engine bases in ci #4649 : 2 other dependent PRs (#4650 , #4666 )
• chore: lockfile lefthook #4647
• fix(rivetkit): surface native sqlite kv errors to callers #4645
• fix(rivetkit): prevent sleep races during disconnect and db work #4644
• fix(rivetkit): isolate engine envoys and propagate startup failures #4643
• test(rivetkit): remove wasm sqlite-only fixtures and coverage #4642
• chore(sqlite-vfs): remove wasm sqlite packages and workspace wiring #4641
• chore(rivetkit): remove wasm sqlite runtime #4614
• fix(sqlite-native): restore native startup kv preload #4639
• fix(sqlite-native): delete metadata before chunk range #4638
• fix(sqlite-native): keep truncate cache coherent #4637
• fix(sqlite-vfs): use delete range for truncate cleanup #4636
• fix(sqlite-native): restore kv error hook #4635
• perf(sqlite-native): avoid cloning cached read chunks #4634
• perf(sqlite-native): gate kv operation labels #4633
• perf(sqlite-native): reuse read cache for partial writes #4632
• perf(sqlite-native): remove delete file existence probe #4631
• fix(sqlite-native): gate native read cache behind env var #4630
• fix(pegboard): isolate runner config dc lookup failures #4625 : 1 other dependent PR (#4626 )
• docs(pegboard): note runner config upsert split write risk #4624
• fix(pegboard): unpack global runner config keys correctly #4623
• fix(pegboard-gateway): enforce tunnel message state #4622
• fix(pegboard-runner): clear terminal tunnel routes #4621
• fix(pegboard): skip protocol version keys in runner pool backfill #4620
• fix(pegboard): create missing normal runner configs #4619
• fix(epoxy): reuse cached optimistic value #4618
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4727

All packages published as 0.0.0-pr.4727.e649173 with tag pr-4727.

Engine binary is shipped via @rivetkit/engine-cli on linux-x64-musl, linux-arm64-musl, darwin-x64, and darwin-arm64. Windows users should use the release installer or set RIVET_ENGINE_BINARY.

Docker images:

docker pull rivetdev/engine:slim-e649173
docker pull rivetdev/engine:full-e649173

Individual packages

npm install rivetkit@pr-4727
npm install @rivetkit/react@pr-4727
npm install @rivetkit/rivetkit-napi@pr-4727
npm install @rivetkit/workflow-engine@pr-4727

[claude]

PR Review: docs: require close-code rejection for websocket auth/policy failures

Summary

The guidance is technically correct — browsers only see CloseEvent.code / .reason on a failed WebSocket upgrade, never the HTTP status, so pre-upgrade HTTP rejections are opaque to browser clients. The close code 1008 choice and inspector.unauthorized convention also match the existing inspector_ws.rs implementation.

That said, there are a few issues worth addressing:

---

Issues

1. CLAUDE.md format violation (blocker)

CLAUDE.md itself states:

"When adding entries to any CLAUDE.md file, keep them concise. Ideally a single bullet point or minimal bullet points. Do not write paragraphs."
"When the user asks to update any CLAUDE.md, add one-line bullet points only."

The added entry is a multi-sentence paragraph. It should be split into concise one-line bullets. Suggested rewrite:

## WebSocket Rejection

- Reject WebSocket connections by accepting the upgrade and sending a close frame; never reject with an HTTP status before upgrade — browsers see only `CloseEvent.code` / `.reason`, not the HTTP status of a failed upgrade.
- Use close code `1008` (policy violation) for auth/policy failures, with a `<group>.<code>` reason string (e.g. `inspector.unauthorized`).
- Use close code `1011` for unexpected internal errors.

---

2. Scope ambiguity: "any rejection reason" vs. only auth failures

The bullet prescribes <group>.<code> format for "any rejection reason" up front, then narrows to auth failures at the end. The codebase uses different close codes for different error kinds (1008 for policy, 1011 for internal errors, 1003 for unsupported data). The rule should either specify the full mapping or limit itself to the auth case where the convention is established.

---

3. Section placement

The new section sits between "Trust Boundaries" and "Fail-By-Default Runtime". Consider moving it under "Error Handling" or appending it to "Trust Boundaries", since WebSocket rejection is primarily an auth + trust-boundary concern.

---

Verdict

The intent and technical rationale are solid. This just needs to be reformatted as concise bullets (per CLAUDE.md conventions) and have the close-code mapping clarified before merging.

[NathanFlurry]

Landed in main via stack-merge fast-forward push. Commits are in main; closing to match.