@replit/river 0.6.3 → 0.7.0

package/dist/transport/impls/ws/connection.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="ws" />
+import { TransportClientId } from '../../message';
+import { Connection, Transport } from '../../transport';
+import WebSocket from 'isomorphic-ws';
+export declare class WebSocketConnection extends Connection {
+    ws: WebSocket;
+    constructor(transport: Transport<WebSocketConnection>, connectedTo: TransportClientId, ws: WebSocket);
+    send(payload: Uint8Array): boolean;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/transport/impls/ws/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../../transport/impls/ws/connection.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,SAAS,MAAM,eAAe,CAAC;AAEtC,qBAAa,mBAAoB,SAAQ,UAAU;IACjD,EAAE,EAAE,SAAS,CAAC;gBAGZ,SAAS,EAAE,SAAS,CAAC,mBAAmB,CAAC,EACzC,WAAW,EAAE,iBAAiB,EAC9B,EAAE,EAAE,SAAS;IAQf,IAAI,CAAC,OAAO,EAAE,UAAU;IASlB,KAAK;CAGZ"}

package/dist/transport/impls/ws/connection.js

@@ -0,0 +1,22 @@
+import { Connection } from '../../transport';
+export class WebSocketConnection extends Connection {
+    ws;
+    constructor(transport, connectedTo, ws) {
+        super(transport, connectedTo);
+        this.ws = ws;
+        ws.binaryType = 'arraybuffer';
+        this.ws.onmessage = (msg) => this.onMessage(msg.data);
+    }
+    send(payload) {
+        if (this.ws.readyState === this.ws.OPEN) {
+            this.ws.send(payload);
+            return true;
+        }
+        else {
+            return false;
+        }
+    }
+    async close() {
+        this.ws.close();
+    }
+}

package/dist/transport/impls/ws/server.d.ts

@@ -0,0 +1,19 @@
+import { Codec } from '../../../codec';
+import { TransportClientId } from '../../message';
+import { Transport } from '../../transport';
+import { Server } from 'ws';
+import { WebSocketConnection } from './connection';
+interface Options {
+    codec: Codec;
+}
+export declare class WebSocketServerTransport extends Transport<WebSocketConnection> {
+    wss: Server;
+    clientId: TransportClientId;
+    constructor(wss: Server, clientId: TransportClientId, providedOptions?: Partial<Options>);
+    setupConnectionStatusListeners(): void;
+    createNewConnection(to: string): Promise<void>;
+    destroy(): Promise<void>;
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/transport/impls/ws/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../transport/impls/ws/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAkB,MAAM,gBAAgB,CAAC;AAEvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,UAAU,OAAO;IACf,KAAK,EAAE,KAAK,CAAC;CACd;AAMD,qBAAa,wBAAyB,SAAQ,SAAS,CAAC,mBAAmB,CAAC;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,iBAAiB,CAAC;gBAG1B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,iBAAiB,EAC3B,eAAe,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;IASpC,8BAA8B,IAAI,IAAI;IA8BhC,mBAAmB,CAAC,EAAE,EAAE,MAAM;IAM9B,OAAO;IAKP,KAAK;CAIZ"}

package/dist/transport/impls/ws/server.js

@@ -0,0 +1,53 @@
+import { NaiveJsonCodec } from '../../../codec';
+import { log } from '../../../logging';
+import { Transport } from '../../transport';
+import { WebSocketConnection } from './connection';
+const defaultOptions = {
+    codec: NaiveJsonCodec,
+};
+export class WebSocketServerTransport extends Transport {
+    wss;
+    clientId;
+    constructor(wss, clientId, providedOptions) {
+        const options = { ...defaultOptions, ...providedOptions };
+        super(options.codec, clientId);
+        this.wss = wss;
+        this.clientId = clientId;
+        this.setupConnectionStatusListeners();
+    }
+    setupConnectionStatusListeners() {
+        this.wss.on('connection', (ws) => {
+            let conn = undefined;
+            ws.onmessage = (msg) => {
+                const parsedMsg = this.parseMsg(msg.data);
+                if (parsedMsg) {
+                    conn = new WebSocketConnection(this, parsedMsg.from, ws);
+                    this.onConnect(conn);
+                    this.handleMsg(parsedMsg);
+                }
+            };
+            // close is always emitted, even on error, ok to do cleanup here
+            ws.onclose = () => {
+                if (conn) {
+                    this.onDisconnect(conn);
+                }
+            };
+            ws.onerror = (msg) => {
+                log?.warn(`${this.clientId} -- ws error from client ${conn?.connectedTo ?? 'unknown'}: ${msg}`);
+            };
+        });
+    }
+    async createNewConnection(to) {
+        const err = `${this.clientId} -- failed to send msg to ${to}, client probably dropped`;
+        log?.warn(err);
+        return;
+    }
+    async destroy() {
+        super.destroy();
+        this.wss.close();
+    }
+    async close() {
+        super.close();
+        this.wss.close();
+    }
+}

package/dist/transport/impls/ws/ws.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ws.test.d.ts.map

package/dist/transport/impls/ws/ws.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.test.d.ts","sourceRoot":"","sources":["../../../../transport/impls/ws/ws.test.ts"],"names":[],"mappings":""}

package/dist/transport/impls/ws/ws.test.js

@@ -0,0 +1,97 @@
+import http from 'http';
+import { describe, test, expect, afterAll } from 'vitest';
+import { createWebSocketServer, createWsTransports, createDummyTransportMessage, onServerReady, createLocalWebSocketClient, } from '../../../testUtils';
+import { msg, waitForMessage } from '../..';
+import { WebSocketServerTransport } from './server';
+import { WebSocketClientTransport } from './client';
+describe('sending and receiving across websockets works', async () => {
+    const server = http.createServer();
+    const port = await onServerReady(server);
+    const wss = await createWebSocketServer(server);
+    afterAll(() => {
+        wss.clients.forEach((socket) => {
+            socket.close();
+        });
+        server.close();
+    });
+    test('basic send/receive', async () => {
+        const [clientTransport, serverTransport] = createWsTransports(port, wss);
+        const msg = createDummyTransportMessage();
+        clientTransport.send(msg);
+        return expect(waitForMessage(serverTransport, (recv) => recv.id === msg.id)).resolves.toStrictEqual(msg.payload);
+    });
+    test('sending respects to/from fields', async () => {
+        const makeDummyMessage = (from, to, message) => {
+            return msg(from, to, 'service', 'proc', 'stream', {
+                msg: message,
+            });
+        };
+        const clientId1 = 'client1';
+        const clientId2 = 'client2';
+        const serverId = 'SERVER';
+        const serverTransport = new WebSocketServerTransport(wss, serverId);
+        const initClient = async (id) => {
+            const client = new WebSocketClientTransport(() => createLocalWebSocketClient(port), id, 'SERVER');
+            const initMsg = makeDummyMessage(id, serverId, 'hello server');
+            client.send(initMsg);
+            await expect(waitForMessage(serverTransport, (recv) => recv.id === initMsg.id)).resolves.toStrictEqual(initMsg.payload);
+            return client;
+        };
+        const client1 = await initClient(clientId1);
+        const client2 = await initClient(clientId2);
+        // sending messages from server to client shouldn't leak between clients
+        const msg1 = makeDummyMessage('SERVER', 'client1', 'hello client1');
+        const msg2 = makeDummyMessage('SERVER', 'client2', 'hello client1');
+        const promises = Promise.all([
+            // true means reject if we receive any message that isn't the one we are expecting
+            waitForMessage(client2, (recv) => recv.id === msg2.id, true),
+            waitForMessage(client1, (recv) => recv.id === msg1.id, true),
+        ]);
+        serverTransport.send(msg1);
+        serverTransport.send(msg2);
+        await expect(promises).resolves.toStrictEqual([msg1.payload, msg2.payload]);
+    });
+});
+describe('retry logic', async () => {
+    const server = http.createServer();
+    const port = await onServerReady(server);
+    const wss = await createWebSocketServer(server);
+    afterAll(() => {
+        wss.clients.forEach((socket) => {
+            socket.close();
+        });
+        server.close();
+    });
+    // TODO: right now, we only test client-side disconnects, we probably
+    // need to also write tests for server-side crashes (but this involves clearing/restoring state)
+    // not going to worry about this rn but for future
+    test('ws transport is recreated after clean disconnect', async () => {
+        const [clientTransport, serverTransport] = createWsTransports(port, wss);
+        const msg1 = createDummyTransportMessage();
+        const msg2 = createDummyTransportMessage();
+        clientTransport.send(msg1);
+        await expect(waitForMessage(serverTransport, (recv) => recv.id === msg1.id)).resolves.toStrictEqual(msg1.payload);
+        clientTransport.connections.forEach((conn) => conn.ws.close());
+        clientTransport.send(msg2);
+        return expect(waitForMessage(serverTransport, (recv) => recv.id === msg2.id)).resolves.toStrictEqual(msg2.payload);
+    });
+    test('ws transport is recreated after unclean disconnect', async () => {
+        const [clientTransport, serverTransport] = createWsTransports(port, wss);
+        const msg1 = createDummyTransportMessage();
+        const msg2 = createDummyTransportMessage();
+        clientTransport.send(msg1);
+        await expect(waitForMessage(serverTransport, (recv) => recv.id === msg1.id)).resolves.toStrictEqual(msg1.payload);
+        clientTransport.connections.forEach((conn) => conn.ws.terminate());
+        clientTransport.send(msg2);
+        return expect(waitForMessage(serverTransport, (recv) => recv.id === msg2.id)).resolves.toStrictEqual(msg2.payload);
+    });
+    test('ws transport is not recreated after destroy', async () => {
+        const [clientTransport, serverTransport] = createWsTransports(port, wss);
+        const msg1 = createDummyTransportMessage();
+        const msg2 = createDummyTransportMessage();
+        clientTransport.send(msg1);
+        await expect(waitForMessage(serverTransport, (recv) => recv.id === msg1.id)).resolves.toStrictEqual(msg1.payload);
+        clientTransport.destroy();
+        return expect(() => clientTransport.send(msg2)).toThrow(new Error('transport is destroyed, cant send'));
+    });
+});

package/dist/transport/impls/ws.d.ts

@@ -29,7 +29,7 @@ export declare class WebSocketTransport extends Transport {
      * A flag indicating whether the transport has been destroyed.
      * A destroyed transport will not attempt to reconnect and cannot be used again.
      */
-    destroyed: boolean;
+    state: 'open' | 'closed' | 'destroyed';
     /**
      * An ongoing reconnect attempt if it exists. When the attempt finishes, it contains a
      * {@link WebSocketResult} object when a connection is established or an error occurs.
@@ -59,9 +59,13 @@ export declare class WebSocketTransport extends Transport {
      */
     send(msg: OpaqueTransportMessage): MessageId;
     /**
-     * Destroys the WebSocket transport and marks it as unusable.
+     * Closes the WebSocket transport. Any messages sent while the transport is closed will be silently discarded.
      */
     close(): Promise<void | undefined>;
+    /**
+     * Destroys the WebSocket transport. Any messages sent while the transport is closed will throw an error.
+     */
+    destroy(): Promise<void | undefined>;
 }
 export {};
 //# sourceMappingURL=ws.d.ts.map

package/dist/transport/impls/ws.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../../transport/impls/ws.ts"],"names":[],"mappings":";AAAA,OAAO,SAAS,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,OAAO,EACL,SAAS,EACT,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,UAAU,OAAO;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,aAAa,GAAG,MAAM,CAAC;CACpC;AAQD,KAAK,eAAe,GAAG;IAAE,EAAE,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C;;OAEG;IACH,QAAQ,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC;IACnC,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAE5C;;;OAGG;IACH,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAE5B;;;;;OAKG;gBAED,QAAQ,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,EAClC,QAAQ,EAAE,iBAAiB,EAC3B,eAAe,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;IAWpC;;OAEG;YACW,UAAU;IAmExB;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,sBAAsB,GAAG,SAAS;IAyB5C;;OAEG;IACG,KAAK;CAKZ"}
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../../transport/impls/ws.ts"],"names":[],"mappings":";AAAA,OAAO,SAAS,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,OAAO,EACL,SAAS,EACT,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,UAAU,OAAO;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,UAAU,EAAE,aAAa,GAAG,MAAM,CAAC;CACpC;AAQD,KAAK,eAAe,GAAG;IAAE,EAAE,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C;;OAEG;IACH,QAAQ,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC;IACnC,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC;IAEvC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAE5C;;;OAGG;IACH,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAE5B;;;;;OAKG;gBAED,QAAQ,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,EAClC,QAAQ,EAAE,iBAAiB,EAC3B,eAAe,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;IAWpC;;OAEG;YACW,UAAU;IAuExB;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,sBAAsB,GAAG,SAAS;IA4B5C;;OAEG;IACG,KAAK;IAMX;;OAEG;IACG,OAAO;CAKd"}

package/dist/transport/impls/ws.js

@@ -22,7 +22,7 @@ export class WebSocketTransport extends Transport {
      * A flag indicating whether the transport has been destroyed.
      * A destroyed transport will not attempt to reconnect and cannot be used again.
      */
-    destroyed;
+    state;
     /**
      * An ongoing reconnect attempt if it exists. When the attempt finishes, it contains a
      * {@link WebSocketResult} object when a connection is established or an error occurs.
@@ -42,7 +42,7 @@ export class WebSocketTransport extends Transport {
     constructor(wsGetter, clientId, providedOptions) {
         const options = { ...defaultOptions, ...providedOptions };
         super(options.codec, clientId);
-        this.destroyed = false;
+        this.state = 'open';
         this.wsGetter = wsGetter;
         this.options = options;
         this.sendQueue = [];
@@ -52,6 +52,9 @@ export class WebSocketTransport extends Transport {
      * Begins a new attempt to establish a WebSocket connection.
      */
     async tryConnect() {
+        if (this.state !== 'open') {
+            return;
+        }
         // wait until it's ready or we get an error
         this.reconnectPromise ??= new Promise(async (resolve) => {
             log?.info(`${this.clientId} -- establishing a new websocket`);
@@ -113,11 +116,15 @@ export class WebSocketTransport extends Transport {
      */
     send(msg) {
         const id = msg.id;
-        if (this.destroyed) {
+        if (this.state === 'destroyed') {
             const err = 'ws is destroyed, cant send';
-            log?.error(err);
+            log?.error(err + `: ${JSON.stringify(msg)}`);
             throw new Error(err);
         }
+        else if (this.state === 'closed') {
+            log?.info(`ws is closed, discarding msg: ${JSON.stringify(msg)}`);
+            return msg.id;
+        }
         this.sendBuffer.set(id, msg);
         if (this.ws && this.ws.readyState === this.ws.OPEN) {
             log?.info(`${this.clientId} -- sending ${JSON.stringify(msg)}`);
@@ -131,11 +138,19 @@ export class WebSocketTransport extends Transport {
         return id;
     }
     /**
-     * Destroys the WebSocket transport and marks it as unusable.
+     * Closes the WebSocket transport. Any messages sent while the transport is closed will be silently discarded.
      */
     async close() {
-        log?.info('manually closed ws');
-        this.destroyed = true;
+        log?.info('closed ws transport');
+        this.state = 'closed';
+        return this.ws?.close();
+    }
+    /**
+     * Destroys the WebSocket transport. Any messages sent while the transport is closed will throw an error.
+     */
+    async destroy() {
+        log?.info('destroyed ws transport');
+        this.state = 'destroyed';
         return this.ws?.close();
     }
 }

package/dist/transport/impls/ws.test.js

@@ -52,13 +52,13 @@ describe('retry logic', async () => {
         clientTransport.send(msg2);
         return expect(waitForMessage(serverTransport, (recv) => recv.id === msg2.id)).resolves.toStrictEqual(msg2.payload);
     });
-    test('ws transport is not recreated after manually closing', async () => {
+    test('ws transport is not recreated after destroy', async () => {
         const [clientTransport, serverTransport] = createWsTransports(port, wss);
         const msg1 = createDummyTransportMessage();
         const msg2 = createDummyTransportMessage();
         clientTransport.send(msg1);
         await expect(waitForMessage(serverTransport, (recv) => recv.id === msg1.id)).resolves.toStrictEqual(msg1.payload);
-        clientTransport.close();
+        clientTransport.destroy();
         return expect(() => clientTransport.send(msg2)).toThrow(new Error('ws is destroyed, cant send'));
     });
 });

package/dist/transport/index.d.ts

@@ -1,6 +1,6 @@
 import { OpaqueTransportMessage } from './message';
-import { Transport } from './types';
-export { Transport } from './types';
+import { Connection, Transport } from './transport';
+export { Transport } from './transport';
 export { TransportMessageSchema, OpaqueTransportMessageSchema, msg, reply, } from './message';
 export type { TransportMessage, MessageId, OpaqueTransportMessage, TransportClientId, } from './message';
 /**
@@ -9,5 +9,5 @@ export type { TransportMessage, MessageId, OpaqueTransportMessage, TransportClie
  * @param filter - An optional filter function to apply to the received messages.
  * @returns A promise that resolves with the payload of the first message that passes the filter.
  */
-export declare function waitForMessage(t: Transport, filter?: (msg: OpaqueTransportMessage) => boolean): Promise<unknown>;
+export declare function waitForMessage(t: Transport<Connection>, filter?: (msg: OpaqueTransportMessage) => boolean, rejectMismatch?: boolean): Promise<unknown>;
 //# sourceMappingURL=index.d.ts.map

package/dist/transport/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../transport/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGpC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,GAAG,EACH,KAAK,GACN,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,gBAAgB,EAChB,SAAS,EACT,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAEnB;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,CAAC,EAAE,SAAS,EACZ,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,sBAAsB,KAAK,OAAO,oBAYlD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../transport/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGpD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,GAAG,EACH,KAAK,GACN,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,gBAAgB,EAChB,SAAS,EACT,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAEnB;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,EACxB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,sBAAsB,KAAK,OAAO,EACjD,cAAc,CAAC,EAAE,OAAO,oBAczB"}

package/dist/transport/index.js

@@ -1,5 +1,5 @@
 // re-export
-export { Transport } from './types';
+export { Transport } from './transport';
 export { TransportMessageSchema, OpaqueTransportMessageSchema, msg, reply, } from './message';
 /**
  * Waits for a message from the transport.
@@ -7,13 +7,16 @@ export { TransportMessageSchema, OpaqueTransportMessageSchema, msg, reply, } fro
  * @param filter - An optional filter function to apply to the received messages.
  * @returns A promise that resolves with the payload of the first message that passes the filter.
  */
-export async function waitForMessage(t, filter) {
-    return new Promise((resolve, _reject) => {
+export async function waitForMessage(t, filter, rejectMismatch) {
+    return new Promise((resolve, reject) => {
         function onMessage(msg) {
             if (!filter || filter?.(msg)) {
                 resolve(msg.payload);
                 t.removeMessageListener(onMessage);
             }
+            else if (rejectMismatch) {
+                reject(new Error('message didnt match the filter'));
+            }
         }
         t.addMessageListener(onMessage);
     });

package/dist/transport/message.d.ts

@@ -44,6 +44,9 @@ export declare const TransportAckSchema: import("@sinclair/typebox").TObject<{
         ack: import("@sinclair/typebox").TString;
     }>;
 }>;
+export declare const ControlMessagePayloadSchema: import("@sinclair/typebox").TObject<{
+    type: import("@sinclair/typebox").TLiteral<"CLOSE">;
+}>;
 /**
  * Defines the schema for an opaque transport message that is agnostic to any
  * procedure/service.
@@ -80,7 +83,7 @@ export type MessageId = string;
  * @template T - The type of the opaque payload.
  */
 export type OpaqueTransportMessage = TransportMessage<unknown>;
-export type TransportClientId = 'SERVER' | string;
+export type TransportClientId = string;
 /**
  * Creates a transport message with the given parameters. You shouldn't need to call this manually unless
  * you're writing a test.

package/dist/transport/message.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../transport/message.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGlD;;;;;;GAMG;AACH,0BAAkB,YAAY;IAC5B,MAAM,IAAS;IACf,aAAa,IAAS;IACtB,eAAe,IAAS;CACzB;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;EAU/B,CAAC;AAEL;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;EAI9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;EAExC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAC1B,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACzE;IACF,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC/D,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,MAAM,CAAC;AAElD;;;;;;;;;;GAUG;AACH,wBAAgB,GAAG,CAAC,OAAO,SAAS,MAAM,EACxC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,GACf,gBAAgB,CAAC,OAAO,CAAC,CAW3B;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,OAAO,SAAS,MAAM,EAC1C,GAAG,EAAE,sBAAsB,EAC3B,QAAQ,EAAE,OAAO,GAChB,gBAAgB,CAAC,OAAO,CAAC,CAQ3B;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAIzD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAK1D"}
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../transport/message.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGlD;;;;;;GAMG;AACH,0BAAkB,YAAY;IAC5B,MAAM,IAAS;IACf,aAAa,IAAS;IACtB,eAAe,IAAS;CACzB;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;EAU/B,CAAC;AAEL;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;EAI9B,CAAC;AAEF,eAAO,MAAM,2BAA2B;;EAEtC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;EAExC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAC1B,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACzE;IACF,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC/D,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,wBAAgB,GAAG,CAAC,OAAO,SAAS,MAAM,EACxC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,GACf,gBAAgB,CAAC,OAAO,CAAC,CAW3B;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,OAAO,SAAS,MAAM,EAC1C,GAAG,EAAE,sBAAsB,EAC3B,QAAQ,EAAE,OAAO,GAChB,gBAAgB,CAAC,OAAO,CAAC,CAQ3B;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAIzD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAK1D"}

package/dist/transport/message.js

@@ -24,6 +24,9 @@ export const TransportMessageSchema = (t) => Type.Object({
 export const TransportAckSchema = TransportMessageSchema(Type.Object({
     ack: Type.String(),
 }));
+export const ControlMessagePayloadSchema = Type.Object({
+    type: Type.Literal('CLOSE'),
+});
 /**
  * Defines the schema for an opaque transport message that is agnostic to any
  * procedure/service.

package/dist/transport/transport.d.ts

@@ -0,0 +1,132 @@
+import { Codec } from '../codec/types';
+import { MessageId, OpaqueTransportMessage, TransportClientId } from './message';
+/**
+ * Abstract base for a connection between two nodes in a River network.
+ * A connection is responsible for sending and receiving messages on a 1:1
+ * basis between nodes.
+ * Connections can be reused across different transports.
+ * @abstract
+ */
+export declare abstract class Connection {
+    connectedTo: TransportClientId;
+    transport: Transport<Connection>;
+    constructor(transport: Transport<Connection>, connectedTo: TransportClientId);
+    onMessage(msg: Uint8Array): void;
+    abstract send(msg: Uint8Array): boolean;
+    abstract close(): Promise<void>;
+}
+export type TransportStatus = 'open' | 'closed' | 'destroyed';
+/**
+ * Abstract base for a transport layer for communication between nodes in a River network.
+ * A transport is responsible for handling the 1:n connection logic between nodes and
+ * delegating sending/receiving to connections.
+ * Any River transport methods need to implement this interface.
+ * @abstract
+ */
+export declare abstract class Transport<ConnType extends Connection> {
+    /**
+     * A flag indicating whether the transport has been destroyed.
+     * A destroyed transport will not attempt to reconnect and cannot be used again.
+     */
+    state: TransportStatus;
+    /**
+     * The {@link Codec} used to encode and decode messages.
+     */
+    codec: Codec;
+    /**
+     * The client ID of this transport.
+     */
+    clientId: TransportClientId;
+    /**
+     * The set of message handlers registered with this transport.
+     */
+    messageHandlers: Set<(msg: OpaqueTransportMessage) => void>;
+    /**
+     * An array of message IDs that are waiting to be sent over the WebSocket connection.
+     * This builds up if the WebSocket is down for a period of time.
+     */
+    sendQueue: Map<TransportClientId, Array<MessageId>>;
+    /**
+     * The buffer of messages that have been sent but not yet acknowledged.
+     */
+    sendBuffer: Map<MessageId, OpaqueTransportMessage>;
+    /**
+     * The map of {@link Connection}s managed by this transport.
+     */
+    connections: Map<TransportClientId, ConnType>;
+    /**
+     * Creates a new Transport instance.
+     * @param codec The codec used to encode and decode messages.
+     * @param clientId The client ID of this transport.
+     */
+    constructor(codec: Codec, clientId: TransportClientId);
+    /**
+     * Abstract method that sets up {@link onConnect}, and {@link onDisconnect} listeners.
+     * The downstream implementation needs to implement this.
+     */
+    abstract setupConnectionStatusListeners(): void;
+    /**
+     * Abstract method that creates a new {@link Connection} object. This should call
+     * {@link onConnect} when the connection is established. The downstream implementation needs to implement this.
+     * @param to The client ID of the node to connect to.
+     * @returns The new connection object.
+     */
+    abstract createNewConnection(to: TransportClientId): Promise<void>;
+    /**
+     * The downstream implementation needs to call this when a new connection is established.
+     * @param conn The connection object.
+     */
+    onConnect(conn: ConnType): void;
+    /**
+     * The downstream implementation needs to call this when a connection is closed.
+     * @param conn The connection object.
+     */
+    onDisconnect(conn: ConnType): void;
+    /**
+     * Handles a message received by this transport. Thin wrapper around {@link handleMsg} and {@link parseMsg}.
+     * @param msg The message to handle.
+     */
+    onMessage(msg: Uint8Array): void;
+    /**
+     * Parses a message from a Uint8Array into a {@link OpaqueTransportMessage}.
+     * @param msg The message to parse.
+     * @returns The parsed message, or null if the message is malformed or invalid.
+     */
+    protected parseMsg(msg: Uint8Array): OpaqueTransportMessage | null;
+    /**
+     * Called when a message is received by this transport.
+     * You generally shouldn't need to override this in downstream transport implementations.
+     * @param msg The received message.
+     */
+    protected handleMsg(msg: OpaqueTransportMessage | null): void;
+    /**
+     * Adds a message listener to this transport.
+     * @param handler The message handler to add.
+     */
+    addMessageListener(handler: (msg: OpaqueTransportMessage) => void): void;
+    /**
+     * Removes a message listener from this transport.
+     * @param handler The message handler to remove.
+     */
+    removeMessageListener(handler: (msg: OpaqueTransportMessage) => void): void;
+    /**
+     * Sends a message over this transport, delegating to the appropriate connection to actually
+     * send the message.
+     * @param msg The message to send.
+     * @returns The ID of the sent message.
+     */
+    send(msg: OpaqueTransportMessage): MessageId;
+    /**
+     * Default close implementation for transports. You should override this in the downstream
+     * implementation if you need to do any additional cleanup and call super.close() at the end.
+     * Closes the transport. Any messages sent while the transport is closed will be silently discarded.
+     */
+    close(): Promise<void>;
+    /**
+     * Default destroy implementation for transports. You should override this in the downstream
+     * implementation if you need to do any additional cleanup and call super.destroy() at the end.
+     * Destroys the transport. Any messages sent while the transport is destroyed will throw an error.
+     */
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../transport/transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,OAAO,EAEL,SAAS,EACT,sBAAsB,EAGtB,iBAAiB,EAGlB,MAAM,WAAW,CAAC;AAGnB;;;;;;GAMG;AACH,8BAAsB,UAAU;IAC9B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,SAAS,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;gBAG/B,SAAS,EAAE,SAAS,CAAC,UAAU,CAAC,EAChC,WAAW,EAAE,iBAAiB;IAMhC,SAAS,CAAC,GAAG,EAAE,UAAU;IAIzB,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO;IACvC,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAChC;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE9D;;;;;;GAMG;AACH,8BAAsB,SAAS,CAAC,QAAQ,SAAS,UAAU;IACzD;;;OAGG;IACH,KAAK,EAAE,eAAe,CAAC;IAEvB;;OAEG;IACH,KAAK,EAAE,KAAK,CAAC;IAEb;;OAEG;IACH,QAAQ,EAAE,iBAAiB,CAAC;IAE5B;;OAEG;IACH,eAAe,EAAE,GAAG,CAAC,CAAC,GAAG,EAAE,sBAAsB,KAAK,IAAI,CAAC,CAAC;IAE5D;;;OAGG;IACH,SAAS,EAAE,GAAG,CAAC,iBAAiB,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAEpD;;OAEG;IACH,UAAU,EAAE,GAAG,CAAC,SAAS,EAAE,sBAAsB,CAAC,CAAC;IAEnD;;OAEG;IACH,WAAW,EAAE,GAAG,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAAC;IAE9C;;;;OAIG;gBACS,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,iBAAiB;IAUrD;;;OAGG;IACH,QAAQ,CAAC,8BAA8B,IAAI,IAAI;IAE/C;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAElE;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,QAAQ;IAyBxB;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,QAAQ;IAM3B;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,UAAU;IAIzB;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,sBAAsB,GAAG,IAAI;IAmBlE;;;;OAIG;IACH,SAAS,CAAC,SAAS,CAAC,GAAG,EAAE,sBAAsB,GAAG,IAAI;IAgCtD;;;OAGG;IACH,kBAAkB,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,sBAAsB,KAAK,IAAI,GAAG,IAAI;IAIxE;;;OAGG;IACH,qBAAqB,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,sBAAsB,KAAK,IAAI,GAAG,IAAI;IAI3E;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,sBAAsB,GAAG,SAAS;IA4C5C;;;;OAIG;IACG,KAAK;IAUX;;;;OAIG;IACG,OAAO;CASd"}