@replit/river 0.17.3 → 0.18.0

package/README.md

@@ -168,12 +168,13 @@ if (result.ok) {
 To add logging,
 
 ```ts
-import { bindLogger, setLevel } from '@replit/river/logging';
+import { bindLogger, stringLogger } from '@replit/river/logging';
 
-bindLogger(console.log);
-setLevel('info');
+bindLogger(stringLogger, 'info');
 ```
 
+You can define your own logging functions that satisfy the `LogFn` type.
+
 ### Connection status
 
 River defines two types of reconnects:

package/dist/{chunk-7WY3Z5ZN.js → chunk-CLY7AQ25.js}

@@ -10,7 +10,7 @@ import {
 } from "./chunk-VH3NGOXQ.js";
 import {
   log
-} from "./chunk-H4BYJELI.js";
+} from "./chunk-YITXOAPA.js";
 import {
   NaiveJsonCodec
 } from "./chunk-GZ7HCLLM.js";
@@ -115,6 +115,14 @@ var Session = class {
       options.heartbeatIntervalMs
     );
   }
+  get loggingMetadata() {
+    return {
+      clientId: this.from,
+      connectedTo: this.to,
+      sessionId: this.id,
+      connId: this.connection?.debugId
+    };
+  }
   /**
    * Sends a message over the session's connection.
    * If the connection is not ready or the message fails to send, the message can be buffered for retry unless skipped.
@@ -125,26 +133,37 @@ var Session = class {
    */
   send(msg) {
     const fullMsg = this.constructMsg(msg);
-    log?.debug(`${this.from} -- sending ${JSON.stringify(fullMsg)}`);
+    log?.debug(`sending msg`, {
+      ...this.loggingMetadata,
+      fullTransportMessage: fullMsg
+    });
     if (this.connection) {
       const ok = this.connection.send(this.codec.toBuffer(fullMsg));
       if (ok)
         return fullMsg.id;
       log?.info(
-        `${this.from} -- failed to send ${fullMsg.id} (seq: ${fullMsg.seq}) to ${fullMsg.to}, connection (id: ${this.connection.debugId}) is probably dead`
+        `failed to send msg to ${fullMsg.to}, connection is probably dead`,
+        {
+          ...this.loggingMetadata,
+          fullTransportMessage: fullMsg
+        }
       );
     } else {
       log?.info(
-        `${this.from} -- failed to send ${fullMsg.id} (seq: ${fullMsg.seq}) to ${fullMsg.to}, connection not ready yet`
+        `failed to send msg to ${fullMsg.to}, connection not ready yet`,
+        { ...this.loggingMetadata, fullTransportMessage: fullMsg }
       );
     }
     return fullMsg.id;
   }
   sendHeartbeat() {
-    if (this.heartbeatMisses >= this.options.heartbeatsUntilDead) {
+    const misses = this.heartbeatMisses;
+    const missDuration = misses * this.options.heartbeatIntervalMs;
+    if (misses > this.options.heartbeatsUntilDead) {
       if (this.connection) {
         log?.info(
-          `${this.from} -- closing connection (id: ${this.connection.debugId}) to ${this.to} due to inactivity`
+          `closing connection to ${this.to} due to inactivity (missed ${misses} heartbeats which is ${missDuration}ms)`,
+          this.loggingMetadata
         );
         this.closeStaleConnection();
       }
@@ -166,26 +185,36 @@ var Session = class {
   }
   sendBufferedMessages() {
     if (!this.connection) {
-      const msg = `${this.from} -- tried sending buffered messages without a connection (if you hit this code path something is seriously wrong)`;
-      log?.error(msg);
+      const msg = `tried sending buffered messages without a connection (if you hit this code path something is seriously wrong)`;
+      log?.error(msg, this.loggingMetadata);
       throw new Error(msg);
     }
     log?.info(
-      `${this.from} -- resending ${this.sendBuffer.length} buffered messages`
+      `resending ${this.sendBuffer.length} buffered messages`,
+      this.loggingMetadata
     );
     for (const msg of this.sendBuffer) {
-      log?.debug(`${this.from} -- resending ${msg.id} (seq: ${msg.seq})`);
+      log?.debug(`resending msg`, {
+        ...this.loggingMetadata,
+        fullTransportMessage: msg
+      });
       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.id}) (if you hit this code path something is seriously wrong)`;
-        log?.error(msg2);
-        throw new Error(msg2);
+        const errMsg = `failed to send buffered message to ${this.to} (if you hit this code path something is seriously wrong)`;
+        log?.error(errMsg, {
+          ...this.loggingMetadata,
+          fullTransportMessage: msg
+        });
+        throw new Error(errMsg);
       }
     }
   }
   updateBookkeeping(ack, seq) {
     if (seq + 1 < this.ack) {
-      log?.error(`${this.from} -- received stale seq ${seq} + 1 < ${this.ack}`);
+      log?.error(
+        `received stale seq ${seq} + 1 < ${this.ack}`,
+        this.loggingMetadata
+      );
       return;
     }
     this.sendBuffer = this.sendBuffer.filter((unacked) => unacked.seq >= ack);
@@ -195,7 +224,8 @@ var Session = class {
     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.id}) to ${this.to}`
+      `closing old inner connection from session to ${this.to}`,
+      this.loggingMetadata
     );
     this.connection.close();
     this.connection = void 0;
@@ -207,7 +237,8 @@ var Session = class {
   }
   beginGrace(cb) {
     log?.info(
-      `${this.from} -- starting ${this.options.sessionDisconnectGraceMs}ms grace period until session (id: ${this.id}) to ${this.to} is closed`
+      `starting ${this.options.sessionDisconnectGraceMs}ms grace period until session to ${this.to} is closed`,
+      this.loggingMetadata
     );
     this.disconnectionGrace = setTimeout(() => {
       this.close();
@@ -405,7 +436,8 @@ var Transport = class {
     let oldSession = this.sessions.get(connectedTo);
     if (oldSession?.advertisedSessionId && oldSession.advertisedSessionId !== advertisedSessionId) {
       log?.warn(
-        `${this.clientId} -- connection from ${connectedTo} is a different session (id: ${advertisedSessionId}, last connected to: ${oldSession.advertisedSessionId}), starting a new session`
+        `connection from ${connectedTo} is a different session (id: ${advertisedSessionId}, last connected to: ${oldSession.advertisedSessionId}), killing old session and starting a new one`,
+        oldSession.loggingMetadata
       );
       this.deleteSession(oldSession);
       oldSession = void 0;
@@ -414,16 +446,18 @@ var Transport = class {
       const newSession = this.createSession(connectedTo, conn);
       newSession.advertisedSessionId = advertisedSessionId;
       log?.info(
-        `${this.clientId} -- new connection (id: ${conn.debugId}) for new session (id: ${newSession.id}) to ${connectedTo}`
+        `new connection for new session to ${connectedTo}`,
+        newSession.loggingMetadata
       );
       return newSession;
     }
-    log?.info(
-      `${this.clientId} -- new connection (id: ${conn.debugId}) for existing session (id: ${oldSession.id}) to ${connectedTo}`
-    );
     oldSession.replaceWithNewConnection(conn);
     oldSession.sendBufferedMessages();
     oldSession.advertisedSessionId = advertisedSessionId;
+    log?.info(
+      `new connection for existing session to ${connectedTo}`,
+      oldSession.loggingMetadata
+    );
     return oldSession;
   }
   createSession(to, conn) {
@@ -445,7 +479,8 @@ var Transport = class {
     if (!session) {
       session = this.createSession(to, conn);
       log?.info(
-        `${this.clientId} -- no session for ${to}, created a new one (id: ${session.id})`
+        `no session for ${to}, created a new one`,
+        session.loggingMetadata
       );
     }
     return session;
@@ -454,7 +489,8 @@ var Transport = class {
     session.close();
     this.sessions.delete(session.to);
     log?.info(
-      `${this.clientId} -- session ${session.id} disconnect from ${session.to}`
+      `session ${session.id} disconnect from ${session.to}`,
+      session.loggingMetadata
     );
     this.eventDispatcher.dispatchEvent("sessionStatus", {
       status: "disconnect",
@@ -483,17 +519,15 @@ var Transport = class {
     const parsedMsg = this.codec.fromBuffer(msg);
     if (parsedMsg === null) {
       const decodedBuffer = new TextDecoder().decode(Buffer.from(msg));
-      log?.error(
-        `${this.clientId} -- received malformed msg, killing conn: ${decodedBuffer}`
-      );
+      log?.error(`received malformed msg, killing conn: ${decodedBuffer}`, {
+        clientId: this.clientId
+      });
       return null;
     }
     if (!Value.Check(OpaqueTransportMessageSchema, parsedMsg)) {
-      log?.error(
-        `${this.clientId} -- received invalid msg: ${JSON.stringify(
-          parsedMsg
-        )}`
-      );
+      log?.error(`received invalid msg: ${JSON.stringify(parsedMsg)}`, {
+        clientId: this.clientId
+      });
       return null;
     }
     return parsedMsg;
@@ -508,26 +542,29 @@ var Transport = class {
       return;
     const session = this.sessions.get(msg.from);
     if (!session) {
-      const err = `${this.clientId} -- (invariant violation) no existing session for ${msg.from}`;
-      log?.error(err);
+      log?.error(`(invariant violation) no existing session for ${msg.from}`, {
+        clientId: this.clientId,
+        fullTransportMessage: msg
+      });
       return;
     }
     session.cancelGrace();
-    log?.debug(`${this.clientId} -- received msg: ${JSON.stringify(msg)}`);
+    log?.debug(`received msg`, {
+      clientId: this.clientId,
+      fullTransportMessage: msg
+    });
     if (msg.seq !== session.nextExpectedSeq) {
       if (msg.seq < session.nextExpectedSeq) {
         log?.debug(
-          `${this.clientId} -- received duplicate msg (got: ${msg.seq}, wanted: ${session.nextExpectedSeq}), discarding: ${JSON.stringify(
-            msg
-          )}`
+          `received duplicate msg (got seq: ${msg.seq}, wanted seq: ${session.nextExpectedSeq}), discarding`,
+          { clientId: this.clientId, fullTransportMessage: msg }
         );
       } else {
         const errMsg = `received out-of-order msg (got seq: ${msg.seq}, wanted seq: ${session.nextExpectedSeq})`;
-        log?.error(
-          `${this.clientId} -- fatal: ${errMsg}, marking connection as dead: ${JSON.stringify(
-            msg
-          )}`
-        );
+        log?.error(`${errMsg}, marking connection as dead`, {
+          clientId: this.clientId,
+          fullTransportMessage: msg
+        });
         this.protocolError(ProtocolError.MessageOrderingViolated, errMsg);
         session.close();
       }
@@ -537,7 +574,10 @@ var Transport = class {
     if (!isAck(msg.controlFlags)) {
       this.eventDispatcher.dispatchEvent("message", msg);
     } else {
-      log?.debug(`${this.clientId} -- discarding msg ${msg.id} (ack bit set)`);
+      log?.debug(`discarding msg (ack bit set)`, {
+        clientId: this.clientId,
+        fullTransportMessage: msg
+      });
     }
   }
   /**
@@ -565,15 +605,17 @@ var Transport = class {
   send(to, msg) {
     if (this.state === "destroyed") {
       const err = "transport is destroyed, cant send";
-      log?.error(`${this.clientId} -- ` + err + `: ${JSON.stringify(msg)}`);
+      log?.error(err, {
+        clientId: this.clientId,
+        partialTransportMessage: msg
+      });
       this.protocolError(ProtocolError.UseAfterDestroy, err);
       return void 0;
     } else if (this.state === "closed") {
-      log?.info(
-        `${this.clientId} -- transport closed when sending, discarding : ${JSON.stringify(
-          msg
-        )}`
-      );
+      log?.info(`transport closed when sending, discarding`, {
+        clientId: this.clientId,
+        partialTransportMessage: msg
+      });
       return void 0;
     }
     return this.getOrCreateSession(to).send(msg);
@@ -601,7 +643,7 @@ var Transport = class {
     for (const session of this.sessions.values()) {
       this.deleteSession(session);
     }
-    log?.info(`${this.clientId} -- manually closed transport`);
+    log?.info(`manually closed transport`, { clientId: this.clientId });
   }
   /**
    * Default destroy implementation for transports. You should override this in the downstream
@@ -613,7 +655,7 @@ var Transport = class {
     for (const session of this.sessions.values()) {
       this.deleteSession(session);
     }
-    log?.info(`${this.clientId} -- manually destroyed transport`);
+    log?.info(`manually destroyed transport`, { clientId: this.clientId });
   }
 };
 var ClientTransport = class extends Transport {
@@ -669,18 +711,22 @@ var ClientTransport = class extends Transport {
       if (session) {
         this.onDisconnect(conn, session);
       }
-      log?.info(
-        `${this.clientId} -- connection (id: ${conn.debugId}) to ${to} disconnected`
-      );
+      log?.info(`connection to ${to} disconnected`, {
+        ...session?.loggingMetadata,
+        clientId: this.clientId,
+        connectedTo: to
+      });
       this.inflightConnectionPromises.delete(to);
       if (this.reconnectOnConnectionDrop) {
         void this.connect(to);
       }
     });
     conn.addErrorListener((err) => {
-      log?.warn(
-        `${this.clientId} -- error in connection (id: ${conn.debugId}) to ${to}: ${coerceErrorString(err)}`
-      );
+      log?.warn(`error in connection to ${to}: ${coerceErrorString(err)}`, {
+        ...session?.loggingMetadata,
+        clientId: this.clientId,
+        connectedTo: to
+      });
     });
   }
   receiveHandshakeResponseMessage(data, conn) {
@@ -693,11 +739,11 @@ var ClientTransport = class extends Transport {
       return false;
     }
     if (!Value.Check(ControlMessageHandshakeResponseSchema, parsed.payload)) {
-      log?.warn(
-        `${this.clientId} -- received invalid handshake resp: ${JSON.stringify(
-          parsed
-        )}`
-      );
+      log?.warn(`received invalid handshake resp`, {
+        clientId: this.clientId,
+        connectedTo: parsed.from,
+        fullTransportMessage: parsed
+      });
       this.protocolError(
         ProtocolError.HandshakeFailed,
         "invalid handshake resp"
@@ -705,18 +751,22 @@ var ClientTransport = class extends Transport {
       return false;
     }
     if (!parsed.payload.status.ok) {
-      log?.warn(
-        `${this.clientId} -- received failed handshake resp: ${JSON.stringify(
-          parsed
-        )}`
-      );
+      log?.warn(`received invalid handshake resp`, {
+        clientId: this.clientId,
+        connectedTo: parsed.from,
+        fullTransportMessage: parsed
+      });
       this.protocolError(
         ProtocolError.HandshakeFailed,
         parsed.payload.status.reason
       );
       return false;
     }
-    log?.debug(`${this.clientId} -- handshake from ${parsed.from} ok`);
+    log?.debug(`handshake from ${parsed.from} ok`, {
+      clientId: this.clientId,
+      connectedTo: parsed.from,
+      fullTransportMessage: parsed
+    });
     const session = this.onConnect(
       conn,
       parsed.from,
@@ -733,7 +783,8 @@ var ClientTransport = class extends Transport {
     const canProceedWithConnection = () => this.state === "open";
     if (!canProceedWithConnection()) {
       log?.info(
-        `${this.clientId} -- transport state is no longer open, cancelling attempt to connect to ${to}`
+        `transport state is no longer open, cancelling attempt to connect to ${to}`,
+        { clientId: this.clientId, connectedTo: to }
       );
       return;
     }
@@ -742,7 +793,7 @@ var ClientTransport = class extends Transport {
       const budgetConsumed = this.retryBudget.getBudgetConsumed(to);
       if (!this.retryBudget.hasBudget(to)) {
         const errMsg = `tried to connect to ${to} but retry budget exceeded (more than ${budgetConsumed} attempts in the last ${this.retryBudget.totalBudgetRestoreTime}ms)`;
-        log?.warn(`${this.clientId} -- ${errMsg}`);
+        log?.warn(errMsg, { clientId: this.clientId, connectedTo: to });
         this.protocolError(ProtocolError.RetriesExceeded, errMsg);
         return;
       }
@@ -751,9 +802,10 @@ var ClientTransport = class extends Transport {
       if (backoffMs > 0) {
         sleep = new Promise((resolve) => setTimeout(resolve, backoffMs));
       }
-      log?.info(
-        `${this.clientId} -- attempting connection to ${to} (${backoffMs}ms backoff)`
-      );
+      log?.info(`attempting connection to ${to} (${backoffMs}ms backoff)`, {
+        clientId: this.clientId,
+        connectedTo: to
+      });
       this.retryBudget.consumeBudget(to);
       reconnectPromise = sleep.then(() => {
         if (!canProceedWithConnection()) {
@@ -762,7 +814,12 @@ var ClientTransport = class extends Transport {
       }).then(() => this.createNewOutgoingConnection(to)).then((conn) => {
         if (!canProceedWithConnection()) {
           log?.info(
-            `${this.clientId} -- transport state is no longer open, closing pre-handshake connection (id: ${conn.debugId}) to ${to}`
+            `transport state is no longer open, closing pre-handshake connection to ${to}`,
+            {
+              clientId: this.clientId,
+              connectedTo: to,
+              connId: conn.debugId
+            }
           );
           conn.close();
           throw new Error("transport state is no longer open");
@@ -772,9 +829,10 @@ var ClientTransport = class extends Transport {
       });
       this.inflightConnectionPromises.set(to, reconnectPromise);
     } else {
-      log?.info(
-        `${this.clientId} -- attempting connection to ${to} (reusing previous attempt)`
-      );
+      log?.info(`attempting connection to ${to} (reusing previous attempt)`, {
+        clientId: this.clientId,
+        connectedTo: to
+      });
     }
     try {
       await reconnectPromise;
@@ -782,11 +840,15 @@ var ClientTransport = class extends Transport {
       this.inflightConnectionPromises.delete(to);
       const errStr = coerceErrorString(error);
       if (!this.reconnectOnConnectionDrop || !canProceedWithConnection()) {
-        log?.warn(`${this.clientId} -- connection to ${to} failed (${errStr})`);
+        log?.warn(`connection to ${to} failed (${errStr})`, {
+          clientId: this.clientId,
+          connectedTo: to
+        });
       } else {
-        log?.warn(
-          `${this.clientId} -- connection to ${to} failed (${errStr}), retrying`
-        );
+        log?.warn(`connection to ${to} failed (${errStr}), retrying`, {
+          clientId: this.clientId,
+          connectedTo: to
+        });
         return this.connect(to);
       }
     }
@@ -798,7 +860,10 @@ var ClientTransport = class extends Transport {
   sendHandshake(to, conn) {
     const session = this.getOrCreateSession(to, conn);
     const requestMsg = handshakeRequestMessage(this.clientId, to, session.id);
-    log?.debug(`${this.clientId} -- sending handshake request to ${to}`);
+    log?.debug(`sending handshake request to ${to}`, {
+      clientId: this.clientId,
+      connectedTo: to
+    });
     conn.send(this.codec.toBuffer(requestMsg));
   }
   close() {
@@ -809,16 +874,18 @@ var ClientTransport = class extends Transport {
 var ServerTransport = class extends Transport {
   constructor(clientId, providedOptions) {
     super(clientId, providedOptions);
-    log?.info(
-      `${this.clientId} -- initiated server transport (protocol: ${PROTOCOL_VERSION})`
-    );
+    log?.info(`initiated server transport`, {
+      clientId: this.clientId,
+      protocolVersion: PROTOCOL_VERSION
+    });
   }
   handleConnection(conn) {
     if (this.state !== "open")
       return;
-    log?.info(
-      `${this.clientId} -- new incoming connection (id: ${conn.debugId})`
-    );
+    log?.info(`new incoming connection`, {
+      clientId: this.clientId,
+      connId: conn.debugId
+    });
     let session = void 0;
     const client = () => session?.to ?? "unknown";
     const handshakeHandler = (data) => {
@@ -843,16 +910,18 @@ var ServerTransport = class extends Transport {
     conn.addCloseListener(() => {
       if (!session)
         return;
-      log?.info(
-        `${this.clientId} -- connection (id: ${conn.debugId}) to ${client()} disconnected`
-      );
+      log?.info(`connection to ${client()} disconnected`, {
+        clientId: this.clientId,
+        connId: conn.debugId
+      });
       this.onDisconnect(conn, session);
     });
     conn.addErrorListener((err) => {
       if (!session)
         return;
       log?.warn(
-        `${this.clientId} -- connection (id: ${conn.debugId}) to ${client()} got an error: ${coerceErrorString(err)}`
+        `connection to ${client()} got an error: ${coerceErrorString(err)}`,
+        { clientId: this.clientId, connId: conn.debugId }
       );
     });
   }
@@ -872,7 +941,10 @@ var ServerTransport = class extends Transport {
         reason
       });
       conn.send(this.codec.toBuffer(responseMsg2));
-      log?.warn(`${this.clientId} -- ${reason}: ${JSON.stringify(parsed)}`);
+      log?.warn(`${reason}: ${JSON.stringify(parsed)}`, {
+        clientId: this.clientId,
+        connId: conn.debugId
+      });
       this.protocolError(
         ProtocolError.HandshakeFailed,
         "invalid handshake request"
@@ -888,14 +960,16 @@ var ServerTransport = class extends Transport {
       });
       conn.send(this.codec.toBuffer(responseMsg2));
       log?.warn(
-        `${this.clientId} -- received handshake msg with incompatible protocol version (got: ${gotVersion}, expected: ${PROTOCOL_VERSION})`
+        `received handshake msg with incompatible protocol version (got: ${gotVersion}, expected: ${PROTOCOL_VERSION})`,
+        { clientId: this.clientId, connId: conn.debugId }
       );
       this.protocolError(ProtocolError.HandshakeFailed, reason);
       return false;
     }
     const session = this.getOrCreateSession(parsed.from, conn);
     log?.debug(
-      `${this.clientId} -- handshake from ${parsed.from} ok, responding with handshake success`
+      `handshake from ${parsed.from} ok, responding with handshake success`,
+      { clientId: this.clientId, connId: conn.debugId }
     );
     const responseMsg = handshakeResponseMessage(this.clientId, parsed.from, {
       ok: true,