chore(rivetkit): add support for conn params on onRequest and onWebSocket

[NathanFlurry]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
rivetkit-serverless	Ready	Preview	Comment	Nov 10, 2025 11:33pm

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Nov 10, 2025 11:33pm
rivet-inspector	Ignored	Preview		Nov 10, 2025 11:33pm
rivet-site	Ignored	Preview		Nov 10, 2025 11:33pm

[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

• feat(site): add typedoc docs #3446
• chore(rivetkit): remove deprecated packages #3447
• chore(rivetkit): add support for conn params on onRequest and onWebSocket #3445 👈 (View in Graphite)
• feat(rivetkit): add asyncapi spec #3442
• chore(rivetkit): add actor router to the openapi spec #3441
• fix(rivetkit): skip sending RivetKit messages to conns that do not support it #3440
• fix(rivetkit): fix race condition with websocket open events #3439
• fix(rivetkit): standardize error metadata return type #3438
• fix(rivetkit): remove incorrect getEndpoint call in metadata handler #3433
• feat(rivetkit): add json protocol support #3432
• chore(rivetkit): add required zod validation for json encoding #3431
• chore(rivetkit): add listing actors by only name to manager api #3430
• refactor(rivetkit): extract WebSocket protocol parsing to shared utility #3429
• refactor(rivetkit): restructure connection lifecycle contexts #3428
• chore(rivetkit): add WebSocketContext and RequestContext #3427
• chore(rivetkit): add conn type #3426
• chore(rivetkit): add connection for raw http #3425
• chore(rivetkit): rename onFetch to onRequest #3424
• refactor(rivetkit): add state manager for conn with symbol-based access #3423
• fix(rivetkit): use loggerWithoutContext for websocket error when actor undefined #3412
• feat(rivetkit): add GET /actors/names #3411
• feat(api-public): expose actor kv api #3410
• chore(rivetkit): auto-generate inspector token for engine driver #3409
• chore(rivetkit): close websockets on out of sequence messages #3404
• fix(rivetkit): properly apply clientEndpoint from metadata lookup #3402
• fix(rivetkit): properly handle msgIndex for hibernatable websocket reconnection #3401
• chore(rivetkit): rename onstart/onstop to onwake/onsleep #3422
• chore(rivetkit): split ActorInstance logic in to multiple classes #3421
• chore(rivetkit): move conns to separate persisted kv keys #3420
• chore(rivetkit): remove deprecated conn tokens & sse support #3419
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

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

[claude]

Code Review

Summary

This PR adds support for passing connection parameters (connParams) to onRequest and onWebSocket handlers. The changes properly extract connection parameters from HTTP headers and WebSocket protocols and thread them through to the connection manager.

Positive Aspects ✅

1. Consistent Implementation: The changes follow the existing pattern used in handleWebSocketConnect and properly reuse the getRequestConnParams and parseWebSocketProtocols utility functions.

2. Correct Parameter Threading: The connParams are properly passed through all the call sites:

   • handleRawRequest in router-endpoints.ts:344
   • handleRawWebSocket in router-endpoints.ts:373
   • Engine driver in actor-driver.ts:565
   • File system manager in manager.ts:192, 250

3. Backwards Compatibility: The fallback to empty object for WebSocket (connParams ?? {}) ensures backwards compatibility if connParams is undefined.

4. Good Logging: Added debug logging for connParams in the raw WebSocket handler (router.ts:190) which will help with debugging.

Issues & Concerns 🔍

1. Type Safety - Critical

The connParams parameter in handleRawWebSocket is typed as unknown | undefined:

connParams: unknown | undefined,

However, when calling prepareAndConnectConn, you are passing connParams ?? {}. This could lead to type mismatches since the connection manager expects a specific type CP (the connection parameters generic type).

Recommendation: Consider validating/parsing connParams before passing to prepareAndConnectConn, similar to how encoding is validated with EncodingSchema.parse().

2. Null vs Undefined Inconsistency - Medium

In getRequestConnParams (router-endpoints.ts:550), the function returns null when the header is not present, but the calling code in handleRawRequest assigns it to parameters without checking for null:

const parameters = getRequestConnParams(c.req); // Could be null
// ...
parameters, // Passed directly to prepareAndConnectConn

Meanwhile, for WebSocket you handle undefined with ??. This inconsistency could cause issues.

Recommendation: Make the return types consistent - either use null, undefined, or {} as the default consistently across both HTTP and WebSocket paths.

3. Missing Comment Removal - Minor

In router.ts:113, a comment was removed:

-// Parse configuration from Sec-WebSocket-Protocol header
 const protocols = c.req.header("sec-websocket-protocol");

While the comment might have been redundant, it is worth noting this was the only comment removal in the PR. Not a functional issue, but worth confirming it was intentional.

Testing Concerns 🧪

Missing Test Coverage: There do not appear to be tests added for this new functionality. Consider adding tests for:

• onRequest handler receiving connParams via HTTP headers
• onWebSocket handler receiving connParams via WebSocket protocols
• Edge cases: malformed JSON in headers/protocols, missing headers, etc.

Given that this touches connection management which is critical infrastructure, test coverage would be valuable.

Performance Considerations ⚡

No performance concerns identified. The changes are minimal and follow existing patterns.

Security Considerations 🔒

Input Validation: The connParams are parsed from user-controlled input (HTTP headers or WebSocket protocols). Current implementation:

• Uses JSON.parse() with try/catch
• Throws InvalidParams error on parse failure

This is reasonable, but consider:

• Adding schema validation if connParams has a specific expected structure
• Documenting any limits on the size of connParams to prevent DoS via oversized headers

Recommendations Summary

1. High Priority: Add type validation/parsing for connParams before passing to prepareAndConnectConn
2. Medium Priority: Fix null/undefined inconsistency between HTTP and WebSocket paths
3. Medium Priority: Add test coverage for the new functionality
4. Low Priority: Consider schema validation for connParams structure

Conclusion

The implementation is solid and follows existing patterns well. The main concerns are around type safety and test coverage. With the recommendations addressed, this would be ready to merge.

---

🤖 Generated with Claude Code

[pkg-pr-new]

More templates

• example-ai-agent
• example-background-jobs
• example-better-auth-external-db
• example-bots
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• example-counter
• example-counter-serverless
• example-crdt
• example-cursors
• example-cursors-raw-websocket
• example-database
• example-deno
• example-sqlite
• example-elysia
• example-express
• example-freestyle
• example-game
• example-hono
• example-hono-bun
• example-hono-react
• example-kitchen-sink
• example-next-js
• example-rate
• example-raw-fetch-handler
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-react
• starter
• example-stream
• example-sync
• example-tenant
• example-trpc
• example-workflows

@rivetkit/actor

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/actor@3445

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@3445

@rivetkit/core

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/core@3445

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/db@3445

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@3445

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@3445

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@3445

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@3445

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@3445

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@3445

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@3445

commit: 633481b