/** * Classification of Cloudflare *platform* Durable Object failures. * * A Durable Object can be torn out from under its own code by the runtime, and * when that happens the only thing the caller receives is a plain `Error` whose * message is the entire signal. Those are not application defects: the object * was healthy, the request was valid, and the correct answer to the client is * "this id is dead, reconnect" or "come back in a moment" — never an unhandled * 500 and never an error report. * * The codebase already classifies transient-vs-definitive failures carefully * for the auth provider; this is the same discipline for the one other * dependency that fails without a typed error: the DO platform itself. * * Everything not listed here stays UNCLASSIFIED on purpose. An unrecognized * failure keeps its current behaviour — rethrow, report, page — because the * cost of silently swallowing a real defect is much higher than the cost of one * more retryable envelope. */import { Cause } from "effect"; import { jsonRpcErrorBody, UNAVAILABLE_RETRY_AFTER_SECONDS } from "@executor-js/host-mcp"; /** * The specific platform condition, kept granular so it can be recorded on a * span (`mcp.do.reset_kind`) and the aggregate bucket split by cause in * production instead of being one opaque pile. */export type DurableObjectFailureKind =  /** The object called `ctx.abort("destroyed")` on itself — session teardown. */  | "destroyed"  /** A deploy replaced the script and the runtime reset every live object. */  | "code_update"  /** A storage op ran past the platform's ceiling; the object was reset. */  | "storage_timeout"  /** The storage backend failed internally and reset the object. */  | "storage_internal"  /** The storage backend failed internally *while bringing the object up*. */  | "startup_internal_error"  /** `blockConcurrencyWhile()` ran past its cap and was cancelled. */  | "concurrency_reset"  /** An invocation ran past the per-invocation CPU ceiling; the object was reset. */  | "cpu_limit"  /** A generic platform blip: `internal error; reference = <id>`. */  | "internal_error"  /** The runtime itself flagged the error as retryable. */  | "retryable"; /** * What the caller should do about it. * * - `session_dead` — the object is gone for good; the id will never work again, *   so the client must mint a new session. * - `transient` — the object was reset but the id is still valid; the very next *   attempt is likely to succeed. */export type DurableObjectFailureDisposition = "session_dead" | "transient"; export type DurableObjectFailure = {  readonly kind: DurableObjectFailureKind;  readonly disposition: DurableObjectFailureDisposition;}; /** * Message fragments workerd puts on the plain `Error` it throws. Matched * case-insensitively on a substring because the runtime appends ids and * punctuation ("… reference = 0123abcd") and has reworded these before. */const MESSAGE_PATTERNS: ReadonlyArray<{  readonly fragment: string;  readonly failure: DurableObjectFailure;}> = [  {    fragment: "durable object reset because its code was updated",    failure: { kind: "code_update", disposition: "transient" },  },  {    fragment: "storage operation exceeded timeout",    failure: { kind: "storage_timeout", disposition: "transient" },  },  {    fragment: "internal error in durable object storage",    failure: { kind: "storage_internal", disposition: "transient" },  },  {    // The startup sibling of the entry above: the storage backend faults while    // the object is being brought up rather than while it is serving, and the    // runtime says so in a different clause ("… while starting up Durable    // Object storage caused object to be reset; reference = <id>").    //    // Deliberately stops before "storage": the two known members of this family    // agree on "Internal error … Durable Object" and disagree on everything    // that follows the verb, so the qualifier is the part most likely to move    // and is not what identifies the failure. Equally deliberately NOT    // shortened to the shared tail "caused object to be reset" — that tail is    // common to several unrelated storage faults and would stop this bucket    // from meaning anything on a span.    //    // Transient for the same reason as its sibling: nothing about the request    // caused it, the id still routes, and the object gets a fresh start on the    // next attempt.    fragment: "internal error while starting up durable object",    failure: { kind: "startup_internal_error", disposition: "transient" },  },  {    // Deliberately the whole phrase, not the bare method name: an application    // defect thrown from inside a `blockConcurrencyWhile` callback also resets    // the object, and a message that merely names the method must not be read    // as a platform reset and quietly turned into a retry.    fragment: "blockconcurrencywhile() in a durable object waited for too long",    failure: { kind: "concurrency_reset", disposition: "transient" },  },  {    // Deliberately starts at the verb, not at "Durable Object": the runtime's    // resource-limit messages disagree about the subject noun (the memory    // variant says "Durable Object's isolate exceeded its memory limit"), and    // pinning a subject here would let a rewording defeat the match. From    // "exceeded its CPU time limit" onward the phrase is the runtime's alone.    //    // Transient, not a defect: the invocation was cut off but the object's    // durable storage is untouched and the session id still routes, so the next    // attempt — a smaller unit of work, or the same one under a warm isolate —    // can succeed. Retrying the same id is strictly better than the unhandled    // 500 this produced before.    fragment: "exceeded its cpu time limit and was reset",    failure: { kind: "cpu_limit", disposition: "transient" },  },  {    // Only the bare blip. A reference id at the end of the message is NOT the    // marker: the runtime also appends one to described faults such as the    // startup failure above, and because this fragment includes the semicolon    // that immediately follows "internal error", any interposed description    // defeats it. Those variants each need their own entry rather than a    // loosened version of this one, which would turn every referenced error    // into an opaque "internal_error" bucket.    fragment: "internal error; reference =",    failure: { kind: "internal_error", disposition: "transient" },  },  // Not listed, on purpose: the sibling memory-limit reset ("Durable Object's  // isolate exceeded its memory limit due to overflowing the storage cache …  // All objects in the isolate were reset."). The runtime tags that one as a  // user error, and it names its own cause — too many un-awaited writes, or one  // oversized read. Retrying reproduces it, so calling it transient would bury  // an application defect behind a 503 instead of surfacing it.]; /** * `ctx.abort("destroyed")` surfaces as an `Error` whose message is exactly the * abort reason, so this one is matched whole rather than as a substring — a * message that merely mentions the word must not condemn a live session. */const DESTROYED_MESSAGE = "destroyed"; /** How deep to follow `error.cause` before giving up. */const MAX_UNWRAP_DEPTH = 5; const messageOf = (error: unknown): string | null => {  if (typeof error === "string") return error;  if (typeof error !== "object" || error === null) return null;  // oxlint-disable-next-line executor/no-unknown-error-message -- platform boundary: workerd rejects with an untyped Error whose message IS the only signal; reading it here is the entire purpose of this module, and it exists so no other file has to  const message = (error as { readonly message?: unknown }).message;  return typeof message === "string" ? message : null;}; const isRuntimeRetryable = (error: unknown): boolean =>  typeof error === "object" &&  error !== null &&  (error as { readonly retryable?: unknown }).retryable === true; const classifyOne = (error: unknown): DurableObjectFailure | null => {  const message = messageOf(error);  if (message !== null) {    const normalized = message.trim().toLowerCase();    if (normalized === DESTROYED_MESSAGE) {      return { kind: "destroyed", disposition: "session_dead" };    }    for (const pattern of MESSAGE_PATTERNS) {      if (normalized.includes(pattern.fragment)) return pattern.failure;    }  }  // Checked last: the message is the more specific signal, and the runtime sets  // `retryable` on some of the same errors.  if (isRuntimeRetryable(error)) return { kind: "retryable", disposition: "transient" };  return null;}; /** * Recognize a Cloudflare platform Durable Object failure. * * Accepts whatever the caller happens to be holding: the raw `Error` a stub RPC * rejected with, an `Error` that wrapped it as its `cause`, or an Effect * `Cause` — the DO seam only ever sees the last of those, and forcing every * call site to unwrap first is how a classifier ends up with three subtly * different copies. * * Returns `null` for anything unrecognized — the caller must then treat the * error exactly as it did before this module existed. */export const classifyDurableObjectError = (error: unknown): DurableObjectFailure | null => {  if (Cause.isCause(error)) {    for (const inner of Cause.prettyErrors(error)) {      const failure = classifyDurableObjectError(inner);      if (failure) return failure;    }    return null;  }  let current: unknown = error;  for (let depth = 0; depth < MAX_UNWRAP_DEPTH && current !== null && current !== undefined; ) {    const failure = classifyOne(current);    if (failure) return failure;    depth += 1;    if (typeof current !== "object") break;    current = (current as { readonly cause?: unknown }).cause;  }  return null;}; /** * Render a classified platform failure as the MCP protocol error the client * should act on. * * Both branches reuse envelopes the MCP host already speaks, because the client * side of this is not new: a dead session id has always been "reconnect", and a * transient dependency failure has always been a 503 carrying `Retry-After`. * The only thing that was missing is that a platform reset never reached * either, and fell out of the worker as an unhandled 500 instead. * * The JSON-RPC code is -32001 for both; the HTTP STATUS is the discriminator * clients act on — 404 = the id is dead, mint a new session; 503 = retry the * SAME id after the advertised delay. */export const durableObjectFailureResponse = (failure: DurableObjectFailure): Response =>  failure.disposition === "session_dead"    ? jsonRpcErrorBody(404, -32001, "Session timed out, please reconnect")    : jsonRpcErrorBody(503, -32001, "MCP session is restarting, please retry", {        retryAfterSeconds: UNAVAILABLE_RETRY_AFTER_SECONDS,      });