@replit/river 0.11.0 → 0.12.1

package/dist/chunk-QEYN2Z6O.js

@@ -0,0 +1,726 @@
+import {
+  NaiveJsonCodec
+} from "./chunk-GZ7HCLLM.js";
+import {
+  ControlMessageHandshakeRequestSchema,
+  ControlMessageHandshakeResponseSchema,
+  OpaqueTransportMessageSchema,
+  PROTOCOL_VERSION,
+  bootRequestMessage,
+  bootResponseMessage,
+  coerceErrorString,
+  isAck
+} from "./chunk-XFFS4UOD.js";
+import {
+  log
+} from "./chunk-H4BYJELI.js";
+
+// transport/events.ts
+var EventDispatcher = class {
+  eventListeners = {};
+  numberOfListeners(eventType) {
+    return this.eventListeners[eventType]?.size ?? 0;
+  }
+  addEventListener(eventType, handler) {
+    if (!this.eventListeners[eventType]) {
+      this.eventListeners[eventType] = /* @__PURE__ */ new Set();
+    }
+    this.eventListeners[eventType]?.add(handler);
+  }
+  removeEventListener(eventType, handler) {
+    const handlers = this.eventListeners[eventType];
+    if (handlers) {
+      this.eventListeners[eventType]?.delete(handler);
+    }
+  }
+  dispatchEvent(eventType, event) {
+    const handlers = this.eventListeners[eventType];
+    if (handlers) {
+      for (const handler of handlers) {
+        handler(event);
+      }
+    }
+  }
+};
+
+// transport/session.ts
+import { customAlphabet } from "nanoid";
+var nanoid = customAlphabet("1234567890abcdefghijklmnopqrstuvxyz", 6);
+var unsafeId = () => nanoid();
+var Connection = class {
+  debugId;
+  constructor() {
+    this.debugId = `conn-${unsafeId()}`;
+  }
+};
+var HEARTBEAT_INTERVAL_MS = 1e3;
+var HEARTBEATS_TILL_DEAD = 2;
+var SESSION_DISCONNECT_GRACE_MS = 5e3;
+var Session = class {
+  codec;
+  /**
+   * The buffer of messages that have been sent but not yet acknowledged.
+   */
+  sendBuffer = [];
+  /**
+   * The active connection associated with this session
+   */
+  connection;
+  from;
+  to;
+  /**
+   * The unique ID of this session.
+   */
+  debugId;
+  /**
+   * Number of messages we've sent along this session (excluding handshake)
+   */
+  seq = 0;
+  /**
+   * Number of unique messages we've received this session (excluding handshake)
+   */
+  ack = 0;
+  /**
+   * The grace period between when the inner connection is disconnected
+   * and when we should consider the entire session disconnected.
+   */
+  disconnectionGrace;
+  /**
+   * Number of heartbeats we've sent without a response.
+   */
+  heartbeatMisses;
+  /**
+   * The interval for sending heartbeats.
+   */
+  heartbeat;
+  constructor(codec, from, connectedTo, conn) {
+    this.debugId = `sess-${unsafeId()}`;
+    this.from = from;
+    this.to = connectedTo;
+    this.connection = conn;
+    this.codec = codec;
+    this.heartbeatMisses = 0;
+    this.heartbeat = setInterval(
+      () => this.sendHeartbeat(),
+      HEARTBEAT_INTERVAL_MS
+    );
+  }
+  /**
+   * 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.
+   *
+   * @param msg The partial message to be sent, which will be constructed into a full message.
+   * @param skipRetry Optional. If true, the message will not be buffered for retry on failure. This should only be used for
+   * ack hearbeats, which contain information that can already be found in the other buffered messages.
+   * @returns The full transport ID of the message that was attempted to be sent.
+   */
+  send(msg, skipRetry) {
+    const fullMsg = this.constructMsg(msg);
+    log?.debug(`${this.from} -- sending ${JSON.stringify(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} to ${fullMsg.to}, connection (id: ${this.connection.debugId}) is probably dead`
+      );
+    } else {
+      log?.info(
+        `${this.from} -- failed to send ${fullMsg.id} to ${fullMsg.to}, connection not ready yet`
+      );
+    }
+    if (skipRetry)
+      return fullMsg.id;
+    this.addToSendBuff(fullMsg);
+    log?.info(
+      `${this.from} -- buffering msg ${fullMsg.id} until connection is healthy again`
+    );
+    return fullMsg.id;
+  }
+  sendHeartbeat() {
+    if (this.heartbeatMisses >= HEARTBEATS_TILL_DEAD) {
+      if (this.connection) {
+        log?.info(
+          `${this.from} -- closing connection (id: ${this.connection.debugId}) to ${this.to} due to inactivity`
+        );
+        this.halfCloseConnection();
+      }
+      return;
+    }
+    this.send(
+      {
+        streamId: "heartbeat",
+        controlFlags: 1 /* AckBit */,
+        payload: {
+          type: "ACK"
+        }
+      },
+      true
+    );
+    this.heartbeatMisses++;
+  }
+  resetBufferedMessages() {
+    this.sendBuffer = [];
+    this.seq = 0;
+    this.ack = 0;
+  }
+  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);
+      throw new Error(msg);
+    }
+    for (const msg of this.sendBuffer) {
+      log?.debug(`${this.from} -- resending ${JSON.stringify(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.debugId}) (if you hit this code path something is seriously wrong)`;
+        log?.error(msg2);
+        throw new Error(msg2);
+      }
+    }
+  }
+  updateBookkeeping(ack, seq) {
+    this.sendBuffer = this.sendBuffer.filter((unacked) => unacked.seq > ack);
+    this.ack = seq + 1;
+  }
+  addToSendBuff(msg) {
+    this.sendBuffer.push(msg);
+    log?.debug(
+      `${this.from} -- send buff to ${this.to} now tracking ${this.sendBuffer.length} messages`
+    );
+  }
+  closeStaleConnection(conn) {
+    if (!this.connection || 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.connection.close();
+    this.connection = void 0;
+  }
+  replaceWithNewConnection(newConn) {
+    this.closeStaleConnection(this.connection);
+    this.cancelGrace();
+    this.connection = newConn;
+  }
+  beginGrace(cb) {
+    this.disconnectionGrace = setTimeout(() => {
+      this.resetBufferedMessages();
+      clearInterval(this.heartbeat);
+      cb();
+    }, SESSION_DISCONNECT_GRACE_MS);
+  }
+  cancelGrace() {
+    this.heartbeatMisses = 0;
+    clearTimeout(this.disconnectionGrace);
+  }
+  get connected() {
+    return this.connection !== void 0;
+  }
+  get nextExpectedSeq() {
+    return this.ack;
+  }
+  constructMsg(partialMsg) {
+    const msg = {
+      ...partialMsg,
+      id: unsafeId(),
+      to: this.to,
+      from: this.from,
+      seq: this.seq,
+      ack: this.ack
+    };
+    this.seq++;
+    return msg;
+  }
+  /**
+   * Closes the out-going connection but doesn't remove the listeners
+   * for incoming messages. The connection will eventually call onClose
+   * when it is ready to be cleaned up and only then will {@link connection} be set back
+   * to undefined
+   */
+  halfCloseConnection() {
+    this.connection?.close();
+  }
+  inspectSendBuffer() {
+    return this.sendBuffer;
+  }
+};
+
+// transport/transport.ts
+import { Value } from "@sinclair/typebox/value";
+import { nanoid as nanoid2 } from "nanoid";
+var DEFAULT_RECONNECT_JITTER_MAX_MS = 500;
+var DEFAULT_RECONNECT_INTERVAL_MS = 250;
+var defaultTransportOptions = {
+  retryIntervalMs: DEFAULT_RECONNECT_INTERVAL_MS,
+  retryJitterMs: DEFAULT_RECONNECT_JITTER_MAX_MS,
+  retryAttemptsMax: 5,
+  codec: NaiveJsonCodec
+};
+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.
+   */
+  state;
+  /**
+   * The {@link Codec} used to encode and decode messages.
+   */
+  codec;
+  /**
+   * The client ID of this transport.
+   */
+  clientId;
+  /**
+   * The map of {@link Session}s managed by this transport.
+   */
+  sessions;
+  /**
+   * The map of {@link Connection}s managed by this transport.
+   */
+  get connections() {
+    return new Map(
+      [...this.sessions].map(([client, session]) => [client, session.connection]).filter((entry) => entry[1] !== void 0)
+    );
+  }
+  /**
+   * The event dispatcher for handling events of type EventTypes.
+   */
+  eventDispatcher;
+  /**
+   * The options for this transport.
+   */
+  options;
+  /**
+   * Creates a new Transport instance.
+   * This should also set up {@link onConnect}, and {@link onDisconnect} listeners.
+   * @param codec The codec used to encode and decode messages.
+   * @param clientId The client ID of this transport.
+   */
+  constructor(clientId, providedOptions) {
+    this.options = { ...defaultTransportOptions, ...providedOptions };
+    this.eventDispatcher = new EventDispatcher();
+    this.sessions = /* @__PURE__ */ new Map();
+    this.codec = this.options.codec;
+    this.clientId = clientId;
+    this.state = "open";
+  }
+  sessionByClientId(clientId) {
+    const session = this.sessions.get(clientId);
+    if (!session) {
+      const err = `${this.clientId} -- (invariant violation) no existing session for ${clientId}`;
+      log?.error(err);
+      throw new Error(err);
+    }
+    return session;
+  }
+  /**
+   * Called when a new connection is established
+   * and we know the identity of the connected client.
+   * @param conn The connection object.
+   */
+  onConnect(conn, connectedTo, instanceId) {
+    this.eventDispatcher.dispatchEvent("connectionStatus", {
+      status: "connect",
+      conn
+    });
+    let session = this.sessions.get(connectedTo);
+    const lastInstanceId = this.connectedInstanceIds.get(connectedTo);
+    if (session && lastInstanceId !== instanceId && lastInstanceId !== void 0) {
+      log?.debug(
+        `${this.clientId} -- handshake from ${connectedTo} has different server instance (got: ${instanceId}, last connected to: ${lastInstanceId}), starting a new session`
+      );
+      session.resetBufferedMessages();
+      session.closeStaleConnection();
+      this.deleteSession(session);
+      session = void 0;
+    }
+    this.connectedInstanceIds.set(connectedTo, instanceId);
+    if (session === void 0) {
+      const newSession = this.createSession(connectedTo, conn);
+      log?.info(
+        `${this.clientId} -- new connection (id: ${conn.debugId}) for new session (id: ${newSession.debugId}) to ${connectedTo}`
+      );
+      return newSession;
+    }
+    log?.info(
+      `${this.clientId} -- new connection (id: ${conn.debugId}) for existing session (id: ${session.debugId}) to ${connectedTo}`
+    );
+    session.replaceWithNewConnection(conn);
+    session.sendBufferedMessages();
+    return session;
+  }
+  createSession(connectedTo, conn) {
+    const session = new Session(
+      this.codec,
+      this.clientId,
+      connectedTo,
+      conn
+    );
+    this.sessions.set(session.to, session);
+    this.eventDispatcher.dispatchEvent("sessionStatus", {
+      status: "connect",
+      session
+    });
+    return session;
+  }
+  deleteSession(session) {
+    this.sessions.delete(session.to);
+    this.eventDispatcher.dispatchEvent("sessionStatus", {
+      status: "disconnect",
+      session
+    });
+    log?.info(
+      `${this.clientId} -- session ${session.debugId} disconnect from ${session.to}`
+    );
+  }
+  /**
+   * The downstream implementation needs to call this when a connection is closed.
+   * @param conn The connection object.
+   */
+  onDisconnect(conn, connectedTo) {
+    this.eventDispatcher.dispatchEvent("connectionStatus", {
+      status: "disconnect",
+      conn
+    });
+    if (!connectedTo)
+      return;
+    const session = this.sessionByClientId(connectedTo);
+    log?.info(
+      `${this.clientId} -- connection (id: ${conn.debugId}) disconnect from ${connectedTo}, ${SESSION_DISCONNECT_GRACE_MS}ms until session (id: ${session.debugId}) disconnect`
+    );
+    session.closeStaleConnection(conn);
+    session.beginGrace(() => this.deleteSession(session));
+  }
+  /**
+   * Parses a message from a Uint8Array into a {@link OpaqueTransportMessage}.
+   * @param msg The message to parse.
+   * @returns The parsed message, or null if the message is malformed or invalid.
+   */
+  parseMsg(msg) {
+    const parsedMsg = this.codec.fromBuffer(msg);
+    if (parsedMsg === null) {
+      const decodedBuffer = new TextDecoder().decode(msg);
+      log?.error(
+        `${this.clientId} -- received malformed msg, killing conn: ${decodedBuffer}`
+      );
+      return null;
+    }
+    if (!Value.Check(OpaqueTransportMessageSchema, parsedMsg)) {
+      log?.error(
+        `${this.clientId} -- received invalid msg: ${JSON.stringify(
+          parsedMsg
+        )}`
+      );
+      return null;
+    }
+    return {
+      ...parsedMsg,
+      serviceName: parsedMsg.serviceName === null ? void 0 : parsedMsg.serviceName,
+      procedureName: parsedMsg.procedureName === null ? void 0 : parsedMsg.procedureName
+    };
+  }
+  /**
+   * Called when a message is received by this transport.
+   * You generally shouldn't need to override this in downstream transport implementations.
+   * @param msg The received message.
+   */
+  handleMsg(msg) {
+    const session = this.sessionByClientId(msg.from);
+    session.cancelGrace();
+    log?.debug(`${this.clientId} -- received msg: ${JSON.stringify(msg)}`);
+    if (msg.seq !== session.nextExpectedSeq) {
+      log?.warn(
+        `${this.clientId} -- received out-of-order msg (got: ${msg.seq}, wanted: ${session.nextExpectedSeq}), discarding: ${JSON.stringify(
+          msg
+        )}`
+      );
+      return;
+    }
+    if (!isAck(msg.controlFlags)) {
+      this.eventDispatcher.dispatchEvent("message", msg);
+    }
+    session.updateBookkeeping(msg.ack, msg.seq);
+  }
+  /**
+   * Adds a listener to this transport.
+   * @param the type of event to listen for
+   * @param handler The message handler to add.
+   */
+  addEventListener(type, handler) {
+    this.eventDispatcher.addEventListener(type, handler);
+  }
+  /**
+   * Removes a listener from this transport.
+   * @param the type of event to unlisten on
+   * @param handler The message handler to remove.
+   */
+  removeEventListener(type, handler) {
+    this.eventDispatcher.removeEventListener(type, handler);
+  }
+  /**
+   * Sends a message over this transport, delegating to the appropriate connection to actually
+   * send the message.
+   * @param msg The message to send.
+   * @returns The ID of the sent message or undefined if it wasn't sent
+   */
+  send(to, msg) {
+    if (this.state === "destroyed") {
+      const err = "transport is destroyed, cant send";
+      log?.error(`${this.clientId} -- ` + err + `: ${JSON.stringify(msg)}`);
+      throw new Error(err);
+    } else if (this.state === "closed") {
+      log?.info(
+        `${this.clientId} -- transport closed when sending, discarding : ${JSON.stringify(
+          msg
+        )}`
+      );
+      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);
+  }
+  // control helpers
+  sendCloseStream(to, streamId) {
+    return this.send(to, {
+      streamId,
+      controlFlags: 4 /* StreamClosedBit */,
+      payload: {
+        type: "CLOSE"
+      }
+    });
+  }
+  /**
+   * Default close implementation for transports. You should override this in the downstream
+   * implementation if you need to do any additional cleanup and call super.close() at the end.
+   * Closes the transport. Any messages sent while the transport is closed will be silently discarded.
+   */
+  close() {
+    for (const session of this.sessions.values()) {
+      session.halfCloseConnection();
+    }
+    this.state = "closed";
+    log?.info(`${this.clientId} -- manually closed transport`);
+  }
+  /**
+   * Default destroy implementation for transports. You should override this in the downstream
+   * implementation if you need to do any additional cleanup and call super.destroy() at the end.
+   * Destroys the transport. Any messages sent while the transport is destroyed will throw an error.
+   */
+  destroy() {
+    for (const session of this.sessions.values()) {
+      session.closeStaleConnection(session.connection);
+    }
+    this.state = "destroyed";
+    log?.info(`${this.clientId} -- manually destroyed transport`);
+  }
+};
+var ClientTransport = class extends Transport {
+  /**
+   * The map of reconnect promises for each client ID.
+   */
+  inflightConnectionPromises;
+  tryReconnecting = true;
+  constructor(clientId, providedOptions) {
+    super(clientId, providedOptions);
+    this.inflightConnectionPromises = /* @__PURE__ */ new Map();
+  }
+  handleConnection(conn, to) {
+    const bootHandler = this.receiveWithBootSequence(conn, () => {
+      conn.removeDataListener(bootHandler);
+      conn.addDataListener((data) => {
+        const parsed = this.parseMsg(data);
+        if (!parsed) {
+          conn.close();
+          return;
+        }
+        this.handleMsg(parsed);
+      });
+    });
+    conn.addDataListener(bootHandler);
+    conn.addCloseListener(() => {
+      this.onDisconnect(conn, to);
+      void this.connect(to);
+    });
+    conn.addErrorListener((err) => {
+      log?.warn(
+        `${this.clientId} -- error in connection (id: ${conn.debugId}) to ${to}: ${coerceErrorString(err)}`
+      );
+    });
+  }
+  /**
+   * Manually attempts to connect to a client.
+   * @param to The client ID of the node to connect to.
+   */
+  async connect(to, attempt = 0) {
+    if (this.state !== "open" || !this.tryReconnecting) {
+      log?.info(
+        `${this.clientId} -- transport state is no longer open, not attempting connection`
+      );
+      return;
+    }
+    let reconnectPromise = this.inflightConnectionPromises.get(to);
+    if (!reconnectPromise) {
+      reconnectPromise = this.createNewOutgoingConnection(to);
+      this.inflightConnectionPromises.set(to, reconnectPromise);
+    }
+    try {
+      const conn = await reconnectPromise;
+      this.state = "open";
+      const requestMsg = bootRequestMessage(this.clientId, to, this.instanceId);
+      log?.debug(`${this.clientId} -- sending boot handshake to ${to}`);
+      conn.send(this.codec.toBuffer(requestMsg));
+    } catch (error) {
+      const errStr = coerceErrorString(error);
+      this.inflightConnectionPromises.delete(to);
+      if (attempt >= this.options.retryAttemptsMax) {
+        const errMsg = `connection to ${to} failed after ${attempt} attempts (${errStr}), giving up`;
+        log?.error(`${this.clientId} -- ${errMsg}`);
+        throw new Error(errMsg);
+      } else {
+        const jitter = Math.floor(Math.random() * this.options.retryJitterMs);
+        const backoffMs = this.options.retryIntervalMs * 2 ** attempt + jitter;
+        log?.warn(
+          `${this.clientId} -- connection to ${to} failed (${errStr}), trying again in ${backoffMs}ms`
+        );
+        setTimeout(() => void this.connect(to, attempt + 1), backoffMs);
+      }
+    }
+  }
+  receiveWithBootSequence(conn, sessionCb) {
+    const bootHandler = (data) => {
+      const parsed = this.parseMsg(data);
+      if (!parsed) {
+        conn.close();
+        return;
+      }
+      if (!Value.Check(ControlMessageHandshakeResponseSchema, parsed.payload)) {
+        log?.warn(
+          `${this.clientId} -- received invalid handshake resp: ${JSON.stringify(parsed)}`
+        );
+        return;
+      }
+      if (!parsed.payload.status.ok) {
+        log?.warn(
+          `${this.clientId} -- received failed handshake resp: ${JSON.stringify(
+            parsed
+          )}`
+        );
+        return;
+      }
+      const serverInstanceId = parsed.payload.status.instanceId;
+      log?.debug(
+        `${this.clientId} -- handshake from ${parsed.from} ok (server instance: ${serverInstanceId})`
+      );
+      sessionCb(this.onConnect(conn, parsed.from, serverInstanceId));
+    };
+    return bootHandler;
+  }
+  onDisconnect(conn, connectedTo) {
+    if (connectedTo)
+      this.inflightConnectionPromises.delete(connectedTo);
+    super.onDisconnect(conn, connectedTo);
+  }
+};
+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})`
+    );
+  }
+  handleConnection(conn) {
+    let session = void 0;
+    const client = () => session?.to ?? "unknown";
+    const bootHandler = this.receiveWithBootSequence(
+      conn,
+      (establishedSession) => {
+        session = establishedSession;
+        conn.removeDataListener(bootHandler);
+        conn.addDataListener((data) => {
+          const parsed = this.parseMsg(data);
+          if (!parsed) {
+            conn.close();
+            return;
+          }
+          this.handleMsg(parsed);
+        });
+      }
+    );
+    conn.addDataListener(bootHandler);
+    conn.addCloseListener(() => {
+      if (!session)
+        return;
+      log?.info(
+        `${this.clientId} -- connection (id: ${conn.debugId}) to ${client()} disconnected`
+      );
+      this.onDisconnect(conn, session.to);
+    });
+    conn.addErrorListener((err) => {
+      if (!session)
+        return;
+      log?.warn(
+        `${this.clientId} -- connection (id: ${conn.debugId}) to ${client()} got an error: ${coerceErrorString(err)}`
+      );
+    });
+  }
+  receiveWithBootSequence(conn, sessionCb) {
+    const bootHandler = (data) => {
+      const parsed = this.parseMsg(data);
+      if (!parsed) {
+        conn.close();
+        return;
+      }
+      if (!Value.Check(ControlMessageHandshakeRequestSchema, parsed.payload)) {
+        const responseMsg2 = bootResponseMessage(
+          this.clientId,
+          this.instanceId,
+          parsed.from,
+          false
+        );
+        conn.send(this.codec.toBuffer(responseMsg2));
+        log?.warn(
+          `${this.clientId} -- received invalid handshake msg: ${JSON.stringify(
+            parsed
+          )}`
+        );
+        return;
+      }
+      const instanceId = parsed.payload.instanceId;
+      log?.debug(
+        `${this.clientId} -- handshake from ${parsed.from} ok (instance id: ${instanceId}), responding with handshake success`
+      );
+      const responseMsg = bootResponseMessage(
+        this.clientId,
+        this.instanceId,
+        parsed.from,
+        true
+      );
+      conn.send(this.codec.toBuffer(responseMsg));
+      sessionCb(this.onConnect(conn, parsed.from, instanceId));
+    };
+    return bootHandler;
+  }
+};
+
+export {
+  Connection,
+  Session,
+  Transport,
+  ClientTransport,
+  ServerTransport
+};