@dev-crew-berlin/enter-js-utils 0.97.5 → 0.98.10

package/dist/api-client/api-client.test.js

@@ -0,0 +1,748 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import APIBase from './api-base';
+import API from './index';
+class TestAPI extends APIBase {
+  async *subscribe(endpoint, options = {}) {
+    yield* this.stream(endpoint, options);
+  }
+}
+function makeAPI() {
+  return new TestAPI({
+    credentials: {
+      accessToken: 'token',
+      url: 'https://api.example.com'
+    },
+    requesterId: 'req-1',
+    deviceName: 'test',
+    onLogout: vi.fn()
+  });
+}
+function sseChunk(messages) {
+  const text = messages.map(m => {
+    let s = '';
+    if (m.id !== undefined) s += `id: ${m.id}\n`;
+    if (m.event !== undefined) s += `event: ${m.event}\n`;
+    s += `data: ${m.data}\n\n`;
+    return s;
+  }).join('');
+  return new TextEncoder().encode(text);
+}
+
+// Creates a stream that enqueues chunks but does NOT close automatically.
+// Returns an explicit close() handle — the caller decides when the server
+// "shuts the connection", making the cause of any reconnect visible at the
+// call site rather than hidden inside a helper.
+// If the abort signal fires, the stream errors so in-progress reads throw.
+function makeStream(chunks, signal) {
+  let ctrl;
+  const stream = new ReadableStream({
+    start(controller) {
+      ctrl = controller;
+      if (signal?.aborted) {
+        controller.error(new DOMException('Aborted', 'AbortError'));
+        return;
+      }
+      signal?.addEventListener('abort', () => controller.error(new DOMException('Aborted', 'AbortError')), {
+        once: true
+      });
+      for (const chunk of chunks) controller.enqueue(chunk);
+    }
+  });
+  return {
+    stream,
+    push: chunk => ctrl.enqueue(chunk),
+    close: () => ctrl.close()
+  };
+}
+
+// Stream that hangs until the signal fires — intentionally never closed.
+function makeSilentStream(signal) {
+  return makeStream([], signal).stream;
+}
+function okResponse(body) {
+  return new Response(body, {
+    status: 200
+  });
+}
+function unauthorizedResponse() {
+  return new Response(null, {
+    status: 401,
+    statusText: 'Unauthorized'
+  });
+}
+
+// Flush the microtask queue by yielding many times.
+async function flushMicrotasks(rounds = 30) {
+  for (let i = 0; i < rounds; i++) await Promise.resolve();
+}
+
+// Flush pending microtasks (so the generator reaches its sleep() call and
+// registers the setTimeout), then advance fake timers by ms, then flush again
+// so the generator processes the reconnect before we assert.
+async function advanceTime(ms) {
+  await flushMicrotasks();
+  await vi.advanceTimersByTimeAsync(ms);
+  await flushMicrotasks();
+}
+describe('resilientStream', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  // ─── basic event delivery ────────────────────────────────────────────────
+
+  it('yields parsed JSON events', async () => {
+    const payload = {
+      type: 'attendee.updated',
+      id: '42'
+    };
+    vi.stubGlobal('fetch', (_url, init) => {
+      const {
+        stream
+      } = makeStream([sseChunk([{
+        data: JSON.stringify(payload)
+      }])], init.signal);
+      return Promise.resolve(okResponse(stream));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    const response = await gen.next();
+    expect(response.value).toEqual(payload);
+    expect(response.done).toBe(false);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── reconnect after stream end ──────────────────────────────────────────
+
+  it('reconnects after stream ends normally', async () => {
+    const event1 = {
+      n: 1
+    };
+    const event2 = {
+      n: 2
+    };
+    const events = [event1, event2];
+    let connectionCount = 0;
+    let closeStream;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      const {
+        stream,
+        close
+      } = makeStream([sseChunk([{
+        data: JSON.stringify(events.shift())
+      }])], init.signal);
+      closeStream = close;
+      return Promise.resolve(okResponse(stream));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    const response1 = await gen.next();
+    expect(response1.value).toEqual(event1);
+
+    // Closing the stream is what triggers the reconnect
+    // the generator exits the read loop and enters backoff.
+    closeStream();
+
+    // Dont await here so we can advance time and dont have to wait for backoff
+    const response2Promise = gen.next();
+    await advanceTime(3000); // past max jittered initial backoff
+    const response2 = await response2Promise;
+    expect(response2.value).toEqual(event2);
+    expect(connectionCount).toBe(2);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── reconnect after fetch error ─────────────────────────────────────────
+
+  it('reconnects after fetch network error', async () => {
+    const event = {
+      ok: true
+    };
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      if (connectionCount === 1) return Promise.reject(new Error('Network failure'));
+      const {
+        stream
+      } = makeStream([sseChunk([{
+        data: JSON.stringify(event)
+      }])], init.signal);
+      return Promise.resolve(okResponse(stream));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+
+    // fails on first attempt and hides retry, but takes some backoff time before retrying
+    const response1Promise = gen.next();
+    await advanceTime(3000);
+    const response1 = await response1Promise;
+    expect(response1.value).toEqual(event);
+    expect(connectionCount).toBe(2);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── Last-Event-ID ───────────────────────────────────────────────────────
+
+  it('sends Last-Event-ID header on reconnect', async () => {
+    const event = {
+      x: 1
+    };
+    const capturedInits = [];
+    // First connection delivers one event with a cursor; second is silent.
+    const streamChunks = [[sseChunk([{
+      id: 'cursor-99',
+      data: JSON.stringify(event)
+    }])], []];
+    let closeStream;
+    vi.stubGlobal('fetch', (_url, init) => {
+      capturedInits.push(init);
+      const {
+        stream,
+        close
+      } = makeStream(streamChunks.shift() ?? [], init.signal);
+      closeStream = close;
+      return Promise.resolve(okResponse(stream));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    const response1 = await gen.next();
+    expect(response1.value).toEqual(event);
+
+    // Close first stream — reconnect trigger
+    closeStream();
+    const response2Promise = gen.next();
+    await advanceTime(3000);
+    expect(capturedInits.length).toBeGreaterThanOrEqual(2);
+    const secondHeaders = capturedInits[1]?.headers;
+    expect(secondHeaders?.['Last-Event-ID']).toBe('cursor-99');
+    abortController.abort();
+    await response2Promise;
+  });
+  it('does not send Last-Event-ID on first connect', async () => {
+    const capturedInits = [];
+    vi.stubGlobal('fetch', (_url, init) => {
+      capturedInits.push(init);
+      return Promise.resolve(okResponse(makeSilentStream(init.signal)));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const pending = api.subscribe('/test', {
+      signal: abortController.signal
+    }).next();
+    await flushMicrotasks();
+    const firstHeaders = capturedInits[0]?.headers;
+    expect(firstHeaders?.['Last-Event-ID']).toBeUndefined();
+    abortController.abort();
+    await pending;
+  });
+
+  // ─── heartbeat watchdog ───────────────────────────────────────────────────
+
+  it('fires watchdog after 45s of silence and triggers reconnect', async () => {
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      return Promise.resolve(okResponse(makeSilentStream(init.signal)));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    const nextPromise = gen.next();
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+
+    // Fire the 45s watchdog then let the backoff sleep through
+    await advanceTime(45_001);
+    await advanceTime(3_000);
+    expect(connectionCount).toBeGreaterThanOrEqual(2);
+    abortController.abort();
+    await nextPromise;
+  });
+  it('heartbeats reset the watchdog so it does not fire during activity', async () => {
+    const realEvent = {
+      data: 'live'
+    };
+    let connectionCount = 0;
+    let pushChunk;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      const {
+        stream,
+        push
+      } = makeStream([], init.signal);
+      pushChunk = push;
+      return Promise.resolve(okResponse(stream));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    const responsePromise = gen.next();
+    await flushMicrotasks();
+
+    // Advance to just under the 45s watchdog — it has not fired yet
+    await advanceTime(44_000);
+    expect(connectionCount).toBe(1);
+
+    // Heartbeat arrives and resets the watchdog to another 45s from now
+    pushChunk(sseChunk([{
+      event: 'heartbeat',
+      data: '{}'
+    }]));
+    await flushMicrotasks();
+
+    // Advance another 44s — total 88s elapsed but watchdog was reset at 44s,
+    // so it still hasn't fired
+    await advanceTime(44_000);
+    expect(connectionCount).toBe(1);
+
+    // Real event arrives — generator yields it
+    pushChunk(sseChunk([{
+      data: JSON.stringify(realEvent)
+    }]));
+    const response = await responsePromise;
+    expect(response.value).toEqual(realEvent);
+    expect(connectionCount).toBe(1);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── heartbeat filtering ──────────────────────────────────────────────────
+
+  it('never yields heartbeat events to the consumer', async () => {
+    const realEvent = {
+      type: 'real'
+    };
+    vi.stubGlobal('fetch', (_url, init) => {
+      const {
+        stream
+      } = makeStream([sseChunk([{
+        event: 'heartbeat',
+        data: '{}'
+      }, {
+        data: JSON.stringify(realEvent)
+      }, {
+        event: 'heartbeat',
+        data: '{}'
+      }])], init.signal);
+      return Promise.resolve(okResponse(stream));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    const response = await gen.next();
+    expect(response.value).toEqual(realEvent);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── reset handling ───────────────────────────────────────────────────────
+
+  it('calls onReset for server reset event and does not yield it', async () => {
+    const realEvent = {
+      type: 'real'
+    };
+    vi.stubGlobal('fetch', (_url, init) => {
+      const {
+        stream
+      } = makeStream([sseChunk([{
+        event: 'reset',
+        data: '{}'
+      }, {
+        data: JSON.stringify(realEvent)
+      }])], init.signal);
+      return Promise.resolve(okResponse(stream));
+    });
+    const onReset = vi.fn();
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      onReset,
+      signal: abortController.signal
+    });
+    const response = await gen.next();
+    expect(response.value).toEqual(realEvent);
+    expect(onReset).toHaveBeenCalledTimes(1);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+  it('calls onReset when reconnecting without a stored cursor', async () => {
+    // No id fields → cursor never stored → onReset fires on reconnect
+    const events = ['{"n":1}', '{"n":2}'];
+    let closeStream;
+    vi.stubGlobal('fetch', (_url, init) => {
+      const {
+        stream,
+        close
+      } = makeStream([sseChunk([{
+        data: events.shift() ?? ''
+      }])], init.signal);
+      closeStream = close;
+      return Promise.resolve(okResponse(stream));
+    });
+    const onReset = vi.fn();
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      onReset,
+      signal: abortController.signal
+    });
+    const response1 = await gen.next();
+    expect(response1.value).toEqual({
+      n: 1
+    });
+    expect(onReset).not.toHaveBeenCalled(); // no onReset on first connect
+
+    // Closing the first stream (no cursor stored) triggers onReset on reconnect
+    closeStream();
+    const response2Promise = gen.next();
+    await advanceTime(3000);
+    const response2 = await response2Promise;
+    expect(response2.value).toEqual({
+      n: 2
+    });
+    expect(onReset).toHaveBeenCalledTimes(1);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+  it('does not call onReset on the first connect', async () => {
+    vi.stubGlobal('fetch', (_url, init) => {
+      const {
+        stream
+      } = makeStream([sseChunk([{
+        data: '{"n":1}'
+      }])], init.signal);
+      return Promise.resolve(okResponse(stream));
+    });
+    const onReset = vi.fn();
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      onReset,
+      signal: abortController.signal
+    });
+    await gen.next();
+    expect(onReset).not.toHaveBeenCalled();
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── clean termination ────────────────────────────────────────────────────
+
+  it('does not reconnect after consumer break', async () => {
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      const {
+        stream
+      } = makeStream([sseChunk([{
+        data: '{"n":1}'
+      }, {
+        data: '{"n":2}'
+      }])], init.signal);
+      return Promise.resolve(okResponse(stream));
+    });
+    const api = makeAPI();
+    const gen = api.subscribe('/test');
+    const response1 = await gen.next();
+    expect(response1.value.n).toBe(1);
+
+    // Consumer breaks — generator terminates cleanly; no server close needed
+    await gen.return(undefined);
+    await vi.advanceTimersByTimeAsync(60_000);
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+  });
+  it('does not reconnect when external AbortSignal is fired', async () => {
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      return Promise.resolve(okResponse(makeSilentStream(init.signal)));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const pending = api.subscribe('/test', {
+      signal: abortController.signal
+    }).next();
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+    abortController.abort();
+    await pending; // resolves as {done: true}
+
+    await vi.advanceTimersByTimeAsync(60_000);
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+  });
+  it('does not reconnect after a 401 response', async () => {
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', () => {
+      connectionCount++;
+      return Promise.resolve(unauthorizedResponse());
+    });
+    const api = makeAPI();
+    const gen = api.subscribe('/test');
+    const response = await gen.next();
+    expect(response.done).toBe(true);
+    await vi.advanceTimersByTimeAsync(60_000);
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+  });
+
+  // ─── backoff behaviour ────────────────────────────────────────────────────
+
+  it('backoff grows across successive reconnects', async () => {
+    // Pin jitter to maximum (Math.random() = 1 → multiplier = 1.5) so timing is deterministic:
+    //   1st sleep  = 1_000 ms (initial backoffMs, jitter applied after)
+    //   2nd sleep  = Math.min(1_000 × 2, 30_000) × 1.5 = 3_000 ms
+    vi.spyOn(Math, 'random').mockReturnValue(1);
+    let connectionCount = 0;
+    let closeStream;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      const {
+        stream,
+        close
+      } = makeStream([], init.signal);
+      closeStream = close;
+      return Promise.resolve(okResponse(stream));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    gen.next();
+    await flushMicrotasks();
+
+    // 1st disconnect → 1_000 ms backoff
+    closeStream();
+    await advanceTime(999);
+    expect(connectionCount).toBe(1); // not yet
+
+    await advanceTime(2); // crosses 1_000 ms
+    expect(connectionCount).toBe(2);
+
+    // 2nd disconnect → 3_000 ms backoff (grew)
+    closeStream();
+    await advanceTime(2_999);
+    expect(connectionCount).toBe(2); // not yet
+
+    await advanceTime(2); // crosses 3_000 ms
+    expect(connectionCount).toBe(3);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+  it('resets backoff after a connection that lived longer than the threshold', async () => {
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      return Promise.resolve(okResponse(makeSilentStream(init.signal)));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    gen.next();
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+
+    // Watchdog fires at 45 s (connection lived > 10 s threshold → backoff resets)
+    await advanceTime(45_001);
+
+    // Backoff should have been reset to ~1 s; advance 2 s to cover jitter
+    await advanceTime(2_000);
+
+    // Second fetch triggered
+    expect(connectionCount).toBeGreaterThanOrEqual(2);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── connection state callbacks ───────────────────────────────────────────
+
+  it('emits connected then reconnecting on connection loss', async () => {
+    // First connection delivers one event; second is silent (only the state
+    // sequence matters here, not a second event).
+    const streamChunks = [[sseChunk([{
+      data: '{"n":1}'
+    }])], []];
+    let closeStream;
+    vi.stubGlobal('fetch', (_url, init) => {
+      const {
+        stream,
+        close
+      } = makeStream(streamChunks.shift() ?? [], init.signal);
+      closeStream = close;
+      return Promise.resolve(okResponse(stream));
+    });
+    const states = [];
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal,
+      onConnectionChange: s => states.push(s)
+    });
+    const response1 = await gen.next();
+    expect(response1.value).toEqual({
+      n: 1
+    });
+
+    // Closing the first stream triggers 'reconnecting', then 'connected' on the second
+    closeStream();
+    const response2Promise = gen.next();
+    await advanceTime(3000);
+    expect(states).toContain('connected');
+    expect(states).toContain('reconnecting');
+    expect(states.indexOf('connected')).toBeLessThan(states.indexOf('reconnecting'));
+    abortController.abort();
+    await response2Promise;
+  });
+
+  // ─── initialLastEventId ───────────────────────────────────────────────────
+
+  it('sends initialLastEventId as Last-Event-ID on the very first connect', async () => {
+    const capturedInits = [];
+    vi.stubGlobal('fetch', (_url, init) => {
+      capturedInits.push(init);
+      return Promise.resolve(okResponse(makeSilentStream(init.signal)));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const pending = api.subscribe('/test', {
+      signal: abortController.signal,
+      initialLastEventId: 'seed-cursor'
+    }).next();
+    await flushMicrotasks();
+    const firstHeaders = capturedInits[0]?.headers;
+    expect(firstHeaders?.['Last-Event-ID']).toBe('seed-cursor');
+    abortController.abort();
+    await pending;
+  });
+});
+function makeFullAPI() {
+  return new API({
+    credentials: {
+      accessToken: 'token',
+      url: 'https://api.example.com'
+    },
+    requesterId: 'req-1',
+    deviceName: 'test',
+    onLogout: vi.fn()
+  });
+}
+describe('getAttendeeList', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+  it('returns eventCursor: null when X-Event-Cursor header is absent', async () => {
+    vi.stubGlobal('fetch', () => Promise.resolve(new Response(JSON.stringify([{
+      id: 'att-1'
+    }]), {
+      status: 200
+    })));
+    const api = makeFullAPI();
+    const result = await api.getAttendeeList({
+      instanceName: 'test-instance'
+    });
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.data.eventCursor).toBeNull();
+    expect(result.data.attendees).toHaveLength(1);
+    expect(result.data.attendees[0].id).toBe('att-1');
+  });
+  it('returns eventCursor from X-Event-Cursor response header', async () => {
+    vi.stubGlobal('fetch', () => Promise.resolve(new Response(JSON.stringify([{
+      id: 'att-1'
+    }]), {
+      status: 200,
+      headers: {
+        'X-Event-Cursor': 'abc123'
+      }
+    })));
+    const api = makeFullAPI();
+    const result = await api.getAttendeeList({
+      instanceName: 'test-instance'
+    });
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.data.eventCursor).toBe('abc123');
+  });
+});
+describe('createEvents', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+  it('returns created and eventCursors populated from response body', async () => {
+    vi.stubGlobal('fetch', () => Promise.resolve(new Response(JSON.stringify({
+      created: 2,
+      event_cursors: {
+        'uuid-1': 'cursor-abc',
+        'uuid-2': 'cursor-def'
+      }
+    }), {
+      status: 201
+    })));
+    const api = makeFullAPI();
+    const result = await api.createEvents([]);
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.data.created).toBe(2);
+    expect(result.data.eventCursors).toEqual({
+      'uuid-1': 'cursor-abc',
+      'uuid-2': 'cursor-def'
+    });
+  });
+  it('returns empty eventCursors when field is absent', async () => {
+    vi.stubGlobal('fetch', () => Promise.resolve(new Response(JSON.stringify({
+      created: 1
+    }), {
+      status: 201
+    })));
+    const api = makeFullAPI();
+    const result = await api.createEvents([]);
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.data.created).toBe(1);
+    expect(result.data.eventCursors).toEqual({});
+  });
+  it('returns empty eventCursors when field is empty', async () => {
+    vi.stubGlobal('fetch', () => Promise.resolve(new Response(JSON.stringify({
+      created: 0,
+      event_cursors: {}
+    }), {
+      status: 201
+    })));
+    const api = makeFullAPI();
+    const result = await api.createEvents([]);
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.data.created).toBe(0);
+    expect(result.data.eventCursors).toEqual({});
+  });
+});