zero-query 1.0.9 → 1.2.0

package/tests/webrtc/sfu.test.js

@@ -0,0 +1,160 @@
+/**
+ * tests/webrtc/sfu.test.js
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { loadSfuAdapter, createMediasoupAdapter, SfuError } from '../../src/webrtc/index.js';
+
+
+function makeFakeMediasoupClient({ loaded = false, canProduce = true } = {}) {
+    const transports = [];
+    class FakeDevice {
+        constructor(opts) {
+            this.opts   = opts;
+            this.loaded = loaded;
+            this.loadCalls = [];
+        }
+        async load({ routerRtpCapabilities }) {
+            this.loadCalls.push(routerRtpCapabilities);
+            this.loaded = true;
+        }
+        canProduce(kind) { return canProduce && (kind === 'audio' || kind === 'video'); }
+        createSendTransport(params) {
+            const t = { kind: 'send', params };
+            transports.push(t);
+            return t;
+        }
+        createRecvTransport(params) {
+            const t = { kind: 'recv', params };
+            transports.push(t);
+            return t;
+        }
+    }
+    return { mod: { Device: FakeDevice }, transports };
+}
+
+
+describe('loadSfuAdapter', () => {
+    it('rejects unknown adapter names', async () => {
+        await expect(loadSfuAdapter('nope')).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_SFU_UNKNOWN',
+        });
+    });
+
+    it('rejects livekit when livekit-client is not installed (peer-dep missing)', async () => {
+        await expect(loadSfuAdapter('livekit')).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_SFU_PEER_MISSING',
+        });
+    });
+
+    it('throws ZQ_WEBRTC_SFU_PEER_MISSING when mediasoup-client is not installed', async () => {
+        // mediasoup-client is genuinely not in this project's deps, so the
+        // dynamic import will fail.
+        await expect(loadSfuAdapter('mediasoup')).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_SFU_PEER_MISSING',
+        });
+    });
+
+    it('builds a mediasoup adapter with an injected client mock', async () => {
+        const { mod } = makeFakeMediasoupClient();
+        const adapter = await loadSfuAdapter('mediasoup', { client: mod, deviceOptions: { handlerName: 'TestHandler' } });
+        expect(adapter.name).toBe('mediasoup');
+        expect(adapter.device).toBeDefined();
+        expect(adapter.device.opts).toEqual({ handlerName: 'TestHandler' });
+        expect(adapter.loaded).toBe(false);
+    });
+});
+
+
+describe('createMediasoupAdapter (with mock)', () => {
+    it('throws ZQ_WEBRTC_SFU_BAD_MODULE when Device is missing', async () => {
+        await expect(createMediasoupAdapter({ client: {} })).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_SFU_BAD_MODULE',
+        });
+    });
+
+    it('also accepts a `default` export wrapper', async () => {
+        const { mod } = makeFakeMediasoupClient();
+        const adapter = await createMediasoupAdapter({ client: { default: mod } });
+        expect(adapter.name).toBe('mediasoup');
+    });
+
+    it('wraps Device-constructor exceptions in SfuError', async () => {
+        class BoomDevice { constructor() { throw new Error('boom'); } }
+        await expect(createMediasoupAdapter({ client: { Device: BoomDevice } })).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_SFU_DEVICE_FAILED',
+        });
+    });
+
+    it('load() requires routerRtpCapabilities', async () => {
+        const { mod } = makeFakeMediasoupClient();
+        const a = await createMediasoupAdapter({ client: mod });
+        await expect(a.load()).rejects.toMatchObject({ code: 'ZQ_WEBRTC_SFU_BAD_RTP_CAPS' });
+        await expect(a.load(null)).rejects.toMatchObject({ code: 'ZQ_WEBRTC_SFU_BAD_RTP_CAPS' });
+    });
+
+    it('load() forwards routerRtpCapabilities to the Device once', async () => {
+        const { mod } = makeFakeMediasoupClient();
+        const a = await createMediasoupAdapter({ client: mod });
+        const caps = { codecs: [], headerExtensions: [] };
+        await a.load(caps);
+        expect(a.loaded).toBe(true);
+        expect(a.device.loadCalls).toEqual([caps]);
+        // Calling again is a no-op (device.loaded short-circuits).
+        await a.load(caps);
+        expect(a.device.loadCalls).toEqual([caps]);
+    });
+
+    it('wraps device.load() failures', async () => {
+        class FailingDevice {
+            constructor() { this.loaded = false; }
+            async load() { throw new Error('rtp parse failed'); }
+        }
+        const a = await createMediasoupAdapter({ client: { Device: FailingDevice } });
+        await expect(a.load({ codecs: [] })).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_SFU_LOAD_FAILED',
+        });
+    });
+
+    it('canProduce / createSendTransport / createRecvTransport require load()', async () => {
+        const { mod } = makeFakeMediasoupClient();
+        const a = await createMediasoupAdapter({ client: mod });
+        expect(() => a.canProduce('audio')).toThrow(/not loaded/);
+        expect(() => a.createSendTransport({})).toThrow(/not loaded/);
+        expect(() => a.createRecvTransport({})).toThrow(/not loaded/);
+    });
+
+    it('after load(), forwards transport creation to the device', async () => {
+        const { mod, transports } = makeFakeMediasoupClient();
+        const a = await createMediasoupAdapter({ client: mod });
+        await a.load({ codecs: [] });
+
+        expect(a.canProduce('audio')).toBe(true);
+        expect(a.canProduce('video')).toBe(true);
+
+        const send = a.createSendTransport({ id: 'send-1' });
+        const recv = a.createRecvTransport({ id: 'recv-1' });
+        expect(send).toEqual({ kind: 'send', params: { id: 'send-1' } });
+        expect(recv).toEqual({ kind: 'recv', params: { id: 'recv-1' } });
+        expect(transports).toHaveLength(2);
+    });
+
+    it('join() throws ZQ_WEBRTC_SFU_JOIN_UNAVAILABLE (not yet wired)', async () => {
+        const { mod } = makeFakeMediasoupClient();
+        const a = await createMediasoupAdapter({ client: mod });
+        await expect(a.join({})).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_SFU_JOIN_UNAVAILABLE',
+        });
+    });
+
+    it('SfuError is exported and instanceof WebRtcError', async () => {
+        const { mod } = makeFakeMediasoupClient();
+        const a = await createMediasoupAdapter({ client: mod });
+        try {
+            await a.join({});
+        } catch (err) {
+            expect(err).toBeInstanceOf(SfuError);
+            expect(err.code).toBe('ZQ_WEBRTC_SFU_JOIN_UNAVAILABLE');
+        }
+    });
+});

package/tests/webrtc/signaling.test.js

@@ -0,0 +1,251 @@
+/**
+ * tests/webrtc/signaling.test.js
+ *
+ * Covers the low-level `SignalingClient`:
+ *   - connect + hello → peerId
+ *   - reconnect on abrupt close with exponential backoff
+ *   - protocol error on missing `type` field
+ *   - ICE coalescing batches outbound `ice` frames
+ *   - SSR-safe import (no globals required at module load)
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+import { SignalingClient, SignalingError } from '../../src/webrtc/index.js';
+import { FakeWebSocket, fakeSockets, resetFakeSockets } from '../_helpers/webrtcFakes.js';
+
+
+function makeClient(overrides = {}) {
+    return new SignalingClient('wss://example.test/rtc', Object.assign({
+        WebSocket: FakeWebSocket,
+        reconnect: { baseMs: 10, capMs: 80, maxRetries: 3 },
+        iceFlushMs: 20,
+        iceBatch:   3,
+    }, overrides));
+}
+
+
+describe('SignalingClient', () => {
+    beforeEach(() => {
+        resetFakeSockets();
+        vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    it('connect → hello → peerId', async () => {
+        const client = makeClient();
+        const p = client.connect();
+
+        // First (and only) socket created so far
+        expect(fakeSockets.length).toBe(1);
+        const ws = fakeSockets[0];
+        ws.fakeOpen();
+        await p;
+
+        expect(client.connected).toBe(true);
+        expect(client.peerId).toBe(null);
+
+        ws.fakeMessage({ type: 'hello', peerId: 'peer-abc' });
+        expect(client.peerId).toBe('peer-abc');
+    });
+
+    it('dispatches server frames to typed listeners', async () => {
+        const client = makeClient();
+        const p = client.connect();
+        fakeSockets[0].fakeOpen();
+        await p;
+        fakeSockets[0].fakeMessage({ type: 'hello', peerId: 'me' });
+
+        const seen = [];
+        client.on('joined', (frame) => seen.push(frame));
+        fakeSockets[0].fakeMessage({ type: 'joined', room: 'lobby', peerId: 'me', peers: ['x', 'y'] });
+
+        expect(seen.length).toBe(1);
+        expect(seen[0].room).toBe('lobby');
+        expect(seen[0].peers).toEqual(['x', 'y']);
+    });
+
+    it('emits a SignalingError when first frame is not a hello', async () => {
+        const client = makeClient();
+        const errors = [];
+        client.on('error', (e) => errors.push(e));
+        const p = client.connect();
+        fakeSockets[0].fakeOpen();
+        await p;
+
+        fakeSockets[0].fakeMessage({ type: 'joined', room: 'x' });
+        expect(errors.length).toBeGreaterThanOrEqual(1);
+        const err = errors[errors.length - 1];
+        expect(err).toBeInstanceOf(SignalingError);
+        expect(err.code).toBe('ZQ_WEBRTC_SIGNALING_NO_HELLO');
+    });
+
+    it('emits a SignalingError on a frame missing a `type`', async () => {
+        const client = makeClient();
+        const errors = [];
+        client.on('error', (e) => errors.push(e));
+        const p = client.connect();
+        fakeSockets[0].fakeOpen();
+        await p;
+        fakeSockets[0].fakeMessage({ type: 'hello', peerId: 'me' });
+
+        fakeSockets[0].fakeMessage({ room: 'lobby' });
+        const err = errors[errors.length - 1];
+        expect(err).toBeInstanceOf(SignalingError);
+        expect(err.code).toBe('ZQ_WEBRTC_SIGNALING_BAD_FRAME');
+    });
+
+    it('emits a SignalingError on malformed JSON', async () => {
+        const client = makeClient();
+        const errors = [];
+        client.on('error', (e) => errors.push(e));
+        const p = client.connect();
+        fakeSockets[0].fakeOpen();
+        await p;
+
+        fakeSockets[0].fakeMessage('not-json-at-all');
+        const err = errors[errors.length - 1];
+        expect(err).toBeInstanceOf(SignalingError);
+        expect(err.code).toBe('ZQ_WEBRTC_SIGNALING_BAD_JSON');
+    });
+
+    it('throws SignalingError when send() is called without a type', async () => {
+        const client = makeClient();
+        const p = client.connect();
+        fakeSockets[0].fakeOpen();
+        await p;
+        fakeSockets[0].fakeMessage({ type: 'hello', peerId: 'me' });
+
+        expect(() => client.send('')).toThrow(SignalingError);
+    });
+
+    it('reconnects with exponential backoff on abrupt close', async () => {
+        const client = makeClient();
+        const reconnects = [];
+        client.on('reconnect', (e) => reconnects.push(e));
+
+        const p = client.connect();
+        fakeSockets[0].fakeOpen();
+        await p;
+
+        // First abrupt close → schedules attempt 1 at baseMs * 2^0 = 10
+        fakeSockets[0].fakeClose(1006);
+        expect(reconnects.length).toBe(1);
+        expect(reconnects[0]).toEqual({ attempt: 1, delayMs: 10 });
+
+        // Drive the reconnect WITHOUT firing onopen so backoff continues to grow
+        vi.advanceTimersByTime(10);
+        expect(fakeSockets.length).toBe(2);
+
+        // Second close (still no successful open) → attempt 2 at 20ms
+        fakeSockets[1].fakeClose(1006);
+        expect(reconnects[1]).toEqual({ attempt: 2, delayMs: 20 });
+
+        vi.advanceTimersByTime(20);
+        expect(fakeSockets.length).toBe(3);
+
+        // Third close → attempt 3 at 40ms
+        fakeSockets[2].fakeClose(1006);
+        expect(reconnects[2]).toEqual({ attempt: 3, delayMs: 40 });
+    });
+
+    it('does not reconnect after .close()', async () => {
+        const client = makeClient();
+        const p = client.connect();
+        fakeSockets[0].fakeOpen();
+        await p;
+        fakeSockets[0].fakeMessage({ type: 'hello', peerId: 'me' });
+
+        client.close();
+        // close() called close(1000) synchronously - no reconnect should be scheduled
+        vi.advanceTimersByTime(500);
+        expect(fakeSockets.length).toBe(1);
+        expect(client.closed).toBe(true);
+    });
+
+    it('coalesces outbound ICE frames into batches', async () => {
+        const client = makeClient({ iceFlushMs: 50, iceBatch: 3 });
+        const p = client.connect();
+        const ws = fakeSockets[0];
+        ws.fakeOpen();
+        await p;
+        ws.fakeMessage({ type: 'hello', peerId: 'me' });
+
+        // Send 5 ice frames in quick succession
+        for (let i = 0; i < 5; i++) {
+            client.send('ice', { to: 'peer-x', candidate: `cand-${i}` });
+        }
+
+        // Nothing flushed yet
+        const iceSentBefore = ws.sentFrames.filter(f => f.type === 'ice');
+        expect(iceSentBefore.length).toBe(0);
+
+        // First window → first 3 flushed
+        vi.advanceTimersByTime(50);
+        const after1 = ws.sentFrames.filter(f => f.type === 'ice');
+        expect(after1.length).toBe(3);
+        expect(after1.map(f => f.candidate)).toEqual(['cand-0', 'cand-1', 'cand-2']);
+
+        // Second window → remaining 2 flushed
+        vi.advanceTimersByTime(50);
+        const after2 = ws.sentFrames.filter(f => f.type === 'ice');
+        expect(after2.length).toBe(5);
+        expect(after2.map(f => f.candidate)).toEqual(['cand-0', 'cand-1', 'cand-2', 'cand-3', 'cand-4']);
+    });
+
+    it('sends non-ICE frames immediately (no coalescing)', async () => {
+        const client = makeClient();
+        const p = client.connect();
+        fakeSockets[0].fakeOpen();
+        await p;
+        fakeSockets[0].fakeMessage({ type: 'hello', peerId: 'me' });
+
+        client.send('join', { room: 'lobby' });
+        const sent = fakeSockets[0].sentFrames;
+        expect(sent.length).toBe(1);
+        expect(sent[0]).toEqual({ type: 'join', room: 'lobby' });
+    });
+
+    it('gives up after maxRetries reconnect attempts', async () => {
+        const client = makeClient({ reconnect: { baseMs: 5, capMs: 100, maxRetries: 2 } });
+        const errors = [];
+        client.on('error', (e) => errors.push(e));
+        const p = client.connect();
+        fakeSockets[0].fakeOpen();
+        await p;
+
+        // Three consecutive failed connects (no fakeOpen on the reconnect sockets)
+        fakeSockets[0].fakeClose(1006);
+        vi.advanceTimersByTime(5);
+        fakeSockets[1].fakeClose(1006);
+        vi.advanceTimersByTime(10);
+        fakeSockets[2].fakeClose(1006);
+
+        // No more reconnects scheduled - giveup error emitted instead
+        const giveup = errors.find(e => e.code === 'ZQ_WEBRTC_SIGNALING_GIVEUP');
+        expect(giveup).toBeDefined();
+        expect(giveup).toBeInstanceOf(SignalingError);
+    });
+
+    it('is SSR-safe: importing the module does not require WebSocket on globalThis', async () => {
+        // Snapshot + delete the global WebSocket binding (jsdom provides one)
+        const hadWs = 'WebSocket' in globalThis;
+        const prev  = hadWs ? globalThis.WebSocket : undefined;
+        try {
+             
+            delete globalThis.WebSocket;
+            // Re-import via dynamic import to prove module init doesn't read it
+            const mod = await import('../../src/webrtc/signaling.js?ssrSafe=1');
+            expect(typeof mod.SignalingClient).toBe('function');
+            // Constructing also must not touch the global
+            const c = new mod.SignalingClient('wss://x/', { WebSocket: FakeWebSocket });
+            expect(c.connected).toBe(false);
+            expect(c.peerId).toBe(null);
+        } finally {
+            if (hadWs) globalThis.WebSocket = prev;
+        }
+    });
+});

package/tests/webrtc/turn.test.js

@@ -0,0 +1,256 @@
+/**
+ * tests/webrtc/turn.test.js - TURN credential client
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+    fetchTurnCredentials,
+    mergeIceServers,
+    createTurnRefresher,
+    TurnError,
+} from '../../src/webrtc/index.js';
+
+
+const validBody = () => ({
+    username:   'u1',
+    credential: 'secret',
+    urls:       ['turn:host:3478?transport=udp', 'turn:host:3478?transport=tcp'],
+    ttl:        600,
+});
+
+
+function mockFetch(impl) {
+    return vi.fn(impl);
+}
+
+function jsonResponse(body, { ok = true, status = 200 } = {}) {
+    return {
+        ok,
+        status,
+        json: async () => body,
+    };
+}
+
+
+describe('fetchTurnCredentials', () => {
+    it('returns normalized credentials on a 200 JSON body', async () => {
+        const fetchImpl = mockFetch(async () => jsonResponse(validBody()));
+        const creds = await fetchTurnCredentials('https://x/turn', { fetch: fetchImpl });
+        expect(creds.username).toBe('u1');
+        expect(creds.credential).toBe('secret');
+        expect(creds.urls).toEqual([
+            'turn:host:3478?transport=udp',
+            'turn:host:3478?transport=tcp',
+        ]);
+        expect(creds.ttl).toBe(600);
+    });
+
+    it('clones the urls array (mutating the result does not mutate the source)', async () => {
+        const body = validBody();
+        const fetchImpl = mockFetch(async () => jsonResponse(body));
+        const creds = await fetchTurnCredentials('https://x/turn', { fetch: fetchImpl });
+        creds.urls.push('turn:other:3478');
+        expect(body.urls).toHaveLength(2);
+    });
+
+    it('strips the `fetch` option before forwarding to fetch', async () => {
+        const fetchImpl = mockFetch(async (_url, init) => {
+            expect(init).toBeDefined();
+            expect(init.fetch).toBeUndefined();
+            expect(init.method).toBe('GET');
+            return jsonResponse(validBody());
+        });
+        await fetchTurnCredentials('https://x/turn', { fetch: fetchImpl, method: 'GET' });
+        expect(fetchImpl).toHaveBeenCalledTimes(1);
+    });
+
+    it('rejects an empty url', async () => {
+        await expect(fetchTurnCredentials('', { fetch: mockFetch() })).rejects.toMatchObject({
+            name: 'TurnError',
+            code: 'ZQ_WEBRTC_TURN_BAD_URL',
+        });
+    });
+
+    it('rejects when no fetch implementation is available', async () => {
+        const originalFetch = globalThis.fetch;
+        try {
+             
+            globalThis.fetch = undefined;
+            await expect(fetchTurnCredentials('https://x/turn')).rejects.toMatchObject({
+                code: 'ZQ_WEBRTC_TURN_NO_FETCH',
+            });
+        } finally {
+            globalThis.fetch = originalFetch;
+        }
+    });
+
+    it('wraps network errors as TurnError(ZQ_WEBRTC_TURN_NETWORK)', async () => {
+        const fetchImpl = mockFetch(async () => { throw new Error('boom'); });
+        await expect(fetchTurnCredentials('https://x/turn', { fetch: fetchImpl })).rejects.toMatchObject({
+            code:    'ZQ_WEBRTC_TURN_NETWORK',
+            message: expect.stringContaining('boom'),
+        });
+    });
+
+    it('rejects non-OK HTTP responses', async () => {
+        const fetchImpl = mockFetch(async () => jsonResponse({}, { ok: false, status: 503 }));
+        await expect(fetchTurnCredentials('https://x/turn', { fetch: fetchImpl })).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_TURN_HTTP',
+            context: { status: 503 },
+        });
+    });
+
+    it('rejects malformed JSON bodies', async () => {
+        const fetchImpl = mockFetch(async () => ({
+            ok: true, status: 200,
+            json: async () => { throw new Error('bad json'); },
+        }));
+        await expect(fetchTurnCredentials('https://x/turn', { fetch: fetchImpl })).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_TURN_BAD_JSON',
+        });
+    });
+
+    it.each([
+        ['missing username',   { ...validBody(), username:   '' }],
+        ['missing credential', { ...validBody(), credential: '' }],
+        ['missing urls',       { ...validBody(), urls:        [] }],
+        ['urls wrong type',    { ...validBody(), urls:        [42] }],
+        ['ttl zero',           { ...validBody(), ttl:         0 }],
+        ['ttl NaN',            { ...validBody(), ttl:         'soon' }],
+    ])('rejects invalid body shape (%s)', async (_label, body) => {
+        const fetchImpl = mockFetch(async () => jsonResponse(body));
+        await expect(fetchTurnCredentials('https://x/turn', { fetch: fetchImpl })).rejects.toMatchObject({
+            code: 'ZQ_WEBRTC_TURN_BAD_BODY',
+        });
+    });
+
+    it('throws a TurnError instance (instanceof check)', async () => {
+        const fetchImpl = mockFetch(async () => jsonResponse({}, { ok: false, status: 500 }));
+        await fetchTurnCredentials('https://x/turn', { fetch: fetchImpl }).catch((err) => {
+            expect(err).toBeInstanceOf(TurnError);
+        });
+    });
+});
+
+
+describe('mergeIceServers', () => {
+    it('appends a TURN entry to the base list', () => {
+        const out = mergeIceServers(
+            [{ urls: 'stun:stun.l.google.com:19302' }],
+            { username: 'u', credential: 'c', urls: ['turn:host:3478?transport=udp'] }
+        );
+        expect(out).toEqual([
+            { urls: ['stun:stun.l.google.com:19302'] },
+            { urls: ['turn:host:3478?transport=udp'], username: 'u', credential: 'c' },
+        ]);
+    });
+
+    it('dedupes duplicate urls (first occurrence wins)', () => {
+        const out = mergeIceServers(
+            [{ urls: ['stun:a', 'turn:host:3478'] }],
+            { username: 'u', credential: 'c', urls: ['turn:host:3478', 'turn:host:5349'] }
+        );
+        expect(out[0].urls).toEqual(['stun:a', 'turn:host:3478']);
+        expect(out[1].urls).toEqual(['turn:host:5349']);
+    });
+
+    it('drops an entry whose urls are all duplicates', () => {
+        const out = mergeIceServers(
+            [{ urls: ['turn:host:3478'] }],
+            { username: 'u', credential: 'c', urls: ['turn:host:3478'] }
+        );
+        expect(out).toHaveLength(1);
+    });
+
+    it('handles missing base and missing turn', () => {
+        expect(mergeIceServers()).toEqual([]);
+        expect(mergeIceServers([{ urls: 'stun:a' }])).toEqual([{ urls: ['stun:a'] }]);
+        expect(mergeIceServers(undefined, { username: 'u', credential: 'c', urls: ['turn:a'] }))
+            .toEqual([{ urls: ['turn:a'], username: 'u', credential: 'c' }]);
+    });
+
+    it('ignores non-string urls', () => {
+        const out = mergeIceServers([{ urls: ['stun:a', '', null, 42] }]);
+        expect(out).toEqual([{ urls: ['stun:a'] }]);
+    });
+});
+
+
+describe('createTurnRefresher', () => {
+    beforeEach(() => { vi.useFakeTimers(); });
+    afterEach(()  => { vi.useRealTimers(); });
+
+    it('rejects construction without a url', () => {
+        expect(() => createTurnRefresher({ url: '' })).toThrow(/url is required/);
+    });
+
+    it('fetches once on start() and reschedules ahead of expiry', async () => {
+        const fetchImpl = mockFetch(async () => jsonResponse(validBody()));
+        const refresher = createTurnRefresher({ url: 'https://x', fetch: fetchImpl, leadMs: 30000 });
+
+        const first = await refresher.start();
+        expect(first.username).toBe('u1');
+        expect(refresher.value).toEqual(first);
+        expect(fetchImpl).toHaveBeenCalledTimes(1);
+
+        // ttl=600s, leadMs=30s -> next refresh in 570s
+        await vi.advanceTimersByTimeAsync(570_000);
+        expect(fetchImpl).toHaveBeenCalledTimes(2);
+
+        refresher.stop();
+    });
+
+    it('floors the schedule at minIntervalMs', async () => {
+        const fetchImpl = mockFetch(async () => jsonResponse({ ...validBody(), ttl: 1 }));
+        const refresher = createTurnRefresher({
+            url:           'https://x',
+            fetch:         fetchImpl,
+            leadMs:        30000,
+            minIntervalMs: 5000,
+        });
+        await refresher.start();
+        expect(fetchImpl).toHaveBeenCalledTimes(1);
+
+        await vi.advanceTimersByTimeAsync(4999);
+        expect(fetchImpl).toHaveBeenCalledTimes(1);
+        await vi.advanceTimersByTimeAsync(1);
+        expect(fetchImpl).toHaveBeenCalledTimes(2);
+
+        refresher.stop();
+    });
+
+    it('invokes onRefresh for every successful fetch', async () => {
+        const fetchImpl = mockFetch(async () => jsonResponse(validBody()));
+        const onRefresh = vi.fn();
+        const refresher = createTurnRefresher({ url: 'https://x', fetch: fetchImpl, onRefresh });
+
+        await refresher.start();
+        expect(onRefresh).toHaveBeenCalledTimes(1);
+        await refresher.refresh();
+        expect(onRefresh).toHaveBeenCalledTimes(2);
+
+        refresher.stop();
+    });
+
+    it('invokes onError on failure and retries later', async () => {
+        const fetchImpl = mockFetch(async () => jsonResponse({}, { ok: false, status: 500 }));
+        const onError = vi.fn();
+        const refresher = createTurnRefresher({ url: 'https://x', fetch: fetchImpl, onError });
+
+        await expect(refresher.start()).rejects.toMatchObject({ code: 'ZQ_WEBRTC_TURN_HTTP' });
+        expect(onError).toHaveBeenCalledTimes(1);
+
+        refresher.stop();
+    });
+
+    it('stop() cancels pending timers and prevents further refreshes', async () => {
+        const fetchImpl = mockFetch(async () => jsonResponse(validBody()));
+        const refresher = createTurnRefresher({ url: 'https://x', fetch: fetchImpl });
+
+        await refresher.start();
+        refresher.stop();
+
+        await vi.advanceTimersByTimeAsync(10 * 60 * 1000);
+        expect(fetchImpl).toHaveBeenCalledTimes(1);
+    });
+});