Retry transient Durable Object routing failures

PartyServer now retries transient Durable Object infrastructure errors at the routing boundary so callers do not need to wrap every routeAgentRequest or routePartykitRequest use site themselves. The retry path is scoped to retryable, non-overloaded runtime errors and recreates the DO stub/request per attempt while avoiding rerunning user routing hooks.

This also exposes routingRetry configuration, documents the option, and covers retry, opt-out, overload, non-retryable, exhausted, body replay, and onRetry observer edge cases.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: threepointone

.changeset/tall-lions-retry.md

@@ -0,0 +1,5 @@
+---
+"partyserver": patch
+---
+
+Retry transient Durable Object routing errors from `routePartykitRequest` and `getServerByName`, and expose route-level retry configuration.

packages/partyserver/README.md

@@ -169,9 +169,10 @@ export class MyServer extends Server {
 
 ### Utility Methods
 
-- `getServerByName(namespace, name, {locationHint, jurisdiction}): Promise<DurableObjectStub>` - Create a new Server with a specific name. Optionally pass a `locationHint` to specify the [location](https://developers.cloudflare.com/durable-objects/reference/data-location/#provide-a-location-hint) or `jurisdiction` to specify the [jurisdiction](https://developers.cloudflare.com/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) of the server.
+- `getServerByName(namespace, name, {locationHint, jurisdiction, routingRetry}): Promise<DurableObjectStub>` - Create a new Server with a specific name. Optionally pass a `locationHint` to specify the [location](https://developers.cloudflare.com/durable-objects/reference/data-location/#provide-a-location-hint), `jurisdiction` to specify the [jurisdiction](https://developers.cloudflare.com/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction), or `routingRetry: false` to disable retries for transient Durable Object infrastructure errors.
 
-- `routePartykitRequest(request, env, {locationHint, jurisdiction, prefix = 'parties', onBeforeConnect, onBeforeRequest}): Promise<Response | null>` - Match a request to a server. Takes a URL of the form `/${prefix}/:server/:name` and matches it with any namespace named `:server` (case insensitive) and a server named `:name`. Optionally pass a `locationHint` to specify the [location](https://developers.cloudflare.com/durable-objects/reference/data-location/#provide-a-location-hint) or `jurisdiction` to specify the [jurisdiction](https://developers.cloudflare.com/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) of the server.
+- `routePartykitRequest(request, env, {locationHint, jurisdiction, prefix = 'parties', routingRetry, onBeforeConnect, onBeforeRequest}): Promise<Response | null>` - Match a request to a server. Takes a URL of the form `/${prefix}/:server/:name` and matches it with any namespace named `:server` (case insensitive) and a server named `:name`. Optionally pass a `locationHint` to specify the [location](https://developers.cloudflare.com/durable-objects/reference/data-location/#provide-a-location-hint), `jurisdiction` to specify the [jurisdiction](https://developers.cloudflare.com/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction), or `routingRetry: false` to disable retries for transient Durable Object infrastructure errors.
+  - `routingRetry` - Retry options for transient Durable Object infrastructure errors thrown while routing to the target Durable Object. Enabled by default with 3 attempts and jittered exponential backoff. Only errors with `retryable === true` are retried, and errors with `overloaded === true` are never retried.
   - `onBeforeConnect(request, {party: string, name: string}): Request | Response | void` - A function that can modify the request for a websocket connection before it's passed to the server.
     - If it returns a `Request`, it will be used instead of the original request. Use this to modify headers or other request properties before passing it to the partyserver instance / durable object.
     - If it returns a `Response`, it will be returned instead of the original request. Use this to return a custom response, such as a 404 or 403.

packages/partyserver/src/index.ts

@@ -91,12 +91,156 @@ const serverMapCache = new WeakMap<
 // Maps kebab-case namespace -> original env binding name (e.g. "my-agent" -> "MyAgent")
 const bindingNameCache = new WeakMap<object, Record<string, string>>();
 
+const DEFAULT_ROUTING_RETRY_OPTIONS = {
+  maxAttempts: 3,
+  baseDelayMs: 100,
+  maxDelayMs: 800
+};
+
+export interface RoutingRetryEvent {
+  error: unknown;
+  attempt: number;
+  maxAttempts: number;
+  delayMs: number;
+  name: string;
+  className?: string;
+}
+
+export interface RoutingRetryOptions {
+  /** Max number of attempts, including the first. Default: 3 */
+  maxAttempts?: number;
+  /** Base delay in ms for exponential backoff. Default: 100 */
+  baseDelayMs?: number;
+  /** Max delay cap in ms. Default: 800 */
+  maxDelayMs?: number;
+  /** Optional callback invoked before each retry delay. */
+  onRetry?: (event: RoutingRetryEvent) => void | Promise<void>;
+}
+
+interface ResolvedRoutingRetryOptions extends Required<
+  Omit<RoutingRetryOptions, "onRetry">
+> {
+  onRetry?: RoutingRetryOptions["onRetry"];
+}
+
+interface RoutingRetryContext {
+  name: string;
+  className?: string;
+}
+
+function durableObjectGetOptions(
+  options: { locationHint?: DurableObjectLocationHint } | undefined
+) {
+  return options?.locationHint
+    ? { locationHint: options.locationHint }
+    : undefined;
+}
+
+function validatePositiveInteger(value: number, name: string): void {
+  if (!Number.isFinite(value) || value < 1) {
+    throw new Error(`${name} must be >= 1`);
+  }
+  if (!Number.isInteger(value)) {
+    throw new Error(`${name} must be an integer`);
+  }
+}
+
+function validatePositiveNumber(value: number, name: string): void {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${name} must be > 0`);
+  }
+}
+
+function resolveRoutingRetryOptions(
+  options: false | RoutingRetryOptions | undefined
+): ResolvedRoutingRetryOptions | null {
+  if (options === false) return null;
+
+  const resolved = {
+    maxAttempts:
+      options?.maxAttempts ?? DEFAULT_ROUTING_RETRY_OPTIONS.maxAttempts,
+    baseDelayMs:
+      options?.baseDelayMs ?? DEFAULT_ROUTING_RETRY_OPTIONS.baseDelayMs,
+    maxDelayMs: options?.maxDelayMs ?? DEFAULT_ROUTING_RETRY_OPTIONS.maxDelayMs,
+    onRetry: options?.onRetry
+  };
+
+  validatePositiveInteger(resolved.maxAttempts, "routingRetry.maxAttempts");
+  validatePositiveNumber(resolved.baseDelayMs, "routingRetry.baseDelayMs");
+  validatePositiveNumber(resolved.maxDelayMs, "routingRetry.maxDelayMs");
+  if (resolved.baseDelayMs > resolved.maxDelayMs) {
+    throw new Error("routingRetry.baseDelayMs must be <= maxDelayMs");
+  }
+
+  return resolved;
+}
+
+function isRetryableDurableObjectError(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) return false;
+  const typed = error as { retryable?: boolean; overloaded?: boolean };
+  return typed.retryable === true && typed.overloaded !== true;
+}
+
+function routingRetryDelayMs(
+  attempt: number,
+  options: ResolvedRoutingRetryOptions
+): number {
+  const upperBoundMs = Math.min(
+    options.maxDelayMs,
+    options.baseDelayMs * 2 ** (attempt - 1)
+  );
+  return Math.floor(Math.random() * upperBoundMs);
+}
+
+async function retryDurableObjectOperation<T>(
+  operation: () => Promise<T>,
+  context: RoutingRetryContext,
+  retryOptions: false | RoutingRetryOptions | undefined
+): Promise<T> {
+  const resolved = resolveRoutingRetryOptions(retryOptions);
+  if (!resolved) return await operation();
+
+  let attempt = 1;
+  while (true) {
+    try {
+      return await operation();
+    } catch (error) {
+      const nextAttempt = attempt + 1;
+      if (
+        nextAttempt > resolved.maxAttempts ||
+        !isRetryableDurableObjectError(error)
+      ) {
+        throw error;
+      }
+
+      const delayMs = routingRetryDelayMs(attempt, resolved);
+      try {
+        await resolved.onRetry?.({
+          error,
+          attempt,
+          maxAttempts: resolved.maxAttempts,
+          delayMs,
+          name: context.name,
+          className: context.className
+        });
+      } catch (callbackError) {
+        console.warn(
+          "PartyServer routingRetry onRetry callback failed:",
+          callbackError
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+      attempt = nextAttempt;
+    }
+  }
+}
+
 /**
  * For a given server namespace, create a server with a name.
  *
- * Makes a single RPC that awaits the DO's `onStart()` before returning,
- * so callers can invoke user-defined RPC methods on the returned stub and
- * trust that `onStart()` has completed. (User-defined RPC methods don't
+ * Makes an RPC that awaits the DO's `onStart()` before returning, so callers
+ * can invoke user-defined RPC methods on the returned stub and trust that
+ * `onStart()` has completed. (User-defined RPC methods don't
  * otherwise pass through `Server.fetch()`, which is where initialization
  * would normally be triggered.)
  *
@@ -115,18 +259,23 @@ export async function getServerByName<
     jurisdiction?: DurableObjectJurisdiction;
     locationHint?: DurableObjectLocationHint;
     props?: Props;
+    routingRetry?: false | RoutingRetryOptions;
   }
 ): Promise<DurableObjectStub<T>> {
   if (options?.jurisdiction) {
     serverNamespace = serverNamespace.jurisdiction(options.jurisdiction);
   }
 
   const id = serverNamespace.idFromName(name);
-  const stub = serverNamespace.get(id, options);
+  const getOptions = durableObjectGetOptions(options);
 
-  await stub.setName(name, options?.props);
+  await retryDurableObjectOperation(
+    () => serverNamespace.get(id, getOptions).setName(name, options?.props),
+    { name },
+    options?.routingRetry
+  );
 
-  return stub;
+  return serverNamespace.get(id, getOptions);
 }
 
 function camelCaseToKebabCase(str: string): string {
@@ -189,6 +338,14 @@ export interface PartyServerOptions<
    * Non-WebSocket responses on matched routes will also have the CORS headers appended.
    */
   cors?: boolean | HeadersInit;
+  /**
+   * Retry transient Durable Object infrastructure errors thrown while routing
+   * to the target DO. Enabled by default; pass `false` to disable.
+   *
+   * Only errors marked `retryable === true` are retried, and overloaded
+   * errors (`overloaded === true`) are never retried.
+   */
+  routingRetry?: false | RoutingRetryOptions;
   onBeforeConnect?: (
     req: Request,
     lobby: Lobby<Env>
@@ -320,7 +477,7 @@ Did you forget to add a durable object binding to the class ${namespace[0].toUpp
     }
 
     const id = doNamespace.idFromName(name);
-    const stub = doNamespace.get(id, options);
+    const getOptions = durableObjectGetOptions(options);
 
     req = new Request(req);
     req.headers.set("x-partykit-namespace", namespace);
@@ -377,7 +534,11 @@ Did you forget to add a durable object binding to the class ${namespace[0].toUpp
     // `ctx.id.name` inside the DO, so there's no need for a prior
     // `setName()` round-trip. Props (if any) travel in the request header
     // and are picked up in `Server.fetch()`.
-    const response = await stub.fetch(req);
+    const response = await retryDurableObjectOperation(
+      () => doNamespace.get(id, getOptions).fetch(req.clone()),
+      { name, className },
+      options?.routingRetry
+    );
     return isWebSocket ? response : withCorsHeaders(response);
   } else {
     return null;