@replit/river 0.3.1 → 0.5.0

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

@@ -1,19 +1,7 @@
 import http from 'http';
 import { describe, test, expect, afterAll } from 'vitest';
-import { createWebSocketServer, createWsTransports, onServerReady, } from '../../testUtils';
-import { nanoid } from 'nanoid';
+import { createWebSocketServer, createWsTransports, createDummyTransportMessage, onServerReady, } from '../../testUtils';
 import { waitForMessage } from '..';
-const getMsg = () => ({
-    id: nanoid(),
-    from: 'client',
-    to: 'SERVER',
-    serviceName: 'test',
-    procedureName: 'test',
-    payload: {
-        msg: 'cool',
-        test: Math.random(),
-    },
-});
 describe('sending and receiving across websockets works', async () => {
     const server = http.createServer();
     const port = await onServerReady(server);
@@ -26,7 +14,7 @@ describe('sending and receiving across websockets works', async () => {
     });
     test('basic send/receive', async () => {
         const [clientTransport, serverTransport] = createWsTransports(port, wss);
-        const msg = getMsg();
+        const msg = createDummyTransportMessage();
         clientTransport.send(msg);
         return expect(waitForMessage(serverTransport, (recv) => recv.id === msg.id)).resolves.toStrictEqual(msg.payload);
     });
@@ -46,8 +34,8 @@ describe('retry logic', async () => {
     // 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 = getMsg();
-        const msg2 = getMsg();
+        const msg1 = createDummyTransportMessage();
+        const msg2 = createDummyTransportMessage();
         clientTransport.send(msg1);
         await expect(waitForMessage(serverTransport, (recv) => recv.id === msg1.id)).resolves.toStrictEqual(msg1.payload);
         clientTransport.ws?.close();
@@ -56,8 +44,8 @@ describe('retry logic', async () => {
     });
     test('ws transport is recreated after unclean disconnect', async () => {
         const [clientTransport, serverTransport] = createWsTransports(port, wss);
-        const msg1 = getMsg();
-        const msg2 = getMsg();
+        const msg1 = createDummyTransportMessage();
+        const msg2 = createDummyTransportMessage();
         clientTransport.send(msg1);
         await expect(waitForMessage(serverTransport, (recv) => recv.id === msg1.id)).resolves.toStrictEqual(msg1.payload);
         clientTransport.ws?.terminate();
@@ -66,8 +54,8 @@ describe('retry logic', async () => {
     });
     test('ws transport is not recreated after manually closing', async () => {
         const [clientTransport, serverTransport] = createWsTransports(port, wss);
-        const msg1 = getMsg();
-        const msg2 = getMsg();
+        const msg1 = createDummyTransportMessage();
+        const msg2 = createDummyTransportMessage();
         clientTransport.send(msg1);
         await expect(waitForMessage(serverTransport, (recv) => recv.id === msg1.id)).resolves.toStrictEqual(msg1.payload);
         clientTransport.close();

package/dist/transport/index.d.ts

@@ -1,6 +1,13 @@
 import { OpaqueTransportMessage } from './message';
 import { Transport } from './types';
 export { Transport } from './types';
-export { TransportMessageSchema, OpaqueTransportMessageSchema, TransportAckSchema, msg, payloadToTransportMessage, ack, reply, } from './message';
-export type { TransportMessage, MessageId, OpaqueTransportMessage, TransportClientId, TransportMessageAck, } from './message';
+export { TransportMessageSchema, OpaqueTransportMessageSchema, msg, reply, } from './message';
+export type { TransportMessage, MessageId, OpaqueTransportMessage, TransportClientId, } from './message';
+/**
+ * Waits for a message from the transport.
+ * @param {Transport} t - The transport to listen to.
+ * @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>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/transport/index.js

@@ -1,6 +1,12 @@
 // re-export
 export { Transport } from './types';
-export { TransportMessageSchema, OpaqueTransportMessageSchema, TransportAckSchema, msg, payloadToTransportMessage, ack, reply, } from './message';
+export { TransportMessageSchema, OpaqueTransportMessageSchema, msg, reply, } from './message';
+/**
+ * Waits for a message from the transport.
+ * @param {Transport} t - The transport to listen to.
+ * @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) => {
         function onMessage(msg) {

package/dist/transport/message.d.ts

@@ -1,63 +1,121 @@
-import { type Static, TSchema } from '@sinclair/typebox';
+import { TSchema } from '@sinclair/typebox';
+/**
+ * Control flags for transport messages.
+ * An RPC message is coded with StreamOpenBit | StreamClosedBit.
+ * Streams are expected to start with StreamOpenBit sent and the client SHOULD send an empty
+ * message with StreamClosedBit to close the stream handler on the server, indicating that
+ * it will not be using the stream anymore.
+ */
+export declare const enum ControlFlags {
+    AckBit = 1,
+    StreamOpenBit = 2,
+    StreamClosedBit = 4
+}
+/**
+ * Generic Typebox schema for a transport message.
+ * @template T The type of the payload.
+ * @param {T} t The payload schema.
+ * @returns The transport message schema.
+ */
 export declare const TransportMessageSchema: <T extends TSchema>(t: T) => import("@sinclair/typebox").TObject<{
     id: import("@sinclair/typebox").TString;
-    replyTo: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     from: import("@sinclair/typebox").TString;
     to: import("@sinclair/typebox").TString;
     serviceName: import("@sinclair/typebox").TString;
     procedureName: import("@sinclair/typebox").TString;
+    streamId: import("@sinclair/typebox").TString;
+    controlFlags: import("@sinclair/typebox").TInteger;
     payload: T;
 }>;
+/**
+ * Defines the schema for a transport acknowledgement message. This is never constructed manually
+ * and is only used internally by the library for tracking inflight messages.
+ * @returns The transport message schema.
+ */
+export declare const TransportAckSchema: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    from: import("@sinclair/typebox").TString;
+    to: import("@sinclair/typebox").TString;
+    serviceName: import("@sinclair/typebox").TString;
+    procedureName: import("@sinclair/typebox").TString;
+    streamId: import("@sinclair/typebox").TString;
+    controlFlags: import("@sinclair/typebox").TInteger;
+    payload: import("@sinclair/typebox").TObject<{
+        ack: import("@sinclair/typebox").TString;
+    }>;
+}>;
+/**
+ * Defines the schema for an opaque transport message that is agnostic to any
+ * procedure/service.
+ * @returns The transport message schema.
+ */
 export declare const OpaqueTransportMessageSchema: import("@sinclair/typebox").TObject<{
     id: import("@sinclair/typebox").TString;
-    replyTo: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     from: import("@sinclair/typebox").TString;
     to: import("@sinclair/typebox").TString;
     serviceName: import("@sinclair/typebox").TString;
     procedureName: import("@sinclair/typebox").TString;
+    streamId: import("@sinclair/typebox").TString;
+    controlFlags: import("@sinclair/typebox").TInteger;
     payload: import("@sinclair/typebox").TUnknown;
 }>;
+/**
+ * Represents a transport message. This is the same type as {@link TransportMessageSchema} but
+ * we can't statically infer generics from generic Typebox schemas so we have to define it again here.
+ * @template Payload The type of the payload.
+ */
 export type TransportMessage<Payload extends Record<string, unknown> | unknown = Record<string, unknown>> = {
     id: string;
-    replyTo?: string;
     from: string;
     to: string;
     serviceName: string;
     procedureName: string;
+    streamId: string;
+    controlFlags: number;
     payload: Payload;
 };
 export type MessageId = string;
+/**
+ * A type alias for a transport message with an opaque payload.
+ * @template T - The type of the opaque payload.
+ */
 export type OpaqueTransportMessage = TransportMessage<unknown>;
 export type TransportClientId = 'SERVER' | string;
-export declare const TransportAckSchema: import("@sinclair/typebox").TObject<{
-    id: import("@sinclair/typebox").TString;
-    from: import("@sinclair/typebox").TString;
-    ack: import("@sinclair/typebox").TString;
-}>;
-export type TransportMessageAck = Static<typeof TransportAckSchema>;
-export declare function msg<Payload extends object>(from: string, to: string, service: string, proc: string, payload: Payload): {
-    id: string;
-    to: string;
-    from: string;
-    serviceName: string;
-    procedureName: string;
-    payload: Payload;
-};
-export declare function payloadToTransportMessage<Payload extends object>(payload: Payload): {
-    id: string;
-    to: string;
-    from: string;
-    serviceName: string;
-    procedureName: string;
-    payload: Payload;
-};
-export declare function ack(msg: OpaqueTransportMessage): TransportMessageAck;
-export declare function reply<Payload extends object>(msg: OpaqueTransportMessage, response: Payload): {
-    id: string;
-    replyTo: string;
-    to: string;
-    from: string;
-    payload: Payload;
-    serviceName: string;
-    procedureName: string;
-};
+/**
+ * Creates a transport message with the given parameters. You shouldn't need to call this manually unless
+ * you're writing a test.
+ * @param from The sender of the message.
+ * @param to The intended recipient of the message.
+ * @param service The name of the service the message is intended for.
+ * @param proc The name of the procedure the message is intended for.
+ * @param stream The ID of the stream the message is intended for.
+ * @param payload The payload of the message.
+ * @returns A TransportMessage object with the given parameters.
+ */
+export declare function msg<Payload extends object>(from: string, to: string, service: string, proc: string, stream: string, payload: Payload): TransportMessage<Payload>;
+/**
+ * Creates a new transport message as a response to the given message.
+ * @param msg The original message to respond to.
+ * @param response The payload of the response message.
+ * @returns A new transport message with appropriate to, from, and payload fields
+ */
+export declare function reply<Payload extends object>(msg: OpaqueTransportMessage, response: Payload): TransportMessage<Payload>;
+/**
+ * Checks if the given control flag (usually found in msg.controlFlag) is an ack message.
+ * @param controlFlag - The control flag to check.
+ * @returns True if the control flag contains the AckBit, false otherwise.
+ */
+export declare function isAck(controlFlag: number): boolean;
+/**
+ * Checks if the given control flag (usually found in msg.controlFlag) is a stream open message.
+ * @param controlFlag - The control flag to check.
+ * @returns True if the control flag contains the StreamOpenBit, false otherwise.
+ */
+export declare function isStreamOpen(controlFlag: number): boolean;
+/**
+ * Checks if the given control flag (usually found in msg.controlFlag) is a stream close message.
+ * @param controlFlag - The control flag to check.
+ * @returns True if the control flag contains the StreamCloseBit, false otherwise.
+ */
+export declare function isStreamClose(controlFlag: number): boolean;
+//# sourceMappingURL=message.d.ts.map

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

@@ -0,0 +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"}

package/dist/transport/message.js

@@ -1,48 +1,95 @@
 import { Type } from '@sinclair/typebox';
 import { nanoid } from 'nanoid';
-// look at https://github.com/websockets/ws#use-the-nodejs-streams-api for a duplex stream we can use
+/**
+ * Generic Typebox schema for a transport message.
+ * @template T The type of the payload.
+ * @param {T} t The payload schema.
+ * @returns The transport message schema.
+ */
 export const TransportMessageSchema = (t) => Type.Object({
     id: Type.String(),
-    replyTo: Type.Optional(Type.String()),
     from: Type.String(),
     to: Type.String(),
     serviceName: Type.String(),
     procedureName: Type.String(),
+    streamId: Type.String(),
+    controlFlags: Type.Integer(),
     payload: t,
 });
-export const OpaqueTransportMessageSchema = TransportMessageSchema(Type.Unknown());
-export const TransportAckSchema = Type.Object({
-    id: Type.String(),
-    from: Type.String(),
+/**
+ * Defines the schema for a transport acknowledgement message. This is never constructed manually
+ * and is only used internally by the library for tracking inflight messages.
+ * @returns The transport message schema.
+ */
+export const TransportAckSchema = TransportMessageSchema(Type.Object({
     ack: Type.String(),
-});
-export function msg(from, to, service, proc, payload) {
+}));
+/**
+ * Defines the schema for an opaque transport message that is agnostic to any
+ * procedure/service.
+ * @returns The transport message schema.
+ */
+export const OpaqueTransportMessageSchema = TransportMessageSchema(Type.Unknown());
+/**
+ * Creates a transport message with the given parameters. You shouldn't need to call this manually unless
+ * you're writing a test.
+ * @param from The sender of the message.
+ * @param to The intended recipient of the message.
+ * @param service The name of the service the message is intended for.
+ * @param proc The name of the procedure the message is intended for.
+ * @param stream The ID of the stream the message is intended for.
+ * @param payload The payload of the message.
+ * @returns A TransportMessage object with the given parameters.
+ */
+export function msg(from, to, service, proc, stream, payload) {
     return {
         id: nanoid(),
         to,
         from,
         serviceName: service,
         procedureName: proc,
+        streamId: stream,
+        controlFlags: 0,
         payload,
     };
 }
-export function payloadToTransportMessage(payload) {
-    return msg('client', 'SERVER', 'service', 'procedure', payload);
-}
-export function ack(msg) {
-    return {
-        id: nanoid(),
-        from: msg.to,
-        ack: msg.id,
-    };
-}
+/**
+ * Creates a new transport message as a response to the given message.
+ * @param msg The original message to respond to.
+ * @param response The payload of the response message.
+ * @returns A new transport message with appropriate to, from, and payload fields
+ */
 export function reply(msg, response) {
     return {
         ...msg,
         id: nanoid(),
-        replyTo: msg.id,
         to: msg.from,
         from: msg.to,
         payload: response,
     };
 }
+/**
+ * Checks if the given control flag (usually found in msg.controlFlag) is an ack message.
+ * @param controlFlag - The control flag to check.
+ * @returns True if the control flag contains the AckBit, false otherwise.
+ */
+export function isAck(controlFlag) {
+    return (controlFlag & 1 /* ControlFlags.AckBit */) === 1 /* ControlFlags.AckBit */;
+}
+/**
+ * Checks if the given control flag (usually found in msg.controlFlag) is a stream open message.
+ * @param controlFlag - The control flag to check.
+ * @returns True if the control flag contains the StreamOpenBit, false otherwise.
+ */
+export function isStreamOpen(controlFlag) {
+    return ((controlFlag & 2 /* ControlFlags.StreamOpenBit */) === 2 /* ControlFlags.StreamOpenBit */);
+}
+/**
+ * Checks if the given control flag (usually found in msg.controlFlag) is a stream close message.
+ * @param controlFlag - The control flag to check.
+ * @returns True if the control flag contains the StreamCloseBit, false otherwise.
+ */
+export function isStreamClose(controlFlag) {
+    return ((controlFlag & 4 /* ControlFlags.StreamClosedBit */) ===
+        4 /* ControlFlags.StreamClosedBit */);
+}

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

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

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

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

package/dist/transport/message.test.js

@@ -1,14 +1,32 @@
-import { ack, msg, reply } from './message';
+import { isAck, isStreamClose, isStreamOpen, msg, reply, } from './message';
 import { describe, test, expect } from 'vitest';
 describe('message helpers', () => {
     test('ack', () => {
-        const m = msg('a', 'b', 'svc', 'proc', { test: 1 });
-        const resp = ack(m);
-        expect(resp.from).toBe('b');
-        expect(resp).toHaveProperty('ack');
+        const m = msg('a', 'b', 'svc', 'proc', 'stream', { test: 1 });
+        m.controlFlags |= 1 /* ControlFlags.AckBit */;
+        expect(m).toHaveProperty('controlFlags');
+        expect(isAck(m.controlFlags)).toBe(true);
+        expect(isStreamOpen(m.controlFlags)).toBe(false);
+        expect(isStreamClose(m.controlFlags)).toBe(false);
+    });
+    test('streamOpen', () => {
+        const m = msg('a', 'b', 'svc', 'proc', 'stream', { test: 1 });
+        m.controlFlags |= 2 /* ControlFlags.StreamOpenBit */;
+        expect(m).toHaveProperty('controlFlags');
+        expect(isAck(m.controlFlags)).toBe(false);
+        expect(isStreamOpen(m.controlFlags)).toBe(true);
+        expect(isStreamClose(m.controlFlags)).toBe(false);
+    });
+    test('streamClose', () => {
+        const m = msg('a', 'b', 'svc', 'proc', 'stream', { test: 1 });
+        m.controlFlags |= 4 /* ControlFlags.StreamClosedBit */;
+        expect(m).toHaveProperty('controlFlags');
+        expect(isAck(m.controlFlags)).toBe(false);
+        expect(isStreamOpen(m.controlFlags)).toBe(false);
+        expect(isStreamClose(m.controlFlags)).toBe(true);
     });
     test('reply', () => {
-        const m = msg('a', 'b', 'svc', 'proc', { test: 1 });
+        const m = msg('a', 'b', 'svc', 'proc', 'stream', { test: 1 });
         const payload = { cool: 2 };
         const resp = reply(m, payload);
         expect(resp.id).not.toBe(m.id);
@@ -16,4 +34,19 @@ describe('message helpers', () => {
         expect(resp.from).toBe('b');
         expect(resp.to).toBe('a');
     });
+    test('default message has no control flags set', () => {
+        const m = msg('a', 'b', 'svc', 'proc', 'stream', { test: 1 });
+        expect(isAck(m.controlFlags)).toBe(false);
+        expect(isStreamOpen(m.controlFlags)).toBe(false);
+        expect(isStreamClose(m.controlFlags)).toBe(false);
+    });
+    test('combining control flags works', () => {
+        const m = msg('a', 'b', 'svc', 'proc', 'stream', { test: 1 });
+        m.controlFlags |= 2 /* ControlFlags.StreamOpenBit */;
+        expect(isStreamOpen(m.controlFlags)).toBe(true);
+        expect(isStreamClose(m.controlFlags)).toBe(false);
+        m.controlFlags |= 4 /* ControlFlags.StreamClosedBit */;
+        expect(isStreamOpen(m.controlFlags)).toBe(true);
+        expect(isStreamClose(m.controlFlags)).toBe(true);
+    });
 });

package/dist/transport/types.d.ts

@@ -1,14 +1,50 @@
 import { Codec } from '../codec/types';
-import { MessageId, OpaqueTransportMessage, TransportClientId, TransportMessageAck } from './message';
+import { MessageId, OpaqueTransportMessage, TransportClientId } from './message';
+/**
+ * Abstract base for a transport layer for communication between nodes in a River network.
+ * Any River transport methods need to implement this interface.
+ * @abstract
+ */
 export declare abstract class Transport {
+    /**
+     * 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.
+     */
     handlers: Set<(msg: OpaqueTransportMessage) => void>;
+    /**
+     * The buffer of messages that have been sent but not yet acknowledged.
+     */
     sendBuffer: Map<MessageId, OpaqueTransportMessage>;
+    /**
+     * 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);
+    /**
+     * 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.
+     */
     onMessage(msg: string): 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;
-    abstract send(msg: OpaqueTransportMessage | TransportMessageAck): MessageId;
+    abstract send(msg: OpaqueTransportMessage): MessageId;
     abstract close(): Promise<void>;
 }
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../transport/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,OAAO,EAEL,SAAS,EACT,sBAAsB,EAGtB,iBAAiB,EAGlB,MAAM,WAAW,CAAC;AAGnB;;;;GAIG;AACH,8BAAsB,SAAS;IAC7B;;OAEG;IACH,KAAK,EAAE,KAAK,CAAC;IAEb;;OAEG;IACH,QAAQ,EAAE,iBAAiB,CAAC;IAE5B;;OAEG;IACH,QAAQ,EAAE,GAAG,CAAC,CAAC,GAAG,EAAE,sBAAsB,KAAK,IAAI,CAAC,CAAC;IAGrD;;OAEG;IACH,UAAU,EAAE,GAAG,CAAC,SAAS,EAAE,sBAAsB,CAAC,CAAC;IAEnD;;;;OAIG;gBACS,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,iBAAiB;IAOrD;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM;IAuCrB;;;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,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,sBAAsB,GAAG,SAAS;IACrD,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAChC"}

package/dist/transport/types.js

@@ -1,31 +1,61 @@
 import { Value } from '@sinclair/typebox/value';
-import { OpaqueTransportMessageSchema, TransportAckSchema, ack, } from './message';
+import { OpaqueTransportMessageSchema, TransportAckSchema, isAck, reply, } from './message';
 import { log } from '../logging';
+/**
+ * Abstract base for a transport layer for communication between nodes in a River network.
+ * Any River transport methods need to implement this interface.
+ * @abstract
+ */
 export class Transport {
+    /**
+     * The {@link Codec} used to encode and decode messages.
+     */
     codec;
+    /**
+     * The client ID of this transport.
+     */
     clientId;
+    /**
+     * The set of message handlers registered with this transport.
+     */
     handlers;
+    // TODO; we can do much better here on retry (maybe resending the sendBuffer on fixed interval)
+    /**
+     * The buffer of messages that have been sent but not yet acknowledged.
+     */
     sendBuffer;
+    /**
+     * 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, clientId) {
         this.handlers = new Set();
         this.sendBuffer = new Map();
         this.codec = codec;
         this.clientId = clientId;
     }
+    /**
+     * 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.
+     */
     onMessage(msg) {
         const parsedMsg = this.codec.fromStringBuf(msg);
         if (parsedMsg === null) {
             log?.warn(`${this.clientId} -- received malformed msg: ${msg}`);
             return;
         }
-        if (Value.Check(TransportAckSchema, parsedMsg)) {
+        if (Value.Check(TransportAckSchema, parsedMsg) &&
+            isAck(parsedMsg.controlFlags)) {
             // process ack
             log?.info(`${this.clientId} -- received ack: ${msg}`);
-            if (this.sendBuffer.has(parsedMsg.ack)) {
-                this.sendBuffer.delete(parsedMsg.ack);
+            if (this.sendBuffer.has(parsedMsg.payload.ack)) {
+                this.sendBuffer.delete(parsedMsg.payload.ack);
             }
         }
         else if (Value.Check(OpaqueTransportMessageSchema, parsedMsg)) {
+            // regular river message
             log?.info(`${this.clientId} -- received msg: ${msg}`);
             // ignore if not for us
             if (parsedMsg.to !== this.clientId && parsedMsg.to !== 'broadcast') {
@@ -35,7 +65,8 @@ export class Transport {
             for (const handler of this.handlers) {
                 handler(parsedMsg);
             }
-            const ackMsg = ack(parsedMsg);
+            const ackMsg = reply(parsedMsg, { ack: parsedMsg.id });
+            ackMsg.controlFlags = 1 /* ControlFlags.AckBit */;
             ackMsg.from = this.clientId;
             this.send(ackMsg);
         }
@@ -43,9 +74,17 @@ export class Transport {
             log?.warn(`${this.clientId} -- received invalid transport msg: ${msg}`);
         }
     }
+    /**
+     * Adds a message listener to this transport.
+     * @param handler The message handler to add.
+     */
     addMessageListener(handler) {
         this.handlers.add(handler);
     }
+    /**
+     * Removes a message listener from this transport.
+     * @param handler The message handler to remove.
+     */
     removeMessageListener(handler) {
         this.handlers.delete(handler);
     }

package/package.json

@@ -2,14 +2,13 @@
   "name": "@replit/river",
   "sideEffects": false,
   "description": "It's like tRPC but... with JSON Schema Support, duplex streaming and support for service multiplexing. Transport agnostic!",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "type": "module",
   "exports": {
     ".": "./dist/router/index.js",
     "./logging": "./dist/logging/index.js",
     "./codec": "./dist/codec/index.js",
     "./test-util": "./dist/testUtils.js",
-    "./package.json": "./package.json",
     "./transport": "./dist/transport/index.js",
     "./transport/ws": "./dist/transport/impls/ws.js",
     "./transport/stdio": "./dist/transport/impls/stdio.js"