chore(rivetkit): split ActorInstance logic in to multiple classes

[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 9, 2025 5:08am

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Nov 9, 2025 5:08am
rivet-inspector	Ignored	Preview		Nov 9, 2025 5:08am
rivet-site	Ignored	Preview		Nov 9, 2025 5:08am

[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
• 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 👈 (View in Graphite)
• 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]

PR Review: Split ActorInstance logic into multiple classes

Summary

This is a well-executed refactoring that improves code organization by splitting the monolithic ActorInstance class (~2200 lines) into focused, single-responsibility manager classes. The changes enhance maintainability while preserving existing functionality.

Positive Aspects ✅

1. Excellent Code Organization

• Clear separation of concerns with dedicated managers:
  • ConnectionManager - connection lifecycle and hibernation
  • StateManager - state persistence and change tracking
  • EventManager - event broadcasting and handling
  • ScheduleManager - scheduled task management
• Each manager has well-defined responsibilities and encapsulation

2. API Improvements

• Changed from underscored private-style methods (_onAlarm, _broadcast, _sendMessage) to proper public methods (onAlarm, broadcast, sendMessage)
• Better use of TypeScript symbols for internal state (CONN_PERSIST_SYMBOL, ACTOR_INSTANCE_PERSIST_SYMBOL)
• More intuitive driver interface with factory functions (createWebSocketSocket, createHttpSocket)

3. Improved Driver Architecture

• Simplified driver interface by moving driver-specific logic into factory functions
• Eliminated discriminated union pattern (ConnDriverState) in favor of closure-based approach
• Better encapsulation with drivers holding their own state

4. File Organization

• Logical directory structure (actor/conn/, actor/contexts/, actor/instance/)
• Clear module boundaries with appropriate re-exports

Issues & Recommendations ⚠️

1. Missing Error Handling in WebSocket Driver 🔴

Location: rivetkit-typescript/packages/rivetkit/src/actor/conn/drivers/websocket.ts:92-94

terminate: () => {
    (websocket as any).terminate();
},

Issue: The terminate() method uses type assertion to call a method that may not exist on WSContext.

Recommendation: Add proper type checking or error handling:

terminate: () => {
    if ('terminate' in websocket && typeof websocket.terminate === 'function') {
        (websocket as any).terminate();
    } else {
        actor.rLog.warn('WebSocket does not support terminate(), using close instead');
        websocket.close(1011, 'Connection terminated');
    }
},

2. Potential Memory Leak in Close Promises 🟡

Location: rivetkit-typescript/packages/rivetkit/src/actor/router-endpoints.ts:142

const closePromiseResolvers = promiseWithResolvers<void>();

Issue: If closePromiseResolvers.resolve() is never called (e.g., due to errors in WebSocket lifecycle), the promise will hang indefinitely. The disconnect method awaits this promise.

Recommendation: Add timeout handling:

disconnect: async (actor, conn, reason) => {
    websocket.close(1000, reason);
    
    // Wait for close with timeout
    const timeoutMs = 5000;
    await Promise.race([
        closePromise,
        new Promise((_, reject) => 
            setTimeout(() => reject(new Error('Close timeout')), timeoutMs)
        )
    ]).catch(err => {
        actor.rLog.warn({ msg: 'websocket close timeout', error: err });
    });
},

3. Inconsistent Type Annotations 🟡

Location: Multiple files in actor/instance/

Several manager constructors use any for config parameters:

// state-manager.ts:48
#config: any; // ActorConfig type

// connection-manager.ts:99
eventManager: any, // EventManager type

Recommendation: Use proper generic types or define specific config interfaces to maintain type safety throughout the refactoring.

4. Deleted File May Have Active Usage 🟡

Location: rivetkit-typescript/packages/rivetkit/src/actor/unstable-react.ts

This file was completely removed (110 lines). Ensure there are no external consumers of this unstable API before merging.

Recommendation: Verify with a grep for any imports:

grep -r "unstable-react" rivetkit-typescript/

5. Symbol Export Strategy 🟢

Location: actor/conn/mod.ts:25-26

export const CONN_PERSIST_SYMBOL = Symbol("persist");
export const CONN_DRIVER_SYMBOL = Symbol("driver");

Minor concern: Exporting symbols makes them accessible but doesn't truly enforce privacy since symbols are unique but discoverable.

Recommendation: Document in comments that these are internal-only and should not be used by consumers.

Security Considerations 🔒

1. Type Assertions on User Input

The WebSocket message handling uses type assertions that could be exploited if validation is insufficient upstream. Ensure all message deserialization is properly validated.

2. Closure-based State

The new driver pattern uses closures to hold state (encoding, websocket reference, etc.). This is secure as long as the factory functions are only called by trusted code.

Performance Considerations ⚡

Positive:

• Manager delegation should have minimal overhead
• Closure-based drivers avoid repeated state lookups

Neutral:

• Additional indirection through managers (acceptable tradeoff for maintainability)

Testing Coverage 📋

Concern: Only one test file was modified (tests/actor-types.test.ts). Such a large refactoring should include:

• Unit tests for each new manager class
• Integration tests verifying manager interactions
• Tests for edge cases in connection lifecycle
• Tests for the new driver factory pattern

Recommendation: Add comprehensive test coverage before merging.

Migration Impact 🔄

Breaking Changes:

• Method renames (_onAlarm → onAlarm, etc.) may affect internal consumers
• Symbol changes may affect code using __persist and __socket
• File reorganization requires import updates

Recommendation: Document migration path for any internal consumers.

Final Verdict

Overall Assessment: ✅ Approve with minor changes

This is a solid refactoring that significantly improves code organization and maintainability. The architectural changes are sound, and the code quality is high. The identified issues are minor and can be addressed before or shortly after merge.

Priority Fixes:

1. Fix WebSocket terminate() error handling
2. Add timeout to WebSocket close promise
3. Replace any types with proper generics
4. Verify no external consumers of deleted unstable-react.ts
5. Add test coverage for new manager classes

Nice to Have:

• Document symbol export strategy
• Add migration guide for breaking changes

Great work on improving the codebase architecture! 🎉

[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@3421

@rivetkit/cloudflare-workers

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

@rivetkit/core

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

@rivetkit/db

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: 47cb55f