chore(rivetkit): add debug logging around sleep condition

[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 4, 2025 8:26pm

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Nov 4, 2025 8:26pm
rivet-inspector	Ignored	Preview		Nov 4, 2025 8:26pm
rivet-site	Ignored	Preview		Nov 4, 2025 8:26pm

[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

• ci: trigger rust ci for generated bare artifacts #3346
• chore(rivetkit): debounce ws message ack #3345
• chore(rivetkit): auto-update auto-start engine version #3344
• chore(guard): handle cors on the gateway #3341
• chore(guard): add support for routing runner ws to /runners/connect #3340
• chore(guard): simplify gateway routing #3339
• fix(guard): include method in cache key #3338
• chore(engine): move smoke test to engine/tests/ #3337
• chore(rivetkit): add debug logging around sleep condition #3336 👈 (View in Graphite)
• fix(rivetkit): fix conns not being cleaned up if actor.createConn errors #3335
• fix(rivetkit): fix not pino bindings #3334
• chore(rivetkit): fmt #3331
• chore(rivetkit): correctly stringify engine runner request ids for logs #3330
• fix(rivetkit): ack ws messages #3329
• chore(runner): decrease timeout to 15s #3328
• chore(pegboard): log explicit gc reason for pending requests #3327
• fix(pegboard): fix tunnel ack from gateway #3326
• fix(rivetkit): explicitly handle errors in _onStop #3325
• chore(rivetkit): document sleep sequence better #3324
• fix(runner): close active requests after onActorStop has finished running #3323
• fix(runner): fix http requests not returning 503 when actor removed #3322
• fix(runner): dupe onActorStop call #3321
• chore: add rivetkit test writer agent #3320
• fix(rivetkit): prevent sleeping if there are any action hono requests, fixes inspector requests not resetiting sleep timer #3319
• chore(rivetkit): pass request id from driver to conn so we can correlate underlying requests with connections #3318
• chore(rivetkit): improve conn inspector properties #3317
• fix(rivetkit): don't throw error if websocket is not open, causing realtime to break after a connection disconnects #3316
• chore(smoke-test): add simple http test #3315
• chore(scripts): tee run logs to file #3314
• chore(engine): add db nuke subcommand #3313
• fix(rivetkit): fix "Method get ArrayBuffer.prototype.byteLength called on incompatible receiver #<ArrayBuffer>" #3312
• chore(scripts): add engine shell command #3311
• chore: set minimum node version to 20 #3310
• fix(fe): show connect page when there are no runner configs but runner names #3298 : 1 other dependent PR (#3306 )
• chore(rivetkit): log version with error logs #3303
• chore(rivetkit): log close code & reason in disconnect warning #3302
• feat(rivetkit): integrate websocket hibernation #3301
• fix: use correct vbare functions for runner tunnel #3300 : 1 other dependent PR (#3332 )
• feat(grafana): fix api dashboards #3193
• fix: docker compose build #3273
• chore: fix remaining warnings for all targets #3305
• fix(gas): fix from_workflow when creating standalone ctx from op ctx #3342
• ci: udpate ci filter to succeed if no relevant changes #3343
• 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: Add debug logging around sleep condition

Overview

This PR improves observability of the actor sleep mechanism by converting the boolean #canSleep() method to return an enum that indicates why the actor cannot sleep, rather than just whether it can or cannot. This is a solid debugging improvement.

✅ Strengths

1. Better Observability: The enum approach makes debugging much easier by exposing the specific reason an actor cannot sleep in logs
2. Clean Refactoring: The logic is reorganized to check conditions in a clearer order (ready → HTTP requests → websockets → connections)
3. Type Safety: Using an enum instead of a boolean provides better type checking and makes the code more self-documenting

📝 Code Quality

Good practices observed:

• Enum values are descriptive and self-explanatory
• The logging now uses CanSleep[canSleep] to get the string representation
• The comparison is explicit: canSleep === CanSleep.Yes
• Early returns make the flow easier to follow

🔍 Observations & Suggestions

1. Check order rationalization

The PR changes the order of checks from:

• Old: ready → connections → HTTP requests → websockets
• New: ready → HTTP requests → websockets → connections

Question: Is there a specific reason for checking HTTP requests and websockets before connections now? If the connection check is more expensive (iterating through a Map), this could be an optimization. Otherwise, it might be worth keeping the original order or documenting the rationale.

2. Enum naming convention

The enum uses TypeScript default numeric values (0, 1, 2, 3, 4). Consider making it explicit if specific values matter:

enum CanSleep {
  Yes = 0,
  NotReady = 1,
  ActiveConns = 2,
  ActiveHonoHttpRequests = 3,
  ActiveRawWebSockets = 4,
}

This is minor and not required since TypeScript handles it correctly, but it can improve readability.

3. Consider const enum for tree-shaking

If performance is critical, consider using const enum to avoid runtime overhead:

const enum CanSleep {
  Yes,
  NotReady,
  ActiveConns,
  ActiveHonoHttpRequests,
  ActiveRawWebSockets,
}

However, this would prevent the CanSleep[canSleep] string lookup in logs, so you would need to handle that differently.

🐛 Potential Issues

None identified - The logic appears sound and is equivalent to the previous implementation.

🔒 Security Considerations

No security concerns - this is purely a debugging/observability change.

⚡ Performance Considerations

The change should have negligible performance impact:

• Returning an enum value vs boolean is essentially the same cost
• The reordering of checks could be slightly more efficient if connections iteration is expensive
• The enum string lookup in logging only happens when debug logging is enabled

🧪 Test Coverage

Recommendation: Consider adding or updating tests to verify:

1. The sleep timer is correctly set/cleared based on different CanSleep states
2. Debug logs include the correct CanSleep reason (if you have log testing infrastructure)

✨ Overall Assessment

This is a clean, low-risk improvement that will make debugging actor sleep issues significantly easier. The code quality is good, and the change is well-focused on its goal.

Recommendation: ✅ Approve (with minor suggestions for consideration)

---

Generated with Claude Code

[claude]

Code Review

Summary

This PR improves debuggability of the actor sleep mechanism by converting the canSleep method from returning a boolean to returning an enum that indicates why sleep is blocked.

Positive Aspects

1. Improved Debuggability
The enum-based approach makes it significantly easier to diagnose why actors aren't sleeping. Instead of seeing canSleep: false, developers now see specific reasons like canSleep: ActiveHonoHttpRequests.

2. Better Code Organization
The refactored canSleep method now checks conditions in a logical order (ready state, HTTP requests, WebSockets, connections), making it easier to understand the sleep eligibility criteria.

3. Early Returns for Clarity
Each blocking condition returns immediately with a specific enum value, making the control flow clearer and easier to follow.

4. No Behavioral Changes
The refactoring is purely for observability - the actual sleep logic remains unchanged, reducing risk.

Suggestions for Improvement

1. Consider Adding Trace-Level Logging
The canSleep method is called frequently. Consider adding a trace-level log inside canSleep itself to capture the decision logic, which would help trace timing issues where the sleep state changes rapidly.

2. Test Coverage Consideration
While I don't see existing tests for the sleep mechanism, this refactoring doesn't change behavior so the risk is low. However, consider adding tests that verify:

• canSleep returns correct enum values under different conditions
• The sleep timer is properly set or cleared based on the return value
• Debug logs contain the expected enum string

Security and Performance

Security: No security concerns. The change is purely internal logging.

Performance: No performance impact. The enum comparison is as efficient as the previous boolean check. The enum-to-string conversion only happens during logging.

Potential Issues

None identified. The refactoring is clean and maintains backward compatibility while improving observability.

Conclusion

This is a well-executed refactoring that improves developer experience without introducing risk. The code quality is high and follows TypeScript best practices.

Recommendation: Approve with the optional suggestions above for future consideration.

[vercel]

Deployment failed with the following error:

Too many requests - try again in 4 minutes (more than 120, code: "api-deployments-flood-pro").

Learn More: https://vercel.com/docs/limits#rate-limits

[claude]

Code Review for PR #3336

Summary

This PR adds debug logging around the sleep condition by introducing a CanSleep enum to provide more detailed information about why an actor can or cannot sleep. This is a good debugging improvement!

✅ Strengths

1. Better Observability: The CanSleep enum provides much clearer debugging information than a boolean return value. Now logs will show exactly why an actor cannot sleep (e.g., "NotReady", "ActiveConns", "ActiveHonoHttpRequests", "ActiveRawWebSockets").

2. Early Returns for Readability: The refactored #canSleep() method now checks conditions in order with early returns, making the logic easier to follow.

3. No Behavioral Changes: This is purely a refactoring for observability - the actual sleep logic remains unchanged, which reduces risk.

🔍 Observations & Suggestions

1. Condition Check Order Change

The order of checks has been modified:

• Before: ready → connections → HTTP requests → WebSockets
• After: ready → HTTP requests → WebSockets → connections

While this doesn't affect correctness (all conditions are still checked), the original order had connections first, which the comment mentions "will also cover active actions". Consider if there's a performance reason to check connections first, as it might be the most common blocker.

2. Type Safety Consideration

The enum-to-string conversion in the log statement:

canSleep: CanSleep[canSleep]

This works, but TypeScript enums can have quirks. Consider using a more explicit approach if you encounter issues:

canSleep: CanSleep[canSleep] as string

Or define the enum as a const enum for better tree-shaking:

const enum CanSleep { ... }

3. Missing Test Coverage

I couldn't find tests for the sleep functionality. Consider adding tests to verify:

• Each CanSleep state is returned correctly under the right conditions
• The debug log contains the expected enum string values
• The sleep timer is set/cleared appropriately based on the CanSleep state

4. Enum Naming Convention

The enum name CanSleep reads a bit awkwardly with values like CanSleep.Yes. Consider alternatives like:

• SleepStatus (with values: Allowed, BlockedNotReady, BlockedActiveConns, etc.)
• SleepEligibility
• ActorSleepState

This is a minor naming preference, but SleepStatus.Allowed reads more naturally than CanSleep.Yes.

🎯 Code Quality

• ✅ Follows TypeScript conventions
• ✅ Maintains existing logic without breaking changes
• ✅ Improves debugging capabilities
• ⚠️ Could benefit from test coverage

Verdict

LGTM with minor suggestions. This is a solid debugging improvement that will make it much easier to diagnose sleep-related issues. The suggestions above are non-blocking improvements to consider for future iterations.

Great work on improving observability! 👍

[graphite-app]

Merge activity

• Nov 4, 8:10 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Nov 4, 8:11 PM UTC: CI is running for this pull request on a draft pull request (#3349) due to your merge queue CI optimization settings.
• Nov 4, 8:41 PM UTC: The Graphite merge queue removed this pull request due to removal of a downstack PR #3342.
• Nov 4, 8:53 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Nov 4, 8:53 PM UTC: CI is running for this pull request on a draft pull request (#3353) due to your merge queue CI optimization settings.
• Nov 4, 8:56 PM UTC: Merged by the Graphite merge queue via draft PR: #3353.

[claude]

Code Review

Thanks for this PR! This is a solid improvement that adds better observability for the sleep condition logic. Here's my detailed review:

✅ Strengths

1. Improved Debugging: The enum-based approach provides much better debug logging output. Instead of just true/false, we now get meaningful strings like "ActiveConns" or "ActiveHonoHttpRequests" which makes troubleshooting sleep issues much easier.

2. Better Code Organization: Reordering the checks in #canSleep() to perform the cheaper checks first (activeHonoHttpRequests, activeRawWebSockets) before the more expensive loop over connections is a good optimization.

3. Type Safety: Using an enum instead of boolean return values makes the code more maintainable and self-documenting. Each early return now clearly states WHY sleeping is blocked.

4. Consistent Pattern: The enum values clearly map to the conditions being checked, making the logic easy to follow.

💡 Suggestions

1. Minor: TypeScript Enum vs Const Enum

   • Consider using const enum instead of enum if you want to eliminate the enum object at runtime (TypeScript will inline the values). This would be a micro-optimization:

   const enum CanSleep {
       Yes,
       NotReady,
       ActiveConns,
       ActiveHonoHttpRequests,
       ActiveRawWebSockets,
   }

   • However, the current approach is fine if you need the reverse mapping for debug logging (which you're using with CanSleep[canSleep]).

2. Optional: Consider More Descriptive Log Message

   • The debug log could potentially include the actual counts when relevant:

   this.#rLog.debug({
       msg: "resetting sleep timer",
       canSleep: CanSleep[canSleep],
       existingTimeout: !!this.#sleepTimeout,
       timeout: this.#config.options.sleepTimeout,
       activeHonoHttpRequests: this.#activeHonoHttpRequests,
       activeRawWebSockets: this.#activeRawWebSockets.size,
       activeConnections: this.#connections.size,
   });

   • This would provide even more context when debugging, but it's not critical.

🔍 Code Quality

• ✅ No bugs identified
• ✅ Logic is preserved from the original implementation
• ✅ Performance improved with check reordering
• ✅ Type safety maintained
• ✅ No security concerns
• ✅ Follows TypeScript best practices

📝 Documentation

The existing comments and TODO notes are preserved and still accurate. The code is self-documenting with the enum names.

Overall Assessment

This is a clean refactor that improves debuggability without changing functionality. The change is low-risk and provides real value for troubleshooting sleep-related issues. Approved! ✅

[claude]

Code Review

Summary

This PR improves debugging capabilities for the actor sleep mechanism by introducing a CanSleep enum to provide better visibility into why an actor can or cannot sleep. Overall, this is a well-executed improvement that enhances observability.

Positive Changes ✅

1. Enhanced Debugging: The introduction of the CanSleep enum significantly improves debugging by providing clear, human-readable reasons why an actor cannot sleep (e.g., NotReady, ActiveConns, ActiveHonoHttpRequests, ActiveRawWebSockets).

2. Better Log Readability: Using CanSleep[canSleep] in the debug log (line 1924) converts the enum value to a string, making logs much more interpretable than boolean values.

3. Improved Code Structure: Reorganizing the checks in #canSleep() to return early with specific enum values makes the logic clearer and easier to follow.

4. Type Safety: Changing from boolean to enum return type provides stronger type safety and makes the intent explicit at the call site (canSleep === CanSleep.Yes).

Suggestions for Improvement 💡

1. Enum Ordering: The check order in #canSleep() doesn't match the enum declaration order. Consider reordering the enum to match the check sequence for consistency:

   • Current enum order: Yes, NotReady, ActiveConns, ActiveHonoHttpRequests, ActiveRawWebSockets
   • Actual check order: NotReady, ActiveHonoHttpRequests, ActiveRawWebSockets, ActiveConns, Yes

2. Additional Context in Logs: Consider enhancing the debug log to include the count of blocking resources when sleep is prevented (e.g., number of active HTTP requests, WebSocket count, connection count). This would provide even more debugging context.

Code Quality ✅

• Style: Code follows TypeScript conventions
• Logic: The refactoring maintains exact functional equivalence with the previous implementation
• Readability: Significant improvement in code clarity

Testing Considerations 🧪

• The changes are purely refactoring with no behavior modification
• Existing tests should continue to pass without changes
• Consider adding tests that verify log output includes the expected CanSleep reason strings if log testing infrastructure exists

Security & Performance ⚡

• No security concerns: This is a debugging enhancement with no security implications
• No performance impact: The enum comparison has negligible overhead compared to boolean checks

Conclusion

This is a solid improvement that will make debugging sleep-related issues much easier. The code is clean and well-structured. Consider the optional suggestions above for even better observability.

Recommendation: ✅ Approve