feat: actor messages & queues

[NathanFlurry]

No description provided.

[railway-app]

🚅 Deployed to the rivet-pr-3989 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
frontend-inspector	❌ Build Failed (View Logs)	Web	Jan 21, 2026 at 1:44 am
frontend-cloud	❌ Build Failed (View Logs)	Web	Jan 21, 2026 at 1:43 am
website	😴 Sleeping (View Logs)	Web	Jan 21, 2026 at 1:09 am

[NathanFlurry]

• feat: actor messages & queues #3989 👈 (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]

Review of PR #3989: Actor Messages & Queues

This PR adds a message queue system to RivetKit actors. Overall, the implementation is well-structured with good separation of concerns. Here are my findings:

✅ Strengths

1. Clean Architecture: Queue functionality is properly separated into QueueManager (internal) and ActorQueue (user-facing API)
2. Comprehensive Testing: Good test coverage in actor-queue.ts including edge cases (timeouts, aborts, size limits)
3. Versioning: Proper schema versioning with v4 of actor-persist and v3 of client-protocol
4. Error Handling: Well-defined custom errors (QueueFull, QueueMessageTooLarge, QueueMessageInvalid, ActorAborted)
5. Type Safety: Good use of TypeScript generics and overloaded signatures in ActorQueue.next()

🐛 Potential Issues

High Priority

1. Race Condition in Metadata Updates (queue-manager.ts:129-138)

   • The code updates in-memory metadata before the KV write completes
   • If the batch write fails, in-memory state becomes inconsistent with storage
   • Fix: Only update in-memory metadata after successful write, or revert on failure

   // Current (risky):
   this.#metadata.nextId = id + 1n;
   this.#metadata.size += 1;
   const encodedMetadata = this.#serializeMetadata();
   await this.#driver.kvBatchPut(this.#actor.id, [...]);
   
   // Better:
   const newMetadata = {
       nextId: id + 1n,
       size: this.#metadata.size + 1
   };
   const encodedMetadata = this.#serializeMetadata(newMetadata);
   await this.#driver.kvBatchPut(this.#actor.id, [...]);
   this.#metadata = newMetadata; // Only update after success

2. Message Ordering Not Guaranteed (queue-manager.ts:246-278)

   • kvListPrefix returns entries, but sorting relies on BigInt ID comparison
   • No guarantee that IDs are assigned in the order messages arrive if there are concurrent enqueues
   • Consider documenting this behavior or adding sequence numbers

3. Unbounded Waiter Growth (queue-manager.ts:45)

   • No limit on number of concurrent waiters
   • A malicious actor could create thousands of waiters and cause memory issues
   • Recommendation: Add maxConcurrentWaiters config option

Medium Priority

4. Missing Cleanup on Actor Stop (queue-manager.ts)

   • No explicit cleanup method to reject pending waiters when actor stops unexpectedly
   • The abort signal handling (lines 204-209) helps, but there's no cleanup of timeout handles if the manager is destroyed
   • Recommendation: Add a destroy() method that clears all waiters and their timeouts

5. Inefficient Queue Draining (queue-manager.ts:228-244)

   • #drainMessages loads ALL messages from storage, then filters in memory
   • For large queues (up to 1000 messages), this is wasteful
   • Optimization: Consider adding a way to filter at the storage layer, or at least batch the loading

6. Error Handling in Message Loading (queue-manager.ts:266-271)

   • Corrupted messages are silently logged but not tracked
   • Could lead to confusion if messages are "lost" due to corruption
   • Recommendation: Consider exposing corruption metrics or warnings to the user

7. Metadata Rebuild Logic (queue-manager.ts:327-353)

   • Only scans for max ID, doesn't validate message integrity
   • The size is based on entry count, which could include corrupted entries
   • Consider validating at least one message to ensure the schema is correct

Low Priority

8. Timestamp Precision (queue-manager.ts:107)

   • Uses Date.now() which returns milliseconds
   • Per CLAUDE.md conventions, timestamps should be "i64 epoch timestamps in milliseconds" ✓
   • This is correct, no issue

9. Magic Number (keys.ts:10)

   • QUEUE_ID_BYTES = 8 is defined separately
   • Consider adding a comment explaining why 8 bytes (supports 2^64 messages)

10. Proxy Implementation (queue.ts:87-124)

    • The queue proxy is clever but the has trap always returns true for strings
    • This could lead to confusing behavior with in operator
    • Consider being more selective about what properties are claimed to exist

🔒 Security Considerations

1. Message Size Validation: ✅ Properly validates message size before storage
2. CBOR Serialization Check: ✅ Validates serializability before encoding
3. Queue Size Limits: ✅ Enforces configurable limits
4. Path Traversal: N/A - queue names are not used in file paths
5. Injection: ✅ Queue names are strings, properly encoded

⚡ Performance Considerations

1. Batch Operations: ✅ Good use of kvBatchPut and kvBatchDelete to minimize round trips
2. Metadata Caching: ✅ Keeps size in memory, good for frequent checks
3. Message Filtering: ⚠️ See issue [SVC-2358] Enable Redis memory overcommit #5 above - could be optimized
4. Waiter Resolution: ✅ Efficiently iterates only active waiters

📋 Code Quality

1. Follows CLAUDE.md:

   • ✅ Uses lowercase log messages
   • ✅ Uses structured logging with ? prefix
   • ✅ Timestamp named createdAt (correct convention)
   • ✅ Complete sentences in comments
   • ❌ Import issue: router-endpoints.ts:45 imports after imports (minor)

2. Type Safety: ✅ Excellent use of TypeScript

3. Documentation: ⚠️ User-facing API has JSDoc, but internal methods lack comments explaining complex logic

4. Testing: ✅ Good test coverage of happy paths and error cases

📝 Recommendations

1. Fix the metadata race condition (issue [SVC-2555] Set up issue templates #1) before merging - this could cause data loss
2. Add waiter limits to prevent DoS scenarios
3. Document message ordering guarantees (or lack thereof) in the API docs
4. Add cleanup/destroy method for proper resource management
5. Consider optimizing the queue draining for large queues
6. Add JSDoc comments to complex internal methods like #maybeResolveWaiters

📊 Test Coverage

The test suite covers:

• ✅ Basic send/receive
• ✅ Multiple queue names
• ✅ Timeout behavior
• ✅ Abort signals
• ✅ Size limits
• ✅ Message size limits

Missing tests:

• ❌ Concurrent enqueue/dequeue scenarios
• ❌ Metadata corruption recovery
• ❌ Actor restart with pending messages
• ❌ Multiple waiters on same queue

Overall Assessment

This is a solid implementation with good architecture and test coverage. The main concern is the metadata race condition which should be addressed before merging. The other issues are mostly optimization opportunities and defensive programming improvements.

Recommendation: Request changes for issue #1, recommend addressing issues #3-4 before merge.