chore: rename retry -> hibernate in runner protocol

[MasterPtato]

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 18, 2025 11:52pm

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Nov 18, 2025 11:52pm
rivet-inspector	Ignored	Preview		Nov 18, 2025 11:52pm
rivet-site	Ignored	Preview		Nov 18, 2025 11:52pm

[MasterPtato]

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: rename retry -> hibernate in runner protocol #3473 : 2 dependent PRs (#3475 , #3481 ) 👈 (View in Graphite)
• 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

Summary

This PR performs a straightforward renaming of the retry field to hibernate in the runner protocol's ToServerWebSocketClose message. The change improves semantic clarity by better describing the field's purpose: indicating whether a WebSocket connection should enter a hibernation state rather than fully close.

Positive Aspects ✅

1. Semantic Clarity: The rename from retry to hibernate is a good improvement. The new name more accurately describes the behavior - the connection is entering a hibernation state that can be resumed, rather than a simple retry.

2. Comprehensive Coverage: The change is applied consistently across:

   • Protocol schema (v3.bare)
   • Rust protocol implementation
   • TypeScript protocol bindings
   • All consuming code in gateway and runner packages
   • Protocol version conversion functions (v2 ↔ v3)

3. Backward Compatibility: The protocol version conversion functions correctly maintain backward compatibility by mapping close.retry (v2) ↔ close.hibernate (v3) in both directions at versioned.rs:1288 and versioned.rs:1337.

4. Logical Improvements: The code reorganization in pegboard-gateway/src/lib.rs:404-409 improves readability by moving the "Successful closure" comment to the else branch where it actually applies.

Issues Found 🔍

1. Unrelated Import Reordering (Minor)

File: engine/packages/api-peer/src/actors/kv_get.rs:1-3

The import order change appears unrelated to the PR's purpose:

-use base64::prelude::BASE64_STANDARD;
 use base64::Engine;
+use base64::prelude::BASE64_STANDARD;

Recommendation: This formatting change should either be:

• Reverted (preferred, to keep the PR focused)
• Or explained if it's intentional to match the project's import ordering standards

2. Unrelated Formatting Changes (Minor)

File: engine/packages/api-public/src/actors/kv_get.rs:68-72

The multiline formatting of the format! call appears unrelated to the rename:

-"/actors/{}/kv/keys/{}", path.actor_id, urlencoding::encode(&path.key)
+&format!(
+    "/actors/{}/kv/keys/{}",
+    path.actor_id,
+    urlencoding::encode(&path.key)
+)

Recommendation: Consider reverting this change to keep the PR focused on the retry → hibernate rename.

3. Assert Function and Whitespace Changes (Minor)

File: engine/sdks/typescript/runner-protocol/src/index.ts

Multiple unrelated changes:

• Moving import assert from "node:assert" to the top (line 1)
• Removing the custom assert function at the bottom (lines 1930-1933)
• Whitespace changes in callbacks (() => {} → () => { })
• Indentation changes (lines 611, 621)

Recommendation: While these are generally good cleanups:

• The assert import move is good (following best practices)
• Removing the duplicate assert function is correct (using Node's built-in instead)
• However, the whitespace changes in empty functions and indentation adjustments should ideally be in a separate formatting PR

Per CLAUDE.md: "Do not run ./scripts/cargo/fix.sh. Do not format the code yourself." These formatting changes may have been unintentional.

Recommendations 📝

1. Consider reverting unrelated changes to keep the PR focused solely on the retry → hibernate rename. This makes code review easier and git history cleaner.

2. Test Coverage: While the change is straightforward, consider verifying that:

   • WebSocket hibernation behavior still works correctly
   • Protocol version conversion maintains backward compatibility
   • No tests were broken by the rename

3. Documentation: If there's any user-facing documentation that mentions the "retry" field, it should be updated to reference "hibernate" instead.

Security & Performance ✅

• No security concerns identified
• No performance impact (purely a naming change)
• Backward compatibility properly maintained through version conversion

Overall Assessment

This is a clean refactoring PR that improves code clarity. The core change (rename) is well-executed and comprehensive. The only concerns are minor unrelated formatting changes that could be cleaned up to keep the PR focused.

Recommendation: Approve with minor cleanup suggestions.

[claude]

Code Review

Thank you for this PR! The rename from retry to hibernate better reflects the semantic meaning of the field. Here is my review:

✅ Strengths

1. Clear intent: The rename from retry to hibernate is semantically more accurate for describing WebSocket connection hibernation behavior
2. Comprehensive coverage: The change is applied consistently across:
   • Protocol schema (v3.bare)
   • Rust implementations (pegboard-gateway, pegboard-runner)
   • TypeScript SDK (runner-protocol, runner, websocket-tunnel-adapter)
   • Version conversion logic (v2 ↔ v3 conversions)
3. Backward compatibility: The versioned.rs file correctly maintains the field mapping between v2 (retry) and v3 (hibernate) for protocol version compatibility

🐛 Issues Found

Critical: Missing update in stringify.ts

The file engine/sdks/typescript/runner/src/stringify.ts still references retry instead of hibernate:

// Line 61-64
const { code, reason, retry } = kind.val;
const codeStr = code === null ? "null" : code.toString();
const reasonStr = reason === null ? "null" : `"${reason}"`;
return `ToServerWebSocketClose{code: ${codeStr}, reason: ${reasonStr}, retry: ${retry}}`;

This should be updated to:

const { code, reason, hibernate } = kind.val;
// ...
return `ToServerWebSocketClose{code: ${codeStr}, reason: ${reasonStr}, hibernate: ${hibernate}}`;

Location: engine/sdks/typescript/runner/src/stringify.ts:61-64

📝 Minor Observations

1. Unrelated formatting changes: The PR includes some minor formatting changes:

   • Import reordering in api-peer/src/actors/kv_get.rs
   • Formatting in api-public/src/actors/kv_get.rs
   • Whitespace changes in TypeScript files
   • Import statement consolidation in runner-protocol/src/index.ts

   While these are generally fine, it is worth noting they are technically outside the scope of the rename. Per the CLAUDE.md guidelines, cargo fmt should not be run automatically, so these changes appear to be manual adjustments.

2. Comment improvement: The pegboard-gateway comment placement is better after the change - "Successful closure" is now in the else branch where it belongs (line pegboard-gateway/src/lib.rs:407).

✅ Security & Performance

• No security concerns identified
• No performance impact expected
• The change is purely semantic and maintains the same behavior

🧪 Testing Recommendation

Given that this is a protocol-level change:

1. Verify integration tests pass, especially those involving WebSocket hibernation
2. Test protocol version compatibility (v2 ↔ v3 conversions)
3. Ensure the stringify function works correctly after fixing the bug

Summary

This is a solid refactoring that improves code clarity. The main action item is to fix the missing rename in stringify.ts. Once that is addressed, this should be ready to merge!

[claude]

Code Review

This PR renames the retry field to hibernate in the runner protocol's ToServerWebSocketClose message. This is a valuable clarification that better reflects the actual semantics of the field - it controls whether a WebSocket should hibernate (as per HIBERNATING_WS.md) rather than retry.

Positives

1. Better Naming: The rename from retry to hibernate accurately reflects the behavior documented in docs/engine/HIBERNATING_WS.md, where step 7 explicitly mentions "the runner will close the websocket by sending ToServerWebSocketClose with .hibernate = true"

2. Comprehensive Coverage: The change properly updates:

   • Schema definition (v3.bare)
   • TypeScript bindings (runner-protocol/src/index.ts)
   • Rust implementations (pegboard-gateway, pegboard-runner)
   • Version conversion functions (v2 to v3)
   • WebSocket tunnel adapter
   • All usages in the tunnel implementation

3. Correct Version Handling: The versioned.rs file correctly maps between v2's retry and v3's hibernate in both directions, maintaining backward compatibility

4. Code Quality: The formatting changes (import ordering in kv_get.rs, spacing fixes) follow Rust conventions

Issues Found

1. Missing Update in stringify.ts (Bug)

   The file engine/sdks/typescript/runner/src/stringify.ts:61-64 still references the old retry field. This should be updated to use hibernate instead. This will cause a TypeScript compilation error since the field was renamed in the type definition.

2. Outdated Comment (Minor)

   engine/sdks/typescript/runner/src/tunnel.ts:80 has a comment that says "The WebSocket close event with retry is automatically sent when the". Consider updating "with retry" to "with hibernate" for consistency.

3. Inconsistent Method Name (Semantic)

   The method __closeWithRetry() in websocket-tunnel-adapter.ts:207 should arguably be renamed to __closeWithHibernate() for consistency. Currently the method is called __closeWithRetry but it passes hibernate: true to closeInner and the protocol field is now hibernate. While this works functionally, the naming is now misleading.

4. No Test Coverage (Gap)

   There don't appear to be tests verifying the hibernate field behavior. Consider adding tests to ensure:

   • Hibernatable websockets close with hibernate: true
   • Non-hibernatable websockets close with hibernate: false
   • The version conversion between v2 and v3 works correctly

5. Generated TypeDoc Not Updated

   The file website/public/typedoc shows retry instead of hibernate. The TypeDoc likely needs to be regenerated.

Security

No security concerns identified. This is a straightforward rename that doesn't change the protocol's security properties.

Performance

No performance impact - this is a pure rename.

Recommendations

1. Must Fix: Update stringify.ts to use hibernate instead of retry (lines 61, 64)
2. Should Fix: Consider renaming __closeWithRetry() to __closeWithHibernate() for semantic consistency
3. Nice to Have: Update the comment on line 80 of tunnel.ts
4. Nice to Have: Add test coverage for hibernate behavior
5. Nice to Have: Regenerate TypeDoc documentation

Summary

This is a good refactoring that improves code clarity. However, there's at least one file (stringify.ts) that was missed and will cause a compilation error. The PR should not be merged until that's fixed.

[claude]

PR Review: Rename retry -> hibernate in runner protocol

Summary

This PR renames the retry field to hibernate in the WebSocket close message of the runner protocol. This is a good semantic improvement as hibernate more accurately describes the intent of persisting WebSocket state for later resumption.

Code Quality - Strengths

• Clean, focused rename across the protocol stack (schema, Rust, TypeScript)
• Proper bidirectional protocol version conversion (v2-v3) maintained in versioned.rs
• Consistent naming throughout all layers of the stack

Issues Found

1. Bug: Incomplete rename in stringify.ts (line 61, 64)
The stringify function still uses the old retry field name. It should use hibernate instead.
File: engine/sdks/typescript/runner/src/stringify.ts:61-64

2. Type inconsistency in websocket-tunnel-adapter.ts (line 20, 35)
The callback parameter still uses retry in its type signature instead of hibernate.
File: engine/sdks/typescript/runner/src/websocket-tunnel-adapter.ts:20,35

3. Outdated comment in tunnel.ts (line 80)
Comment still references retry instead of hibernate.
File: engine/sdks/typescript/runner/src/tunnel.ts:80

4. Unrelated formatting changes
The PR includes several unrelated formatting changes in api-peer, api-public, tunnel.ts, and runner-protocol index.ts. While these are good cleanups, they make the PR harder to review. Consider keeping refactoring PRs focused on a single change.

Security and Performance

• No security concerns identified
• No performance implications from this rename
• Protocol versioning properly handles backward compatibility

Test Coverage

• No tests found that explicitly cover the hibernate/retry field
• Recommendation: Consider adding a test that validates WebSocket hibernation behavior

Action Items

Must Fix: Update stringify.ts and websocket-tunnel-adapter.ts to use hibernate
Should Fix: Update comment in tunnel.ts, separate formatting changes
Nice to Have: Add test coverage for WebSocket hibernation behavior

Verdict

Good refactoring that improves code clarity! Just needs completion of the rename in a couple of TypeScript files to maintain consistency.

[claude]

PR Review: Rename retry → hibernate in Runner Protocol

Summary

This PR renames the retry field to hibernate in the ToServerWebSocketClose message across the runner protocol schema and all implementations. The change improves semantic clarity by using a more descriptive term for the hibernation behavior.

✅ Positive Aspects

1. Consistent Renaming: The change is applied thoroughly across all layers:

   • Schema definition (v3.bare)
   • Rust protocol SDK (versioned.rs)
   • TypeScript protocol SDK (index.ts)
   • Gateway implementation (pegboard-gateway)
   • Runner implementation (pegboard-runner)
   • WebSocket adapter (websocket-tunnel-adapter.ts, tunnel.ts)

2. Semantic Clarity: The new name hibernate better describes the behavior - when true, it triggers hibernation rather than a simple retry, making the code intent clearer.

3. Backward Compatibility: The versioned protocol conversion functions properly map between v2 (retry) and v3 (hibernate) in versioned.rs:1287 and versioned.rs:1337, maintaining compatibility.

4. Code Style: Changes follow the repository conventions:

   • Hard tabs in Rust files
   • Consistent naming patterns
   • No unnecessary whitespace changes (except the minor formatting in tunnel.ts)

🔍 Issues & Concerns

1. Unintended Formatting Changes (Minor)

// engine/sdks/typescript/runner/src/tunnel.ts:404-405, 611
resolve: () => { },  // Extra space added
reject: () => { },   // Extra space added

// Line 611: Indentation change
typeof data === "string"
    ? (new TextEncoder().encode(data)
-           .buffer as ArrayBuffer)  // Was 3 tabs + spaces
+       .buffer as ArrayBuffer)      // Now 2 tabs + spaces

Recommendation: These formatting changes are unrelated to the rename. Per CLAUDE.md, formatting should be done via the build process, not manually. Consider reverting these whitespace-only changes to keep the PR focused.

2. Comment Position Change (Minor)

// engine/packages/pegboard-gateway/src/lib.rs:404-408
-if can_hibernate && close.retry {
-    // Successful closure
+if can_hibernate && close.hibernate {
     return Err(WebSocketServiceHibernate.build());
 } else {
+    // Successful closure
     return Ok(LifecycleResult::ServerClose(close));
 }

Question: Was moving the "Successful closure" comment intentional? The comment now applies to the else branch (non-hibernation close) rather than both branches. This seems more accurate semantically, but wanted to confirm this was intended.

🧪 Testing Considerations

Missing Test Evidence: The PR doesn't show test coverage for the hibernation behavior. Consider:

1. Protocol Conversion Tests: Verify v2 ↔ v3 conversion works correctly with the renamed field
2. WebSocket Close Tests: Ensure hibernate: true properly triggers hibernation in the gateway
3. End-to-End Tests: Validate that WebSocket connections properly hibernate when requested

Recommendation: Run the test suite and verify no tests are broken by this rename:

cargo test -p pegboard-gateway
cargo test -p pegboard-runner
# Also test TypeScript SDK if applicable

🔒 Security & Performance

• No security concerns: This is a pure rename with no logic changes
• No performance impact: Field name changes don't affect runtime performance

📋 Suggestions

1. Revert unrelated formatting changes in tunnel.ts to keep the diff clean
2. Clarify comment position in pegboard-gateway/src/lib.rs:407
3. Verify test coverage for hibernation behavior
4. Update documentation if any docs reference the old retry field name

Overall Assessment

Status: ✅ Approve with minor suggestions

This is a solid refactoring that improves code clarity. The rename is applied consistently across all layers of the protocol stack. The only concerns are minor formatting issues and the need to verify test coverage.

The change aligns well with the codebase conventions and demonstrates good attention to consistency across multiple language implementations.

[claude]

Code Review

Summary

This PR performs a semantic renaming from retry to hibernate in the runner protocol's WebSocket close message. This is a refactoring improvement that makes the code's intent clearer.

Changes Overview

• Protocol Schema (v3): Renamed field from retry: bool to hibernate: bool in ToServerWebSocketClose
• Backward Compatibility: Properly maintained v2 ↔ v3 protocol conversion in versioned.rs
• SDK Updates: Updated Rust and TypeScript generated code
• Implementation Updates: Updated pegboard-gateway and pegboard-runner to use the new field name

Code Quality ✅

Strengths:

1. Semantic Clarity: The rename from retry to hibernate better communicates the intent - this flag indicates whether the connection should hibernate (for later resumption) rather than just "retry"
2. Consistency: All references updated across the codebase (schema, SDKs, implementations)
3. Backward Compatibility: The v2 ↔ v3 conversion functions correctly map close.retry (v2) to close.hibernate (v3) in both directions
4. Complete Coverage: Updated all language SDKs (Rust, TypeScript) and both directions of the tunnel (gateway and runner)

Minor Observations:

1. Formatting Changes: The diff shows some unintentional whitespace changes:

   • engine/sdks/typescript/runner/src/tunnel.ts:404-405: Empty function bodies changed from () => {} to () => { }
   • engine/sdks/typescript/runner/src/tunnel.ts:611: Indentation change in template literal

   These are cosmetic and don't affect functionality, but ideally should be in a separate formatting commit.

Potential Issues ❌ None Found

No bugs, security issues, or performance concerns identified.

Test Coverage 🔍

Recommendation: Consider verifying that existing WebSocket tests still pass, particularly:

• Tests that exercise the hibernation flow
• Integration tests between pegboard-gateway and pegboard-runner
• Any tests that validate protocol v2 ↔ v3 conversion

The renaming is purely semantic, so existing tests should continue to work without modification, but it's worth confirming the behavior is unchanged.

Performance Considerations ✅

No performance impact - this is a pure rename with no logic changes.

Security Concerns ✅

No security implications.

Verdict: ✅ Approved

This is a clean refactoring that improves code readability without introducing any functional changes. The semantic meaning of "hibernate" is clearer than "retry" for this use case, where the connection may be resumed later.

Recommendations:

• Consider running the test suite to confirm no regressions
• In future PRs, keep formatting changes separate from semantic changes for easier review