fix(rivetkit): add lifecycle error retry and gateway HTTP routing

[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(test): stabilize lifecycle, sleep, queue, and run edge cases #4660 : 2 dependent PRs (#4664 , #4665 )
• test(rivetkit): re-enable gateway URL and direct-registry coverage #4659
• fix(rivetkit): keep internal error exposure behavior consistent #4661
• fix(rivetkit): add lifecycle error retry and gateway HTTP routing #4666 👈 (View in Graphite)
• fix(rivetkit-core): remove legacy timeouts #4799
• chore: add CLAUDE.md guidance on test fixtures, SDK regen, and TS client layer #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): add lifecycle error retry and gateway HTTP routing

Overview

This PR adds two distinct improvements:

1. Lifecycle error retry logic — a new lifecycle-errors.ts module classifies errors at actor lifecycle boundaries (restarting, stopping) and wraps action calls with an automatic retry loop. Connection open failures that are non-retryable now abort pRetry immediately instead of exhausting retries.
2. Gateway HTTP routing fix — test URLs updated to include a /request/ path prefix, along with a new test asserting that non-/request paths are not routed to onRequest.
3. WebSocket listener ordering fix — close/error listeners are now attached before onOpen to avoid losing close events from actors that immediately reject connections.

---

Specific Issues

lifecycle-errors.ts: continue vs early return in classifyLifecycleBoundaryError

When classifyActorError returns undefined for the "database accessed after actor stopped" case, the outer loop calls continue, which proceeds to check the next error in the cause chain. If a retryable error exists deeper in that chain, it would be incorrectly classified as retryable — even though the definitive signal was "do not retry." The intent here appears to be suppression, so this branch should return undefined from the outer function, not continue.

actor-conn.ts: misleading log level for non-retryable errors

In the .catch((err) => handler, non-retryable connection open errors (e.g., auth failure) fall into the same branch as intentional aborts and log at info level with the message "connection retry aborted". These should log at warn/error with a distinct message so they are diagnosable in production.

retryOnLifecycleBoundary: no jitter in exponential backoff

The delay calculation is Math.min(initialDelayMs * 2 ** attempt, maxDelayMs). When many clients hit a restarting actor simultaneously, this produces a synchronized thundering herd on restart. Adding random jitter is the standard fix.

actor-handle.ts: fragile string comparison for the destroy guard

if (opts.name === "destroy") skips the retry wrapper. This works today but would silently break if the destroy action is ever renamed or aliased. A typed constant or an explicit option on the call site would be more robust.

Missing unit tests for lifecycle-errors.ts

The classification logic covers multiple legacy string patterns, a depth-limited error chain walk, and two distinct retry kinds. This is the highest-risk new code in the PR — a unit test file exercising each classification case (actorRestarting, legacy internal_error with "Actor is stopping", actor.stopped, transport string matches, chain walking) would catch regressions without needing full integration tests.

---

Minor Notes

• The actor.stopped case in classifyActorError is tagged legacy: true but lacks a TODO(RVT-XXXX) tracking issue unlike the other legacy cases.
• maxAttempts = 0 would cause throw lastError to throw undefined. While unlikely in practice, guarding or initializing lastError to a sentinel would be safer.
• The WebSocket listener reordering in actor-driver.ts is a clean, correct fix for the race condition.
• The gateway routing test split (into "does route" / "does not route" subtests) is a clear improvement in test coverage.

---

Summary

The design intent is sound and the error classification approach is well-structured. The main concerns before merge are: the continue/return suppression logic for the "database accessed" guard in classifyLifecycleBoundaryError, the misleading log level for non-retryable connection open errors, and the absence of unit tests for the classification logic given the number of edge-case string patterns being matched.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4666

All packages published as 0.0.0-pr.4666.c672e53 with tag pr-4666.

Engine binary is shipped via @rivetkit/engine-cli on linux-x64-musl, linux-arm64-musl, darwin-x64, and darwin-arm64. Windows users should use the release installer or set RIVET_ENGINE_BINARY.

Docker images:

docker pull rivetdev/engine:slim-c672e53
docker pull rivetdev/engine:full-c672e53

Individual packages

npm install rivetkit@pr-4666
npm install @rivetkit/react@pr-4666
npm install @rivetkit/rivetkit-native@pr-4666
npm install @rivetkit/workflow-engine@pr-4666

[NathanFlurry]

Landed in main via stack-merge fast-forward push. Commits are in main; closing to match.