@replit/river 0.18.4 → 0.19.1

package/dist/index-2941de8c.d.ts

@@ -0,0 +1,341 @@
+import * as _sinclair_typebox from '@sinclair/typebox';
+import { TSchema } from '@sinclair/typebox';
+import { C as Codec } from './types-3e5768ec.js';
+
+declare const LoggingLevels: {
+    readonly debug: -1;
+    readonly info: 0;
+    readonly warn: 1;
+    readonly error: 2;
+};
+type LoggingLevel = keyof typeof LoggingLevels;
+type LogFn = (msg: string, ctx?: MessageMetadata, level?: LoggingLevel) => void;
+type Logger = {
+    [key in LoggingLevel]: LogFn;
+};
+type MessageMetadata = Record<string, unknown> & Partial<{
+    protocolVersion: string;
+    clientId: string;
+    connectedTo: string;
+    sessionId: string;
+    connId: string;
+    fullTransportMessage: OpaqueTransportMessage;
+    partialTransportMessage: Partial<PartialTransportMessage>;
+}>;
+declare const stringLogger: LogFn;
+declare const coloredStringLogger: LogFn;
+declare const jsonLogger: LogFn;
+declare function bindLogger(fn: LogFn | Logger | undefined, level?: LoggingLevel): Logger | undefined;
+
+/**
+ * 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;
+}
+interface SessionOptions {
+    /**
+     * Frequency at which to send heartbeat acknowledgements
+     */
+    heartbeatIntervalMs: number;
+    /**
+     * Number of elapsed heartbeats without a response message before we consider
+     * the connection dead.
+     */
+    heartbeatsUntilDead: number;
+    /**
+     * Duration to wait between connection disconnect and actual session disconnect
+     */
+    sessionDisconnectGraceMs: number;
+    /**
+     * The codec to use for encoding/decoding messages over the wire
+     */
+    codec: Codec;
+}
+/**
+ * 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
+ */
+declare class Session<ConnType extends Connection> {
+    private codec;
+    private options;
+    /**
+     * 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.
+     */
+    id: string;
+    /**
+     * What the other side advertised as their session ID
+     * for this session.
+     */
+    advertisedSessionId?: string;
+    /**
+     * The metadata for this session, as parsed from the handshake.
+     *
+     * Will only ever be populated on the server side.
+     */
+    metadata?: ParsedHandshakeMetadata;
+    /**
+     * Number of messages we've sent along this session (excluding handshake and acks)
+     */
+    private seq;
+    /**
+     * Number of unique messages we've received this session (excluding handshake and acks)
+     */
+    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(conn: ConnType | undefined, from: TransportClientId, to: TransportClientId, options: SessionOptions);
+    get loggingMetadata(): Omit<MessageMetadata, 'parsedMsg'>;
+    /**
+     * 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 addToSendBuff Whether to add the message to the send buffer for retry.
+     * @returns The full transport ID of the message that was attempted to be sent.
+     */
+    send(msg: PartialTransportMessage): string;
+    sendHeartbeat(): void;
+    resetBufferedMessages(): void;
+    sendBufferedMessages(conn: ConnType): void;
+    updateBookkeeping(ack: number, seq: number): void;
+    closeStaleConnection(conn?: ConnType): void;
+    replaceWithNewConnection(newConn: ConnType): void;
+    beginGrace(cb: () => void): void;
+    cancelGrace(): void;
+    close(): void;
+    get connected(): boolean;
+    get nextExpectedSeq(): number;
+    constructMsg<Payload>(partialMsg: PartialTransportMessage<Payload>): TransportMessage<Payload>;
+    inspectSendBuffer(): ReadonlyArray<OpaqueTransportMessage>;
+}
+
+/**
+ * Metadata associated with a handshake request, as sent by the client.
+ *
+ * You should use declaration merging to extend this interface
+ * with whatever you need. For example, if you need to store an
+ * identifier for the client, you could do:
+ * ```
+ * declare module '@replit/river' {
+ *   interface HandshakeMetadataClient {
+ *     id: string;
+ *   }
+ * }
+ * ```
+ */
+interface HandshakeRequestMetadata {
+}
+/**
+ * Metadata associated with a handshake response, after the server
+ * has processed the data in {@link HandshakeRequestMetadata}. This
+ * is a separate interface for multiple reasons, but one of the main
+ * ones is that the server should remove any sensitive data from the
+ * client's request metadata before storing it in the session, that
+ * way no secrets are persisted in memory.
+ *
+ * You should use declaration merging to extend this interface
+ * with whatever you need. For example, if you need to store an
+ * identifier for the client, you could do:
+ * ```
+ * declare module '@replit/river' {
+ *   interface HandshakeMetadataServer {
+ *     id: string;
+ *   }
+ * }
+ * ```
+ */
+interface ParsedHandshakeMetadata {
+}
+/**
+ * Options for extending the client handshake process.
+ */
+interface ClientHandshakeOptions {
+    /**
+     * Schema for the metadata that the client sends to the server
+     * during the handshake.
+     *
+     * Needs to match {@link HandshakeRequestMetadata}.
+     */
+    schema: TSchema;
+    /**
+     * Gets the {@link HandshakeRequestMetadata} to send to the server.
+     */
+    get: () => HandshakeRequestMetadata | Promise<HandshakeRequestMetadata>;
+}
+/**
+ * Options for extending the server handshake process.
+ */
+interface ServerHandshakeOptions {
+    /**
+     * Schema for the metadata that the server receives from the client
+     * during the handshake.
+     *
+     * Needs to match {@link HandshakeRequestMetadata}.
+     */
+    requestSchema: TSchema;
+    /**
+     * Schema for the transformed metadata that is then associated with the
+     * client's session.
+     *
+     * Needs to match {@link ParsedHandshakeMetadata}.
+     */
+    parsedSchema: TSchema;
+    /**
+     * Parses the {@link HandshakeRequestMetadata} sent by the client, transforming
+     * it into {@link ParsedHandshakeMetadata}.
+     *
+     * May return `false` if the client should be rejected.
+     *
+     * @param metadata - The metadata sent by the client.
+     * @param session - The session that the client would be associated with.
+     * @param isReconnect - Whether the client is reconnecting to the session,
+     *                      or if this is a new session.
+     */
+    parse: (metadata: HandshakeRequestMetadata, session: Session<Connection>, isReconnect: boolean) => false | ParsedHandshakeMetadata | Promise<false | ParsedHandshakeMetadata>;
+}
+/**
+ * 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.TString>;
+    procedureName: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+    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.TString>;
+    procedureName: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+    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).
+ * * If `controlFlags & AckBit == AckBit`, the message is an explicit acknowledgement message and doesn't
+ *   contain any payload that is relevant to the application so should not be delivered.
+ * @template Payload The type of the payload.
+ */
+interface TransportMessage<Payload = unknown> {
+    id: string;
+    from: string;
+    to: string;
+    seq: number;
+    ack: number;
+    serviceName?: string;
+    procedureName?: string;
+    streamId: string;
+    controlFlags: number;
+    payload: Payload;
+}
+type PartialTransportMessage<Payload = 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;
+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;
+
+export { Connection as C, HandshakeRequestMetadata as H, Logger as L, MessageMetadata as M, OpaqueTransportMessage as O, PartialTransportMessage as P, SessionOptions as S, TransportClientId as T, Session as a, ParsedHandshakeMetadata as b, TransportMessageSchema as c, OpaqueTransportMessageSchema as d, TransportMessage as e, ClientHandshakeOptions as f, ServerHandshakeOptions as g, isStreamClose as h, isStreamOpen as i, coloredStringLogger as j, jsonLogger as k, bindLogger as l, LogFn as m, stringLogger as s };

package/dist/logging/index.d.cts

@@ -1,2 +1,3 @@
-export { g as LogFn, L as Logger, M as MessageMetadata, f as bindLogger, e as coloredStringLogger, j as jsonLogger, s as stringLogger } from '../index-46ed19d8.js';
+export { m as LogFn, L as Logger, M as MessageMetadata, l as bindLogger, j as coloredStringLogger, k as jsonLogger, s as stringLogger } from '../index-2941de8c.js';
 import '@sinclair/typebox';
+import '../types-3e5768ec.js';

package/dist/logging/index.d.ts

@@ -1,2 +1,3 @@
-export { g as LogFn, L as Logger, M as MessageMetadata, f as bindLogger, e as coloredStringLogger, j as jsonLogger, s as stringLogger } from '../index-46ed19d8.js';
+export { m as LogFn, L as Logger, M as MessageMetadata, l as bindLogger, j as coloredStringLogger, k as jsonLogger, s as stringLogger } from '../index-2941de8c.js';
 import '@sinclair/typebox';
+import '../types-3e5768ec.js';

package/dist/router/index.cjs

@@ -28,12 +28,22 @@ __export(router_exports, {
   ServiceSchema: () => ServiceSchema,
   UNCAUGHT_ERROR: () => UNCAUGHT_ERROR,
   createClient: () => createClient,
-  createServer: () => createServer
+  createServer: () => createServer,
+  serializeSchema: () => serializeSchema
 });
 module.exports = __toCommonJS(router_exports);
 
 // router/services.ts
 var import_typebox = require("@sinclair/typebox");
+function serializeSchema(services) {
+  return Object.entries(services).reduce(
+    (acc, [name, value]) => {
+      acc[name] = value.serialize();
+      return acc;
+    },
+    {}
+  );
+}
 var ServiceSchema = class _ServiceSchema {
   /**
    * Factory function for creating a fresh state.
@@ -618,7 +628,8 @@ var ControlMessageCloseSchema = import_typebox3.Type.Object({
 var ControlMessageHandshakeRequestSchema = import_typebox3.Type.Object({
   type: import_typebox3.Type.Literal("HANDSHAKE_REQ"),
   protocolVersion: import_typebox3.Type.String(),
-  sessionId: import_typebox3.Type.String()
+  sessionId: import_typebox3.Type.String(),
+  metadata: import_typebox3.Type.Optional(import_typebox3.Type.Unknown())
 });
 var ControlMessageHandshakeResponseSchema = import_typebox3.Type.Object({
   type: import_typebox3.Type.Literal("HANDSHAKE_RESP"),
@@ -1152,6 +1163,13 @@ var RiverServer = class {
         })
       );
     };
+    if (session.metadata === void 0) {
+      log?.error(
+        `(invariant violation) session doesn't have handshake metadata`,
+        session.loggingMetadata
+      );
+      return;
+    }
     let inputHandler;
     const procHasInitMessage = "init" in procedure;
     const serviceContextWithTransportInfo = {
@@ -1159,6 +1177,7 @@ var RiverServer = class {
       to: message.to,
       from: message.from,
       streamId: message.streamId,
+      // we've already validated that the session has handshake metadata
       session
     };
     switch (procedure.type) {
@@ -1334,7 +1353,7 @@ function createServer(transport, services, extendedContext) {
 }
 
 // package.json
-var version = "0.18.4";
+var version = "0.19.1";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Err,
@@ -1345,5 +1364,6 @@ var version = "0.18.4";
   ServiceSchema,
   UNCAUGHT_ERROR,
   createClient,
-  createServer
+  createServer,
+  serializeSchema
 });