fix(envoy-client): complete command and request lifecycles

[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(envoy-client): dedupe replayed commands by index #4811 : 2 dependent PRs (#4802 , #4812 )
• fix(envoy-client): complete command and request lifecycles #4801 👈 (View in Graphite)
• fix(guard): serialize gateway actor keys correctly #4655 : 1 other dependent PR (#4800 )
• chore(rivetkit): remove inline tests #4668 : 1 other dependent PR (#4657 )
• fix(api): subscribe before namespace workflow dispatch #4654
• fix(rivetkit): restore hibernatable sockets and hydrate serverless starts #4658
• test(rivetkit): stabilize actor db driver tests #4664 : 1 other dependent PR (#4656 )
• 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): keep internal error exposure behavior consistent #4661
• fix(rivetkit): add lifecycle error retry and gateway HTTP routing #4666
• 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]

Overview

This PR fixes a silent failure in handle_req_start: when the actors fetch callback returns Err, the request lifecycle was left incomplete -- no response was ever sent back to the gateway, leaving the client hanging. The fix adds send_fetch_error_response to send a proper 500 error response in the error branch.

This is a correct and necessary fix. A few observations below.

---

Issues

1. Missing content-type: application/json header

The response body is JSON, but no content-type header is set. Clients that inspect the content-type before parsing the body (e.g., SDKs, error middleware) will not know to decode it as JSON.

Compare to test-envoy/src/behaviors.rs:75, which sets content-type: application/json for JSON responses, and tunnel.rs::send_error_response (~line 274), which intentionally sends a plain-text body without one.

Suggested addition in send_fetch_error_response:

headers.insert("content-type".to_string(), "application/json".to_string());

2. JSON body format does not match canonical RivetError structure

CLAUDE.md mandates: Errors use universal RivetError (group/code/message/metadata) at all boundaries.

The emitted body uses a flat code field that bundles group and code together (envoy_fetch_failed), rather than the canonical separate group + code fields. The x-rivet-error header correctly uses envoy.fetch_failed (dot-notation group.code), so the JSON body should match that same structure. Without group, clients using the canonical RivetError decoder will either fail to parse or silently fall through to unstructured error handling.

Suggested body format: group="envoy", code="fetch_failed", message="actor fetch failed"

3. HTTP status 500 vs 502

500 is defensible (actor runtime error), but 502 Bad Gateway is more semantically accurate since the envoy is acting as a reverse proxy and the upstream (the actor fetch handler) failed. Worth a deliberate choice either way. For reference, tunnel.rs uses 503 for the analogous "actor not found" path.

---

Minor Notes

• No tests cover the fetch-error path. The existing mod tests harness looks well-suited to add a case asserting a 500 is returned when the fetch callback errors.
• PR description is blank (understood given the Draft status).

---

Summary

The core fix is correct and necessary -- completing the request lifecycle on error prevents client hangs. Two items to address before merging:

1. Add content-type: application/json to the error response headers.
2. Align the JSON body to the canonical RivetError shape with separate group and code fields.

[NathanFlurry]

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

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4801

All packages published as 0.0.0-pr.4801.1822679 with tag pr-4801.

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-1822679
docker pull rivetdev/engine:full-1822679

Individual packages

npm install rivetkit@pr-4801
npm install @rivetkit/react@pr-4801
npm install @rivetkit/rivetkit-napi@pr-4801
npm install @rivetkit/workflow-engine@pr-4801

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4801

All packages published as 0.0.0-pr.4801.1822679 with tag pr-4801.

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-1822679
docker pull rivetdev/engine:full-1822679

Individual packages

npm install rivetkit@pr-4801
npm install @rivetkit/react@pr-4801
npm install @rivetkit/rivetkit-napi@pr-4801
npm install @rivetkit/workflow-engine@pr-4801