contree-client 0.3.0 → 0.4.0

package/README.md

@@ -63,9 +63,11 @@ const client = new ContreeClient(token, { retry: new RetryPolicy() });
 const stored = await client.ensureFile(bytes);
 ```
 
-Only idempotent requests are retried (410/425/5xx and transient
-network errors, honoring `Retry-After`); pass
-`new RetryPolicy({ retryUnsafe: true })` to opt POSTs in.
+Idempotent requests retry after connection errors, request
+timeouts, and retryable responses (410/425/429/5xx). The client honors
+`Retry-After`. Pass `new RetryPolicy({ retryUnsafe: true })` to retry
+POSTs. Responses 425 and 429 are always safe to retry because they mean
+the backend did not process the request.
 
 ## Bring your own fetch
 
@@ -93,7 +95,7 @@ const client = new ContreeClient(token, {
   (`ReadableStream` uploads) are Node-only.
 - A truncated compressed download ends the stream short instead of
   throwing: `fetch` is lenient about a missing gzip trailer (the
-  Python client raises `DecompressionError` there).
+  Python client raises `EOFError` there).
 
 ## Testing
 

package/lib/client.js

@@ -1,14 +1,14 @@
 // Generated by codegen from the OpenAPI spec - do not edit.
 
 import {
-  ContreeAPIError,
-  ContreeError,
+  APIConnectionError,
+  APIStatusError,
+  ERROR_CLASSES,
+  ServerError,
   NotFoundError,
-  SSEStreamError,
 } from "./errors.js";
 import { AUTH_TYPE_IAM, ProfileError, resolveProfile } from "./profiles.js";
 import {
-  EVENTS_UNAVAILABLE_STATUSES,
   IS_NODE,
   SSEParser,
   TIGHT_LOOP_FLOOR,
@@ -17,20 +17,15 @@ import {
   UA_RUNTIME,
   decodeFramePayload,
   encodeQuery,
-  errorForResponse,
   monotonic,
-  retryAfterDelay,
+  responseErrorDetails,
   retryDelays,
   sha256,
   isUuid,
   sleep,
 } from "./runtime.js";
 import { DEFAULT_BASE_URL } from "./specInfo.js";
-import {
-  EventDataCompletion,
-  OperationEvent,
-  isTerminalStatus,
-} from "./models.js";
+import { OperationEvent, isTerminalStatus } from "./models.js";
 import * as operations from "./operations.js";
 
 /** Contree API client on top of the platform fetch.
@@ -63,6 +58,9 @@ export class ContreeClient {
         `unsupported baseUrl scheme ${parsed.protocol} in ${baseUrl}: use http:// or https://`,
       );
     }
+    if (parsed.username || parsed.password) {
+      throw new RangeError("baseUrl must not include credentials");
+    }
     this.token = token ?? null;
     this.baseUrl = baseUrl.replace(/\/+$/, "");
     this.project = project;
@@ -133,6 +131,11 @@ export class ContreeClient {
     if (IS_NODE && !("User-Agent" in headers)) {
       headers["User-Agent"] = this.userAgent();
     }
+    try {
+      new Headers(headers);
+    } catch {
+      throw new RangeError("invalid HTTP header name or value");
+    }
     return headers;
   }
 
@@ -155,33 +158,91 @@ export class ContreeClient {
     return options;
   }
 
-  /** Execute the request and return the buffered response. */
+  /** Execute one request and map its transport and HTTP errors. */
   async request(spec) {
     const controller = new AbortController();
+    const deadline = spec.deadline ?? null;
+    const remaining = deadline === null ? null : deadline - monotonic();
+    if (remaining !== null && remaining <= 0) {
+      const cause = new DOMException("request timed out", "TimeoutError");
+      throw new APIConnectionError(cause.message, { cause, timedOut: true });
+    }
+    const url = this.buildUrl(spec);
+    const options = this._fetchOptions(spec, controller.signal);
+    const timeout =
+      this.timeout === null
+        ? remaining
+        : remaining === null
+          ? this.timeout
+          : Math.min(this.timeout, remaining);
     // an explicit timer, not AbortSignal.timeout(): Node unrefs that
     // timer, so it can never fire when nothing else keeps the event
     // loop alive (custom fetch transports, for one)
     const timer =
-      this.timeout !== null
+      timeout !== null
         ? setTimeout(
             () =>
               controller.abort(
                 new DOMException("request timed out", "TimeoutError"),
               ),
-            this.timeout * 1000,
+            Math.ceil(Math.max(0, timeout) * 1000),
           )
         : null;
     try {
-      const response = await this._fetch(
-        this.buildUrl(spec),
-        this._fetchOptions(spec, controller.signal),
-      );
-      const body = new Uint8Array(await response.arrayBuffer());
+      let response;
+      try {
+        response = await this._fetch(url, options);
+      } catch (cause) {
+        if (cause?.name === "AbortError" && !controller.signal.aborted) {
+          throw cause;
+        }
+        throw new APIConnectionError(String(cause?.message ?? cause), {
+          cause,
+          timedOut:
+            cause?.name === "TimeoutError" ||
+            controller.signal.reason?.name === "TimeoutError",
+        });
+      }
+      if (deadline !== null && monotonic() >= deadline) {
+        const cause = new DOMException("request timed out", "TimeoutError");
+        throw new APIConnectionError(cause.message, { cause, timedOut: true });
+      }
+      let body;
+      try {
+        body = new Uint8Array(await response.arrayBuffer());
+      } catch (cause) {
+        if (cause?.name === "AbortError" && !controller.signal.aborted) {
+          throw cause;
+        }
+        throw new APIConnectionError(String(cause?.message ?? cause), {
+          cause,
+          timedOut:
+            cause?.name === "TimeoutError" ||
+            controller.signal.reason?.name === "TimeoutError",
+        });
+      }
+      if (deadline !== null && monotonic() >= deadline) {
+        const cause = new DOMException("request timed out", "TimeoutError");
+        throw new APIConnectionError(cause.message, { cause, timedOut: true });
+      }
       const headers = {};
       response.headers.forEach((value, key) => {
         headers[key.toLowerCase()] = value;
       });
-      return { status: response.status, headers, body, url: response.url };
+      const data = {
+        status: response.status,
+        headers,
+        body,
+        url: response.url,
+      };
+      if (response.status >= 400) {
+        const { error, traceback, retryAfter } = responseErrorDetails(data);
+        const ErrorClass =
+          ERROR_CLASSES.get(response.status) ??
+          (response.status >= 500 ? ServerError : APIStatusError);
+        throw new ErrorClass(response.status, error, { traceback, retryAfter });
+      }
+      return data;
     } finally {
       if (timer !== null) {
         clearTimeout(timer);
@@ -189,19 +250,7 @@ export class ContreeClient {
     }
   }
 
-  /** fetch reports network failures as TypeError; timeouts abort. */
-  _transportRetryable(error) {
-    return error instanceof TypeError;
-  }
-
-  _transportNonretryable(error) {
-    return (
-      error instanceof DOMException &&
-      (error.name === "AbortError" || error.name === "TimeoutError")
-    );
-  }
-
-  /** One transparent reconnect for a replayable idempotent request:
+  /** One transparent reconnect for a replayable connection error:
    * fetch pools keep-alive sockets and cannot pre-check them the way
    * the Python adapters do, so the first request on a socket the
    * server already closed fails without ever reaching the server. */
@@ -213,8 +262,8 @@ export class ContreeClient {
         !spec.idempotent ||
         (typeof ReadableStream !== "undefined" &&
           spec.body instanceof ReadableStream) ||
-        !this._transportRetryable(error) ||
-        this._transportNonretryable(error)
+        !(error instanceof APIConnectionError) ||
+        error.cause?.name !== "TypeError"
       ) {
         throw error;
       }
@@ -242,41 +291,45 @@ export class ContreeClient {
     // contract guarantees both mean the request was rejected before
     // any processing, so replaying is always safe.
     const replaySafe = spec.idempotent || policy.retryUnsafe;
+    const deadline = spec.deadline ?? null;
     const delays = retryDelays(policy.delays);
     let attempts = 0;
     for (;;) {
       attempts += 1;
       const exhausted =
         policy.maxAttempts !== null && attempts >= policy.maxAttempts;
-      let response;
       try {
-        response = await this.request(spec);
+        return await this.request(spec);
       } catch (error) {
+        const retryableStatus =
+          error instanceof APIStatusError &&
+          policy.retryableStatus(error.status);
+        const rejectedBeforeProcessing =
+          error instanceof APIStatusError &&
+          (error.status === 425 || error.status === 429);
         if (
-          !replaySafe ||
-          !this._transportRetryable(error) ||
-          this._transportNonretryable(error) ||
-          exhausted
+          (!(error instanceof APIConnectionError) && !retryableStatus) ||
+          (!replaySafe && !rejectedBeforeProcessing) ||
+          exhausted ||
+          (deadline !== null && monotonic() >= deadline)
         ) {
           throw error;
         }
-        await sleep(delays.next().value);
-        continue;
-      }
-      if (!policy.retryableStatus(response.status) || exhausted) {
-        return response;
-      }
-      if (!replaySafe && response.status !== 425 && response.status !== 429) {
-        return response;
+        let delay =
+          error instanceof APIStatusError && error.retryAfter !== null
+            ? error.retryAfter
+            : delays.next().value;
+        if (deadline !== null) {
+          delay = Math.min(delay, Math.max(0, deadline - monotonic()));
+        }
+        await sleep(delay);
       }
-      const retryAfter = retryAfterDelay(response);
-      await sleep(retryAfter !== null ? retryAfter : delays.next().value);
     }
   }
 
   /** Execute the request and yield response body chunks. */
   async *stream(spec) {
-    const controller = new AbortController();
+    let controller;
     let timer = null;
     const disarm = () => {
       if (timer !== null) {
@@ -294,21 +347,33 @@ export class ContreeClient {
           controller.abort(
             new DOMException("stream read timed out", "TimeoutError"),
           ),
-        Math.max(0, seconds) * 1000,
+        Math.ceil(Math.max(0, seconds) * 1000),
       );
     };
     const sse = spec.accept === "text/event-stream";
     const deadline = spec.deadline ?? null; // monotonic seconds
     // the budget for the next transport wait: downloads use the
-    // client timeout (idle cap, re-armed per chunk); SSE is unbounded
-    // unless the caller set an absolute deadline - keepalive frames
-    // re-enter abortIn with a shrinking remainder, so the bound stays
-    // absolute no matter how often the server keeps the stream warm
+    // client timeout as an idle cap, bounded by the caller's absolute
+    // deadline; SSE is unbounded unless the caller set a deadline.
+    // Keepalive frames re-enter abortIn with a shrinking remainder, so
+    // the bound stays absolute while the server keeps the stream warm.
     const nextBudget = () => {
-      if (!sse) {
-        return this.timeout;
+      const remaining = deadline === null ? null : deadline - monotonic();
+      if (sse || this.timeout === null) {
+        return remaining;
       }
-      return deadline === null ? null : deadline - monotonic();
+      return remaining === null
+        ? this.timeout
+        : Math.min(this.timeout, remaining);
+    };
+    const connectBudget = () => {
+      const remaining = deadline === null ? null : deadline - monotonic();
+      if (this.timeout === null) {
+        return remaining;
+      }
+      return remaining === null
+        ? this.timeout
+        : Math.min(this.timeout, remaining);
     };
     // the server may close a pooled keep-alive socket between
     // requests and fetch exposes no pool to pre-check (the Python
@@ -322,57 +387,68 @@ export class ContreeClient {
         typeof ReadableStream !== "undefined" &&
         spec.body instanceof ReadableStream
       );
-    const policy = replayable ? this.retry : null;
+    // SSE reconnection belongs to followOperationEvents(), which
+    // checks terminal status after each failed stream.
+    const policy = replayable && !sse ? this.retry : null;
     const maxAttempts =
       policy !== null ? policy.maxAttempts : replayable ? 2 : 1;
     const delays = policy === null ? null : retryDelays(policy.delays);
     let attempts = 0;
     let response;
     for (;;) {
+      if (deadline !== null && monotonic() >= deadline) {
+        throw new DOMException("stream read timed out", "TimeoutError");
+      }
       attempts += 1;
-      abortIn(this.timeout); // the connect phase always has a bound
+      controller = new AbortController();
+      abortIn(connectBudget());
       try {
         response = await this._fetch(
           this.buildUrl(spec),
           this._fetchOptions(spec, controller.signal),
         );
+        if (deadline !== null && monotonic() >= deadline) {
+          throw new DOMException("stream read timed out", "TimeoutError");
+        }
         break;
       } catch (error) {
         disarm();
+        const reconnectable =
+          error?.name === "TypeError" ||
+          (policy !== null && error?.name === "TimeoutError");
         if (
-          !this._transportRetryable(error) ||
-          this._transportNonretryable(error) ||
-          (maxAttempts !== null && attempts >= maxAttempts)
+          !reconnectable ||
+          (maxAttempts !== null && attempts >= maxAttempts) ||
+          (deadline !== null && monotonic() >= deadline)
         ) {
           throw error;
         }
-        await sleep(delays === null ? 0 : delays.next().value);
-      }
-    }
-    if (!(response.status >= 200 && response.status < 300)) {
-      // the error body is read under the same timer: a 500 with an
-      // endless body must not hang the caller
-      let body;
-      try {
-        body = new Uint8Array(await response.arrayBuffer());
-      } finally {
-        disarm();
+        let delay = delays === null ? 0 : delays.next().value;
+        if (deadline !== null) {
+          delay = Math.min(delay, Math.max(0, deadline - monotonic()));
+        }
+        await sleep(delay);
       }
-      const headers = {};
-      response.headers.forEach((value, key) => {
-        headers[key.toLowerCase()] = value;
-      });
-      throw errorForResponse({ status: response.status, headers, body });
     }
     disarm();
     const reader = response.body.getReader();
     try {
+      if (response.status >= 400) {
+        throw new RangeError(`HTTP ${response.status}`);
+      }
       for (;;) {
-        abortIn(nextBudget());
+        const budget = nextBudget();
+        if (budget !== null && budget <= 0) {
+          throw new DOMException("stream read timed out", "TimeoutError");
+        }
+        abortIn(budget);
         const { done, value } = await reader.read();
         // the timer covers only the transport wait, never the
         // consumer's processing of the yielded chunk
         disarm();
+        if (deadline !== null && monotonic() >= deadline) {
+          throw new DOMException("stream read timed out", "TimeoutError");
+        }
         if (done) {
           return;
         }
@@ -393,14 +469,42 @@ export class ContreeClient {
   async close() {}
 
   /** Best-effort check that the operation reached a terminal state. */
-  async operationTerminal(operationId) {
+  async operationTerminal(operationId, deadline = null) {
     let status;
+    const deadlineLimited =
+      deadline !== null &&
+      (this.timeout === null || deadline - monotonic() <= this.timeout);
     try {
-      status = (await this.getOperationStatus(operationId)).status;
+      // The outer event loop owns retries. Each status probe uses one
+      // transport attempt and stays inside the caller's deadline.
+      const spec = operations.buildGetOperationStatus(operationId);
+      spec.deadline = deadline;
+      status = operations.parseGetOperationStatus(
+        await this.request(spec),
+      ).status;
     } catch (error) {
-      if (error instanceof ContreeError || this._transportRetryable(error)) {
+      if (error instanceof APIConnectionError) {
+        if (
+          deadline !== null &&
+          (monotonic() >= deadline || (deadlineLimited && error.timedOut))
+        ) {
+          throw new DOMException(
+            `operation ${operationId} status probe exceeded its deadline`,
+            "TimeoutError",
+          );
+        }
         return false;
       }
+      if (error instanceof APIStatusError) {
+        if (
+          error.status === 410 ||
+          error.status === 425 ||
+          error.status === 429 ||
+          error.status >= 500
+        ) {
+          return false;
+        }
+      }
       throw error;
     }
     return status !== undefined && isTerminalStatus(status);
@@ -410,36 +514,49 @@ export class ContreeClient {
    * follows the SSE log until `completion`, then fetches and returns
    * the terminal OperationResponse. */
   async waitOperation(operationId, { timeout = null } = {}) {
+    const deadline = timeout === null ? null : monotonic() + timeout;
     // eslint-disable-next-line no-unused-vars
     for await (const event of this.followOperationEvents(operationId, {
       timeout,
     })) {
       // draining the stream is the wait
     }
-    return await this.getOperationStatus(operationId);
+    const spec = operations.buildGetOperationStatus(operationId);
+    spec.deadline = deadline;
+    const deadlineLimited =
+      deadline !== null &&
+      (this.timeout === null || deadline - monotonic() <= this.timeout);
+    try {
+      return operations.parseGetOperationStatus(await this.call(spec));
+    } catch (error) {
+      if (
+        deadline !== null &&
+        error instanceof APIConnectionError &&
+        (monotonic() >= deadline || (deadlineLimited && error.timedOut))
+      ) {
+        throw new DOMException(
+          `operation ${operationId} did not complete within ${timeout}s`,
+          "TimeoutError",
+        );
+      }
+      throw error;
+    }
   }
 
-  /** Stream operation events with transparent reconnection: network
-   * drops, in-band SSE error frames and retryable API statuses
-   * (410/425/5xx) reconnect from the last received event id. A status
-   * meaning the events endpoint itself doesn't exist for this
-   * operation/server (400/404/405/406) stops reconnecting and instead
-   * polls getOperationStatus() until the operation is terminal, then
-   * yields a synthesized `completion` event built from that status
-   * (there is no real event log to relay). Other API errors
-   * propagate. Ends after the `completion` event. */
+  /** Stream operation events with transparent reconnection.
+   * Native stream failures trigger a terminal-status probe and a
+   * reconnect from the last event id. */
   async *followOperationEvents(
     operationId,
     { last_event_id = null, spid = null, since = null, timeout = null } = {},
   ) {
     let lastId = last_event_id;
-    const delays = retryDelays();
     const deadline = timeout === null ? null : monotonic() + timeout;
     const checkDeadline = () => {
       if (deadline !== null && monotonic() >= deadline) {
-        throw new ContreeAPIError(
-          0,
+        throw new DOMException(
           `operation ${operationId} events did not complete within ${timeout}s`,
+          "TimeoutError",
         );
       }
     };
@@ -462,101 +579,25 @@ export class ContreeClient {
           checkDeadline();
         }
       } catch (error) {
-        if (error instanceof SSEStreamError) {
-          if (error.lastEventId !== null) {
-            lastId = error.lastEventId;
-          }
-        } else if (error instanceof ContreeAPIError) {
-          if (EVENTS_UNAVAILABLE_STATUSES.has(error.status)) {
-            // the endpoint is gone, not just failing: reconnecting the
-            // same request will never work, but the operation may
-            // still finish - stop touching /events and poll status
-            // instead for the rest of this wait
-            for (;;) {
-              checkDeadline();
-              let response;
-              try {
-                response = await this.getOperationStatus(operationId);
-              } catch (pollError) {
-                if (
-                  !(pollError instanceof ContreeError) &&
-                  !this._transportRetryable(pollError)
-                ) {
-                  throw pollError;
-                }
-                response = null;
-              }
-              if (
-                response !== null &&
-                response.status !== undefined &&
-                isTerminalStatus(response.status)
-              ) {
-                // no event log to relay, but a caller of
-                // followOperationEvents must still observe a terminal
-                // completion rather than nothing at all
-                lastId = lastId === null ? 0 : lastId + 1;
-                yield new OperationEvent({
-                  id: lastId,
-                  ts: new Date(),
-                  type: "completion",
-                  data: new EventDataCompletion({
-                    status: response.status,
-                    duration_ms:
-                      typeof response.duration === "number"
-                        ? Math.round(response.duration * 1000)
-                        : 0,
-                    result_image_uuid: response.result_image_uuid,
-                    error: response.error,
-                    image_size_bytes:
-                      typeof response.image_size === "number"
-                        ? response.image_size
-                        : undefined,
-                  }),
-                });
-                return;
-              }
-              let pollDelay = delays.next().value;
-              if (deadline !== null) {
-                pollDelay = Math.min(
-                  pollDelay,
-                  Math.max(0, deadline - monotonic()),
-                );
-              }
-              await sleep(pollDelay);
-            }
-          }
-          const retryable =
-            error.status === 410 ||
-            error.status === 425 ||
-            (error.status >= 500 && error.status < 600);
-          if (!retryable) {
-            throw error;
-          }
-          if (await this.operationTerminal(operationId)) {
-            return;
-          }
-          let delay =
-            error.retryAfter !== null ? error.retryAfter : delays.next().value;
-          if (deadline !== null) {
-            // a Retry-After must not sleep past the caller's deadline
-            delay = Math.min(delay, Math.max(0, deadline - monotonic()));
-          }
-          await sleep(delay);
-          continue;
-        } else if (
-          !this._transportRetryable(error) ||
-          this._transportNonretryable(error)
-        ) {
+        if (error?.name === "AbortError") {
           throw error;
         }
+        checkDeadline();
+        if (Number.isInteger(error?.lastEventId)) {
+          lastId = error.lastEventId;
+        }
       }
       // the stream ended or broke without a completion frame: the
       // retry must not outlive the operation itself
-      if (await this.operationTerminal(operationId)) {
+      if (await this.operationTerminal(operationId, deadline)) {
         return;
       }
       if (lastId === eventsBefore) {
-        await sleep(TIGHT_LOOP_FLOOR);
+        let delay = TIGHT_LOOP_FLOOR;
+        if (deadline !== null) {
+          delay = Math.min(delay, Math.max(0, deadline - monotonic()));
+        }
+        await sleep(delay);
       }
     }
   }
@@ -717,7 +758,14 @@ export class ContreeClient {
   /** Check if a file exists for the current namespace (HEAD /files/{sha256}) */
   async checkFileExists(sha256) {
     const spec = operations.buildCheckFileExists(sha256);
-    return operations.parseCheckFileExists(await this.call(spec));
+    try {
+      return operations.parseCheckFileExists(await this.call(spec));
+    } catch (error) {
+      if (error instanceof NotFoundError) {
+        return false;
+      }
+      throw error;
+    }
   }
 
   /** Spawn a new container instance (POST /instances) */
@@ -797,12 +845,10 @@ export class ContreeClient {
     let lastSeen = options.last_event_id ?? null;
     for await (const chunk of this.stream(spec)) {
       for (const frame of parser.feed(chunk)) {
-        const payload = decodeFramePayload(frame, lastSeen);
-        // id-only frames advance the resume cursor even
-        // though they carry no payload
         if (frame.id !== null) {
           lastSeen = frame.id;
         }
+        const payload = decodeFramePayload(frame, lastSeen);
         if (payload === null) {
           continue;
         }
@@ -875,7 +921,14 @@ export class ContreeClient {
   /** Check if a file exists in image (HEAD /inspect/{image_uuid}/download) */
   async checkImageFile(imageUuid, path) {
     const spec = operations.buildCheckImageFile(imageUuid, path);
-    return operations.parseCheckImageFile(await this.call(spec));
+    try {
+      return operations.parseCheckImageFile(await this.call(spec));
+    } catch (error) {
+      if (error instanceof NotFoundError) {
+        return false;
+      }
+      throw error;
+    }
   }
 
   /** Download a file or a directory from image as tar archive (GET /inspect/{image_uuid}/archive) */
@@ -887,7 +940,14 @@ export class ContreeClient {
   /** Check if a path can be archived from image (HEAD /inspect/{image_uuid}/archive) */
   async checkImageArchive(imageUuid, path) {
     const spec = operations.buildCheckImageArchive(imageUuid, path);
-    return operations.parseCheckImageArchive(await this.call(spec));
+    try {
+      return operations.parseCheckImageArchive(await this.call(spec));
+    } catch (error) {
+      if (error instanceof NotFoundError) {
+        return false;
+      }
+      throw error;
+    }
   }
 
   /** List files in image (GET /inspect/{image_uuid}/list) */

package/lib/errors.d.ts

@@ -1,11 +1,16 @@
-export declare class ContreeError extends Error {}
+export declare class ContreeError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
 
-export declare class SSEStreamError extends ContreeError {
-  lastEventId: number | null;
-  constructor(message: string, options?: { lastEventId?: number | null });
+export declare class APIConnectionError extends ContreeError {
+  timedOut: boolean;
+  constructor(
+    message: string,
+    options?: { cause?: unknown; timedOut?: boolean },
+  );
 }
 
-export declare class ContreeAPIError extends ContreeError {
+export declare class APIStatusError extends ContreeError {
   status: number;
   error: unknown;
   traceback: string[] | null;
@@ -17,14 +22,15 @@ export declare class ContreeAPIError extends ContreeError {
   );
 }
 
-export declare class BadRequestError extends ContreeAPIError {}
-export declare class UnauthorizedError extends ContreeAPIError {}
-export declare class ForbiddenError extends ContreeAPIError {}
-export declare class NotFoundError extends ContreeAPIError {}
-export declare class ConflictError extends ContreeAPIError {}
-export declare class GoneError extends ContreeAPIError {}
-export declare class UnprocessableEntityError extends ContreeAPIError {}
-export declare class TooEarlyError extends ContreeAPIError {}
-export declare class ServerError extends ContreeAPIError {}
+export declare class BadRequestError extends APIStatusError {}
+export declare class AuthenticationError extends APIStatusError {}
+export declare class PermissionDeniedError extends APIStatusError {}
+export declare class NotFoundError extends APIStatusError {}
+export declare class ConflictError extends APIStatusError {}
+export declare class GoneError extends APIStatusError {}
+export declare class UnprocessableEntityError extends APIStatusError {}
+export declare class TooEarlyError extends APIStatusError {}
+export declare class RateLimitError extends APIStatusError {}
+export declare class ServerError extends APIStatusError {}
 
-export declare const ERROR_CLASSES: Map<number, typeof ContreeAPIError>;
+export declare const ERROR_CLASSES: Map<number, typeof APIStatusError>;

package/lib/errors.js

@@ -1,20 +1,20 @@
 /** Exception hierarchy for the Contree API client. */
 
 export class ContreeError extends Error {
-  constructor(message) {
-    super(message);
+  constructor(message, options) {
+    super(message, options);
     this.name = new.target.name;
   }
 }
 
-export class SSEStreamError extends ContreeError {
-  constructor(message, { lastEventId = null } = {}) {
-    super(message);
-    this.lastEventId = lastEventId;
+export class APIConnectionError extends ContreeError {
+  constructor(message, { cause, timedOut = false } = {}) {
+    super(message, { cause });
+    this.timedOut = timedOut;
   }
 }
 
-export class ContreeAPIError extends ContreeError {
+export class APIStatusError extends ContreeError {
   constructor(status, error, { traceback = null, retryAfter = null } = {}) {
     super(`HTTP ${status}: ${error}`);
     this.status = status;
@@ -24,23 +24,25 @@ export class ContreeAPIError extends ContreeError {
   }
 }
 
-export class BadRequestError extends ContreeAPIError {}
-export class UnauthorizedError extends ContreeAPIError {}
-export class ForbiddenError extends ContreeAPIError {}
-export class NotFoundError extends ContreeAPIError {}
-export class ConflictError extends ContreeAPIError {}
-export class GoneError extends ContreeAPIError {}
-export class UnprocessableEntityError extends ContreeAPIError {}
-export class TooEarlyError extends ContreeAPIError {}
-export class ServerError extends ContreeAPIError {}
+export class BadRequestError extends APIStatusError {}
+export class AuthenticationError extends APIStatusError {}
+export class PermissionDeniedError extends APIStatusError {}
+export class NotFoundError extends APIStatusError {}
+export class ConflictError extends APIStatusError {}
+export class GoneError extends APIStatusError {}
+export class UnprocessableEntityError extends APIStatusError {}
+export class TooEarlyError extends APIStatusError {}
+export class RateLimitError extends APIStatusError {}
+export class ServerError extends APIStatusError {}
 
 export const ERROR_CLASSES = new Map([
   [400, BadRequestError],
-  [401, UnauthorizedError],
-  [403, ForbiddenError],
+  [401, AuthenticationError],
+  [403, PermissionDeniedError],
   [404, NotFoundError],
   [409, ConflictError],
   [410, GoneError],
   [422, UnprocessableEntityError],
   [425, TooEarlyError],
+  [429, RateLimitError],
 ]);

package/lib/index.d.ts

@@ -8,9 +8,13 @@ export {
   RETRY_DELAYS,
   RetryPolicy,
   SSEParser,
+  base64ToBytes,
+  bytesToBase64,
+  bytesToText,
   parseDatetime,
   parseRetryAfter,
   sha256,
+  textToBytes,
 } from "./runtime.js";
 export type { RequestSpec, ResponseData, RequestBody } from "./runtime.js";
 export { ContreeClient, ContreeClientOptions } from "./client.js";

package/lib/index.js

@@ -8,9 +8,13 @@ export {
   RETRY_DELAYS,
   RetryPolicy,
   SSEParser,
+  base64ToBytes,
+  bytesToBase64,
+  bytesToText,
   parseDatetime,
   parseRetryAfter,
   sha256,
+  textToBytes,
 } from "./runtime.js";
 export { ContreeClient } from "./client.js";
 export * as operations from "./operations.js";

package/lib/operations.js

@@ -1,7 +1,6 @@
 // Generated by codegen from the OpenAPI spec - do not edit.
 
 import {
-  errorForResponse,
   formatTimeParam,
   jsonArray,
   jsonObject,
@@ -67,7 +66,7 @@ export function parseListImages(response) {
   if (response.status >= 200 && response.status < 300) {
     return ImageListResponse.fromWire(jsonObject(response));
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `DELETE /images/{imageUUID}/tag`. */
@@ -89,7 +88,7 @@ export function parseDeleteImageTag(response) {
   if (response.status >= 200 && response.status < 300) {
     return null;
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `PATCH /images/{imageUUID}/tag`. */
@@ -110,7 +109,7 @@ export function parseUpdateImageTag(response) {
   if (response.status >= 200 && response.status < 300) {
     return Image.fromWire(jsonObject(response));
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `POST /images/import`. */
@@ -130,7 +129,7 @@ export function parseImportImage(response) {
   if (response.status >= 200 && response.status < 300) {
     return String(jsonObject(response)["uuid"]);
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `GET /files`. */
@@ -161,7 +160,7 @@ export function parseListFiles(response) {
   if (response.status >= 200 && response.status < 300) {
     return FilesListResponse.fromWire(jsonObject(response));
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `POST /files`. */
@@ -180,7 +179,7 @@ export function parseUploadFile(response) {
   if (response.status >= 200 && response.status < 300) {
     return FileResponse.fromWire(jsonObject(response));
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `GET /files/{sha256}`. */
@@ -197,7 +196,7 @@ export function parseGetFile(response) {
   if (response.status >= 200 && response.status < 300) {
     return File.fromWire(jsonObject(response));
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `HEAD /files/{sha256}`. */
@@ -214,10 +213,7 @@ export function parseCheckFileExists(response) {
   if (response.status >= 200 && response.status < 300) {
     return true;
   }
-  if (response.status === 404) {
-    return false;
-  }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `POST /instances`. */
@@ -275,7 +271,7 @@ export function parseSpawnInstance(response) {
   if (response.status >= 200 && response.status < 300) {
     return InstanceSpawnResponse.fromWire(jsonObject(response));
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `GET /operations`. */
@@ -314,7 +310,7 @@ export function parseListOperations(response) {
   if (response.status >= 200 && response.status < 300) {
     return jsonArray(response).map((item) => OperationSummary.fromWire(item));
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `GET /operations/{operationId}`. */
@@ -339,7 +335,7 @@ export function parseGetOperationStatus(response) {
   if (response.status >= 200 && response.status < 300) {
     return OperationResponse.fromWire(jsonObject(response));
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `DELETE /operations/{operationId}`. */
@@ -356,7 +352,7 @@ export function parseCancelOperation(response) {
   if (response.status >= 200 && response.status < 300) {
     return null;
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `GET /operations/{operationId}/events`. */
@@ -420,7 +416,7 @@ export function parseOperationSubprocessCreate(response) {
   if (response.status >= 200 && response.status < 300) {
     return Number(jsonObject(response)["spid"]);
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `GET /operations/{operationId}/subprocesses/{spid}`. */
@@ -437,7 +433,7 @@ export function parseOperationSubprocess(response) {
   if (response.status >= 200 && response.status < 300) {
     return InstanceResult.fromWire(jsonObject(response));
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `DELETE /operations/{operationId}/subprocesses/{spid}`. */
@@ -463,7 +459,7 @@ export function parseOperationSubprocessKill(response) {
   if (response.status >= 200 && response.status < 300) {
     return null;
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `POST /operations/{operationId}/subprocesses/{spid}/stdin`. */
@@ -494,7 +490,7 @@ export function parseOperationSubprocessStdin(response) {
   if (response.status >= 200 && response.status < 300) {
     return null;
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `GET /inspect/`. */
@@ -522,7 +518,7 @@ export function parseInspectFindImageByTag(response) {
     const path = new URL(response.url).pathname;
     return path.replace(/\/+$/, "").split("/").pop();
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `GET /inspect/{image_uuid}/`. */
@@ -539,7 +535,7 @@ export function parseInspectImage(response) {
   if (response.status >= 200 && response.status < 300) {
     return Image.fromWire(jsonObject(response));
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `GET /inspect/{image_uuid}/download`. */
@@ -559,7 +555,7 @@ export function parseInspectImageDownload(response) {
   if (response.status >= 200 && response.status < 300) {
     return response.body;
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `HEAD /inspect/{image_uuid}/download`. */
@@ -579,10 +575,7 @@ export function parseCheckImageFile(response) {
   if (response.status >= 200 && response.status < 300) {
     return true;
   }
-  if (response.status === 404) {
-    return false;
-  }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `GET /inspect/{image_uuid}/archive`. */
@@ -614,10 +607,7 @@ export function parseCheckImageArchive(response) {
   if (response.status >= 200 && response.status < 300) {
     return true;
   }
-  if (response.status === 404) {
-    return false;
-  }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `GET /inspect/{image_uuid}/list`. */
@@ -637,7 +627,7 @@ export function parseInspectImageList(response) {
   if (response.status >= 200 && response.status < 300) {
     return DirectoryList.fromWire(jsonObject(response));
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `GET /inspect/{image_uuid}/grep`. */
@@ -690,7 +680,7 @@ export function parseInspectImageGrep(response) {
   if (response.status >= 200 && response.status < 300) {
     return GrepResult.fromWire(jsonObject(response));
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }
 
 /** Build the request for `GET /whoami`. */
@@ -703,5 +693,5 @@ export function parseWhoami(response) {
   if (response.status >= 200 && response.status < 300) {
     return WhoAmIResponse.fromWire(jsonObject(response));
   }
-  throw errorForResponse(response);
+  throw new RangeError(`unexpected HTTP status ${response.status}`);
 }

package/lib/profiles.d.ts

@@ -1,11 +1,9 @@
-import { ContreeError } from "./errors.js";
-
 export declare const AUTH_TYPE_IAM: "iam";
 export declare const AUTH_TYPE_JWT: "jwt";
 export declare const PROFILE_PREFIX: "profile:";
 export declare const DEFAULT_PROFILE: "default";
 
-export declare class ProfileError extends ContreeError {}
+export declare class ProfileError extends Error {}
 
 export interface Profile {
   name: string;

package/lib/profiles.js

@@ -7,7 +7,6 @@
  * loaded lazily so browser bundlers never pull them in.
  */
 
-import { ContreeError } from "./errors.js";
 import { DEFAULT_BASE_URL } from "./specInfo.js";
 
 export const AUTH_TYPE_IAM = "iam";
@@ -15,7 +14,7 @@ export const AUTH_TYPE_JWT = "jwt";
 export const PROFILE_PREFIX = "profile:";
 export const DEFAULT_PROFILE = "default";
 
-export class ProfileError extends ContreeError {}
+export class ProfileError extends Error {}
 
 function record() {
   // a null-prototype object: keys come from an external file, and a

package/lib/runtime.d.ts

@@ -28,7 +28,7 @@ export interface RequestSpec {
   accept?: string | null;
   idempotent?: boolean;
   redirect?: "manual" | "follow";
-  /** absolute deadline in monotonic seconds; bounds SSE idle waits */
+  /** absolute deadline in monotonic seconds; bounds transport waits */
   deadline?: number | null;
 }
 
@@ -53,7 +53,6 @@ export declare class RetryPolicy {
 export declare function parseRetryAfter(
   value: string | null | undefined,
 ): number | null;
-export declare function retryAfterDelay(response: ResponseData): number | null;
 export declare function sleep(seconds: number): Promise<void>;
 export declare function monotonic(): number;
 export declare function isUuid(ref: string): boolean;
@@ -75,7 +74,11 @@ export declare function jsonObject(
   response: ResponseData,
 ): Record<string, unknown>;
 export declare function jsonArray(response: ResponseData): unknown[];
-export declare function errorForResponse(response: ResponseData): Error;
+export declare function responseErrorDetails(response: ResponseData): {
+  error: unknown;
+  traceback: string[] | null;
+  retryAfter: number | null;
+};
 
 export interface SSEFrame {
   id: number | null;

package/lib/runtime.js

@@ -5,16 +5,9 @@
  * fetch itself, so only the protocol logic lives here.
  */
 
-import {
-  ContreeAPIError,
-  ERROR_CLASSES,
-  ServerError,
-  SSEStreamError,
-} from "./errors.js";
-
 export const CHUNK_SIZE = 65536;
 
-export const PACKAGE_VERSION = "0.3.0";
+export const PACKAGE_VERSION = "0.4.0";
 export const UA_PRODUCT = `contree-client-js/${PACKAGE_VERSION}`;
 
 const NODE_VERSION =
@@ -38,17 +31,6 @@ export const RETRY_DELAYS = Object.freeze([0.1, 0.2, 0.5, 1.0, 2.0, 5.0]);
 // returning immediate empty streams does not spin the client
 export const TIGHT_LOOP_FLOOR = 0.5;
 
-// the events route itself doesn't exist for this operation/server
-// (malformed request an older backend rejects, or a reverse proxy
-// that never forwards it) rather than merely being down: reconnecting
-// will never succeed, but the operation itself may still complete -
-// degrade to polling instead of failing the whole wait. 401/403 are
-// deliberately excluded: an auth/permission failure here likely means
-// the whole client is broken, not just this route, so it still throws
-export const EVENTS_UNAVAILABLE_STATUSES = Object.freeze(
-  new Set([400, 404, 405, 406]),
-);
-
 /** An endless ladder of backoff delays: the ladder is walked once and
  * then the tail delay repeats forever. */
 export function* retryDelays(delays = RETRY_DELAYS) {
@@ -125,10 +107,6 @@ export function parseRetryAfter(value) {
   return Math.max(0, (moment - Date.now()) / 1000);
 }
 
-export function retryAfterDelay(response) {
-  return parseRetryAfter(response.headers["retry-after"] ?? null);
-}
-
 export function sleep(seconds) {
   return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
 }
@@ -266,7 +244,9 @@ export function jsonBody(response) {
 export function jsonObject(response) {
   const data = jsonBody(response);
   if (data === null || typeof data !== "object" || Array.isArray(data)) {
-    throw new ContreeAPIError(response.status, "expected a JSON object");
+    const type =
+      data === null ? "null" : Array.isArray(data) ? "array" : typeof data;
+    throw new TypeError(`expected a JSON object, got ${type}`);
   }
   return data;
 }
@@ -274,13 +254,14 @@ export function jsonObject(response) {
 export function jsonArray(response) {
   const data = jsonBody(response);
   if (!Array.isArray(data)) {
-    throw new ContreeAPIError(response.status, "expected a JSON array");
+    const type = data === null ? "null" : typeof data;
+    throw new TypeError(`expected a JSON array, got ${type}`);
   }
   return data;
 }
 
-/** Build the exception matching an error response. */
-export function errorForResponse(response) {
+/** Extract diagnostic fields from an unsuccessful response. */
+export function responseErrorDetails(response) {
   let error = bytesToText(response.body);
   let traceback = null;
   let payload = null;
@@ -301,11 +282,7 @@ export function errorForResponse(response) {
   }
   const parsedRetry = parseRetryAfter(response.headers["retry-after"] ?? null);
   const retryAfter = parsedRetry === null ? null : Math.trunc(parsedRetry);
-  let cls = ERROR_CLASSES.get(response.status);
-  if (cls === undefined) {
-    cls = response.status >= 500 ? ServerError : ContreeAPIError;
-  }
-  return new cls(response.status, error, { traceback, retryAfter });
+  return { error, traceback, retryAfter };
 }
 
 /** Incremental sans-io parser for `text/event-stream` bytes.
@@ -334,7 +311,7 @@ export class SSEParser {
     // accumulated so far: many short data lines must not grow the
     // pending event unboundedly
     if (this.buffer.length + this.pendingSize > SSEParser.MAX_BUFFER) {
-      throw new SSEStreamError(
+      throw new RangeError(
         `SSE frame exceeds ${SSEParser.MAX_BUFFER} bytes before completion`,
       );
     }
@@ -398,30 +375,15 @@ export class SSEParser {
   }
 }
 
-/** Decode an SSE frame's JSON payload.
- *
- * Raises SSEStreamError for in-band `sse_error` frames, carrying
- * *lastEventId* so the caller can reconnect from that point; returns
- * null for frames that carry no event payload. The caller turns the
- * plain object into a typed OperationEvent.
- */
+/** Decode an SSE frame's JSON payload. */
 export function decodeFramePayload(frame, lastEventId = null) {
   if (frame.event === "sse_error") {
-    throw new SSEStreamError(frame.data, { lastEventId });
+    throw Object.assign(new Error(frame.data), { lastEventId });
   }
   if (!frame.data) {
     return null;
   }
-  let payload;
-  try {
-    payload = JSON.parse(frame.data);
-  } catch (error) {
-    // surface protocol corruption through the SSE error channel so
-    // followOperationEvents reconnects instead of crashing
-    throw new SSEStreamError(`malformed SSE event payload: ${error}`, {
-      lastEventId,
-    });
-  }
+  const payload = JSON.parse(frame.data);
   if (
     payload === null ||
     typeof payload !== "object" ||

package/lib/testing.js

@@ -7,7 +7,6 @@
  */
 
 import { ContreeClient as GeneratedClient } from "./client.js";
-import { ContreeError } from "./errors.js";
 
 export const RESERVED = new Set([
   "constructor",
@@ -31,7 +30,7 @@ function apiMethodNames() {
 }
 
 function unmocked(operation) {
-  return new ContreeError(
+  return new Error(
     `no mock configured for ${operation}(); arm it with` +
       ` client.mock(${JSON.stringify(operation)}, result)`,
   );
@@ -94,9 +93,7 @@ export class ContreeClient extends GeneratedClient {
   /** Queue an outcome for *operation*; the last one queued is sticky. */
   mock(operation, result = null, { error = null } = {}) {
     if (typeof this[operation] !== "function" || RESERVED.has(operation)) {
-      throw new ContreeError(
-        `unknown API operation ${JSON.stringify(operation)}`,
-      );
+      throw new TypeError(`unknown API operation ${JSON.stringify(operation)}`);
     }
     const queue = this.mocks.get(operation) ?? [];
     queue.push({ result, error });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contree-client",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "JavaScript client for the Contree API, generated from the OpenAPI spec",
   "homepage": "https://contree.dev/",
   "repository": {