fix(rivetkit): restore hibernatable sockets and hydrate serverless starts

[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(pegboard): stabilize actor2 validation and lifecycle #4804 : 2 dependent PRs (#4805 , #4808 )
• fix(pegboard): decode envoy actor eviction keys #4803
• fix(pegboard-envoy): subscribe before registering envoy #4802
• fix(envoy-client): clear processed_command_idx after ack send #4812
• fix(envoy-client): dedupe replayed commands by index #4811
• fix(envoy-client): complete command and request lifecycles #4801
• fix(envoy-protocol): advertise current protocol version #4800
• fix(guard): serialize gateway actor keys correctly #4655
• fix(rivetkit-native): expose full hibernation metadata to JS #4657
• chore(rivetkit): remove inline tests #4668
• fix(api): subscribe before namespace workflow dispatch #4654
• fix(rivetkit): restore hibernatable sockets and hydrate serverless starts #4658 👈 (View in Graphite)
• fix(pegboard): persist and replay hibernating requests #4656
• fix(rivetkit): keep internal error exposure behavior consistent #4661
• test(rivetkit): stabilize actor db driver tests #4664
• fix(test): stabilize lifecycle, sleep, queue, and run edge cases #4660 : 1 other dependent PR (#4665 )
• test(rivetkit): re-enable gateway URL and direct-registry coverage #4659
• fix(rivetkit): add lifecycle error retry and gateway HTTP routing #4666
• fix(rivetkit-core): remove legacy timeouts #4799
• docs: add replay guidance notes #4796
• fix(inspector): stream patched state updates #4795
• fix(rivetkit): refresh stale actor handles #4794
• test(rivetkit-napi): move private tests to crate root #4793
• test(rivetkit-core): move private tests to crate root #4792
• test(runner-configs): assert envoy protocol version #4791
• fix(serverless): split metadata protocol errors #4789 : 1 other dependent PR (#4790 )
• chore(sqlite): add open close lifecycle for envoy actors #4788
• fix(rivetkit): share lifecycle shutdown grace #4810
• fix(pegboard): move sqlite v1 migration into actor workflow #4787 : 1 other dependent PR (#4797 )
• test(rivetkit): cover c.db access from onWake/onSleep/onDestroy #4786
• fix(rivetkit-napi): run onMigrate before createState/onCreate/createVars #4785
• refactor(rivetkit-core): merge ready+started into lifecycle_started, drop redundant napi calls #4784
• fix(rivetkit): drain native sleep side tasks reliably #4782 : 1 other dependent PR (#4783 )
• fix(rivetkit): route raw request fetches to actors #4781
• fix(pegboard): refresh runner config after envoy connect #4778 : 2 other dependent PRs (#4779 , #4798 )
• chore(kitchen-sink): configurable endpoint #4766 : 2 other dependent PRs (#4754 , #4777 )
• refactor(rivetkit-core): rename StopReason to ShutdownKind and kill enum fallthroughs #4765
• chore(envoy-client): log command and event payloads #4751
• fix(rivetkit): minor sleep-cleanup follow-ups #4761
• docs(rivetkit): clean up stale setPreventSleep references in docs and JSDoc #4760
• docs(rivetkit): document keepAwake/waitUntil counter-arm race and surface bridge errors #4759
• test(engine): force overdue branch in alarm-during-sleep test with negative offset #4758
• fix(rivetkit-core): return stopping not starting when sleep/destroy called mid-shutdown #4757
• test(rivetkit): remove sleepWithPreventSleep fixture and tests #4756
• test(engine): add regression test for alarm-during-sleep-transition race #4755
• test(rivetkit-core): cover sleep/destroy guards and prevent_sleep no-op #4750
• docs: add keepAwake vs waitUntil table and internal sleep-sequence invariants #4749
• feat(rivetkit): expose c.keepAwake(promise) through native path #4748
• refactor(rivetkit): deprecate setPreventSleep to no-op in TypeScript #4747
• fix(rivetkit-core): enumerate non-drained counters in grace deadline warn log #4746
• fix(rivetkit-core): abort graceful cleanup task when grace deadline elapses #4745
• fix(rivetkit-core): error on sleep/destroy before startup or already-requested #4743
• fix(rivetkit-core): cap SerializeState shutdown timeout at 15s #4742
• refactor(rivetkit-core): remove prevent_sleep field and deprecate set_prevent_sleep to no-op #4741
• fix(api-public): remove orphan import_export actors module #4764
• main

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

[claude]

PR Review: fix(rivetkit): restore hibernatable sockets and hydrate serverless starts

Overview

This PR fixes hibernatable WebSocket restore and serverless start hydration for the engine actor driver. The core change introduces two new binding registries (#hibernatableConnectBindings and #hibernatableRunnerWebSocketBindings) that persist socket state across actor hibernation/wake cycles so existing connections can be re-bound to the newly started actor without being dropped. It also fixes a pre-existing omission where #dynamicRuntimes was cleared without calling dispose().

---

Bugs / Correctness Issues

1. Log field inconsistency: err vs error

In the serverlessHandleStart catch block the field is named err: instead of error:. Every other structured log in this file uses error:. This will silently break any log-based alerting or dashboards that filter on the error field.

2. #bindDynamicHibernatableRunnerWebSocket detach does not close proxy

In #bindDynamicHibernatableConnectSocket, the detach closure sends 1011 "dynamic.rebind" to close the proxy WebSocket before removing listeners. The equivalent detach in #bindDynamicHibernatableRunnerWebSocket only removes listeners without closing proxyToActorWs. If the runner-side proxy is open when the binding is detached during rebind, it will linger without a close frame. This asymmetry should be confirmed intentional or fixed.

3. Single try block swallows partial restoration failures silently

A single failure in #rebindHibernatableConnectSockets aborts the entire block, abandoning all remaining connections for that actor with no close frame sent to the gateway or client. Consider separating these into independent try/catch blocks, or at minimum closing each unrestored binding explicitly so the client receives a meaningful error.

4. actorForDispatch fallback may dispatch to a stale actor reference

When currentActor exists but is not a static actor instance, dispatch falls back to the earlier-captured actor variable, which could be a stopped or replaced instance. A comment explaining the intended fallback semantics would help, and the case where neither reference is valid should be handled explicitly rather than silently dispatching to a stale object.

---

Code Quality

5. as any casts

Multiple event.data as any casts appear when calling forwardIncomingWebSocketMessage and websocket.send. These should use the correct union type (ArrayBuffer | string) or a type guard.

6. Unhandled throws inside onMessage static path

In #bindHibernatableConnectSocket the static path calls wsHandler.onMessage and actor.handleInboundHibernatableWebSocketMessage without a try/catch. An uncaught exception will crash the event listener. The dynamic path wraps forwarding in .catch() — the static path should do the same.

7. Double-logging in #runnerDynamicWebSocket error path

deconstructError internally logs the error, then the call site logs it again at error level before closing. This produces duplicate log entries for the same event.

---

Performance

8. O(n) scans in rebind helpers

Both #rebindHibernatableConnectSockets and #rebindDynamicHibernatableRunnerWebSockets iterate all bindings to find those matching actorId. For many concurrent connections across many actors, each actor wake-up is O(total bindings). Consider indexing bindings by actorId for O(1) lookup.

---

Test Coverage

The PR description leaves all test checklist items unchecked. There are no new tests covering:

• Hibernation and wake-up restoring an active WebSocket connection end-to-end
• Rebind on dynamic actor restart
• Cleanup when rebind fails partway through
• Force-stop behavior during the shutdown drain timeout

Given the complexity of the two new binding maps and their detach/rebind/cleanup paths, the absence of tests is the highest-risk aspect of this change. At minimum, a driver test covering the hibernation-wake-message-delivery round trip would catch regressions early.

---

Minor / Nits

• The let to const fix for payload in serverlessHandleStart is a good cleanup.
• The #disposeDynamicRuntime / #disposeAllDynamicRuntimes refactor correctly replaces the silent .clear() call and improves shutdown correctness.
• The force-stop loop added during the drain timeout is appropriate; the structured log fields look good.