fix(serverless): split metadata protocol errors

[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(serverless): split metadata protocol errors #4789 : 2 dependent PRs (#4790 , #4791 ) 👈 (View in Graphite)
• 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(serverless): split metadata protocol errors

Overview

This PR improves debuggability of serverless metadata protocol errors by:

1. Adding max_supported to InvalidEnvoyProtocolVersion so callers know what version to target instead of just what they sent
2. Propagating parse_error through all SDKs for InvalidResponseJson (the field existed in Rust but was silently dropped at the API boundary)
3. Regenerating TypeScript, Go, and Rust SDK types consistently
4. Adding unit tests in engine/packages/pegboard/tests/ and integration tests in engine/packages/engine/tests/

The change is focused and the intent is clear. A few items worth discussing:

---

Issues

Breaking change for InvalidResponseJson — parse_error is now required

parse_error is added as a required field in the OpenAPI schema for invalid_response_json. The Go SDK new() constructor now requires it as a second argument. Any existing consumer constructing this type directly will break at compile time. This is probably fine given the context, but worth confirming no internal callers are affected.

Flaky potential in refresh_metadata test (line 248)

tokio::time::timeout(Duration::from_millis(100), async {
    // assert cache was invalidated
})

This assumes cache invalidation completes within 100 ms. In a CI environment under load this could race. Since the operation is a direct cache read (not a poll), await-ing the assertion directly without a timeout would be more robust. If a timeout is intentional to catch a "cache was not invalidated" regression, a comment explaining that would help, and the timeout should be longer.

Hand-rolled HTTP server buffer in serverless_metadata_fetch.rs

let mut buf = [0; 1024];
let _ = socket.read(&mut buf).await;

The 1024-byte buffer can be exceeded on some platforms/reqwest versions when headers like user-agent, accept, and keep-alive accumulate. Consider a Vec-based drain loop or using axum (as the integration test files already do).

---

Observations

No test for protocol version 0 or exactly PROTOCOL_VERSION

The guard is envoy_protocol_version < 1 || envoy_protocol_version > PROTOCOL_VERSION. There is a test for PROTOCOL_VERSION + 1 (too high) but none for 0 (too low) or PROTOCOL_VERSION itself (exact valid boundary). Adding these would make boundary behavior explicit.

run and setup_test_namespace duplicated across both new test files

Both new integration test files copy-paste an identical run helper and setup_test_namespace. The existing common/api/public.rs pattern shows this codebase uses #[path] includes — run could live in common/ctx.rs or a new common/test_utils.rs.

i32 in Rust SDK vs u16 in source

RunnerConfigsServerlessMetadataErrorOneOf6InvalidEnvoyProtocolVersion uses i32 for max_supported and version while the Rust source uses u16. This is expected from code generation (int32 + minimum: 0), but a version number > 32767 would overflow/sign-flip in SDK consumers.

MockMetadataErrorState naming

The struct name implies an error state, but it is also used for the valid-JSON-with-invalid-version case. A name like MockRawBodyState would be more neutral.

---

Positive notes

• Tests are correctly placed under tests/ following the repo convention.
• AtomicBool with Ordering::SeqCst is correct for the cross-thread mock server visibility.
• The CLAUDE.md addition about engine/sdks/*/api-* being auto-generated is a useful guardrail.
• All three SDKs (Go, Rust, TypeScript) are updated consistently; the TypeScript core.serialization.property snake_case mapping is handled correctly.
• Removing the // Re-export types from pegboard for API schema comment follows the project's no-delta-comments convention.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4789

All packages published as 0.0.0-pr.4789.1e19894 with tag pr-4789.

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

Individual packages

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

[NathanFlurry]

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