@novasamatech/host-substrate-chain-connection 0.10.1 → 0.10.2

package/dist/connectionPool.d.ts

@@ -25,5 +25,21 @@ export type ChainConnection<C extends ChainConfig, T = PolkadotClient> = {
      */
     pauseAll(): void;
     resumeAll(): void;
+    /**
+     * Rebuild the transport of the chains named by `genesisHashes`, or of every
+     * chain currently held when it is omitted. `createProvider` runs again, so a
+     * host that picks its transport from settings (a light client versus RPC
+     * nodes, say) applies the new choice here.
+     *
+     * Pooled clients, resolved apis and refcounts all survive: consumers keep the
+     * references they already hold and see the same interruption a dropped socket
+     * would have caused. A chain nobody holds is skipped — one the pool never
+     * connected to, and one still waiting out `destroyDelay` — and picks the new
+     * transport up when it is next acquired.
+     *
+     * The old transports close at once, the new ones come up on the reconnect
+     * backoff; see `restart` in `createRestartableProvider`.
+     */
+    reconnect(genesisHashes?: readonly string[]): void;
 };
 export declare const createChainConnection: <C extends ChainConfig, T = PolkadotClient>({ resolve, clientOptions, createProvider, createClient: makeClient, destroyDelay, }: ChainConnectionConfig<C, T>) => ChainConnection<C, T>;

package/dist/connectionPool.js

@@ -3,7 +3,7 @@ import { createClient } from 'polkadot-api';
 import { createBranchedProvider } from './branchedProvider.js';
 import { createConnectionManager } from './connectionManager.js';
 import { createRefCounter } from './refCounter.js';
-import { isPausable } from './wsProvider.js';
+import { createRestartableProvider } from './restartableProvider.js';
 export const createChainConnection = ({ resolve, clientOptions, createProvider, createClient: makeClient = createClient, destroyDelay = 0, }) => {
     const connections = createConnectionManager();
     const refCounter = createRefCounter();
@@ -23,7 +23,28 @@ export const createChainConnection = ({ resolve, clientOptions, createProvider,
         const existing = existingClients.get(chain.genesisHash);
         if (existing)
             return existing;
-        const rootProvider = createProvider(chain, status => connections.update(chain.genesisHash, status));
+        // A provider replaced by `reconnect` can still report a trailing
+        // `disconnected` while its successor is already connecting, so status is
+        // scoped to the generation that produced it and stale updates are dropped.
+        let generation = 0;
+        const rootProvider = createRestartableProvider(() => {
+            const current = ++generation;
+            const update = (status) => {
+                if (current === generation)
+                    connections.update(chain.genesisHash, status);
+            };
+            try {
+                return createProvider(chain, update);
+            }
+            catch (error) {
+                // The bump above already muted the previous transport's updates, so a
+                // factory that throws would otherwise leave the chain reporting the
+                // status of a transport that no longer exists. `createRestartableProvider`
+                // retries, and the next attempt reports for itself.
+                update('disconnected');
+                throw error;
+            }
+        });
         const branchedProvider = createBranchedProvider(rootProvider);
         const client = makeClient(branchedProvider.branch(), clientOptions?.(chain));
         const pooled = { client, provider: branchedProvider, rootProvider };
@@ -142,14 +163,24 @@ export const createChainConnection = ({ resolve, clientOptions, createProvider,
         },
         pauseAll() {
             for (const { rootProvider } of existingClients.values()) {
-                if (isPausable(rootProvider))
-                    rootProvider.pause();
+                rootProvider.pause();
             }
         },
         resumeAll() {
             for (const { rootProvider } of existingClients.values()) {
-                if (isPausable(rootProvider))
-                    rootProvider.resume();
+                rootProvider.resume();
+            }
+        },
+        reconnect(genesisHashes) {
+            for (const [genesisHash, { rootProvider }] of existingClients) {
+                if (genesisHashes && !genesisHashes.includes(genesisHash))
+                    continue;
+                // Nobody holds this one any more — it is only waiting out `destroyDelay`.
+                // Rebuilding its transport would open a socket the destruction timer is
+                // about to throw away.
+                if (destructionTimers.has(genesisHash))
+                    continue;
+                rootProvider.restart();
             }
         },
     };

package/dist/connectionPool.spec.js

@@ -1,16 +1,28 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { createChainConnection } from './connectionPool.js';
+import { noop } from './helpers.js';
 // An in-memory stand-in for polkadot-api's `createClient`: one client object per
 // call, each counting its own `destroy()`.
 const createClientFactory = () => {
     const clients = [];
-    const factory = ((_provider, _options) => {
+    const factory = ((provider, _options) => {
         const client = { destroyed: 0 };
         clients.push(client);
-        return { destroy: () => client.destroyed++ };
+        // The real one connects up front and drops the connection on destroy; the
+        // pool only builds a transport once something actually connects.
+        const connection = provider(noop);
+        return {
+            destroy: () => {
+                client.destroyed++;
+                connection.disconnect();
+            },
+        };
     });
     return { createClient: factory, last: () => clients[clients.length - 1] };
 };
+// The transport is built on the proxy's first connect attempt, which it
+// schedules rather than runs inline.
+const connected = () => new Promise(resolve => setTimeout(resolve, 0));
 const createMockProvider = () => {
     const send = vi.fn();
     const disconnect = vi.fn();
@@ -125,9 +137,13 @@ describe('createChainConnection', () => {
                     return createMockProvider().provider;
                 },
             });
-            await connection.lockApi(testChain('a')).then(({ unlock }) => unlock());
+            // The lock is held across the wait: releasing it destroys the client, and
+            // a destroyed pool never gets round to building a transport at all.
+            const { unlock } = await connection.lockApi(testChain('a'));
+            await connected();
             statusCb('connected');
             expect(connection.status('a')).toBe('connected');
+            unlock();
         });
         it('onStatusChanged returns unsubscribe function', async () => {
             let statusCb;
@@ -137,7 +153,8 @@ describe('createChainConnection', () => {
                     return createMockProvider().provider;
                 },
             });
-            await connection.lockApi(testChain('a')).then(({ unlock }) => unlock());
+            const { unlock } = await connection.lockApi(testChain('a'));
+            await connected();
             const callback = vi.fn();
             const unsub = connection.onStatusChanged('a', callback);
             statusCb('connected');
@@ -146,6 +163,7 @@ describe('createChainConnection', () => {
             callback.mockClear();
             statusCb('disconnected');
             expect(callback).not.toHaveBeenCalled();
+            unlock();
         });
     });
     describe('lockApi — connection lifecycle', () => {
@@ -214,6 +232,7 @@ describe('createChainConnection', () => {
             });
             const { unlock: u1 } = await connection.lockApi(testChain('a'));
             const { unlock: u2 } = await connection.lockApi(testChain('b'));
+            await connected();
             connection.pauseAll();
             expect(chainA.pause).toHaveBeenCalledTimes(1);
             expect(chainB.pause).toHaveBeenCalledTimes(1);
@@ -227,6 +246,7 @@ describe('createChainConnection', () => {
                 createClient: createClientFactory().createClient,
             });
             const { unlock } = await connection.lockApi(testChain('a'));
+            await connected();
             connection.pauseAll();
             connection.resumeAll();
             expect(chainA.resume).toHaveBeenCalledTimes(1);
@@ -242,6 +262,7 @@ describe('createChainConnection', () => {
             });
             await connection.lockApi(testChain('a'));
             await connection.lockApi(testChain('b'));
+            await connected();
             connection.pauseAll();
             connection.resumeAll();
             expect(pausable.pause).toHaveBeenCalledTimes(1);
@@ -260,4 +281,101 @@ describe('createChainConnection', () => {
             expect(chainA.pause).not.toHaveBeenCalled();
         });
     });
+    describe('reconnect', () => {
+        // A restart rides the proxy's halt path, which backs off when halts land on
+        // top of each other. Running fake time past that window keeps these cases
+        // about the swap rather than about the backoff.
+        beforeEach(() => vi.useFakeTimers());
+        afterEach(() => vi.useRealTimers());
+        const settle = () => vi.advanceTimersByTimeAsync(1_000);
+        it('asks createProvider for a new transport and closes the old one', async () => {
+            const first = createMockProvider();
+            const second = createMockProvider();
+            const transports = [first, second];
+            const createProvider = vi.fn(() => transports.shift().provider);
+            const { connection } = createTestConnection({ createProvider });
+            const { unlock } = await connection.lockApi(testChain('a'));
+            await settle();
+            connection.reconnect();
+            await settle();
+            expect(createProvider).toHaveBeenCalledTimes(2);
+            expect(first.disconnect).toHaveBeenCalledTimes(1);
+            unlock();
+        });
+        it('keeps the pooled client — the point is not restarting the app', async () => {
+            const { connection, clients } = createTestConnection();
+            const { api, unlock } = await connection.lockApi(testChain('a'));
+            await settle();
+            connection.reconnect();
+            await settle();
+            const { api: after, unlock: unlockAfter } = await connection.lockApi(testChain('a'));
+            expect(clients.last().destroyed).toBe(0);
+            expect(after).toBe(api);
+            unlock();
+            unlockAfter();
+        });
+        it('rebuilds only the chains it was given', async () => {
+            const built = [];
+            const connection = createChainConnection({
+                createProvider: chain => {
+                    built.push(chain.genesisHash);
+                    return createMockProvider().provider;
+                },
+                createClient: createClientFactory().createClient,
+            });
+            const { unlock: unlockA } = await connection.lockApi(testChain('a'));
+            const { unlock: unlockB } = await connection.lockApi(testChain('b'));
+            await settle();
+            expect(built).toEqual(['a', 'b']);
+            connection.reconnect(['a']);
+            await settle();
+            expect(built).toEqual(['a', 'b', 'a']);
+            unlockA();
+            unlockB();
+        });
+        it('ignores a chain the pool is not holding', async () => {
+            const createProvider = vi.fn(() => createMockProvider().provider);
+            const connection = createChainConnection({
+                createProvider,
+                createClient: createClientFactory().createClient,
+            });
+            expect(() => connection.reconnect(['nothing-here'])).not.toThrow();
+            expect(createProvider).not.toHaveBeenCalled();
+        });
+        it('skips a chain that is only waiting out destroyDelay', async () => {
+            const createProvider = vi.fn(() => createMockProvider().provider);
+            const connection = createChainConnection({
+                createProvider,
+                createClient: createClientFactory().createClient,
+                destroyDelay: 10_000,
+            });
+            const { unlock } = await connection.lockApi(testChain('a'));
+            await settle();
+            unlock();
+            connection.reconnect();
+            await settle();
+            // Nobody holds it; the destruction timer is about to discard the client,
+            // so a fresh transport would be opened only to be thrown away.
+            expect(createProvider).toHaveBeenCalledTimes(1);
+        });
+        it('drops a status the replaced transport reports after the swap', async () => {
+            const statusCallbacks = [];
+            const { connection } = createTestConnection({
+                createProvider: (_chain, onStatusChanged) => {
+                    statusCallbacks.push(onStatusChanged);
+                    return createMockProvider().provider;
+                },
+            });
+            const { unlock } = await connection.lockApi(testChain('a'));
+            await settle();
+            connection.reconnect();
+            await settle();
+            statusCallbacks[1]('connected');
+            // The transport that was replaced has no say any more — otherwise its
+            // parting 'disconnected' would land on top of its successor's 'connected'.
+            statusCallbacks[0]('disconnected');
+            expect(connection.status('a')).toBe('connected');
+            unlock();
+        });
+    });
 });

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { type ChainConnection, type ChainConnectionConfig, createChainConnection } from './connectionPool.js';
 export { type MetadataCache, createMetadataCache } from './metadataCache.js';
+export { type RestartableJsonRpcProvider, createRestartableProvider } from './restartableProvider.js';
 export { withSubscriptionReplay } from './subscriptionReplayProvider.js';
 export { createWsJsonRpcProvider } from './wsProvider.js';
 export { type ChainConfig, type ConnectionStatus } from './types.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { createChainConnection } from './connectionPool.js';
 export { createMetadataCache } from './metadataCache.js';
+export { createRestartableProvider } from './restartableProvider.js';
 export { withSubscriptionReplay } from './subscriptionReplayProvider.js';
 export { createWsJsonRpcProvider } from './wsProvider.js';
 export {} from './types.js';

package/dist/restartableProvider.d.ts

@@ -0,0 +1,33 @@
+import type { JsonRpcProvider } from 'polkadot-api';
+export type RestartableJsonRpcProvider = JsonRpcProvider & {
+    /**
+     * Throw the live transport away and build a new one from the factory, without
+     * tearing down the consumers hanging off this provider. Callers use it to move
+     * a chain onto a different transport — a light client to an RPC node, say —
+     * while clients, subscriptions and refcounts stay where they are.
+     *
+     * The old transport closes synchronously; the new one does not. The swap goes
+     * through the proxy's reconnect path, so the factory is called on its backoff
+     * — 500 ms after this returns, and a step further out for each restart that
+     * lands before the chain has delivered a message on the transport before it
+     * (`getSyncProvider` counts those as a flapping connection). Next to opening a
+     * socket or booting a light client the first step is noise, but a caller
+     * driving this from a UI toggle should not treat it as instantaneous.
+     */
+    restart(): void;
+    /** Forwarded to the current transport when it supports it; otherwise a no-op. */
+    pause(): void;
+    resume(): void;
+};
+/**
+ * A provider whose underlying transport can be replaced at any time.
+ *
+ * The swap is dressed up as a connection drop, which is the one event every
+ * layer above already knows how to survive: `getSyncProvider`'s proxy reports
+ * the active `chainHead` follows as stopped and re-sends the requests that were
+ * in flight, so polkadot-api re-follows on the new transport by itself, and the
+ * subscription-replay wrapper re-establishes the legacy subscriptions that
+ * `chainHead` bookkeeping does not cover. Consumers see the same interruption a
+ * dropped socket would have caused, and nothing above has to be rebuilt.
+ */
+export declare const createRestartableProvider: (createTransport: () => JsonRpcProvider) => RestartableJsonRpcProvider;

package/dist/restartableProvider.js

@@ -0,0 +1,107 @@
+import { getSyncProvider } from '@polkadot-api/json-rpc-provider-proxy';
+import { noop } from './helpers.js';
+import { withSubscriptionReplay } from './subscriptionReplayProvider.js';
+import { isPausable } from './wsProvider.js';
+/**
+ * A provider whose underlying transport can be replaced at any time.
+ *
+ * The swap is dressed up as a connection drop, which is the one event every
+ * layer above already knows how to survive: `getSyncProvider`'s proxy reports
+ * the active `chainHead` follows as stopped and re-sends the requests that were
+ * in flight, so polkadot-api re-follows on the new transport by itself, and the
+ * subscription-replay wrapper re-establishes the legacy subscriptions that
+ * `chainHead` bookkeeping does not cover. Consumers see the same interruption a
+ * dropped socket would have caused, and nothing above has to be rebuilt.
+ */
+export const createRestartableProvider = (createTransport) => {
+    let active = null;
+    let notifyReconnect = noop;
+    // Survives a restart: a transport built while the host has the pool paused
+    // must come up paused too, or backgrounding the app would stop holding.
+    let paused = false;
+    const onReconnect = (callback) => {
+        notifyReconnect = callback;
+        return () => {
+            notifyReconnect = noop;
+        };
+    };
+    const core = getSyncProvider(onResult => {
+        let built = false;
+        onResult((onMessage, halt) => {
+            let provider;
+            let connection;
+            try {
+                provider = createTransport();
+                // Paused before the transport is handed its message callback: a
+                // transport that opens its connection right there (a light client, say)
+                // would otherwise be up for as long as it takes to pause it again,
+                // which is the socket-behind-a-backgrounded-app this guards against.
+                if (paused && isPausable(provider))
+                    provider.pause();
+                connection = provider(onMessage);
+            }
+            catch (error) {
+                // The proxy is mid-connect and stores whatever we return here, so a
+                // factory that throws has to be reported through `halt`: it puts the
+                // proxy back to connecting — buffering sends rather than pushing them
+                // at a transport that was never built — and schedules the next attempt.
+                // Without it the chain would keep a live-looking client wired to
+                // nothing, for good.
+                halt(error);
+                return { send: noop, disconnect: noop };
+            }
+            // The transport's own halt channel is deliberately not wired up: a
+            // transport either recovers on its own (the ws provider proxies its
+            // reconnects internally) or reports `disconnected` and stays down. `halt`
+            // is kept for `restart`, which is the only reason this layer replaces one.
+            const transport = { provider, connection, halt };
+            active = transport;
+            built = true;
+            return {
+                send: message => connection.send(message),
+                disconnect: () => {
+                    if (active === transport)
+                        active = null;
+                    connection.disconnect();
+                },
+            };
+        });
+        // `onResult` runs the proxy's connect synchronously, so by here the proxy is
+        // connected and the replayed subscribes go out on the new transport rather
+        // than into a buffer that a failed connect would discard. A failed attempt
+        // skips the replay entirely — the halt above has already queued another one,
+        // which will do it against a transport that exists.
+        if (built)
+            notifyReconnect();
+        // Nothing to cancel: `onResult` above already resolved this attempt.
+        return noop;
+    });
+    const provider = withSubscriptionReplay(core, onReconnect);
+    return Object.assign(provider, {
+        restart() {
+            const transport = active;
+            // Nothing to replace while the proxy is between transports — whatever it
+            // asks the factory for next is already built from the current settings.
+            if (!transport)
+                return;
+            active = null;
+            // Close before halting: the halt schedules the next `createTransport`, and
+            // a transport left open would keep its socket (or light client) running
+            // alongside its replacement.
+            transport.connection.disconnect();
+            transport.halt();
+        },
+        pause() {
+            paused = true;
+            const transport = active?.provider;
+            if (transport && isPausable(transport))
+                transport.pause();
+        },
+        resume() {
+            paused = false;
+            const transport = active?.provider;
+            if (transport && isPausable(transport))
+                transport.resume();
+        },
+    });
+};

package/dist/restartableProvider.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/restartableProvider.spec.js

@@ -0,0 +1,192 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRestartableProvider } from './restartableProvider.js';
+const createFakeTransport = ({ pausable = false } = {}) => {
+    const send = vi.fn();
+    const disconnect = vi.fn();
+    let onMessage = null;
+    const provider = cb => {
+        onMessage = cb;
+        return { send, disconnect };
+    };
+    const transport = { provider, send, disconnect, emit: message => onMessage?.(message) };
+    if (pausable) {
+        transport.pause = vi.fn();
+        transport.resume = vi.fn();
+        Object.assign(provider, { pause: transport.pause, resume: transport.resume });
+    }
+    return transport;
+};
+// `getSyncProvider` schedules every connect attempt on a timer, and treats
+// halts that land on top of each other as a flapping connection worth backing
+// off from. Letting fake time run past that window keeps these cases about the
+// swap rather than about the backoff.
+const settle = () => vi.advanceTimersByTimeAsync(1_000);
+const connect = async (provider) => {
+    const messages = [];
+    const connection = provider(message => messages.push(message));
+    await settle();
+    return { connection, messages };
+};
+describe('createRestartableProvider', () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+    it('builds a transport lazily and routes traffic through it', async () => {
+        const transport = createFakeTransport();
+        const provider = createRestartableProvider(() => transport.provider);
+        const { connection, messages } = await connect(provider);
+        connection.send({ jsonrpc: '2.0', id: 1, method: 'system_chain', params: [] });
+        transport.emit({ jsonrpc: '2.0', id: 1, result: 'polkadot' });
+        expect(transport.send).toHaveBeenCalledOnce();
+        expect(messages).toContainEqual({ jsonrpc: '2.0', id: 1, result: 'polkadot' });
+    });
+    it('replaces the transport on restart, closing the old one exactly once', async () => {
+        const first = createFakeTransport();
+        const second = createFakeTransport();
+        const transports = [first, second];
+        const provider = createRestartableProvider(() => transports.shift().provider);
+        await connect(provider);
+        provider.restart();
+        await settle();
+        expect(first.disconnect).toHaveBeenCalledOnce();
+        expect(second.disconnect).not.toHaveBeenCalled();
+    });
+    it('keeps the consumer connection alive across a restart', async () => {
+        const first = createFakeTransport();
+        const second = createFakeTransport();
+        const transports = [first, second];
+        const provider = createRestartableProvider(() => transports.shift().provider);
+        const { connection, messages } = await connect(provider);
+        provider.restart();
+        await settle();
+        connection.send({ jsonrpc: '2.0', id: 2, method: 'system_chain', params: [] });
+        second.emit({ jsonrpc: '2.0', id: 2, result: 'kusama' });
+        expect(second.send).toHaveBeenCalledOnce();
+        expect(messages).toContainEqual({ jsonrpc: '2.0', id: 2, result: 'kusama' });
+    });
+    it('reports the active chainHead follows as stopped so the client re-follows', async () => {
+        const first = createFakeTransport();
+        const second = createFakeTransport();
+        const transports = [first, second];
+        const provider = createRestartableProvider(() => transports.shift().provider);
+        const { connection, messages } = await connect(provider);
+        connection.send({ jsonrpc: '2.0', id: 3, method: 'chainHead_v1_follow', params: [true] });
+        first.emit({ jsonrpc: '2.0', id: 3, result: 'follow-1' });
+        provider.restart();
+        await settle();
+        expect(messages).toContainEqual(expect.objectContaining({
+            method: 'chainHead_v1_follow',
+            params: { subscription: 'follow-1', result: { event: 'stop', internal: true } },
+        }));
+    });
+    it('re-establishes a legacy subscription on the new transport', async () => {
+        const first = createFakeTransport();
+        const second = createFakeTransport();
+        const transports = [first, second];
+        const provider = createRestartableProvider(() => transports.shift().provider);
+        const { connection, messages } = await connect(provider);
+        const subscribe = { jsonrpc: '2.0', id: 4, method: 'state_subscribeStorage', params: [['0x00']] };
+        connection.send(subscribe);
+        first.emit({ jsonrpc: '2.0', id: 4, result: 'sub-1' });
+        provider.restart();
+        await settle();
+        expect(second.send).toHaveBeenCalledWith(expect.objectContaining({ method: 'state_subscribeStorage' }));
+        // The consumer only ever learned `sub-1`, so notifications from the new
+        // transport's id have to arrive back under the one it is routing on.
+        second.emit({ jsonrpc: '2.0', id: 4, result: 'sub-2' });
+        second.emit({
+            jsonrpc: '2.0',
+            method: 'state_storage',
+            params: { subscription: 'sub-2', result: '0x01' },
+        });
+        expect(messages).toContainEqual(expect.objectContaining({ params: { subscription: 'sub-1', result: '0x01' } }));
+        // The re-confirmation is the consumer's own subscribe id — surfacing it
+        // would look like a second, unasked-for response.
+        expect(messages.filter(message => 'result' in message && message.result === 'sub-2')).toHaveLength(0);
+    });
+    it('retries instead of wedging when the transport factory throws', async () => {
+        const transport = createFakeTransport();
+        const created = vi.fn(() => {
+            if (created.mock.calls.length === 1)
+                throw new Error('no WebSocket class');
+            return transport.provider;
+        });
+        const provider = createRestartableProvider(created);
+        const { connection, messages } = await connect(provider);
+        connection.send({ jsonrpc: '2.0', id: 5, method: 'system_chain', params: [] });
+        transport.emit({ jsonrpc: '2.0', id: 5, result: 'polkadot' });
+        expect(created).toHaveBeenCalledTimes(2);
+        expect(transport.send).toHaveBeenCalledOnce();
+        expect(messages).toContainEqual({ jsonrpc: '2.0', id: 5, result: 'polkadot' });
+    });
+    it('does not replay subscriptions into a transport the factory failed to build', async () => {
+        const first = createFakeTransport();
+        const second = createFakeTransport();
+        const transports = [first, null, second];
+        const provider = createRestartableProvider(() => {
+            const next = transports.shift();
+            if (!next)
+                throw new Error('transport unavailable');
+            return next.provider;
+        });
+        const { connection } = await connect(provider);
+        const subscribe = { jsonrpc: '2.0', id: 6, method: 'state_subscribeStorage', params: [['0x00']] };
+        connection.send(subscribe);
+        first.emit({ jsonrpc: '2.0', id: 6, result: 'sub-1' });
+        provider.restart();
+        // Two windows: the failed attempt in between pushes the next one out by a
+        // further backoff step.
+        await settle();
+        await settle();
+        expect(second.send).toHaveBeenCalledTimes(1);
+        expect(second.send).toHaveBeenCalledWith(expect.objectContaining({ method: 'state_subscribeStorage' }));
+    });
+    it('is a no-op before anything has connected', async () => {
+        const transport = createFakeTransport();
+        const created = vi.fn(() => transport.provider);
+        const provider = createRestartableProvider(created);
+        provider.restart();
+        await connect(provider);
+        expect(created).toHaveBeenCalledOnce();
+    });
+    it('forwards pause and resume to a pausable transport', async () => {
+        const transport = createFakeTransport({ pausable: true });
+        const provider = createRestartableProvider(() => transport.provider);
+        await connect(provider);
+        provider.pause();
+        provider.resume();
+        expect(transport.pause).toHaveBeenCalledOnce();
+        expect(transport.resume).toHaveBeenCalledOnce();
+    });
+    it('pauses a transport built while paused before handing it the message callback', async () => {
+        const pause = vi.fn();
+        const pausedAtInvocation = [];
+        const transport = Object.assign(() => {
+            pausedAtInvocation.push(pause.mock.calls.length > 0);
+            return { send: vi.fn(), disconnect: vi.fn() };
+        }, { pause, resume: vi.fn() });
+        const provider = createRestartableProvider(() => transport);
+        provider.pause();
+        await connect(provider);
+        expect(pausedAtInvocation).toEqual([true]);
+    });
+    it('brings a transport built while paused up paused', async () => {
+        const first = createFakeTransport({ pausable: true });
+        const second = createFakeTransport({ pausable: true });
+        const transports = [first, second];
+        const provider = createRestartableProvider(() => transports.shift().provider);
+        await connect(provider);
+        provider.pause();
+        provider.restart();
+        await settle();
+        expect(second.pause).toHaveBeenCalledOnce();
+    });
+    it('tolerates pause and resume on a transport that cannot pause', async () => {
+        const transport = createFakeTransport();
+        const provider = createRestartableProvider(() => transport.provider);
+        await connect(provider);
+        expect(() => {
+            provider.pause();
+            provider.resume();
+        }).not.toThrow();
+    });
+});

package/dist/restartableProviderWsIntegration.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/restartableProviderWsIntegration.spec.js

@@ -0,0 +1,80 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRestartableProvider } from './restartableProvider.js';
+import { createWsJsonRpcProvider } from './wsProvider.js';
+class FakeWebSocket {
+    static instances = [];
+    sent = [];
+    url;
+    listeners = new Map();
+    constructor(url) {
+        this.url = url;
+        FakeWebSocket.instances.push(this);
+    }
+    addEventListener(type, listener) {
+        const forType = this.listeners.get(type) ?? new Set();
+        forType.add(listener);
+        this.listeners.set(type, forType);
+    }
+    removeEventListener(type, listener) {
+        this.listeners.get(type)?.delete(listener);
+    }
+    send(data) {
+        this.sent.push(data);
+    }
+    close() {
+        this.emit('close', { type: 'close' });
+    }
+    open() {
+        this.emit('open', { type: 'open' });
+    }
+    deliver(message) {
+        this.emit('message', { data: JSON.stringify(message) });
+    }
+    requests(method) {
+        return this.sent.map(raw => JSON.parse(raw)).filter(message => message.method === method);
+    }
+    emit(type, event) {
+        for (const listener of [...(this.listeners.get(type) ?? [])])
+            listener(event);
+    }
+}
+const subscribe = { jsonrpc: '2.0', id: 1, method: 'state_subscribeStorage', params: [['0x00']] };
+// The proxy schedules each connect attempt on a timer, and a restart lands on
+// its reconnect backoff — one window covers both.
+const settle = () => vi.advanceTimersByTimeAsync(1_000);
+describe('createRestartableProvider × createWsJsonRpcProvider', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        FakeWebSocket.instances.length = 0;
+    });
+    afterEach(() => vi.useRealTimers());
+    it('re-establishes a legacy subscription exactly once on the new socket', async () => {
+        const provider = createRestartableProvider(() => createWsJsonRpcProvider({
+            endpoints: ['wss://example.test'],
+            websocketClass: FakeWebSocket,
+        }));
+        const messages = [];
+        const connection = provider(message => messages.push(message));
+        await settle();
+        const first = FakeWebSocket.instances[0];
+        first.open();
+        connection.send(subscribe);
+        first.deliver({ jsonrpc: '2.0', id: 1, result: 'sub-1' });
+        provider.restart();
+        await settle();
+        const second = FakeWebSocket.instances[1];
+        second.open();
+        // Twice would leave the second subId subscribed server-side with nothing
+        // holding it: the ws proxy drops the duplicate response, so neither replay
+        // layer ever learns that id and neither will unsubscribe it.
+        expect(second.requests('state_subscribeStorage')).toHaveLength(1);
+        // And the consumer keeps routing on the subId it was given.
+        second.deliver({ jsonrpc: '2.0', id: 1, result: 'sub-2' });
+        second.deliver({
+            jsonrpc: '2.0',
+            method: 'state_storage',
+            params: { subscription: 'sub-2', result: '0x01' },
+        });
+        expect(messages).toContainEqual(expect.objectContaining({ params: { subscription: 'sub-1', result: '0x01' } }));
+    });
+});

package/dist/subscriptionReplayProvider.js

@@ -69,16 +69,17 @@ export const withSubscriptionReplay = (provider, onReconnect) => onMessage => {
         onMessage(message);
     });
     const unsubReconnect = onReconnect(() => {
-        // Replay unconfirmed subscribes first: their `reconnectFor === null`, so
-        // they're disjoint from the entries inserted by the active-replay loop
-        // below (which all carry a non-null `reconnectFor`).
-        for (const [, pending] of pendingSubscriptions) {
-            if (pending.reconnectFor === null)
-                conn.send(pending.payload);
-        }
-        // Replay confirmed subscriptions: the server returns a fresh subId, which
-        // we map back to the consumer's stable subId.
+        // Only confirmed subscriptions are replayed. An unconfirmed subscribe is
+        // still owned by the transport underneath — every provider this wraps is
+        // built on `getSyncProvider`, whose proxy re-sends its in-flight requests
+        // across a reconnect and buffers them until the next one is up — so
+        // re-sending it here would put the same subscribe on the wire twice and
+        // leave the second, unmatched subId subscribed server-side forever.
+        // Its pending entry is kept: the response still has to be recognised.
         for (const [consumerSubId, sub] of activeSubscriptions) {
+            // The server returns a fresh subId, which we map back to the consumer's
+            // stable subId. `reconnectFor` keeps these entries apart from the
+            // unconfirmed ones already in the map, which all carry null.
             pendingSubscriptions.set(sub.id, { payload: sub.payload, reconnectFor: consumerSubId });
             conn.send(sub.payload);
         }

package/dist/subscriptionReplayProvider.spec.js

@@ -61,7 +61,7 @@ describe('withSubscriptionReplay', () => {
         control.triggerReconnect();
         expect(mock.send).not.toHaveBeenCalled();
     });
-    it('replays pending subscriptions (no server response yet) on reconnect', () => {
+    it('leaves unconfirmed subscribes to the transport underneath on reconnect', () => {
         const mock = createMockProvider();
         const control = createReconnectControl();
         const conn = withSubscriptionReplay(mock.provider, control.onReconnect)(vi.fn());
@@ -70,6 +70,24 @@ describe('withSubscriptionReplay', () => {
         // intentionally no simulateMessage — subscription not confirmed by server
         mock.send.mockClear();
         control.triggerReconnect();
+        // `getSyncProvider`'s proxy re-sends it on its own; a second copy from here
+        // would leave an unmatched subscription live on the server.
+        expect(mock.send).not.toHaveBeenCalled();
+    });
+    it('still recognises the response to an unconfirmed subscribe the transport re-sent', () => {
+        const mock = createMockProvider();
+        const control = createReconnectControl();
+        const onMessage = vi.fn();
+        const conn = withSubscriptionReplay(mock.provider, control.onReconnect)(onMessage);
+        const subscribeMsg = req(1, 'statement_subscribeStatement');
+        conn.send(subscribeMsg);
+        control.triggerReconnect();
+        // The transport's own replay puts it back on the wire; the answer arrives
+        // against the id we are still holding a pending entry for.
+        mock.simulateMessage(res(1, 'sub-1'));
+        mock.send.mockClear();
+        control.triggerReconnect();
+        expect(onMessage).toHaveBeenCalledWith(res(1, 'sub-1'));
         expect(mock.send).toHaveBeenCalledWith(subscribeMsg);
     });
     it('replays active subscriptions on reconnect', () => {

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { JsonRpcProvider, PolkadotClient } from 'polkadot-api';
+import type { RestartableJsonRpcProvider } from './restartableProvider.js';
 export type ChainConfig = {
     genesisHash: string;
 };
@@ -9,5 +10,5 @@ export type BranchedProvider = {
 export type PooledClient = {
     client: PolkadotClient;
     provider: BranchedProvider;
-    rootProvider: JsonRpcProvider;
+    rootProvider: RestartableJsonRpcProvider;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@novasamatech/host-substrate-chain-connection",
   "type": "module",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Chain connection pool with ref counting and provider branching for Polkadot API",
   "license": "Apache-2.0",
   "repository": {
@@ -25,7 +25,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@novasamatech/storage-adapter": "0.10.1",
+    "@novasamatech/storage-adapter": "0.10.2",
     "@polkadot-api/ws-provider": "^0.9.0",
     "@polkadot-api/json-rpc-provider": "^0.2.0",
     "@polkadot-api/json-rpc-provider-proxy": "^0.4.0",