/** * vapor-chamber - the failure every part of the library raises. * * `BusError`, its code vocabulary (`owner:condition:subject`, docs/contract.md 2-3), * the owner-bound factory and the two readers. Its own module, free of the * bus, so a part that keeps the bus out of its graph on purpose (the router, * docs/contract.md 6) raises the same failure the core does: one shape for every failure * (docs/contract.md rule 2), one reader for all of them. */ import { DEV } from './dev'; import { ERRORS_PAGE } from './error-registry'; import { _report } from './report'; /** * What went wrong, from a closed vocabulary the library owns (docs/contract.md 3). The * retry policy and a logger read it; a receiver that has never seen a code * still knows its condition. `unauthenticated` and `conflict` are the two * distinctions gRPC's canonical codes draw that `refused` and `already` hid * (sign in, then retry; the state changed underneath); the 1:1 table against * gRPC is docs/contract.md 3. */ export type Condition = | 'missing' | 'already' | 'conflict' | 'invalid' | 'refused' | 'unauthenticated' | 'limited' | 'timeout' | 'lost' | 'aborted' | 'exceeded' | 'failed' | 'unexpected' | 'unknown'; /** What a site passes: `condition:subject`. The owner is the wiring's (docs/contract.md 5). */ export type FailCode = `${Condition}:${string}`; /** * A whole code, `owner:condition:subject`: who raised it (set by the wiring, * never by the site), what went wrong, and what it is about. * * @example * if (result.error instanceof BusError) { * switch (result.error.code) { * case 'core:missing:handler': // register a handler * case 'authGuard:unauthenticated:action': // a rule refused it * case 'circuitBreaker:limited:action': // the circuit is open * } * } */ export type BusErrorCode = `${string}:${Condition}:${string}`; export type FailOptions = { action?: string; context?: Record; cause?: unknown }; /** A failure factory bound to its owner. A party only ever holds its own. */ export type Fail = (code: FailCode, message: string, opts?: FailOptions) => BusError; // The owner the next BusError is minted for: a one-shot slot, the pattern of // `_nextOrigin`. Only `_failures` writes it, so a constructor call anywhere // else mints for 'app'. let mintOwner = 'app'; /** * BusError - a failure the library, a plugin or a transport raised. * * Extends native Error so it works everywhere errors work (catch, result.error). * `code` is `owner:condition:subject`; `ownerOf()` and `conditionOf()` read its * parts. Severity is not on it: whoever logs a failure decides how loud it is * (the catalogue's `severity` is the suggested level). * * @example * const result = bus.dispatch('missing', {}); * if (!result.ok && result.error instanceof BusError) { * console.log(result.error.code); // 'core:missing:handler' * console.log(conditionOf(result.error)); // 'missing' * console.log(result.error.action); // 'missing' * } */ export class BusError extends Error { // Private, so no holder can rewrite it: the owner is the wiring's, and the // condition (the retry verdict) is the raiser's. A private field is an // ordinary in-object slot to V8, so it costs what a plain field costs. #code: BusErrorCode; /** The action name involved (if applicable). */ declare readonly action?: string; /** Every value the message carries, and whatever else a reader inspects. */ declare readonly context?: Record; constructor(code: FailCode, message: string, opts: FailOptions = {}) { const owner = mintOwner; mintOwner = 'app'; // The type admits only `condition:subject`; plain JS can pass anything, and // a code outside the vocabulary gives `conditionOf` a condition that is not // one and the stack rule the wrong answer. DEV only, so the pattern folds // away with DEV in a production build. if (DEV && !/^(missing|already|conflict|invalid|refused|unauthenticated|limited|timeout|lost|aborted|exceeded|failed|unexpected|unknown):[^:]/.test(code)) { _report('warn', 'core:invalid:code', `BusError code "${code}" is not condition:subject from the condition vocabulary (missing, invalid, refused, limited, timeout, failed, ...); conditionOf() and the async bus's retry cannot read it.`); } // Only a bug (`failed`) keeps its stack. An expected refusal is control // flow, and V8's stack capture dominated its cost (docs/contract.md rule 4). const limit = (Error as any).stackTraceLimit; if (!code.startsWith('failed:')) (Error as any).stackTraceLimit = 0; // Restored right after, with no try/finally: Error's constructor cannot // throw here, and a `super()` inside `try` makes the compiler lower the // private field below into WeakMap helpers, even on an es2022 target. super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined); (Error as any).stackTraceLimit = limit; this.#code = `${owner}:${code}`; this.action = opts.action; this.context = opts.context; // An abort is named as the platform names one (DOM `throwIfAborted`, Fetch), // so `e.name === 'AbortError'` reads the platform's abort and every one the // library builds. A custom Error reason keeps its own name. 'b' at index 1 is // `aborted` alone in the vocabulary. Measured against `startsWith` // (+12.5 ns) and a subclass (+10 ns): +1.3 ns, an aborted BusError only. this.name = code.charCodeAt(1) === 98 ? 'AbortError' : 'BusError'; } /** `owner:condition:subject`, read-only. */ get code(): BusErrorCode { return this.#code; } /** * The failure as an RFC 9457 problem, with the members it needs * (docs/contract.md rule 3): `type`, `detail`, and `code`, `action` and the context as * extensions. `type` names the condition, a URI that resolves to its section * of docs/errors.md, because an RFC client identifies a problem by `type` * and ignores extensions it does not know (RFC 9457 3.1.1, 3.2); the exact * identity stays `code`. A backend's problem keeps the `type` it sent (its * own identity, read into `context` by the transports). No `title`: optional * in the RFC, and the summaries live in ERROR_CODE_REGISTRY, not in the * core. The transports' reader reads this shape back, so a failure crossing * a worker, a channel or storage has one shape both ways. * tests/problem-type.test.ts. */ toJSON(): Record { const own = this.code.startsWith('remote:') ? this.context?.type : undefined; return { ...this.context, type: own ?? ERRORS_PAGE + this.code.split(':')[1], detail: this.message, code: this.code, action: this.action }; } } /** @internal - a failure factory for `owner`. The bus hands each party its own. */ export const _failures = (owner: string): Fail => (code, message, opts) => { mintOwner = owner; return new BusError(code, message, opts); }; /** The party that raised `e`, or `undefined` when `e` is not a BusError. */ export const ownerOf = (e: unknown): string | undefined => e instanceof BusError ? e.code.slice(0, e.code.indexOf(':')) : undefined; /** A failure's condition, or `undefined` for anything the library did not raise. */ export const conditionOf = (e: unknown): Condition | undefined => e instanceof BusError ? (e.code.split(':')[1] as Condition) : undefined; /** * The condition a status declares (the status table, docs/contract.md 4), saying only * what RFC 9110 says of it, plus 419 (Laravel's expired CSRF token). Every * reader of a backend's answer maps a status through it, here beside the * failure so the http client reads it without the bus. * 401 and 419 are `unauthenticated` (a session or token to renew, then the * same request); 403 is `refused` (final). 409 Conflict and 412 Precondition * Failed are `conflict` (the target's state is not the one the request * assumed), not `already`. */ export function conditionOfStatus(status: number): Condition { if (status === 404 || status === 410) return 'missing'; if (status === 409 || status === 412) return 'conflict'; if (status === 401 || status === 419) return 'unauthenticated'; if (status === 403) return 'refused'; if (status === 429 || status === 503) return 'limited'; if (status === 408 || status === 504) return 'timeout'; if (status === 501 || status === 502 || status === 505) return 'unexpected'; return status >= 500 ? 'failed' : 'invalid'; } /** * @internal - a party's own `failed` (a plugin that threw): a bug, which a * re-send would repeat and which says nothing about the other side. A * backend's (`remote`) is not one; neither is a raw throw from a handler. */ export const _isBug = (e: unknown): boolean => conditionOf(e) === 'failed' && !(e as BusError).code.startsWith('remote:'); /** * @internal - the caller's cancel: a failure named `AbortError`, or the * command's own abort reason itself. The second is the platform's rule: * `throwIfAborted()` and Fetch reject with `signal.reason`, and the bus * returns an Error reason as itself. Identity, so a real failure that lands * after an abort still counts. tests/abort-custom-reason.test.ts. */ export const _isCancel = (e: unknown, signal?: AbortSignal): boolean => (e as Error | null)?.name === 'AbortError' || (signal?.aborted === true && e === signal.reason); /** * The one retry rule's reading of a failure (docs/contract.md 4), for the bus and the * http client alike: `transient` (held back, or a 408: the server never got * the whole request) may be sent again for any request; `uncertain` (the * first attempt may have landed: no reply, a gateway's 502 or 504, an * off-protocol answer, a backend's own failure) only for one that is * identified, safe to send twice; `final` (a verdict, an abort, a bound, a * party's bug) never. A declared wait is read by the caller: it sets when, * never whether (RFC 9110 10.2.3). Log s35.131, s35.162. */ export function retryClass(e: unknown, condition: Condition | undefined = conditionOf(e)): 'transient' | 'uncertain' | 'final' { if (condition === 'limited' || (condition === 'timeout' && !noReply(e))) return 'transient'; return condition === 'timeout' || condition === 'lost' || condition === 'unexpected' || condition === 'unknown' || (condition === 'failed' && !_isBug(e)) ? 'uncertain' : 'final'; } /** @internal - attempts in total, the first included: the async bus's default `maxAttempts`, the http client's own. */ export const _RETRY_ATTEMPTS = 3; /** @internal - the retry's base and cap in ms: the async bus's default `baseDelay` and `maxDelay`, the http client's own. */ export const _RETRY_BASE_MS = 200; export const _RETRY_MAX_MS = 20_000; /** * @internal - the one retry schedule's wait before re-send `n` (0 for the * first): full jitter, uniform under `base * 2^n`, capped at `max`, so * clients that failed together do not come back together (docs/retry.md). * The async bus's retry and the http client both wait it * (tests/http-retry-schedule.test.ts). */ export function _backoff(n: number, base = _RETRY_BASE_MS, max = _RETRY_MAX_MS): number { return Math.min(Math.random() * base * 2 ** n, max); } // Nothing that applies the request answered: our transport's timeout or lost // connection, or a gateway's 502 or 504 (RFC 9110 15.6.3, 15.6.5). The // request may have landed, and nothing says whether. function noReply(e: unknown): boolean { const status = (e as BusError | undefined)?.context?.status; return e instanceof BusError && (/^transport:(timeout|lost):/.test(e.code) || status === 502 || status === 504); } // The subjects already warned about, created on the first warning. let warnedUnidentified: Set | undefined; /** * @internal - a failure the retry rule did not re-send because nothing * identifies its request (no idempotency key, not declared idempotent, not * an idempotent method). Called only while retries were on and attempts * left. It acts when the failure got no reply or `declared` a wait, and * otherwise does nothing. No reply: marked `outcome: 'unknown'`, since it * may have landed. A declared wait on a verdict: not marked, the condition * already says not applied. DEV warns once per subject (`action`, or * `action` as a method with `url`) and cause. Log s35.162. */ export function _heldBack(e: unknown, declared: unknown, action: string, url?: string): void { const lost = noReply(e); if (!lost && typeof declared !== 'number') return; if (lost) (e as { context?: Record }).context = { ...(e as BusError).context, outcome: 'unknown' }; const subject = DEV ? (url === undefined ? `"${action}"` : `${action} "${url}"`) : ''; if (DEV && !(warnedUnidentified ??= new Set()).has(lost + subject)) { warnedUnidentified.add(lost + subject); _report('warn', 'core:missing:key', `${subject} is unidentified (${url === undefined ? 'no idempotency key, not declared idempotent' : 'no Idempotency-Key, not an idempotent method'}): the library cannot trace it to its effect. ${lost ? 'It got no reply and may have landed. It is not re-sent, and it cannot be confirmed or safely undone. Check its status on the server.' : `The server answered ${(e as BusError).code} with a wait, and it is not re-sent.`} ${url === undefined ? 'Key it (the idempotent plugin) or declare it idempotent (retry: { actionPolicies }).' : 'Send an Idempotency-Key header to let the client re-send it.'}`); } }