@oxy.so/core 1.6.0 → 1.7.0

package/dist/types/HttpService.d.ts

@@ -36,6 +36,25 @@ export interface RequestOptions {
     deduplicate?: boolean;
     retry?: boolean;
     maxRetries?: number;
+    /**
+     * Retry an attempt that hit {@link timeout}. Default `false`.
+     *
+     * Off by default because a timeout usually means the SERVER is slow, so more
+     * attempts add load to the thing already struggling — and because retrying
+     * one behind a short per-attempt timeout is how a single slow endpoint used
+     * to cost ~28s of wall clock. Turn it on for an idempotent read where a
+     * retry is genuinely likely to help, and pair it with {@link deadline}.
+     */
+    retryOnTimeout?: boolean;
+    /**
+     * Wall-clock budget in ms for the WHOLE call, retries and backoff included.
+     *
+     * {@link timeout} bounds one attempt; this bounds the call. Without it the
+     * total is `attempts x timeout + backoff`, which is arithmetic nobody does
+     * at the call site — so a caller who wants "never more than 8 seconds" can
+     * say that instead of deriving it.
+     */
+    deadline?: number;
     timeout?: number;
     signal?: AbortSignal;
     headers?: Record<string, string>;

package/dist/types/mixins/OxyServices.user.d.ts

@@ -127,8 +127,16 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         }>;
         /**
          * Search user profiles
-         */
-        searchProfiles(query: string, pagination?: PaginationParams): Promise<SearchProfilesResponse>;
+         *
+         * 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.
+         */
+        searchProfiles(query: string, pagination?: PaginationParams, options?: {
+            signal?: AbortSignal;
+        }): Promise<SearchProfilesResponse>;
         /**
          * Resolve a fediverse handle to an Oxy user profile.
          * Performs WebFinger discovery and returns the user, or null if not found.

package/dist/types/utils/asyncUtils.d.ts

@@ -20,7 +20,36 @@ export declare function parallelWithErrorHandling<T>(operations: (() => Promise<
  *
  * Use the `shouldRetry` callback to customize retry behavior.
  */
-export declare function retryAsync<T>(operation: () => Promise<T>, maxRetries?: number, baseDelay?: number, shouldRetry?: (error: any) => boolean): Promise<T>;
+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;
+}
+export declare function retryAsync<T>(operation: () => Promise<T>, maxRetriesOrOptions?: number | RetryOptions, baseDelayArg?: number, shouldRetryArg?: (error: any) => boolean): Promise<T>;
 /**
  * Debounce async function calls
  */

package/dist/types/utils/errorUtils.d.ts

@@ -22,6 +22,19 @@ export declare const ErrorCodes: {
     readonly TIMEOUT: "TIMEOUT";
     readonly NETWORK_ERROR: "NETWORK_ERROR";
     readonly 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.
+     */
+    readonly CANCELLED: "CANCELLED";
 };
 /**
  * The `Error` shape the SDK rejects with when an HTTP request fails.
@@ -94,6 +107,29 @@ export declare function parseHttpErrorBody(body: unknown): ParsedHttpErrorBody;
  * Create a standardized API error
  */
 export declare function createApiError(message: string, code?: string, status?: number, details?: Record<string, unknown>): ApiError;
+/**
+ * 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 declare function createCancelledError(message?: string): CancelledError;
+export declare function isCancelledError(error: unknown): boolean;
 /**
  * Handle common HTTP errors and convert to ApiError
  */

package/dist/types/utils/requestUtils.d.ts

@@ -27,7 +27,7 @@ export declare class RequestDeduplicator {
      * @param requestFn Function that returns a promise
      * @returns Promise that will be shared if key already exists
      */
-    deduplicate<T>(key: string, requestFn: () => Promise<T>): Promise<T>;
+    deduplicate<T>(key: string, requestFn: () => Promise<T>, signal?: AbortSignal): Promise<T>;
     /**
      * Clear all pending requests
      */
@@ -69,7 +69,7 @@ export declare class RequestQueue {
      * @param requestFn Function that returns a promise
      * @returns Promise that resolves when request completes
      */
-    enqueue<T>(requestFn: () => Promise<T>): Promise<T>;
+    enqueue<T>(requestFn: () => Promise<T>, signal?: AbortSignal): Promise<T>;
     /**
      * Process queued requests
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -118,7 +118,7 @@
     "@oxy.so/telemetry": "^1.1.1",
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxy.so/contracts": "^1.2.0",
+    "@oxy.so/contracts": "^1.3.0",
     "@oxy.so/protocol": "^1.0.1",
     "@scure/bip39": "^1.6.0",
     "buffer": "^6.0.3",

package/src/HttpService.ts

@@ -16,7 +16,7 @@
 import { TTLCache, registerCacheForCleanup } from './utils/cache';
 import { RequestDeduplicator, RequestQueue, SimpleLogger } from './utils/requestUtils';
 import { retryAsync } from './utils/asyncUtils';
-import { handleHttpError, parseHttpErrorBody } from './utils/errorUtils';
+import { createCancelledError, ErrorCodes, handleHttpError, isCancelledError, parseHttpErrorBody } from './utils/errorUtils';
 import { jwtDecode } from 'jwt-decode';
 import { isNative, getPlatformOS } from './utils/platform';
 import { isReactNative } from '@oxy.so/protocol';
@@ -85,6 +85,25 @@ export interface RequestOptions {
   deduplicate?: boolean;
   retry?: boolean;
   maxRetries?: number;
+  /**
+   * Retry an attempt that hit {@link timeout}. Default `false`.
+   *
+   * Off by default because a timeout usually means the SERVER is slow, so more
+   * attempts add load to the thing already struggling — and because retrying
+   * one behind a short per-attempt timeout is how a single slow endpoint used
+   * to cost ~28s of wall clock. Turn it on for an idempotent read where a
+   * retry is genuinely likely to help, and pair it with {@link deadline}.
+   */
+  retryOnTimeout?: boolean;
+  /**
+   * Wall-clock budget in ms for the WHOLE call, retries and backoff included.
+   *
+   * {@link timeout} bounds one attempt; this bounds the call. Without it the
+   * total is `attempts x timeout + backoff`, which is arithmetic nobody does
+   * at the call site — so a caller who wants "never more than 8 seconds" can
+   * say that instead of deriving it.
+   */
+  deadline?: number;
   timeout?: number;
   signal?: AbortSignal;
   headers?: Record<string, string>;
@@ -288,9 +307,48 @@ class TokenStore {
   }
 }
 
+/**
+ * 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: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    (error as { name?: unknown }).name === 'AbortError'
+  );
+}
+
+function linkAbort(parent: AbortSignal, child: AbortController): () => void {
+  if (parent.aborted) {
+    child.abort((parent as AbortSignal & { reason?: unknown }).reason);
+    return () => { /* nothing was ever attached */ };
+  }
+  const onAbort = (): void => {
+    child.abort((parent as AbortSignal & { reason?: unknown }).reason);
+  };
+  parent.addEventListener('abort', onAbort, { once: true });
+  return () => parent.removeEventListener('abort', onAbort);
+}
+
 /**
  * Unified HTTP Service
- * 
+ *
  * Consolidates HttpClient + RequestManager into a single efficient class.
  * Uses native fetch instead of axios for smaller bundle size.
  */
@@ -543,9 +601,58 @@ export class HttpService {
     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 (): Promise<T> => {
       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);
@@ -554,14 +661,6 @@ export class HttpService {
         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: Record<string, string> = {
           'Accept': 'application/json',
@@ -657,6 +756,8 @@ export class HttpService {
               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
@@ -787,41 +888,90 @@ 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`) as Error & {
+              status?: number;
+              code?: string;
+              timeout?: boolean;
+            };
+            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;
+      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?.();
+    }
   }
 
   /**