@replit/river 0.10.5 → 0.10.6

package/README.md

@@ -1,15 +1,130 @@
 # river - Streaming Remote Procedure Calls
 
-It's like tRPC but...
+It's like tRPC/gRPC but with
 
-- with JSON Schema Support
-- with full-duplex streaming
-- with support for service multiplexing
-- with Result types and error handling
-- over WebSockets
+- JSON Schema Support + run-time schema validation
+- full-duplex streaming
+- service multiplexing
+- result types and error handling
+- snappy DX (no code-generation)
+- over any transport (WebSockets, stdio, Unix Domain Socket out of the box)
+
+## Installation
 
 To use River, you must be on least Typescript 5 with `"moduleResolution": "bundler"`.
 
+```bash
+npm i @replit/river @sinclair/typebox
+
+# if you plan on using WebSocket for transport, also install
+npm i ws isomorphic-ws
+```
+
+## Writing Services
+
+### Concepts
+
+- Router: a collection of services, namespaced by service name.
+- Service: a collection of procedures with shared state.
+- Procedure: a single procedure. A procedure declares its type, an input message type, an output message type, optionally an error type, and the associated handler. Valid types are:
+  - `rpc` whose handler has a signature of `Input -> Result<Output, Error>`.
+  - `upload` whose handler has a signature of `AsyncIterableIterator<Input> -> Result<Output, Error>`.
+  - `subscription` whose handler has a signature of `Input -> Pushable<Result<Output, Error>>`.
+  - `stream` whose handler has a signature of `AsyncIterableIterator<Input> -> Pushable<Result<Output, Error>>`.
+- Transport: manages the lifecycle (creation/deletion) of connections and multiplexing read/writes from clients. Both the client and the server must be passed in a subclass of `Transport` to work.
+- Codec: encodes messages between clients/servers before the transport sends it across the wire.
+
+### A basic router
+
+First, we create a service using the `ServiceBuilder`
+
+```ts
+import { ServiceBuilder, Ok, buildServiceDefs } from '@replit/river';
+import { Type } from '@sinclair/typebox';
+
+export const ExampleServiceConstructor = () =>
+  ServiceBuilder.create('example')
+    .initialState({
+      count: 0,
+    })
+    .defineProcedure('add', {
+      type: 'rpc',
+      input: Type.Object({ n: Type.Number() }),
+      output: Type.Object({ result: Type.Number() }),
+      errors: Type.Never(),
+      async handler(ctx, { n }) {
+        ctx.state.count += n;
+        return Ok({ result: ctx.state.count });
+      },
+    })
+    .finalize();
+
+// expore a listing of all the services that we have
+export const serviceDefs = buildServiceDefs([ExampleServiceConstructor()]);
+```
+
+Then, we create the server
+
+```ts
+import http from 'http';
+import { WebSocketServer } from 'ws';
+import { WebSocketServerTransport } from '@replit/river/transport/ws/server';
+import { createServer } from '@replit/river';
+
+// start websocket server on port 3000
+const httpServer = http.createServer();
+const port = 3000;
+const wss = new WebSocketServer({ server: httpServer });
+const transport = new WebSocketServerTransport(wss, 'SERVER');
+
+export const server = createServer(transport, serviceDefs);
+export type ServiceSurface = typeof server;
+
+httpServer.listen(port);
+```
+
+In another file for the client (to create a separate entrypoint),
+
+```ts
+import WebSocket from 'isomorphic-ws';
+import { WebSocketClientTransport } from '@replit/river/transport/ws/client';
+import { createClient } from '@replit/river';
+
+const websocketUrl = `ws://localhost:3000`;
+const transport = new WebSocketClientTransport(
+  async () => new WebSocket(websocketUrl),
+  'my-client-id',
+  'SERVER',
+);
+
+const client = createClient<ServiceSurface>(transport, 'SERVER');
+
+// we get full type safety on `client`
+// client.<service name>.<procedure name>.<procedure type>()
+// e.g.
+const result = await client.example.add.rpc({ n: 3 });
+if (result.ok) {
+  const msg = result.payload;
+  console.log(msg.result); // 0 + 3 = 3
+}
+```
+
+To add logging,
+
+```ts
+import { bindLogger, setLevel } from '@replit/river/logging';
+
+bindLogger(console.log);
+setLevel('info');
+```
+
+### Further examples
+
+We've also provided an end-to-end testing environment using Next.js, and a simple backend connected
+with the WebSocket transport that you can [play with on Replit](https://replit.com/@jzhao-replit/riverbed).
+
+You can find more service examples in the [E2E test fixtures](https://github.com/replit/river/blob/main/__tests__/fixtures/services.ts)
+
 ## Developing
 
 [![Run on Repl.it](https://replit.com/badge/github/replit/river)](https://replit.com/new/github/replit/river)

package/dist/{chunk-IEU7OE5W.js → chunk-5735JCTZ.js}

@@ -1,12 +1,12 @@
 import {
   WebSocketConnection
-} from "./chunk-SZTOUKL7.js";
+} from "./chunk-KRYKORQT.js";
 import {
   NaiveJsonCodec
 } from "./chunk-R6H2BIMC.js";
 import {
   Transport
-} from "./chunk-V2YJRBRX.js";
+} from "./chunk-MF3Z3IDF.js";
 import {
   log
 } from "./chunk-SLUSVGQH.js";

package/dist/{chunk-SZTOUKL7.js → chunk-KRYKORQT.js}

@@ -1,6 +1,6 @@
 import {
   Connection
-} from "./chunk-V2YJRBRX.js";
+} from "./chunk-MF3Z3IDF.js";
 
 // transport/impls/ws/connection.ts
 var WebSocketConnection = class extends Connection {

package/dist/{chunk-PNZXYQME.js → chunk-LRQGTUTI.js}

@@ -1,12 +1,12 @@
 import {
   WebSocketConnection
-} from "./chunk-SZTOUKL7.js";
+} from "./chunk-KRYKORQT.js";
 import {
   NaiveJsonCodec
 } from "./chunk-R6H2BIMC.js";
 import {
   Transport
-} from "./chunk-V2YJRBRX.js";
+} from "./chunk-MF3Z3IDF.js";
 import {
   log
 } from "./chunk-SLUSVGQH.js";

package/dist/{chunk-V2YJRBRX.js → chunk-MF3Z3IDF.js}

@@ -184,9 +184,6 @@ var Transport = class {
       }
     } else {
       log?.info(`${this.clientId} -- received msg: ${JSON.stringify(msg)}`);
-      if (msg.to !== this.clientId) {
-        return;
-      }
       this.eventDispatcher.dispatchEvent("message", msg);
       if (!isAck(msg.controlFlags)) {
         const ackMsg = reply(msg, { ack: msg.id });

package/dist/{chunk-IYRPZPSQ.js → chunk-SCULZ4KS.js}

@@ -515,6 +515,12 @@ function handleRpc(transport, serverId, input, serviceName, procName) {
       transport.removeEventListener("connectionStatus", onConnectionStatus);
     }
     function onMessage(msg2) {
+      if (msg2.streamId !== streamId) {
+        return;
+      }
+      if (msg2.to !== transport.clientId) {
+        return;
+      }
       if (msg2.streamId === streamId) {
         cleanup();
         resolve(msg2.payload);
@@ -560,6 +566,9 @@ function handleStream(transport, serverId, init, serviceName, procName) {
     if (msg2.streamId !== streamId) {
       return;
     }
+    if (msg2.to !== transport.clientId) {
+      return;
+    }
     if (isStreamClose(msg2.controlFlags)) {
       cleanup();
     } else {
@@ -606,6 +615,9 @@ function handleSubscribe(transport, serverId, input, serviceName, procName) {
     if (msg2.streamId !== streamId) {
       return;
     }
+    if (msg2.to !== transport.clientId) {
+      return;
+    }
     if (isStreamClose(msg2.controlFlags)) {
       cleanup();
     } else {
@@ -680,6 +692,9 @@ function handleUpload(transport, serverId, input, serviceName, procName) {
       transport.removeEventListener("connectionStatus", onConnectionStatus);
     }
     function onMessage(msg2) {
+      if (msg2.to !== transport.clientId) {
+        return;
+      }
       if (msg2.streamId === streamId) {
         cleanup();
         resolve(msg2.payload);

package/dist/{chunk-TZSX5KM2.js → chunk-XWRKNZSC.js}

@@ -1,6 +1,6 @@
 import {
   Connection
-} from "./chunk-V2YJRBRX.js";
+} from "./chunk-MF3Z3IDF.js";
 
 // transport/transforms/delim.ts
 import { Transform } from "node:stream";

package/dist/router/index.cjs

@@ -595,6 +595,12 @@ function handleRpc(transport, serverId, input, serviceName, procName) {
       transport.removeEventListener("connectionStatus", onConnectionStatus);
     }
     function onMessage(msg2) {
+      if (msg2.streamId !== streamId) {
+        return;
+      }
+      if (msg2.to !== transport.clientId) {
+        return;
+      }
       if (msg2.streamId === streamId) {
         cleanup();
         resolve(msg2.payload);
@@ -640,6 +646,9 @@ function handleStream(transport, serverId, init, serviceName, procName) {
     if (msg2.streamId !== streamId) {
       return;
     }
+    if (msg2.to !== transport.clientId) {
+      return;
+    }
     if (isStreamClose(msg2.controlFlags)) {
       cleanup();
     } else {
@@ -686,6 +695,9 @@ function handleSubscribe(transport, serverId, input, serviceName, procName) {
     if (msg2.streamId !== streamId) {
       return;
     }
+    if (msg2.to !== transport.clientId) {
+      return;
+    }
     if (isStreamClose(msg2.controlFlags)) {
       cleanup();
     } else {
@@ -760,6 +772,9 @@ function handleUpload(transport, serverId, input, serviceName, procName) {
       transport.removeEventListener("connectionStatus", onConnectionStatus);
     }
     function onMessage(msg2) {
+      if (msg2.to !== transport.clientId) {
+        return;
+      }
       if (msg2.streamId === streamId) {
         cleanup();
         resolve(msg2.payload);

package/dist/router/index.js

@@ -8,7 +8,7 @@ import {
   createClient,
   createServer,
   serializeService
-} from "../chunk-IYRPZPSQ.js";
+} from "../chunk-SCULZ4KS.js";
 import "../chunk-ZE4MX7DF.js";
 import "../chunk-SLUSVGQH.js";
 export {

package/dist/transport/impls/stdio/stdio.cjs

@@ -341,9 +341,6 @@ var Transport = class {
       }
     } else {
       log?.info(`${this.clientId} -- received msg: ${JSON.stringify(msg)}`);
-      if (msg.to !== this.clientId) {
-        return;
-      }
       this.eventDispatcher.dispatchEvent("message", msg);
       if (!isAck(msg.controlFlags)) {
         const ackMsg = reply(msg, { ack: msg.id });

package/dist/transport/impls/stdio/stdio.js

@@ -1,14 +1,14 @@
 import {
   StreamConnection,
   createDelimitedStream
-} from "../../../chunk-TZSX5KM2.js";
+} from "../../../chunk-XWRKNZSC.js";
 import "../../../chunk-ORAG7IAU.js";
 import {
   NaiveJsonCodec
 } from "../../../chunk-R6H2BIMC.js";
 import {
   Transport
-} from "../../../chunk-V2YJRBRX.js";
+} from "../../../chunk-MF3Z3IDF.js";
 import "../../../chunk-ZE4MX7DF.js";
 import {
   log

package/dist/transport/impls/unixsocket/client.cjs

@@ -241,9 +241,6 @@ var Transport = class {
       }
     } else {
       log?.info(`${this.clientId} -- received msg: ${JSON.stringify(msg)}`);
-      if (msg.to !== this.clientId) {
-        return;
-      }
       this.eventDispatcher.dispatchEvent("message", msg);
       if (!isAck(msg.controlFlags)) {
         const ackMsg = reply(msg, { ack: msg.id });

package/dist/transport/impls/unixsocket/client.js

@@ -1,7 +1,7 @@
 import {
   StreamConnection,
   createDelimitedStream
-} from "../../../chunk-TZSX5KM2.js";
+} from "../../../chunk-XWRKNZSC.js";
 import "../../../chunk-ORAG7IAU.js";
 import "../../../chunk-WVT5QXMZ.js";
 import {
@@ -9,7 +9,7 @@ import {
 } from "../../../chunk-R6H2BIMC.js";
 import {
   Transport
-} from "../../../chunk-V2YJRBRX.js";
+} from "../../../chunk-MF3Z3IDF.js";
 import "../../../chunk-ZE4MX7DF.js";
 import {
   log

package/dist/transport/impls/unixsocket/server.cjs

@@ -241,9 +241,6 @@ var Transport = class {
       }
     } else {
       log?.info(`${this.clientId} -- received msg: ${JSON.stringify(msg)}`);
-      if (msg.to !== this.clientId) {
-        return;
-      }
       this.eventDispatcher.dispatchEvent("message", msg);
       if (!isAck(msg.controlFlags)) {
         const ackMsg = reply(msg, { ack: msg.id });

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

@@ -1,7 +1,7 @@
 import {
   StreamConnection,
   createDelimitedStream
-} from "../../../chunk-TZSX5KM2.js";
+} from "../../../chunk-XWRKNZSC.js";
 import "../../../chunk-ORAG7IAU.js";
 import "../../../chunk-WVT5QXMZ.js";
 import {
@@ -9,7 +9,7 @@ import {
 } from "../../../chunk-R6H2BIMC.js";
 import {
   Transport
-} from "../../../chunk-V2YJRBRX.js";
+} from "../../../chunk-MF3Z3IDF.js";
 import "../../../chunk-ZE4MX7DF.js";
 import {
   log

package/dist/transport/impls/ws/client.cjs

@@ -241,9 +241,6 @@ var Transport = class {
       }
     } else {
       log?.info(`${this.clientId} -- received msg: ${JSON.stringify(msg)}`);
-      if (msg.to !== this.clientId) {
-        return;
-      }
       this.eventDispatcher.dispatchEvent("message", msg);
       if (!isAck(msg.controlFlags)) {
         const ackMsg = reply(msg, { ack: msg.id });

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

@@ -1,9 +1,9 @@
 import {
   WebSocketClientTransport
-} from "../../../chunk-IEU7OE5W.js";
-import "../../../chunk-SZTOUKL7.js";
+} from "../../../chunk-5735JCTZ.js";
+import "../../../chunk-KRYKORQT.js";
 import "../../../chunk-R6H2BIMC.js";
-import "../../../chunk-V2YJRBRX.js";
+import "../../../chunk-MF3Z3IDF.js";
 import "../../../chunk-ZE4MX7DF.js";
 import "../../../chunk-SLUSVGQH.js";
 export {

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

@@ -287,9 +287,6 @@ var Transport = class {
       }
     } else {
       log?.info(`${this.clientId} -- received msg: ${JSON.stringify(msg)}`);
-      if (msg.to !== this.clientId) {
-        return;
-      }
       this.eventDispatcher.dispatchEvent("message", msg);
       if (!isAck(msg.controlFlags)) {
         const ackMsg = reply(msg, { ack: msg.id });

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

@@ -1,10 +1,10 @@
 import {
   WebSocketServerTransport
-} from "../../../chunk-PNZXYQME.js";
-import "../../../chunk-SZTOUKL7.js";
+} from "../../../chunk-LRQGTUTI.js";
+import "../../../chunk-KRYKORQT.js";
 import "../../../chunk-WVT5QXMZ.js";
 import "../../../chunk-R6H2BIMC.js";
-import "../../../chunk-V2YJRBRX.js";
+import "../../../chunk-MF3Z3IDF.js";
 import "../../../chunk-ZE4MX7DF.js";
 import "../../../chunk-SLUSVGQH.js";
 export {

package/dist/transport/index.cjs

@@ -258,9 +258,6 @@ var Transport = class {
       }
     } else {
       log?.info(`${this.clientId} -- received msg: ${JSON.stringify(msg2)}`);
-      if (msg2.to !== this.clientId) {
-        return;
-      }
       this.eventDispatcher.dispatchEvent("message", msg2);
       if (!isAck(msg2.controlFlags)) {
         const ackMsg = reply(msg2, { ack: msg2.id });

package/dist/transport/index.js

@@ -2,7 +2,7 @@ import "../chunk-ORAG7IAU.js";
 import {
   Connection,
   Transport
-} from "../chunk-V2YJRBRX.js";
+} from "../chunk-MF3Z3IDF.js";
 import {
   OpaqueTransportMessageSchema,
   TransportMessageSchema,

package/dist/util/testHelpers.cjs

@@ -278,9 +278,6 @@ var Transport = class {
       }
     } else {
       log?.info(`${this.clientId} -- received msg: ${JSON.stringify(msg2)}`);
-      if (msg2.to !== this.clientId) {
-        return;
-      }
       this.eventDispatcher.dispatchEvent("message", msg2);
       if (!isAck(msg2.controlFlags)) {
         const ackMsg = reply(msg2, { ack: msg2.id });

package/dist/util/testHelpers.js

@@ -1,18 +1,18 @@
 import {
   UNCAUGHT_ERROR,
   pushable
-} from "../chunk-IYRPZPSQ.js";
+} from "../chunk-SCULZ4KS.js";
 import {
   WebSocketClientTransport
-} from "../chunk-IEU7OE5W.js";
+} from "../chunk-5735JCTZ.js";
 import {
   WebSocketServerTransport
-} from "../chunk-PNZXYQME.js";
-import "../chunk-SZTOUKL7.js";
+} from "../chunk-LRQGTUTI.js";
+import "../chunk-KRYKORQT.js";
 import "../chunk-ORAG7IAU.js";
 import "../chunk-WVT5QXMZ.js";
 import "../chunk-R6H2BIMC.js";
-import "../chunk-V2YJRBRX.js";
+import "../chunk-MF3Z3IDF.js";
 import {
   msg
 } from "../chunk-ZE4MX7DF.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@replit/river",
   "description": "It's like tRPC but... with JSON Schema Support, duplex streaming and support for service multiplexing. Transport agnostic!",
-  "version": "0.10.5",
+  "version": "0.10.6",
   "type": "module",
   "exports": {
     ".": {