ravensight-playtest 0.1.0

package/src/api/client.js

@@ -0,0 +1,340 @@
+import { ApiError } from './errors.js';
+import { buildUrl, requestWithRetry, DEFAULT_RETRIES, DEFAULT_TIMEOUT_MS } from './http.js';
+import { resolveApiUrl } from '../paths.js';
+import { CLI_VERSION, CLIENT_NAME, userAgentFor } from '../version.js';
+
+const CLI_BASE = '/api/v1/playtest/cli';
+const PACKS_BASE = '/api/v1/playtest/packs';
+
+/** `/api/v1/games/:gameId/playtest` with the game id encoded. */
+function gameBase(gameId) {
+  if (typeof gameId !== 'string' || gameId.length === 0) {
+    throw new TypeError('gameId is required');
+  }
+  return `/api/v1/games/${encodeURIComponent(gameId)}/playtest`;
+}
+
+/**
+ * The Ravensight playtest API, as one object with one namespace per surface.
+ *
+ * Every method is a thin wrapper over `request`, and every wrapper keeps the
+ * server's own field spelling (`confirm_price_cents`, not `confirmPriceCents`)
+ * on anything that goes into or comes out of a body. Translating between two
+ * naming conventions in a client is a second place for a contract to drift,
+ * and the server's spelling is the one written down in the task reports.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.apiUrl]
+ * @param {string|null} [options.token] - a `gt_cli_...` token
+ * @param {string} [options.cliVersion]
+ * @param {typeof fetch} [options.fetch]
+ * @param {number} [options.retries]
+ * @param {number} [options.timeoutMs]
+ * @param {Function} [options.onRetry]
+ * @param {Function} [options.sleep]
+ */
+export function createClient(options = {}) {
+  const apiUrl = (options.apiUrl || resolveApiUrl()).replace(/\/+$/, '');
+  const token = options.token === undefined ? null : options.token;
+  const cliVersion = options.cliVersion || CLI_VERSION;
+  const userAgent = userAgentFor(cliVersion);
+  const transport = {
+    fetchImpl: options.fetch || globalThis.fetch,
+    retries: options.retries === undefined ? DEFAULT_RETRIES : options.retries,
+    timeoutMs: options.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : options.timeoutMs,
+    onRetry: options.onRetry,
+    sleep: options.sleep,
+    random: options.random
+  };
+
+  /**
+   * @param {string} method
+   * @param {string} path
+   * @param {{query?: Object, body?: unknown, headers?: Object, idempotent?: boolean,
+   *   raw?: boolean, anonymous?: boolean}} [opts]
+   * @returns {Promise<{status: number, headers: Headers, body: unknown}>}
+   */
+  async function request(method, path, opts = {}) {
+    const headers = {
+      accept: opts.raw ? '*/*' : 'application/json',
+      'user-agent': userAgent,
+      'x-ravensight-cli-version': cliVersion,
+      ...(opts.headers || {})
+    };
+    if (!opts.anonymous) {
+      if (!token) {
+        throw new ApiError({
+          status: 0,
+          code: 'not_authenticated',
+          message: 'No Ravensight credential. Run login, or set RAVENSIGHT_TOKEN.',
+          method,
+          path
+        });
+      }
+      headers.authorization = `Bearer ${token}`;
+    }
+    let bodyText;
+    if (opts.body !== undefined) {
+      bodyText = JSON.stringify(opts.body);
+      headers['content-type'] = 'application/json';
+    }
+    return requestWithRetry({
+      url: buildUrl(apiUrl, path, opts.query),
+      method,
+      path,
+      headers,
+      bodyText,
+      idempotent: Boolean(opts.idempotent),
+      raw: Boolean(opts.raw),
+      ...transport
+    });
+  }
+
+  /** A GET whose body we want and whose status we do not. */
+  const get = async (path, opts) => (await request('GET', path, { idempotent: true, ...opts })).body;
+
+  /**
+   * A cacheable GET: hand back the status, the ETag and the body, because a
+   * 304 is a successful answer with no body and the caller has to be able to
+   * tell it from a 200.
+   * @param {string} path
+   * @param {{query?: Object, etag?: string|null}} [opts]
+   */
+  async function cacheable(path, opts = {}) {
+    const headers = {};
+    if (opts.etag) headers['if-none-match'] = opts.etag;
+    const answer = await request('GET', path, { query: opts.query, headers, idempotent: true });
+    return {
+      status: answer.status,
+      etag: answer.headers.get('etag'),
+      body: answer.status === 304 ? null : answer.body
+    };
+  }
+
+  const packModules = modules => (Array.isArray(modules) && modules.length > 0 ? modules.join(',') : undefined);
+
+  const cli = {
+    /** Unauthenticated on purpose: a CLI asks this before it holds a credential. */
+    version: () => get(`${CLI_BASE}/version`, { anonymous: true }),
+
+    deviceCode: ({ client = CLIENT_NAME, clientVersion = cliVersion } = {}) =>
+      request('POST', `${CLI_BASE}/device-code`, {
+        body: { client, clientVersion },
+        anonymous: true
+      }).then(answer => answer.body),
+
+    /**
+     * One poll. Throws `ApiError` with code `authorization_pending` (428),
+     * `slow_down` (429), `expired_token` (400) or `access_denied` (403); the
+     * caller's loop decides which of those means keep waiting.
+     *
+     * Not retried, although 429 normally is: `slow_down` is the server telling
+     * this exact caller to poll less often, and an automatic retry inside the
+     * request would be the CLI arguing with it.
+     */
+    pollToken: deviceCode =>
+      request('POST', `${CLI_BASE}/token`, {
+        body: { device_code: deviceCode },
+        anonymous: true,
+        idempotent: false
+      }).then(answer => answer.body),
+
+    whoami: () => get(`${CLI_BASE}/whoami`),
+
+    revoke: () => request('DELETE', `${CLI_BASE}/token`).then(() => undefined)
+  };
+
+  const packs = {
+    manifest: (opts = {}) => cacheable(`${PACKS_BASE}/manifest`, opts),
+    personas: ({ gameId, etag } = {}) =>
+      cacheable(`${PACKS_BASE}/personas`, { query: { game_id: gameId }, etag }),
+    skills: ({ modules, etag } = {}) =>
+      cacheable(`${PACKS_BASE}/skills`, { query: { modules: packModules(modules) }, etag }),
+    schemas: ({ etag } = {}) => cacheable(`${PACKS_BASE}/schemas`, { etag }),
+    routing: ({ etag } = {}) => cacheable(`${PACKS_BASE}/routing`, { etag }),
+    bundle: ({ gameId, modules, etag } = {}) =>
+      cacheable(`${PACKS_BASE}/bundle`, {
+        query: { game_id: gameId, modules: packModules(modules) },
+        etag
+      })
+  };
+
+  const brief = {
+    get: gameId => get(`${gameBase(gameId)}/brief`),
+    versions: gameId => get(`${gameBase(gameId)}/brief/versions`),
+    version: (gameId, version) => get(`${gameBase(gameId)}/brief/versions/${encodeURIComponent(version)}`),
+
+    /**
+     * Save a new version. `parentVersion` is the version this edit was based
+     * on; a mismatch is 409 `stale_version` carrying `current_version`, which
+     * is the whole point of sending it.
+     */
+    put: (gameId, { fields, status = 'draft', parentVersion = null } = {}) =>
+      request('PUT', `${gameBase(gameId)}/brief`, {
+        body: { fields, status, parent_version: parentVersion }
+      }).then(answer => answer.body),
+
+    estimate: (gameId, { modules = [], personas = [] } = {}) =>
+      request('POST', `${gameBase(gameId)}/brief/estimate`, { body: { modules, personas } })
+        .then(answer => answer.body),
+
+    check: (gameId, completeness) =>
+      request('POST', `${gameBase(gameId)}/brief/check`, { body: { completeness } })
+        .then(answer => answer.body)
+  };
+
+  const jobs = {
+    estimate: (gameId, { modules = [], personas = [] } = {}) =>
+      request('POST', `${gameBase(gameId)}/estimate`, { body: { modules, personas } })
+        .then(answer => answer.body),
+
+    /**
+     * Register a job: this is the request that moves money.
+     *
+     * `Idempotency-Key` is required by the server and checked here, before the
+     * request leaves, so a caller that forgot one gets a TypeError with a
+     * stack pointing at its own bug instead of a 400 from a round trip. With
+     * the key present the call is marked idempotent, so a dropped response is
+     * retried and the server replays its stored job rather than charging
+     * twice.
+     */
+    register: (gameId, body, { idempotencyKey } = {}) => {
+      if (typeof idempotencyKey !== 'string' || idempotencyKey.length === 0) {
+        throw new TypeError('jobs.register needs an idempotencyKey: without one a retry charges twice');
+      }
+      return request('POST', `${gameBase(gameId)}/jobs`, {
+        body: { cli_version: cliVersion, ...body },
+        headers: { 'idempotency-key': idempotencyKey },
+        idempotent: true
+      }).then(answer => ({ ...answer.body, status: answer.status }));
+    },
+
+    list: (gameId, query = {}) => get(`${gameBase(gameId)}/jobs`, { query }),
+    get: (gameId, jobId) => get(`${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}`),
+
+    patch: (gameId, jobId, { state, reason = '' } = {}) =>
+      request('PATCH', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}`, {
+        body: { state, reason }
+      }).then(answer => answer.body),
+
+    cancel: (gameId, jobId) =>
+      request('POST', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/cancel`, { body: {} })
+        .then(answer => answer.body),
+
+    finish: (gameId, jobId, { state, reason = '' } = {}) =>
+      request('POST', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/finish`, {
+        body: { state, reason }
+      }).then(answer => answer.body),
+
+    remove: (gameId, jobId) =>
+      request('DELETE', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}`).then(() => undefined),
+
+    /** Job level presign: capability-report.json and aggregate-report.*. */
+    uploads: (gameId, jobId, { files } = {}) =>
+      request('POST', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/uploads`, {
+        body: { files }
+      }).then(answer => answer.body),
+
+    capabilityReport: (gameId, jobId, body) =>
+      request('POST', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/capability-report`, { body })
+        .then(answer => answer.body),
+
+    aggregateComplete: (gameId, jobId, body) =>
+      request('POST', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/aggregate/complete`, { body })
+        .then(answer => answer.body),
+
+    artifacts: (gameId, jobId) =>
+      get(`${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/artifacts`),
+
+    /** The aggregate report itself, as text. `format` is 'md' or 'json'. */
+    report: async (gameId, jobId, format = 'md') =>
+      (await request('GET', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/report`, {
+        query: { format },
+        raw: true,
+        idempotent: true
+      })).body,
+
+    summary: gameId => get(`${gameBase(gameId)}/summary`),
+    findings: (gameId, query = {}) => get(`${gameBase(gameId)}/findings`, { query })
+  };
+
+  function runPath(gameId, jobId, runId, suffix = '') {
+    return `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/runs/${encodeURIComponent(runId)}${suffix}`;
+  }
+
+  /** Both heartbeat and transition are the same PATCH; only `state` differs. */
+  function patchRun(gameId, jobId, runId, body, idempotent) {
+    return request('PATCH', runPath(gameId, jobId, runId), { body, idempotent })
+      .then(answer => answer.body);
+  }
+
+  const runs = {
+    list: (gameId, jobId) => get(`${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/runs`),
+
+    add: (gameId, jobId, personas) =>
+      request('POST', `${gameBase(gameId)}/jobs/${encodeURIComponent(jobId)}/runs`, {
+        body: { personas }
+      }).then(answer => answer.body),
+
+    /**
+     * Say the runner is alive, and optionally where it is. Idempotent, so a
+     * dropped beat is retried: losing beats is how a live run gets marked
+     * `interrupted` after 30 minutes.
+     *
+     * Answers `{ run, cancel_requested }`. `cancel_requested` is the only way
+     * a runner learns it should stop, so read it on every beat.
+     */
+    heartbeat: (gameId, jobId, runId, { checkpointStep, actionsTaken } = {}) =>
+      patchRun(gameId, jobId, runId, {
+        heartbeat: true,
+        ...(Number.isInteger(checkpointStep) ? { checkpoint_step: checkpointStep } : {}),
+        ...(Number.isInteger(actionsTaken) ? { actions_taken: actionsTaken } : {})
+      }, true),
+
+    /**
+     * Move a run to a new state, and beat at the same time (a runner reporting
+     * a state is by definition alive).
+     *
+     * `heartbeat: true` is sent explicitly, because the server only beats when
+     * the flag is set OR no state was given
+     * (`if (req.body.heartbeat || req.body.state === undefined)`). Without it a
+     * run that transitions regularly and beats rarely would look silent to the
+     * sweep and be marked `interrupted` mid flight.
+     *
+     * NOT idempotent: the server's transition is a conditional write filtered
+     * on the state the caller read, so a retry after a dropped response can
+     * lose the race and answer 409 `invalid_transition`. That answer has to
+     * reach the caller rather than be swallowed by a retry loop.
+     */
+    // Idempotent on purpose: a state transition names its target, so a
+    // retry after a timed-out request either lands the same state or is
+    // refused as already there. The first production run lost a run to a
+    // single timed-out PATCH that was never retried.
+    transition: (gameId, jobId, runId, state, { reason = '', checkpointStep, actionsTaken } = {}) =>
+      patchRun(gameId, jobId, runId, {
+        state,
+        reason,
+        heartbeat: true,
+        ...(Number.isInteger(checkpointStep) ? { checkpoint_step: checkpointStep } : {}),
+        ...(Number.isInteger(actionsTaken) ? { actions_taken: actionsTaken } : {})
+      }, true),
+
+    uploads: (gameId, jobId, runId, { files, includeVideo = false } = {}) =>
+      request('POST', runPath(gameId, jobId, runId, '/uploads'), {
+        body: { files, include_video: includeVideo }
+      }).then(answer => answer.body),
+
+    complete: (gameId, jobId, runId, body) =>
+      request('POST', runPath(gameId, jobId, runId, '/complete'), { body })
+        .then(answer => answer.body),
+
+    report: async (gameId, jobId, runId, format = 'md') =>
+      (await request('GET', runPath(gameId, jobId, runId, '/report'), {
+        query: { format },
+        raw: true,
+        idempotent: true
+      })).body
+  };
+
+  return { apiUrl, token, cliVersion, request, cli, packs, brief, jobs, runs };
+}

package/src/api/errors.js

@@ -0,0 +1,115 @@
+/**
+ * The Ravensight error envelope, as one class.
+ *
+ * Every playtest route answers a refusal as
+ * `{ error, message, details: [{ instancePath, message, code? }] }` plus
+ * whatever figures that particular refusal carries (`shortfall_cents`,
+ * `min_version`, `current_version`, and so on). `ApiError` keeps all three
+ * parts: the code to branch on, the message to print, and the whole body for
+ * the figures, so no caller has to reach past it to the raw response.
+ *
+ * A request that never got an answer is also an `ApiError`, with `status: 0`
+ * and `code: 'network_error'`. Callers branch on one type, not two.
+ */
+export class ApiError extends Error {
+  /**
+   * @param {{status: number, code: string, message: string, details?: Array,
+   *   body?: unknown, retryAfter?: number|null, method?: string, path?: string,
+   *   cause?: unknown}} fields
+   */
+  constructor(fields) {
+    super(fields.message || fields.code || 'request failed', { cause: fields.cause });
+    this.name = 'ApiError';
+    this.status = fields.status;
+    this.code = fields.code;
+    this.details = Array.isArray(fields.details) ? fields.details : [];
+    this.body = fields.body === undefined ? null : fields.body;
+    this.retryAfter = fields.retryAfter === undefined ? null : fields.retryAfter;
+    this.method = fields.method || null;
+    this.path = fields.path || null;
+  }
+
+  /** True when this is a local or transport failure rather than a server verdict. */
+  get isNetwork() {
+    return this.status === 0;
+  }
+
+  /**
+   * The validation pointers as one printable block, or an empty string when
+   * the refusal carried none.
+   * @returns {string}
+   */
+  formatDetails() {
+    return this.details
+      .map(detail => `  ${detail.instancePath || '/'}: ${detail.message}`)
+      .join('\n');
+  }
+}
+
+const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+/**
+ * Two playtest error codes where the status alone gives the wrong answer, so
+ * the code has to be consulted.
+ *
+ * `too_many_active_jobs` is a 429, and every other 429 is a retry. This one is
+ * not: it means this game already has three jobs running, which no amount of
+ * waiting inside one request will change. Retrying it would spend four
+ * backoffs to arrive at the same refusal, and the person needs to be told, not
+ * made to wait.
+ *
+ * `charge_in_progress` is a 409, and no other 409 is a retry. This one is,
+ * because it does not mean refused: it means another caller holds the charge
+ * claim and this one cannot tell whether money moved. The server sends
+ * `Retry-After: 2` precisely so the client asks again, and it becomes a real
+ * answer (a replay, or a charge) within a few seconds. Only retried when it
+ * actually carries a `Retry-After`: without one there is no interval the
+ * server has blessed, and guessing at a money path is not this layer's call.
+ */
+const NEVER_RETRY_CODES = new Set(['too_many_active_jobs']);
+const CODE_RETRY_LIMITS = new Map([['charge_in_progress', 5]]);
+
+/**
+ * How many retries this error's own code is allowed, independent of the
+ * client's general `retries` setting, or null when the code has no special
+ * allowance and the ordinary status rules apply.
+ * @param {unknown} error
+ * @returns {number|null}
+ */
+export function codeRetryLimit(error) {
+  if (!(error instanceof ApiError)) return null;
+  if (!CODE_RETRY_LIMITS.has(error.code)) return null;
+  if (error.retryAfter === null || error.retryAfter === undefined) return null;
+  return CODE_RETRY_LIMITS.get(error.code);
+}
+
+/**
+ * Whether a retry could plausibly succeed. This is about the failure, not
+ * about whether repeating the request is safe: that is the caller's
+ * `idempotent` flag, and a POST that moves money is never retried on this
+ * answer alone.
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isRetryable(error) {
+  if (!(error instanceof ApiError)) return false;
+  if (error.isNetwork) return true;
+  if (NEVER_RETRY_CODES.has(error.code)) return false;
+  if (codeRetryLimit(error) !== null) return true;
+  return RETRYABLE_STATUSES.has(error.status);
+}
+
+/**
+ * Parse a `Retry-After` header. Seconds or an HTTP date, per RFC 9110;
+ * anything else is null rather than a guess.
+ * @param {string|null|undefined} value
+ * @returns {number|null} seconds
+ */
+export function parseRetryAfter(value) {
+  if (!value) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds;
+  const when = Date.parse(value);
+  if (Number.isNaN(when)) return null;
+  return Math.max(0, Math.round((when - Date.now()) / 1000));
+}

package/src/api/http.js

@@ -0,0 +1,194 @@
+import { ApiError, codeRetryLimit, isRetryable, parseRetryAfter } from './errors.js';
+
+export const DEFAULT_RETRIES = 4;
+export const DEFAULT_TIMEOUT_MS = 30000;
+const BASE_DELAY_MS = 500;
+const MAX_DELAY_MS = 30000;
+
+/**
+ * Backoff for attempt `n` (1 based): exponential from 500 ms, capped at 30 s,
+ * with full jitter so a fleet of runners that all hit a 503 at once do not
+ * come back in lockstep. A `Retry-After` from the server wins over the
+ * computed delay, because the server knows something the client does not.
+ *
+ * @param {number} attempt
+ * @param {number|null} retryAfterSeconds
+ * @param {() => number} [random]
+ * @returns {number} milliseconds
+ */
+export function backoffDelay(attempt, retryAfterSeconds = null, random = Math.random) {
+  if (retryAfterSeconds !== null && retryAfterSeconds !== undefined) {
+    return Math.min(retryAfterSeconds * 1000, MAX_DELAY_MS);
+  }
+  const ceiling = Math.min(BASE_DELAY_MS * 2 ** (attempt - 1), MAX_DELAY_MS);
+  return Math.round(ceiling * (0.5 + random() * 0.5));
+}
+
+/**
+ * Build a URL from a base, a path and a query object. Undefined and null
+ * values are dropped rather than sent as the strings "undefined" and "null",
+ * which is what a template literal would do.
+ * @param {string} apiUrl
+ * @param {string} path
+ * @param {Object} [query]
+ * @returns {string}
+ */
+export function buildUrl(apiUrl, path, query) {
+  const url = new URL(path.replace(/^\/+/, ''), apiUrl.endsWith('/') ? apiUrl : `${apiUrl}/`);
+  for (const [key, value] of Object.entries(query || {})) {
+    if (value === undefined || value === null) continue;
+    url.searchParams.set(key, String(value));
+  }
+  return url.toString();
+}
+
+/**
+ * Read a response body without ever throwing. A 502 from a load balancer is
+ * HTML, a 204 is empty, and a JSON parse failure on the error path would
+ * replace a useful status code with a useless SyntaxError.
+ * @param {Response} response
+ * @returns {Promise<{json: unknown, text: string}>}
+ */
+async function readBody(response) {
+  let text = '';
+  try {
+    text = await response.text();
+  } catch {
+    return { json: null, text: '' };
+  }
+  if (!text) return { json: null, text: '' };
+  try {
+    return { json: JSON.parse(text), text };
+  } catch {
+    return { json: null, text };
+  }
+}
+
+function errorFrom(response, parsed, { method, path }) {
+  const body = parsed.json;
+  const envelope = body && typeof body === 'object' ? body : {};
+  return new ApiError({
+    status: response.status,
+    code: typeof envelope.error === 'string' ? envelope.error : `http_${response.status}`,
+    message: typeof envelope.message === 'string' && envelope.message
+      ? envelope.message
+      : `${method} ${path} failed with ${response.status}`,
+    details: envelope.details,
+    body: body === null ? parsed.text || null : body,
+    retryAfter: parseRetryAfter(response.headers.get('retry-after')),
+    method,
+    path
+  });
+}
+
+/**
+ * One HTTP request, with retries.
+ *
+ * Retries cover a network failure, a timeout, 408, 425, 429 and 5xx, plus the
+ * two error codes whose status alone gives the wrong answer (see
+ * `codeRetryLimit`): `charge_in_progress` is retried on its own `Retry-After`
+ * although it is a 409, and `too_many_active_jobs` is not retried although it
+ * is a 429. A mutation is only ever retried when the caller says
+ * `idempotent: true`, which in practice means a GET, a heartbeat, or a POST
+ * carrying an `Idempotency-Key` the server uses to replay rather than repeat.
+ * Everything else fails on the first answer, because a second charge is worse
+ * than an error message.
+ *
+ * @param {Object} options
+ * @param {string} options.url
+ * @param {string} options.method
+ * @param {string} options.path - for error messages only
+ * @param {Object} [options.headers]
+ * @param {string} [options.bodyText]
+ * @param {boolean} [options.idempotent]
+ * @param {boolean} [options.raw] - resolve the body as text, not JSON
+ * @param {number} [options.retries]
+ * @param {number} [options.timeoutMs]
+ * @param {typeof fetch} [options.fetchImpl]
+ * @param {(info: {attempt: number, delayMs: number, error: ApiError}) => void} [options.onRetry]
+ * @param {(ms: number) => Promise<void>} [options.sleep]
+ * @param {() => number} [options.random]
+ * @returns {Promise<{status: number, headers: Headers, body: unknown}>}
+ */
+export async function requestWithRetry(options) {
+  const {
+    url,
+    method,
+    path,
+    headers = {},
+    bodyText,
+    idempotent = false,
+    raw = false,
+    retries = DEFAULT_RETRIES,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    fetchImpl = globalThis.fetch,
+    onRetry,
+    sleep = ms => new Promise(resolve => setTimeout(resolve, ms)),
+    random = Math.random
+  } = options;
+
+  const retryable = idempotent || method === 'GET' || method === 'HEAD';
+  let lastError = null;
+  // Two budgets, not one. `generalRetries` is the client's `retries` setting,
+  // spent on network failures and 5xx. `codeRetries` is the separate allowance
+  // a specific error code carries (see codeRetryLimit), which must not be
+  // shortened by a caller that set `retries: 0` for its own reasons, nor
+  // lengthened by one that set it to 20.
+  let generalRetries = 0;
+  const codeRetries = new Map();
+
+  for (let attempt = 1; ; attempt += 1) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response = null;
+    try {
+      response = await fetchImpl(url, {
+        method,
+        headers,
+        body: bodyText === undefined ? undefined : bodyText,
+        signal: controller.signal
+      });
+    } catch (cause) {
+      lastError = new ApiError({
+        status: 0,
+        code: 'network_error',
+        message: `${method} ${path} could not reach ${new URL(url).host}: ${cause.message}`,
+        method,
+        path,
+        cause
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (response) {
+      const parsed = await readBody(response);
+      if (response.ok || response.status === 304) {
+        return {
+          status: response.status,
+          headers: response.headers,
+          body: raw ? parsed.text : parsed.json
+        };
+      }
+      lastError = errorFrom(response, parsed, { method, path });
+    }
+
+    if (!retryable) throw lastError;
+
+    const limit = codeRetryLimit(lastError);
+    let canRetry;
+    if (limit === null) {
+      canRetry = isRetryable(lastError) && generalRetries < retries;
+      if (canRetry) generalRetries += 1;
+    } else {
+      const used = codeRetries.get(lastError.code) || 0;
+      canRetry = used < limit;
+      if (canRetry) codeRetries.set(lastError.code, used + 1);
+    }
+    if (!canRetry) throw lastError;
+
+    const delayMs = backoffDelay(attempt, lastError.retryAfter, random);
+    if (onRetry) onRetry({ attempt, delayMs, error: lastError });
+    await sleep(delayMs);
+  }
+}