chore(rivetkit): doc skip ready wait

Author: NathanFlurry

rivetkit-typescript/packages/rivetkit/src/client/actor-common.ts

@@ -33,6 +33,7 @@ export type ActorActionFunction<
 
 export interface ActorGatewayOptions {
 	bypassConnectable?: boolean;
+	skipReadyWait?: boolean;
 }
 
 export type ResolvedActorGatewayOptions = Required<ActorGatewayOptions>;
@@ -41,9 +42,16 @@ export function resolveActorGatewayOptions(
 	defaults: ActorGatewayOptions = {},
 	overrides?: ActorGatewayOptions,
 ): ResolvedActorGatewayOptions {
+	const bypassConnectable =
+		overrides?.bypassConnectable ??
+		overrides?.skipReadyWait ??
+		defaults.bypassConnectable ??
+		defaults.skipReadyWait ??
+		false;
+
 	return {
-		bypassConnectable:
-			overrides?.bypassConnectable ?? defaults.bypassConnectable ?? false,
+		bypassConnectable,
+		skipReadyWait: bypassConnectable,
 	};
 }
 

rivetkit-typescript/packages/rivetkit/src/engine-client/actor-http-client.ts

@@ -5,7 +5,10 @@ import {
 	HEADER_RIVET_TARGET,
 	HEADER_RIVET_TOKEN,
 } from "@/common/actor-router-consts";
-import type { GatewayRequestOptions } from "./driver";
+import {
+	shouldBypassConnectable,
+	type GatewayRequestOptions,
+} from "./driver";
 
 export interface HttpGatewayRequestOptions extends GatewayRequestOptions {
 	directActorId?: string;
@@ -79,7 +82,7 @@ function buildGuardHeaders(
 		headers.set(HEADER_RIVET_TARGET, "actor");
 		headers.set(HEADER_RIVET_ACTOR, options.directActorId);
 	}
-	if (options.bypassConnectable) {
+	if (shouldBypassConnectable(options)) {
 		headers.set(HEADER_RIVET_BYPASS_CONNECTABLE, "1");
 	}
 	return headers;

rivetkit-typescript/packages/rivetkit/src/engine-client/actor-websocket-client.ts

@@ -18,7 +18,10 @@ import type { ActorGatewayQuery, CrashPolicy } from "@/client/query";
 import type { Encoding, UniversalWebSocket } from "@/mod";
 import { encodeCborCompat, uint8ArrayToBase64 } from "@/serde";
 import { combineUrlPath } from "@/utils";
-import type { GatewayRequestOptions } from "./driver";
+import {
+	shouldBypassConnectable,
+	type GatewayRequestOptions,
+} from "./driver";
 import { logger } from "./log";
 
 class BufferedRemoteWebSocket implements UniversalWebSocket {
@@ -269,7 +272,7 @@ export function buildActorQueryGatewayUrl(
 	if (token !== undefined) {
 		params.append("rvt-token", token);
 	}
-	if (options.bypassConnectable) {
+	if (shouldBypassConnectable(options)) {
 		params.append("rvt-bypass_connectable", "true");
 	}
 
@@ -392,7 +395,7 @@ export function buildWebSocketProtocols(
 		protocols.push(`${WS_PROTOCOL_TARGET}${target.target}`);
 		protocols.push(`${WS_PROTOCOL_ACTOR}${target.actorId}`);
 	}
-	if (options.bypassConnectable) {
+	if (shouldBypassConnectable(options)) {
 		protocols.push(WS_PROTOCOL_BYPASS_CONNECTABLE);
 	}
 	if (params) {

rivetkit-typescript/packages/rivetkit/src/engine-client/driver.ts

@@ -8,6 +8,13 @@ export type GatewayTarget = { directId: string } | ActorQuery;
 
 export interface GatewayRequestOptions {
 	bypassConnectable?: boolean;
+	skipReadyWait?: boolean;
+}
+
+export function shouldBypassConnectable(
+	options: GatewayRequestOptions = {},
+): boolean {
+	return options.bypassConnectable === true || options.skipReadyWait === true;
 }
 
 export interface EngineControlClient {

rivetkit-typescript/packages/rivetkit/src/engine-client/mod.ts

@@ -9,6 +9,7 @@ import {
 } from "@/common/actor-router-consts";
 import { noopNext } from "@/common/utils";
 import type { Actor as ApiActor } from "@/engine-api/actors";
+import { shouldBypassConnectable } from "@/engine-client/driver";
 import type {
 	ActorOutput,
 	CreateInput,
@@ -264,7 +265,7 @@ export class RemoteEngineControlClient implements EngineControlClient {
 		);
 		const httpOptions = {
 			...options,
-			directActorId: options.bypassConnectable
+			directActorId: shouldBypassConnectable(options)
 				? directActorIdFromTarget(target)
 				: undefined,
 		};
@@ -299,7 +300,7 @@ export class RemoteEngineControlClient implements EngineControlClient {
 			params,
 			{
 				...options,
-				directActorId: options.bypassConnectable
+				directActorId: shouldBypassConnectable(options)
 					? directActorIdFromTarget(target)
 					: undefined,
 			},
@@ -424,7 +425,7 @@ export class RemoteEngineControlClient implements EngineControlClient {
 		const endpoint = getEndpoint(this.#config);
 
 		if (
-			options.bypassConnectable &&
+			shouldBypassConnectable(options) &&
 			directActorIdFromTarget(target) &&
 			canUseDirectBypassPath(path)
 		) {

rivetkit-typescript/packages/rivetkit/tests/actor-gateway-url.test.ts

@@ -7,6 +7,7 @@ import {
 import {
 	buildActorGatewayUrl,
 	buildActorQueryGatewayUrl,
+	buildWebSocketProtocols,
 } from "@/engine-client/actor-websocket-client";
 import { toBase64Url } from "./test-utils";
 
@@ -56,7 +57,30 @@ 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",
+			{
+				getForKey: {
+					name: "room",
+					key: ["alpha"],
+				},
+			},
+			undefined,
+			"/status",
+			undefined,
+			undefined,
+			undefined,
+			{ skipReadyWait: true },
+		);
+
+		expect(new URL(url).searchParams.get("rvt-bypass_connectable")).toBe(
+			"true",
+		);
+	});
+
+	test("serializes bypassConnectable for query routing", () => {
 		const url = buildActorQueryGatewayUrl(
 			"https://api.rivet.dev/manager",
 			"prod",
@@ -79,6 +103,19 @@ describe("gateway URL builders", () => {
 		);
 	});
 
+	test("serializes bypassConnectable for websocket protocols", () => {
+		const protocols = buildWebSocketProtocols(
+			ClientConfigSchema.parse({ endpoint: "https://api.rivet.dev" }),
+			"json",
+			undefined,
+			undefined,
+			{ target: "actor", actorId: "actor-1" },
+			{ bypassConnectable: true },
+		);
+
+		expect(protocols).toContain("rivet_bypass_connectable");
+	});
+
 	test("serializes getOrCreate queries with rvt-* params", () => {
 		const input = { hello: "world" };
 		const url = buildActorQueryGatewayUrl(

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.

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

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:

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)