feat(rivetkit): support gateway bypass client requests

[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

• chore(rivetkit): note duplicate admission logic #4948
• test(rivetkit): cover bypass fetch header forwarding #4947
• feat(kitchen-sink): add actor probe controls #4946
• fix(gateway): split actor response wait errors #4945
• fix(guard): handle bypass preflight before query parse #4944
• feat(kitchen-sink): add mock agent event log copy #4943
• fix(kitchen-sink): default mock agent to local endpoint #4942
• test(rivetkit): enable driver lifecycle regressions #4941
• test(rivetkit): verify cached websocket db refs exceed grace #4940
• fix(rivetkit-core): keep sleeping actors reachable during grace #4939
• test(rivetkit): cover async websocket close db access #4938
• fix(rivetkit): keep actors awake until keepAwake work finishes #4937
• fix(rivetkit): persist native onSleep state on errors #4936
• fix(rivetkit-core): allow dispatch during sleep grace #4935
• fix(rivetkit): make duplicate sleep requests idempotent #4934
• fix(rivetkit): align logs with engine logfmt #4933
• fix(ci): standardize publish rust toolchain #4931
• SPLIT UP: agentic loop test #4932
• chore(rivetkit): doc skip ready wait #4927
• fix(guard): parse gateway bypass query booleans #4926
• feat(depot-client): add vfs staging cache ttl #4930
• feat(depot-client): wire sqlite optimization flags #4923
• feat(rivetkit): support gateway bypass client overrides #4928
• test(depot-client): stabilize fault harness #4924
• chore(depot-client): split sqlite vfs transports #4922
• feat(rivetkit): support gateway bypass probes #4915
• feat(kitchen-sink): add mock agentic lifecycle loop #4914
• feat(kitchen-sink): add mock agentic loop #4891
• feat(rivetkit): support gateway bypass client requests #4917 👈 (View in Graphite)
• fix(pegboard): restore hibernating request ids #4898 : 2 other dependent PRs (#4899 , #4916 )
• chore(guard): configure local timeout knobs #4913
• docs(rivetkit): raise serverless start payload limit #4911
• test(kitchen-sink): add sqlite memory soak harness #4910
• feat(rivetkit): expose runtime diagnostics #4909
• chore(depot-client): migrate to worker thread #4907 : 2 other dependent PRs (#4912 , #4918 )
• test(driver): select matrix cells with vitest filters #4906
• fix(pegboard): restore hibernating requests on serverful start #4904 : 1 other dependent PR (#4905 )
• fix(rivetkit): drain shutdown work before sleep #4902 : 1 other dependent PR (#4903 )
• feat(sqlite): wire remote sqlite execute handlers #4897
• test(serverless): avoid pinning header validation order #4896
• chore(driver-test-runner): add native/wasm runtime matrix to skill #4884 : 3 other dependent PRs (#4892 , #4894 , #4901 )
• chroe: rename rivetkit-sqlite to depot-client #4883
• fix(rivetkit-wasm): fix mem leaks #4880
• chore(rivetkit): wasm support #4860
• feat(sqlite): add cold read benchmarks and simplify optimizations #4857
• feat(sqlite): benchmark cold reads #4848 : 1 other dependent PR (#4864 )
• docs(actors): document manual lifecycle controls #4847
• test(sqlite): expand db stress coverage #4846 : 1 other dependent PR (#4849 )
• test(raw-websocket): add serverless smoke coverage #4845
• feat(serverless): configure drain grace period #4844
• fix(publish): enable frontend build for engine target and use turbo build instead of turbo build:engine #4843
• feat(rivetkit): expose conn handle in onWebSocket context #4842
• fix(rivetkit): normalize waitUntil/keepAwake promises to null to avoid serde undefined error #4841
• fix(rivetkit): remove requirement for token #4839 : 1 other dependent PR (#4840 )
• fix(pegboard-envoy): allow sqlite requests across lifecycle states #4838
• fix(pegboard): route scoped actor key reads by runner dc #4837
• fix(sqlite-storage): let sqlite open take over stale owners #4834
• fix(engine-tests): parallelize multi-DC startup + enable 6 multi-DC tests #4833
• fix(api): honor cursor in actor_ids list path #4832
• fix(api): silently filter invalid IDs from actor_ids query instead of 400 #4831
• fix(api-peer): make actors_delete idempotent for already-destroyed actors #4830
• fix(pegboard): use Iterator streaming mode in list_names so limit param is honored #4829
• chore(engine-tests): convert envoy tests to Sleep crash policy + triage ignored #4828
• feat(engine-tests): wire envoy actor names through prepopulate_actor_names #4827
• chore(depot): fault injection tests #4868
• feat(sqlite): pitr & forking #4859 : 1 other dependent PR (#4863 )
• chore(sqlite): stateless storage refactor #4856
• main

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

[claude]

Review: feat(rivetkit): support gateway bypass client requests

Status: Draft — feedback below before marking ready for review.

Overview

This PR adds a bypassConnectable option that lets client code route requests directly to an actor instance, bypassing the normal "connectable" routing layer. The flag propagates through three channels depending on transport:

• HTTP: x-rivet-bypass-connectable: 1 header
• WebSocket (subprotocol): rivet_bypass_connectable WS protocol token
• Query-based routing: rvt-bypass_connectable=true query param

---

Issues

Naming inconsistency in query parameter

actor-websocket-client.ts:273

params.append("rvt-bypass_connectable", "true");

All other rvt- params use kebab-case (rvt-token, rvt-crash-policy, rvt-namespace). This one mixes a hyphen and underscore. Should be rvt-bypass-connectable.

Duplicate directActorId type definition

actor-http-client.ts exports HttpGatewayRequestOptions extends GatewayRequestOptions { directActorId?: string }, while actor-websocket-client.ts uses the inline intersection GatewayRequestOptions & { directActorId?: string }. These should share a single named interface (from driver.ts or actor-http-client.ts) to prevent silent drift.

Structural duplication between ActorGatewayOptions and GatewayRequestOptions

Both interfaces independently declare bypassConnectable?: boolean. ActorGatewayOptions in actor-common.ts should extend or re-export GatewayRequestOptions from driver.ts so they cannot diverge.

Asymmetric behavior by target type is undocumented

For directId/getForId targets with bypassConnectable: true, the URL is stripped to just the base endpoint and actor routing moves entirely into headers. For getForKey/getOrCreateForKey targets, the normal query URL is built with an added rvt-bypass_connectable param. This intentional split is invisible to callers and deserves a brief comment in #buildGatewayUrlForTarget.

directActorId is silently undefined for query targets

In sendRequest and openWebSocket in mod.ts:

directActorId: options.bypassConnectable
    ? directActorIdFromTarget(target)
    : undefined,

For getForKey/getOrCreateForKey targets, directActorIdFromTarget returns undefined, so HEADER_RIVET_TARGET and HEADER_RIVET_ACTOR are never set. If bypass is meaningless for query targets (actor not yet resolved), consider an early guard or logged warning rather than silently degrading to only the bypass header.

---

Minor / Style

• WS_PROTOCOL_BYPASS_CONNECTABLE naming: All other WS_PROTOCOL_* constants are value prefixes ending with . (e.g. rivet_actor.). The new constant is a bare boolean flag with no dot. Consider naming it WS_PROTOCOL_FLAG_BYPASS_CONNECTABLE to distinguish it from the prefix family.

---

Test coverage

The new test covers only buildActorQueryGatewayUrl with bypassConnectable: true. Consider adding:

1. A test for the HTTP header path: verify HEADER_RIVET_BYPASS_CONNECTABLE and HEADER_RIVET_ACTOR are set when a directId target is used.
2. A test for buildWebSocketProtocols: verify rivet_bypass_connectable appears in the protocols list.

---

Summary

Core approach is sound. Main items to address before marking ready:

1. Fix rvt-bypass_connectable → rvt-bypass-connectable (kebab-case consistency)
2. Unify the directActorId type into a shared interface
3. Have ActorGatewayOptions extend/reuse GatewayRequestOptions instead of redeclaring bypassConnectable
4. Add an inline comment in #buildGatewayUrlForTarget explaining the directId-vs-query target asymmetry

[NathanFlurry]

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