rivetkit 2.3.29 → 3.0.0-preview.1

package/dist/tsup/test/mod.cjs

@@ -1,13 +1,13 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
-var _chunkCRBPB6QIcjs = require('../chunk-CRBPB6QI.cjs');
+var _chunk6DDQSAATcjs = require('../chunk-6DDQSAAT.cjs');
 
 
-var _chunkWSSI5L6Lcjs = require('../chunk-WSSI5L6L.cjs');
-require('../chunk-MYWZCDML.cjs');
-require('../chunk-Q6GKUC22.cjs');
+var _chunkCTQKKUZCcjs = require('../chunk-CTQKKUZC.cjs');
+require('../chunk-RTWH3AX3.cjs');
+require('../chunk-HW2D5OFJ.cjs');
 require('../chunk-KVFIONKQ.cjs');
-require('../chunk-DTGPF6XY.cjs');
+require('../chunk-IBEFA6CX.cjs');
 require('../chunk-MGI2VVF6.cjs');
 
 // src/test/ready.ts
@@ -36,8 +36,8 @@ async function setupTest(c, registry) {
   registry.config.noWelcome = true;
   registry.start();
   await waitForRegistryReady(registry);
-  const client = _chunkCRBPB6QIcjs.createClient.call(void 0, {
-    ..._chunkWSSI5L6Lcjs.convertRegistryConfigToClientConfig.call(void 0, registry.parseConfig()),
+  const client = _chunk6DDQSAATcjs.createClient.call(void 0, {
+    ..._chunkCTQKKUZCcjs.convertRegistryConfigToClientConfig.call(void 0, registry.parseConfig()),
     disableMetadataLookup: false
   });
   c.onTestFinished(async () => {

package/dist/tsup/test/mod.d.cts

@@ -1,7 +1,7 @@
 import { TestContext } from 'vitest';
-import { aI as Registry, a6 as Client } from '../config-osdJqQwX.cjs';
+import { aI as Registry, a6 as Client } from '../config-8NgsxIcT.cjs';
 import 'zod/v4';
-import '../config-ey2I2zz5.cjs';
+import '../config-B2wlj9wx.cjs';
 import '@rivetkit/rivetkit-wasm';
 import 'zod';
 import 'pino';

package/dist/tsup/test/mod.d.ts

@@ -1,7 +1,7 @@
 import { TestContext } from 'vitest';
-import { aI as Registry, a6 as Client } from '../config-Cv6pjCt-.js';
+import { aI as Registry, a6 as Client } from '../config-DJ3KW-fe.js';
 import 'zod/v4';
-import '../config-ey2I2zz5.js';
+import '../config-B2wlj9wx.js';
 import '@rivetkit/rivetkit-wasm';
 import 'zod';
 import 'pino';

package/dist/tsup/test/mod.js

@@ -1,13 +1,13 @@
 import {
   createClient
-} from "../chunk-SNFXCNXD.js";
+} from "../chunk-DQ6K3VVV.js";
 import {
   convertRegistryConfigToClientConfig
-} from "../chunk-K7QBHEVI.js";
-import "../chunk-JI6GZ2C2.js";
-import "../chunk-IXJCAFAQ.js";
+} from "../chunk-3MMTF3QA.js";
+import "../chunk-A2CF6PFH.js";
+import "../chunk-DCDCHB5J.js";
 import "../chunk-JTHHCZCZ.js";
-import "../chunk-WHA3XM3R.js";
+import "../chunk-5OCN7VHH.js";
 import "../chunk-ZOVJDAOW.js";
 
 // src/test/ready.ts

package/dist/tsup/unstable/migrations.d.cts

@@ -1,4 +1,4 @@
-import { R as RawAccess } from '../config-ey2I2zz5.cjs';
+import { R as RawAccess } from '../config-B2wlj9wx.cjs';
 
 declare const DEFAULT_MIGRATION_TABLE_NAME = "rivetkit_schema_version";
 type MigrationDatabase = Pick<RawAccess, "execute">;

package/dist/tsup/unstable/migrations.d.ts

@@ -1,4 +1,4 @@
-import { R as RawAccess } from '../config-ey2I2zz5.js';
+import { R as RawAccess } from '../config-B2wlj9wx.js';
 
 declare const DEFAULT_MIGRATION_TABLE_NAME = "rivetkit_schema_version";
 type MigrationDatabase = Pick<RawAccess, "execute">;

package/dist/tsup/utils.cjs

@@ -19,7 +19,7 @@
 
 
 
-var _chunkDTGPF6XYcjs = require('./chunk-DTGPF6XY.cjs');
+var _chunkIBEFA6CXcjs = require('./chunk-IBEFA6CX.cjs');
 require('./chunk-MGI2VVF6.cjs');
 
 
@@ -42,5 +42,5 @@ require('./chunk-MGI2VVF6.cjs');
 
 
 
-exports.EXTRA_ERROR_LOG = _chunkDTGPF6XYcjs.EXTRA_ERROR_LOG; exports.SinglePromiseQueue = _chunkDTGPF6XYcjs.SinglePromiseQueue; exports.VERSION = _chunkDTGPF6XYcjs.VERSION; exports.arrayBuffersEqual = _chunkDTGPF6XYcjs.arrayBuffersEqual; exports.assertUnreachable = _chunkDTGPF6XYcjs.assertUnreachable; exports.bufferToArrayBuffer = _chunkDTGPF6XYcjs.bufferToArrayBuffer; exports.combineUrlPath = _chunkDTGPF6XYcjs.combineUrlPath; exports.dbg = _chunkDTGPF6XYcjs.dbg; exports.detectRuntime = _chunkDTGPF6XYcjs.detectRuntime; exports.getEnvUniversal = _chunkDTGPF6XYcjs.getEnvUniversal; exports.httpUserAgent = _chunkDTGPF6XYcjs.httpUserAgent; exports.interval = _chunkDTGPF6XYcjs.interval; exports.joinSignals = _chunkDTGPF6XYcjs.joinSignals; exports.jsonParseCompat = _chunkDTGPF6XYcjs.jsonParseCompat; exports.jsonStringifyCompat = _chunkDTGPF6XYcjs.jsonStringifyCompat; exports.promiseWithResolvers = _chunkDTGPF6XYcjs.promiseWithResolvers; exports.setLongTimeout = _chunkDTGPF6XYcjs.setLongTimeout; exports.sleep = _chunkDTGPF6XYcjs.sleep; exports.stringifyError = _chunkDTGPF6XYcjs.stringifyError; exports.toUint8Array = _chunkDTGPF6XYcjs.toUint8Array;
+exports.EXTRA_ERROR_LOG = _chunkIBEFA6CXcjs.EXTRA_ERROR_LOG; exports.SinglePromiseQueue = _chunkIBEFA6CXcjs.SinglePromiseQueue; exports.VERSION = _chunkIBEFA6CXcjs.VERSION; exports.arrayBuffersEqual = _chunkIBEFA6CXcjs.arrayBuffersEqual; exports.assertUnreachable = _chunkIBEFA6CXcjs.assertUnreachable; exports.bufferToArrayBuffer = _chunkIBEFA6CXcjs.bufferToArrayBuffer; exports.combineUrlPath = _chunkIBEFA6CXcjs.combineUrlPath; exports.dbg = _chunkIBEFA6CXcjs.dbg; exports.detectRuntime = _chunkIBEFA6CXcjs.detectRuntime; exports.getEnvUniversal = _chunkIBEFA6CXcjs.getEnvUniversal; exports.httpUserAgent = _chunkIBEFA6CXcjs.httpUserAgent; exports.interval = _chunkIBEFA6CXcjs.interval; exports.joinSignals = _chunkIBEFA6CXcjs.joinSignals; exports.jsonParseCompat = _chunkIBEFA6CXcjs.jsonParseCompat; exports.jsonStringifyCompat = _chunkIBEFA6CXcjs.jsonStringifyCompat; exports.promiseWithResolvers = _chunkIBEFA6CXcjs.promiseWithResolvers; exports.setLongTimeout = _chunkIBEFA6CXcjs.setLongTimeout; exports.sleep = _chunkIBEFA6CXcjs.sleep; exports.stringifyError = _chunkIBEFA6CXcjs.stringifyError; exports.toUint8Array = _chunkIBEFA6CXcjs.toUint8Array;
 //# sourceMappingURL=utils.cjs.map

package/dist/tsup/utils.js

@@ -19,7 +19,7 @@ import {
   sleep,
   stringifyError,
   toUint8Array
-} from "./chunk-WHA3XM3R.js";
+} from "./chunk-5OCN7VHH.js";
 import "./chunk-ZOVJDAOW.js";
 export {
   EXTRA_ERROR_LOG,

package/dist/tsup/workflow/mod.cjs

@@ -1,8 +1,8 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } async function _asyncNullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return await rhsFn(); } } var _class; var _class2;
 
-var _chunkWHAUEDUTcjs = require('../chunk-WHAUEDUT.cjs');
-require('../chunk-RDBXO2ND.cjs');
-require('../chunk-NK4D6G45.cjs');
+var _chunk3E2BPHQOcjs = require('../chunk-3E2BPHQO.cjs');
+require('../chunk-XUO6G4H6.cjs');
+require('../chunk-VCVV726P.cjs');
 
 
 
@@ -10,10 +10,10 @@ var _chunkHDVZ6YZGcjs = require('../chunk-HDVZ6YZG.cjs');
 
 
 
-var _chunkMYWZCDMLcjs = require('../chunk-MYWZCDML.cjs');
+var _chunkRTWH3AX3cjs = require('../chunk-RTWH3AX3.cjs');
 
 
-var _chunkDTGPF6XYcjs = require('../chunk-DTGPF6XY.cjs');
+var _chunkIBEFA6CXcjs = require('../chunk-IBEFA6CX.cjs');
 
 
 
@@ -355,7 +355,7 @@ var WorkflowContext = class _WorkflowContext {
 };
 
 // src/workflow/driver.ts
-var WORKFLOW_STORAGE_PREFIX = _chunkMYWZCDMLcjs.workflowStoragePrefix.call(void 0, );
+var WORKFLOW_STORAGE_PREFIX = _chunkRTWH3AX3cjs.workflowStoragePrefix.call(void 0, );
 var WORKFLOW_SQLITE_MAX_BATCH_ROWS = 128;
 var WORKFLOW_SQLITE_MAX_BATCH_BYTES = 512 * 1024;
 function stripWorkflowKey(prefixed) {
@@ -412,7 +412,7 @@ var WorkflowStorage = class {
   }
   async get(key) {
     var _a;
-    const prefixed = _chunkMYWZCDMLcjs.makeWorkflowKey.call(void 0, key);
+    const prefixed = _chunkRTWH3AX3cjs.makeWorkflowKey.call(void 0, key);
     const rows = await this.#db.execute(
       "SELECT value FROM _rivet_wf_kv WHERE key = ?",
       prefixed
@@ -423,7 +423,7 @@ var WorkflowStorage = class {
     await this.batch([{ key, value }]);
   }
   async delete(key) {
-    const prefixed = _chunkMYWZCDMLcjs.makeWorkflowKey.call(void 0, key);
+    const prefixed = _chunkRTWH3AX3cjs.makeWorkflowKey.call(void 0, key);
     await this.#db.execute(
       "DELETE FROM _rivet_wf_kv WHERE key = ?",
       prefixed
@@ -431,10 +431,10 @@ var WorkflowStorage = class {
   }
   async batchDelete(keys) {
     if (keys.length === 0) return;
-    await this.deleteRawKeys(keys.map((key) => _chunkMYWZCDMLcjs.makeWorkflowKey.call(void 0, key)));
+    await this.deleteRawKeys(keys.map((key) => _chunkRTWH3AX3cjs.makeWorkflowKey.call(void 0, key)));
   }
   async deletePrefix(prefix) {
-    const start = _chunkMYWZCDMLcjs.makeWorkflowKey.call(void 0, prefix);
+    const start = _chunkRTWH3AX3cjs.makeWorkflowKey.call(void 0, prefix);
     const end = computeUpperBound(start);
     if (end) {
       await this.#db.execute(
@@ -450,8 +450,8 @@ var WorkflowStorage = class {
     );
   }
   async deleteRange(start, end) {
-    const prefixedStart = _chunkMYWZCDMLcjs.makeWorkflowKey.call(void 0, start);
-    const prefixedEnd = _chunkMYWZCDMLcjs.makeWorkflowKey.call(void 0, end);
+    const prefixedStart = _chunkRTWH3AX3cjs.makeWorkflowKey.call(void 0, start);
+    const prefixedEnd = _chunkRTWH3AX3cjs.makeWorkflowKey.call(void 0, end);
     await this.#db.execute(
       "DELETE FROM _rivet_wf_kv WHERE key >= ? AND key < ?",
       prefixedStart,
@@ -459,7 +459,7 @@ var WorkflowStorage = class {
     );
   }
   async list(prefix) {
-    const prefixed = _chunkMYWZCDMLcjs.makeWorkflowKey.call(void 0, prefix);
+    const prefixed = _chunkRTWH3AX3cjs.makeWorkflowKey.call(void 0, prefix);
     const entries = await this.listRaw(prefixed);
     return entries.filter(([key]) => keyStartsWith(key, prefixed)).map(([key, value]) => ({
       key: stripWorkflowKey(key),
@@ -473,7 +473,7 @@ var WorkflowStorage = class {
         for (const { key, value } of chunk) {
           await tx.execute(
             "INSERT INTO _rivet_wf_kv (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
-            _chunkMYWZCDMLcjs.makeWorkflowKey.call(void 0, key),
+            _chunkRTWH3AX3cjs.makeWorkflowKey.call(void 0, key),
             value
           );
         }
@@ -743,7 +743,7 @@ function workflow(fn, options = {}) {
   function getWorkflowInspector(actorId) {
     let workflowInspector = workflowInspectors.get(actorId);
     if (!workflowInspector) {
-      workflowInspector = _chunkWHAUEDUTcjs.createWorkflowInspectorAdapter.call(void 0, );
+      workflowInspector = _chunk3E2BPHQOcjs.createWorkflowInspectorAdapter.call(void 0, );
       workflowInspectors.set(actorId, workflowInspector);
     }
     return workflowInspector;
@@ -816,13 +816,13 @@ function workflow(fn, options = {}) {
       if (shouldRethrowWorkflowError(error)) {
         runCtx.log.error({
           msg: "workflow run failed",
-          error: _chunkDTGPF6XYcjs.stringifyError.call(void 0, error)
+          error: _chunkIBEFA6CXcjs.stringifyError.call(void 0, error)
         });
         throw error;
       }
       runCtx.log.warn({
         msg: "workflow failed and will sleep until woken",
-        error: _chunkDTGPF6XYcjs.stringifyError.call(void 0, error)
+        error: _chunkIBEFA6CXcjs.stringifyError.call(void 0, error)
       });
     } finally {
       runCtx.abortSignal.removeEventListener("abort", onAbort);

package/dist/tsup/workflow/mod.d.cts

@@ -1,9 +1,9 @@
 import { WorkflowErrorEvent } from '@rivetkit/workflow-engine';
 export { Loop, TryBlockCatchKind, TryBlockConfig, TryBlockFailure, TryBlockResult, TryStepCatchKind, TryStepConfig, TryStepFailure, TryStepResult, WorkflowError, WorkflowErrorEvent } from '@rivetkit/workflow-engine';
-import { E as EventSchemaConfig, Q as QueueSchemaConfig, h as RunContext } from '../config-osdJqQwX.cjs';
-import { A as AnyDatabaseProvider } from '../config-ey2I2zz5.cjs';
-import { d as WorkflowContext } from '../context-DpjrM7n7.cjs';
-export { e as WorkflowBranchConfig, W as WorkflowBranchContextOf, a as WorkflowContextOf, f as WorkflowLoopConfig, b as WorkflowLoopContextOf, g as WorkflowStepConfig, h as WorkflowStepContext, c as WorkflowStepContextOf, i as WorkflowTryConfig, j as WorkflowTryStepConfig } from '../context-DpjrM7n7.cjs';
+import { E as EventSchemaConfig, Q as QueueSchemaConfig, h as RunContext } from '../config-8NgsxIcT.cjs';
+import { A as AnyDatabaseProvider } from '../config-B2wlj9wx.cjs';
+import { d as WorkflowContext } from '../context-_RoE_YHL.cjs';
+export { e as WorkflowBranchConfig, W as WorkflowBranchContextOf, a as WorkflowContextOf, f as WorkflowLoopConfig, b as WorkflowLoopContextOf, g as WorkflowStepConfig, h as WorkflowStepContext, c as WorkflowStepContextOf, i as WorkflowTryConfig, j as WorkflowTryStepConfig } from '../context-_RoE_YHL.cjs';
 import 'zod/v4';
 import '@rivetkit/rivetkit-wasm';
 import 'zod';

package/dist/tsup/workflow/mod.d.ts

@@ -1,9 +1,9 @@
 import { WorkflowErrorEvent } from '@rivetkit/workflow-engine';
 export { Loop, TryBlockCatchKind, TryBlockConfig, TryBlockFailure, TryBlockResult, TryStepCatchKind, TryStepConfig, TryStepFailure, TryStepResult, WorkflowError, WorkflowErrorEvent } from '@rivetkit/workflow-engine';
-import { E as EventSchemaConfig, Q as QueueSchemaConfig, h as RunContext } from '../config-Cv6pjCt-.js';
-import { A as AnyDatabaseProvider } from '../config-ey2I2zz5.js';
-import { d as WorkflowContext } from '../context-CoVbKBuk.js';
-export { e as WorkflowBranchConfig, W as WorkflowBranchContextOf, a as WorkflowContextOf, f as WorkflowLoopConfig, b as WorkflowLoopContextOf, g as WorkflowStepConfig, h as WorkflowStepContext, c as WorkflowStepContextOf, i as WorkflowTryConfig, j as WorkflowTryStepConfig } from '../context-CoVbKBuk.js';
+import { E as EventSchemaConfig, Q as QueueSchemaConfig, h as RunContext } from '../config-DJ3KW-fe.js';
+import { A as AnyDatabaseProvider } from '../config-B2wlj9wx.js';
+import { d as WorkflowContext } from '../context-BL8kUGjq.js';
+export { e as WorkflowBranchConfig, W as WorkflowBranchContextOf, a as WorkflowContextOf, f as WorkflowLoopConfig, b as WorkflowLoopContextOf, g as WorkflowStepConfig, h as WorkflowStepContext, c as WorkflowStepContextOf, i as WorkflowTryConfig, j as WorkflowTryStepConfig } from '../context-BL8kUGjq.js';
 import 'zod/v4';
 import '@rivetkit/rivetkit-wasm';
 import 'zod';

package/dist/tsup/workflow/mod.js

@@ -1,8 +1,8 @@
 import {
   createWorkflowInspectorAdapter
-} from "../chunk-7TRYBX2R.js";
-import "../chunk-U3KY2OGG.js";
-import "../chunk-JMUNIWKG.js";
+} from "../chunk-TBJ4I3R3.js";
+import "../chunk-SJPPKBT3.js";
+import "../chunk-KQ2WQDYT.js";
 import {
   ACTOR_CONTEXT_INTERNAL_SYMBOL,
   defineRunHandler
@@ -10,10 +10,10 @@ import {
 import {
   makeWorkflowKey,
   workflowStoragePrefix
-} from "../chunk-JI6GZ2C2.js";
+} from "../chunk-A2CF6PFH.js";
 import {
   stringifyError
-} from "../chunk-WHA3XM3R.js";
+} from "../chunk-5OCN7VHH.js";
 import {
   RivetError,
   isActorAbortedError

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rivetkit",
-	"version": "2.3.29",
+	"version": "3.0.0-preview.1",
 	"description": "Lightweight libraries for building stateful actors on edge platforms",
 	"license": "Apache-2.0",
 	"keywords": [
@@ -210,17 +210,16 @@
 	"dependencies": {
 		"@hono/zod-openapi": "^1.1.5",
 		"@opentelemetry/api": "^1.1.0",
-		"@rivet-dev/services": "^0.2.3",
 		"@rivetkit/bare-ts": "^0.6.2",
-		"@rivetkit/engine-api-full": "2.3.29",
-		"@rivetkit/engine-cli": "2.3.29",
-		"@rivetkit/engine-envoy-protocol": "2.3.29",
+		"@rivetkit/engine-api-full": "3.0.0-preview.1",
+		"@rivetkit/engine-cli": "3.0.0-preview.1",
+		"@rivetkit/engine-envoy-protocol": "3.0.0-preview.1",
 		"@rivetkit/on-change": "6.0.1",
-		"@rivetkit/rivetkit-napi": "2.3.29",
-		"@rivetkit/rivetkit-wasm": "2.3.29",
-		"@rivetkit/traces": "2.3.29",
-		"@rivetkit/virtual-websocket": "2.3.29",
-		"@rivetkit/workflow-engine": "2.3.29",
+		"@rivetkit/rivetkit-napi": "3.0.0-preview.1",
+		"@rivetkit/rivetkit-wasm": "3.0.0-preview.1",
+		"@rivetkit/traces": "3.0.0-preview.1",
+		"@rivetkit/virtual-websocket": "3.0.0-preview.1",
+		"@rivetkit/workflow-engine": "3.0.0-preview.1",
 		"cbor-x": "^1.6.0",
 		"drizzle-orm": "0.45.2",
 		"hono": "^4.7.0",

package/src/actor/keys.ts

@@ -60,6 +60,8 @@ const TRACES_STORAGE_PREFIX = concatPrefix(
 	STORAGE_VERSION_BYTES.TRACES,
 );
 
+// The slash key form the actor REST API and the actor runtime use. The engine translates it to
+// the canonical form (`encodeActorKey`) at those boundaries.
 export function serializeActorKey(key: ActorKey): string {
 	// Use a special marker for empty key arrays
 	if (key.length === 0) {
@@ -145,6 +147,90 @@ export function deserializeActorKey(keyString: string | undefined): ActorKey {
 	return parts;
 }
 
+// The canonical actor key: parts joined with `,`, with `\` and `,` escaped by a backslash, an
+// empty part written as `\0`, and the empty key as the empty string. The engine hashes, stores
+// and compares only canonical keys, and the gateway's `rvt-key` carries one. The Rust twin is
+// `rivetkit_shared_types::actor_key`; both run the vectors in
+// `rivetkit-rust/packages/shared-types/tests/fixtures/actor_key_vectors.json`.
+const CANONICAL_SEPARATOR = ",";
+const CANONICAL_EMPTY_PART = "\\0";
+
+/** Encodes `key` in the canonical form. */
+export function encodeActorKey(key: ActorKey): string {
+	return key
+		.map((part) => {
+			if (part === "") {
+				return CANONICAL_EMPTY_PART;
+			}
+			return part.replace(/\\/g, "\\\\").replace(/,/g, "\\,");
+		})
+		.join(CANONICAL_SEPARATOR);
+}
+
+/**
+ * Decodes a canonical key, or an unescaped `rvt-key` value from an earlier client. Only `\\` and
+ * `\,` are escapes; any other backslash is literal, and a part written as exactly `\0` is empty.
+ */
+export function decodeActorKey(key: string): ActorKey {
+	if (key === "") {
+		return [];
+	}
+
+	const parts: string[] = [];
+	let raw = "";
+	let current = "";
+	const finishPart = () => {
+		parts.push(raw === CANONICAL_EMPTY_PART ? "" : current);
+		raw = "";
+		current = "";
+	};
+	for (let i = 0; i < key.length; i++) {
+		const char = key[i];
+		if (char === CANONICAL_SEPARATOR) {
+			finishPart();
+			continue;
+		}
+
+		raw += char;
+		if (char !== "\\") {
+			current += char;
+			continue;
+		}
+
+		const next = key[i + 1];
+		if (next === "\\" || next === CANONICAL_SEPARATOR) {
+			raw += next;
+			current += next;
+			i++;
+		} else {
+			current += char;
+		}
+	}
+	finishPart();
+	return parts;
+}
+
+/**
+ * The gateway's `rvt-key` query value for `key`: the canonical key, or `undefined` when the
+ * parameter is omitted, as it is for the empty key.
+ */
+export function actorKeyToGatewayQuery(key: ActorKey): string | undefined {
+	if (key.length === 0) {
+		return undefined;
+	}
+	return encodeActorKey(key);
+}
+
+/** Reads the gateway's `rvt-key` query value. A missing value is the empty key. */
+export function actorKeyFromGatewayQuery(
+	rvtKey: string | null | undefined,
+): ActorKey {
+	if (rvtKey === undefined || rvtKey === null) {
+		return [];
+	}
+	return decodeActorKey(rvtKey);
+}
+
 export function makePrefixedKey(key: Uint8Array): Uint8Array {
 	const prefixed = new Uint8Array(KEYS.KV.length + key.length);
 	prefixed.set(KEYS.KV, 0);

package/src/client/actor-conn.ts

@@ -50,6 +50,7 @@ import {
 import { ACTOR_CONNS_SYMBOL, type ClientRaw } from "./client";
 import * as errors from "./errors";
 import { isRetryableLifecycleReconnectSignal } from "./lifecycle-errors";
+import { retryAfterMs } from "./retry-budget";
 import { logger } from "./log";
 import { isInvalidToken } from "./token-provider";
 import { outboundTelemetryHeaders } from "./outbound-telemetry";
@@ -104,6 +105,21 @@ interface EventSubscriptions<Args extends Array<unknown>> {
  */
 export type EventUnsubscribe = () => void;
 
+/**
+ * How long a connection attempt may wait for the actor's Init before it is abandoned and
+ * retried. Longer than the engine's own WebSocket open deadline (15 s by default), so an engine
+ * that answers with a typed close wins, while a socket that never settles is still retried.
+ */
+const CONNECT_TIMEOUT_MS = 20_000;
+
+function isConnectionOpenTimeout(error: unknown): boolean {
+	return (
+		error instanceof errors.ActorError &&
+		error.group === "client" &&
+		error.code === "connection_open_timeout"
+	);
+}
+
 /**
  * A function that handles connection errors.
  *
@@ -182,6 +198,8 @@ export class ActorConnRaw {
 
 	/** Promise used to indicate the socket has connected successfully. This will be rejected if the connection fails. */
 	#onOpenPromise?: ReturnType<typeof promiseWithResolvers<undefined>>;
+	/** Sockets given up on by the connect timeout. Their late events are ignored. */
+	#abandonedSockets = new WeakSet<UniversalWebSocket>();
 
 	#websocket?: UniversalWebSocket;
 	#authRetryAvailable = true;
@@ -457,12 +475,17 @@ export class ActorConnRaw {
 			minTimeout: 250,
 			maxTimeout: 30_000,
 
-			onFailedAttempt: (error) => {
+			onFailedAttempt: async (error) => {
 				logger().warn({
 					msg: "failed to reconnect",
 					attempt: error.attemptNumber,
 					error: stringifyError(error),
 				});
+				// A close that carried the service's retry hint waits at least that long.
+				const hintMs = retryAfterMs(error);
+				if (hintMs !== undefined) {
+					await new Promise((resolve) => setTimeout(resolve, hintMs));
+				}
 			},
 
 			// Cancel retry if aborted
@@ -498,7 +521,7 @@ export class ActorConnRaw {
 			await this.#connectWebSocket();
 
 			// Wait for result
-			await this.#onOpenPromise.promise;
+			await this.#waitForOpen(this.#onOpenPromise.promise);
 		} catch (error) {
 			if (this.#shouldRetryConnectionOpenError(error)) {
 				throw error;
@@ -529,10 +552,65 @@ export class ActorConnRaw {
 		}
 	}
 
+	/**
+	 * Waits for the actor's Init on the current socket, up to {@link CONNECT_TIMEOUT_MS}. A socket
+	 * can stay connecting with no open, error or close event, as when the engine holds the
+	 * upgrade or a refused connect reports only an error. On timeout the socket is abandoned
+	 * and closed, and the retryable `client.connection_open_timeout` starts the next attempt.
+	 */
+	async #waitForOpen(open: Promise<undefined>) {
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const timedOut = new Promise<never>((_, reject) => {
+			timer = setTimeout(() => {
+				reject(
+					new errors.ActorError(
+						"client",
+						"connection_open_timeout",
+						`Connection did not open within ${CONNECT_TIMEOUT_MS} ms`,
+					),
+				);
+			}, CONNECT_TIMEOUT_MS);
+		});
+		try {
+			await Promise.race([open, timedOut]);
+		} catch (error) {
+			if (isConnectionOpenTimeout(error)) {
+				this.#abandonCurrentSocket();
+			}
+			throw error;
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+
+	#abandonCurrentSocket() {
+		const ws = this.#websocket;
+		if (!ws) return;
+		this.#websocket = undefined;
+		this.#abandonedSockets.add(ws);
+		logger().warn({
+			msg: "connection did not open in time, retrying",
+			connId: this.#connId,
+			readyState: ws.readyState,
+			timeoutMs: CONNECT_TIMEOUT_MS,
+		});
+		try {
+			ws.close(1000, "Connect timeout");
+		} catch (err) {
+			logger().debug({
+				msg: "failed to close abandoned websocket",
+				error: stringifyError(err),
+			});
+		}
+	}
+
 	#shouldRetryConnectionOpenError(error: unknown): boolean {
 		if (error instanceof errors.ActorConnDisposed) {
 			return false;
 		}
+		if (isConnectionOpenTimeout(error)) {
+			return true;
+		}
 		if (
 			error instanceof errors.ActorError &&
 			isInvalidToken(error.group, error.code) &&
@@ -614,12 +692,14 @@ export class ActorConnRaw {
 		});
 		this.#websocket = ws;
 		ws.addEventListener("open", () => {
+			if (this.#abandonedSockets.has(ws)) return;
 			logger().debug({
 				msg: "client websocket open",
 				connId: this.#connId,
 			});
 		});
 		ws.addEventListener("message", async (ev: { data: ConnMessage }) => {
+			if (this.#abandonedSockets.has(ws)) return;
 			try {
 				await this.#handleOnMessage(ev.data);
 			} catch (err) {
@@ -630,6 +710,7 @@ export class ActorConnRaw {
 			}
 		});
 		ws.addEventListener("close", async (ev: Event | CloseEventLike) => {
+			if (this.#abandonedSockets.has(ws)) return;
 			try {
 				await this.#handleOnClose(ev);
 			} catch (err) {
@@ -640,6 +721,7 @@ export class ActorConnRaw {
 			}
 		});
 		ws.addEventListener("error", () => {
+			if (this.#abandonedSockets.has(ws)) return;
 			try {
 				this.#handleOnError();
 			} catch (err) {
@@ -894,7 +976,11 @@ export class ActorConnRaw {
 			const parsed = parseWebSocketCloseReason(reason);
 
 			if (parsed) {
-				const { group, code, rayId } = parsed;
+				const { group, code, rayId, retryAfterMs } = parsed;
+				const closeOptions =
+					retryAfterMs === undefined
+						? { rayId }
+						: { rayId, metadata: { retry_after_ms: retryAfterMs } };
 				if (
 					isInvalidToken(group, code) &&
 					closeEvent.code === 1008 &&
@@ -923,7 +1009,7 @@ export class ActorConnRaw {
 							group,
 							code,
 							`Connection closed: ${reason}`,
-							{ rayId },
+							closeOptions,
 						),
 					);
 					return;
@@ -946,7 +1032,7 @@ export class ActorConnRaw {
 							group,
 							code,
 							`Connection closed: ${reason}`,
-							{ rayId },
+							closeOptions,
 						);
 					}
 				} else {
@@ -954,7 +1040,7 @@ export class ActorConnRaw {
 						group,
 						code,
 						`Connection closed: ${reason}`,
-						{ rayId },
+						closeOptions,
 					);
 				}