chore(core): impl rivet engine alarms

[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	Oct 1, 2025 4:28am

[claude]

Claude finished @NathanFlurry's task —— View job

---

Pull Request Review: Rivet Engine Alarms Implementation

I've completed my review of the rivet engine alarms implementation. Here's my comprehensive analysis:

Review Checklist

• Read project guidelines (CLAUDE.md)
• Analyze core actor instance changes
• Review router and endpoint modifications
• Examine driver implementations
• Evaluate test suite changes
• Check for potential bugs and security issues
• Assess performance implications
• Review test coverage
• Provide comprehensive feedback

---

🎯 Overall Assessment

This PR successfully implements alarm functionality for the RivetKit engine, enabling scheduled callbacks at specific timestamps. The implementation is comprehensive and well-tested, following the project's architectural patterns.

✅ Strengths

1. Comprehensive Implementation

• Alarm Scheduling: Robust scheduleEvent() method in ActorInstance with proper event queuing
• Persistence: Alarms survive actor restarts through scheduledEvents in persisted state
• Driver Integration: Clean integration with engine driver's setAlarm() method
• Test Coverage: Extensive test suite covering scheduling, execution order, and sleep interactions

2. Proper State Management

• Events stored in chronological order in persist.scheduledEvents
• Atomic alarm updates using dedicated #alarmWriteQueue
• State changes properly trigger persistence saves
• Clean conversion between internal and BARE schema formats

3. Robust Error Handling

• Individual alarm failures don't crash the actor (packages/rivetkit/src/actor/instance.ts:495-502)
• Structured error logging with context
• Graceful handling of missing/invalid action functions
• Early alarm firing protection with rescheduling logic

4. Performance Considerations

• Single timeout approach instead of multiple timers
• Efficient event insertion using findIndex()
• Queued alarm writes prevent race conditions
• Proper cleanup in actor stop sequence

⚠️ Issues & Concerns

1. Code Quality Issues

Debug Console Logs (packages/rivetkit/src/actor/router.ts:126,151)

console.log("===== point 1");
console.log("===== point 2");

These debug statements should be removed before merging.

Typo in Test (packages/rivetkit/src/driver-test-suite/tests/actor-sleep.ts:185)

// Wait until after SLEEPT_IMEOUT to validate the actor did not sleep

Should be SLEEP_TIMEOUT.

2. Potential Bugs

Race Condition Risk (packages/rivetkit/src/actor/instance.ts:427-449)

const runIndex = this.#persist.scheduledEvents.findIndex(
    (x) => x.timestamp <= now,
);
if (runIndex === -1) {
    // Events may have been scheduled between checks
}

If events are scheduled between the findIndex and the warning log, they could be lost.

Weak Error Boundaries (packages/rivetkit/src/actor/instance.ts:494)

await fn.call(undefined, this.actorContext, ...args);

Calling alarm functions with undefined context could cause issues if functions expect this binding.

3. Security Considerations

Action Name Validation - Missing validation that alarm action names correspond to actual actor actions, potentially allowing arbitrary function calls.

CBOR Deserialization (packages/rivetkit/src/actor/instance.ts:492) - No input validation on deserialized alarm arguments before passing to action functions.

4. Performance Concerns

Linear Search - findIndex() for event insertion is O(n), which could be slow with many scheduled events. Consider using a heap or sorted data structure.

No Rate Limiting - No protection against scheduling excessive numbers of alarms that could impact memory usage.

🔧 Recommendations

High Priority

1. Remove debug console logs from router.ts
2. Fix typo in sleep test comments
3. Add action validation - Verify alarm action names exist in actor config
4. Add input validation for deserialized alarm arguments

Medium Priority

1. Improve error handling - Use proper this context when calling alarm functions
2. Add rate limiting - Limit number of concurrent scheduled events per actor
3. Optimize data structure - Consider heap for better insertion performance
4. Enhanced logging - Add more structured logging for alarm lifecycle

Low Priority

1. Add JSDoc comments for public alarm-related APIs
2. Consider alarm cancellation - API to cancel scheduled alarms by ID
3. Add metrics - Track alarm execution success/failure rates

🧪 Test Coverage Assessment

The test suite is comprehensive and covers:

• ✅ Basic alarm scheduling and execution
• ✅ Multiple alarms in correct order
• ✅ Alarm-sleep interactions
• ✅ State persistence across restarts
• ✅ Error scenarios

📝 Final Verdict

This is a solid implementation that adds important alarm functionality to RivetKit. While there are some code quality issues and potential improvements, the core logic is sound and well-tested.

Recommendation: Approve with requested changes - Address the debug logs and typo before merging, consider the other recommendations for future iterations.

---

[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

• chore(core): impl rivet engine alarms #1320 👈 (View in Graphite)
• fix(serverless): read x-rivet-token from start endpoint #1315 : 2 other dependent PRs (#1316 , #1317 )
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• merge queue - adds this PR to the back of the merge queue
• hotfix - for urgent hot fixes, skip the queue and merge this PR next

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]

Claude finished @NathanFlurry's task —— View job

---

Pull Request Review: Rivet Engine Alarms Implementation

I've completed my comprehensive review of the rivet engine alarms implementation. Here's my detailed analysis:

Review Checklist

• Read project guidelines (CLAUDE.md)
• Analyze core actor instance changes
• Review router and endpoint modifications
• Examine driver implementations
• Evaluate test suite changes
• Check for potential bugs and security issues
• Assess performance implications
• Review test coverage
• Provide comprehensive feedback

---

🎯 Overall Assessment

This PR successfully implements alarm functionality for the RivetKit engine, enabling scheduled callbacks at specific timestamps. The implementation is comprehensive and well-tested, following the project's architectural patterns.

✅ Strengths

1. Comprehensive Implementation

• Alarm Scheduling: Robust scheduleEvent() method in ActorInstance with proper event queuing
• Persistence: Alarms survive actor restarts through scheduledEvents in persisted state
• Driver Integration: Clean integration with engine driver's setAlarm() method
• Test Coverage: Extensive test suite covering scheduling, execution order, and sleep interactions

2. Proper State Management

• Events stored in chronological order in persist.scheduledEvents
• Atomic alarm updates using dedicated #alarmWriteQueue
• State changes properly trigger persistence saves
• Clean conversion between internal and BARE schema formats

3. Robust Error Handling

• Individual alarm failures don't crash the actor (packages/rivetkit/src/actor/instance.ts:495-502)
• Structured error logging with context
• Graceful handling of missing/invalid action functions
• Early alarm firing protection with rescheduling logic

4. Performance Considerations

• Single timeout approach instead of multiple timers
• Efficient event insertion using findIndex()
• Queued alarm writes prevent race conditions
• Proper cleanup in actor stop sequence

⚠️ Issues & Concerns

1. Code Quality Issues

Typo in Test (packages/rivetkit/src/driver-test-suite/tests/actor-sleep.ts:185)

// Wait until after SLEEPT_IMEOUT to validate the actor did not sleep

Should be SLEEP_TIMEOUT.

2. Potential Bugs

Race Condition Risk (packages/rivetkit/src/actor/instance.ts:427-449)

const runIndex = this.#persist.scheduledEvents.findIndex(
    (x) => x.timestamp <= now,
);
if (runIndex === -1) {
    // Events may have been scheduled between checks
}

If events are scheduled between the findIndex and the warning log, they could be lost.

Weak Error Boundaries (packages/rivetkit/src/actor/instance.ts:494)

await fn.call(undefined, this.actorContext, ...args);

Calling alarm functions with undefined context could cause issues if functions expect this binding.

3. Security Considerations

Action Name Validation - Missing validation that alarm action names correspond to actual actor actions, potentially allowing arbitrary function calls.

CBOR Deserialization (packages/rivetkit/src/actor/instance.ts:492) - No input validation on deserialized alarm arguments before passing to action functions.

4. Performance Concerns

Linear Search - findIndex() for event insertion is O(n), which could be slow with many scheduled events. Consider using a heap or sorted data structure.

No Rate Limiting - No protection against scheduling excessive numbers of alarms that could impact memory usage.

🔧 Recommendations

High Priority

1. Fix typo in sleep test comments (SLEEPT_IMEOUT → SLEEP_TIMEOUT)
2. Add action validation - Verify alarm action names exist in actor config
3. Add input validation for deserialized alarm arguments

Medium Priority

1. Improve error handling - Use proper this context when calling alarm functions
2. Add rate limiting - Limit number of concurrent scheduled events per actor
3. Optimize data structure - Consider heap for better insertion performance
4. Enhanced logging - Add more structured logging for alarm lifecycle

Low Priority

1. Add JSDoc comments for public alarm-related APIs
2. Consider alarm cancellation - API to cancel scheduled alarms by ID
3. Add metrics - Track alarm execution success/failure rates

🧪 Test Coverage Assessment

The test suite is comprehensive and covers:

• ✅ Basic alarm scheduling and execution
• ✅ Multiple alarms in correct order
• ✅ Alarm-sleep interactions
• ✅ State persistence across restarts
• ✅ Error scenarios

📝 Final Verdict

This is a solid implementation that adds important alarm functionality to RivetKit. While there are some code quality issues and potential improvements, the core logic is sound and well-tested.

Recommendation: Approve with requested changes - Address the typo and consider the other recommendations for future iterations.

---

View job

[graphite-app]

Merge activity

• Oct 1, 4:29 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Oct 1, 4:30 AM UTC: CI is running for this pull request on a draft pull request (#1321) due to your merge queue CI optimization settings.
• Oct 1, 4:31 AM UTC: Merged by the Graphite merge queue via draft PR: #1321.