@the-open-engine/zeroshot 6.28.0 → 6.29.1

package/src/hosted-session/coordinator.ts

@@ -1,26 +1,48 @@
-import { ClusterConfigError, connectInitialized } from '../cluster/index.js';
-import type { ServerCapabilities, GraphProfile } from '../cluster/index.js';
-import type { ConnectOptions } from '../cluster/index.js';
-import type { AccessResponse, HostedSessionInit, InitializedSession } from './types.js';
+import {
+  ClusterConfigError,
+  ClusterUpgradeError,
+  connectInitialized,
+  type ServerCapabilities,
+  type GraphProfile,
+} from '../cluster/index.js';
+import type {
+  HostedAccess,
+  HostedSessionInit,
+  HostedWatch,
+  HostedWatchOptions,
+  InitializedSession,
+} from './types.js';
+import { normalizedAuthority, validateHostedAccess } from './authority.js';
+import { HostedAuthenticationError } from './errors.js';
+import { ReconnectingHostedWatch } from './reconnecting-watch.js';
+export {
+  HostedAuthenticationError,
+  HostedAuthorizationError,
+  HostedTransportUncertainError,
+} from './errors.js';
+
 
 function combineSignals(signals: Array<AbortSignal | undefined>): AbortSignal | undefined {
-  const defined = signals.filter((s): s is AbortSignal => s !== undefined);
+  const defined = signals.filter((signal): signal is AbortSignal => signal !== undefined);
   if (defined.length === 0) return undefined;
   if (defined.length === 1) return defined[0];
   return AbortSignal.any(defined);
 }
 
 export class HostedSessionCoordinator {
-  readonly #getAccess: (signal?: AbortSignal) => Promise<AccessResponse>;
-  readonly #connectOptions: Omit<ConnectOptions, 'headers' | 'signal'> | undefined;
+  readonly #init: HostedSessionInit;
+  readonly #targetAuthority: string;
   readonly #clock: { now(): number };
   readonly #closeController = new AbortController();
+  readonly #sessions = new Set<InitializedSession>();
   #referenceCapabilities: ServerCapabilities | undefined;
   #closed = false;
 
   constructor(init: HostedSessionInit) {
-    this.#getAccess = init.getAccess;
-    this.#connectOptions = init.connectOptions;
+    if (init.capsuleId.length === 0)
+      throw new ClusterConfigError('capsuleId must not be empty', 'INVALID_CAPSULE_ID');
+    this.#init = init;
+    this.#targetAuthority = normalizedAuthority(init.targetAuthority);
     this.#clock = init.clock ?? Date;
   }
 
@@ -34,72 +56,107 @@ export class HostedSessionCoordinator {
   async replace(signal?: AbortSignal): Promise<InitializedSession> {
     this.#requireNotClosed();
     const session = await this.#createSession(signal);
-    this.#verifyCapabilities(session.initializeResult.capabilities, session);
-    return session;
+    try {
+      if (this.#referenceCapabilities !== undefined) {
+        this.#verifyCapabilities(
+          this.#referenceCapabilities,
+          session.initializeResult.capabilities
+        );
+      }
+      return session;
+    } catch (error) {
+      await session.connection.close();
+      throw error;
+    }
+  }
+
+  async watch(options: HostedWatchOptions): Promise<HostedWatch> {
+    const session = await this.open(options.signal);
+    try {
+      const subscription = await session.client.watch(
+        options.params,
+        options.signal === undefined ? {} : { signal: options.signal }
+      );
+      const hosted = new ReconnectingHostedWatch(
+        (replacementSignal) => this.replace(replacementSignal),
+        session,
+        subscription,
+        options.signal,
+      );
+      options.signal?.addEventListener(
+        'abort',
+        () => {
+          void hosted.cancel().catch(() => undefined);
+        },
+        { once: true }
+      );
+      if (options.signal?.aborted) {
+        await hosted.cancel();
+        throw options.signal.reason ?? new DOMException('hosted watch aborted', 'AbortError');
+      }
+      return hosted;
+    } catch (error) {
+      await session.connection.close();
+      throw error;
+    }
   }
 
-  renewalDeadline(access: AccessResponse, receivedAt: number): number {
+  renewalDeadline(access: HostedAccess, receivedAt: number): number {
     const expiresAt = Date.parse(access.expiresAt);
-    if (Number.isNaN(expiresAt)) {
-      throw new ClusterConfigError(`invalid expiresAt: ${access.expiresAt}`, 'INVALID_EXPIRY');
+    if (!Number.isFinite(expiresAt) || expiresAt <= receivedAt) {
+      throw new ClusterConfigError(
+        'access expiry must be a future RFC 3339 timestamp',
+        'INVALID_ACCESS_EXPIRY'
+      );
     }
     const lifetime = expiresAt - receivedAt;
-    return Math.min(expiresAt - 30_000, receivedAt + 0.8 * lifetime);
+    const lead = Math.max(5_000, Math.min(60_000, Math.floor(lifetime * 0.1)));
+    return Math.max(receivedAt, expiresAt - lead);
   }
 
   async close(): Promise<void> {
+    if (this.#closed) return;
     this.#closed = true;
-    this.#closeController.abort();
+    this.#closeController.abort(new DOMException('coordinator closed', 'AbortError'));
+    const sessions = [...this.#sessions];
+    await Promise.all(sessions.map((session) => session.connection.close()));
+    this.#sessions.clear();
   }
 
   async #createSession(signal?: AbortSignal): Promise<InitializedSession> {
     const combined = combineSignals([signal, this.#closeController.signal]);
-    const access = await this.#getAccess(combined);
-    const expiresAt = Date.parse(access.expiresAt);
-    if (Number.isNaN(expiresAt)) {
-      throw new ClusterConfigError(`invalid expiresAt: ${access.expiresAt}`, 'INVALID_EXPIRY');
-    }
-    if (expiresAt <= this.#clock.now()) {
-      throw new ClusterConfigError('access token is already expired', 'ACCESS_EXPIRED');
-    }
-
-    let endpoint: URL;
+    const access = await this.#init.adapter.access(this.#init.capsuleId, combined);
+    validateHostedAccess(access, this.#targetAuthority);
+    const receivedAt = this.#clock.now();
+    this.renewalDeadline(access, receivedAt);
     try {
-      endpoint = new URL(access.endpoint);
-    } catch {
-      throw new ClusterConfigError('hosted access endpoint is invalid', 'INVALID_ENDPOINT');
-    }
-    if (endpoint.protocol !== 'wss:') {
-      throw new ClusterConfigError('hosted access endpoint must use wss', 'INSECURE_ENDPOINT');
+      const session = await connectInitialized(access.websocketUrl, {
+        ...this.#init.connectOptions,
+        headers: { Authorization: `Bearer ${access.accessToken}` },
+        ...(combined === undefined ? {} : { signal: combined }),
+      });
+      this.#sessions.add(session);
+      void session.connection.closed.then(() => this.#sessions.delete(session));
+      return session;
+    } catch (error) {
+      if (error instanceof ClusterUpgradeError && error.status === 401)
+        throw new HostedAuthenticationError();
+      throw error;
     }
-
-    return connectInitialized(endpoint.href, {
-      ...this.#connectOptions,
-      headers: { Authorization: `Bearer ${access.token}` },
-      ...(combined !== undefined ? { signal: combined } : {}),
-    });
   }
 
-  #verifyCapabilities(incoming: ServerCapabilities, session: InitializedSession): void {
-    if (!this.#referenceCapabilities) return;
-    const ref = this.#referenceCapabilities;
-    const mismatches: string[] = [];
-
-    if (ref.graphProfiles) {
-      const incomingProfiles = new Set<GraphProfile>(incoming.graphProfiles ?? []);
-      for (const profile of ref.graphProfiles) {
-        if (!incomingProfiles.has(profile)) mismatches.push(`missing graphProfile: ${profile}`);
-      }
-    }
-    if (ref.logs && !incoming.logs) mismatches.push('missing capability: logs');
-    if (ref.agentAttach && !incoming.agentAttach)
-      mismatches.push('missing capability: agentAttach');
 
-    if (mismatches.length > 0) {
-      void session.connection.close();
+  #verifyCapabilities(reference: ServerCapabilities, incoming: ServerCapabilities): void {
+    const referenceProfiles = new Set<GraphProfile>(reference.graphProfiles ?? []);
+    const incomingProfiles = new Set<GraphProfile>(incoming.graphProfiles ?? []);
+    if (
+      (reference.logs && !incoming.logs) ||
+      (reference.agentAttach && !incoming.agentAttach) ||
+      [...referenceProfiles].some((profile) => !incomingProfiles.has(profile))
+    ) {
       throw new ClusterConfigError(
-        `replacement capabilities incompatible: ${mismatches.join(', ')}`,
-        'INCOMPATIBLE_CAPABILITIES'
+        'replacement connection removed required server capabilities',
+        'CAPABILITY_REGRESSION'
       );
     }
   }

package/src/hosted-session/errors.ts

@@ -0,0 +1,21 @@
+export class HostedAuthenticationError extends Error {
+  constructor() {
+    super('Hosted target authentication failed');
+    this.name = 'HostedAuthenticationError';
+  }
+}
+
+export class HostedAuthorizationError extends Error {
+  constructor() {
+    super('Hosted target authorization was revoked');
+    this.name = 'HostedAuthorizationError';
+  }
+}
+
+export class HostedTransportUncertainError extends Error {
+  readonly executionRetryAuthorized = false;
+  constructor() {
+    super('Hosted session transport closed with uncertain execution state');
+    this.name = 'HostedTransportUncertainError';
+  }
+}

package/src/hosted-session/index.ts

@@ -1,2 +1,14 @@
-export { HostedSessionCoordinator } from './coordinator.js';
-export type { AccessResponse, HostedSessionInit, InitializedSession } from './types.js';
+export {
+  HostedSessionCoordinator,
+  HostedAuthenticationError,
+  HostedAuthorizationError,
+  HostedTransportUncertainError,
+} from './coordinator.js';
+export type {
+  HostedAccess,
+  HostedAccessAdapter,
+  HostedSessionInit,
+  HostedWatch,
+  HostedWatchOptions,
+  InitializedSession,
+} from './types.js';

package/src/hosted-session/reconnecting-watch.ts

@@ -0,0 +1,148 @@
+import type {
+  WatchSubscription,
+  WatchSubscriptionItem,
+} from '../cluster/index.js';
+import {
+  HostedAuthorizationError,
+  HostedTransportUncertainError,
+} from './errors.js';
+import type { HostedWatch, InitializedSession } from './types.js';
+
+type ReplaceSession = (signal: AbortSignal) => Promise<InitializedSession>;
+
+export class ReconnectingHostedWatch implements HostedWatch {
+  readonly #replace: ReplaceSession;
+  readonly #ownedController = new AbortController();
+  readonly #signal: AbortSignal;
+  #session: InitializedSession;
+  #subscription: WatchSubscription;
+  #tail: Promise<void> = Promise.resolve();
+  #replacementPromise: Promise<InitializedSession> | undefined;
+  #cancelPromise: Promise<void> | undefined;
+  #reconnected = false;
+  #cancelled = false;
+
+  constructor(
+    replace: ReplaceSession,
+    session: InitializedSession,
+    subscription: WatchSubscription,
+    signal?: AbortSignal,
+  ) {
+    this.#replace = replace;
+    this.#session = session;
+    this.#subscription = subscription;
+    this.#signal = signal === undefined
+      ? this.#ownedController.signal
+      : AbortSignal.any([signal, this.#ownedController.signal]);
+  }
+
+  [Symbol.asyncIterator](): this {
+    return this;
+  }
+
+  next(): Promise<IteratorResult<WatchSubscriptionItem>> {
+    const result = this.#tail.then(() => this.#readNext());
+    this.#tail = result.then(() => undefined, () => undefined);
+    return result;
+  }
+
+  async #readNext(): Promise<IteratorResult<WatchSubscriptionItem>> {
+    while (!this.#cancelled) {
+      const item = await this.#subscription.stream.next();
+      if (this.#cancelled) return { done: true, value: undefined };
+      if (!item.done) return item;
+      return this.#handleClosed(item);
+    }
+    return { done: true, value: undefined };
+  }
+
+  async #handleClosed(
+    item: IteratorResult<WatchSubscriptionItem>,
+  ): Promise<IteratorResult<WatchSubscriptionItem>> {
+    if (this.#session.connection.state === 'OPEN') {
+      await this.#session.connection.close();
+      return item;
+    }
+    const { code } = await this.#session.connection.closed;
+    if (code === 4401) return this.#reconnect();
+    if (code === 4403) throw new HostedAuthorizationError();
+    if (code === 1000) return item;
+    throw new HostedTransportUncertainError();
+  }
+
+  async #reconnect(): Promise<IteratorResult<WatchSubscriptionItem>> {
+    if (this.#reconnected) throw new HostedTransportUncertainError();
+    this.#reconnected = true;
+    const replacementPromise = this.#replace(this.#signal);
+    this.#replacementPromise = replacementPromise;
+    let replacement: InitializedSession;
+    try {
+      replacement = await replacementPromise;
+    } catch (error) {
+      if (this.#cancelled) return { done: true, value: undefined };
+      throw error;
+    } finally {
+      if (this.#replacementPromise === replacementPromise) {
+        this.#replacementPromise = undefined;
+      }
+    }
+    return this.#installReplacement(replacement);
+  }
+
+  async #installReplacement(
+    replacement: InitializedSession,
+  ): Promise<IteratorResult<WatchSubscriptionItem>> {
+    if (this.#cancelled) {
+      await replacement.connection.close();
+      return { done: true, value: undefined };
+    }
+    try {
+      const subscription = await this.#subscription.stream.reconnect(replacement.connection);
+      if (this.#cancelled) {
+        await subscription.stream.cancel();
+        await replacement.connection.close();
+        return { done: true, value: undefined };
+      }
+      this.#subscription = subscription;
+      this.#session = replacement;
+      return this.#readNext();
+    } catch (error) {
+      await replacement.connection.close();
+      if (this.#cancelled) return { done: true, value: undefined };
+      throw error;
+    }
+  }
+
+  async return(): Promise<IteratorResult<WatchSubscriptionItem>> {
+    await this.cancel();
+    return { done: true, value: undefined };
+  }
+
+  async throw(error?: unknown): Promise<IteratorResult<WatchSubscriptionItem>> {
+    await this.cancel();
+    throw error;
+  }
+
+  cancel(): Promise<void> {
+    this.#cancelPromise ??= this.#cancelOwned();
+    return this.#cancelPromise;
+  }
+
+  async #cancelOwned(): Promise<void> {
+    this.#cancelled = true;
+    this.#ownedController.abort(new DOMException('hosted watch cancelled', 'AbortError'));
+    const replacement = this.#replacementPromise;
+    const outcomes = await Promise.allSettled([
+      this.#subscription.stream.cancel(),
+      this.#session.connection.close(),
+      ...(replacement === undefined
+        ? []
+        : [replacement.then(() => undefined, () => undefined)]),
+    ]);
+    await this.#tail;
+    const failure = outcomes.find(
+      (outcome): outcome is PromiseRejectedResult => outcome.status === 'rejected',
+    );
+    if (failure !== undefined) throw failure.reason;
+  }
+}

package/src/hosted-session/types.ts

@@ -1,15 +1,20 @@
-import type { Connection } from '../cluster/index.js';
-import type { ClusterClient, ConnectOptions } from '../cluster/index.js';
-import type { InitializeResult } from '../cluster/index.js';
-
-export interface AccessResponse {
-  readonly endpoint: string;
-  readonly token: string;
+import type { Connection, ClusterClient, ConnectOptions, InitializeResult, WatchParams, WatchSubscriptionItem } from '../cluster/index.js';
+export interface HostedAccess {
+  readonly protocol: 'openengine.cluster/v1';
+  readonly websocketUrl: string;
+  readonly accessToken: string;
+  readonly tokenType: 'Bearer';
   readonly expiresAt: string;
 }
 
+export interface HostedAccessAdapter {
+  access(capsuleId: string, signal?: AbortSignal): Promise<HostedAccess>;
+}
+
 export interface HostedSessionInit {
-  readonly getAccess: (signal?: AbortSignal) => Promise<AccessResponse>;
+  readonly adapter: HostedAccessAdapter;
+  readonly capsuleId: string;
+  readonly targetAuthority: string;
   readonly connectOptions?: Omit<ConnectOptions, 'headers' | 'signal'>;
   readonly clock?: { now(): number };
 }
@@ -19,3 +24,12 @@ export interface InitializedSession {
   readonly client: ClusterClient;
   readonly initializeResult: InitializeResult;
 }
+
+export interface HostedWatch extends AsyncIterator<WatchSubscriptionItem>, AsyncIterable<WatchSubscriptionItem> {
+  cancel(): Promise<void>;
+}
+
+export interface HostedWatchOptions {
+  readonly params: WatchParams;
+  readonly signal?: AbortSignal;
+}

package/src/hosted-target/access-url.ts

@@ -0,0 +1,46 @@
+import type { TargetDiscoveryDescriptor } from '../target/discovery.js';
+import { TargetProtocolError } from './errors.js';
+
+function hasForbiddenCodePoint(value: string): boolean {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0)!;
+    if (codePoint <= 0x20 || codePoint === 0x7f) return true;
+  }
+  return false;
+}
+
+function parseAccessUrl(value: string): URL {
+  try {
+    if (hasForbiddenCodePoint(value)) throw new TypeError('unsafe URL code point');
+    const url = new globalThis.URL(value);
+    if (url.href !== value) throw new TypeError('non-canonical URL');
+    return url;
+  } catch {
+    throw new TargetProtocolError('Capsule access WebSocket URL is invalid');
+  }
+}
+
+function matchesAccessRoute(url: URL, target: URL, expectedPath: string): boolean {
+  const expectedProtocol = target.protocol === 'http:' ? 'ws:' : 'wss:';
+  return url.protocol === expectedProtocol &&
+    url.host === target.host &&
+    !url.username &&
+    !url.password &&
+    !url.search &&
+    !url.hash &&
+    url.pathname === expectedPath;
+}
+
+export function validateAccessUrl(
+  value: string,
+  capsuleId: string,
+  descriptor: TargetDiscoveryDescriptor,
+): void {
+  const url = parseAccessUrl(value);
+  const expectedPath = descriptor.transport.websocketRouteTemplate.expand({
+    capsule_id: capsuleId,
+  });
+  if (!matchesAccessRoute(url, new globalThis.URL(descriptor.origin), expectedPath)) {
+    throw new TargetProtocolError('Capsule access WebSocket URL does not match discovery');
+  }
+}

package/src/hosted-target/adapter-request.ts

@@ -0,0 +1,28 @@
+import type { RouteTemplate, TargetDiscoveryDescriptor } from '../target/discovery.js';
+import { TargetProtocolError } from './errors.js';
+import type { TargetOperation } from './retry-executor.js';
+
+export type AdapterRequest = {
+  readonly body?: string;
+  readonly headers?: Readonly<Record<string, string>>;
+};
+
+export type ExecuteArguments<T> = [
+  operation: TargetOperation,
+  method: string,
+  template: RouteTemplate,
+  values: Readonly<Record<string, string | number | undefined>>,
+  expectedStatus: number,
+  validate: (body: unknown) => T,
+  signal?: AbortSignal,
+  request?: AdapterRequest,
+];
+
+export function requestUrl(path: string, descriptor: TargetDiscoveryDescriptor): URL {
+  const url = new globalThis.URL(path, descriptor.capsule.baseUrl);
+  if (url.origin !== descriptor.origin || url.hash ||
+      `${url.pathname}${url.search}` !== path) {
+    throw new TargetProtocolError('Capsule route changed during URL canonicalization');
+  }
+  return url;
+}

package/src/hosted-target/adapter-types.ts

@@ -0,0 +1,39 @@
+import type { TargetDiscoveryDescriptor } from '../target/discovery.js';
+import type {
+  AllocateRequest,
+  Capsule,
+  CapsuleAccess,
+  CapsuleLimits,
+  CapsuleListPage,
+  Clock,
+  HttpTransport,
+  ListRequest,
+  RetryPolicy,
+  TargetAccessTokenProvider,
+} from './types.js';
+
+export type CredentialInstallCapability =
+  | { readonly supported: false }
+  | {
+      readonly supported: true;
+      readonly descriptor: NonNullable<TargetDiscoveryDescriptor['credentialInstall']>;
+    };
+
+export interface TargetAdapter {
+  allocate(req: AllocateRequest, signal?: AbortSignal): Promise<Capsule>;
+  list(req?: ListRequest, signal?: AbortSignal): Promise<CapsuleListPage>;
+  inspect(capsuleId: string, signal?: AbortSignal): Promise<Capsule>;
+  terminate(capsuleId: string, signal?: AbortSignal): Promise<Capsule>;
+  limits(signal?: AbortSignal): Promise<CapsuleLimits>;
+  access(capsuleId: string, signal?: AbortSignal): Promise<CapsuleAccess>;
+  readonly credentialInstall: CredentialInstallCapability;
+}
+
+export interface CreateTargetAdapterOptions {
+  readonly descriptor: TargetDiscoveryDescriptor;
+  readonly organization: { readonly id: string };
+  readonly tokenProvider: TargetAccessTokenProvider;
+  readonly transport?: HttpTransport;
+  readonly clock?: Clock;
+  readonly retryPolicy?: RetryPolicy;
+}

package/src/hosted-target/bounds.ts

@@ -1,3 +1,4 @@
+/** Shared wire limits for every hosted-target response and retry path. */
 export const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
 export const MAX_PAGINATION_PAGES = 100;
 export const MAX_RETRY_ATTEMPTS = 3;

package/src/hosted-target/capsule-error-response.ts

@@ -0,0 +1,107 @@
+import { TargetProtocolError, TargetServerError } from './errors.js';
+import { parseRetryAfter } from './retry.js';
+import type { Clock } from './types.js';
+
+const ERROR_CODES = Object.freeze({
+  unauthorized: { statuses: [401], retryable: false },
+  invalid_request: { statuses: [400], retryable: false },
+  not_found: { statuses: [404], retryable: false },
+  forbidden: { statuses: [402, 403], retryable: false },
+  idempotency_conflict: { statuses: [409], retryable: false },
+  run_conflict: { statuses: [409], retryable: true },
+  rate_limited: { statuses: [429], retryable: true },
+  temporarily_unavailable: { statuses: [503], retryable: true },
+  internal_error: { statuses: [500], retryable: false },
+});
+type ErrorCode = keyof typeof ERROR_CODES;
+
+type CapsuleErrorBody = {
+  readonly code: ErrorCode;
+  readonly capsuleId: string | null;
+  readonly retryable: boolean;
+};
+
+function isErrorCode(value: unknown): value is ErrorCode {
+  return typeof value === 'string' && value in ERROR_CODES;
+}
+
+function isRecordBody(body: unknown): body is Record<string, unknown> {
+  return body !== null && typeof body === 'object' && !Array.isArray(body);
+}
+
+function hasExactErrorFields(value: Record<string, unknown>): boolean {
+  const fields = Object.keys(value);
+  const exactFields = ['code', 'message', 'capsule_id', 'retryable'];
+  return fields.length === exactFields.length &&
+    exactFields.every((field) => field in value);
+}
+
+function hasValidErrorValues(value: Record<string, unknown>): value is Record<string, unknown> & {
+  readonly code: ErrorCode;
+  readonly capsule_id: string | null;
+  readonly retryable: boolean;
+} {
+  return isErrorCode(value.code) &&
+    typeof value.message === 'string' &&
+    (value.capsule_id === null || typeof value.capsule_id === 'string') &&
+    typeof value.retryable === 'boolean';
+}
+
+function parseErrorBody(body: unknown): CapsuleErrorBody {
+  if (!isRecordBody(body) || !hasExactErrorFields(body) || !hasValidErrorValues(body)) {
+    throw new TargetProtocolError('Capsule error response is malformed');
+  }
+  const value = body;
+  return {
+    code: value.code,
+    capsuleId: value.capsule_id,
+    retryable: value.retryable,
+  };
+}
+
+function validateChallenge(response: Response): void {
+  if (response.status !== 401) return;
+  if (response.headers.get('WWW-Authenticate') !== 'Bearer error="invalid_token"') {
+    throw new TargetProtocolError('Capsule authentication challenge is malformed');
+  }
+}
+
+function validatedRetryAfter(
+  response: Response,
+  retryable: boolean,
+  clock: Clock,
+): number | undefined {
+  const header = response.headers.get('Retry-After');
+  const retryAfter = parseRetryAfter(header, clock) ?? undefined;
+  if (header !== null && retryAfter === undefined) {
+    throw new TargetProtocolError('Capsule Retry-After header is malformed');
+  }
+  if (retryable && retryAfter === undefined) {
+    throw new TargetProtocolError('Retryable capsule error omitted Retry-After');
+  }
+  if (!retryable && retryAfter !== undefined) {
+    throw new TargetProtocolError('Permanent capsule error advertised Retry-After');
+  }
+  return retryAfter;
+}
+
+export async function throwCapsuleServerError(
+  response: Response,
+  readJson: (response: Response) => Promise<unknown>,
+  clock: Clock,
+): Promise<never> {
+  const value = parseErrorBody(await readJson(response));
+  const contract = ERROR_CODES[value.code];
+  if (!contract.statuses.includes(response.status) || contract.retryable !== value.retryable) {
+    throw new TargetProtocolError('Capsule error response contradicts its status contract');
+  }
+  validateChallenge(response);
+  const retryAfter = validatedRetryAfter(response, contract.retryable, clock);
+  throw new TargetServerError(
+    response.status,
+    value.code,
+    contract.retryable,
+    value.capsuleId,
+    retryAfter,
+  );
+}