fix(actor-kv): fix listing keys

[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	Error			Nov 19, 2025 1:29am

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Nov 19, 2025 1:29am
rivet-inspector	Ignored	Preview		Nov 19, 2025 1:29am
rivet-site	Ignored	Preview		Nov 19, 2025 1:29am

[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(rivetkit): implement new hibernating ws protocol #3464
• fix(actor-kv): fix listing keys #3484 👈 (View in Graphite)
• fix(guard): handle actor stopped during ws/req #3481
• chore: rename retry -> hibernate in runner protocol #3473 : 1 other dependent PR (#3475 )
• fix(udb): update backoff algo #3469
• chore: write/update docs #3468
• chore: add debug scripts #3467
• 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]

Code Review: Fix listing keys in actor-kv

Overall, this is a solid PR that addresses a critical bug in the KV list operation. The implementation is well-tested and the fix is logical.

Strengths

Excellent Test Coverage

• Comprehensive test suite with 375+ lines of edge case testing
• Tests cover all query types with various edge cases
• Good coverage of limit behavior, reverse ordering, and boundary conditions

Clear Documentation

• Added helpful documentation to KeyWrapper and ListKeyWrapper
• Comments explain the logic behind the prefix query fix

Correct Bug Fix

• The limit check was moved to the right place (before adding entries)
• This prevents off-by-one errors

Issues and Concerns

1. Potential Bug in Prefix Query (lib.rs:336-354)

The prefix query assumes tuple encoding adds a trailing 0 byte:

if let Some(&0) = start.last() {
    start.pop();
}

This assumption should be verified with tests that check the encoded bytes directly.

2. 0xFF Byte Handling

Test acknowledges but doesn't fix the issue where keys with 0xFF bytes may not match prefixes correctly. This should either be:

• Documented as a known limitation
• Fixed in the implementation
• Rejected via validation

3. Import Style Violation (lib.rs:3)

use anyhow::*; violates CLAUDE.md guidelines. Should be: use anyhow::{bail, Context, Result};

4. Test Assertions

Could include actual values in assertion messages for easier debugging.

Recommendations

Must fix:

1. Fix the glob import from anyhow

Should fix:
2. Document or fix the 0xFF byte limitation
3. Add verification test for encoding assumptions

Nice to have:
4. Enhanced assertion messages with actual values

This is a good PR that fixes an important bug. After addressing the glob import and clarifying the 0xFF behavior, it will be ready to merge!

[claude]

Code Review

Summary

This PR fixes a critical bug in the actor-kv package's key listing functionality and adds comprehensive test coverage. The changes address issues with prefix queries and list limiting behavior.

---

✅ Positive Aspects

1. Excellent Test Coverage: The addition of two comprehensive test files (kv_operations.rs and list_edge_cases.rs) is outstanding. These tests cover:

   • Basic CRUD operations
   • Edge cases with null bytes, 0xFF bytes, empty prefixes
   • Limit and reverse operations
   • Large value chunking
   • Range query boundaries

2. Clear Documentation: The enhanced comments in key.rs clearly explain when to use KeyWrapper vs ListKeyWrapper, which is very helpful for maintainability.

3. Critical Bug Fix: The limit check logic in list() (lines 175-179 and 208-215 in lib.rs) now correctly prevents exceeding the limit by checking before adding entries, not after.

---

🐛 Potential Issues

Critical: Prefix Query Logic May Be Incorrect

In lib.rs:336-355, the prefix query implementation has a significant issue:

let mut start = subspace.pack(&ListKeyWrapper(prefix.key.clone()));
// Remove the trailing 0 byte that tuple encoding adds to strings
if let Some(&0) = start.last() {
    start.pop();
}

let mut end = start.clone();
end.push(0xFF);

Problem: This assumes tuple encoding always adds a trailing 0 byte, but:

• The ListKeyWrapper does NOT add a NIL byte (by design, see line 77 in key.rs)
• The Bytes type inside ListKeyWrapper.pack() might add a 0x00 terminator, but this depends on the encoding of byte strings in your tuple implementation
• If the key ends with 0x00 naturally, this would incorrectly remove it

Recommendation:

• Either verify that Bytes::pack() always adds a trailing 0 for byte strings, or
• Use a more explicit approach that doesn't rely on stripping bytes

The test at line 253 in list_edge_cases.rs notes that keys with 0xFF may not match prefixes correctly, which suggests this approach has edge case issues.

Medium: Comment Inconsistency in entry.rs

Line 63 in entry.rs:

Ok((&input[0..0], v))

This returns an empty slice by taking a zero-length slice from the input. While this works, it's unusual and may be confusing. The comment "Parses key in first position, ignores the rest" doesn't clearly explain why we return an empty remaining slice. Consider adding a comment explaining this is intentional to consume all remaining input.

---

🔍 Security Considerations

1. ✅ No Security Issues Identified: The validation logic in utils.rs properly enforces:

   • Key size limits (2KB)
   • Value size limits (128KB)
   • Total payload limits (976KB)
   • Storage quota (1GB)

2. ✅ No Injection Risks: The use of tuple encoding for keys prevents injection attacks.

---

⚡ Performance Considerations

1. Potential Inefficiency: In lib.rs:345-349, the code calls both .pack() and then manually manipulates the bytes. Consider whether there's a cleaner way to construct the range without the pop() operation.

2. ✅ Good: The chunking approach (10KB chunks) is well-designed for large values.

3. ✅ Good: The limit check optimization prevents unnecessary data retrieval.

---

🧪 Testing

Strengths:

• Comprehensive edge case coverage
• Tests for limit boundary conditions
• Tests for special byte values (0x00, 0xFF)
• Tests for empty prefixes and ranges

Suggestions:

1. Add a test that verifies prefix queries work correctly when the prefix itself ends with 0x00
2. Add a test for concurrent put/get operations to verify transaction isolation
3. Consider adding property-based tests using proptest or quickcheck for the key encoding logic

---

📝 Style & Convention Notes

Per CLAUDE.md:

1. ✅ Logging: Proper use of structured logging with tracing::info!(?x, "message")
2. ✅ Error Handling: Correctly returns anyhow::Result
3. ✅ Dependencies: Proper use of workspace dependencies in Cargo.toml
4. ✅ Naming: Lowercase log messages as specified

---

🎯 Recommendations

Must Fix Before Merge:

1. Verify and document the prefix query byte manipulation logic. Add explicit tests showing the behavior with keys ending in 0x00.

Nice to Have:

1. Add inline comment in entry.rs:63 explaining the &input[0..0] pattern
2. Consider extracting the prefix range construction into a separate tested function

---

Overall Assessment

This is a high-quality PR that fixes an important bug and adds excellent test coverage. The main concern is the prefix query implementation which needs verification/clarification. Once that's addressed, this should be ready to merge.

Approval Status: Approve with minor concerns (pending verification of prefix query logic)

---

Review generated by Claude Code

[claude]

Code Review

Overview

This PR fixes a critical bug in the actor KV store's list operation where the limit was not being enforced correctly, and adds comprehensive test coverage. The changes are well-structured and address real issues with prefix queries and limit handling.

---

✅ Strengths

1. Excellent test coverage: The two new test files (kv_operations.rs and list_edge_cases.rs) are comprehensive and cover a wide range of scenarios including basic CRUD operations, limit enforcement, reverse listing, prefix queries with various patterns, edge cases (empty datasets, null bytes, 0xFF bytes, etc.), and large value chunking.

2. Clear documentation: The added comments in key.rs clearly explain the difference between KeyWrapper and ListKeyWrapper, which is crucial for understanding the tuple encoding behavior.

3. Bug fix is correct: The limit enforcement fix in lib.rs:175-179 and lib.rs:207-216 properly checks the limit before adding entries, preventing off-by-one errors.

4. Proper dependency management: Test dependencies are correctly added to [dev-dependencies] with workspace references.

---

🔍 Issues & Concerns

Critical: Potential Prefix Query Bug

Location: engine/packages/actor-kv/src/lib.rs:336-355

The prefix query implementation has concerning logic where it attempts to remove a trailing 0 byte from the packed key. This is problematic because:

1. Incorrect assumption: The comment states "tuple encoding adds a terminating 0 byte to strings", but ListKeyWrapper is designed specifically NOT to add a trailing NIL byte. The TuplePack implementation in key.rs:64-80 shows it only adds NESTED code and the packed bytes - no NIL byte.

2. Risk of removing user data: If you pop a legitimate 0 byte from the user's key (e.g., prefix is ending in \x00), the prefix query would return incorrect results.

Recommendation:

• Verify that ListKeyWrapper packing actually produces what you expect through unit tests
• Add specific tests for prefixes ending in 0x00 to verify correctness
• If the trailing 0 is from tuple encoding of the Bytes type itself, document this explicitly

---

Minor Issues

1. Inconsistent import pattern (lib.rs:3): The import of std::result::Result::Ok is unusual and potentially confusing.

2. Weak test assertion (list_edge_cases.rs:261-267): The test uses >= 3 instead of == 4 when checking prefix matches, which means it would pass even if the bug still exists.

---

📊 Summary

Category	Rating	Notes
Bug Fix	✅ Good	Limit enforcement is correctly fixed
Test Coverage	✅ Excellent	Comprehensive tests for most scenarios
Code Quality	⚠️ Fair	Some concerns with prefix query logic
Documentation	✅ Good	Clear comments on key wrappers
Security	✅ Good	Proper validation, no injection risks

Overall: Approve with recommendations. The core bug fix is correct and the test coverage is excellent. However, the prefix query implementation should be reviewed carefully before merging.