@replit/river 0.23.16 → 0.24.0

package/README.md

@@ -1,6 +1,6 @@
 # River
 
-⚠️ Not production ready, while Replit is using parts of river in production, we are still going through rapid breaking changes. First production ready version will be 1.x.x ⚠️
+⚠️ Not production ready, while Replit is using parts of River in production, we are still going through rapid breaking changes. First production ready version will be `1.x.x` ⚠️
 
 River allows multiple clients to connect to and make remote procedure calls to a remote server as if they were local procedures.
 
@@ -80,7 +80,7 @@ Before proceeding, ensure you have TypeScript 5 installed and configured appropr
 First, we create a service using `ServiceSchema`:
 
 ```ts
-import { ServicaSchema, Procedure, Ok } from '@replit/river';
+import { ServiceSchema, Procedure, Ok } from '@replit/river';
 import { Type } from '@sinclair/typebox';
 
 export const ExampleService = ServiceSchema.define(
@@ -134,17 +134,17 @@ In another file for the client (to create a separate entrypoint),
 ```ts
 import { WebSocketClientTransport } from '@replit/river/transport/ws/client';
 import { createClient } from '@replit/river';
-import type ServiceSurface from './server';
+import { WebSocket } from 'ws';
 
 const transport = new WebSocketClientTransport(
   async () => new WebSocket('ws://localhost:3000'),
   'my-client-id',
 );
 
-const client = createClient<ServiceSurface>(
+const client = createClient(
   transport,
   'SERVER', // transport id of the server in the previous step
-  true, // whether to eagerly connect to the server on creation (optional argument)
+  { eagerlyConnect: true }, // whether to eagerly connect to the server on creation (optional argument)
 );
 
 // we get full type safety on `client`
@@ -157,15 +157,6 @@ if (result.ok) {
 }
 ```
 
-You can then access the `ParsedMetadata` in your procedure handlers:
-
-```ts
-async handler(ctx, ...args) {
-  // this contains the parsed metadata
-  console.log(ctx.metadata)
-}
-```
-
 ### Logging
 
 To add logging, you can bind a logging function to a transport.
@@ -192,12 +183,12 @@ River defines two types of reconnects:
 1. **Transparent reconnects:** These occur when the connection is temporarily lost and reestablished without losing any messages. From the application's perspective, this process is seamless and does not disrupt ongoing operations.
 2. **Hard reconnect:** This occurs when all server state is lost, requiring the client to reinitialize anything stateful (e.g. subscriptions).
 
-You can listen for transparent reconnects via the `connectionStatus` events, but realistically, no applications should need to listen for this unless it is for debugging purposes. Hard reconnects are signaled via `sessionStatus` events.
+Hard reconnects are signaled via `sessionStatus` events.
 
 If your application is stateful on either the server or the client, the service consumer _should_ wrap all the client-side setup with `transport.addEventListener('sessionStatus', (evt) => ...)` to do appropriate setup and teardown.
 
 ```ts
-transport.addEventListener('connectionStatus', (evt) => {
+transport.addEventListener('sessionStatus', (evt) => {
   if (evt.status === 'connect') {
     // do something
   } else if (evt.status === 'disconnect') {
@@ -205,11 +196,12 @@ transport.addEventListener('connectionStatus', (evt) => {
   }
 });
 
-transport.addEventListener('sessionStatus', (evt) => {
-  if (evt.status === 'connect') {
+// or, listen for specific session states
+transport.addEventListener('sessionTransition', (evt) => {
+  if (evt.state === SessionState.Connected) {
+    // switch on various transition states
+  } else if (evt.state === SessionState.NoConnection) {
     // do something
-  } else if (evt.status === 'disconnect') {
-    // do something else
   }
 });
 ```
@@ -253,6 +245,15 @@ createServer(new MockServerTransport('SERVER'), services, {
 });
 ```
 
+You can then access the `ParsedMetadata` in your procedure handlers:
+
+```ts
+async handler(ctx, ...args) {
+  // this contains the parsed metadata
+  console.log(ctx.metadata)
+}
+```
+
 ### 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).

package/dist/{chunk-UDXM64QK.js → chunk-AASMR3CQ.js}

@@ -1,6 +1,6 @@
 import {
   Connection
-} from "./chunk-YXDAOVP7.js";
+} from "./chunk-ZAT3R4CU.js";
 
 // transport/transforms/messageFraming.ts
 import { Transform } from "node:stream";
@@ -71,36 +71,42 @@ var UdsConnection = class extends Connection {
     this.framer = MessageFramer.createFramedStream();
     this.sock = sock;
     this.input = sock.pipe(this.framer);
-  }
-  addDataListener(cb) {
-    this.input.on("data", cb);
-  }
-  removeDataListener(cb) {
-    this.input.off("data", cb);
-  }
-  addCloseListener(cb) {
-    this.sock.on("close", cb);
-  }
-  addErrorListener(cb) {
+    this.sock.on("close", () => {
+      for (const cb of this.closeListeners) {
+        cb();
+      }
+    });
     this.sock.on("error", (err) => {
       if (err instanceof Error && "code" in err && err.code === "EPIPE") {
         return;
       }
-      cb(err);
+      for (const cb of this.errorListeners) {
+        cb(err);
+      }
+    });
+    this.input.on("data", (msg) => {
+      for (const cb of this.dataListeners) {
+        cb(msg);
+      }
+    });
+    this.sock.on("end", () => {
+      this.sock.destroy();
     });
   }
   send(payload) {
-    if (this.framer.destroyed || !this.sock.writable)
+    if (this.framer.destroyed || !this.sock.writable || this.sock.closed) {
       return false;
-    return this.sock.write(MessageFramer.write(payload));
+    }
+    this.sock.write(MessageFramer.write(payload));
+    return true;
   }
   close() {
-    this.sock.destroy();
-    this.framer.destroy();
+    this.sock.end();
+    this.framer.end();
   }
 };
 
 export {
   UdsConnection
 };
-//# sourceMappingURL=chunk-UDXM64QK.js.map
+//# sourceMappingURL=chunk-AASMR3CQ.js.map

package/dist/chunk-AASMR3CQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../transport/transforms/messageFraming.ts","../transport/impls/uds/connection.ts"],"sourcesContent":["import { Transform, TransformCallback, TransformOptions } from 'node:stream';\n\nexport interface LengthEncodedOptions extends TransformOptions {\n  /** Maximum in-memory buffer size before we throw */\n  maxBufferSizeBytes: number;\n}\n\n/**\n * A transform stream that emits data each time a message with a network/BigEndian uint32 length prefix is received.\n * @extends Transform\n */\nexport class Uint32LengthPrefixFraming extends Transform {\n  receivedBuffer: Buffer;\n  maxBufferSizeBytes: number;\n\n  constructor({ maxBufferSizeBytes, ...options }: LengthEncodedOptions) {\n    super(options);\n    this.maxBufferSizeBytes = maxBufferSizeBytes;\n    this.receivedBuffer = Buffer.alloc(0);\n  }\n\n  _transform(chunk: Buffer, _encoding: BufferEncoding, cb: TransformCallback) {\n    if (\n      this.receivedBuffer.byteLength + chunk.byteLength >\n      this.maxBufferSizeBytes\n    ) {\n      const err = new Error(\n        `buffer overflow: ${this.receivedBuffer.byteLength}B > ${this.maxBufferSizeBytes}B`,\n      );\n\n      this.emit('error', err);\n      cb(err);\n      return;\n    }\n\n    this.receivedBuffer = Buffer.concat([this.receivedBuffer, chunk]);\n\n    // ensure there's enough for a length prefix\n    while (this.receivedBuffer.length > 4) {\n      // read length from buffer (accounting for uint32 prefix)\n      const claimedMessageLength = this.receivedBuffer.readUInt32BE(0) + 4;\n      if (this.receivedBuffer.length >= claimedMessageLength) {\n        // slice the buffer to extract the message\n        const message = this.receivedBuffer.subarray(4, claimedMessageLength);\n        this.push(message);\n        this.receivedBuffer =\n          this.receivedBuffer.subarray(claimedMessageLength);\n      } else {\n        // not enough data for a complete message, wait for more data\n        break;\n      }\n    }\n\n    cb();\n  }\n\n  _flush(cb: TransformCallback) {\n    // if there's any leftover data that doesn't form a complete message\n    if (this.receivedBuffer.length) {\n      this.emit('error', new Error('got incomplete message while flushing'));\n    }\n\n    this.receivedBuffer = Buffer.alloc(0);\n    cb();\n  }\n\n  _destroy(error: Error | null, callback: (error: Error | null) => void): void {\n    this.receivedBuffer = Buffer.alloc(0);\n    super._destroy(error, callback);\n  }\n}\n\nfunction createLengthEncodedStream(options?: Partial<LengthEncodedOptions>) {\n  return new Uint32LengthPrefixFraming({\n    maxBufferSizeBytes: options?.maxBufferSizeBytes ?? 16 * 1024 * 1024, // 16MB\n  });\n}\n\nexport const MessageFramer = {\n  createFramedStream: createLengthEncodedStream,\n  write: (buf: Uint8Array) => {\n    const lengthPrefix = Buffer.alloc(4);\n    lengthPrefix.writeUInt32BE(buf.length, 0);\n    return Buffer.concat([lengthPrefix, buf]);\n  },\n};\n","import { type Socket } from 'node:net';\nimport stream from 'node:stream';\nimport {\n  MessageFramer,\n  Uint32LengthPrefixFraming,\n} from '../../transforms/messageFraming';\nimport { Connection } from '../../connection';\n\nexport class UdsConnection extends Connection {\n  sock: Socket;\n  input: stream.Readable;\n  framer: Uint32LengthPrefixFraming;\n  constructor(sock: Socket) {\n    super();\n    this.framer = MessageFramer.createFramedStream();\n    this.sock = sock;\n    this.input = sock.pipe(this.framer);\n\n    this.sock.on('close', () => {\n      for (const cb of this.closeListeners) {\n        cb();\n      }\n    });\n\n    this.sock.on('error', (err) => {\n      if (err instanceof Error && 'code' in err && err.code === 'EPIPE') {\n        // Ignore EPIPE errors\n        return;\n      }\n\n      for (const cb of this.errorListeners) {\n        cb(err);\n      }\n    });\n\n    this.input.on('data', (msg: Uint8Array) => {\n      for (const cb of this.dataListeners) {\n        cb(msg);\n      }\n    });\n\n    this.sock.on('end', () => {\n      this.sock.destroy();\n    });\n  }\n\n  send(payload: Uint8Array) {\n    if (this.framer.destroyed || !this.sock.writable || this.sock.closed) {\n      return false;\n    }\n    this.sock.write(MessageFramer.write(payload));\n    return true;\n  }\n\n  close() {\n    this.sock.end();\n    this.framer.end();\n  }\n}\n"],"mappings":"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","names":[]}