feat(rivetkit): c.keepAwake

[NathanFlurry]

No description provided.

[NathanFlurry]

• feat(rivetkit): add clearAlarm #4004
• feat(rivetkit): c.keepAwake #4003 👈 (View in Graphite)
• 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: feat(rivetkit): c.keepAwake

Summary

This PR improves the documentation and discoverability of the keepAwake API, which prevents Rivet Actors from sleeping during async operations. The changes primarily focus on clarifying when and how to use keepAwake vs waitUntil.

Code Quality: ✅ Good

Strengths:

• Documentation is clear and follows the repository's style guide
• The API surface is unchanged - only documentation improvements
• Good use of concrete examples showing real-world usage patterns
• Proper error propagation is maintained

Documentation Improvements:

1. Added important warning to run handler JSDoc about sleep interruption
2. Clarified that keepAwake should wrap async operations to prevent sleep
3. Reorganized documentation to put keepAwake before waitUntil (better pedagogical order)
4. Removed confusing comparison table that may have implied keepAwake was only for "tracked background work"

Potential Issues: ⚠️ Minor Concerns

1. Documentation Example Could Be Misleading

The example in lifecycle.mdx shows wrapping a fetch call but doesn't clarify that the actor could still sleep after this line if subsequent async operations aren't wrapped. Consider adding a note about this behavior.

2. Missing Test Coverage

keepAwake has no dedicated test coverage. Consider adding tests for:

• Actor doesn't sleep while keepAwake promise is pending
• Sleep timer resets on completion
• Errors propagate correctly
• Multiple concurrent keepAwake calls work correctly
• activeKeepAwakeCount tracking

3. Removed Context May Be Valuable

The removed comparison table helped developers choose between APIs. Consider incorporating key differences into prose.

Performance: ✅ No concerns

No runtime changes, documentation only.

Security: ✅ No concerns

No security implications.

Suggestions

1. Clarify Sleep Behavior in Long-Running run Handlers

Consider explicitly showing whether the 5-second setTimeout could be interrupted by sleep.

2. Add a "When to Use" Guide

• Use keepAwake when: You need the result AND want to prevent sleep
• Use waitUntil when: Fire-and-forget AND don't care about errors
• Use neither when: You want the actor to be able to sleep

3. Consider Renaming Section

"Preventing Sleep with keepAwake" could be "Managing Async Operations" to better capture both patterns.

Verdict: ✅ Approve with Suggestions

The changes are valuable and improve the developer experience. My suggestions are minor enhancements that could be addressed in follow-up PRs.

Recommendation: Merge after addressing test coverage concerns, or create a follow-up issue to add tests for keepAwake.

[graphite-app]

Merge activity

• Feb 4, 8:37 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Feb 4, 8:38 PM UTC: The Graphite merge queue removed this pull request due to downstack failures on PR #4002.
• Feb 4, 8:38 PM UTC: The Graphite merge queue removed this pull request due to downstack failures on PR #4002.