@oxy.so/core 1.18.0 → 3.0.0

package/src/__tests__/httpServiceCache.test.ts

@@ -1,318 +0,0 @@
-/**
- * HttpService response-cache identity-scoping tests.
- *
- * Regression coverage for the "Who to follow" bug: the GET-response cache used
- * to key on only `method:url[:data]`, so an anonymous response cached during a
- * web cold boot (session still restoring) was served back to the SAME URL once
- * the session landed (now authenticated) — recommending accounts the user
- * already follows. These tests pin down that:
- *
- *  - an anonymous GET response is NOT served to a later authenticated GET of
- *    the same URL (different identity tag -> cache miss -> a fresh network call),
- *  - two different authenticated users never share a cache entry,
- *  - after `clearTokens()` a previously-cached authenticated response is not
- *    served to an anonymous caller,
- *  - the `clearCacheByPrefix` invalidation used by `updateProfile` still works
- *    against identity-scoped keys.
- */
-
-import { HttpService } from '../HttpService';
-
-/**
- * Build a non-verified JWT whose payload decodes to the given claims.
- * `jwtDecode` only base64url-decodes the middle segment (no signature check),
- * so a fixed header + base64url(JSON) payload + dummy signature is enough.
- */
-function makeJwt(payload: Record<string, unknown>): string {
-  const b64url = (obj: Record<string, unknown>): string =>
-    Buffer.from(JSON.stringify(obj)).toString('base64url');
-  // Far-future expiry so getAuthHeader() never tries to refresh it.
-  const fullPayload = { exp: Math.floor(Date.now() / 1000) + 3600, ...payload };
-  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url(fullPayload)}.sig`;
-}
-
-/** A JSON `Response` mimicking the API's `{ data: ... }` success envelope. */
-function jsonResponse(data: unknown): Response {
-  return new Response(JSON.stringify({ data }), {
-    status: 200,
-    headers: { 'content-type': 'application/json' },
-  });
-}
-
-describe('HttpService identity-scoped response cache', () => {
-  let originalFetch: typeof globalThis.fetch;
-  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
-
-  const newService = (): HttpService =>
-    new HttpService({
-      baseURL: 'http://test.invalid',
-      enableRetry: false,
-      requestTimeout: 1000,
-    });
-
-  beforeEach(() => {
-    originalFetch = globalThis.fetch;
-    fetchMock = jest.fn();
-    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
-  });
-
-  afterEach(() => {
-    globalThis.fetch = originalFetch;
-    jest.clearAllMocks();
-  });
-
-  it('does NOT serve an anonymous cached GET to a later authenticated caller', async () => {
-    const http = newService();
-
-    // 1) Anonymous GET — caches the public response.
-    fetchMock.mockResolvedValueOnce(jsonResponse({ profiles: ['popular-1', 'popular-2'] }));
-    const anon = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
-    expect(anon.profiles).toEqual(['popular-1', 'popular-2']);
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-
-    // 2) Session lands — now authenticated as user-1.
-    http.setTokens(makeJwt({ userId: 'user-1' }));
-
-    // 3) Same URL, authenticated: MUST be a cache miss -> a real network call,
-    //    returning the personalized list (no already-followed accounts).
-    fetchMock.mockResolvedValueOnce(jsonResponse({ profiles: ['suggested-a', 'suggested-b'] }));
-    const authed = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
-
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(authed.profiles).toEqual(['suggested-a', 'suggested-b']);
-  });
-
-  it('serves a warm cache hit to the SAME authenticated identity (no extra network call)', async () => {
-    const http = newService();
-    http.setTokens(makeJwt({ userId: 'user-1' }));
-
-    fetchMock.mockResolvedValueOnce(jsonResponse({ profiles: ['suggested-a'] }));
-    const first = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
-    const second = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
-
-    expect(first).toEqual(second);
-    // Only one network call — the second read is a cache hit for the same id.
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-  });
-
-  it('never shares a cache entry between two different authenticated users', async () => {
-    const http = newService();
-
-    http.setTokens(makeJwt({ userId: 'user-1' }));
-    fetchMock.mockResolvedValueOnce(jsonResponse({ profiles: ['for-user-1'] }));
-    const u1 = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
-    expect(u1.profiles).toEqual(['for-user-1']);
-
-    // Switch identity to a different user (does not clear cache by itself).
-    http.setTokens(makeJwt({ userId: 'user-2' }));
-    fetchMock.mockResolvedValueOnce(jsonResponse({ profiles: ['for-user-2'] }));
-    const u2 = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
-
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(u2.profiles).toEqual(['for-user-2']);
-  });
-
-  it('does NOT serve an authenticated cached response to an anonymous caller after clearTokens()', async () => {
-    const http = newService();
-    http.setTokens(makeJwt({ userId: 'user-1' }));
-
-    fetchMock.mockResolvedValueOnce(jsonResponse({ profiles: ['private-suggestion'] }));
-    const authed = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
-    expect(authed.profiles).toEqual(['private-suggestion']);
-
-    // Logout clears the response cache (privacy + correct logout semantics).
-    http.clearTokens();
-
-    fetchMock.mockResolvedValueOnce(jsonResponse({ profiles: ['popular-public'] }));
-    const anon = await http.get<{ profiles: string[] }>('/profiles/recommendations', { cache: true });
-
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(anon.profiles).toEqual(['popular-public']);
-  });
-
-  it('still honors clearCacheByPrefix against identity-scoped keys (updateProfile path)', async () => {
-    const http = newService();
-    http.setTokens(makeJwt({ userId: 'user-1' }));
-
-    // Warm a `GET:/session/user/<id>` entry (as updateProfile's prefix targets).
-    fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-1', name: 'old' }));
-    await http.get('/session/user/sess-1', { cache: true });
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-
-    // A cache hit confirms the entry is warm.
-    await http.get('/session/user/sess-1', { cache: true });
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-
-    // Prefix sweep used by updateProfile must match the identity-scoped key.
-    const removed = http.clearCacheByPrefix('GET:/session/user/');
-    expect(removed).toBe(1);
-
-    // Next read re-fetches (cache was invalidated).
-    fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-1', name: 'new' }));
-    const after = await http.get<{ id: string; name: string }>('/session/user/sess-1', { cache: true });
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(after.name).toBe('new');
-  });
-
-  it('clearCacheEntry busts every identity-scoped variant of a base key', async () => {
-    const http = newService();
-
-    // Anonymous reads /users/u1.
-    fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'u1', name: 'anon-view' }));
-    await http.get('/users/u1', { cache: true });
-
-    // Authenticated user reads the same resource — separate cache entry.
-    http.setTokens(makeJwt({ userId: 'user-1' }));
-    fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'u1', name: 'authed-view' }));
-    await http.get('/users/u1', { cache: true });
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-
-    // updateProfile-style exact invalidation must clear BOTH identity variants.
-    http.clearCacheEntry('GET:/users/u1');
-
-    // Both identities now re-fetch.
-    http.setTokens(makeJwt({ userId: 'user-1' }));
-    fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'u1', name: 'refetched' }));
-    await http.get('/users/u1', { cache: true });
-    expect(fetchMock).toHaveBeenCalledTimes(3);
-  });
-
-  /**
-   * The soft cache-size guard is observability-only: it must warn (once,
-   * throttled) when the entry count blows past the soft ceiling, but must NEVER
-   * evict a live entry. We synthesize bloat by giving every request a distinct
-   * undecodable token, so each write mints a fresh identity tag → a fresh key.
-   */
-  describe('soft cache-size telemetry guard', () => {
-    /** Number of distinct cached entries needed to cross the 500 soft ceiling. */
-    const ENTRIES_PAST_LIMIT = 520;
-
-    const newLoggingService = (): HttpService =>
-      new HttpService({
-        baseURL: 'http://test.invalid',
-        enableRetry: false,
-        requestTimeout: 1000,
-        enableLogging: true,
-        logLevel: 'warn',
-      });
-
-    let warnSpy: jest.SpyInstance;
-    beforeEach(() => {
-      // SimpleLogger routes `warn` to console.warn; spy there to assert telemetry.
-      warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
-    });
-    afterEach(() => {
-      warnSpy.mockRestore();
-    });
-
-    it('warns (throttled) once the cache exceeds the soft entry limit and never evicts', async () => {
-      const http = newLoggingService();
-
-      // Each iteration: a fresh undecodable token → fresh identity tag → fresh
-      // key, so the cache grows by one live entry per call.
-      for (let i = 0; i < ENTRIES_PAST_LIMIT; i++) {
-        http.setTokens(`undecodable-token-${i}`);
-        fetchMock.mockResolvedValueOnce(jsonResponse({ i }));
-        await http.get('/profiles/recommendations', { cache: true });
-      }
-
-      // No eviction: every distinct entry is still resident.
-      expect(http.getCacheStats().size).toBe(ENTRIES_PAST_LIMIT);
-
-      // Telemetry fired, and exactly once within the throttle window.
-      const cacheWarnings = warnSpy.mock.calls.filter((args) =>
-        args.some(
-          (a: unknown) =>
-            typeof a === 'string' && a.includes('exceeded soft entry limit'),
-        ),
-      );
-      expect(cacheWarnings.length).toBe(1);
-    });
-
-    it('does not warn while the cache stays under the soft limit', async () => {
-      const http = newLoggingService();
-
-      for (let i = 0; i < 10; i++) {
-        http.setTokens(`undecodable-token-${i}`);
-        fetchMock.mockResolvedValueOnce(jsonResponse({ i }));
-        await http.get('/profiles/recommendations', { cache: true });
-      }
-
-      const cacheWarnings = warnSpy.mock.calls.filter((args) =>
-        args.some(
-          (a: unknown) =>
-            typeof a === 'string' && a.includes('exceeded soft entry limit'),
-        ),
-      );
-      expect(cacheWarnings.length).toBe(0);
-    });
-  });
-
-  /**
-   * `enableCache: false` (or `cacheTTL <= 0`) must fully disable the
-   * per-instance GET response cache: every read hits the network, even when the
-   * per-request `cache: true` flag is set. This is the lever Mention's linked
-   * backend client uses to make React Query the single cache authority and
-   * avoid stale-after-write reads from the SDK's own cache. Default behavior
-   * (config unset) is unchanged — caching stays ON.
-   */
-  describe('per-instance cache disable', () => {
-    it('never serves a cached GET when enableCache is false', async () => {
-      const http = new HttpService({
-        baseURL: 'http://test.invalid',
-        enableRetry: false,
-        requestTimeout: 1000,
-        enableCache: false,
-      });
-      http.setTokens(makeJwt({ userId: 'user-1' }));
-
-      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 1 }));
-      const first = await http.get<{ v: number }>('/some/resource', { cache: true });
-      expect(first.v).toBe(1);
-      expect(fetchMock).toHaveBeenCalledTimes(1);
-
-      // A second identical read with cache:true must STILL hit the network,
-      // because the instance cache is disabled. Nothing is ever stored.
-      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 2 }));
-      const second = await http.get<{ v: number }>('/some/resource', { cache: true });
-      expect(second.v).toBe(2);
-      expect(fetchMock).toHaveBeenCalledTimes(2);
-      expect(http.getCacheStats().size).toBe(0);
-    });
-
-    it('treats cacheTTL <= 0 as a disabled cache', async () => {
-      const http = new HttpService({
-        baseURL: 'http://test.invalid',
-        enableRetry: false,
-        requestTimeout: 1000,
-        cacheTTL: 0,
-      });
-      http.setTokens(makeJwt({ userId: 'user-1' }));
-
-      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 1 }));
-      await http.get('/some/resource', { cache: true });
-      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 2 }));
-      await http.get('/some/resource', { cache: true });
-
-      expect(fetchMock).toHaveBeenCalledTimes(2);
-      expect(http.getCacheStats().size).toBe(0);
-    });
-
-    it('still caches by default (config unset) — no behavior change', async () => {
-      const http = new HttpService({
-        baseURL: 'http://test.invalid',
-        enableRetry: false,
-        requestTimeout: 1000,
-      });
-      http.setTokens(makeJwt({ userId: 'user-1' }));
-
-      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 1 }));
-      const first = await http.get<{ v: number }>('/some/resource', { cache: true });
-      // Second read is a warm cache hit — no second network call.
-      const second = await http.get<{ v: number }>('/some/resource', { cache: true });
-
-      expect(first).toEqual(second);
-      expect(fetchMock).toHaveBeenCalledTimes(1);
-    });
-  });
-});

package/src/__tests__/httpServiceFormEncoded.test.ts

@@ -1,139 +0,0 @@
-/**
- * `application/x-www-form-urlencoded` request bodies.
- *
- * Needed because a few endpoints are defined by a standard that fixes their
- * request encoding instead of by our JSON conventions — `POST /auth/oauth/token`
- * (RFC 6749 §4.1.3) is the first. Before this path existed, a `URLSearchParams`
- * payload fell through to `JSON.stringify`, which serialises it to `"{}"`: the
- * request left with an empty body and a JSON content type, and the server saw
- * no parameters at all. That silent failure is what these tests prevent.
- */
-
-import { HttpService } from '../HttpService';
-
-interface FetchCall {
-  url: string;
-  init: RequestInit | undefined;
-}
-
-function jsonResponse(data: unknown): Response {
-  return new Response(JSON.stringify(data), {
-    status: 200,
-    headers: { 'content-type': 'application/json' },
-  });
-}
-
-function readHeaders(init: RequestInit | undefined): Record<string, string> {
-  const headers = init?.headers;
-  if (!headers) {
-    return {};
-  }
-  if (headers instanceof Headers) {
-    return Object.fromEntries(headers.entries());
-  }
-  if (Array.isArray(headers)) {
-    return Object.fromEntries(headers);
-  }
-  return headers as Record<string, string>;
-}
-
-describe('HttpService form-urlencoded bodies', () => {
-  const originalFetch = globalThis.fetch;
-
-  afterEach(() => {
-    globalThis.fetch = originalFetch;
-    jest.restoreAllMocks();
-  });
-
-  /**
-   * POST a form body and return the token-endpoint call. Selected by URL so
-   * any preflight a future change adds cannot shift the call under test.
-   */
-  async function postForm(body: URLSearchParams): Promise<FetchCall> {
-    const calls: FetchCall[] = [];
-    globalThis.fetch = async (input, init) => {
-      calls.push({ url: String(input), init });
-      return jsonResponse({ ok: true });
-    };
-
-    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
-    await http.post('/auth/oauth/token', body, { skipAuth: true, cache: false });
-
-    const tokenCalls = calls.filter((call) => call.url.endsWith('/auth/oauth/token'));
-    expect(tokenCalls).toHaveLength(1);
-    return tokenCalls[0];
-  }
-
-  it('serialises URLSearchParams into the request body', async () => {
-    const call = await postForm(
-      new URLSearchParams({
-        grant_type: 'authorization_code',
-        code: 'code-1',
-        redirect_uri: 'https://app.example/callback',
-      }),
-    );
-
-    // Not `"{}"` — the actual encoded parameters.
-    expect(call.init?.body).toBe(
-      'grant_type=authorization_code&code=code-1&redirect_uri=https%3A%2F%2Fapp.example%2Fcallback',
-    );
-  });
-
-  it('declares the form content type instead of application/json', async () => {
-    const call = await postForm(new URLSearchParams({ grant_type: 'authorization_code' }));
-
-    expect(readHeaders(call.init)['Content-Type']).toBe(
-      'application/x-www-form-urlencoded;charset=UTF-8',
-    );
-  });
-
-  it('percent-encodes values that would otherwise break the encoding', async () => {
-    const call = await postForm(new URLSearchParams({ code: 'a+b c&d=e' }));
-
-    expect(call.init?.body).toBe('code=a%2Bb+c%26d%3De');
-  });
-
-  it('still sends plain objects as JSON', async () => {
-    const calls: FetchCall[] = [];
-    globalThis.fetch = async (input, init) => {
-      calls.push({ url: String(input), init });
-      return jsonResponse({ ok: true });
-    };
-
-    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
-    await http.post('/auth/session/claim', { sessionToken: 'abc' }, { skipAuth: true });
-
-    const claimCall = calls.find((call) => call.url.endsWith('/auth/session/claim'));
-    expect(claimCall?.init?.body).toBe(JSON.stringify({ sessionToken: 'abc' }));
-    expect(readHeaders(claimCall?.init)['Content-Type']).toBe('application/json');
-  });
-
-  it('prefers OAuth error_description over the bare error code', async () => {
-    globalThis.fetch = async (input) => {
-      const url = String(input);
-      return new Response(
-        JSON.stringify({
-          error: 'invalid_grant',
-          error_description: 'The authorization code has expired.',
-        }),
-        { status: 400, headers: { 'content-type': 'application/json' } },
-      );
-    };
-
-    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
-    let caught: unknown;
-    try {
-      await http.post(
-        '/auth/oauth/token',
-        new URLSearchParams({ grant_type: 'authorization_code', code: 'expired' }),
-        { skipAuth: true, cache: false, deduplicate: false, retry: false },
-      );
-    } catch (error) {
-      caught = error;
-    }
-    expect(caught).toBeDefined();
-    expect(String((caught as { message?: string })?.message ?? caught)).toContain(
-      'The authorization code has expired.',
-    );
-  });
-});

package/src/__tests__/httpServiceQueueDeadlock.test.ts

@@ -1,128 +0,0 @@
-/**
- * RequestQueue deadlock regression.
- *
- * The auth preflight (`getAuthHeader` → single-flight `refreshAccessToken` → the
- * device-secret mint) used to run INSIDE a RequestQueue slot, and the mint itself
- * went through the queue. When `maxConcurrentRequests` requests all parked in
- * slots awaiting that same mint, the mint could never acquire a slot to run —
- * a systemic deadlock in which NOTHING settles (observed on a real device: the
- * running count climbs to the pool size with zero settled requests, including a
- * public GET /health). The fix: (1) `bypassQueue` runs control-plane calls (the
- * mint) directly, and (2) the preflight is resolved OUTSIDE the slot, so an
- * auth-blocked request never holds a slot while the shared mint runs.
- */
-import { HttpService } from '../HttpService';
-
-function createJwt(payload: Record<string, unknown>): string {
-  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
-  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.signature`;
-}
-
-function jsonResponse(data: unknown): Response {
-  return new Response(JSON.stringify({ data }), {
-    status: 200,
-    headers: { 'content-type': 'application/json' },
-  });
-}
-
-/** Resolve to `true` if `promise` settles within `ms`, else `false`. Always
- *  clears its timer so no pending timeout leaks into jest's teardown. */
-async function settlesWithin(promise: Promise<unknown>, ms: number): Promise<boolean> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const timeout = new Promise<false>((resolve) => {
-    timer = setTimeout(() => resolve(false), ms);
-  });
-  try {
-    return await Promise.race([promise.then(() => true), timeout]);
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-describe('HttpService RequestQueue deadlock', () => {
-  const originalFetch = globalThis.fetch;
-
-  afterEach(() => {
-    globalThis.fetch = originalFetch;
-    jest.restoreAllMocks();
-  });
-
-  it('runs a bypassQueue control-plane request even when every slot is held', async () => {
-    const releases: Array<() => void> = [];
-    globalThis.fetch = (async (input: RequestInfo | URL) => {
-      const url = String(input);
-      if (url.includes('/slow')) {
-        // Occupy the slot indefinitely until explicitly released.
-        await new Promise<void>((resolve) => releases.push(resolve));
-        return jsonResponse({ slow: true });
-      }
-      return jsonResponse({ minted: true });
-    }) as typeof fetch;
-
-    const http = new HttpService({
-      baseURL: 'https://api.oxy.so',
-      maxConcurrentRequests: 2,
-      enableRetry: false,
-    });
-
-    // Saturate both slots with requests whose fetch never settles.
-    const slowA = http.get('/slow/a', { skipAuth: true });
-    const slowB = http.get('/slow/b', { skipAuth: true });
-    await new Promise((resolve) => setTimeout(resolve, 0));
-
-    // The device-secret mint (bypassQueue) must still run despite full saturation.
-    const mint = http.post(
-      '/session/device/token',
-      { deviceId: 'd', deviceSecret: 's' },
-      { skipAuth: true, bypassQueue: true, retry: false },
-    );
-
-    expect(await settlesWithin(mint, 500)).toBe(true);
-
-    releases.forEach((release) => release());
-    await Promise.all([slowA, slowB]);
-  });
-
-  it('does not deadlock when a boot burst larger than the pool all trigger the same preflight mint', async () => {
-    const now = Math.floor(Date.now() / 1000);
-    // Within the 60s refresh lead window → every request's preflight refreshes.
-    const nearExpiry = createJwt({ userId: 'u', exp: now + 30 });
-    const fresh = createJwt({ userId: 'u', exp: now + 3600, jti: 'fresh' });
-
-    let mintCalls = 0;
-    globalThis.fetch = (async (input: RequestInfo | URL) => {
-      const url = String(input);
-      if (url.includes('/session/device/token')) {
-        mintCalls += 1;
-        return jsonResponse({ minted: true });
-      }
-      return jsonResponse({ ok: true });
-    }) as typeof fetch;
-
-    const http = new HttpService({
-      baseURL: 'https://api.oxy.so',
-      maxConcurrentRequests: 2,
-      enableRetry: false,
-    });
-    http.setTokens(nearExpiry);
-
-    http.setAuthRefreshHandler(async () => {
-      // Mirror refreshDeviceSecretArm: mint via a bypassQueue request through the
-      // SAME instance, then plant + return the fresh token.
-      await http.post(
-        '/session/device/token',
-        { deviceId: 'd', deviceSecret: 's' },
-        { skipAuth: true, bypassQueue: true, retry: false },
-      );
-      http.setTokens(fresh);
-      return fresh;
-    });
-
-    // A boot burst of 4 against a pool of 2, all in the near-expiry window.
-    const burst = Promise.all([http.get('/a'), http.get('/b'), http.get('/c'), http.get('/d')]);
-
-    expect(await settlesWithin(burst, 800)).toBe(true);
-    // The single-flight refresh coalesces the whole burst into ONE mint.
-    expect(mintCalls).toBe(1);
-  });
-});