@replit/river 0.11.0 → 0.12.0

package/dist/index-d91775d9.d.ts

@@ -0,0 +1,442 @@
+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;
+    seq: _sinclair_typebox.TInteger;
+    ack: _sinclair_typebox.TInteger;
+    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;
+    seq: _sinclair_typebox.TInteger;
+    ack: _sinclair_typebox.TInteger;
+    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.
+ */
+interface TransportMessage<Payload = Record<string, unknown>> {
+    id: string;
+    from: string;
+    to: string;
+    seq: number;
+    ack: number;
+    serviceName?: string;
+    procedureName?: string;
+    streamId: string;
+    controlFlags: number;
+    payload: Payload;
+}
+type PartialTransportMessage<Payload extends Record<string, unknown> = Record<string, unknown>> = Omit<TransportMessage<Payload>, 'id' | 'from' | 'to' | 'seq' | 'ack'>;
+/**
+ * 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;
+/**
+ * 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;
+
+/**
+ * A connection is the actual raw underlying transport connection.
+ * It’s responsible for dispatching to/from the actual connection itself
+ * This should be instantiated as soon as the client/server has a connection
+ * It’s tied to the lifecycle of the underlying transport connection (i.e. if the WS drops, this connection should be deleted)
+ */
+declare abstract class Connection {
+    debugId: string;
+    constructor();
+    /**
+     * Handle adding a callback for when a message is received.
+     * @param msg The message that was received.
+     */
+    abstract addDataListener(cb: (msg: Uint8Array) => void): void;
+    abstract removeDataListener(cb: (msg: Uint8Array) => void): void;
+    /**
+     * Handle adding a callback for when the connection is closed.
+     * This should also be called if an error happens.
+     * @param cb The callback to call when the connection is closed.
+     */
+    abstract addCloseListener(cb: () => void): void;
+    /**
+     * Handle adding a callback for when an error is received.
+     * This should only be used for logging errors, all cleanup
+     * should be delegated to addCloseListener.
+     *
+     * The implementer should take care such that the implemented
+     * connection will call both the close and error callbacks
+     * on an error.
+     *
+     * @param cb The callback to call when an error is received.
+     */
+    abstract addErrorListener(cb: (err: Error) => void): void;
+    /**
+     * Sends a message over the connection.
+     * @param msg The message to send.
+     * @returns true if the message was sent, false otherwise.
+     */
+    abstract send(msg: Uint8Array): boolean;
+    /**
+     * Closes the connection.
+     */
+    abstract close(): void;
+}
+/**
+ * A session is a higher-level abstraction that operates over the span of potentially multiple transport-level connections
+ * - It’s responsible for tracking any metadata for a particular client that might need to be persisted across connections (i.e. the sendBuffer, ack, seq)
+ * - This will only be considered disconnected if
+ *    - the server tells the client that we’ve reconnected but it doesn’t recognize us anymore (server definitely died) or
+ *    - we hit a grace period after a connection disconnect
+ *
+ * Here's a legend for what each of the numbers means. A '-' indicates the
+ * session/connection is connected and ' ' means it is disconnected.
+ *
+ * 1. connectionStatus :: connect
+ * 2. sessionStatus    :: connect
+ * 3. connectionStatus :: disconnect
+ * 4. sessionStatus    :: disconnect
+ *
+ * From the server's perspective:
+ * ```plaintext
+ * session         2-----------------------4
+ * connection  ----1---------3   1-------3
+ *                                       ^-^ grace period
+ *             ^---^ connection is created
+ *                   before connectionStatus event is fired
+ * ```
+ *
+ * From the client's perspective:
+ * ```plaintext
+ * session     2---------------------------4
+ * connection      1---------3   1-------3
+ *                                       ^-^ grace period
+ *             ^---^ session is created as soon
+ *                   as we send an outgoing message
+ * ```
+ */
+declare class Session<ConnType extends Connection> {
+    private codec;
+    /**
+     * The buffer of messages that have been sent but not yet acknowledged.
+     */
+    private sendBuffer;
+    /**
+     * The active connection associated with this session
+     */
+    connection?: ConnType;
+    readonly from: TransportClientId;
+    readonly to: TransportClientId;
+    /**
+     * The unique ID of this session.
+     */
+    debugId: string;
+    /**
+     * Number of messages we've sent along this session (excluding handshake)
+     */
+    private seq;
+    /**
+     * Number of unique messages we've received this session (excluding handshake)
+     */
+    private ack;
+    /**
+     * The grace period between when the inner connection is disconnected
+     * and when we should consider the entire session disconnected.
+     */
+    private disconnectionGrace?;
+    /**
+     * Number of heartbeats we've sent without a response.
+     */
+    private heartbeatMisses;
+    /**
+     * The interval for sending heartbeats.
+     */
+    private heartbeat?;
+    constructor(codec: Codec, from: TransportClientId, connectedTo: TransportClientId, conn: ConnType | undefined);
+    /**
+     * 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: PartialTransportMessage, skipRetry?: boolean): string;
+    sendHeartbeat(): void;
+    resetBufferedMessages(): void;
+    sendBufferedMessages(): void;
+    updateBookkeeping(ack: number, seq: number): void;
+    addToSendBuff(msg: TransportMessage): void;
+    closeStaleConnection(conn?: ConnType): void;
+    replaceWithNewConnection(newConn: ConnType): void;
+    beginGrace(cb: () => void): void;
+    cancelGrace(): void;
+    get connected(): boolean;
+    get nextExpectedSeq(): number;
+    constructMsg<Payload extends Record<string, unknown>>(partialMsg: PartialTransportMessage<Payload>): TransportMessage<Payload>;
+    /**
+     * 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(): void;
+    inspectSendBuffer(): ReadonlyArray<OpaqueTransportMessage>;
+}
+
+type ConnectionStatus = 'connect' | 'disconnect';
+interface EventMap {
+    message: OpaqueTransportMessage;
+    connectionStatus: {
+        status: ConnectionStatus;
+        conn: Connection;
+    };
+    sessionStatus: {
+        status: ConnectionStatus;
+        session: Session<Connection>;
+    };
+}
+type EventTypes = keyof EventMap;
+type EventHandler<K extends EventTypes> = (event: EventMap[K]) => unknown;
+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;
+}
+
+/**
+ * Represents the possible states of a transport.
+ * @property {'open'} open - The transport is open and operational (note that this doesn't mean it is actively connected)
+ * @property {'closed'} closed - The transport is closed and not operational, but can be reopened.
+ * @property {'destroyed'} destroyed - The transport is permanently destroyed and cannot be reopened.
+ */
+type TransportStatus = 'open' | 'closed' | 'destroyed';
+interface TransportOptions {
+    retryIntervalMs: number;
+    retryJitterMs: number;
+    retryAttemptsMax: number;
+    codec: Codec;
+}
+/**
+ * Transports manage the lifecycle (creation/deletion) of sessions and connections. Its responsibilities include:
+ *
+ *  1) Constructing a new {@link Session} and {@link Connection} on {@link TransportMessage}s from new clients.
+ *     After constructing the {@link Connection}, {@link onConnect} is called which adds it to the connection map.
+ *  2) Delegating message listening of the connection to the newly created {@link Connection}.
+ *     From this point on, the {@link Connection} is responsible for *reading* and *writing*
+ *     messages from the connection.
+ *  3) When a connection is closed, the {@link Transport} calls {@link onDisconnect} which closes the
+ *     connection via {@link Connection.close} and removes it from the {@link connections} map.
+
+ *
+ * ```plaintext
+ *            ▲
+ *  incoming  │
+ *  messages  │
+ *            ▼
+ *      ┌─────────────┐   1:N   ┌───────────┐   1:1*  ┌────────────┐
+ *      │  Transport  │ ◄─────► │  Session  │ ◄─────► │ Connection │
+ *      └─────────────┘         └───────────┘         └────────────┘
+ *            ▲                               * (may or may not be initialized yet)
+ *            │
+ *            ▼
+ *      ┌───────────┐
+ *      │ Message   │
+ *      │ Listeners │
+ *      └───────────┘
+ * ```
+ * @abstract
+ */
+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.
+     */
+    state: TransportStatus;
+    /**
+     * The {@link Codec} used to encode and decode messages.
+     */
+    codec: Codec;
+    /**
+     * The client ID of this transport.
+     */
+    clientId: TransportClientId;
+    /**
+     * The map of {@link Session}s managed by this transport.
+     */
+    sessions: Map<TransportClientId, Session<ConnType>>;
+    /**
+     * The map of {@link Connection}s managed by this transport.
+     */
+    get connections(): Map<string, ConnType>;
+    /**
+     * The event dispatcher for handling events of type EventTypes.
+     */
+    eventDispatcher: EventDispatcher<EventTypes>;
+    /**
+     * The options for this transport.
+     */
+    options: TransportOptions;
+    /**
+     * 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: TransportClientId, providedOptions?: Partial<TransportOptions>);
+    private sessionByClientId;
+    /**
+     * This is called immediately after a new connection is established and we
+     * may or may not know the identity of the connected client.
+     * It should attach all the necessary listeners to the connection for lifecycle
+     * events (i.e. data, close, error)
+     *
+     * This method is implemented by {@link ClientTransport} and {@link ServerTransport}.
+     */
+    protected abstract handleConnection(conn: ConnType, to: TransportClientId): void;
+    /**
+     * Called when a new connection is established
+     * and we know the identity of the connected client.
+     * @param conn The connection object.
+     */
+    protected onConnect(conn: ConnType, connectedTo: TransportClientId): Session<ConnType>;
+    private createSession;
+    protected deleteSession(session: Session<ConnType>): void;
+    /**
+     * The downstream implementation needs to call this when a connection is closed.
+     * @param conn The connection object.
+     */
+    onDisconnect(conn: ConnType, connectedTo: TransportClientId | undefined): void;
+    /**
+     * 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.
+     */
+    protected parseMsg(msg: Uint8Array): OpaqueTransportMessage | 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(msg: OpaqueTransportMessage | null): void;
+    /**
+     * Adds a listener to this transport.
+     * @param the type of event to listen for
+     * @param handler The message handler to add.
+     */
+    addEventListener<K extends EventTypes, T extends EventHandler<K>>(type: K, handler: T): void;
+    /**
+     * Removes a listener from this transport.
+     * @param the type of event to unlisten on
+     * @param handler The message handler to remove.
+     */
+    removeEventListener<K extends EventTypes, T extends EventHandler<K>>(type: K, handler: T): void;
+    /**
+     * 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: TransportClientId, msg: PartialTransportMessage): string | undefined;
+    sendCloseStream(to: TransportClientId, streamId: string): string | undefined;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+}
+declare abstract class ClientTransport<ConnType extends Connection> extends Transport<ConnType> {
+    /**
+     * The map of reconnect promises for each client ID.
+     */
+    inflightConnectionPromises: Map<TransportClientId, Promise<ConnType>>;
+    tryReconnecting: boolean;
+    serverInstanceIds: Map<string, string>;
+    constructor(clientId: TransportClientId, providedOptions?: Partial<TransportOptions>);
+    protected handleConnection(conn: ConnType, to: TransportClientId): void;
+    /**
+     * Abstract method that creates a new {@link Connection} object.
+     * This should call {@link handleConnection} when the connection is created.
+     * The downstream client implementation needs to implement this.
+     *
+     * @param to The client ID of the node to connect to.
+     * @returns The new connection object.
+     */
+    protected abstract createNewOutgoingConnection(to: TransportClientId): Promise<ConnType>;
+    /**
+     * Manually attempts to connect to a client.
+     * @param to The client ID of the node to connect to.
+     */
+    connect(to: TransportClientId, attempt?: number): Promise<void>;
+    receiveWithBootSequence(conn: ConnType, sessionCb: (sess: Session<ConnType>) => void): (data: Uint8Array) => void;
+    onDisconnect(conn: ConnType, connectedTo: string | undefined): void;
+}
+declare abstract class ServerTransport<ConnType extends Connection> extends Transport<ConnType> {
+    /**
+     * Unique per instance of server transport.
+     * This allows us to distinguish reconnects to different
+     * server transports at the same reachable address and signal
+     * the appropriate session disconnect back to the client at the
+     * boot stage.
+     */
+    instanceId: string;
+    constructor(clientId: TransportClientId, providedOptions?: Partial<TransportOptions>);
+    protected handleConnection(conn: ConnType): void;
+    receiveWithBootSequence(conn: ConnType, sessionCb: (sess: Session<ConnType>) => void): (data: Uint8Array) => void;
+}
+
+export { Connection as C, EventMap as E, OpaqueTransportMessage as O, PartialTransportMessage as P, ServerTransport as S, Transport as T, ClientTransport as a, TransportClientId as b, TransportOptions as c, Session as d, TransportMessageSchema as e, OpaqueTransportMessageSchema as f, TransportMessage as g, isStreamClose as h, isStreamOpen as i, EventTypes as j, EventHandler as k };

package/dist/logging/index.cjs

@@ -22,7 +22,8 @@ var logging_exports = {};
 __export(logging_exports, {
   bindLogger: () => bindLogger,
   log: () => log,
-  setLevel: () => setLevel
+  setLevel: () => setLevel,
+  unbindLogger: () => unbindLogger
 });
 module.exports = __toCommonJS(logging_exports);
 var LoggingLevels = {
@@ -32,7 +33,7 @@ var LoggingLevels = {
   error: 2
 };
 var log;
-var defaultLoggingLevel = "warn";
+var defaultLoggingLevel = "info";
 function bindLogger(write, color) {
   const debug = color ? "\x1B[37mdebug\x1B[0m" : "debug";
   const info = color ? "\x1B[37minfo\x1B[0m" : "info";
@@ -46,6 +47,9 @@ function bindLogger(write, color) {
     minLevel: log?.minLevel ?? defaultLoggingLevel
   };
 }
+function unbindLogger() {
+  log = void 0;
+}
 function setLevel(level) {
   if (log) {
     log.minLevel = level;
@@ -55,5 +59,6 @@ function setLevel(level) {
 0 && (module.exports = {
   bindLogger,
   log,
-  setLevel
+  setLevel,
+  unbindLogger
 });

package/dist/logging/index.d.cts

@@ -20,10 +20,15 @@ declare let log: Logger | undefined;
  * @param color - Whether to use colored log levels.
  */
 declare function bindLogger(write: (msg: string) => void, color?: boolean): void;
+/**
+ * Unbinds the logger so subsequent logs do not call
+ * the write callback previously provided to {@link bindLogger}
+ */
+declare function unbindLogger(): void;
 /**
  * Sets the minimum logging level for the logger.
  * @param level - The minimum logging level to set.
  */
 declare function setLevel(level: LoggingLevel): void;
 
-export { Logger, bindLogger, log, setLevel };
+export { Logger, bindLogger, log, setLevel, unbindLogger };

package/dist/logging/index.d.ts

@@ -20,10 +20,15 @@ declare let log: Logger | undefined;
  * @param color - Whether to use colored log levels.
  */
 declare function bindLogger(write: (msg: string) => void, color?: boolean): void;
+/**
+ * Unbinds the logger so subsequent logs do not call
+ * the write callback previously provided to {@link bindLogger}
+ */
+declare function unbindLogger(): void;
 /**
  * Sets the minimum logging level for the logger.
  * @param level - The minimum logging level to set.
  */
 declare function setLevel(level: LoggingLevel): void;
 
-export { Logger, bindLogger, log, setLevel };
+export { Logger, bindLogger, log, setLevel, unbindLogger };

package/dist/logging/index.js

@@ -1,10 +1,12 @@
 import {
   bindLogger,
   log,
-  setLevel
-} from "../chunk-T7M7OKPE.js";
+  setLevel,
+  unbindLogger
+} from "../chunk-H4BYJELI.js";
 export {
   bindLogger,
   log,
-  setLevel
+  setLevel,
+  unbindLogger
 };

package/dist/messageFraming-b200ef25.d.ts

@@ -0,0 +1,20 @@
+import { Transform, TransformCallback, TransformOptions } from 'node:stream';
+
+interface LengthEncodedOptions extends TransformOptions {
+    /** Maximum in-memory buffer size before we throw */
+    maxBufferSizeBytes: number;
+}
+/**
+ * A transform stream that emits data each time a message with a network/BigEndian uint32 length prefix is received.
+ * @extends Transform
+ */
+declare class Uint32LengthPrefixFraming extends Transform {
+    receivedBuffer: Buffer;
+    maxBufferSizeBytes: number;
+    constructor({ maxBufferSizeBytes, ...options }: LengthEncodedOptions);
+    _transform(chunk: Buffer, _encoding: BufferEncoding, cb: TransformCallback): void;
+    _flush(cb: TransformCallback): void;
+    _destroy(error: Error | null, callback: (error: Error | null) => void): void;
+}
+
+export { Uint32LengthPrefixFraming as U };