@oxy.so/core 1.6.0 → 1.7.0

package/src/utils/__tests__/requestUtilsAbort.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Abort awareness in the request queue and the deduplicator.
+ *
+ * Neither used to know about cancellation, and each turned that into a
+ * different bug:
+ *
+ * - `RequestQueue` never dropped a queued entry whose caller had cancelled, so
+ *   a burst of abandoned work (a search box being typed into) occupied every
+ *   one of the ten slots while the ONE request the viewer was waiting on
+ *   queued behind it. Refusing to RETRY a cancellation stops making more
+ *   zombies; this is what returns the slots.
+ * - `RequestDeduplicator` handed every caller on a key the same promise, so one
+ *   caller's abort rejected all the others — including ones that never
+ *   cancelled anything and had no way to know the failure was not theirs.
+ */
+import { RequestDeduplicator, RequestQueue } from '../requestUtils';
+import { ErrorCodes } from '../errorUtils';
+
+const aborted = (): AbortSignal => {
+  const controller = new AbortController();
+  controller.abort();
+  return controller.signal;
+};
+
+describe('RequestQueue abort awareness', () => {
+  it('never runs a request whose caller already cancelled', async () => {
+    const queue = new RequestQueue(2);
+    const run = jest.fn(async () => 'ran');
+
+    await expect(queue.enqueue(run, aborted())).rejects.toMatchObject({
+      code: ErrorCodes.CANCELLED,
+    });
+    expect(run).not.toHaveBeenCalled();
+  });
+
+  it('keeps slots free for a live request when the queue is full of cancelled ones', async () => {
+    const queue = new RequestQueue(2);
+    let liveRan = false;
+
+    // Six abandoned requests against a two-slot pool. If any of them took a
+    // slot and held it, the live request below could never run.
+    const dead = Array.from({ length: 6 }, () =>
+      queue
+        .enqueue(() => new Promise<string>(() => { /* would never settle */ }), aborted())
+        .catch(() => 'cancelled'),
+    );
+    await Promise.all(dead);
+
+    await expect(
+      queue.enqueue(async () => { liveRan = true; return 'live'; }),
+    ).resolves.toBe('live');
+    expect(liveRan).toBe(true);
+  });
+
+  it('drops a queued entry that is cancelled while it waits for a slot', async () => {
+    const queue = new RequestQueue(1);
+    const started: string[] = [];
+    let releaseFirst: (() => void) | undefined;
+
+    const first = queue.enqueue(async () => {
+      started.push('first');
+      await new Promise<void>((resolve) => { releaseFirst = resolve; });
+      return 'first';
+    });
+
+    // The pool is full, so this one sits in the queue rather than starting.
+    const controller = new AbortController();
+    const second = queue.enqueue(async () => {
+      started.push('second');
+      return 'second';
+    }, controller.signal);
+
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(started).toEqual(['first']);
+
+    // Cancelled while queued: it must never start, not merely be ignored once
+    // it finishes. A request can sit here as long as the slots stay busy, which
+    // is exactly when the caller is most likely to have moved on.
+    controller.abort();
+    await expect(second).rejects.toMatchObject({ code: ErrorCodes.CANCELLED });
+
+    releaseFirst?.();
+    await expect(first).resolves.toBe('first');
+    expect(started).toEqual(['first']);
+  });
+
+  it('still decrements its running count when a started request is aborted', async () => {
+    const queue = new RequestQueue(1);
+    const controller = new AbortController();
+
+    // An entry that has already started is left to its own abort domain: the
+    // queue must still observe it finishing, or `running` never comes back down
+    // and the slot is leaked permanently.
+    const inflight = queue.enqueue(
+      () => new Promise<string>((_resolve, reject) => {
+        controller.signal.addEventListener('abort', () => reject(new Error('aborted')), { once: true });
+      }),
+      controller.signal,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    controller.abort();
+    await expect(inflight).rejects.toBeDefined();
+
+    await expect(queue.enqueue(async () => 'after')).resolves.toBe('after');
+  });
+});
+
+describe('RequestDeduplicator abort awareness', () => {
+  it('shares one in-flight request across callers', async () => {
+    const dedupe = new RequestDeduplicator();
+    const work = jest.fn(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      return 'shared';
+    });
+
+    const [a, b] = await Promise.all([
+      dedupe.deduplicate('key', work),
+      dedupe.deduplicate('key', work),
+    ]);
+
+    expect(a).toBe('shared');
+    expect(b).toBe('shared');
+    expect(work).toHaveBeenCalledTimes(1);
+  });
+
+  it('lets one caller cancel without rejecting the others', async () => {
+    const dedupe = new RequestDeduplicator();
+    const work = jest.fn(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 30));
+      return 'shared';
+    });
+
+    const cancelling = new AbortController();
+    const first = dedupe.deduplicate('key', work, cancelling.signal);
+    const second = dedupe.deduplicate('key', work, new AbortController().signal);
+
+    const firstAssertion = expect(first).rejects.toMatchObject({ code: ErrorCodes.CANCELLED });
+    cancelling.abort();
+    await firstAssertion;
+
+    // The caller that never cancelled anything still gets its answer.
+    await expect(second).resolves.toBe('shared');
+    expect(work).toHaveBeenCalledTimes(1);
+  });
+
+  it('refuses a caller whose signal is already aborted without starting work', async () => {
+    const dedupe = new RequestDeduplicator();
+    const work = jest.fn(async () => 'shared');
+
+    await expect(dedupe.deduplicate('key', work, aborted())).rejects.toMatchObject({
+      code: ErrorCodes.CANCELLED,
+    });
+    expect(work).not.toHaveBeenCalled();
+  });
+});

package/src/utils/asyncUtils.ts

@@ -3,6 +3,7 @@
  */
 
 import { logger } from '../logger';
+import { ErrorCodes, isCancelledError } from './errorUtils';
 
 /**
  * Wrapper for async operations with automatic error handling
@@ -79,12 +80,72 @@ function extractHttpStatus(error: unknown): number | undefined {
  *
  * Use the `shouldRetry` callback to customize retry behavior.
  */
+export interface RetryOptions {
+  maxRetries?: number;
+  baseDelay?: number;
+  shouldRetry?: (error: unknown) => boolean;
+  /**
+   * Retry a request that hit its own per-attempt timeout. Default `false`.
+   *
+   * Retrying a timeout is defensible for an idempotent GET and indefensible
+   * with the old defaults: a 5s per-attempt timeout with 3 retries and
+   * exponential backoff spends ~28s before reporting a failure, all of it after
+   * the caller stopped waiting, while holding a request-queue slot throughout.
+   * A timeout also usually means the SERVER is slow, so three more attempts add
+   * load to the thing already struggling.
+   *
+   * Opt in per call, and pair it with {@link deadline} so the total is bounded
+   * by wall clock rather than by attempts x timeout + backoff.
+   */
+  retryOnTimeout?: boolean;
+  /**
+   * Absolute wall-clock budget for ALL attempts, as an epoch milliseconds
+   * timestamp (`Date.now() + budget`). Once passed, no further attempt starts
+   * and the last error is thrown.
+   *
+   * This is what makes a pathological total unreachable BY CONSTRUCTION rather
+   * than by arithmetic on the other knobs: a deadline per call, a timeout per
+   * attempt, and jittered retries inside the deadline.
+   */
+  deadline?: number;
+}
+
+/**
+ * Whether an error came from a request hitting its own timeout.
+ *
+ * A timeout and a caller cancellation both surface from `fetch` as an
+ * `AbortError`, so this only recognises one that has already been CLASSIFIED
+ * (by `HttpService`, which knows which of its own timers fired). An
+ * unclassified abort is treated as a cancellation, which is the safe
+ * direction: refusing to retry something that was abandoned costs nothing,
+ * while retrying it is the defect this whole option exists to fix.
+ */
+function isTimeoutError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const candidate = error as { code?: unknown; timeout?: unknown };
+  return candidate.timeout === true || candidate.code === ErrorCodes.TIMEOUT;
+}
+
 export async function retryAsync<T>(
   operation: () => Promise<T>,
-  maxRetries = 3,
-  baseDelay = 1000,
-  shouldRetry?: (error: any) => boolean
+  maxRetriesOrOptions: number | RetryOptions = 3,
+  baseDelayArg = 1000,
+  shouldRetryArg?: (error: any) => boolean
 ): Promise<T> {
+  // An options-object overload rather than a fifth positional parameter:
+  // `retryOnError` below and other in-tree callers pass positionally, and a
+  // boolean wedged between `baseDelay` and `shouldRetry` is the kind of
+  // signature that gets called wrong exactly once and then silently.
+  const options: RetryOptions =
+    typeof maxRetriesOrOptions === 'object' && maxRetriesOrOptions !== null
+      ? maxRetriesOrOptions
+      : { maxRetries: maxRetriesOrOptions, baseDelay: baseDelayArg, shouldRetry: shouldRetryArg };
+
+  const maxRetries = options.maxRetries ?? 3;
+  const baseDelay = options.baseDelay ?? 1000;
+  const retryOnTimeout = options.retryOnTimeout ?? false;
+  const deadline = options.deadline;
+
   let lastError: any;
 
   // Default shouldRetry: don't retry on 4xx errors (client errors).
@@ -92,6 +153,15 @@ export async function retryAsync<T>(
   // clients) AND `error.response.status` (axios-style shape) so neither
   // representation can leak a client error into the retry loop.
   const defaultShouldRetry = (error: unknown): boolean => {
+    // A cancellation is an INSTRUCTION, not a transient failure, and is
+    // refused here rather than only in HttpService so that every `retryAsync`
+    // consumer inherits it. This was the defect: an `AbortError` carries no
+    // HTTP status, `status: 0` is not 4xx, so the status check below passed it
+    // straight into the retry loop and the SDK re-issued requests their
+    // callers had already abandoned.
+    if (isCancelledError(error)) {
+      return false;
+    }
     const status = extractHttpStatus(error);
     if (status !== undefined && status >= 400 && status < 500) {
       return false;
@@ -99,28 +169,46 @@ export async function retryAsync<T>(
     return true;
   };
 
-  const retryCheck = shouldRetry || defaultShouldRetry;
-  
+  const retryCheck = options.shouldRetry || defaultShouldRetry;
+
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
       return await operation();
     } catch (error) {
       lastError = error;
-      
+
       if (attempt === maxRetries) {
         break;
       }
-      
+
+      // A cancellation is never retryable, whatever `shouldRetry` says: a
+      // custom predicate is for deciding which FAILURES are worth another
+      // attempt, and it has no business overriding an explicit abort.
+      if (isCancelledError(error)) {
+        break;
+      }
+
+      if (!retryOnTimeout && isTimeoutError(error)) {
+        break;
+      }
+
       if (!retryCheck(error)) {
         break;
       }
-      
+
       // Calculate delay with exponential backoff and jitter
       const delay = baseDelay * Math.pow(2, attempt) + Math.random() * 1000;
+
+      // Nothing may start, or even sleep, past the deadline — otherwise the
+      // budget bounds the attempts but not the wall clock the caller feels.
+      if (deadline !== undefined && Date.now() + delay >= deadline) {
+        break;
+      }
+
       await new Promise(resolve => setTimeout(resolve, delay));
     }
   }
-  
+
   throw lastError;
 }
 

package/src/utils/errorUtils.ts

@@ -33,7 +33,21 @@ export const ErrorCodes = {
   
   // Network errors
   NETWORK_ERROR: 'NETWORK_ERROR',
-  CONNECTION_FAILED: 'CONNECTION_FAILED'
+  CONNECTION_FAILED: 'CONNECTION_FAILED',
+
+  /**
+   * The CALLER cancelled this request — it did not fail.
+   *
+   * Distinct from {@link ErrorCodes.TIMEOUT} on purpose, and the distinction is
+   * load-bearing rather than cosmetic. Both arrive from `fetch` as an
+   * `AbortError` carrying no status, so for a long time both collapsed to
+   * `TIMEOUT` with `status: 0` — and since `status: 0` is not 4xx, the retry
+   * predicate treated a cancellation as a transient failure and re-issued the
+   * request the caller had just abandoned. A cancellation is an INSTRUCTION;
+   * nothing may retry it. See `retryAsync`'s default predicate, which refuses
+   * this code specifically.
+   */
+  CANCELLED: 'CANCELLED'
 } as const;
 
 /**
@@ -157,6 +171,59 @@ export function createApiError(
   };
 }
 
+/**
+ * The error a CALLER-cancelled request rejects with.
+ *
+ * Carries both identities on purpose, because consumers check for
+ * cancellation two different ways and both are legitimate:
+ *
+ * - `name: 'AbortError'` is what every `fetch`-era consumer tests, and what
+ *   React Query and friends recognise. Dropping it would silently turn
+ *   cancellations into errors in every app that already handles aborts.
+ * - `code: ErrorCodes.CANCELLED` / `cancelled: true` is what code inside this
+ *   SDK tests, because `handleHttpError` returns PLAIN objects (not `Error`s)
+ *   for most failures, so `name` is not a reliable discriminator across the
+ *   whole surface.
+ *
+ * It is an `Error` rather than a bare `ApiError` object so a stack survives and
+ * `instanceof Error` holds — the shape the abort path always looked like it
+ * produced, and never did.
+ */
+export type CancelledError = Error & ApiError & { cancelled: true };
+
+export function createCancelledError(message = 'Request cancelled'): CancelledError {
+  const error = new Error(message) as CancelledError;
+  error.name = 'AbortError';
+  error.code = ErrorCodes.CANCELLED;
+  error.status = 0;
+  error.cancelled = true;
+  return error;
+}
+
+/**
+ * Whether an error represents a CALLER cancellation rather than a failure.
+ *
+ * Structural, never message-based: a message is localizable and rewordable,
+ * and a retry predicate that keys off one is a bug waiting for a copy edit.
+ */
+function isAbortLike(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    (error as { name?: unknown }).name === 'AbortError'
+  );
+}
+
+export function isCancelledError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const candidate = error as { code?: unknown; cancelled?: unknown; name?: unknown };
+  return (
+    candidate.cancelled === true ||
+    candidate.code === ErrorCodes.CANCELLED ||
+    candidate.name === 'AbortError'
+  );
+}
+
 /**
  * Handle common HTTP errors and convert to ApiError
  */
@@ -174,8 +241,16 @@ export function handleHttpError(error: unknown): ApiError {
     return apiError;
   }
 
-  // Handle AbortError (timeout or cancelled requests)
-  if (error instanceof Error && error.name === 'AbortError') {
+  // Handle AbortError (timeout or cancelled requests).
+  //
+  // Matched by NAME rather than `instanceof Error`, because `fetch` rejects an
+  // abort with a `DOMException` and `instanceof` is realm-bound — an exception
+  // built in another realm (a test VM, a worker, an iframe) fails the check and
+  // falls through to the generic 500 branch below. `HttpService` classifies its
+  // own aborts before reaching here, so this is the fallback for aborts raised
+  // anywhere else, and it stays TIMEOUT: a caller that never passed a signal
+  // cannot have cancelled anything.
+  if (isAbortLike(error)) {
     return createApiError(
       'Request timeout or cancelled',
       ErrorCodes.TIMEOUT,

package/src/utils/requestUtils.ts

@@ -4,6 +4,28 @@
  * Provides reusable components for request deduplication, queuing, and logging
  */
 
+import { createCancelledError } from './errorUtils';
+
+/**
+ * The error to reject an aborted request with.
+ *
+ * ALWAYS the SDK's own cancellation error, with the signal's `reason` preserved
+ * as `cause` rather than substituted for it. The tempting version —
+ * `reason ?? createCancelledError()` — is wrong twice: `controller.abort()`
+ * always populates `reason` with a default `DOMException`, so the fallback
+ * would never run, and that `DOMException` carries none of the fields the retry
+ * predicates and consumers key off (`code: 'CANCELLED'`, `cancelled: true`).
+ * A cancellation that is not recognisable as one is the whole defect.
+ */
+function abortReason(signal: AbortSignal): unknown {
+  const reason = (signal as AbortSignal & { reason?: unknown }).reason;
+  const error = createCancelledError('Request cancelled') as Error & { cause?: unknown };
+  if (reason !== undefined) {
+    error.cause = reason;
+  }
+  return error;
+}
+
 /**
  * Request deduplication - prevents duplicate concurrent requests
  * 
@@ -31,20 +53,48 @@ export class RequestDeduplicator {
    */
   async deduplicate<T>(
     key: string,
-    requestFn: () => Promise<T>
+    requestFn: () => Promise<T>,
+    signal?: AbortSignal
   ): Promise<T> {
-    const existing = this.pendingRequests.get(key);
-    if (existing) {
-      return existing;
+    if (signal?.aborted) {
+      throw abortReason(signal);
     }
 
-    const promise = requestFn()
-      .finally(() => {
+    let promise = this.pendingRequests.get(key) as Promise<T> | undefined;
+    if (!promise) {
+      promise = requestFn().finally(() => {
         this.pendingRequests.delete(key);
       });
+      this.pendingRequests.set(key, promise);
+    }
+
+    // Callers SHARE the work but own their cancellation separately.
+    //
+    // Returning the shared promise directly meant one caller's abort rejected
+    // every other caller on the same key — including ones that never cancelled
+    // anything, and which had no way to tell that the failure was not theirs.
+    // Racing each caller's own signal against the shared work keeps the single
+    // in-flight request (the point of deduplication) while making cancellation
+    // per-caller. The shared promise is left running: another caller may still
+    // want it, and if nobody does its own abort domain ends it.
+    if (!signal) {
+      return promise;
+    }
+
+    // `promise` is already owned by the map's `finally`, so attach a no-op
+    // catch to the copy we race: without it, a rejection settled by the race's
+    // loser surfaces as an unhandled rejection.
+    const shared = promise;
+    shared.catch(() => { /* ownership stays with the caller(s) awaiting it */ });
 
-    this.pendingRequests.set(key, promise);
-    return promise;
+    return new Promise<T>((resolve, reject) => {
+      const onAbort = (): void => reject(abortReason(signal));
+      signal.addEventListener('abort', onAbort, { once: true });
+      shared.then(
+        (value) => { signal.removeEventListener('abort', onAbort); resolve(value); },
+        (error) => { signal.removeEventListener('abort', onAbort); reject(error); },
+      );
+    });
   }
 
   /**
@@ -99,21 +149,62 @@ export class RequestQueue {
    * @param requestFn Function that returns a promise
    * @returns Promise that resolves when request completes
    */
-  async enqueue<T>(requestFn: () => Promise<T>): Promise<T> {
+  async enqueue<T>(requestFn: () => Promise<T>, signal?: AbortSignal): Promise<T> {
     if (this.queue.length >= this.maxQueueSize) {
       throw new Error('Request queue is full');
     }
 
+    // A slot is the scarce resource — ten by default — so a request whose
+    // caller has already given up must never consume one. Without this, a
+    // burst of cancelled work (a search box being typed into, say) keeps every
+    // slot busy on results nobody will read, and the ONE request the user is
+    // waiting on queues behind them. This is the change that actually returns
+    // the slots; refusing to retry a cancellation only stops making more.
+    if (signal?.aborted) {
+      throw abortReason(signal);
+    }
+
     return new Promise<T>((resolve, reject) => {
-      this.queue.push(async () => {
+      let settled = false;
+      const finish = (fn: () => void): void => {
+        if (settled) return;
+        settled = true;
+        signal?.removeEventListener('abort', onAbort);
+        fn();
+      };
+
+      const entry = async (): Promise<void> => {
+        // Re-checked at the moment of execution, not just at enqueue: a request
+        // can sit in the queue for as long as the slots stay busy, and the
+        // caller may well have moved on in the meantime.
+        if (signal?.aborted) {
+          finish(() => reject(abortReason(signal)));
+          return;
+        }
         try {
           const result = await requestFn();
-          resolve(result);
+          finish(() => resolve(result));
         } catch (error) {
-          reject(error);
+          finish(() => reject(error));
         }
-      });
+      };
+
+      const abortingSignal = signal;
+      function onAbort(this: void): void {
+        if (!abortingSignal) return;
+        // Drop it from the queue if it has not started. An entry already
+        // running is left to its own abort domain — the queue must still see it
+        // finish, or `running` never decrements and the slot leaks for good.
+        const index = queueRef.indexOf(entry);
+        if (index !== -1) {
+          queueRef.splice(index, 1);
+        }
+        finish(() => reject(abortReason(abortingSignal)));
+      }
 
+      const queueRef = this.queue;
+      signal?.addEventListener('abort', onAbort, { once: true });
+      this.queue.push(entry);
       this.process();
     });
   }