rivetkit 2.3.12-rc.1 → 2.3.12-rc.3

package/dist/browser/client.d.ts

@@ -286,6 +286,7 @@ interface DeconstructedError {
     code: string;
     message: string;
     metadata?: unknown;
+    rayId?: string;
     actor?: ActorSpecifier;
 }
 
@@ -294,6 +295,8 @@ interface RivetErrorOptions extends ErrorOptions {
     public?: boolean;
     /** Metadata associated with this error. */
     metadata?: unknown;
+    /** Request identifier used to correlate this error with engine logs. */
+    rayId?: string;
     /** Explicit HTTP status override for router responses. */
     statusCode?: number;
     /** Actor context associated with this error. */
@@ -321,6 +324,7 @@ declare class RivetError extends Error {
     __type: "RivetError";
     public: boolean;
     metadata?: unknown;
+    readonly rayId?: string;
     statusCode: number;
     actor?: ActorSpecifier;
     readonly group: string;

package/dist/browser/client.js

@@ -10,7 +10,7 @@ var INTERNAL_ERROR_CODE = "internal_error";
 var INTERNAL_ERROR_DESCRIPTION = "An internal error occurred";
 var USER_ERROR_CODE = "user_error";
 function looksLikeRivetErrorOptions(value) {
-  return typeof value === "object" && value !== null && ("public" in value || "metadata" in value || "statusCode" in value || "actor" in value || "cause" in value);
+  return typeof value === "object" && value !== null && ("public" in value || "metadata" in value || "rayId" in value || "statusCode" in value || "actor" in value || "cause" in value);
 }
 function isTypedErrorTag(value) {
   return value === "ActorError" || value === "RivetError";
@@ -22,12 +22,13 @@ function errorMessage(error, fallback = String(error)) {
   return fallback;
 }
 function isRivetErrorLike(error) {
-  return typeof error === "object" && error !== null && "group" in error && typeof error.group === "string" && "code" in error && typeof error.code === "string" && "message" in error && typeof error.message === "string" && (!("__type" in error) || isTypedErrorTag(error.__type));
+  return typeof error === "object" && error !== null && "group" in error && typeof error.group === "string" && "code" in error && typeof error.code === "string" && "message" in error && typeof error.message === "string" && (!("rayId" in error) || error.rayId === void 0 || typeof error.rayId === "string") && (!("__type" in error) || isTypedErrorTag(error.__type));
 }
 var RivetError = class extends Error {
   __type = "RivetError";
   public;
   metadata;
+  rayId;
   statusCode;
   actor;
   group;
@@ -46,6 +47,7 @@ var RivetError = class extends Error {
     this.code = code;
     this.public = normalized.public ?? false;
     this.metadata = normalized.metadata;
+    this.rayId = normalized.rayId ?? void 0;
     this.statusCode = normalized.statusCode ?? (this.public ? 400 : 500);
     this.actor = normalized.actor;
   }
@@ -96,6 +98,7 @@ function deconstructError(error, exposeInternalError = false) {
   let code;
   let message;
   let metadata;
+  let rayId;
   let actor;
   if (isCanonicalStructuredRivetError(error)) {
     statusCode = typeof error.statusCode === "number" ? error.statusCode : error.public ? 400 : 500;
@@ -104,6 +107,7 @@ function deconstructError(error, exposeInternalError = false) {
     code = error.code;
     message = error.message;
     metadata = error.metadata;
+    rayId = error.rayId;
     actor = error.actor;
   } else if (RivetError.isActorError(error) && error.public) {
     statusCode = "statusCode" in error && error.statusCode ? error.statusCode : 400;
@@ -112,6 +116,7 @@ function deconstructError(error, exposeInternalError = false) {
     code = error.code;
     message = getErrorMessage(error);
     metadata = error.metadata;
+    rayId = error.rayId;
     actor = error.actor;
   } else if (exposeInternalError) {
     if (RivetError.isActorError(error)) {
@@ -121,6 +126,7 @@ function deconstructError(error, exposeInternalError = false) {
       code = error.code;
       message = getErrorMessage(error);
       metadata = error.metadata;
+      rayId = error.rayId;
       actor = error.actor;
     } else {
       statusCode = 500;
@@ -150,6 +156,7 @@ function deconstructError(error, exposeInternalError = false) {
     code,
     message,
     metadata,
+    rayId,
     actor
   };
 }
@@ -194,7 +201,7 @@ function noopNext() {
 // package.json
 var package_default = {
   name: "rivetkit",
-  version: "2.3.12-rc.1",
+  version: "2.3.12-rc.3",
   description: "Lightweight libraries for building stateful actors on edge platforms",
   license: "Apache-2.0",
   keywords: [
@@ -3689,12 +3696,12 @@ var ActorConnDisposed = class extends ActorClientError {
 function isSchedulingError(group, code) {
   return group === "guard" && (code === "actor_ready_timeout" || code === "actor_runner_failed");
 }
-function actorSchedulingError(group, code, actorId, details) {
+function actorSchedulingError(group, code, actorId, details, rayId) {
   return new RivetError(
     group,
     code,
     `Actor failed to start (${actorId}): ${JSON.stringify(details)}`,
-    { metadata: { actorId, details } }
+    { metadata: { actorId, details }, rayId }
   );
 }
 function internalClientError(message, opts) {
@@ -3813,6 +3820,7 @@ async function sendHttpRequest(opts) {
         code: responseData.code,
         message: responseData.message,
         metadata: responseData.metadata,
+        rayId,
         actorId: responseData.actor?.actorId,
         generation: responseData.actor?.generation,
         actorKey: responseData.actor?.key
@@ -3823,6 +3831,7 @@ async function sendHttpRequest(opts) {
         responseData.message,
         {
           metadata: responseData.metadata,
+          rayId: rayId ?? void 0,
           actor: responseData.actor
         }
       );
@@ -4235,24 +4244,45 @@ var RemoteEngineControlClient = class {
       name,
       key
     });
-    const { actor, created } = await getOrCreateActor(this.#config, {
-      datacenter: region,
-      name,
-      key: serializeActorKey(key),
-      runner_name_selector: poolName ?? this.#config.poolName,
-      input: actorInput ? uint8ArrayToBase64(
-        encodeCborCompat(actorInput)
-      ) : void 0,
-      crash_policy: crashPolicy ?? "sleep"
-    });
-    logger3().info({
-      msg: "getOrCreateWithKey: actor ready",
-      actorId: actor.actor_id,
-      name,
-      key,
-      created
-    });
-    return apiActorToOutput(actor);
+    try {
+      const { actor, created } = await getOrCreateActor(this.#config, {
+        datacenter: region,
+        name,
+        key: serializeActorKey(key),
+        runner_name_selector: poolName ?? this.#config.poolName,
+        input: actorInput ? uint8ArrayToBase64(
+          encodeCborCompat(actorInput)
+        ) : void 0,
+        crash_policy: crashPolicy ?? "sleep"
+      });
+      logger3().info({
+        msg: "getOrCreateWithKey: actor ready",
+        actorId: actor.actor_id,
+        name,
+        key,
+        created
+      });
+      return apiActorToOutput(actor);
+    } catch (error) {
+      if (error instanceof RivetError && error.group === "actor" && error.code === "key_reserved_in_different_datacenter") {
+        logger3().warn({
+          msg: "getOrCreateWithKey: key reserved in different datacenter, retrying as get",
+          name,
+          key
+        });
+        const response = await getActorByKey(this.#config, name, key);
+        const existing = response.actors[0];
+        if (!existing) throw error;
+        logger3().info({
+          msg: "getOrCreateWithKey: resolved existing actor via get",
+          actorId: existing.actor_id,
+          name,
+          key
+        });
+        return apiActorToOutput(existing);
+      }
+      throw error;
+    }
   }
   async createActor({
     name,
@@ -4489,7 +4519,7 @@ function getGatewayTarget(state) {
 function isStaleResolvedActorError(group, code) {
   return group === "actor" && (code === "not_found" || code === "starting" || code === "stopping" || code === "not_configured" || code === "dropped_reply" || code.startsWith("destroyed_"));
 }
-async function checkForSchedulingError(group, code, actorId, query, driver) {
+async function checkForSchedulingError(group, code, actorId, query, driver, rayId) {
   const name = getActorNameFromQuery(query);
   try {
     const actor = await driver.getForId({ name, actorId });
@@ -4499,7 +4529,13 @@ async function checkForSchedulingError(group, code, actorId, query, driver) {
         actorId,
         error: actor.error
       });
-      return actorSchedulingError(group, code, actorId, actor.error);
+      return actorSchedulingError(
+        group,
+        code,
+        actorId,
+        actor.error,
+        rayId
+      );
     }
   } catch (err) {
     logger2().warn({
@@ -5328,7 +5364,7 @@ var ActorConnRaw = class {
       const reason = closeEvent.reason || "";
       const parsed = parseWebSocketCloseReason(reason);
       if (parsed) {
-        const { group, code } = parsed;
+        const { group, code, rayId } = parsed;
         if (this.#shouldReconnectForStaleActor(group, code)) {
           this.#clearResolvedActorIdentity();
           this.#onOpenPromise?.reject(
@@ -5336,7 +5372,7 @@ var ActorConnRaw = class {
               group,
               code,
               `Connection closed: ${reason}`,
-              void 0
+              { rayId }
             )
           );
           return;
@@ -5347,7 +5383,8 @@ var ActorConnRaw = class {
             code,
             this.#actorId,
             this.#actorResolutionState,
-            this.#driver
+            this.#driver,
+            rayId
           );
           if (schedulingError) {
             error = schedulingError;
@@ -5356,7 +5393,7 @@ var ActorConnRaw = class {
               group,
               code,
               `Connection closed: ${reason}`,
-              void 0
+              { rayId }
             );
           }
         } else {
@@ -5364,7 +5401,7 @@ var ActorConnRaw = class {
             group,
             code,
             `Connection closed: ${reason}`,
-            void 0
+            { rayId }
           );
         }
         this.#invalidateActorIfStale(group, code);
@@ -5946,11 +5983,8 @@ async function rawHttpFetch(driver, target, params, input, init, options = {}) {
     });
     return driver.sendRequest(target, proxyRequest, options);
   } catch (err) {
-    const { group, code, message, metadata, actor } = deconstructError(
-      err,
-      true
-    );
-    throw new RivetError(group, code, message, { metadata, actor });
+    const { group, code, message, metadata, rayId, actor } = deconstructError(err, true);
+    throw new RivetError(group, code, message, { metadata, rayId, actor });
   }
 }
 async function rawWebSocket(driver, target, params, path, _protocols, options = {}) {
@@ -6069,7 +6103,7 @@ var ActorHandleRaw = class {
   async #sendQueueMessage(name, body, options) {
     return await this.#queueSendMutex.run(async () => {
       const maxAttempts = this.#getDynamicQueryMaxAttempts();
-      let useQueryTarget = false;
+      let useQueryTarget = isDynamicActorQuery(this.#actorResolutionState);
       for (let attempt = 0; attempt < maxAttempts; attempt++) {
         let actorId;
         try {
@@ -6093,7 +6127,7 @@ var ActorHandleRaw = class {
             }
           }).send(name, body, options);
         } catch (err) {
-          const { group, code, message, metadata, actor } = deconstructError(err, true);
+          const { group, code, message, metadata, rayId, actor } = deconstructError(err, true);
           if (this.#shouldRetryQueueDispatchOverload(
             group,
             code,
@@ -6109,7 +6143,8 @@ var ActorHandleRaw = class {
             code,
             actorId,
             attempt,
-            maxAttempts
+            maxAttempts,
+            rayId
           )) {
             useQueryTarget = true;
             await this.#waitForRetryWindow();
@@ -6131,14 +6166,16 @@ var ActorHandleRaw = class {
             code
           );
           if (invalidated && attempt < maxAttempts - 1) {
-            useQueryTarget = code === "starting" || code === "stopping" || code.startsWith("destroyed_");
-            if (useQueryTarget) {
+            const waitForReady = code === "starting" || code === "stopping" || code.startsWith("destroyed_");
+            useQueryTarget = useQueryTarget || waitForReady;
+            if (waitForReady) {
               await this.#waitForRetryWindow();
             }
             continue;
           }
           throw new RivetError(group, code, message, {
             metadata,
+            rayId,
             actor
           });
         }
@@ -6167,7 +6204,7 @@ var ActorHandleRaw = class {
   }
   async #sendActionNow(opts) {
     const maxAttempts = this.#getDynamicQueryMaxAttempts();
-    let useQueryTarget = false;
+    let useQueryTarget = isDynamicActorQuery(this.#actorResolutionState);
     const gatewayOptions = resolveActorGatewayOptions(
       this.#gatewayOptions,
       opts
@@ -6232,13 +6269,14 @@ var ActorHandleRaw = class {
         }
         return output;
       } catch (err) {
-        const { group, code, message, metadata, actor } = deconstructError(err, true);
+        const { group, code, message, metadata, rayId, actor } = deconstructError(err, true);
         if (await this.#shouldRetrySchedulingError(
           group,
           code,
           actorId,
           attempt,
-          maxAttempts
+          maxAttempts,
+          rayId
         )) {
           useQueryTarget = true;
           await this.#waitForRetryWindow();
@@ -6260,7 +6298,7 @@ var ActorHandleRaw = class {
             "actor",
             "not_found",
             "The actor does not exist or was destroyed.",
-            { metadata, actor }
+            { metadata, rayId, actor }
           );
         }
         const invalidated = this.#invalidateResolvedActorId(
@@ -6276,7 +6314,11 @@ var ActorHandleRaw = class {
           }
           continue;
         }
-        throw new RivetError(group, code, message, { metadata, actor });
+        throw new RivetError(group, code, message, {
+          metadata,
+          rayId,
+          actor
+        });
       }
     }
     throw new Error("unreachable action retry state");
@@ -6318,7 +6360,7 @@ var ActorHandleRaw = class {
     this.#resolvedActorId = void 0;
     this.#resolvingActorId = void 0;
   }
-  async #shouldRetrySchedulingError(group, code, actorId, attempt, maxAttempts) {
+  async #shouldRetrySchedulingError(group, code, actorId, attempt, maxAttempts, rayId) {
     if (!isDynamicActorQuery(this.#actorResolutionState) || !isSchedulingError(group, code) || attempt >= maxAttempts - 1) {
       return false;
     }
@@ -6328,7 +6370,8 @@ var ActorHandleRaw = class {
         code,
         actorId,
         this.#actorResolutionState,
-        this.#driver
+        this.#driver,
+        rayId
       );
       if (schedulingError) {
         throw schedulingError;
@@ -6410,7 +6453,7 @@ var ActorHandleRaw = class {
   }
   async #fetchWithResolvedActor(input, init) {
     const maxAttempts = this.#getDynamicQueryMaxAttempts();
-    let useQueryTarget = false;
+    let useQueryTarget = isDynamicActorQuery(this.#actorResolutionState);
     const { skipReadyWait, ...requestInit } = init ?? {};
     const gatewayOptions = resolveActorGatewayOptions(
       this.#gatewayOptions,
@@ -6449,13 +6492,14 @@ var ActorHandleRaw = class {
         }
         return response;
       } catch (err) {
-        const { group, code, message, metadata, actor } = deconstructError(err, true);
+        const { group, code, message, metadata, rayId, actor } = deconstructError(err, true);
         if (await this.#shouldRetrySchedulingError(
           group,
           code,
           actorId,
           attempt,
-          maxAttempts
+          maxAttempts,
+          rayId
         )) {
           useQueryTarget = true;
           await this.#waitForRetryWindow();
@@ -6477,13 +6521,18 @@ var ActorHandleRaw = class {
           code
         );
         if (invalidated && attempt < maxAttempts - 1) {
-          useQueryTarget = code === "starting" || code === "stopping" || code.startsWith("destroyed_");
-          if (useQueryTarget) {
+          const waitForReady = code === "starting" || code === "stopping" || code.startsWith("destroyed_");
+          useQueryTarget = useQueryTarget || waitForReady;
+          if (waitForReady) {
             await this.#waitForRetryWindow();
           }
           continue;
         }
-        throw new RivetError(group, code, message, { metadata, actor });
+        throw new RivetError(group, code, message, {
+          metadata,
+          rayId,
+          actor
+        });
       }
     }
     throw new Error("unreachable fetch retry state");
@@ -6496,13 +6545,14 @@ var ActorHandleRaw = class {
     if (!error) {
       return null;
     }
-    const { group, code } = error;
+    const { group, code, rayId } = error;
     if (await this.#shouldRetrySchedulingError(
       group,
       code,
       actorId,
       attempt,
-      maxAttempts
+      maxAttempts,
+      rayId
     )) {
       return {
         useQueryTarget: true,
@@ -6523,10 +6573,10 @@ var ActorHandleRaw = class {
     }
     const invalidated = this.#invalidateResolvedActorId(group, code);
     if (invalidated && attempt < maxAttempts - 1) {
-      const useQueryTarget = code === "starting" || code === "stopping" || code.startsWith("destroyed_");
+      const waitForReady = code === "starting" || code === "stopping" || code.startsWith("destroyed_");
       return {
-        useQueryTarget,
-        waitForRetryWindow: useQueryTarget
+        useQueryTarget: true,
+        waitForRetryWindow: waitForReady
       };
     }
     return null;
@@ -6538,7 +6588,7 @@ var ActorHandleRaw = class {
     const contentType = response.headers.get("content-type");
     const encoding = contentType?.includes("application/json") ? "json" : this.#encoding;
     try {
-      return deserializeWithEncoding(
+      const error = deserializeWithEncoding(
         encoding,
         new Uint8Array(await response.clone().arrayBuffer()),
         HTTP_RESPONSE_ERROR_VERSIONED,
@@ -6562,6 +6612,10 @@ var ActorHandleRaw = class {
           } : void 0
         })
       );
+      return {
+        ...error,
+        rayId: response.headers.get("x-rivet-ray-id") ?? void 0
+      };
     } catch {
       return null;
     }
@@ -6625,7 +6679,9 @@ var ActorHandleRaw = class {
         "actor",
         "reload_failed",
         `reload failed with status ${response.status}: ${body}`,
-        {}
+        {
+          rayId: response.headers.get("x-rivet-ray-id") ?? void 0
+        }
       );
     }
   }