@oxy.so/core 1.6.1 → 1.7.0

package/dist/esm/HttpService.js

@@ -15,7 +15,7 @@
 import { TTLCache, registerCacheForCleanup } from './utils/cache.js';
 import { RequestDeduplicator, RequestQueue, SimpleLogger } from './utils/requestUtils.js';
 import { retryAsync } from './utils/asyncUtils.js';
-import { handleHttpError, parseHttpErrorBody } from './utils/errorUtils.js';
+import { createCancelledError, ErrorCodes, handleHttpError, parseHttpErrorBody } from './utils/errorUtils.js';
 import { jwtDecode } from 'jwt-decode';
 import { isNative, getPlatformOS } from './utils/platform.js';
 import { isReactNative } from '@oxy.so/protocol';
@@ -170,6 +170,41 @@ class TokenStore {
         this.csrfTokenFetchPromise = null;
     }
 }
+/**
+ * Propagate `parent`'s abort to `child`, returning a disposer.
+ *
+ * Three things a bare `parent.addEventListener('abort', ...)` gets wrong, all
+ * of which this exists to stop repeating:
+ *
+ * 1. **An already-aborted parent never fires again.** `abort` is a once-only
+ *    event, so linking to a signal that has already fired silently links to
+ *    nothing — which is how a cancelled request got re-issued on every retry.
+ *    The `aborted` pre-check is the whole point.
+ * 2. **The listener outlives the request.** A long-lived caller signal (one
+ *    React Query owns for a query's lifetime, say) accumulates one listener per
+ *    attempt per request with nothing ever removing them.
+ * 3. **The reason is dropped**, so the child cannot tell WHY it was aborted.
+ *
+ * `AbortSignal.any` does all this natively and is not used: Hermes support is
+ * not safe to assume, and this SDK ships to React Native. The pattern is the
+ * one `uploadViaXHR` already had right; this is that code, shared.
+ */
+function isAbortLike(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        error.name === 'AbortError');
+}
+function linkAbort(parent, child) {
+    if (parent.aborted) {
+        child.abort(parent.reason);
+        return () => { };
+    }
+    const onAbort = () => {
+        child.abort(parent.reason);
+    };
+    parent.addEventListener('abort', onAbort, { once: true });
+    return () => parent.removeEventListener('abort', onAbort);
+}
 /**
  * Unified HTTP Service
  *
@@ -365,21 +400,59 @@ export class HttpService {
         const csrfToken = isStateChangingMethod && !authHeader ? await this.fetchCsrfToken() : null;
         const edgeRegionHeader = await getBrowserEdgeRegionHeader();
         const activityIdHeader = getBrowserActivityIdHeader();
+        // A request the caller has ALREADY abandoned takes no queue slot and makes
+        // no network call. Checked here, before enqueue, because a slot is the
+        // scarce resource: ten of them, and a dead request holding one is a live
+        // request waiting for nothing.
+        if (signal?.aborted) {
+            throw createCancelledError('Request cancelled before it was sent');
+        }
+        // ONE abort domain for the whole call, linked to the caller's signal ONCE.
+        //
+        // The bug this replaces: the controller used to be built INSIDE `requestFn`
+        // — the function `retryAsync` re-invokes — and the caller's signal was
+        // linked to each new controller with a bare `addEventListener`. An `abort`
+        // event fires once, so on attempt 2 the caller's already-fired signal could
+        // not abort the freshly built controller, and the request the caller had
+        // cancelled went out for real. Hoisting the linkage means a cancellation
+        // arrives once and is then true for every attempt, including ones not yet
+        // started.
+        const callController = new AbortController();
+        const disposeCallerLink = signal ? linkAbort(signal, callController) : undefined;
+        /**
+         * Which of our own timers fired, so a timeout can be told apart from a
+         * cancellation. Both reach us from `fetch` as an indistinguishable
+         * `AbortError`, and collapsing them (as this used to) is what let the retry
+         * predicate treat an abandoned request as a transient failure.
+         */
+        let timedOut = false;
         // Request function
         const requestFn = async () => {
             const startTime = Date.now();
+            // Re-checked per attempt so no retry can issue a network call after the
+            // caller gave up — belt to `retryAsync`'s braces, and the one that holds
+            // if a custom `shouldRetry` ever says yes to a cancellation.
+            if (callController.signal.aborted) {
+                throw createCancelledError('Request cancelled');
+            }
+            // This attempt's controller carries its own timeout and inherits the
+            // call-wide abort domain. Declared OUTSIDE the `try` so the `finally`
+            // that releases them can see them — the timer and the listener are
+            // exactly what leaked when they lived inside it.
+            const controller = new AbortController();
+            const disposeCallLink = linkAbort(callController.signal, controller);
+            const timeoutId = timeout
+                ? setTimeout(() => {
+                    timedOut = true;
+                    controller.abort();
+                }, timeout)
+                : null;
             try {
                 // Build URL with params
                 const fullUrl = this.buildURL(url, params);
                 // Determine if data is FormData using robust detection
                 const isFormData = this.isFormData(data);
                 const isUrlEncoded = this.isUrlSearchParams(data);
-                // Make fetch request
-                const controller = new AbortController();
-                const timeoutId = timeout ? setTimeout(() => controller.abort(), timeout) : null;
-                if (signal) {
-                    signal.addEventListener('abort', () => controller.abort());
-                }
                 // Build headers - start with defaults
                 const headers = {
                     'Accept': 'application/json',
@@ -457,6 +530,8 @@ export class HttpService {
                         signal: controller.signal,
                         credentials: this.getCredentialsMode(fullUrl),
                     });
+                // Cleared as early as possible; the `finally` below is what GUARANTEES
+                // it, including on every throw between here and there.
                 if (timeoutId)
                     clearTimeout(timeoutId);
                 // Handle response
@@ -582,34 +657,82 @@ export class HttpService {
                 this.updateMetrics(false, duration);
                 this.config.onRequestEnd?.(url, method, duration, false);
                 this.config.onRequestError?.(url, method, error instanceof Error ? error : new Error(String(error)));
-                // Handle AbortError specifically for better error messages
-                if (error instanceof Error && error.name === 'AbortError') {
-                    throw handleHttpError(error);
+                // An abort is the one failure whose CAUSE the error cannot carry on its
+                // own: `fetch` reports a caller cancellation and our own timeout as the
+                // same `AbortError`. `timedOut` is set by the timer callback, so it is
+                // the only thing here that knows which happened — and getting this
+                // wrong is not cosmetic. Both used to collapse to `TIMEOUT` with
+                // `status: 0`, and because `status: 0` is not 4xx the retry predicate
+                // read every cancellation as a transient failure worth another try.
+                // Tested by NAME, not `instanceof Error`. `fetch` rejects an abort with a
+                // `DOMException`, and `instanceof` is realm-bound: the exception can be
+                // constructed in a different realm from the `Error` this module closes
+                // over (a Jest VM context, a worker, an iframe), in which case the check
+                // silently fails and the abort is misreported as a generic 500. That was
+                // happening; a structural check cannot be fooled that way.
+                if (isAbortLike(error)) {
+                    if (timedOut) {
+                        const timeoutError = new Error(`Request timed out after ${timeout}ms`);
+                        timeoutError.status = 0;
+                        timeoutError.code = ErrorCodes.TIMEOUT;
+                        timeoutError.timeout = true;
+                        throw timeoutError;
+                    }
+                    throw createCancelledError('Request cancelled');
                 }
                 throw handleHttpError(error);
             }
+            finally {
+                // Both of these leaked before: `clearTimeout` sat on the success path
+                // only, so any throw between the fetch and the return (a 404, a parse
+                // failure) left the timer armed; and nothing ever removed the abort
+                // listener, so a long-lived caller signal collected one per attempt.
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                disposeCallLink();
+            }
         };
-        // Wrap with retry if enabled
+        // Wrap with retry if enabled.
+        //
+        // `retryOnTimeout` defaults to false in `retryAsync`, which is what makes
+        // the pathological total unreachable: a timeout now costs ONE attempt
+        // instead of four-plus-backoff (~28s at the 5s default), and a cancellation
+        // costs none. `deadline` bounds whatever retries do happen by wall clock
+        // rather than by attempts x timeout + backoff.
         const requestWithRetry = retry
-            ? () => retryAsync(requestFn, maxRetries, this.config.retryDelay || 1000)
+            ? () => retryAsync(requestFn, {
+                maxRetries,
+                baseDelay: this.config.retryDelay || 1000,
+                retryOnTimeout: config.retryOnTimeout ?? false,
+                deadline: config.deadline !== undefined ? Date.now() + config.deadline : undefined,
+            })
             : requestFn;
         // Wrap with deduplication if enabled (use optimized key generation)
         const dedupeKey = deduplicate ? this.generateCacheKey(method, url, data || params) : null;
         const finalRequest = dedupeKey
-            ? () => this.deduplicator.deduplicate(dedupeKey, requestWithRetry)
+            ? () => this.deduplicator.deduplicate(dedupeKey, requestWithRetry, callController.signal)
             : requestWithRetry;
-        // Execute the request. Control-plane calls the auth lane depends on
-        // (`bypassQueue`, e.g. the device-secret mint) run DIRECTLY — a queued mint
-        // could never acquire a slot when every slot is parked awaiting it.
-        const result = config.bypassQueue
-            ? await finalRequest()
-            : await this.requestQueue.enqueue(finalRequest);
-        // Cache the result if caching is enabled
-        if (cache && cacheKey && result) {
-            this.cache.set(cacheKey, result, cacheTTL);
-            this.warnIfCacheOversized();
+        try {
+            // Execute the request. Control-plane calls the auth lane depends on
+            // (`bypassQueue`, e.g. the device-secret mint) run DIRECTLY — a queued mint
+            // could never acquire a slot when every slot is parked awaiting it.
+            const result = config.bypassQueue
+                ? await finalRequest()
+                : await this.requestQueue.enqueue(finalRequest, callController.signal);
+            // Cache the result if caching is enabled
+            if (cache && cacheKey && result) {
+                this.cache.set(cacheKey, result, cacheTTL);
+                this.warnIfCacheOversized();
+            }
+            return result;
+        }
+        finally {
+            // The call-wide link to the CALLER's signal, released once the call is
+            // over however it ended. Without this a caller signal that outlives the
+            // request — the normal case for a React Query query signal — accrues one
+            // listener per request for its whole lifetime.
+            disposeCallerLink?.();
         }
-        return result;
     }
     /**
      * Soft cache-size guard. Emits a single throttled telemetry warning when the

package/dist/esm/mixins/OxyServices.user.js

@@ -64,12 +64,19 @@ export function OxyServicesUserMixin(Base) {
         }
         /**
          * 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, pagination) {
+        async searchProfiles(query, pagination, options) {
             try {
                 const response = await this.makeRequest('GET', '/profiles/search', buildQueryParams({ query, ...pagination }), {
                     cache: true,
                     cacheTTL: 2 * 60 * 1000, // 2 minutes cache
+                    signal: options?.signal,
                 });
                 if (typeof response !== 'object' ||
                     response === null ||

package/dist/esm/utils/asyncUtils.js

@@ -2,6 +2,7 @@
  * Async utilities for common asynchronous patterns and error handling
  */
 import { logger } from '../logger/index.js';
+import { ErrorCodes, isCancelledError } from './errorUtils.js';
 /**
  * Wrapper for async operations with automatic error handling
  * Returns null on error instead of throwing
@@ -53,29 +54,55 @@ function extractHttpStatus(error) {
     return undefined;
 }
 /**
- * Retry an async operation with exponential backoff
+ * Whether an error came from a request hitting its own timeout.
  *
- * By default, does not retry on 4xx errors (client errors). The default
- * predicate accepts both the axios-style `error.response.status` and the
- * flat `error.status` shape produced by {@link handleHttpError}, so callers
- * never accidentally retry a deterministic client failure.
- *
- * Use the `shouldRetry` callback to customize retry behavior.
+ * 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.
  */
-export async function retryAsync(operation, maxRetries = 3, baseDelay = 1000, shouldRetry) {
+function isTimeoutError(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const candidate = error;
+    return candidate.timeout === true || candidate.code === ErrorCodes.TIMEOUT;
+}
+export async function retryAsync(operation, maxRetriesOrOptions = 3, baseDelayArg = 1000, shouldRetryArg) {
+    // 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 = 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;
     // Default shouldRetry: don't retry on 4xx errors (client errors).
     // Checks BOTH `error.status` (flat shape from handleHttpError / fetch
     // clients) AND `error.response.status` (axios-style shape) so neither
     // representation can leak a client error into the retry loop.
     const defaultShouldRetry = (error) => {
+        // 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;
         }
         return true;
     };
-    const retryCheck = shouldRetry || defaultShouldRetry;
+    const retryCheck = options.shouldRetry || defaultShouldRetry;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
             return await operation();
@@ -85,11 +112,25 @@ export async function retryAsync(operation, maxRetries = 3, baseDelay = 1000, sh
             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));
         }
     }

package/dist/esm/utils/errorUtils.js

@@ -26,7 +26,20 @@ export const ErrorCodes = {
     TIMEOUT: 'TIMEOUT',
     // 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'
 };
 /**
  * Narrow a caught value to {@link HttpRequestError}.
@@ -96,6 +109,33 @@ export function createApiError(message, code = ErrorCodes.INTERNAL_ERROR, status
         details
     };
 }
+export function createCancelledError(message = 'Request cancelled') {
+    const error = new Error(message);
+    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) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        error.name === 'AbortError');
+}
+export function isCancelledError(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const candidate = error;
+    return (candidate.cancelled === true ||
+        candidate.code === ErrorCodes.CANCELLED ||
+        candidate.name === 'AbortError');
+}
 /**
  * Handle common HTTP errors and convert to ApiError
  */
@@ -112,8 +152,16 @@ export function handleHttpError(error) {
         }
         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, 0);
     }
     // Handle TypeError (network failures, CORS, etc.)

package/dist/esm/utils/requestUtils.js

@@ -3,6 +3,26 @@
  *
  * Provides reusable components for request deduplication, queuing, and logging
  */
+import { createCancelledError } from './errorUtils.js';
+/**
+ * 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) {
+    const reason = signal.reason;
+    const error = createCancelledError('Request cancelled');
+    if (reason !== undefined) {
+        error.cause = reason;
+    }
+    return error;
+}
 /**
  * Request deduplication - prevents duplicate concurrent requests
  *
@@ -29,17 +49,39 @@ export class RequestDeduplicator {
      * @param requestFn Function that returns a promise
      * @returns Promise that will be shared if key already exists
      */
-    async deduplicate(key, requestFn) {
-        const existing = this.pendingRequests.get(key);
-        if (existing) {
-            return existing;
+    async deduplicate(key, requestFn, signal) {
+        if (signal?.aborted) {
+            throw abortReason(signal);
+        }
+        let promise = this.pendingRequests.get(key);
+        if (!promise) {
+            promise = requestFn().finally(() => {
+                this.pendingRequests.delete(key);
+            });
+            this.pendingRequests.set(key, promise);
         }
-        const promise = requestFn()
-            .finally(() => {
-            this.pendingRequests.delete(key);
+        // 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(() => { });
+        return new Promise((resolve, reject) => {
+            const onAbort = () => 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); });
         });
-        this.pendingRequests.set(key, promise);
-        return promise;
     }
     /**
      * Clear all pending requests
@@ -87,20 +129,60 @@ export class RequestQueue {
      * @param requestFn Function that returns a promise
      * @returns Promise that resolves when request completes
      */
-    async enqueue(requestFn) {
+    async enqueue(requestFn, signal) {
         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((resolve, reject) => {
-            this.queue.push(async () => {
+            let settled = false;
+            const finish = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal?.removeEventListener('abort', onAbort);
+                fn();
+            };
+            const entry = async () => {
+                // 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() {
+                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();
         });
     }