@replit/river 0.10.0 → 0.10.2

package/dist/{router/builder.d.ts → builder-3c4485f0.d.ts}

@@ -1,19 +1,73 @@
-import { TObject, Static, TUnion } from '@sinclair/typebox';
-import type { Pushable } from 'it-pushable';
-import { ServiceContextWithState } from './context';
-import { Result, RiverError, RiverUncaughtSchema } from './result';
+import * as _sinclair_typebox from '@sinclair/typebox';
+import { TObject, TLiteralString, TString, TSchema, TUnion, TNever, Static } from '@sinclair/typebox';
+import { Pushable } from 'it-pushable';
+
+/**
+ * The context for services/procedures. This is used only on
+ * the server.
+ *
+ * An important detail is that the state prop is always on
+ * this interface and it shouldn't be changed, removed, or
+ * extended. This prop is for the state of a service.
+ *
+ * You should use declaration merging to extend this interface
+ * with whatever you need. For example, if you need to access
+ * a database, you could do:
+ *
+ * ```ts
+ * declare module '@replit/river' {
+ *   interface ServiceContext {
+ *     db: Database;
+ *   }
+ * }
+ * ```
+ */
+interface ServiceContext {
+    state: object | unknown;
+}
+/**
+ * The {@link ServiceContext} with state. This is what is passed to procedures.
+ */
+type ServiceContextWithState<State extends object | unknown> = ServiceContext & {
+    state: State;
+};
+
+type RiverErrorSchema = TObject<{
+    code: TLiteralString;
+    message: TLiteralString | TString;
+}> | TObject<{
+    code: TLiteralString;
+    message: TLiteralString | TString;
+    extras: TSchema;
+}>;
+type RiverError = TUnion<RiverErrorSchema[]> | RiverErrorSchema | TNever;
+declare const UNCAUGHT_ERROR = "UNCAUGHT_ERROR";
+declare const RiverUncaughtSchema: TObject<{
+    code: TUnion<[_sinclair_typebox.TLiteral<"UNCAUGHT_ERROR">, _sinclair_typebox.TLiteral<"UNEXPECTED_DISCONNECT">]>;
+    message: TString;
+}>;
+type Result<T, E> = {
+    ok: true;
+    payload: T;
+} | {
+    ok: false;
+    payload: E;
+};
+declare function Ok<T, E>(payload: T): Result<T, E>;
+declare function Err<T, E>(error: E): Result<T, E>;
+
 /**
  * The valid {@link Procedure} types. The `stream` and `upload` types can optionally have a
  * different type for the very first initialization message. The suffixless types correspond to
  * gRPC's four combinations of stream / non-stream in each direction.
  */
-export type ValidProcType = 'rpc' | 'upload' | 'subscription' | 'stream';
+type ValidProcType = 'rpc' | 'upload' | 'subscription' | 'stream';
 /**
  * A generic procedure listing where the keys are the names of the procedures
  * and the values are the {@link Procedure} definitions. This is not meant to
  * be constructed directly, use the {@link ServiceBuilder} class instead.
  */
-export type ProcListing = Record<string, AnyProcedure>;
+type ProcListing = Record<string, AnyProcedure>;
 /**
  * Represents a service with a name, state, and procedures.
  * This is not meant to be constructed directly, use the {@link ServiceBuilder} class instead.
@@ -21,30 +75,30 @@ export type ProcListing = Record<string, AnyProcedure>;
  * @template State The type of the service state.
  * @template Procs The type of the service procedures.
  */
-export interface Service<Name extends string, State extends object, Procs extends ProcListing> {
+interface Service<Name extends string, State extends object, Procs extends ProcListing> {
     name: Name;
     state: State;
     procedures: Procs;
 }
-export type AnyService = Service<string, object, any>;
+type AnyService = Service<string, object, any>;
 /**
  * Serializes a service object into its corresponding JSON Schema Draft 7 type.
  * @param {AnyService} s - The service object to serialize.
  * @returns A plain object representing the serialized service.
  */
-export declare function serializeService(s: AnyService): object;
+declare function serializeService(s: AnyService): object;
 /**
  * Helper to get the type definition for a specific handler of a procedure in a service.
  * @template S - The service.
  * @template ProcName - The name of the procedure.
  */
-export type ProcHandler<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['handler'];
+type ProcHandler<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['handler'];
 /**
  * Helper to get whether the type definition for the procedure contains an init type.
  * @template S - The service.
  * @template ProcName - The name of the procedure.
  */
-export type ProcHasInit<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName] extends {
+type ProcHasInit<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName] extends {
     init: any;
 } ? true : false;
 /**
@@ -52,32 +106,32 @@ export type ProcHasInit<S extends AnyService, ProcName extends keyof S['procedur
  * @template S - The service.
  * @template ProcName - The name of the procedure.
  */
-export type ProcInit<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['init'];
+type ProcInit<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['init'];
 /**
  * Helper to get the type definition for the procedure input of a service.
  * @template S - The service.
  * @template ProcName - The name of the procedure.
  */
-export type ProcInput<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['input'];
+type ProcInput<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['input'];
 /**
  * Helper to get the type definition for the procedure output of a service.
  * @template S - The service.
  * @template ProcName - The name of the procedure.
  */
-export type ProcOutput<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['output'];
+type ProcOutput<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['output'];
 /**
  * Helper to get the type definition for the procedure errors of a service.
  * @template S - The service.
  * @template ProcName - The name of the procedure.
  */
-export type ProcErrors<S extends AnyService, ProcName extends keyof S['procedures']> = TUnion<[S['procedures'][ProcName]['errors'], typeof RiverUncaughtSchema]>;
+type ProcErrors<S extends AnyService, ProcName extends keyof S['procedures']> = TUnion<[S['procedures'][ProcName]['errors'], typeof RiverUncaughtSchema]>;
 /**
  * Helper to get the type of procedure in a service.
  * @template S - The service.
  * @template ProcName - The name of the procedure.
  */
-export type ProcType<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['type'];
-export type PayloadType = TObject | TUnion<TObject[]>;
+type ProcType<S extends AnyService, ProcName extends keyof S['procedures']> = S['procedures'][ProcName]['type'];
+type PayloadType = TObject | TUnion<TObject[]>;
 /**
  * Defines a Procedure type that can be either an RPC or a stream procedure.
  * @template State - The TypeBox schema of the state object.
@@ -86,7 +140,7 @@ export type PayloadType = TObject | TUnion<TObject[]>;
  * @template O - The TypeBox schema of the output object.
  * @template Init - The TypeBox schema of the input initialization object.
  */
-export type Procedure<State extends object | unknown, Ty extends ValidProcType, I extends PayloadType, O extends PayloadType, E extends RiverError, Init extends PayloadType | null = null> = Ty extends 'rpc' ? Init extends null ? {
+type Procedure<State extends object | unknown, Ty extends ValidProcType, I extends PayloadType, O extends PayloadType, E extends RiverError, Init extends PayloadType | null = null> = Ty extends 'rpc' ? Init extends null ? {
     input: I;
     output: O;
     errors: E;
@@ -125,13 +179,13 @@ export type Procedure<State extends object | unknown, Ty extends ValidProcType,
     handler: (context: ServiceContextWithState<State>, input: AsyncIterableIterator<Static<I>>, output: Pushable<Result<Static<O>, Static<E>>>) => Promise<void>;
     type: Ty;
 } : never;
-export type AnyProcedure = Procedure<object, ValidProcType, PayloadType, PayloadType, RiverError, PayloadType | null>;
+type AnyProcedure = Procedure<object, ValidProcType, PayloadType, PayloadType, RiverError, PayloadType | null>;
 /**
  * A builder class for creating River Services.
  * You must call the finalize method to get the finalized schema for use in a service router.
  * @template T The type of the service.
  */
-export declare class ServiceBuilder<T extends Service<string, object, ProcListing>> {
+declare class ServiceBuilder<T extends Service<string, object, ProcListing>> {
     private readonly schema;
     private constructor();
     /**
@@ -174,4 +228,5 @@ export declare class ServiceBuilder<T extends Service<string, object, ProcListin
         procedures: {};
     }>;
 }
-//# sourceMappingURL=builder.d.ts.map
+
+export { AnyService as A, Err as E, Ok as O, PayloadType as P, RiverError as R, ServiceContext as S, UNCAUGHT_ERROR as U, ValidProcType as V, Procedure as a, Result as b, RiverUncaughtSchema as c, AnyProcedure as d, ProcType as e, ProcInput as f, ProcOutput as g, ProcErrors as h, ProcHasInit as i, ProcInit as j, ServiceBuilder as k, ProcListing as l, Service as m, ProcHandler as n, ServiceContextWithState as o, RiverErrorSchema as p, serializeService as s };

package/dist/chunk-AJQU4AZG.js

@@ -0,0 +1,284 @@
+import {
+  OpaqueTransportMessageSchema,
+  TransportAckSchema,
+  isAck,
+  reply
+} from "./chunk-ZE4MX7DF.js";
+import {
+  log
+} from "./chunk-SLUSVGQH.js";
+
+// transport/transport.ts
+import { Value } from "@sinclair/typebox/value";
+
+// 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 msg = this.sendBuffer.get(id);
+      if (!msg) {
+        log?.warn(
+          `${this.clientId} -- tried to resend a message we received an ack for`
+        );
+        continue;
+      }
+      this.send(msg);
+    }
+    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(msg) {
+    return this.handleMsg(this.parseMsg(msg));
+  }
+  /**
+   * 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?.warn(`${this.clientId} -- received malformed msg: ${decodedBuffer}`);
+      return null;
+    }
+    if (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(msg) {
+    if (!msg) {
+      return;
+    }
+    if (isAck(msg.controlFlags) && Value.Check(TransportAckSchema, msg)) {
+      log?.info(`${this.clientId} -- received ack: ${JSON.stringify(msg)}`);
+      if (this.sendBuffer.has(msg.payload.ack)) {
+        this.sendBuffer.delete(msg.payload.ack);
+      }
+    } else {
+      log?.info(`${this.clientId} -- received msg: ${JSON.stringify(msg)}`);
+      if (msg.to !== this.clientId) {
+        return;
+      }
+      this.eventDispatcher.dispatchEvent("message", msg);
+      if (!isAck(msg.controlFlags)) {
+        const ackMsg = reply(msg, { ack: msg.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(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 msg.id;
+    }
+    let conn = this.connections.get(msg.to);
+    if (!isAck(msg.controlFlags)) {
+      this.sendBuffer.set(msg.id, msg);
+    }
+    if (conn) {
+      log?.info(`${this.clientId} -- sending ${JSON.stringify(msg)}`);
+      const ok = conn.send(this.codec.toBuffer(msg));
+      if (ok) {
+        return msg.id;
+      }
+    }
+    log?.info(
+      `${this.clientId} -- connection to ${msg.to} not ready, attempting reconnect and queuing ${JSON.stringify(msg)}`
+    );
+    const outstanding = this.sendQueue.get(msg.to) || [];
+    outstanding.push(msg.id);
+    this.sendQueue.set(msg.to, outstanding);
+    this.createNewConnection(msg.to);
+    return msg.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`);
+  }
+};
+
+export {
+  Connection,
+  Transport
+};