fix(rivetkit-native): expose full hibernation metadata to JS

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[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

• fix(rivetkit): keep internal error exposure behavior consistent #4661
• fix(test): stabilize lifecycle, sleep, queue, and run edge cases #4660
• test(rivetkit): re-enable gateway URL and direct-registry coverage #4659
• fix(rivetkit): restore hibernatable sockets and hydrate serverless starts #4658
• fix(rivetkit-native): expose full hibernation metadata to JS #4657 👈 (View in Graphite)
• fix(pegboard): persist and replay hibernating requests #4656
• fix(guard): serialize gateway actor keys correctly #4655
• fix(api): subscribe before namespace workflow dispatch #4654
• chore(engine): publish engine bases in ci #4649 : 2 other dependent PRs (#4650 , #4652 )
• chore: lockfile lefthook #4647
• fix(rivetkit): surface native sqlite kv errors to callers #4645
• fix(rivetkit): prevent sleep races during disconnect and db work #4644
• fix(rivetkit): isolate engine envoys and propagate startup failures #4643
• test(rivetkit): remove wasm sqlite-only fixtures and coverage #4642
• chore(sqlite-vfs): remove wasm sqlite packages and workspace wiring #4641
• chore(rivetkit): remove wasm sqlite runtime #4614
• fix(sqlite-native): restore native startup kv preload #4639
• fix(sqlite-native): delete metadata before chunk range #4638
• fix(sqlite-native): keep truncate cache coherent #4637
• fix(sqlite-vfs): use delete range for truncate cleanup #4636
• fix(sqlite-native): restore kv error hook #4635
• perf(sqlite-native): avoid cloning cached read chunks #4634
• perf(sqlite-native): gate kv operation labels #4633
• perf(sqlite-native): reuse read cache for partial writes #4632
• perf(sqlite-native): remove delete file existence probe #4631
• fix(sqlite-native): gate native read cache behind env var #4630
• fix(pegboard): isolate runner config dc lookup failures #4625 : 1 other dependent PR (#4626 )
• docs(pegboard): note runner config upsert split write risk #4624
• fix(pegboard): unpack global runner config keys correctly #4623
• fix(pegboard-gateway): enforce tunnel message state #4622
• fix(pegboard-runner): clear terminal tunnel routes #4621
• fix(pegboard): skip protocol version keys in runner pool backfill #4620
• fix(pegboard): create missing normal runner configs #4619
• fix(epoxy): reuse cached optimistic value #4618
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Code Review: fix(rivetkit-native): expose full hibernation metadata to JS

Overview

This PR implements the can_hibernate callback properly (previously always returning false) and threads the full hibernation metadata (message indices, path, headers) through the JS bridge so connection state can be faithfully restored after hibernation.

The core mechanism: can_hibernate is a synchronous Rust function that needs to query JS asynchronously. The solution uses ThreadsafeFunctionCallMode::Blocking to enqueue the JS call and tokio::task::block_in_place + rx.blocking_recv() to wait for the result without blocking a Tokio executor thread.

---

Issues

block_in_place requires a multi-threaded runtime

tokio::task::block_in_place panics if called from a current_thread runtime. lib.rs uses Runtime::new() which creates a multi-thread runtime by default, so this is safe today. However, it's a silent footgun — if the runtime ever changes to current_thread, can_hibernate will panic at runtime rather than failing to compile. Consider adding a comment documenting this constraint, or explicitly construct a Builder::new_multi_thread runtime to make the requirement visible.

Mutex<HashMap> violates project conventions

CLAUDE.md states: "Never use Mutex<HashMap<...>> or RwLock<HashMap<...>>. Use scc::HashMap (preferred)..."

ResponseMap is Arc<Mutex<HashMap<String, oneshot::Sender<...>>>>. This was pre-existing with a tokio::sync::Mutex, and the change to std::sync::Mutex is necessary for sync context use, but the pattern should be migrated to scc::HashMap to comply with project guidelines.

unwrap_or_else(HashMap::new) — prefer unwrap_or_default()

envoy_handle.rs:283: r.headers.unwrap_or_else(HashMap::new) is equivalent to r.headers.unwrap_or_default() since HashMap implements Default. Minor style nit.

---

Observations / Questions

Async canHibernate in wrapper.js

The JS side runs config.hibernatableWebSocket.canHibernate(...) as a Promise, then responds via handle._raw.respondCallback. The Rust side uses ThreadsafeFunctionCallMode::Blocking (blocks until the call is enqueued, not until it completes) and then blocking_recv() waits for the response channel. Node's event loop remains unblocked while Rust waits, so Promises can resolve correctly. The pattern is consistent with the existing on_http_request and on_upgrade_request callbacks.

ThreadsafeFunctionCallMode::Blocking in can_hibernate vs NonBlocking elsewhere

All other callbacks use NonBlocking. can_hibernate uses Blocking. Given that this function must return a synchronous answer, Blocking is correct, but worth documenting explicitly — a future reader may change it to match surrounding code and silently break the semantics (the response channel would be orphaned if the queue is full and the call is dropped).

Error field in the rejection handler is silently dropped on the Rust side

In the websocket_can_hibernate rejection handler in wrapper.js, the response includes error: String(err), but the Rust side only reads canHibernate. The error is logged via console.error but Rust has no visibility. Not a bug, but worth noting in case operator visibility into hibernation failures matters.

Metadata defaults in wrapper.js

envoyMessageIndex: e.envoyMessageIndex ?? 0,
rivetMessageIndex: e.rivetMessageIndex ?? 0,
path: e.path ?? "",
headers: e.headers ?? {},

If these fields are always present in the protocol, a warning log when they're absent would help catch protocol drift. If they're genuinely optional, the defaults are appropriate.

---

Summary

The core logic is sound and consistent with existing callback patterns. Three actionable items:

1. Add a comment in lib.rs or bridge_actor.rs documenting that the runtime must be multi-threaded for block_in_place to work — or switch to an explicit Builder::new_multi_thread() to make the constraint compiler-visible.
2. Migrate ResponseMap from Arc<Mutex<HashMap>> to scc::HashMap per CLAUDE.md.
3. Add a comment on the ThreadsafeFunctionCallMode::Blocking call in can_hibernate explaining why Blocking is required (channel would be orphaned if dropped).