@oxy.so/core 1.0.0

package/src/utils/errorUtils.ts

@@ -0,0 +1,352 @@
+import type { ApiError } from '../models/interfaces';
+import { logger } from '../logger';
+
+/**
+ * Error handling utilities for consistent error processing
+ */
+
+/**
+ * Common error codes
+ */
+export const ErrorCodes = {
+  // Authentication errors
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  INVALID_TOKEN: 'INVALID_TOKEN',
+  MISSING_TOKEN: 'MISSING_TOKEN',
+  
+  // Validation errors
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  BAD_REQUEST: 'BAD_REQUEST',
+  MISSING_PARAMETER: 'MISSING_PARAMETER',
+  INVALID_FORMAT: 'INVALID_FORMAT',
+  
+  // Resource errors
+  NOT_FOUND: 'NOT_FOUND',
+  ALREADY_EXISTS: 'ALREADY_EXISTS',
+  CONFLICT: 'CONFLICT',
+  
+  // Server errors
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
+  TIMEOUT: 'TIMEOUT',
+  
+  // Network errors
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  CONNECTION_FAILED: 'CONNECTION_FAILED'
+} as const;
+
+/**
+ * The `Error` shape the SDK rejects with when an HTTP request fails.
+ *
+ * `HttpService` throws this for every non-2xx response, and
+ * `OxyServices.handleError` (the wrapper the mixin methods rethrow through)
+ * preserves `message`, `status`, `code` and `details`. `response` only survives
+ * on the raw `HttpService`/`makeRequest` path, so treat it as optional.
+ *
+ * Narrow a caught value with {@link isHttpRequestError} instead of asserting.
+ */
+export interface HttpRequestError extends Error {
+    /** HTTP status of the failed response. */
+    status: number;
+    /** Machine-readable code the server sent, when it sent one. */
+    code?: string;
+    /** Structured error detail the server sent, when it sent an object. */
+    details?: Record<string, unknown>;
+    /**
+     * Present on errors thrown directly by `HttpService`. `data` is the parsed
+     * JSON error body verbatim — the escape hatch for any server field the SDK
+     * does not lift onto `code`/`details`.
+     */
+    response?: {
+        status: number;
+        statusText: string;
+        data?: unknown;
+    };
+}
+
+/**
+ * Narrow a caught value to {@link HttpRequestError}.
+ *
+ * Returns `false` for a plain {@link ApiError} object (those are objects, not
+ * `Error`s) — run an arbitrary thrown value through {@link handleHttpError}
+ * first if you need one normalized.
+ */
+export function isHttpRequestError(value: unknown): value is HttpRequestError {
+    if (!(value instanceof Error)) {
+        return false;
+    }
+    return typeof (value as Partial<HttpRequestError>).status === 'number';
+}
+
+/**
+ * The fields {@link parseHttpErrorBody} lifts off a parsed error response body.
+ */
+export interface ParsedHttpErrorBody {
+    message?: string;
+    code?: string;
+    details?: Record<string, unknown>;
+}
+
+const isPlainRecord = (value: unknown): value is Record<string, unknown> =>
+    typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const nonEmptyString = (value: unknown): string | undefined =>
+    typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+
+/**
+ * Extract `message` / `code` / `details` from a parsed HTTP error response body.
+ *
+ * Handles every error envelope in use across the Oxy ecosystem:
+ *
+ * - `{ error: { code, message, details? } }` — nested envelope (CrowdSource and
+ *   other Oxy services). Never stringify the nested object: `new Error(obj)`
+ *   yields the literal message `"[object Object]"`.
+ * - `{ error: '<CODE>', message, details? }` — oxy-api's canonical shape
+ *   (`ApiError.toJSON`), where the top-level `error` field IS the code.
+ * - `{ error: '<CODE>', error_description }` — RFC 6749 §5.2 / RFC 6750 §3, the
+ *   OAuth token and userinfo endpoints. `error_description` is the human text
+ *   and `error` is the machine code, so both survive.
+ * - `{ message, code }` — e.g. the API's CSRF rejections.
+ * - `{ error: '<human message>' }` — legacy hand-rolled routes. With no sibling
+ *   `message`/`error_description` the string is the message, not a code: a bare
+ *   `error` string is not machine-readable enough to promote to `code`.
+ *
+ * Anything else — a non-object body (`null`, `[]`, `"str"`, `42`), or an object
+ * carrying none of these fields — yields an empty result, leaving the caller on
+ * its status-based fallback message. Total function: never throws.
+ */
+export function parseHttpErrorBody(body: unknown): ParsedHttpErrorBody {
+    if (!isPlainRecord(body)) {
+        return {};
+    }
+
+    const nested = isPlainRecord(body.error) ? body.error : undefined;
+    const errorString = nonEmptyString(body.error);
+    // A sibling that proves the top-level `error` is a CODE rather than prose.
+    const siblingMessage = nonEmptyString(body.message) ?? nonEmptyString(body.error_description);
+
+    return {
+        message: siblingMessage ?? (nested ? nonEmptyString(nested.message) : errorString),
+        code:
+            (nested ? nonEmptyString(nested.code) : undefined) ??
+            nonEmptyString(body.code) ??
+            (siblingMessage ? errorString : undefined),
+        details: isPlainRecord(body.details)
+            ? body.details
+            : nested && isPlainRecord(nested.details)
+                ? nested.details
+                : undefined,
+    };
+}
+
+/**
+ * Create a standardized API error
+ */
+export function createApiError(
+  message: string,
+  code: string = ErrorCodes.INTERNAL_ERROR,
+  status = 500,
+  details?: Record<string, unknown>
+): ApiError {
+  return {
+    message,
+    code,
+    status,
+    details
+  };
+}
+
+/**
+ * Handle common HTTP errors and convert to ApiError
+ */
+export function handleHttpError(error: unknown): ApiError {
+  // If it's already an ApiError, ensure it has a non-empty message
+  if (error && typeof error === 'object' && 'code' in error && 'status' in error) {
+    const apiError = error as ApiError;
+    // Ensure message is not empty
+    if (!apiError.message || !apiError.message.trim()) {
+      return {
+        ...apiError,
+        message: apiError.message || 'An error occurred',
+      };
+    }
+    return apiError;
+  }
+
+  // Handle AbortError (timeout or cancelled requests)
+  if (error instanceof Error && error.name === 'AbortError') {
+    return createApiError(
+      'Request timeout or cancelled',
+      ErrorCodes.TIMEOUT,
+      0
+    );
+  }
+
+  // Handle TypeError (network failures, CORS, etc.)
+  if (error instanceof TypeError) {
+    // Check if it's a network-related TypeError
+    if (error.message.includes('fetch') || error.message.includes('network') || error.message.includes('Failed to fetch')) {
+      return createApiError(
+        'Network error - failed to connect to server',
+        ErrorCodes.NETWORK_ERROR,
+        0
+      );
+    }
+    return createApiError(
+      error.message || 'Network error occurred',
+      ErrorCodes.NETWORK_ERROR,
+      0
+    );
+  }
+
+  // Handle fetch Response errors - check if it has response property with status
+  if (error && typeof error === 'object' && 'response' in error) {
+    const fetchError = error as {
+      response?: {
+        status: number;
+        statusText?: string;
+      };
+      status?: number;
+      message?: string;
+      details?: unknown;
+    };
+
+    const status = fetchError.response?.status || fetchError.status;
+    if (status) {
+      // `details` is carried through when present: a body may ship structured
+      // detail without a machine-readable `code` (which is what routes the
+      // error to the already-an-ApiError branch above), and dropping it here
+      // would make it unreachable to every caller that rethrows via
+      // `OxyServices.handleError`.
+      return createApiError(
+        fetchError.message || `HTTP ${status} error`,
+        getErrorCodeFromStatus(status),
+        status,
+        isPlainRecord(fetchError.details) ? fetchError.details : undefined
+      );
+    }
+  }
+
+  // Handle standard errors
+  if (error instanceof Error) {
+    // Check for common error patterns
+    if (error.message.includes('timeout') || error.message.includes('aborted')) {
+      return createApiError(
+        'Request timeout',
+        ErrorCodes.TIMEOUT,
+        0
+      );
+    }
+    
+    if (error.message.includes('network') || error.message.includes('fetch')) {
+      return createApiError(
+        error.message || 'Network error occurred',
+        ErrorCodes.NETWORK_ERROR,
+        0
+      );
+    }
+
+    return createApiError(
+      error.message || 'Unknown error occurred',
+      ErrorCodes.INTERNAL_ERROR,
+      500
+    );
+  }
+
+  // Handle other errors - ensure we always return a non-empty message
+  const errorString = error ? String(error) : '';
+  const message = errorString.trim() || 'Unknown error occurred';
+  return createApiError(
+    message,
+    ErrorCodes.INTERNAL_ERROR,
+    500
+  );
+}
+
+/**
+ * Get error code from HTTP status
+ * Exported for use in other modules
+ */
+export function getErrorCodeFromStatus(status: number): string {
+  switch (status) {
+    case 400:
+      return ErrorCodes.BAD_REQUEST;
+    case 401:
+      return ErrorCodes.UNAUTHORIZED;
+    case 403:
+      return ErrorCodes.FORBIDDEN;
+    case 404:
+      return ErrorCodes.NOT_FOUND;
+    case 409:
+      return ErrorCodes.CONFLICT;
+    case 422:
+      return ErrorCodes.VALIDATION_ERROR;
+    case 500:
+      return ErrorCodes.INTERNAL_ERROR;
+    case 503:
+      return ErrorCodes.SERVICE_UNAVAILABLE;
+    default:
+      return ErrorCodes.INTERNAL_ERROR;
+  }
+}
+
+/**
+ * Best-effort extraction of an HTTP status code from a thrown value.
+ *
+ * `HttpService` annotates the errors it throws with both `error.status` and
+ * `error.response.status`; an already-normalized {@link ApiError} carries
+ * `error.status`. This reads either, returning `undefined` when the value is
+ * not an object or carries no numeric status (e.g. a thrown string, a network
+ * `TypeError`). Used by discovery/read paths to distinguish a 404 "not found"
+ * from a transport/server failure for observability without re-deriving the
+ * narrowing at every call site.
+ */
+export function extractErrorStatus(error: unknown): number | undefined {
+  if (!error || typeof error !== 'object') {
+    return undefined;
+  }
+  const record = error as { status?: unknown; response?: { status?: unknown } };
+  if (typeof record.status === 'number') {
+    return record.status;
+  }
+  if (typeof record.response?.status === 'number') {
+    return record.response.status;
+  }
+  return undefined;
+}
+
+/**
+ * Validate required fields and throw error if missing
+ */
+export function validateRequiredFields(data: Record<string, unknown>, fields: string[]): void {
+  const missing = fields.filter(field => !data[field]);
+  
+  if (missing.length > 0) {
+    throw createApiError(
+      `Missing required fields: ${missing.join(', ')}`,
+      ErrorCodes.MISSING_PARAMETER,
+      400
+    );
+  }
+}
+
+/**
+ * Safe error logging with context
+ */
+export function logError(error: unknown, context?: string): void {
+  if (error instanceof Error) {
+    logger.error(error.message, {
+      component: context || 'errorUtils',
+      method: 'logError',
+      stack: error.stack,
+    });
+  } else {
+    logger.error(String(error), {
+      component: context || 'errorUtils',
+      method: 'logError',
+    });
+  }
+}
+
+ 

package/src/utils/identityCacheSweep.ts

@@ -0,0 +1,104 @@
+/**
+ * THE enumeration of `OxyServices` GET-cache keys that can carry a single
+ * account's identity, and the one sweep that clears them.
+ *
+ * WHY THIS IS ONE LIST
+ * --------------------
+ * An Oxy account is readable under SEVERAL cache keys, and a write that only
+ * busts the key it happens to know about leaves every other one serving the
+ * pre-write snapshot for up to its TTL — from the caller's OWN in-memory cache,
+ * with a perfectly healthy server. That failure has already shipped twice with
+ * two different sets of keys:
+ *
+ *   - `updateAccount` busted `GET:/accounts/<id>` and the account lists, but a
+ *     profile screen reads `GET:/profiles/username/<name>` and
+ *     `GET:/users/<id>`, so a channel's new picture stayed invisible for the
+ *     full 5-minute profile TTL.
+ *   - `updateProfile` busted four of the six keys below, missing
+ *     `GET:/auth/lookup/` (the login-flow avatar/display-name lookup) and
+ *     `GET:/profiles/resolve` (handle resolution) — two independently-drifted
+ *     copies of a list that has to agree.
+ *
+ * So the list lives here, once, and every writer calls
+ * {@link evictOxyIdentityCache}. Adding a new identity read means adding its key
+ * HERE and every writer inherits it.
+ *
+ * WHERE THE LINE IS DRAWN
+ * -----------------------
+ * These are the SINGLE-PROFILE reads — the account is the subject of the
+ * response and is addressable by id, handle, or session. Reads that merely
+ * CONTAIN an account among many (`GET:/profiles/search`,
+ * `GET:/users/<other>/followers`, `GET:/profiles/<other>/similar`) are
+ * deliberately NOT swept: an account cannot be located in them without the very
+ * lookup being invalidated, so sweeping them means sweeping the whole namespace
+ * on every identity change — a real cost on a backend consuming the
+ * cross-service invalidation signal, for a surface where a stale thumbnail
+ * expires on its own in ~2 minutes.
+ *
+ * WHY PREFIXES RATHER THAN EXACT KEYS
+ * -----------------------------------
+ * Only the by-id key can be built from a user id. The handle-keyed and
+ * session-keyed entries cannot — deriving a handle from an id needs the lookup
+ * we are invalidating, and the SDK never tracks active session ids centrally.
+ * Prefix sweeping is also what makes a USERNAME CHANGE correct: the entry under
+ * the OLD handle is unreachable by construction (nothing in the write response
+ * carries it), and a sweep targeted at the new handle alone would leave the old
+ * one serving the pre-rename profile until its TTL. Over-eviction costs a
+ * refetch; under-eviction serves wrong data.
+ *
+ * Platform-neutral by construction (no imports, no `OxyServices` reference) so
+ * the client mixins and the Node-only `@oxy.so/core/server` invalidation
+ * subscriber can share it without either pulling in the other.
+ */
+
+/**
+ * The cache-eviction surface of an `OxyServices` instance. Declared
+ * structurally so this module stays free of any client import.
+ */
+export interface OxyIdentityCacheEvictor {
+  clearCacheEntry(key: string): void;
+  clearCacheByPrefix(prefix: string): number;
+}
+
+/**
+ * Cache-key PREFIXES under which an account's identity can be served, for the
+ * reads whose key cannot be derived from a user id. Swept wholesale.
+ */
+export const OXY_IDENTITY_CACHE_PREFIXES: readonly string[] = [
+  // `getUserBySession` — keyed by session id, which the SDK never enumerates.
+  'GET:/session/user/',
+  // `getCurrentUser` (and `GET:/users/me/graph`, harmlessly included).
+  'GET:/users/me',
+  // `lookupUsername` — the pre-session login lookup; carries avatar + display name.
+  'GET:/auth/lookup/',
+  // `getProfileByUsername` — keyed by handle, including the pre-rename handle.
+  'GET:/profiles/username/',
+  // `resolveProfile` — keyed by fediverse handle in the query payload.
+  'GET:/profiles/resolve',
+];
+
+/**
+ * Build the exact cache key `getUserById` reads under. The only identity key
+ * derivable from a user id, so the only one that does not need a prefix sweep.
+ */
+export function oxyUserByIdCacheKey(userId: string): string {
+  return `GET:/users/${userId}`;
+}
+
+/**
+ * Sweep an `OxyServices` GET response cache of everything that could carry the
+ * given account's identity.
+ *
+ * @param oxy    - Anything exposing the SDK's two eviction methods.
+ * @param userId - The account whose by-id entry to drop. Optional: a caller
+ *                 that does not know the id still clears every handle-, session-
+ *                 and self-keyed entry, which is the majority of the surface.
+ */
+export function evictOxyIdentityCache(oxy: OxyIdentityCacheEvictor, userId?: string): void {
+  for (const prefix of OXY_IDENTITY_CACHE_PREFIXES) {
+    oxy.clearCacheByPrefix(prefix);
+  }
+  if (userId) {
+    oxy.clearCacheEntry(oxyUserByIdCacheKey(userId));
+  }
+}