feat(rivetkit): support gateway bypass client overrides

[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 👈 (View in Graphite)
• 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
• 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]

PR Review: feat(rivetkit): support gateway bypass client overrides

Overview

This PR adds layered gateway bypass configuration support, allowing bypassConnectable to be set at three levels of granularity: client-wide defaults, per-action, and per-connect. The pattern uses resolveActorGatewayOptions(defaults, overrides) to merge the layers at call time.

---

Issues

Medium

Redundant double-nesting in test file (tests/driver/gateway-bypass-client.test.ts): describeDriverMatrix("Gateway Bypass Client", ...) already wraps everything in a suite named "Gateway Bypass Client", but the inner describe("Gateway Bypass Client", ...) repeats the same label. The inner describe is unnecessary.

Fragile actor creation ordering in tests: Several tests create two handles for the same actor key -- one without trackRequest (the "view") and one with { trackRequest: true } (the "tracking" handle). The test implicitly relies on enabledTracking.action(...) being the first call that actually creates the actor so trackRequest: true takes effect. If the framework ever eagerly creates on getOrCreate, or test execution order shifts, the request info will not be tracked. Cleaner to create the actor with a single handle that includes trackRequest: true from the start, then read via a second get-only handle.

Minor

isActorHttpRequestPath computes stripped before guard check (engine-client/mod.ts): No correctness problem since short-circuit evaluation protects it, but computing stripped = path.slice("/request".length) unconditionally before the path.startsWith("/request") guard is slightly misleading. Moving the slice inside or using an early-return makes intent clearer.

Unresolved options passed to buildGatewayUrl (actor-handle.ts, getGatewayUrl method): getGatewayUrl() passes this.#gatewayOptions (typed as ActorGatewayOptions with optional fields) directly to the driver. Every other call site resolves options first via resolveActorGatewayOptions. This path should do the same to ensure consistent defaults.

Inconsistent resolved vs. unresolved field types: ActorConnRaw.#gatewayOptions is typed ResolvedActorGatewayOptions (resolved at construction), while ActorHandleRaw.#gatewayOptions is typed ActorGatewayOptions (resolved per call). The asymmetry is workable but worth a brief comment explaining that handles resolve late to support per-call overrides while connections resolve once at construction.

canUseDirectBypassPath allowlist has no documentation: The allowlist approach is the right security posture (fail closed for unknown paths), but there is no comment explaining why it exists or what it protects against. Future contributors adding new actor routes may not know to update it.

---

What Looks Good

• The three-level override pattern (client -> handle -> call) is clean and consistent. resolveActorGatewayOptions(defaults, overrides) is a simple, correct merge strategy.
• Using an allowlist in canUseDirectBypassPath rather than a blocklist is the right default.
• #resolveGatewayTargetForBypass in ActorConnRaw correctly short-circuits to already-known IDs before doing a round-trip resolution.
• Test coverage spans all four call paths: action with bypass on/off, action overriding client default, connect with bypass, connect overriding client default.

[NathanFlurry]

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