chore(core): migrate gateway to use websocket protocols

[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	Error			Sep 24, 2025 6:11am

[claude]

Claude finished @NathanFlurry's task —— View job

---

Code Review: WebSocket Protocol Migration

I've completed my analysis of this PR that migrates the gateway to use WebSocket protocols instead of headers. Here's my comprehensive review:

Todo List

• Read and understand the websocket protocol migration changes
• Review new gateway.ts implementation
• Analyze router.ts refactoring
• Check websocket client and driver changes
• Review test file modifications
• Assess code quality and best practices
• Identify potential bugs or issues
• Evaluate performance considerations
• Check for security concerns
• Assess test coverage impact

---

Summary

This PR introduces a significant architectural change by migrating from HTTP headers to WebSocket Sec-WebSocket-Protocol headers for routing and configuration. The main change extracts WebSocket handling logic into a new gateway.ts file while removing auth data handling throughout the codebase.

Key Changes Analysis

✅ Positive Changes:

• Clean separation of concerns: New gateway.ts provides a clear entry point for all WebSocket routing
• Standards compliance: Using sec-websocket-protocol is the standard way to pass metadata in WebSocket connections
• Code organization: Router is cleaner with gateway logic extracted
• Consistent protocol handling: Unified approach for parsing WebSocket protocols

⚠️ Issues & Concerns:

1. Security: Auth Data Removal (packages/rivetkit/src/actor/router-endpoints.ts:96)

The complete removal of authData parameters across all handlers is a breaking security change:

- authData: unknown,

This affects authentication for WebSocket connections, SSE connections, and actions. Impact: This could break existing authentication flows without proper migration.

2. Error Handling Gap (packages/rivetkit/src/manager/gateway.ts:84-89)

if (target !== "actor") {
	return c.text("WebSocket upgrade requires target.actor protocol", 400);
}

This returns a plain text response during WebSocket upgrade, which may not be handled properly by WebSocket clients expecting the upgrade to fail differently.

3. URL Parsing Logic Duplication (packages/rivetkit/src/manager/gateway.ts:103-105)

const pathWithQuery = c.req.url.includes("?")
	? c.req.path + c.req.url.substring(c.req.url.indexOf("?"))
	: c.req.path;

This manual URL parsing could be replaced with URL.searchParams for better reliability.

4. Protocol Parsing Robustness (packages/rivetkit/src/manager/gateway.ts:67-82)

The protocol parsing logic doesn't handle malformed protocols gracefully:

target = protocol.substring(WS_PROTOCOL_TARGET.length);

If a protocol doesn't match the expected format, this could produce unexpected results.

5. WebSocket Connection Lifecycle (packages/rivetkit/src/manager/gateway.ts:174-275)

The createTestWebSocketProxy function has complex async logic that could benefit from better error boundaries and cleanup:

• Potential memory leaks if promises don't resolve
• Complex event listener setup without proper cleanup

6. Type Safety Issues (packages/rivetkit/src/manager/router.ts:111)

encoding as any, // Will be validated by driver

Using any defeats TypeScript's type safety. Better to use proper type assertions or validation.

7. Missing Input Validation

The PR doesn't validate the WebSocket protocol parameters before using them. Malformed JSON in conn_params could cause runtime errors.

Performance Considerations

✅ Good:

• Protocol parsing is efficient with simple string operations
• Reduced header processing overhead

⚠️ Concerns:

• Multiple substring calls during protocol parsing could be optimized
• JSON parsing of connection params happens multiple times without caching

Test Coverage Impact

Issues Found:

• Raw WebSocket test suite has functionality removed (auth data tests)
• Tests still pass but cover less functionality
• No tests added for the new protocol parsing logic in gateway.ts

Recommendations

High Priority:

1. Address auth data removal: Either provide migration path or document breaking change
2. Add input validation: Validate protocol parameters and handle malformed input
3. Improve error responses: Use appropriate WebSocket error codes instead of HTTP text responses

Medium Priority:

1. Refactor URL parsing: Use standard URL APIs
2. Add tests: Cover new gateway protocol parsing logic
3. Type safety: Remove any type assertions

Low Priority:

1. Performance optimization: Cache parsed parameters
2. Code cleanup: Extract protocol parsing into utility functions

Security Assessment

• Auth removal: Major security concern - needs clear migration strategy
• Input validation: Missing validation could lead to injection issues
• Protocol parsing: Generally safe but lacks error boundaries

Verdict

This is a well-structured refactoring that improves code organization and follows WebSocket standards. However, the removal of authentication data is a breaking change that needs careful consideration and documentation. The implementation is mostly solid but would benefit from additional validation and testing.

Recommendation: Address auth data concerns and add missing validations before merging.

---

[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

• chore(core): migrate gateway to use websocket protocols #1293 👈 (View in Graphite)
• chore(core): update api schema to match new engine schema #1292
• chore(core): fix conn/disconn tests for sse #1290
• fix(core): fix inline client driver for cloudflare-workers #1289
• chore(core): fix missing transport for inline tests #1287 : 1 other dependent PR (#1250 )
• chore(core): fix test for sending message to specific connection sse race condition #1286
• fix(cloudflare-workers): fix alarms #1285
• chore(core): fix broadcast race condition #1284
• chore: list sideEffects #1283
• chore(core): fix connection tests to support sse #1282
• fix(cloudflare-workers): fix aborts on sse streams on cloudflare workers #1281
• fix(cloudflare-workers): fix aborting sse streams #1280
• chore: remove unused FakeEventSource #1279
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• merge queue - adds this PR to the back of the merge queue
• hotfix - for urgent hot fixes, skip the queue and merge this PR next

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.

[pkg-pr-new]

More templates

• example-ai-agent
• example-better-auth-external-db
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• counter
• example-crdt
• example-database
• example-sqlite
• example-elysia
• example-express
• example-game
• example-hono
• example-hono-react
• example-next-js
• example-rate
• example-raw-fetch-handler
• example-raw-websocket-handler-proxy
• example-react
• starter
• example-stream
• example-sync
• example-tenant
• example-trpc

@rivetkit/actor

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

@rivetkit/cloudflare-workers

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

@rivetkit/core

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

@rivetkit/db

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

commit: 9ad97a7

[claude]

Claude finished @NathanFlurry's task —— View job

---

Claude Code finished analyzing the WebSocket protocol migration PR

---

Code Review: WebSocket Protocol Migration

I've completed my analysis of this PR that migrates the gateway to use WebSocket protocols instead of headers. Here's my comprehensive review:

Todo List

• Read and understand the websocket protocol migration changes
• Review new gateway.ts implementation
• Analyze router.ts refactoring
• Check websocket client and driver changes
• Review test file modifications
• Assess code quality and best practices
• Identify potential bugs or issues
• Evaluate performance considerations
• Check for security concerns
• Assess test coverage impact

---

Summary

This PR introduces a significant architectural change by migrating from HTTP headers to WebSocket Sec-WebSocket-Protocol headers for routing and configuration. The main change extracts WebSocket handling logic into a new gateway.ts file while removing auth data handling throughout the codebase.

Key Changes Analysis

✅ Positive Changes:

• Clean separation of concerns: New gateway.ts provides a clear entry point for all WebSocket routing
• Standards compliance: Using sec-websocket-protocol is the standard way to pass metadata in WebSocket connections
• Code organization: Router is cleaner with gateway logic extracted
• Consistent protocol handling: Unified approach for parsing WebSocket protocols

⚠️ Issues & Concerns:

1. Security: Auth Data Removal (packages/rivetkit/src/actor/router-endpoints.ts:96)

The complete removal of authData parameters across all handlers is a breaking security change:

- authData: unknown,

This affects authentication for WebSocket connections, SSE connections, and actions. Impact: This could break existing authentication flows without proper migration.

2. Error Handling Gap (packages/rivetkit/src/manager/gateway.ts:84-89)

if (target !== "actor") {
	return c.text("WebSocket upgrade requires target.actor protocol", 400);
}

This returns a plain text response during WebSocket upgrade, which may not be handled properly by WebSocket clients expecting the upgrade to fail differently.

3. URL Parsing Logic Duplication (packages/rivetkit/src/manager/gateway.ts:103-105)

const pathWithQuery = c.req.url.includes("?")
	? c.req.path + c.req.url.substring(c.req.url.indexOf("?"))
	: c.req.path;

This manual URL parsing could be replaced with URL.searchParams for better reliability.

4. Protocol Parsing Robustness (packages/rivetkit/src/manager/gateway.ts:67-82)

The protocol parsing logic doesn't handle malformed protocols gracefully:

target = protocol.substring(WS_PROTOCOL_TARGET.length);

If a protocol doesn't match the expected format, this could produce unexpected results.

5. WebSocket Connection Lifecycle (packages/rivetkit/src/manager/gateway.ts:174-275)

The createTestWebSocketProxy function has complex async logic that could benefit from better error boundaries and cleanup:

• Potential memory leaks if promises don't resolve
• Complex event listener setup without proper cleanup

6. Type Safety Issues (packages/rivetkit/src/manager/router.ts:111)

encoding as any, // Will be validated by driver

Using any defeats TypeScript's type safety. Better to use proper type assertions or validation.

7. Missing Input Validation

The PR doesn't validate the WebSocket protocol parameters before using them. Malformed JSON in conn_params could cause runtime errors.

Performance Considerations

✅ Good:

• Protocol parsing is efficient with simple string operations
• Reduced header processing overhead

⚠️ Concerns:

• Multiple substring calls during protocol parsing could be optimized
• JSON parsing of connection params happens multiple times without caching

Test Coverage Impact

Issues Found:

• Raw WebSocket test suite has functionality removed (auth data tests)
• Tests still pass but cover less functionality
• No tests added for the new protocol parsing logic in gateway.ts

Recommendations

High Priority:

1. Address auth data removal: Either provide migration path or document breaking change
2. Add input validation: Validate protocol parameters and handle malformed input
3. Improve error responses: Use appropriate WebSocket error codes instead of HTTP text responses

Medium Priority:

1. Refactor URL parsing: Use standard URL APIs
2. Add tests: Cover new gateway protocol parsing logic
3. Type safety: Remove any type assertions

Low Priority:

1. Performance optimization: Cache parsed parameters
2. Code cleanup: Extract protocol parsing into utility functions

Security Assessment

• Auth removal: Major security concern - needs clear migration strategy
• Input validation: Missing validation could lead to injection issues
• Protocol parsing: Generally safe but lacks error boundaries

Verdict

This is a well-structured refactoring that improves code organization and follows WebSocket standards. However, the removal of authentication data is a breaking change that needs careful consideration and documentation. The implementation is mostly solid but would benefit from additional validation and testing.

Recommendation: Address auth data concerns and add missing validations before merging.

---

[claude]

Claude finished @NathanFlurry's task —— View job

---

Code Review: WebSocket Protocol Migration

I've completed my analysis of this PR that migrates the gateway to use WebSocket protocols instead of headers. Here's my comprehensive review:

Todo List

• Read and understand the websocket protocol migration changes
• Review new gateway.ts implementation
• Analyze router.ts refactoring
• Check websocket client and driver changes
• Review test file modifications
• Assess code quality and best practices
• Identify potential bugs or issues
• Evaluate performance considerations
• Check for security concerns
• Assess test coverage impact

---

Summary

This PR introduces a significant architectural change by migrating from HTTP headers to WebSocket Sec-WebSocket-Protocol headers for routing and configuration. The main change extracts WebSocket handling logic into a new gateway.ts file while removing auth data handling throughout the codebase.

Key Changes Analysis

✅ Positive Changes:

• Clean separation of concerns: New gateway.ts provides a clear entry point for all WebSocket routing
• Standards compliance: Using sec-websocket-protocol is the standard way to pass metadata in WebSocket connections
• Code organization: Router is cleaner with gateway logic extracted
• Consistent protocol handling: Unified approach for parsing WebSocket protocols

⚠️ Issues & Concerns:

1. Security: Auth Data Removal (packages/rivetkit/src/actor/router-endpoints.ts:96)

The complete removal of authData parameters across all handlers is a breaking security change:

- authData: unknown,

This affects authentication for WebSocket connections, SSE connections, and actions. Impact: This could break existing authentication flows without proper migration.

2. Error Handling Gap (packages/rivetkit/src/manager/gateway.ts:84-89)

if (target !== "actor") {
	return c.text("WebSocket upgrade requires target.actor protocol", 400);
}

This returns a plain text response during WebSocket upgrade, which may not be handled properly by WebSocket clients expecting the upgrade to fail differently.

3. URL Parsing Logic Duplication (packages/rivetkit/src/manager/gateway.ts:103-105)

const pathWithQuery = c.req.url.includes("?")
	? c.req.path + c.req.url.substring(c.req.url.indexOf("?"))
	: c.req.path;

This manual URL parsing could be replaced with URL.searchParams for better reliability.

4. Protocol Parsing Robustness (packages/rivetkit/src/manager/gateway.ts:67-82)

The protocol parsing logic doesn't handle malformed protocols gracefully:

target = protocol.substring(WS_PROTOCOL_TARGET.length);

If a protocol doesn't match the expected format, this could produce unexpected results.

5. WebSocket Connection Lifecycle (packages/rivetkit/src/manager/gateway.ts:174-275)

The createTestWebSocketProxy function has complex async logic that could benefit from better error boundaries and cleanup:

• Potential memory leaks if promises don't resolve
• Complex event listener setup without proper cleanup

6. Type Safety Issues (packages/rivetkit/src/manager/router.ts:111)

encoding as any, // Will be validated by driver

Using any defeats TypeScript's type safety. Better to use proper type assertions or validation.

7. Missing Input Validation

The PR doesn't validate the WebSocket protocol parameters before using them. Malformed JSON in conn_params could cause runtime errors.

Performance Considerations

✅ Good:

• Protocol parsing is efficient with simple string operations
• Reduced header processing overhead

⚠️ Concerns:

• Multiple substring calls during protocol parsing could be optimized
• JSON parsing of connection params happens multiple times without caching

Test Coverage Impact

Issues Found:

• Raw WebSocket test suite has functionality removed (auth data tests)
• Tests still pass but cover less functionality
• No tests added for the new protocol parsing logic in gateway.ts

Recommendations

High Priority:

1. Address auth data removal: Either provide migration path or document breaking change
2. Add input validation: Validate protocol parameters and handle malformed input
3. Improve error responses: Use appropriate WebSocket error codes instead of HTTP text responses

Medium Priority:

1. Refactor URL parsing: Use standard URL APIs
2. Add tests: Cover new gateway protocol parsing logic
3. Type safety: Remove any type assertions

Low Priority:

1. Performance optimization: Cache parsed parameters
2. Code cleanup: Extract protocol parsing into utility functions

Security Assessment

• Auth removal: Major security concern - needs clear migration strategy
• Input validation: Missing validation could lead to injection issues
• Protocol parsing: Generally safe but lacks error boundaries

Verdict

This is a well-structured refactoring that improves code organization and follows WebSocket standards. However, the removal of authentication data is a breaking change that needs careful consideration and documentation. The implementation is mostly solid but would benefit from additional validation and testing.

Recommendation: Address auth data concerns and add missing validations before merging.

[graphite-app]

Merge activity

• Sep 24, 6:06 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Sep 24, 6:07 AM UTC: CI is running for this pull request on a draft pull request (#1294) due to your merge queue CI optimization settings.
• Sep 24, 6:08 AM UTC: Merged by the Graphite merge queue via draft PR: #1294.