chore(rivetkit): rename onstart/onstop to onwake/onsleep

[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:46am

3 Skipped Deployments

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

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

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

@rivetkit/cloudflare-workers

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

@rivetkit/core

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

@rivetkit/db

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: c298cf6

[claude]

PR Review: Rename onStart/onStop to onWake/onSleep

Summary

This PR performs a straightforward renaming of actor lifecycle hooks from onStart/onStop to onWake/onSleep, which better reflects the actor hibernation/wake semantics. The changes are well-contained and consistent across the codebase.

Code Quality ✅

Strengths:

• Consistent renaming across all public APIs, examples, tests, and documentation
• All affected files have been properly updated including:
  • Type definitions and schemas
  • Example code
  • Test fixtures and test assertions
  • Documentation (SPEC.md)
  • JSDoc comments

Areas for Improvement:

1. Internal Method Names (rivetkit-typescript/packages/rivetkit/src/actor/instance/mod.ts:865, 875)

   • Private methods #callOnStart() and #callOnStop() still use the old naming
   • Consider renaming to #callOnWake() and #callOnSleep() for consistency
   • Comments also reference "onStart lifecycle" and "onStop lifecycle" (lines 319, 370)

2. Log Messages (rivetkit-typescript/packages/rivetkit/src/actor/instance/mod.ts:878, 883, 886, 889)

   • Log messages still say "calling onStop", "onStop completed", "onStop timed out", "error in onStop"
   • Should be updated to reference "onSleep" for consistency

3. Configuration Timeout (rivetkit-typescript/packages/rivetkit/src/actor/config.ts:64)

   • The config option onStopTimeout should be renamed to onSleepTimeout
   • This is a breaking change to the configuration schema, so ensure it's intended
   • If keeping for backward compatibility, add a comment explaining why

4. Public API Methods (rivetkit-typescript/packages/rivetkit/src/actor/instance/mod.ts:351)

   • The public method onStop() on ActorInstance is still named with old terminology
   • Consider renaming to onSleep() or documenting why it retains the old name

5. Driver References

   • rivetkit-typescript/packages/rivetkit/src/drivers/engine/actor-driver.ts has multiple references to onStop in comments and error messages (lines 490, 493, 667, 670, 674, 684, 686)
   • rivetkit-typescript/packages/rivetkit/src/drivers/file-system/global-state.ts:344 calls actor.onStop()

Potential Bugs ⚠️

1. Breaking Change Considerations
   • If any external code or drivers are calling these hooks by name (reflection, dynamic invocation), this will break
   • Recommend checking if there's any serialization/deserialization of these hook names
   • Consider providing deprecation warnings or backward compatibility shims if this is a public API

Performance Considerations ✅

• No performance impact - purely a naming change

Security Concerns ✅

• No security concerns identified

Test Coverage ✅

Strong test coverage:

• All test assertions properly updated (actor-conn.ts, actor-handle.ts, actor-metadata.ts)
• Test fixtures updated (lifecycle.ts, metadata.ts, sleep.ts)
• Event tracking in tests correctly references "onWake" and "onSleep"

Recommendations:

• Consider adding a test that verifies the old hooks are no longer accepted (if that's the intent)
• Verify all driver test suites pass with the new naming

Recommendations

Critical (before merge):

1. Update internal method names #callOnStart() → #callOnWake() and #callOnStop() → #callOnSleep()
2. Update all log messages to reference "onSleep" instead of "onStop"
3. Decide on onStopTimeout config option - rename to onSleepTimeout or document why it stays

Important:
4. Rename public onStop() method to align with new terminology
5. Update driver code references and comments
6. Update comment on line 319 from "Call onStart lifecycle" to "Call onWake lifecycle"
7. Update comment on line 370 from "Call onStop lifecycle" to "Call onSleep lifecycle"

Nice to have:
8. Grep for any remaining "start"/"stop" terminology in comments that should be "wake"/"sleep"

Conclusion

This is a well-executed refactoring that improves API clarity. However, there are several internal references that were missed and should be updated for complete consistency. The changes are mostly cosmetic but important for maintainability and avoiding confusion.

Status: Recommend changes before merge to ensure complete consistency throughout the codebase.