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

NathanFlurry · 2025-11-09T05:44:40Z

No description provided.

vercel · 2025-11-09T05:44:45Z

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

Project	Deployment	Preview	Comments	Updated (UTC)
rivetkit-serverless	Ready	Preview	Comment	Nov 13, 2025 2:48am

3 Skipped Deployments

Project	Deployment	Preview	Updated (UTC)
rivet-cloud	Ignored		Nov 13, 2025 2:48am
rivet-inspector	Ignored	Preview	Nov 13, 2025 2:48am
rivet-site	Ignored	Preview	Nov 13, 2025 2:48am

NathanFlurry · 2025-11-09T05:44:55Z

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

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 · 2025-11-09T05:49:02Z

More templates

@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: 8a57285

claude · 2025-11-09T05:50:16Z

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:

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)
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
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
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
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 ⚠️

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):

Update internal method names #callOnStart() → #callOnWake() and #callOnStop() → #callOnSleep()
Update all log messages to reference "onSleep" instead of "onStop"
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.

claude · 2025-11-13T01:33:42Z

PR Review: Rename onStart/onStop to onWake/onSleep

Overview

This PR renames lifecycle hooks from onStart/onStop to onWake/onSleep across the RivetKit TypeScript codebase. The new naming better reflects the actor lifecycle semantics, particularly in relation to hibernation/sleep behavior.

Code Quality ✅

Strengths:

Consistent Renaming: The renaming is applied consistently across all actor configurations, examples, fixtures, and tests
Maintains Backward Compatibility Structure: The changes preserve the existing function signatures and behavior
Good Test Coverage: All test cases have been updated to use the new terminology

Areas of Concern:

1. Incomplete Refactoring - Internal Method Names ⚠️

The public API has been renamed from onStart/onStop to onWake/onSleep, but internal implementation methods and comments still use the old naming:

File: rivetkit-typescript/packages/rivetkit/src/actor/instance/mod.ts

Line 319: Comment says // Call onStart lifecycle but should be // Call onWake lifecycle
Line 320: Method #callOnStart() should be renamed to #callOnWake()
Line 370: Comment says // Call onStop lifecycle but should be // Call onSleep lifecycle
Line 371: Method #callOnStop() should be renamed to #callOnSleep()
Line 865: Method name async #callOnStart() should be async #callOnWake()
Line 875: Method name async #callOnStop() should be async #callOnSleep()
Lines 878, 883, 886, 889: Log messages and comments still reference "onStop"

File: rivetkit-typescript/packages/rivetkit/src/actor/config.ts

Line 64: Configuration option onStopTimeout should potentially be renamed to onSleepTimeout for consistency

2. Driver Implementation References ⚠️

File: rivetkit-typescript/packages/rivetkit/src/drivers/engine/actor-driver.ts

Lines 490, 493: References to onStop in method calls and error messages
Lines 667, 670, 674, 686: Comments and method calls still use onStop

File: rivetkit-typescript/packages/rivetkit/src/drivers/file-system/global-state.ts

Line 344: Method call await actor.actor.onStop();

These references should be updated to onSleep for consistency, OR if the public method on ActorInstance is intentionally kept as onStop() (line 351 in mod.ts), this should be clearly documented as an internal API vs external hook distinction.

Performance Considerations ✅

No performance impact - this is purely a refactoring change.

Security Concerns ✅

No security implications identified.

Best Practices 📋

Recommendations:

Complete the refactoring: Update all internal method names, comments, and log messages to use the new wake/sleep terminology for consistency
Configuration naming: Consider renaming onStopTimeout to onSleepTimeout in the config schema
Public method naming: The ActorInstance.onStop() public method (line 351) should probably be renamed to onSleep() to match the hook name
Documentation clarity: If there's an intentional distinction between internal "stop" and user-facing "sleep", this should be documented

Suggested Changes

// In src/actor/instance/mod.ts

// Line 319
-		// Call onStart lifecycle
+		// Call onWake lifecycle

// Line 320 & method definition at 865
-	async #callOnStart() {
+	async #callOnWake() {

// Line 351 (if this is a public API)
-	async onStop() {
+	async onSleep() {

// Line 370 & method definition at 875  
-		// Call onStop lifecycle
-	async #callOnStop() {
+		// Call onSleep lifecycle
+	async #callOnSleep() {

Test Coverage ✅

All existing tests have been properly updated:

✅ Lifecycle event assertions updated
✅ Test descriptions updated
✅ Example code updated
✅ Fixture actors updated

Summary

This is a good refactoring that improves semantic clarity. However, the renaming is incomplete - internal implementation details, method names, and comments still use the old terminology. To fully realize the benefits of this change and avoid confusion, the refactoring should be extended to all internal references.

Recommendation: Request changes to complete the refactoring before merging.

Review generated with assistance from Claude Code

claude · 2025-11-13T03:12:17Z

PR Review: Rename onStart/onStop to onWake/onSleep

Summary

This PR performs a straightforward renaming refactor to improve the semantic clarity of actor lifecycle hooks. The renaming from onStart/onStop to onWake/onSleep better reflects the hibernation/wake behavior of actors in the system.

Code Quality: ✅ Good

The refactor is systematic and comprehensive across the TypeScript codebase
Type definitions are properly updated in both the schema and type system
Documentation strings updated appropriately (e.g., "Called when the actor is started and ready to receive connections")
Test cases updated to reflect the new naming

Issues Found: ⚠️ 1 Missing Update

Critical: The engine smoke test file was not updated and still uses the old API:

File: engine/tests/smoke/src/server/registry.ts (lines 10, 13)

onStart: async () => {
    await new Promise((resolve) => setTimeout(resolve, 1000));
},
onStop: async () => {
    await new Promise((resolve) => setTimeout(resolve, 1000));
},

This should be updated to:

onWake: async () => {
    await new Promise((resolve) => setTimeout(resolve, 1000));
},
onSleep: async () => {
    await new Promise((resolve) => setTimeout(resolve, 1000));
},

Additional Observations

Incomplete refactor in internal implementation:
In rivetkit-typescript/packages/rivetkit/src/actor/instance/mod.ts lines 865-889, the internal method names and log messages still reference the old terminology:

Method #callOnStart() - should be #callOnWake()
Method #callOnStop() - should be #callOnSleep()
Log messages like "calling onStop", "onStop completed", "onStop timed out", "error in onStop" should use the new terminology

While these are private implementation details, consistency in naming would improve maintainability and reduce confusion.

Driver-level references:
The files rivetkit-typescript/packages/rivetkit/src/drivers/engine/actor-driver.ts and rivetkit-typescript/packages/rivetkit/src/drivers/file-system/global-state.ts contain references to onStop() as a method call on actor instances. These appear to be calling the lifecycle method, so they should remain consistent with whatever the actor instance's public API is.

Documentation not included:
The following documentation files still reference onStart/onStop and are not included in this PR:

website/src/posts/2025-09-12-performance-lifecycle-updates/page.mdx
website/src/data/examples/examples.ts
website/src/content/docs/actors/lifecycle.mdx
website/src/content/docs/actors/external-sql.mdx
website/src/content/docs/actors/helper-types.mdx

These should be updated in this PR or a follow-up to maintain documentation accuracy.

Performance: ✅ No Impact

This is a pure rename refactor with no runtime performance implications.

Security: ✅ No Concerns

No security-related changes.

Test Coverage: ⚠️ Partially Complete

Test fixtures properly updated
Test expectations properly updated
Missing: The smoke test in engine/tests/smoke/ still uses old API and needs updating

Recommendations

Must fix: Update engine/tests/smoke/src/server/registry.ts to use onWake/onSleep
Should fix: Rename internal methods #callOnStart → #callOnWake and #callOnStop → #callOnSleep for consistency
Should fix: Update log messages in the internal implementation to use new terminology
Consider: Update documentation files in a follow-up PR or include them here
Consider: Verify the driver files are calling the correct lifecycle methods

Overall, this is a good semantic improvement, but needs the smoke test fix before merging.

graphite-app · 2025-11-13T20:47:11Z

Merge activity

Nov 13, 8:47 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
Nov 13, 8:48 PM UTC: CI is running for this pull request on a draft pull request (#3463) due to your merge queue CI optimization settings.
Nov 13, 8:50 PM UTC: Merged by the Graphite merge queue via draft PR: #3463.

NathanFlurry mentioned this pull request Nov 9, 2025

chore(rivetkit): remove deprecated conn tokens & sse support #3419

Closed

NathanFlurry mentioned this pull request Nov 9, 2025

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

Closed

vercel bot deployed to Preview – rivetkit-serverless November 9, 2025 05:46 View deployment

NathanFlurry changed the base branch from 11-08-chore_rivetkit_split_actorinstance_logic_in_to_multiple_classes to graphite-base/3422 November 9, 2025 23:02

This was referenced Nov 9, 2025

refactor(rivetkit): add state manager for conn with symbol-based access #3423

Closed

chore(rivetkit): rename onFetch to onRequest #3424

Closed

chore(rivetkit): add connection for raw http #3425

Closed

chore(rivetkit): add conn type #3426

Closed

NathanFlurry changed the base branch from graphite-base/3422 to 11-08-chore_rivetkit_split_actorinstance_logic_in_to_multiple_classes November 10, 2025 00:18

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

8a57285

NathanFlurry force-pushed the 11-08-chore_rivetkit_rename_onstart_onstop_-_onwake_onsleep branch from 1386f17 to 8a57285 Compare November 13, 2025 02:47

vercel bot deployed to Preview – rivetkit-serverless November 13, 2025 02:48 View deployment

This was referenced Nov 13, 2025

chore(rivetkit-typescript): remove dependency on node modules #3460

Merged

chore(rivetkit): switch dynamic node imports to use require #3461

Merged

chore(rivetkit): fix type checks #3462

Merged

This was referenced Nov 13, 2025

feat(gas): implement smart pulling for horizontally scaled workers #3417

Merged

fix(guard): handle websocket tasks during shutdown #3448

Merged

fix: improve sigterm handling for the entire runtime #3443

Merged

NathanFlurry mentioned this pull request Nov 13, 2025

feat(gateway): websocket hibernation #3400

Merged

This was referenced Nov 13, 2025

fix(pb): dont immediately reallocate actors on runner stopping #3413

Merged

fix(guard): dont send open msg for hibernating ws, hibernating ws keepalive #3449

Merged

NathanFlurry mentioned this pull request Nov 13, 2025

chore(gas): rename wake sub to bump sub #3408

Merged

MasterPtato approved these changes Nov 13, 2025

View reviewed changes

graphite-app bot pushed a commit that referenced this pull request Nov 13, 2025

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

5b69257

graphite-app bot closed this Nov 13, 2025

graphite-app bot deleted the 11-08-chore_rivetkit_rename_onstart_onstop_-_onwake_onsleep branch November 13, 2025 20:50

This was referenced Nov 13, 2025

chore(rivetkit): implement new hibernating ws protocol #3464

Open

feat(cloudflare-workers): add createInlineClient #3466

Open

NicholasKissel mentioned this pull request Nov 15, 2025

chre: v4 website changes #3472

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

Uh oh!

NathanFlurry commented Nov 9, 2025

Uh oh!

vercel bot commented Nov 9, 2025 •

edited

Loading

Uh oh!

NathanFlurry commented Nov 9, 2025 •

edited by jog1t

Loading

Uh oh!

pkg-pr-new bot commented Nov 9, 2025 •

edited

Loading

Uh oh!

claude bot commented Nov 9, 2025

Uh oh!

claude bot commented Nov 13, 2025

Uh oh!

claude bot commented Nov 13, 2025

Uh oh!

graphite-app bot commented Nov 13, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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

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

Uh oh!

Conversation

NathanFlurry commented Nov 9, 2025

Uh oh!

vercel bot commented Nov 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NathanFlurry commented Nov 9, 2025 • edited by jog1t Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How to use the Graphite Merge Queue

Uh oh!

pkg-pr-new bot commented Nov 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude bot commented Nov 9, 2025

PR Review: Rename onStart/onStop to onWake/onSleep

Summary

Code Quality ✅

Potential Bugs ⚠️

Performance Considerations ✅

Security Concerns ✅

Test Coverage ✅

Recommendations

Conclusion

Uh oh!

claude bot commented Nov 13, 2025

PR Review: Rename onStart/onStop to onWake/onSleep

Overview

Code Quality ✅

1. Incomplete Refactoring - Internal Method Names ⚠️

2. Driver Implementation References ⚠️

Performance Considerations ✅

Security Concerns ✅

Best Practices 📋

Suggested Changes

Test Coverage ✅

Summary

Uh oh!

claude bot commented Nov 13, 2025

PR Review: Rename onStart/onStop to onWake/onSleep

Summary

Code Quality: ✅ Good

Issues Found: ⚠️ 1 Missing Update

Additional Observations

Performance: ✅ No Impact

Security: ✅ No Concerns

Test Coverage: ⚠️ Partially Complete

Recommendations

Uh oh!

graphite-app bot commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel bot commented Nov 9, 2025 •

edited

Loading

NathanFlurry commented Nov 9, 2025 •

edited by jog1t

Loading

pkg-pr-new bot commented Nov 9, 2025 •

edited

Loading

graphite-app bot commented Nov 13, 2025 •

edited

Loading