@replit/river 0.10.0 → 0.10.1

package/dist/transport/index.cjs

@@ -0,0 +1,362 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// transport/index.ts
+var transport_exports = {};
+__export(transport_exports, {
+  Connection: () => Connection,
+  OpaqueTransportMessageSchema: () => OpaqueTransportMessageSchema,
+  Transport: () => Transport,
+  TransportMessageSchema: () => TransportMessageSchema,
+  msg: () => msg,
+  reply: () => reply
+});
+module.exports = __toCommonJS(transport_exports);
+
+// transport/transport.ts
+var import_value = require("@sinclair/typebox/value");
+
+// transport/message.ts
+var import_typebox = require("@sinclair/typebox");
+var import_nanoid = require("nanoid");
+var TransportMessageSchema = (t) => import_typebox.Type.Object({
+  id: import_typebox.Type.String(),
+  from: import_typebox.Type.String(),
+  to: import_typebox.Type.String(),
+  serviceName: import_typebox.Type.Optional(import_typebox.Type.Union([import_typebox.Type.String(), import_typebox.Type.Null()])),
+  procedureName: import_typebox.Type.Optional(import_typebox.Type.Union([import_typebox.Type.String(), import_typebox.Type.Null()])),
+  streamId: import_typebox.Type.String(),
+  controlFlags: import_typebox.Type.Integer(),
+  payload: t
+});
+var TransportAckSchema = TransportMessageSchema(
+  import_typebox.Type.Object({
+    ack: import_typebox.Type.String()
+  })
+);
+var ControlMessagePayloadSchema = import_typebox.Type.Object({
+  type: import_typebox.Type.Literal("CLOSE")
+});
+var OpaqueTransportMessageSchema = TransportMessageSchema(
+  import_typebox.Type.Unknown()
+);
+function msg(from, to, streamId, payload, serviceName, procedureName) {
+  return {
+    id: (0, import_nanoid.nanoid)(),
+    to,
+    from,
+    serviceName,
+    procedureName,
+    streamId,
+    controlFlags: 0,
+    payload
+  };
+}
+function reply(msg2, response) {
+  return {
+    id: (0, import_nanoid.nanoid)(),
+    streamId: msg2.streamId,
+    controlFlags: 0,
+    to: msg2.from,
+    from: msg2.to,
+    payload: response
+  };
+}
+function isAck(controlFlag) {
+  return (controlFlag & 1 /* AckBit */) === 1 /* AckBit */;
+}
+
+// logging/index.ts
+var log;
+
+// 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/transport.ts
+var Connection = class {
+  connectedTo;
+  transport;
+  constructor(transport, connectedTo) {
+    this.connectedTo = connectedTo;
+    this.transport = transport;
+  }
+};
+var Transport = class {
+  /**
+   * 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;
+  /**
+   * An array of message IDs that are waiting to be sent over the WebSocket connection.
+   * This builds up if the WebSocket is down for a period of time.
+   */
+  sendQueue;
+  /**
+   * The buffer of messages that have been sent but not yet acknowledged.
+   */
+  sendBuffer;
+  /**
+   * The map of {@link Connection}s managed by this transport.
+   */
+  connections;
+  /**
+   * The event dispatcher for handling events of type EventTypes.
+   */
+  eventDispatcher;
+  /**
+   * Creates a new Transport instance.
+   * @param codec The codec used to encode and decode messages.
+   * @param clientId The client ID of this transport.
+   */
+  constructor(codec, clientId) {
+    this.eventDispatcher = new EventDispatcher();
+    this.sendBuffer = /* @__PURE__ */ new Map();
+    this.sendQueue = /* @__PURE__ */ new Map();
+    this.connections = /* @__PURE__ */ new Map();
+    this.codec = codec;
+    this.clientId = clientId;
+    this.state = "open";
+  }
+  /**
+   * The downstream implementation needs to call this when a new connection is established.
+   * @param conn The connection object.
+   */
+  onConnect(conn) {
+    log?.info(`${this.clientId} -- new connection to ${conn.connectedTo}`);
+    this.connections.set(conn.connectedTo, conn);
+    this.eventDispatcher.dispatchEvent("connectionStatus", {
+      status: "connect",
+      conn
+    });
+    const outstanding = this.sendQueue.get(conn.connectedTo);
+    if (!outstanding) {
+      return;
+    }
+    for (const id of outstanding) {
+      const msg2 = this.sendBuffer.get(id);
+      if (!msg2) {
+        log?.warn(
+          `${this.clientId} -- tried to resend a message we received an ack for`
+        );
+        continue;
+      }
+      this.send(msg2);
+    }
+    this.sendQueue.delete(conn.connectedTo);
+  }
+  /**
+   * The downstream implementation needs to call this when a connection is closed.
+   * @param conn The connection object.
+   */
+  onDisconnect(conn) {
+    log?.info(`${this.clientId} -- disconnect from ${conn.connectedTo}`);
+    conn.close();
+    this.connections.delete(conn.connectedTo);
+    this.eventDispatcher.dispatchEvent("connectionStatus", {
+      status: "disconnect",
+      conn
+    });
+  }
+  /**
+   * Handles a message received by this transport. Thin wrapper around {@link handleMsg} and {@link parseMsg}.
+   * @param msg The message to handle.
+   */
+  onMessage(msg2) {
+    return this.handleMsg(this.parseMsg(msg2));
+  }
+  /**
+   * 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(msg2) {
+    const parsedMsg = this.codec.fromBuffer(msg2);
+    if (parsedMsg === null) {
+      const decodedBuffer = new TextDecoder().decode(msg2);
+      log?.warn(`${this.clientId} -- received malformed msg: ${decodedBuffer}`);
+      return null;
+    }
+    if (import_value.Value.Check(OpaqueTransportMessageSchema, parsedMsg)) {
+      return {
+        ...parsedMsg,
+        serviceName: parsedMsg.serviceName === null ? void 0 : parsedMsg.serviceName,
+        procedureName: parsedMsg.procedureName === null ? void 0 : parsedMsg.procedureName
+      };
+    } else {
+      log?.warn(
+        `${this.clientId} -- received invalid msg: ${JSON.stringify(
+          parsedMsg
+        )}`
+      );
+      return null;
+    }
+  }
+  /**
+   * 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(msg2) {
+    if (!msg2) {
+      return;
+    }
+    if (isAck(msg2.controlFlags) && import_value.Value.Check(TransportAckSchema, msg2)) {
+      log?.info(`${this.clientId} -- received ack: ${JSON.stringify(msg2)}`);
+      if (this.sendBuffer.has(msg2.payload.ack)) {
+        this.sendBuffer.delete(msg2.payload.ack);
+      }
+    } 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 });
+        ackMsg.controlFlags = 1 /* AckBit */;
+        ackMsg.from = this.clientId;
+        this.send(ackMsg);
+      }
+    }
+  }
+  /**
+   * 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.
+   */
+  send(msg2) {
+    if (this.state === "destroyed") {
+      const err = "transport is destroyed, cant send";
+      log?.error(`${this.clientId} -- ` + err + `: ${JSON.stringify(msg2)}`);
+      throw new Error(err);
+    } else if (this.state === "closed") {
+      log?.info(
+        `${this.clientId} -- transport closed when sending, discarding : ${JSON.stringify(
+          msg2
+        )}`
+      );
+      return msg2.id;
+    }
+    let conn = this.connections.get(msg2.to);
+    if (!isAck(msg2.controlFlags)) {
+      this.sendBuffer.set(msg2.id, msg2);
+    }
+    if (conn) {
+      log?.info(`${this.clientId} -- sending ${JSON.stringify(msg2)}`);
+      const ok = conn.send(this.codec.toBuffer(msg2));
+      if (ok) {
+        return msg2.id;
+      }
+    }
+    log?.info(
+      `${this.clientId} -- connection to ${msg2.to} not ready, attempting reconnect and queuing ${JSON.stringify(msg2)}`
+    );
+    const outstanding = this.sendQueue.get(msg2.to) || [];
+    outstanding.push(msg2.id);
+    this.sendQueue.set(msg2.to, outstanding);
+    this.createNewConnection(msg2.to);
+    return msg2.id;
+  }
+  /**
+   * 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.
+   */
+  async close() {
+    for (const conn of this.connections.values()) {
+      conn.close();
+    }
+    this.connections.clear();
+    this.state = "closed";
+    log?.info(`${this.clientId} -- 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.
+   */
+  async destroy() {
+    for (const conn of this.connections.values()) {
+      conn.close();
+    }
+    this.connections.clear();
+    this.state = "destroyed";
+    log?.info(`${this.clientId} -- destroyed transport`);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Connection,
+  OpaqueTransportMessageSchema,
+  Transport,
+  TransportMessageSchema,
+  msg,
+  reply
+});

package/dist/transport/{transport.d.ts → index.d.cts}

@@ -1,6 +1,117 @@
-import { Codec } from '../codec/types';
-import { MessageId, OpaqueTransportMessage, TransportClientId } from './message';
-import { EventDispatcher, EventHandler, EventTypes } from './events';
+import { C as Codec } from '../types-3e5768ec.js';
+import * as _sinclair_typebox from '@sinclair/typebox';
+import { TSchema } from '@sinclair/typebox';
+
+/**
+ * Generic Typebox schema for a transport message.
+ * @template T The type of the payload.
+ * @param {T} t The payload schema.
+ * @returns The transport message schema.
+ */
+declare const TransportMessageSchema: <T extends TSchema>(t: T) => _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TString;
+    from: _sinclair_typebox.TString;
+    to: _sinclair_typebox.TString;
+    serviceName: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNull]>>;
+    procedureName: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNull]>>;
+    streamId: _sinclair_typebox.TString;
+    controlFlags: _sinclair_typebox.TInteger;
+    payload: T;
+}>;
+/**
+ * Defines the schema for an opaque transport message that is agnostic to any
+ * procedure/service.
+ * @returns The transport message schema.
+ */
+declare const OpaqueTransportMessageSchema: _sinclair_typebox.TObject<{
+    id: _sinclair_typebox.TString;
+    from: _sinclair_typebox.TString;
+    to: _sinclair_typebox.TString;
+    serviceName: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNull]>>;
+    procedureName: _sinclair_typebox.TOptional<_sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNull]>>;
+    streamId: _sinclair_typebox.TString;
+    controlFlags: _sinclair_typebox.TInteger;
+    payload: _sinclair_typebox.TUnknown;
+}>;
+/**
+ * Represents a transport message. This is the same type as {@link TransportMessageSchema} but
+ * we can't statically infer generics from generic Typebox schemas so we have to define it again here.
+ *
+ * TypeScript can't enforce types when a bitmask is involved, so these are the semantics of
+ * `controlFlags`:
+ * * If `controlFlags & StreamOpenBit == StreamOpenBit`, `streamId` must be set to a unique value
+ *   (suggestion: use `nanoid`).
+ * * If `controlFlags & StreamOpenBit == StreamOpenBit`, `serviceName` and `procedureName` must be set.
+ * * If `controlFlags & StreamClosedBit == StreamClosedBit` and the kind is `stream` or `subscription`,
+ *   `payload` should be discarded (usually contains a control message).
+ * @template Payload The type of the payload.
+ */
+type TransportMessage<Payload extends Record<string, unknown> | unknown = Record<string, unknown>> = {
+    id: string;
+    from: string;
+    to: string;
+    serviceName?: string;
+    procedureName?: string;
+    streamId: string;
+    controlFlags: number;
+    payload: Payload;
+};
+type MessageId = string;
+/**
+ * A type alias for a transport message with an opaque payload.
+ * @template T - The type of the opaque payload.
+ */
+type OpaqueTransportMessage = TransportMessage<unknown>;
+type TransportClientId = string;
+/**
+ * Creates a transport message with the given parameters. You shouldn't need to call this manually unless
+ * you're writing a test.
+ * @param from The sender of the message.
+ * @param to The intended recipient of the message.
+ * @param service The name of the service the message is intended for.
+ * @param proc The name of the procedure the message is intended for.
+ * @param stream The ID of the stream the message is intended for.
+ * @param payload The payload of the message.
+ * @returns A TransportMessage object with the given parameters.
+ */
+declare function msg<Payload extends object>(from: string, to: string, streamId: string, payload: Payload, serviceName?: string, procedureName?: string): TransportMessage<Payload>;
+/**
+ * Creates a new transport message as a response to the given message.
+ * @param msg The original message to respond to.
+ * @param response The payload of the response message.
+ * @returns A new transport message with appropriate to, from, and payload fields
+ */
+declare function reply<Payload extends object>(msg: OpaqueTransportMessage, response: Payload): TransportMessage<Payload>;
+/**
+ * Checks if the given control flag (usually found in msg.controlFlag) is a stream open message.
+ * @param controlFlag - The control flag to check.
+ * @returns True if the control flag contains the StreamOpenBit, false otherwise.
+ */
+declare function isStreamOpen(controlFlag: number): boolean;
+/**
+ * Checks if the given control flag (usually found in msg.controlFlag) is a stream close message.
+ * @param controlFlag - The control flag to check.
+ * @returns True if the control flag contains the StreamCloseBit, false otherwise.
+ */
+declare function isStreamClose(controlFlag: number): boolean;
+
+interface EventMap {
+    message: OpaqueTransportMessage;
+    connectionStatus: {
+        status: 'connect' | 'disconnect';
+        conn: Connection;
+    };
+}
+type EventTypes = keyof EventMap;
+type EventHandler<K extends EventTypes> = (event: EventMap[K]) => void;
+declare class EventDispatcher<T extends EventTypes> {
+    private eventListeners;
+    numberOfListeners<K extends T>(eventType: K): number;
+    addEventListener<K extends T>(eventType: K, handler: EventHandler<K>): void;
+    removeEventListener<K extends T>(eventType: K, handler: EventHandler<K>): void;
+    dispatchEvent<K extends T>(eventType: K, event: EventMap[K]): void;
+}
+
 /**
  * A 1:1 connection between two transports. Once this is created,
  * the {@link Connection} is expected to take over responsibility for
@@ -12,14 +123,14 @@ import { EventDispatcher, EventHandler, EventTypes } from './events';
  *    connection in the {@link connections} map via `msg.to` and calls {@link send}(bytes)
  *    so the connection can send it.
  */
-export declare abstract class Connection {
+declare abstract class Connection {
     connectedTo: TransportClientId;
     transport: Transport<Connection>;
     constructor(transport: Transport<Connection>, connectedTo: TransportClientId);
     abstract send(msg: Uint8Array): boolean;
     abstract close(): void;
 }
-export type TransportStatus = 'open' | 'closed' | 'destroyed';
+type TransportStatus = 'open' | 'closed' | 'destroyed';
 /**
  * Transports manage the lifecycle (creation/deletion) of connections. Its responsibilities include:
  *
@@ -50,7 +161,7 @@ export type TransportStatus = 'open' | 'closed' | 'destroyed';
  * ```
  * @abstract
  */
-export declare abstract class Transport<ConnType extends Connection> {
+declare abstract class Transport<ConnType extends Connection> {
     /**
      * A flag indicating whether the transport has been destroyed.
      * A destroyed transport will not attempt to reconnect and cannot be used again.
@@ -158,4 +269,5 @@ export declare abstract class Transport<ConnType extends Connection> {
      */
     destroy(): Promise<void>;
 }
-//# sourceMappingURL=transport.d.ts.map
+
+export { Connection, MessageId, OpaqueTransportMessage, OpaqueTransportMessageSchema, Transport, TransportClientId, TransportMessage, TransportMessageSchema, isStreamClose, isStreamOpen, msg, reply };