@oxy.so/core 1.6.1 → 1.7.0

package/src/__tests__/httpServiceAbort.test.ts

@@ -0,0 +1,308 @@
+/**
+ * Cancellation and timeout regressions.
+ *
+ * `HttpService` used to build its `AbortController` INSIDE the function
+ * `retryAsync` re-invokes, and link the caller's signal to each new controller
+ * with a bare `addEventListener`. Since `abort` is a once-only event, a signal
+ * that had already fired could not abort the controller built for attempt 2 —
+ * so a request the caller had CANCELLED was re-issued for real. A caller abort
+ * also reached the retry predicate as an `AbortError` carrying `status: 0`,
+ * which is not 4xx, so the predicate read it as a transient failure worth
+ * another try. With the 5s default timeout and 3 retries that is ~28s of work
+ * after the caller stopped waiting, inside a request queue ten slots deep.
+ *
+ * Every test here pins one half of "a cancellation is an instruction, not a
+ * failure": nothing retries it, nothing queues it, and nothing leaks after it.
+ */
+import { HttpService } from '../HttpService';
+import { ErrorCodes } from '../utils/errorUtils';
+
+function jsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify({ data }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+/**
+ * A fetch that never responds, but DOES honour its abort signal — rejecting
+ * with an `AbortError` exactly as the real one does.
+ *
+ * Honouring the signal is not harness politeness, it is the whole point: the
+ * behaviour under test is what happens after an abort, so a fake that ignores
+ * the signal would hang instead of exercising it.
+ */
+function hangingFetch(): { fetch: typeof globalThis.fetch; calls: () => number } {
+  let calls = 0;
+  return {
+    fetch: ((_input: RequestInfo | URL, init?: RequestInit) => {
+      calls++;
+      return new Promise<Response>((_resolve, reject) => {
+        const signal = init?.signal;
+        const fail = (): void => reject(new DOMException('The operation was aborted.', 'AbortError'));
+        if (!signal) return;
+        if (signal.aborted) { fail(); return; }
+        signal.addEventListener('abort', fail, { once: true });
+      });
+    }) as typeof globalThis.fetch,
+    calls: () => calls,
+  };
+}
+
+/**
+ * Pin the retry backoff's jitter to zero.
+ *
+ * `retryAsync`'s delay is `baseDelay * 2**attempt + Math.random() * 1000`, so
+ * with real timers a retry can land up to a second later. A test that waits a
+ * fixed 80ms to prove "no retry happened" would then pass whether the bug was
+ * present or not — it would just be measuring the jitter. Pinning it makes the
+ * retry window exactly `baseDelay * (1 + 2 + 4)`, which a short wait covers
+ * decisively.
+ */
+function pinJitter(): void {
+  jest.spyOn(Math, 'random').mockReturnValue(0);
+}
+
+describe('HttpService cancellation', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+    jest.useRealTimers();
+  });
+
+  it('never calls fetch for a signal that was already aborted', async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => { calls++; return jsonResponse({}); }) as typeof globalThis.fetch;
+
+    const http = new HttpService({ baseURL: 'https://api.test' });
+    const controller = new AbortController();
+    controller.abort();
+
+    await expect(http.get('/thing', { signal: controller.signal })).rejects.toMatchObject({
+      code: ErrorCodes.CANCELLED,
+    });
+    expect(calls).toBe(0);
+  });
+
+  it('issues exactly one fetch when a request is cancelled mid-flight, with retry on', async () => {
+    pinJitter();
+    const { fetch, calls } = hangingFetch();
+    globalThis.fetch = fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      enableRetry: true,
+      maxRetries: 3,
+      retryDelay: 1,
+    });
+
+    const controller = new AbortController();
+    const pending = http.get('/thing', { signal: controller.signal });
+    const assertion = expect(pending).rejects.toMatchObject({ code: ErrorCodes.CANCELLED });
+
+    // Let the request reach fetch, then cancel it.
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(calls()).toBe(1);
+    controller.abort();
+    await assertion;
+
+    // The retry budget was 3 more attempts, whose backoff with jitter pinned is
+    // 1+2+4ms. Waiting well past that window is what proves none of them ran,
+    // and it is the crux of the defect: the re-issued request went out AFTER
+    // the rejection the caller saw, so a test that stopped at the rejection
+    // would have passed with the bug fully present.
+    await new Promise((resolve) => setTimeout(resolve, 80));
+    expect(calls()).toBe(1);
+  });
+
+  it('leaves no abort listener on a caller signal that outlives the request', async () => {
+    globalThis.fetch = (async () => jsonResponse({ ok: true })) as typeof globalThis.fetch;
+
+    const controller = new AbortController();
+    const added: unknown[] = [];
+    const removed: unknown[] = [];
+    const realAdd = controller.signal.addEventListener.bind(controller.signal);
+    const realRemove = controller.signal.removeEventListener.bind(controller.signal);
+    jest.spyOn(controller.signal, 'addEventListener').mockImplementation(((type: string, fn: never, opts: never) => {
+      if (type === 'abort') added.push(fn);
+      return realAdd(type as 'abort', fn, opts);
+    }) as never);
+    jest.spyOn(controller.signal, 'removeEventListener').mockImplementation(((type: string, fn: never, opts: never) => {
+      if (type === 'abort') removed.push(fn);
+      return realRemove(type as 'abort', fn, opts);
+    }) as never);
+
+    const http = new HttpService({ baseURL: 'https://api.test' });
+    // A React Query query signal is reused across the query's whole lifetime,
+    // so a listener left behind per request is an unbounded leak, not a nit.
+    for (let i = 0; i < 5; i++) {
+      await http.get(`/thing-${i}`, { signal: controller.signal, cache: false, deduplicate: false });
+    }
+
+    expect(added.length).toBeGreaterThan(0);
+    expect(removed.length).toBe(added.length);
+  });
+
+  it('does not consume a queue slot for a cancelled request, so a live one still runs', async () => {
+    const live: string[] = [];
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.includes('/live')) {
+        live.push(url);
+        return jsonResponse({ ok: true });
+      }
+      // Cancelled requests never get here; if one does, it would hold a slot.
+      return new Promise<Response>(() => { /* never settles */ });
+    }) as typeof globalThis.fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      maxConcurrentRequests: 2,
+      enableRetry: false,
+    });
+
+    // Fill more than the pool with requests whose callers have already gone.
+    const dead = Array.from({ length: 6 }, (_, i) => {
+      const controller = new AbortController();
+      controller.abort();
+      return http.get(`/dead-${i}`, { signal: controller.signal }).catch(() => 'cancelled');
+    });
+    await Promise.all(dead);
+
+    // With only two slots, this is the assertion that matters: the live request
+    // is not queued behind six abandoned ones.
+    await expect(http.get('/live', { cache: false })).resolves.toBeDefined();
+    expect(live).toHaveLength(1);
+  });
+});
+
+describe('HttpService timeout', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+    jest.useRealTimers();
+  });
+
+  it('does not retry a timeout by default, and reports it as a timeout not a cancellation', async () => {
+    pinJitter();
+    const { fetch, calls } = hangingFetch();
+    globalThis.fetch = fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      enableRetry: true,
+      maxRetries: 3,
+      retryDelay: 1,
+      requestTimeout: 20,
+    });
+
+    await expect(http.get('/slow', { cache: false })).rejects.toMatchObject({
+      code: ErrorCodes.TIMEOUT,
+      timeout: true,
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 80));
+    // One attempt, not four. Four behind a short timeout is how a single slow
+    // endpoint used to cost tens of seconds of wall clock.
+    expect(calls()).toBe(1);
+  });
+
+  it('retries a timeout when the caller opts in', async () => {
+    const { fetch, calls } = hangingFetch();
+    globalThis.fetch = fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      enableRetry: true,
+      maxRetries: 2,
+      retryDelay: 1,
+      requestTimeout: 20,
+    });
+
+    await expect(
+      http.get('/slow', { cache: false, retryOnTimeout: true }),
+    ).rejects.toMatchObject({ code: ErrorCodes.TIMEOUT });
+
+    expect(calls()).toBe(3);
+  });
+
+  it('bounds total wall clock with a deadline, even with retries on', async () => {
+    pinJitter();
+    const { fetch } = hangingFetch();
+    globalThis.fetch = fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      enableRetry: true,
+      maxRetries: 5,
+      retryDelay: 100,
+      requestTimeout: 20,
+    });
+
+    const started = Date.now();
+    await expect(
+      http.get('/slow', { cache: false, retryOnTimeout: true, deadline: 150 }),
+    ).rejects.toBeDefined();
+
+    // `timeout` bounds an attempt; `deadline` bounds the call. Without it the
+    // total is attempts x timeout + backoff, which no call site computes.
+    expect(Date.now() - started).toBeLessThan(400);
+  });
+
+  it('still retries a 5xx — the fix must not disable retry wholesale', async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls++;
+      return jsonResponse({ error: 'boom' }, 503);
+    }) as typeof globalThis.fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      enableRetry: true,
+      maxRetries: 2,
+      retryDelay: 1,
+    });
+
+    await expect(http.get('/flaky', { cache: false })).rejects.toBeDefined();
+    expect(calls).toBe(3);
+  });
+
+  it('still refuses to retry a 4xx', async () => {
+    let calls = 0;
+    globalThis.fetch = (async () => {
+      calls++;
+      return jsonResponse({ error: 'nope' }, 404);
+    }) as typeof globalThis.fetch;
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      enableRetry: true,
+      maxRetries: 3,
+      retryDelay: 1,
+    });
+
+    await expect(http.get('/missing', { cache: false })).rejects.toBeDefined();
+    expect(calls).toBe(1);
+  });
+
+  it('arms no timer past a request that threw before returning', async () => {
+    globalThis.fetch = (async () => jsonResponse({ error: 'nope' }, 404)) as typeof globalThis.fetch;
+    jest.useFakeTimers({ doNotFake: ['nextTick'] });
+
+    const http = new HttpService({
+      baseURL: 'https://api.test',
+      enableRetry: false,
+      requestTimeout: 30_000,
+    });
+
+    await expect(http.get('/missing', { cache: false })).rejects.toBeDefined();
+    // `clearTimeout` used to sit on the success path only, so any throw between
+    // the fetch and the return left a 30s timer armed.
+    expect(jest.getTimerCount()).toBe(0);
+    jest.useRealTimers();
+  });
+});

package/src/mixins/OxyServices.user.ts

@@ -202,8 +202,18 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
 
     /**
      * Search user profiles
+     *
+     * Takes an `AbortSignal` because people search is typed into: without one
+     * every keystroke started a search that ran to completion and had its
+     * result discarded, while holding one of the request queue's slots. It was
+     * the only search lane in Mention that could not be cancelled, purely
+     * because this signature had no way to say so.
      */
-    async searchProfiles(query: string, pagination?: PaginationParams): Promise<SearchProfilesResponse> {
+    async searchProfiles(
+      query: string,
+      pagination?: PaginationParams,
+      options?: { signal?: AbortSignal }
+    ): Promise<SearchProfilesResponse> {
       try {
         const response = await this.makeRequest<SearchProfilesResponse>(
           'GET',
@@ -212,6 +222,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
           {
             cache: true,
             cacheTTL: 2 * 60 * 1000, // 2 minutes cache
+            signal: options?.signal,
           }
         );
 

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

@@ -1,5 +1,5 @@
 import { retryAsync } from '../asyncUtils';
-import { handleHttpError } from '../errorUtils';
+import { createCancelledError, ErrorCodes, handleHttpError } from '../errorUtils';
 
 /**
  * Regression coverage for the 1.11.11 retry storm:
@@ -185,3 +185,95 @@ describe('handleHttpError preserves HTTP status for retry predicates', () => {
     expect(result.code).toBe('INTERNAL_ERROR');
   });
 });
+
+describe('retryAsync refuses to retry a cancellation', () => {
+  it('stops after one attempt on a cancellation, whatever the retry budget', async () => {
+    const operation = jest.fn(async () => { throw createCancelledError(); });
+
+    await expect(retryAsync(operation, { maxRetries: 3, baseDelay: 1 })).rejects.toMatchObject({
+      code: ErrorCodes.CANCELLED,
+    });
+    // This is the defect in one assertion: a cancellation carries no HTTP
+    // status, `status: 0` is not 4xx, so the status-only predicate passed it
+    // into the retry loop and the SDK re-issued abandoned requests.
+    expect(operation).toHaveBeenCalledTimes(1);
+  });
+
+  it('refuses a cancellation even when a custom shouldRetry says yes', async () => {
+    const operation = jest.fn(async () => { throw createCancelledError(); });
+
+    await expect(
+      retryAsync(operation, { maxRetries: 3, baseDelay: 1, shouldRetry: () => true }),
+    ).rejects.toBeDefined();
+    // A custom predicate decides which FAILURES deserve another attempt. It has
+    // no business overriding an explicit instruction to stop.
+    expect(operation).toHaveBeenCalledTimes(1);
+  });
+
+  it('treats a bare AbortError as a cancellation', async () => {
+    const operation = jest.fn(async () => {
+      throw new DOMException('The operation was aborted.', 'AbortError');
+    });
+
+    await expect(retryAsync(operation, { maxRetries: 3, baseDelay: 1 })).rejects.toBeDefined();
+    // An unclassified abort is assumed to be a cancellation: refusing to retry
+    // something abandoned costs nothing, retrying it is the bug.
+    expect(operation).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('retryAsync timeout policy', () => {
+  afterEach(() => { jest.restoreAllMocks(); });
+
+  const timeoutError = (): Error => {
+    const error = new Error('timed out') as Error & { code?: string; timeout?: boolean; status?: number };
+    error.code = ErrorCodes.TIMEOUT;
+    error.timeout = true;
+    error.status = 0;
+    return error;
+  };
+
+  it('does not retry a timeout by default', async () => {
+    const operation = jest.fn(async () => { throw timeoutError(); });
+
+    await expect(retryAsync(operation, { maxRetries: 3, baseDelay: 1 })).rejects.toBeDefined();
+    expect(operation).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries a timeout when asked to', async () => {
+    const operation = jest.fn(async () => { throw timeoutError(); });
+
+    await expect(
+      retryAsync(operation, { maxRetries: 2, baseDelay: 1, retryOnTimeout: true }),
+    ).rejects.toBeDefined();
+    expect(operation).toHaveBeenCalledTimes(3);
+  });
+
+  it('stops at the deadline rather than at the attempt budget', async () => {
+    // Jitter pinned so the backoff is exactly baseDelay * 2**attempt; otherwise
+    // this measures Math.random() rather than the deadline.
+    jest.spyOn(Math, 'random').mockReturnValue(0);
+    const operation = jest.fn(async () => { throw new Error('5xx-ish'); });
+
+    const started = Date.now();
+    await expect(
+      retryAsync(operation, { maxRetries: 10, baseDelay: 50, deadline: Date.now() + 120 }),
+    ).rejects.toBeDefined();
+
+    // The point of a deadline: the wall clock a caller feels is bounded by a
+    // budget it stated, not by arithmetic over attempts x timeout + backoff.
+    expect(Date.now() - started).toBeLessThan(400);
+    expect(operation.mock.calls.length).toBeLessThan(11);
+  });
+});
+
+describe('retryAsync keeps its positional signature working', () => {
+  it('accepts the legacy (operation, maxRetries, baseDelay, shouldRetry) call', async () => {
+    const operation = jest.fn(async () => { throw new Error('transient'); });
+
+    await expect(retryAsync(operation, 2, 1)).rejects.toThrow('transient');
+    // In-tree callers pass positionally, so the options object had to be an
+    // overload rather than a replacement.
+    expect(operation).toHaveBeenCalledTimes(3);
+  });
+});

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();
+  });
+});