@replit/river 0.16.1 → 0.17.0

package/README.md

@@ -22,32 +22,46 @@ See [PROTOCOL.md](./PROTOCOL.md) for more information on the protocol.
 
 Before proceeding, ensure you have TypeScript 5 installed and configured appropriately:
 
-1. **Ensure `"moduleResolution": "bundler"` in tsconfig.json**:
+1. **Ensure your `tsconfig.json` is configured correctly**:
 
-   ```json
+   You must verify that:
+
+   - `compilerOptions.moduleResolution` is set to `"bundler"`
+   - `compilerOptions.strictFunctionTypes` is set to `true`
+   - `compilerOptions.strictNullChecks` is set to `true`
+
+   or, preferably, that:
+
+   - `compilerOptions.moduleResolution` is set to `"bundler"`
+   - `compilerOptions.strict` is set to `true`
+
+   Like so:
+
+   ```jsonc
    {
      "compilerOptions": {
-       "moduleResolution": "bundler"
+       "moduleResolution": "bundler",
+       "strict": true
        // Other compiler options...
      }
    }
    ```
 
-   If it exists but is set to a different value, modify it to `"bundler"`.
+   If these options already exist in your `tsconfig.json` and don't match what is shown above, modify them. River is designed for `"strict": true`, but technically only `strictFunctionTypes` and `strictNullChecks` being set to `true` is required. Failing to set these will cause unresolvable type errors when defining services.
 
 2. Install River and Dependencies:
 
-To use River, install the required packages using npm:
+   To use River, install the required packages using npm:
 
-```bash
-  npm i @replit/river @sinclair/typebox
-```
+   ```bash
+   npm i @replit/river @sinclair/typebox
+   ```
 
 3. If you plan on using WebSocket for the underlying transport, also install
 
-```bash
-npm i ws isomorphic-ws
-```
+   ```bash
+   npm i ws isomorphic-ws
+   ```
 
 ## Writing services
 

package/dist/{chunk-Q6WPGM3K.js → chunk-7IQO434V.js}

@@ -3,7 +3,7 @@ import {
   coerceErrorString,
   isStreamClose,
   isStreamOpen
-} from "./chunk-GFRAOY75.js";
+} from "./chunk-VH3NGOXQ.js";
 import {
   log
 } from "./chunk-H4BYJELI.js";
@@ -570,8 +570,13 @@ function _createRecursiveProxy(callback, path) {
   });
   return proxy;
 }
-var createClient = (transport, serverId, eagerlyConnect = true) => {
-  if (eagerlyConnect) {
+var defaultClientOptions = {
+  connectOnInvoke: true,
+  eagerlyConnect: true
+};
+var createClient = (transport, serverId, providedClientOptions = {}) => {
+  const options = { ...defaultClientOptions, ...providedClientOptions };
+  if (options.eagerlyConnect) {
     void transport.connect(serverId);
   }
   return _createRecursiveProxy(async (opts) => {
@@ -587,6 +592,9 @@ var createClient = (transport, serverId, eagerlyConnect = true) => {
         input
       )}`
     );
+    if (options.connectOnInvoke && !transport.connections.has(serverId)) {
+      void transport.connect(serverId);
+    }
     if (procType === "rpc") {
       return handleRpc(
         transport,

package/dist/{chunk-7SPCAA6Q.js → chunk-LQMPJI3S.js}

@@ -7,7 +7,7 @@ import {
   handshakeRequestMessage,
   handshakeResponseMessage,
   isAck
-} from "./chunk-GFRAOY75.js";
+} from "./chunk-VH3NGOXQ.js";
 import {
   log
 } from "./chunk-H4BYJELI.js";
@@ -19,7 +19,8 @@ import {
 var ProtocolError = {
   RetriesExceeded: "conn_retry_exceeded",
   HandshakeFailed: "handshake_failed",
-  UseAfterDestroy: "use_after_destroy"
+  UseAfterDestroy: "use_after_destroy",
+  MessageOrderingViolated: "message_ordering_violated"
 };
 var EventDispatcher = class {
   eventListeners = {};
@@ -74,7 +75,12 @@ var Session = class {
   /**
    * The unique ID of this session.
    */
-  debugId;
+  id;
+  /**
+   * What the other side advertised as their session ID
+   * for this session.
+   */
+  advertisedSessionId;
   /**
    * Number of messages we've sent along this session (excluding handshake and acks)
    */
@@ -96,11 +102,11 @@ var Session = class {
    * The interval for sending heartbeats.
    */
   heartbeat;
-  constructor(from, connectedTo, conn, options) {
+  constructor(conn, from, to, options) {
+    this.id = `session-${nanoid(12)}`;
     this.options = options;
-    this.debugId = `sess-${unsafeId()}`;
     this.from = from;
-    this.to = connectedTo;
+    this.to = to;
     this.connection = conn;
     this.codec = options.codec;
     this.heartbeatMisses = 0;
@@ -140,7 +146,7 @@ var Session = class {
         log?.info(
           `${this.from} -- closing connection (id: ${this.connection.debugId}) to ${this.to} due to inactivity`
         );
-        this.closeStaleConnection(this.connection);
+        this.closeStaleConnection();
       }
       return;
     }
@@ -171,33 +177,37 @@ var Session = class {
       log?.debug(`${this.from} -- resending ${msg.id} (seq: ${msg.seq})`);
       const ok = this.connection.send(this.codec.toBuffer(msg));
       if (!ok) {
-        const msg2 = `${this.from} -- failed to send buffered message to ${this.to} in session (id: ${this.debugId}) (if you hit this code path something is seriously wrong)`;
+        const msg2 = `${this.from} -- failed to send buffered message to ${this.to} in session (id: ${this.id}) (if you hit this code path something is seriously wrong)`;
         log?.error(msg2);
         throw new Error(msg2);
       }
     }
   }
   updateBookkeeping(ack, seq) {
+    if (seq + 1 < this.ack) {
+      log?.error(`${this.from} -- received stale seq ${seq} + 1 < ${this.ack}`);
+      return;
+    }
     this.sendBuffer = this.sendBuffer.filter((unacked) => unacked.seq > ack);
     this.ack = seq + 1;
   }
   closeStaleConnection(conn) {
-    if (!this.connection || this.connection !== conn)
+    if (this.connection === void 0 || this.connection === conn)
       return;
     log?.info(
-      `${this.from} -- closing old inner connection (id: ${this.connection.debugId}) from session (id: ${this.debugId}) to ${this.to}`
+      `${this.from} -- closing old inner connection (id: ${this.connection.debugId}) from session (id: ${this.id}) to ${this.to}`
     );
     this.connection.close();
     this.connection = void 0;
   }
   replaceWithNewConnection(newConn) {
-    this.closeStaleConnection(this.connection);
+    this.closeStaleConnection(newConn);
     this.cancelGrace();
     this.connection = newConn;
   }
   beginGrace(cb) {
     log?.info(
-      `${this.from} -- starting ${this.options.sessionDisconnectGraceMs}ms grace period until session (id: ${this.debugId}) to ${this.to} is closed`
+      `${this.from} -- starting ${this.options.sessionDisconnectGraceMs}ms grace period until session (id: ${this.id}) to ${this.to} is closed`
     );
     this.disconnectionGrace = setTimeout(() => {
       this.close();
@@ -208,11 +218,12 @@ var Session = class {
   cancelGrace() {
     this.heartbeatMisses = 0;
     clearTimeout(this.disconnectionGrace);
+    this.disconnectionGrace = void 0;
   }
   // closed when we want to discard the whole session
   // (i.e. shutdown or session disconnect)
   close() {
-    this.closeStaleConnection(this.connection);
+    this.closeStaleConnection();
     this.cancelGrace();
     this.resetBufferedMessages();
     clearInterval(this.heartbeat);
@@ -243,7 +254,6 @@ var Session = class {
 
 // transport/transport.ts
 import { Value } from "@sinclair/typebox/value";
-import { nanoid as nanoid2 } from "nanoid";
 
 // transport/rateLimit.ts
 var LeakyBucketRateLimit = class {
@@ -331,17 +341,10 @@ var defaultConnectionRetryOptions = {
   budgetRestoreIntervalMs: 200
 };
 var defaultClientTransportOptions = {
-  connectionRetryOptions: defaultConnectionRetryOptions,
-  ...defaultTransportOptions
+  ...defaultTransportOptions,
+  ...defaultConnectionRetryOptions
 };
 var Transport = class {
-  /**
-   * Unique per instance of the transport.
-   * This allows us to distinguish reconnects to different
-   * transports.
-   */
-  instanceId = nanoid2();
-  connectedInstanceIds = /* @__PURE__ */ new Map();
   /**
    * A flag indicating whether the transport has been destroyed.
    * A destroyed transport will not attempt to reconnect and cannot be used again.
@@ -394,41 +397,41 @@ var Transport = class {
    * and we know the identity of the connected client.
    * @param conn The connection object.
    */
-  onConnect(conn, connectedTo, instanceId) {
+  onConnect(conn, connectedTo, advertisedSessionId) {
     this.eventDispatcher.dispatchEvent("connectionStatus", {
       status: "connect",
       conn
     });
     let oldSession = this.sessions.get(connectedTo);
-    const lastInstanceId = this.connectedInstanceIds.get(connectedTo);
-    if (oldSession && lastInstanceId !== void 0 && lastInstanceId !== instanceId) {
+    if (oldSession?.advertisedSessionId && oldSession.advertisedSessionId !== advertisedSessionId) {
       log?.warn(
-        `${this.clientId} -- connection from ${connectedTo} is a different instance (got: ${instanceId}, last connected to: ${lastInstanceId}), starting a new session`
+        `${this.clientId} -- connection from ${connectedTo} is a different session (id: ${advertisedSessionId}, last connected to: ${oldSession.advertisedSessionId}), starting a new session`
       );
       oldSession.close();
       this.deleteSession(oldSession);
       oldSession = void 0;
     }
-    this.connectedInstanceIds.set(connectedTo, instanceId);
     if (oldSession === void 0) {
       const newSession = this.createSession(connectedTo, conn);
+      newSession.advertisedSessionId = advertisedSessionId;
       log?.info(
-        `${this.clientId} -- new connection (id: ${conn.debugId}) for new session (id: ${newSession.debugId}) to ${connectedTo}`
+        `${this.clientId} -- new connection (id: ${conn.debugId}) for new session (id: ${newSession.id}) to ${connectedTo}`
       );
       return newSession;
     }
     log?.info(
-      `${this.clientId} -- new connection (id: ${conn.debugId}) for existing session (id: ${oldSession.debugId}) to ${connectedTo}`
+      `${this.clientId} -- new connection (id: ${conn.debugId}) for existing session (id: ${oldSession.id}) to ${connectedTo}`
     );
     oldSession.replaceWithNewConnection(conn);
     oldSession.sendBufferedMessages();
+    oldSession.advertisedSessionId = advertisedSessionId;
     return oldSession;
   }
-  createSession(connectedTo, conn) {
+  createSession(to, conn) {
     const session = new Session(
-      this.clientId,
-      connectedTo,
       conn,
+      this.clientId,
+      to,
       this.options
     );
     this.sessions.set(session.to, session);
@@ -438,10 +441,20 @@ var Transport = class {
     });
     return session;
   }
+  getOrCreateSession(to, conn) {
+    let session = this.sessions.get(to);
+    if (!session) {
+      session = this.createSession(to, conn);
+      log?.info(
+        `${this.clientId} -- no session for ${to}, created a new one (id: ${session.id})`
+      );
+    }
+    return session;
+  }
   deleteSession(session) {
     this.sessions.delete(session.to);
     log?.info(
-      `${this.clientId} -- session ${session.debugId} disconnect from ${session.to}`
+      `${this.clientId} -- session ${session.id} disconnect from ${session.to}`
     );
     this.eventDispatcher.dispatchEvent("sessionStatus", {
       status: "disconnect",
@@ -509,11 +522,14 @@ var Transport = class {
           )}`
         );
       } else {
+        const errMsg = `received out-of-order msg (got seq: ${msg.seq}, wanted seq: ${session.nextExpectedSeq})`;
         log?.error(
-          `${this.clientId} -- received out-of-order msg (got: ${msg.seq}, wanted: ${session.nextExpectedSeq}), marking connection as dead: ${JSON.stringify(msg)}`
+          `${this.clientId} -- fatal: ${errMsg}, marking connection as dead: ${JSON.stringify(
+            msg
+          )}`
         );
+        this.protocolError(ProtocolError.MessageOrderingViolated, errMsg);
         session.close();
-        this.deleteSession(session);
       }
       return;
     }
@@ -560,14 +576,7 @@ var Transport = class {
       );
       return void 0;
     }
-    let session = this.sessions.get(to);
-    if (!session) {
-      session = this.createSession(to, void 0);
-      log?.info(
-        `${this.clientId} -- no session for ${to}, created a new one (id: ${session.debugId})`
-      );
-    }
-    return session.send(msg);
+    return this.getOrCreateSession(to).send(msg);
   }
   // control helpers
   sendCloseStream(to, streamId) {
@@ -619,7 +628,13 @@ var ClientTransport = class extends Transport {
    */
   inflightConnectionPromises;
   retryBudget;
-  tryReconnecting = true;
+  /**
+   * A flag indicating whether the transport should automatically reconnect
+   * when a connection is dropped.
+   * Realistically, this should always be true for clients unless you are writing
+   * tests or a special case where you don't want to reconnect.
+   */
+  reconnectOnConnectionDrop = true;
   constructor(clientId, providedOptions) {
     super(clientId, providedOptions);
     this.options = {
@@ -627,21 +642,20 @@ var ClientTransport = class extends Transport {
       ...providedOptions
     };
     this.inflightConnectionPromises = /* @__PURE__ */ new Map();
-    this.retryBudget = new LeakyBucketRateLimit(
-      this.options.connectionRetryOptions
-    );
+    this.retryBudget = new LeakyBucketRateLimit(this.options);
   }
   handleConnection(conn, to) {
     if (this.state !== "open")
       return;
     let session = void 0;
     const handshakeHandler = (data) => {
-      const handshake = this.receiveHandshakeResponseMessage(data);
-      if (!handshake) {
+      const maybeSession = this.receiveHandshakeResponseMessage(data, conn);
+      if (!maybeSession) {
         conn.close();
         return;
+      } else {
+        session = maybeSession;
       }
-      session = this.onConnect(conn, handshake.from, handshake.instanceId);
       conn.removeDataListener(handshakeHandler);
       conn.addDataListener((data2) => {
         const parsed = this.parseMsg(data2);
@@ -661,7 +675,7 @@ var ClientTransport = class extends Transport {
         `${this.clientId} -- connection (id: ${conn.debugId}) to ${to} disconnected`
       );
       this.inflightConnectionPromises.delete(to);
-      if (this.tryReconnecting) {
+      if (this.reconnectOnConnectionDrop) {
         void this.connect(to);
       }
     });
@@ -671,7 +685,7 @@ var ClientTransport = class extends Transport {
       );
     });
   }
-  receiveHandshakeResponseMessage(data) {
+  receiveHandshakeResponseMessage(data, conn) {
     const parsed = this.parseMsg(data);
     if (!parsed) {
       this.protocolError(
@@ -704,12 +718,14 @@ var ClientTransport = class extends Transport {
       );
       return false;
     }
-    const instanceId = parsed.payload.status.instanceId;
-    log?.debug(
-      `${this.clientId} -- handshake from ${parsed.from} ok (instance: ${instanceId})`
+    log?.debug(`${this.clientId} -- handshake from ${parsed.from} ok`);
+    const session = this.onConnect(
+      conn,
+      parsed.from,
+      parsed.payload.status.sessionId
     );
     this.retryBudget.startRestoringBudget(parsed.from);
-    return { instanceId, from: parsed.from };
+    return session;
   }
   /**
    * Manually attempts to connect to a client.
@@ -767,7 +783,7 @@ var ClientTransport = class extends Transport {
     } catch (error) {
       this.inflightConnectionPromises.delete(to);
       const errStr = coerceErrorString(error);
-      if (!this.tryReconnecting || !canProceedWithConnection()) {
+      if (!this.reconnectOnConnectionDrop || !canProceedWithConnection()) {
         log?.warn(`${this.clientId} -- connection to ${to} failed (${errStr})`);
       } else {
         log?.warn(
@@ -778,11 +794,8 @@ var ClientTransport = class extends Transport {
     }
   }
   sendHandshake(to, conn) {
-    const requestMsg = handshakeRequestMessage(
-      this.clientId,
-      to,
-      this.instanceId
-    );
+    const session = this.getOrCreateSession(to, conn);
+    const requestMsg = handshakeRequestMessage(this.clientId, to, session.id);
     log?.debug(`${this.clientId} -- sending handshake request to ${to}`);
     conn.send(this.codec.toBuffer(requestMsg));
   }
@@ -795,7 +808,7 @@ var ServerTransport = class extends Transport {
   constructor(clientId, providedOptions) {
     super(clientId, providedOptions);
     log?.info(
-      `${this.clientId} -- initiated server transport (instance id: ${this.instanceId}, protocol: ${PROTOCOL_VERSION})`
+      `${this.clientId} -- initiated server transport (protocol: ${PROTOCOL_VERSION})`
     );
   }
   handleConnection(conn) {
@@ -807,12 +820,13 @@ var ServerTransport = class extends Transport {
     let session = void 0;
     const client = () => session?.to ?? "unknown";
     const handshakeHandler = (data) => {
-      const handshake = this.receiveHandshakeRequestMessage(data, conn);
-      if (!handshake) {
+      const maybeSession = this.receiveHandshakeRequestMessage(data, conn);
+      if (!maybeSession) {
         conn.close();
         return;
+      } else {
+        session = maybeSession;
       }
-      session = this.onConnect(conn, handshake.from, handshake.instanceId);
       conn.removeDataListener(handshakeHandler);
       conn.addDataListener((data2) => {
         const parsed = this.parseMsg(data2);
@@ -850,18 +864,13 @@ var ServerTransport = class extends Transport {
       return false;
     }
     if (!Value.Check(ControlMessageHandshakeRequestSchema, parsed.payload)) {
-      const responseMsg2 = handshakeResponseMessage(
-        this.clientId,
-        this.instanceId,
-        parsed.from,
-        false
-      );
+      const reason = "received invalid handshake msg";
+      const responseMsg2 = handshakeResponseMessage(this.clientId, parsed.from, {
+        ok: false,
+        reason
+      });
       conn.send(this.codec.toBuffer(responseMsg2));
-      log?.warn(
-        `${this.clientId} -- received invalid handshake msg: ${JSON.stringify(
-          parsed
-        )}`
-      );
+      log?.warn(`${this.clientId} -- ${reason}: ${JSON.stringify(parsed)}`);
       this.protocolError(
         ProtocolError.HandshakeFailed,
         "invalid handshake request"
@@ -870,34 +879,28 @@ var ServerTransport = class extends Transport {
     }
     const gotVersion = parsed.payload.protocolVersion;
     if (gotVersion !== PROTOCOL_VERSION) {
-      const responseMsg2 = handshakeResponseMessage(
-        this.clientId,
-        this.instanceId,
-        parsed.from,
-        false
-      );
+      const reason = `incorrect version (got: ${gotVersion} wanted ${PROTOCOL_VERSION})`;
+      const responseMsg2 = handshakeResponseMessage(this.clientId, parsed.from, {
+        ok: false,
+        reason
+      });
       conn.send(this.codec.toBuffer(responseMsg2));
       log?.warn(
         `${this.clientId} -- received handshake msg with incompatible protocol version (got: ${gotVersion}, expected: ${PROTOCOL_VERSION})`
       );
-      this.protocolError(
-        ProtocolError.HandshakeFailed,
-        `incorrect version (got: ${gotVersion} wanted ${PROTOCOL_VERSION})`
-      );
+      this.protocolError(ProtocolError.HandshakeFailed, reason);
       return false;
     }
-    const instanceId = parsed.payload.instanceId;
+    const session = this.getOrCreateSession(parsed.from, conn);
     log?.debug(
-      `${this.clientId} -- handshake from ${parsed.from} ok (instance id: ${instanceId}), responding with handshake success`
-    );
-    const responseMsg = handshakeResponseMessage(
-      this.clientId,
-      this.instanceId,
-      parsed.from,
-      true
+      `${this.clientId} -- handshake from ${parsed.from} ok, responding with handshake success`
     );
+    const responseMsg = handshakeResponseMessage(this.clientId, parsed.from, {
+      ok: true,
+      sessionId: session.id
+    });
     conn.send(this.codec.toBuffer(responseMsg));
-    return { instanceId, from: parsed.from };
+    return this.onConnect(conn, parsed.from, parsed.payload.sessionId);
   }
 };
 
@@ -905,6 +908,7 @@ export {
   ProtocolError,
   Connection,
   Session,
+  defaultTransportOptions,
   Transport,
   ClientTransport,
   ServerTransport

package/dist/{chunk-GFRAOY75.js → chunk-VH3NGOXQ.js}

@@ -19,18 +19,18 @@ var ControlMessageAckSchema = Type.Object({
 var ControlMessageCloseSchema = Type.Object({
   type: Type.Literal("CLOSE")
 });
-var PROTOCOL_VERSION = "v1";
+var PROTOCOL_VERSION = "v1.1";
 var ControlMessageHandshakeRequestSchema = Type.Object({
   type: Type.Literal("HANDSHAKE_REQ"),
   protocolVersion: Type.String(),
-  instanceId: Type.String()
+  sessionId: Type.String()
 });
 var ControlMessageHandshakeResponseSchema = Type.Object({
   type: Type.Literal("HANDSHAKE_RESP"),
   status: Type.Union([
     Type.Object({
       ok: Type.Literal(true),
-      instanceId: Type.String()
+      sessionId: Type.String()
     }),
     Type.Object({
       ok: Type.Literal(false),
@@ -47,7 +47,7 @@ var ControlMessagePayloadSchema = Type.Union([
 var OpaqueTransportMessageSchema = TransportMessageSchema(
   Type.Unknown()
 );
-function handshakeRequestMessage(from, to, instanceId) {
+function handshakeRequestMessage(from, to, sessionId) {
   return {
     id: nanoid(),
     from,
@@ -59,11 +59,11 @@ function handshakeRequestMessage(from, to, instanceId) {
     payload: {
       type: "HANDSHAKE_REQ",
       protocolVersion: PROTOCOL_VERSION,
-      instanceId
+      sessionId
     }
   };
 }
-function handshakeResponseMessage(from, instanceId, to, ok, reason) {
+function handshakeResponseMessage(from, to, status) {
   return {
     id: nanoid(),
     from,
@@ -72,18 +72,9 @@ function handshakeResponseMessage(from, instanceId, to, ok, reason) {
     ack: 0,
     streamId: nanoid(),
     controlFlags: 0,
-    payload: ok ? {
-      type: "HANDSHAKE_RESP",
-      status: {
-        ok: true,
-        instanceId
-      }
-    } : {
+    payload: {
       type: "HANDSHAKE_RESP",
-      status: {
-        ok: false,
-        reason: reason ?? "Unknown reason"
-      }
+      status
     }
   };
 }

package/dist/{chunk-L65XWBX2.js → chunk-VJRLJ3JU.js}

@@ -1,6 +1,6 @@
 import {
   Connection
-} from "./chunk-7SPCAA6Q.js";
+} from "./chunk-LQMPJI3S.js";
 
 // transport/transforms/messageFraming.ts
 import { Transform } from "node:stream";

package/dist/{chunk-XLJGKNV2.js → chunk-Y6DLSCKU.js}

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

package/dist/{connection-94896f3b.d.ts → connection-0767dc6b.d.ts}

@@ -1,4 +1,4 @@
-import { C as Connection } from './index-2e402bb8.js';
+import { C as Connection } from './index-8df0bdfb.js';
 import { Socket } from 'node:net';
 import stream, { Transform, TransformCallback, TransformOptions } from 'node:stream';
 

package/dist/{connection-99346822.d.ts → connection-f31edbcd.d.ts}

@@ -1,5 +1,5 @@
 import WebSocket from 'isomorphic-ws';
-import { C as Connection } from './index-2e402bb8.js';
+import { C as Connection } from './index-8df0bdfb.js';
 
 declare class WebSocketConnection extends Connection {
     ws: WebSocket;