@replit/river 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Repl.it
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# river - Streaming Remote Procedure Calls
+
+It's like tRPC but...
+- with JSON Schema Support
+- with full-duplex streaming
+- with support for service multiplexing
+- over WebSockets
+
+## Levels of abstraction
+- Router
+- Service
+- Procedure
+
+## TODO
+- support broadcast

package/dist/__tests__/integration.test.d.ts

@@ -0,0 +1,49 @@
+export declare const EchoRequest: import("@sinclair/typebox").TObject<{
+    msg: import("@sinclair/typebox").TString;
+    ignore: import("@sinclair/typebox").TBoolean;
+}>;
+export declare const EchoResponse: import("@sinclair/typebox").TObject<{
+    response: import("@sinclair/typebox").TString;
+}>;
+export declare const TestServiceConstructor: () => {
+    name: "test";
+    state: {
+        count: number;
+    };
+    procedures: {
+        add: {
+            input: import("@sinclair/typebox").TObject<{
+                n: import("@sinclair/typebox").TNumber;
+            }>;
+            output: import("@sinclair/typebox").TObject<{
+                result: import("@sinclair/typebox").TNumber;
+            }>;
+            handler: (state: {
+                count: number;
+            }, input: import("../transport/message").TransportMessage<{
+                n: number;
+            }>) => Promise<import("../transport/message").TransportMessage<{
+                result: number;
+            }>>;
+            type: "rpc";
+        };
+        echo: {
+            input: import("@sinclair/typebox").TObject<{
+                msg: import("@sinclair/typebox").TString;
+                ignore: import("@sinclair/typebox").TBoolean;
+            }>;
+            output: import("@sinclair/typebox").TObject<{
+                response: import("@sinclair/typebox").TString;
+            }>;
+            handler: (state: {
+                count: number;
+            }, input: AsyncIterable<import("../transport/message").TransportMessage<{
+                msg: string;
+                ignore: boolean;
+            }>>, output: import("it-pushable").Pushable<import("../transport/message").TransportMessage<{
+                response: string;
+            }>, void, unknown>) => Promise<void>;
+            type: "stream";
+        };
+    };
+};

package/dist/__tests__/integration.test.js

@@ -0,0 +1,141 @@
+import http from 'http';
+import { Type } from '@sinclair/typebox';
+import { ServiceBuilder, serializeService } from '../router/builder';
+import { reply } from '../transport/message';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import { createWebSocketServer, createWsTransports, onServerReady } from '../transport/ws.util';
+import { createServer } from '../router/server';
+import { createClient } from '../router/client';
+import { asClientRpc, asClientStream } from '../router/server.util';
+export const EchoRequest = Type.Object({ msg: Type.String(), ignore: Type.Boolean() });
+export const EchoResponse = Type.Object({ response: Type.String() });
+export const TestServiceConstructor = () => ServiceBuilder.create('test')
+    .initialState({
+    count: 0,
+})
+    .defineProcedure('add', {
+    type: 'rpc',
+    input: Type.Object({ n: Type.Number() }),
+    output: Type.Object({ result: Type.Number() }),
+    async handler(state, msg) {
+        const { n } = msg.payload;
+        state.count += n;
+        return reply(msg, { result: state.count });
+    },
+})
+    .defineProcedure('echo', {
+    type: 'stream',
+    input: EchoRequest,
+    output: EchoResponse,
+    async handler(_state, msgStream, returnStream) {
+        for await (const msg of msgStream) {
+            const req = msg.payload;
+            if (!req.ignore) {
+                returnStream.push(reply(msg, { response: req.msg }));
+            }
+        }
+    },
+})
+    .finalize();
+test('serialize service to jsonschema', () => {
+    const service = TestServiceConstructor();
+    expect(serializeService(service)).toStrictEqual({
+        name: 'test',
+        state: { count: 0 },
+        procedures: {
+            add: {
+                input: {
+                    properties: {
+                        n: { type: 'number' },
+                    },
+                    required: ['n'],
+                    type: 'object',
+                },
+                output: {
+                    properties: {
+                        result: { type: 'number' },
+                    },
+                    required: ['result'],
+                    type: 'object',
+                },
+                type: 'rpc',
+            },
+            echo: {
+                input: {
+                    properties: {
+                        msg: { type: 'string' },
+                        ignore: { type: 'boolean' },
+                    },
+                    required: ['msg', 'ignore'],
+                    type: 'object',
+                },
+                output: {
+                    properties: {
+                        response: { type: 'string' },
+                    },
+                    required: ['response'],
+                    type: 'object',
+                },
+                type: 'stream',
+            },
+        },
+    });
+});
+describe('server-side test', () => {
+    const service = TestServiceConstructor();
+    const initialState = { count: 0 };
+    test('rpc basic', async () => {
+        const add = asClientRpc(initialState, service.procedures.add);
+        await expect(add({ n: 3 })).resolves.toStrictEqual({ result: 3 });
+    });
+    test('rpc initial state', async () => {
+        const add = asClientRpc({ count: 5 }, service.procedures.add);
+        await expect(add({ n: 6 })).resolves.toStrictEqual({ result: 11 });
+    });
+    test('stream basic', async () => {
+        const [i, o] = asClientStream(initialState, service.procedures.echo);
+        i.push({ msg: 'abc', ignore: false });
+        i.push({ msg: 'def', ignore: true });
+        i.push({ msg: 'ghi', ignore: false });
+        i.end();
+        await expect(o.next().then((res) => res.value)).resolves.toStrictEqual({ response: 'abc' });
+        await expect(o.next().then((res) => res.value)).resolves.toStrictEqual({ response: 'ghi' });
+        expect(o.readableLength).toBe(0);
+    });
+});
+const port = 3001;
+describe('client <-> server integration test', () => {
+    const server = http.createServer();
+    let wss;
+    beforeAll(async () => {
+        await onServerReady(server, port);
+        wss = await createWebSocketServer(server);
+    });
+    afterAll(() => {
+        wss.clients.forEach((socket) => {
+            socket.close();
+        });
+        server.close();
+    });
+    test('rpc', async () => {
+        const [ct, st] = await createWsTransports(port, wss);
+        const serviceDefs = { test: TestServiceConstructor() };
+        const server = await createServer(st, serviceDefs);
+        const client = createClient(ct);
+        await expect(client.test.add({ n: 3 })).resolves.toStrictEqual({ result: 3 });
+    });
+    test('stream', async () => {
+        const [ct, st] = await createWsTransports(port, wss);
+        const serviceDefs = { test: TestServiceConstructor() };
+        const server = await createServer(st, serviceDefs);
+        const client = createClient(ct);
+        const [i, o, close] = await client.test.echo();
+        i.push({ msg: 'abc', ignore: false });
+        i.push({ msg: 'def', ignore: true });
+        i.push({ msg: 'ghi', ignore: false });
+        i.end();
+        await expect(o.next().then((res) => res.value)).resolves.toStrictEqual({ response: 'abc' });
+        await expect(o.next().then((res) => res.value)).resolves.toStrictEqual({ response: 'ghi' });
+        close();
+    });
+});

package/dist/codec/codec.test.d.ts

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

package/dist/codec/codec.test.js

@@ -0,0 +1,23 @@
+import { NaiveJsonCodec } from './json';
+import { describe, test, expect } from 'vitest';
+describe('naive json codec', () => {
+    test('empty object', () => {
+        const msg = {};
+        expect(NaiveJsonCodec.fromStringBuf(NaiveJsonCodec.toStringBuf(msg))).toStrictEqual(msg);
+    });
+    test('simple test', () => {
+        const msg = { abc: 123, def: 'cool' };
+        expect(NaiveJsonCodec.fromStringBuf(NaiveJsonCodec.toStringBuf(msg))).toStrictEqual(msg);
+    });
+    test('deeply nested test', () => {
+        const msg = {
+            array: [{ object: true }],
+            deeply: {
+                nested: {
+                    nice: null,
+                },
+            },
+        };
+        expect(NaiveJsonCodec.fromStringBuf(NaiveJsonCodec.toStringBuf(msg))).toStrictEqual(msg);
+    });
+});

package/dist/codec/json.d.ts

@@ -0,0 +1,2 @@
+import { Codec } from "./types";
+export declare const NaiveJsonCodec: Codec;

package/dist/codec/json.js

@@ -0,0 +1,4 @@
+export const NaiveJsonCodec = {
+    toStringBuf: JSON.stringify,
+    fromStringBuf: JSON.parse,
+};

package/dist/codec/types.d.ts

@@ -0,0 +1,4 @@
+export interface Codec {
+    toStringBuf(obj: object): string;
+    fromStringBuf(buf: string): object;
+}

package/dist/codec/types.js

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

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";console.log("hello world");

package/dist/index.js

@@ -0,0 +1,2 @@
+// index.ts
+console.log("hello world");

package/dist/router/builder.d.ts

@@ -0,0 +1,50 @@
+import { TObject, Static } from '@sinclair/typebox';
+import { Pushable } from 'it-pushable';
+import { TransportMessage } from '../transport/message';
+export type ValidProcType = 'stream' | 'rpc';
+export type ProcListing = Record<string, Procedure<object, ValidProcType, TObject, TObject>>;
+export interface Service<Name extends string = string, State extends object = object, Procs extends ProcListing = Record<string, any>> {
+    name: Name;
+    state: State;
+    procedures: Procs;
+}
+export declare function serializeService(s: Service): object;
+export type ProcHandler<S extends Service, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['handler'];
+export type ProcInput<S extends Service, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['input'];
+export type ProcOutput<S extends Service, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['output'];
+export type ProcType<S extends Service, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['type'];
+export type Procedure<State extends object | unknown, Ty extends ValidProcType, I extends TObject, O extends TObject> = Ty extends 'rpc' ? {
+    input: I;
+    output: O;
+    handler: (state: State, input: TransportMessage<Static<I>>) => Promise<TransportMessage<Static<O>>>;
+    type: Ty;
+} : {
+    input: I;
+    output: O;
+    handler: (state: State, input: AsyncIterable<TransportMessage<Static<I>>>, output: Pushable<TransportMessage<Static<O>>>) => Promise<void>;
+    type: Ty;
+};
+export declare class ServiceBuilder<T extends Service<string, object, ProcListing>> {
+    private readonly schema;
+    private constructor();
+    finalize(): T;
+    initialState<InitState extends T['state']>(state: InitState): ServiceBuilder<{
+        name: T['name'];
+        state: InitState;
+        procedures: T['procedures'];
+    }>;
+    defineProcedure<ProcName extends string, Ty extends ValidProcType, I extends TObject, O extends TObject, ProcEntry = {
+        [k in ProcName]: Procedure<T['state'], Ty, I, O>;
+    }>(procName: ProcName, procDef: Procedure<T['state'], Ty, I, O>): ServiceBuilder<{
+        name: T['name'];
+        state: T['state'];
+        procedures: {
+            [Key in keyof (T['procedures'] & ProcEntry)]: (T['procedures'] & ProcEntry)[Key];
+        };
+    }>;
+    static create<Name extends string>(name: Name): ServiceBuilder<{
+        name: Name;
+        state: {};
+        procedures: {};
+    }>;
+}

package/dist/router/builder.js

@@ -0,0 +1,48 @@
+import { Type } from '@sinclair/typebox';
+export function serializeService(s) {
+    return {
+        name: s.name,
+        state: s.state,
+        procedures: Object.fromEntries(Object.entries(s.procedures).map(([procName, procDef]) => [
+            procName,
+            {
+                input: Type.Strict(procDef.input),
+                output: Type.Strict(procDef.output),
+                type: procDef.type,
+            },
+        ])),
+    };
+}
+export class ServiceBuilder {
+    schema;
+    constructor(schema) {
+        this.schema = schema;
+    }
+    finalize() {
+        return this.schema;
+    }
+    initialState(state) {
+        return new ServiceBuilder({
+            ...this.schema,
+            state,
+        });
+    }
+    defineProcedure(procName, procDef) {
+        const newProcedure = { [procName]: procDef };
+        const procedures = {
+            ...this.schema.procedures,
+            ...newProcedure,
+        };
+        return new ServiceBuilder({
+            ...this.schema,
+            procedures,
+        });
+    }
+    static create(name) {
+        return new ServiceBuilder({
+            name,
+            state: {},
+            procedures: {},
+        });
+    }
+}

package/dist/router/client.d.ts

@@ -0,0 +1,17 @@
+import { Transport } from '../transport/types';
+import { ProcInput, ProcOutput, ProcType, Service } from './builder';
+import { Pushable } from 'it-pushable';
+import { Server } from './server';
+import { Static } from '@sinclair/typebox';
+type ServiceClient<Router extends Service> = {
+    [ProcName in keyof Router['procedures']]: ProcType<Router, ProcName> extends 'rpc' ? (input: Static<ProcInput<Router, ProcName>>) => Promise<Static<ProcOutput<Router, ProcName>>> : () => Promise<[
+        Pushable<Static<ProcInput<Router, ProcName>>>,
+        AsyncIterator<Static<ProcOutput<Router, ProcName>>>,
+        () => void
+    ]>;
+};
+export type ServerClient<Srv extends Server<Record<string, Service>>> = {
+    [SvcName in keyof Srv['services']]: ServiceClient<Srv['services'][SvcName]>;
+};
+export declare const createClient: <Srv extends Server<Record<string, Service<string, object, Record<string, any>>>>>(transport: Transport) => ServerClient<Srv>;
+export {};

package/dist/router/client.js

@@ -0,0 +1,54 @@
+import { pushable } from 'it-pushable';
+import { msg } from '../transport/message';
+import { waitForMessage } from '../transport/ws.util';
+const noop = () => { };
+function _createRecursiveProxy(callback, path) {
+    const proxy = new Proxy(noop, {
+        get(_obj, key) {
+            if (typeof key !== 'string')
+                return undefined;
+            return _createRecursiveProxy(callback, [...path, key]);
+        },
+        apply(_target, _this, args) {
+            return callback({
+                path,
+                args,
+            });
+        },
+    });
+    return proxy;
+}
+export const createClient = (transport) => _createRecursiveProxy(async (opts) => {
+    const [serviceName, procName] = [...opts.path];
+    const [input] = opts.args;
+    if (input === undefined) {
+        // stream case
+        const i = pushable({ objectMode: true });
+        const o = pushable({ objectMode: true });
+        // i -> transport
+        // this gets cleaned up on i.end() which is called by closeHandler
+        (async () => {
+            for await (const rawIn of i) {
+                transport.send(msg(transport.clientId, 'SERVER', serviceName, procName, rawIn));
+            }
+        })();
+        // transport -> o
+        const listener = (msg) => {
+            if (msg.serviceName === serviceName && msg.procedureName === procName) {
+                o.push(msg.payload);
+            }
+        };
+        transport.addMessageListener(listener);
+        const closeHandler = () => {
+            i.end();
+            o.end();
+            transport.removeMessageListener(listener);
+        };
+        return [i, o, closeHandler];
+    }
+    else {
+        // rpc case
+        const id = transport.send(msg(transport.clientId, 'SERVER', serviceName, procName, input));
+        return waitForMessage(transport, (msg) => msg.replyTo === id);
+    }
+}, []);

package/dist/router/server.d.ts

@@ -0,0 +1,7 @@
+import { Transport } from '../transport/types';
+import { Service } from './builder';
+export interface Server<Services> {
+    services: Services;
+    close(): Promise<void>;
+}
+export declare function createServer<Services extends Record<string, Service>>(transport: Transport, services: Services): Promise<Server<Services>>;

package/dist/router/server.js

@@ -0,0 +1,78 @@
+import { Value } from '@sinclair/typebox/value';
+import { pushable } from 'it-pushable';
+export async function createServer(transport, services) {
+    // create streams for every stream procedure
+    const streamMap = new Map();
+    for (const [serviceName, service] of Object.entries(services)) {
+        for (const [procedureName, proc] of Object.entries(service.procedures)) {
+            const procedure = proc;
+            if (procedure.type === 'stream') {
+                const incoming = pushable({ objectMode: true });
+                const outgoing = pushable({ objectMode: true });
+                const procStream = {
+                    incoming,
+                    outgoing,
+                    doneCtx: Promise.all([
+                        // processing the actual procedure
+                        procedure.handler(service.state, incoming, outgoing),
+                        // sending outgoing messages back to client
+                        (async () => {
+                            for await (const response of outgoing) {
+                                transport.send(response);
+                            }
+                        })(),
+                    ]),
+                };
+                streamMap.set(`${serviceName}:${procedureName}`, procStream);
+            }
+        }
+    }
+    const handler = async (msg) => {
+        // TODO: log msgs received
+        if (msg.to !== 'SERVER') {
+            return;
+        }
+        if (msg.serviceName in services) {
+            const service = services[msg.serviceName];
+            if (msg.procedureName in service.procedures) {
+                const procedure = service.procedures[msg.procedureName];
+                const inputMessage = msg;
+                if (procedure.type === 'rpc' && Value.Check(procedure.input, inputMessage.payload)) {
+                    // synchronous rpc
+                    const response = await procedure.handler(service.state, inputMessage);
+                    transport.send(response);
+                    return;
+                }
+                else if (procedure.type === 'stream' &&
+                    Value.Check(procedure.input, inputMessage.payload)) {
+                    // async stream, push to associated stream. code above handles sending responses
+                    // back to the client
+                    const streams = streamMap.get(`${msg.serviceName}:${msg.procedureName}`);
+                    if (!streams) {
+                        // this should never happen but log here if we get here
+                        return;
+                    }
+                    streams.incoming.push(inputMessage);
+                    return;
+                }
+                else {
+                    // TODO: log invalid payload
+                }
+            }
+        }
+    };
+    transport.addMessageListener(handler);
+    return {
+        services,
+        async close() {
+            // remove listener
+            transport.removeMessageListener(handler);
+            // end all existing streams
+            for (const [_, stream] of streamMap) {
+                stream.incoming.end();
+                stream.outgoing.end();
+                await stream.doneCtx;
+            }
+        },
+    };
+}

package/dist/router/server.util.d.ts

@@ -0,0 +1,5 @@
+import { Static, TObject } from '@sinclair/typebox';
+import { Procedure } from './builder';
+import { Pushable } from 'it-pushable';
+export declare function asClientRpc<State extends object | unknown, I extends TObject, O extends TObject>(state: State, proc: Procedure<State, 'rpc', I, O>): (msg: Static<I>) => Promise<Static<O>>;
+export declare function asClientStream<State extends object | unknown, I extends TObject, O extends TObject>(state: State, proc: Procedure<State, 'stream', I, O>): [Pushable<Static<I>>, Pushable<Static<O>>];

package/dist/router/server.util.js

@@ -0,0 +1,30 @@
+import { payloadToTransportMessage } from '../transport/message';
+import { pushable } from 'it-pushable';
+export function asClientRpc(state, proc) {
+    return (msg) => proc.handler(state, payloadToTransportMessage(msg)).then((res) => res.payload);
+}
+export function asClientStream(state, proc) {
+    const i = pushable({ objectMode: true });
+    const o = pushable({ objectMode: true });
+    const ri = pushable({ objectMode: true });
+    const ro = pushable({ objectMode: true });
+    // wrapping in transport
+    (async () => {
+        for await (const rawIn of i) {
+            ri.push(payloadToTransportMessage(rawIn));
+        }
+        ri.end();
+    })();
+    // unwrap from transport
+    (async () => {
+        for await (const transportRes of ro) {
+            o.push(transportRes.payload);
+        }
+    })();
+    // handle
+    (async () => {
+        await proc.handler(state, ri, ro);
+        ro.end();
+    })();
+    return [i, o];
+}

package/dist/transport/message.d.ts

@@ -0,0 +1,62 @@
+import { type Static, TSchema } from '@sinclair/typebox';
+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;
+    payload: T;
+}>;
+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;
+    payload: import("@sinclair/typebox").TUnknown;
+}>;
+export type TransportMessage<Payload extends Record<string, unknown> | unknown = Record<string, unknown>> = {
+    id: string;
+    replyTo?: string;
+    from: string;
+    to: string;
+    serviceName: string;
+    procedureName: string;
+    payload: Payload;
+};
+export type MessageId = string;
+export type OpaqueTransportMessage = TransportMessage<unknown>;
+export type TransportClientId = 'SERVER' | string;
+export declare const TransportAckSchema: import("@sinclair/typebox").TObject<{
+    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;
+};

package/dist/transport/message.js

@@ -0,0 +1,46 @@
+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
+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(),
+    payload: t,
+});
+export const OpaqueTransportMessageSchema = TransportMessageSchema(Type.Unknown());
+export const TransportAckSchema = Type.Object({
+    from: Type.String(),
+    ack: Type.String(),
+});
+export function msg(from, to, service, proc, payload) {
+    return {
+        id: nanoid(),
+        to,
+        from,
+        serviceName: service,
+        procedureName: proc,
+        payload,
+    };
+}
+export function payloadToTransportMessage(payload) {
+    return msg('client', 'SERVER', 'service', 'procedure', payload);
+}
+export function ack(msg) {
+    return {
+        from: msg.to,
+        ack: msg.id,
+    };
+}
+export function reply(msg, response) {
+    return {
+        ...msg,
+        id: nanoid(),
+        replyTo: msg.id,
+        to: msg.from,
+        from: msg.to,
+        payload: response,
+    };
+}

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

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

package/dist/transport/message.test.js

@@ -0,0 +1,19 @@
+import { ack, 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');
+    });
+    test('reply', () => {
+        const m = msg('a', 'b', 'svc', 'proc', { test: 1 });
+        const payload = { cool: 2 };
+        const resp = reply(m, payload);
+        expect(resp.id).not.toBe(m.id);
+        expect(resp.payload).toEqual(payload);
+        expect(resp.from).toBe('b');
+        expect(resp.to).toBe('a');
+    });
+});

package/dist/transport/stdio.d.ts

@@ -0,0 +1,7 @@
+import { OpaqueTransportMessage, TransportClientId } from './message';
+import { Transport } from './types';
+export declare class StdioTransport extends Transport {
+    constructor(clientId: TransportClientId);
+    send(msg: OpaqueTransportMessage): string;
+    close(): Promise<void>;
+}

package/dist/transport/stdio.js

@@ -0,0 +1,20 @@
+import { NaiveJsonCodec } from '../codec/json';
+import { Transport } from './types';
+import readline from 'readline';
+export class StdioTransport extends Transport {
+    constructor(clientId) {
+        super(NaiveJsonCodec, clientId);
+        const { stdin, stdout } = process;
+        const rl = readline.createInterface({
+            input: stdin,
+            output: stdout,
+        });
+        rl.on('line', this.onMessage);
+    }
+    send(msg) {
+        const id = msg.id;
+        process.stdout.write(this.codec.toStringBuf(msg));
+        return id;
+    }
+    async close() { }
+}

package/dist/transport/types.d.ts

@@ -0,0 +1,14 @@
+import { Codec } from '../codec/types';
+import { MessageId, OpaqueTransportMessage, TransportClientId, TransportMessageAck } from './message';
+export declare abstract class Transport {
+    codec: Codec;
+    clientId: TransportClientId;
+    handlers: Set<(msg: OpaqueTransportMessage) => void>;
+    sendBuffer: Map<MessageId, OpaqueTransportMessage>;
+    constructor(codec: Codec, clientId: TransportClientId);
+    onMessage(msg: string): void;
+    addMessageListener(handler: (msg: OpaqueTransportMessage) => void): void;
+    removeMessageListener(handler: (msg: OpaqueTransportMessage) => void): void;
+    abstract send(msg: OpaqueTransportMessage | TransportMessageAck): MessageId;
+    abstract close(): Promise<void>;
+}

package/dist/transport/types.js

@@ -0,0 +1,40 @@
+import { Value } from '@sinclair/typebox/value';
+import { OpaqueTransportMessageSchema, TransportAckSchema, ack, } from './message';
+export class Transport {
+    codec;
+    clientId;
+    handlers;
+    sendBuffer;
+    constructor(codec, clientId) {
+        this.handlers = new Set();
+        this.sendBuffer = new Map();
+        this.codec = codec;
+        this.clientId = clientId;
+    }
+    onMessage(msg) {
+        const parsedMsg = this.codec.fromStringBuf(msg.toString());
+        if (Value.Check(TransportAckSchema, parsedMsg)) {
+            // process ack
+            if (this.sendBuffer.has(parsedMsg.ack)) {
+                this.sendBuffer.delete(parsedMsg.ack);
+            }
+        }
+        else if (Value.Check(OpaqueTransportMessageSchema, parsedMsg)) {
+            // ignore if not for us
+            if (parsedMsg.to !== this.clientId && parsedMsg.to !== 'broadcast') {
+                return;
+            }
+            // handle actual message
+            for (const handler of this.handlers) {
+                handler(parsedMsg);
+            }
+            this.send(ack(parsedMsg));
+        }
+    }
+    addMessageListener(handler) {
+        this.handlers.add(handler);
+    }
+    removeMessageListener(handler) {
+        this.handlers.delete(handler);
+    }
+}

package/dist/transport/ws.d.ts

@@ -0,0 +1,9 @@
+import type WebSocket from 'ws';
+import { Transport } from './types';
+import { MessageId, OpaqueTransportMessage, TransportClientId } from './message';
+export declare class WebSocketTransport extends Transport {
+    ws: WebSocket;
+    constructor(ws: WebSocket, clientId: TransportClientId);
+    send(msg: OpaqueTransportMessage): MessageId;
+    close(): Promise<void>;
+}

package/dist/transport/ws.js

@@ -0,0 +1,23 @@
+import { Transport } from './types';
+import { NaiveJsonCodec } from '../codec/json';
+// TODO should answer:
+// - how do we handle graceful client disconnects? (i.e. close tab)
+// - how do we handle graceful service disconnects (i.e. a fuck off message)?
+// - how do we handle forceful client disconnects? (i.e. broken connection, offline)
+// - how do we handle forceful service disconnects (i.e. a crash)?
+export class WebSocketTransport extends Transport {
+    ws;
+    constructor(ws, clientId) {
+        super(NaiveJsonCodec, clientId);
+        this.ws = ws;
+        ws.on('message', (msg) => this.onMessage(msg.toString()));
+    }
+    send(msg) {
+        const id = msg.id;
+        this.ws.send(this.codec.toStringBuf(msg));
+        return id;
+    }
+    async close() {
+        return this.ws.close();
+    }
+}

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

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

package/dist/transport/ws.test.js

@@ -0,0 +1,41 @@
+import http from 'http';
+import { WebSocketTransport } from './ws';
+import { describe, test, expect, beforeAll, afterAll } from 'vitest';
+import { createWebSocketClient, createWebSocketServer, onServerReady, waitForMessage, } from './ws.util';
+const port = 3000;
+describe('sending and receiving across websockets works', () => {
+    const server = http.createServer();
+    let wss;
+    beforeAll(async () => {
+        await onServerReady(server, port);
+        wss = await createWebSocketServer(server);
+    });
+    afterAll(() => {
+        wss.clients.forEach((socket) => {
+            socket.close();
+        });
+        server.close();
+    });
+    test('basic send/receive', async () => {
+        let serverTransport;
+        wss.on('connection', (conn) => {
+            serverTransport = new WebSocketTransport(conn, 'SERVER');
+        });
+        const clientSoc = await createWebSocketClient(port);
+        const clientTransport = new WebSocketTransport(clientSoc, 'client');
+        const msg = {
+            msg: 'cool',
+            test: 123,
+        };
+        clientTransport.send({
+            id: '1',
+            from: 'client',
+            to: 'SERVER',
+            serviceName: 'test',
+            procedureName: 'test',
+            payload: msg,
+        });
+        expect(serverTransport).toBeTruthy();
+        return expect(waitForMessage(serverTransport)).resolves.toStrictEqual(msg);
+    });
+});

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

@@ -0,0 +1,11 @@
+/// <reference types="node" />
+import http from 'http';
+import WebSocket, { WebSocketServer } from 'ws';
+import { Transport } from './types';
+import { OpaqueTransportMessage } from './message';
+export declare function createWebSocketServer(server: http.Server): Promise<WebSocket.Server<typeof WebSocket, typeof http.IncomingMessage>>;
+export declare function onServerReady(server: http.Server, port: number): Promise<void>;
+export declare function createWsTransports(port: number, wss: WebSocketServer): Promise<[Transport, Transport]>;
+export declare function waitForSocketReady(socket: WebSocket): Promise<void>;
+export declare function createWebSocketClient(port: number): Promise<WebSocket>;
+export declare function waitForMessage(t: Transport, filter?: (msg: OpaqueTransportMessage) => boolean): Promise<unknown>;

package/dist/transport/ws.util.js

@@ -0,0 +1,42 @@
+import WebSocket, { WebSocketServer } from 'ws';
+import { WebSocketTransport } from './ws';
+export async function createWebSocketServer(server) {
+    return new WebSocketServer({ server });
+}
+export async function onServerReady(server, port) {
+    return new Promise((resolve) => {
+        server.listen(port, resolve);
+    });
+}
+export async function createWsTransports(port, wss) {
+    return new Promise((resolve) => {
+        const clientSockPromise = createWebSocketClient(port);
+        wss.on('connection', async (serverSock) => {
+            resolve([
+                new WebSocketTransport(await clientSockPromise, 'client'),
+                new WebSocketTransport(serverSock, 'SERVER'),
+            ]);
+        });
+    });
+}
+export async function waitForSocketReady(socket) {
+    return new Promise((resolve) => {
+        socket.addEventListener('open', () => resolve());
+    });
+}
+export async function createWebSocketClient(port) {
+    const client = new WebSocket(`ws://localhost:${port}`);
+    await waitForSocketReady(client);
+    return client;
+}
+export async function waitForMessage(t, filter) {
+    return new Promise((resolve, _reject) => {
+        function onMessage(msg) {
+            if (!filter || filter?.(msg)) {
+                resolve(msg.payload);
+                t.removeMessageListener(onMessage);
+            }
+        }
+        t.addMessageListener(onMessage);
+    });
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@replit/river",
+  "description": "It's like tRPC but... with JSON Schema Support, duplex streaming and support for service multiplexing. Transport agnostic!",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "/dist"
+  ],
+  "dependencies": {
+    "@sinclair/typebox": "^0.31.8",
+    "it-pushable": "^3.2.1",
+    "nanoid": "^4.0.2",
+    "ws": "^8.13.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.5",
+    "prettier": "^3.0.3",
+    "tsup": "^7.2.0",
+    "typescript": "^5.2.2",
+    "vitest": "^0.34.3"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "tsc",
+    "prepack": "npm run build",
+    "publish": "npm publish --access public",
+    "test": "vitest"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "rpc",
+    "websockets",
+    "jsonschema"
+  ],
+  "author": "Jacky Zhao",
+  "license": "MIT",
+  "prettier": {
+    "printWidth": 100,
+    "tabWidth": 2,
+    "singleQuote": true,
+    "trailingComma": "all",
+    "bracketSpacing": true,
+    "semi": true,
+    "useTabs": false,
+    "parser": "typescript",
+    "arrowParens": "always"
+  }
+}