chore(rivetkit): doc skip ready wait

NathanFlurry · NathanFlurry · commit 656743e24347 · 2026-05-03T21:02:27.000-07:00
diff --git a/rivetkit-typescript/packages/rivetkit/src/client/actor-common.ts b/rivetkit-typescript/packages/rivetkit/src/client/actor-common.ts
@@ -32,7 +32,7 @@ export type ActorActionFunction<
 ) => Promise<Response>;
 
 export interface ActorGatewayOptions {
-	bypassConnectable?: boolean;
+	skipReadyWait?: boolean;
 }
 
 export interface ActorFetchInit extends RequestInit {
diff --git a/rivetkit-typescript/packages/rivetkit/src/client/actor-handle.ts b/rivetkit-typescript/packages/rivetkit/src/client/actor-handle.ts
@@ -793,7 +793,7 @@ export class ActorHandleRaw {
 		options: ActorWebSocketOptions = {},
 	) {
 		const params = await this.#resolveConnectionParams();
-		const target = options.gateway?.bypassConnectable
+		const target = options.gateway?.skipReadyWait
 			? await this.#resolveActionTarget(false)
 			: getGatewayTarget(this.#actorResolutionState);
 		return await rawWebSocket(
diff --git a/rivetkit-typescript/packages/rivetkit/src/engine-client/actor-http-client.ts b/rivetkit-typescript/packages/rivetkit/src/engine-client/actor-http-client.ts
@@ -79,7 +79,7 @@ function buildGuardHeaders(
 		headers.set(HEADER_RIVET_TARGET, "actor");
 		headers.set(HEADER_RIVET_ACTOR, options.directActorId);
 	}
-	if (options.bypassConnectable) {
+	if (options.skipReadyWait) {
 		headers.set(HEADER_RIVET_BYPASS_CONNECTABLE, "1");
 	}
 	return headers;
diff --git a/rivetkit-typescript/packages/rivetkit/src/engine-client/actor-websocket-client.ts b/rivetkit-typescript/packages/rivetkit/src/engine-client/actor-websocket-client.ts
@@ -269,7 +269,7 @@ export function buildActorQueryGatewayUrl(
 	if (token !== undefined) {
 		params.append("rvt-token", token);
 	}
-	if (options.bypassConnectable) {
+	if (options.skipReadyWait) {
 		params.append("rvt-bypass_connectable", "true");
 	}
 
@@ -392,7 +392,7 @@ export function buildWebSocketProtocols(
 		protocols.push(`${WS_PROTOCOL_TARGET}${target.target}`);
 		protocols.push(`${WS_PROTOCOL_ACTOR}${target.actorId}`);
 	}
-	if (options.bypassConnectable) {
+	if (options.skipReadyWait) {
 		protocols.push(WS_PROTOCOL_BYPASS_CONNECTABLE);
 	}
 	if (params) {
diff --git a/rivetkit-typescript/packages/rivetkit/src/engine-client/driver.ts b/rivetkit-typescript/packages/rivetkit/src/engine-client/driver.ts
@@ -7,7 +7,7 @@ import type { ActorQuery, CrashPolicy } from "@/client/query";
 export type GatewayTarget = { directId: string } | ActorQuery;
 
 export interface GatewayRequestOptions {
-	bypassConnectable?: boolean;
+	skipReadyWait?: boolean;
 }
 
 export interface EngineControlClient {
diff --git a/rivetkit-typescript/packages/rivetkit/src/engine-client/mod.ts b/rivetkit-typescript/packages/rivetkit/src/engine-client/mod.ts
@@ -255,7 +255,7 @@ export class RemoteEngineControlClient implements EngineControlClient {
 		const gatewayUrl = this.#buildGatewayUrlForTarget(target, path, options);
 		const httpOptions = {
 			...options,
-			directActorId: options.bypassConnectable
+			directActorId: options.skipReadyWait
 				? directActorIdFromTarget(target)
 				: undefined,
 		};
@@ -286,7 +286,7 @@ export class RemoteEngineControlClient implements EngineControlClient {
 			params,
 			{
 				...options,
-				directActorId: options.bypassConnectable
+				directActorId: options.skipReadyWait
 					? directActorIdFromTarget(target)
 					: undefined,
 			},
@@ -410,7 +410,7 @@ export class RemoteEngineControlClient implements EngineControlClient {
 	): string {
 		const endpoint = getEndpoint(this.#config);
 
-		if (options.bypassConnectable && directActorIdFromTarget(target)) {
+		if (options.skipReadyWait && directActorIdFromTarget(target)) {
 			return combineUrlPath(endpoint, path);
 		}
 
diff --git a/rivetkit-typescript/packages/rivetkit/tests/actor-gateway-url.test.ts b/rivetkit-typescript/packages/rivetkit/tests/actor-gateway-url.test.ts
@@ -56,7 +56,7 @@ describe("gateway URL builders", () => {
 		expect(url).not.toContain("@");
 	});
 
-	test("serializes gateway bypass for query routing", () => {
+	test("serializes skipReadyWait for query routing", () => {
 		const url = buildActorQueryGatewayUrl(
 			"https://api.rivet.dev/manager",
 			"prod",
@@ -71,7 +71,7 @@ describe("gateway URL builders", () => {
 			undefined,
 			undefined,
 			undefined,
-			{ bypassConnectable: true },
+			{ skipReadyWait: true },
 		);
 
 		expect(new URL(url).searchParams.get("rvt-bypass_connectable")).toBe(
diff --git a/website/src/content/docs/actors/lifecycle.mdx b/website/src/content/docs/actors/lifecycle.mdx
@@ -761,6 +761,12 @@ curl -X POST \
 
 `/sleep` asks the actor to enter the normal sleep shutdown sequence. `/reschedule` asks the platform to allocate the actor again, which is useful after crashes or when you need to force a fresh placement. Both endpoints require the actor ID and namespace.
 
+### Skip Ready Wait
+
+The gateway normally holds requests until the actor is ready. The actor is not ready during startup (before `onWake` finishes) or during the sleep grace period (while `onSleep` and `waitUntil` are running). Probes and readiness checks can opt out with `gateway.skipReadyWait` to reach the actor's `onRequest` or `onWebSocket` handler in either window.
+
+See [Skip Ready Wait](/docs/clients/javascript#skip-ready-wait) on the JavaScript client page for usage.
+
 ### Keeping the Actor Awake
 
 RivetKit gives you two primitives for holding the actor awake across background work. Both take a `Promise` and differ in how they interact with idle sleep and the grace period.
diff --git a/website/src/content/docs/actors/request-handler.mdx b/website/src/content/docs/actors/request-handler.mdx
@@ -249,6 +249,12 @@ The `onRequest` handler is WinterTC compliant and will work with existing librar
 - Does not support streaming responses & server-sent events at the moment. See the [tracking issue](https://github.com/rivet-dev/rivet/issues/3529).
 - `OPTIONS` requests currently are handled by Rivet and are not passed to `onRequest`
 
+## Advanced
+
+### Skip Ready Wait
+
+Requests are normally held at the gateway until the actor is ready. Pass `gateway.skipReadyWait: true` on `handle.fetch()` to deliver immediately, including while the actor is still starting or in the [sleep grace period](/docs/actors/lifecycle#shutdown-sequence). See [Skip Ready Wait](/docs/clients/javascript#skip-ready-wait) for details.
+
 ## API Reference
 
 - [`RequestContext`](/typedoc/interfaces/rivetkit.mod.RequestContext.html) - Context for HTTP request handlers
diff --git a/website/src/content/docs/actors/websocket-handler.mdx b/website/src/content/docs/actors/websocket-handler.mdx
@@ -295,6 +295,10 @@ const myActor = actor({
 });
 ```
 
+### Skip Ready Wait
+
+Connections are normally held at the gateway until the actor is ready. Pass `gateway.skipReadyWait: true` on `handle.webSocket()` to connect immediately, including while the actor is still starting or in the [sleep grace period](/docs/actors/lifecycle#shutdown-sequence). See [Skip Ready Wait](/docs/clients/javascript#skip-ready-wait) for details.
+
 ### Async Handlers
 
 The `onWebSocket` handler can be async, allowing you to perform async code before setting up event listeners:
diff --git a/website/src/content/docs/clients/javascript.mdx b/website/src/content/docs/clients/javascript.mdx
@@ -253,6 +253,31 @@ https://namespace:token@api.rivet.dev
 
 You can also pass the endpoint without auth and provide `RIVET_NAMESPACE` and `RIVET_TOKEN` separately. For serverless deployments, use your app's `/api/rivet` URL. See [Endpoints](/docs/general/endpoints#url-auth-syntax) for details.
 
+## Advanced
+
+### Skip Ready Wait
+
+Requests are normally held at the gateway until the actor is ready to accept traffic. An actor is not ready while it's still starting (before `onWake` finishes) or while it's in the [sleep grace period](/docs/actors/lifecycle#shutdown-sequence) (running `onSleep`, `waitUntil`, and pending disconnects).
+
+Pass `gateway.skipReadyWait: true` on the [low-level HTTP and WebSocket APIs](#low-level-http--websocket) to deliver immediately and reach the actor's `onRequest` / `onWebSocket` handler in either window:
+
+```ts @nocheck
+import { createClient } from "rivetkit/client";
+
+const client = createClient();
+const handle = client.chatRoom.getOrCreate(["general"]);
+
+const response = await handle.fetch("/healthz", {
+  gateway: { skipReadyWait: true },
+});
+
+const ws = await handle.webSocket("probe", undefined, {
+  gateway: { skipReadyWait: true },
+});
+```
+
+Requests still return a transient `actor.stopping` lifecycle error (`{"group":"actor","code":"stopping","message":"Actor is stopping."}`) if the actor has fully stopped, i.e. the sleep grace period has ended but it has not yet restarted. Retry once the actor is available again.
+
 ## API Reference
 
 **Package:** [rivetkit](https://www.npmjs.com/package/rivetkit)

Original file line number	Diff line number	Diff line change
`@@ -32,7 +32,7 @@ export type ActorActionFunction<`
`32`	`32`	`) => Promise<Response>;`
`33`	`33`
`34`	`34`	`export interface ActorGatewayOptions {`
`35`		`- bypassConnectable?: boolean;`
	`35`	`+ skipReadyWait?: boolean;`
`36`	`36`	`}`
`37`	`37`
`38`	`38`	`export interface ActorFetchInit extends RequestInit {`
Original file line number	Diff line number	Diff line change
`@@ -79,7 +79,7 @@ function buildGuardHeaders(`
`79`	`79`	`headers.set(HEADER_RIVET_TARGET, "actor");`
`80`	`80`	`headers.set(HEADER_RIVET_ACTOR, options.directActorId);`
`81`	`81`	`}`
`82`		`- if (options.bypassConnectable) {`
	`82`	`+ if (options.skipReadyWait) {`
`83`	`83`	`headers.set(HEADER_RIVET_BYPASS_CONNECTABLE, "1");`
`84`	`84`	`}`
`85`	`85`	`return headers;`
Original file line number	Diff line number	Diff line change
`@@ -269,7 +269,7 @@ export function buildActorQueryGatewayUrl(`
`269`	`269`	`if (token !== undefined) {`
`270`	`270`	`params.append("rvt-token", token);`
`271`	`271`	`}`
`272`		`- if (options.bypassConnectable) {`
	`272`	`+ if (options.skipReadyWait) {`
`273`	`273`	`params.append("rvt-bypass_connectable", "true");`
`274`	`274`	`}`
`275`	`275`
`@@ -392,7 +392,7 @@ export function buildWebSocketProtocols(`
`392`	`392`	protocols.push(`${WS_PROTOCOL_TARGET}${target.target}`);
`393`	`393`	protocols.push(`${WS_PROTOCOL_ACTOR}${target.actorId}`);
`394`	`394`	`}`
`395`		`- if (options.bypassConnectable) {`
	`395`	`+ if (options.skipReadyWait) {`
`396`	`396`	`protocols.push(WS_PROTOCOL_BYPASS_CONNECTABLE);`
`397`	`397`	`}`
`398`	`398`	`if (params) {`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@ import type { ActorQuery, CrashPolicy } from "@/client/query";`
`7`	`7`	`export type GatewayTarget = { directId: string } \| ActorQuery;`
`8`	`8`
`9`	`9`	`export interface GatewayRequestOptions {`
`10`		`- bypassConnectable?: boolean;`
	`10`	`+ skipReadyWait?: boolean;`
`11`	`11`	`}`
`12`	`12`
`13`	`13`	`export interface EngineControlClient {`