@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/server/index.d.ts

@@ -1,27 +1,47 @@
-import { T as TransactionStatement, Q as QueryResponse, E as ExecuteResponse, a as TransactionResponse, B as BatchResponse, L as LoadResponse, A as AckResponse } from '../protocol-6KrSq2Hy.js';
-export { b as BatchRequest, c as ErrorResponse, d as ExecuteRequest, e as LoadRequest, f as QueryRequest, g as TransactionRequest, t as toExecuteResponse } from '../protocol-6KrSq2Hy.js';
-import { S as Sirannon } from '../sirannon-DaQSyhbJ.js';
-import { B as BulkLoadDurability, S as ServerOptions, W as WSHandlerOptions } from '../server-options-1JHu8pid.js';
-import { W as WriteConcern, R as ReadConcern } from '../types-zhnRXrsb.js';
-import '../database-BY0L5Q2n.js';
-import '../types-C_D8IhpO.js';
-import '../types-CL6piSnD.js';
-import '../operation-registry-9DcvxcE5.js';
+import { T as TransactionStatement, Q as QueryResponse, E as ExecuteResponse, a as TransactionResponse, B as BatchResponse, L as LoadResponse, A as AckResponse } from '../protocol-rqANt-9Q.js';
+export { b as BatchRequest, c as ErrorResponse, d as ExecuteRequest, e as LoadRequest, f as QueryRequest, g as TransactionRequest, t as toExecuteResponse } from '../protocol-rqANt-9Q.js';
+import { S as Sirannon } from '../sirannon-CMhiJa5Y.js';
+import { B as BulkLoadDurability, S as ServerOptions, W as WSHandlerOptions } from '../server-options-Dab_Jvd_.js';
+import { W as WriteConcern, R as ReadConcern } from '../query-types-DL3LtPvY.js';
+import '../database-B5Qv1-cU.js';
+import '../types-rVZKnKN-.js';
+import '../types-CjhxcjhA.js';
+import '../types-BCejqzNA.js';
+import '../operation-registry-hlbhqu7q.js';
 
+/**
+ * Every message a client sends over the WebSocket. Each carries a `type` and a
+ * client-chosen `id` the reply echoes.
+ *
+ * @public
+ */
 type WSClientMessage = WSSubscribeMessage | WSUnsubscribeMessage | WSAckMessage | WSQueryMessage | WSExecuteMessage | WSTransactionMessage | WSBatchMessage | WSLoadMessage;
+/**
+ * Opens a change subscription on one or more tables, or a live query on a registered read.
+ *
+ * @public
+ */
 interface WSSubscribeMessage {
+    /** Names this message as a subscribe. */
     type: 'subscribe';
+    /** Client-chosen identifier the replies and change events echo. */
     id: string;
+    /** Table to subscribe to. */
     table?: string;
+    /** Several tables to subscribe to at once. */
     tables?: string[];
+    /** Narrows the subscription to rows whose columns equal these values. */
     filter?: Record<string, unknown>;
+    /** Name of a registered read, which opens a live query instead of a change subscription. */
     name?: string;
+    /** Arguments that registered read takes. */
     args?: Record<string, unknown>;
+    /** Digest of the operation registry the client built its live query against. */
     registryDigest?: string;
     /**
      * Highest `seq` the client has already processed. When present, the server
      * replays every retained change with a greater seq before delivering live
-     * events, so a reconnecting subscriber does not miss changes. Sent as a
+     * events so that a reconnecting subscriber does not miss changes. Sent as a
      * decimal string to preserve values beyond `Number.MAX_SAFE_INTEGER`.
      */
     sinceSeq?: string;
@@ -32,7 +52,9 @@ interface WSSubscribeMessage {
      * resync rather than replay foreign rows against it.
      */
     epoch?: string;
+    /** Identifies the device, which turns this into a device-sync subscription. */
     deviceId?: string;
+    /** Schema version the device's local database is at, which the server gates the stream on. */
     schemaVersion?: number;
     /**
      * Declares that this device stages pulled changes durably and
@@ -42,61 +64,138 @@ interface WSSubscribeMessage {
      */
     stagedStream?: boolean;
 }
+/**
+ * Ends a subscription.
+ *
+ * @public
+ */
 interface WSUnsubscribeMessage {
+    /** Names this message as an unsubscribe. */
     type: 'unsubscribe';
+    /** Identifier of the subscription to end. */
     id: string;
 }
+/**
+ * Acknowledges every change a device has stored up to a sequence.
+ *
+ * @public
+ */
 interface WSAckMessage {
+    /** Names this message as an acknowledgement. */
     type: 'ack';
+    /** Client-chosen identifier the reply echoes. */
     id: string;
+    /** Identifies the device acknowledging. */
     deviceId: string;
+    /** Highest sequence the device has stored, as a decimal string. */
     seq: string;
 }
+/**
+ * Runs a read, either as SQL or by the name of a registered read.
+ *
+ * @public
+ */
 interface WSQueryMessage {
+    /** Names this message as a read. */
     type: 'query';
+    /** Client-chosen identifier the reply echoes. */
     id: string;
+    /** The statement to run. The server refuses it unless it accepts SQL. */
     sql?: string;
+    /** Values bound to that statement, named or positional. */
     params?: Record<string, unknown> | unknown[];
+    /** Name of a registered read to run instead, which carries no SQL. */
     name?: string;
+    /** Arguments that registered read takes. */
     args?: Record<string, unknown>;
+    /** Currency this read requires. */
     readConcern?: ReadConcern;
 }
+/**
+ * Runs a write, either as SQL or by the name of a registered write.
+ *
+ * @public
+ */
 interface WSExecuteMessage {
+    /** Names this message as a write. */
     type: 'execute';
+    /** Client-chosen identifier the reply echoes. */
     id: string;
+    /** The statement to run. The server refuses it unless it accepts SQL. */
     sql?: string;
+    /** Values bound to that statement, named or positional. */
     params?: Record<string, unknown> | unknown[];
+    /** Name of a registered write to run instead, which carries no SQL. */
     name?: string;
+    /** Arguments that registered write takes. */
     args?: Record<string, unknown>;
+    /** Acknowledgements this write waits for. */
     writeConcern?: WriteConcern;
 }
 /**
  * Runs every statement in one server-side transaction and replies once with
  * all results. The client is never in the loop between statements, so the
  * single writer lock is held only for the duration of local execution.
+ *
+ * @public
  */
 interface WSTransactionMessage {
+    /** Names this message as a transaction. */
     type: 'transaction';
+    /** Client-chosen identifier the reply echoes. */
     id: string;
+    /** The statements to run, in order. */
     statements: TransactionStatement[];
+    /** Acknowledgements the transaction waits for. */
     writeConcern?: WriteConcern;
 }
+/**
+ * Applies one statement over many parameter sets in a single server-side transaction.
+ *
+ * @public
+ */
 interface WSBatchMessage {
+    /** Names this message as a batch. */
     type: 'batch';
+    /** Client-chosen identifier the reply echoes. */
     id: string;
+    /** The statement to run for each parameter set. */
     sql: string;
+    /** One parameter set per run. */
     paramsBatch: (Record<string, unknown> | unknown[])[];
+    /** Acknowledgements the batch waits for. */
     writeConcern?: WriteConcern;
 }
+/**
+ * Imports many rows at relaxed durability, which the server restores before it replies.
+ *
+ * @public
+ */
 interface WSLoadMessage {
+    /** Names this message as a load. */
     type: 'load';
+    /** Client-chosen identifier the reply echoes. */
     id: string;
+    /** The statement to run for each parameter set. */
     sql: string;
+    /** One parameter set per row. */
     paramsBatch: (Record<string, unknown> | unknown[])[];
+    /** Durability in force while the load runs. Default: 'off'. */
     durability?: BulkLoadDurability;
+    /** Whether this load ends with a checkpoint. */
     checkpoint?: boolean;
 }
+/**
+ * Every message the server sends over the WebSocket.
+ *
+ * @public
+ */
 type WSServerMessage = WSSubscribedMessage | WSUnsubscribedMessage | WSChangeMessage | WSChangesMessage | WSLiveMessage | WSResultMessage | WSErrorMessage;
+/**
+ * One edit to a live query's result set, as a position and the row at it.
+ *
+ * @public
+ */
 type WSLiveOp = {
     op: 'insert';
     index: number;
@@ -109,15 +208,32 @@ type WSLiveOp = {
     op: 'delete';
     index: number;
 };
+/**
+ * Carries a live query's new state: the edits that move it, a full replacement, or notice that a re-read has started.
+ *
+ * @public
+ */
 interface WSLiveMessage {
+    /** Names this message as a live-query update. */
     type: 'live';
+    /** Identifier of the subscription this update belongs to. */
     id: string;
+    /** The edits that move the result set to its new state. */
     ops?: WSLiveOp[];
+    /** A complete replacement result set. */
     rows?: unknown[];
+    /** Set while the server re-reads the query. */
     revalidating?: boolean;
 }
+/**
+ * Confirms a subscription opened, and states the cursor and sequence space it streams from.
+ *
+ * @public
+ */
 interface WSSubscribedMessage {
+    /** Names this message as a subscription confirmation. */
     type: 'subscribed';
+    /** Identifier of the subscription that opened. */
     id: string;
     /**
      * How far a device may run ahead of its acknowledged cursor before the
@@ -126,7 +242,7 @@ interface WSSubscribedMessage {
     maxUnacknowledgedChanges?: number;
     /**
      * The seq the subscription is live from. A client that has not yet seen any
-     * change adopts this as its resume cursor, so a reconnect during an idle
+     * change adopts this as its resume cursor so that a reconnect during an idle
      * spell still replays what it missed instead of silently skipping it.
      */
     seq?: string;
@@ -138,58 +254,119 @@ interface WSSubscribedMessage {
     resync?: boolean;
     /**
      * Identifies the sequence space this subscription streams from. The client
-     * stores it and echoes it when resuming, so a cursor carried to a different
+     * stores it and echoes it when resuming so that a cursor carried to a different
      * database forces a resync instead of a silent replay of unrelated rows.
      */
     epoch?: string;
+    /** First result set of a live query, sent when the subscription named a registered read. */
     rows?: unknown[];
 }
+/**
+ * Confirms a subscription ended.
+ *
+ * @public
+ */
 interface WSUnsubscribedMessage {
+    /** Names this message as an unsubscribe confirmation. */
     type: 'unsubscribed';
+    /** Identifier of the subscription that ended. */
     id: string;
 }
+/**
+ * One change event as it crosses the wire, with sequences as decimal strings
+ * so a value beyond the safe integer range survives JSON.
+ *
+ * @public
+ */
 interface WSWireChangeEvent {
+    /** Whether the row was inserted, updated, or deleted. */
     type: 'insert' | 'update' | 'delete';
+    /** Table the row belongs to. */
     table: string;
+    /** The row as it stands after the change. */
     row: Record<string, unknown>;
+    /** The row as it stood before an update or a delete. */
     oldRow?: Record<string, unknown>;
+    /** Position of this change in the database's change log, as a decimal string. */
     seq: string;
+    /** Milliseconds since the Unix epoch, taken when the change was recorded. */
     timestamp: number;
+    /** Hybrid logical clock stamp the writing node gave this change. */
     hlc?: string;
+    /** Identifier of the node that authored the change. */
     origin?: string;
+    /** Primary key of the changed row, encoded as a string. */
     rowId?: string;
+    /** Identifier of the transaction that produced this change. */
     txId?: string;
+    /** Set on the last change of a transaction. */
     txEnd?: boolean;
 }
+/**
+ * Carries one change event to a subscriber.
+ *
+ * @public
+ */
 interface WSChangeMessage {
+    /** Names this message as a single change event. */
     type: 'change';
+    /** Identifier of the subscription this change belongs to. */
     id: string;
+    /** The change itself. */
     event: WSWireChangeEvent;
 }
 /**
  * Several change events in one frame, in ascending seq order. Sent only on
  * a device subscription that requested `stagedStream`; the events carry the
  * same fields as a `change` frame's event.
+ *
+ * @public
  */
 interface WSChangesMessage {
+    /** Names this message as a run of change events. */
     type: 'changes';
+    /** Identifier of the subscription these changes belong to. */
     id: string;
+    /** The changes, in ascending sequence order. */
     events: WSWireChangeEvent[];
 }
+/**
+ * Replies to a read, write, transaction, batch, load, or acknowledgement.
+ *
+ * @public
+ */
 interface WSResultMessage {
+    /** Names this message as a reply to a read, write, transaction, batch, load, or acknowledgement. */
     type: 'result';
+    /** Identifier the request carried. */
     id: string;
+    /** The reply body, whose shape follows the request that produced it. */
     data: QueryResponse | ExecuteResponse | TransactionResponse | BatchResponse | LoadResponse | AckResponse;
 }
+/**
+ * Reports that a request failed.
+ *
+ * @public
+ */
 interface WSErrorMessage {
+    /** Names this message as a failure. */
     type: 'error';
+    /** Identifier the request carried. */
     id: string;
+    /** Machine-readable code and human-readable message. */
     error: {
         code: string;
         message: string;
     };
 }
 
+/**
+ * @public
+ *
+ * Serves a `Sirannon` database registry over HTTP and WebSocket.
+ *
+ * Build one with {@link createServer}, then call {@link SirannonServer.listen}.
+ */
 declare class SirannonServer<Identity = unknown> {
     private app;
     private listenSocket;
@@ -209,8 +386,19 @@ declare class SirannonServer<Identity = unknown> {
     private readonly maxBodyBytes;
     private readonly maxWsBackpressureBytes;
     constructor(sirannon: Sirannon, options?: ServerOptions<Identity>);
+    /**
+     * Binds the configured host and port and starts serving.
+     *
+     * @throws When the port is already in use.
+     */
     listen(): Promise<void>;
+    /**
+     * Stops serving and closes every open connection.
+     */
     close(): Promise<void>;
+    /**
+     * Port the server bound to, which is the resolved port when you asked for 0.
+     */
     get listeningPort(): number;
     private registerRoutes;
     private registerWebSocketRoute;
@@ -219,6 +407,15 @@ declare class SirannonServer<Identity = unknown> {
     private wrapOperationRoute;
     private wrapDbGetRoute;
 }
+/**
+ * @public
+ *
+ * Builds a server over a database registry.
+ *
+ * @param sirannon - The registry whose databases the server exposes.
+ * @param options - Address, cross-origin rules, size limits, authentication, registered operations, and whether the server accepts SQL.
+ * @returns The server, ready to listen.
+ */
 declare function createServer<Identity = unknown>(sirannon: Sirannon, options?: ServerOptions<Identity>): SirannonServer<Identity>;
 
 /**
@@ -232,11 +429,27 @@ declare function createServer<Identity = unknown>(sirannon: Sirannon, options?:
  *   the request as answered.
  */
 type WSSendOutcome = 'sent' | 'buffered' | 'dropped';
+/**
+ * One open WebSocket, as the handler sends over it.
+ *
+ * @internal
+ */
 interface WSConnection {
+    /**
+     * Sends one frame and reports whether it went out, was buffered, or was dropped.
+     */
     send(data: string): WSSendOutcome;
+    /**
+     * Closes the connection with a code and reason.
+     */
     close(code?: number, reason?: string): void;
 }
 
+/**
+ * Serves the WebSocket protocol for one server: queries, writes, change subscriptions, and live queries.
+ *
+ * @internal
+ */
 declare class WSHandler<Identity = unknown> {
     private readonly sirannon;
     private readonly maxPayloadLength;
@@ -272,6 +485,11 @@ declare class WSHandler<Identity = unknown> {
     private sendChange;
     private sendText;
 }
+/**
+ * Builds the WebSocket handler a server routes its upgrades and messages through.
+ *
+ * @internal
+ */
 declare function createWSHandler<Identity = unknown>(sirannon: Sirannon, options?: WSHandlerOptions<Identity>): WSHandler<Identity>;
 
 export { BatchResponse, ExecuteResponse, LoadResponse, QueryResponse, SirannonServer, TransactionResponse, TransactionStatement, type WSBatchMessage, type WSChangeMessage, type WSClientMessage, type WSConnection, type WSErrorMessage, type WSExecuteMessage, WSHandler, type WSLoadMessage, type WSQueryMessage, type WSResultMessage, type WSServerMessage, type WSSubscribeMessage, type WSSubscribedMessage, type WSTransactionMessage, type WSUnsubscribeMessage, type WSUnsubscribedMessage, createServer, createWSHandler };

package/dist/server/index.mjs

@@ -1,13 +1,13 @@
-import { dumpSchema, tablesInFkOrder, dumpTablePages } from '../chunk-OQVZBEBY.mjs';
-import { ChangeTracker, SubscriptionManager, ensureCdcEpoch, migrationChecksum, needsResync, filteredChange, TransactionGrouper, isBulkLoadDurability, PrimedSubscription } from '../chunk-H6PIVVDN.mjs';
-import { SEQ_STRING_RE, highestMigrationVersion, selectCountTableRows, selectTableExists, selectAppliedMigrations, PkResolver, ensureDeviceCursorsTable, upsertDeviceCursor, selectMaxChangeSeq, canonicaliseForChecksum, selectDeviceCursors, selectMinForeignChangeSeqSql, IDENTIFIER_RE, deleteDeviceCursorsUpdatedBefore } from '../chunk-NVQS53NT.mjs';
-import '../chunk-5NOIGN5Y.mjs';
-import { encodeTaggedValues, MIGRATIONS_TABLE, decodeTaggedValues, encodeWireRowsInPlace, CHANGES_TABLE, DEVICE_CURSORS_TABLE, INTERNAL_TABLE_PREFIX } from '../chunk-D7LAYTKN.mjs';
+import { dumpSchema, tablesInFkOrder, dumpTablePages } from '../chunk-XF2HH5E6.mjs';
+import { ChangeTracker, SubscriptionManager, ensureCdcEpoch, migrationChecksum, needsResync, filteredChange, TransactionGrouper, isBulkLoadDurability, PrimedSubscription } from '../chunk-CCZK6LCB.mjs';
+import { SEQ_STRING_RE, highestMigrationVersion, selectCountTableRows, selectTableExists, selectAppliedMigrations, PkResolver, ensureDeviceCursorsTable, upsertDeviceCursor, selectMaxChangeSeq, canonicaliseForChecksum, selectDeviceCursors, selectMinForeignChangeSeqSql, IDENTIFIER_RE, deleteDeviceCursorsUpdatedBefore } from '../chunk-7FQRQH5Z.mjs';
+import '../chunk-2QLXDHAP.mjs';
+import { encodeTaggedValues, MIGRATIONS_TABLE, decodeTaggedValues, encodeWireRowsInPlace, CHANGES_TABLE, DEVICE_CURSORS_TABLE, INTERNAL_TABLE_PREFIX } from '../chunk-7R4ER4FB.mjs';
 import { createOperationSource, operationRegistryDigest, findRead, isRefusal, resolveArguments, findWrite } from '../chunk-TUD5CJ76.mjs';
 import '../chunk-GVCNMPOS.mjs';
-import '../chunk-LFZ37BSX.mjs';
-import { SQLITE_USER_VERSION_MAX } from '../chunk-67M7KAH6.mjs';
-import { SirannonError, WriteOverloadError } from '../chunk-UC3SCMIN.mjs';
+import '../chunk-OUSWVNWT.mjs';
+import { SQLITE_USER_VERSION_MAX } from '../chunk-IWGIYDMZ.mjs';
+import { SirannonError, WriteOverloadError } from '../chunk-PBRXXISQ.mjs';
 import uWS from 'uWebSockets.js';
 import { createHash } from 'crypto';
 
@@ -1165,6 +1165,49 @@ function handleSnapshotPage(sirannon) {
   };
 }
 
+// src/server/limits.ts
+var DEFAULT_MAX_BODY_BYTES = 1048576;
+var DEFAULT_WS_BACKPRESSURE_BYTES = 16 * 1048576;
+var UWS_MAX_LIMIT_BYTES = 4294967295;
+function resolveMaxBodyBytes(value) {
+  if (value === void 0) return DEFAULT_MAX_BODY_BYTES;
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    throw new SirannonError(
+      "ServerOptions.maxBodyBytes must be a positive integer number of bytes",
+      "INVALID_MAX_BODY_BYTES"
+    );
+  }
+  if (value > UWS_MAX_LIMIT_BYTES) {
+    throw new SirannonError(
+      `ServerOptions.maxBodyBytes must be at most ${UWS_MAX_LIMIT_BYTES} bytes; uWebSockets.js stores the limit as an unsigned 32-bit integer and would silently wrap a larger value modulo 2^32`,
+      "INVALID_MAX_BODY_BYTES"
+    );
+  }
+  return value;
+}
+function resolveWsBackpressure(value, maxBodyBytes) {
+  const resolved = value ?? Math.max(DEFAULT_WS_BACKPRESSURE_BYTES, maxBodyBytes);
+  if (typeof resolved !== "number" || !Number.isInteger(resolved) || resolved <= 0) {
+    throw new SirannonError(
+      "ServerOptions.maxWebSocketBackpressureBytes must be a positive integer number of bytes",
+      "INVALID_WS_BACKPRESSURE"
+    );
+  }
+  if (resolved > UWS_MAX_LIMIT_BYTES) {
+    throw new SirannonError(
+      `ServerOptions.maxWebSocketBackpressureBytes must be at most ${UWS_MAX_LIMIT_BYTES} bytes; uWebSockets.js stores the limit as an unsigned 32-bit integer and would silently wrap a larger value modulo 2^32`,
+      "INVALID_WS_BACKPRESSURE"
+    );
+  }
+  if (resolved < maxBodyBytes) {
+    throw new SirannonError(
+      "ServerOptions.maxWebSocketBackpressureBytes must be at least maxBodyBytes so a single frame fits",
+      "INVALID_WS_BACKPRESSURE"
+    );
+  }
+  return resolved;
+}
+
 // src/core/ws-handshake.ts
 var SIRANNON_WS_SUBPROTOCOL = "sirannon.v1";
 var WS_CLOSE_UNAUTHENTICATED = 4401;
@@ -1736,7 +1779,7 @@ var DeviceChangeStream = class {
     }
   }
   /**
-   * Rejoins the live feed. Runs synchronously right after a log read, so no
+   * Rejoins the live feed. Runs synchronously right after a log read so that no
    * poller tick can dispatch between the caught-up check and the mode flip.
    * The grouper survives the transition: the event it holds is released by
    * the boundary flush when the poller stopped at a transaction boundary,
@@ -2811,47 +2854,6 @@ var SQL_ROUTES = ["/db/:id/query", "/db/:id/execute", "/db/:id/transaction", "/d
 function refuseSql(res) {
   sendError(res, 403, "SQL_NOT_ACCEPTED", SQL_NOT_ACCEPTED_MESSAGE);
 }
-var DEFAULT_MAX_BODY_BYTES = 1048576;
-var DEFAULT_WS_BACKPRESSURE_BYTES = 16 * 1048576;
-var UWS_MAX_LIMIT_BYTES = 4294967295;
-function resolveMaxBodyBytes(value) {
-  if (value === void 0) return DEFAULT_MAX_BODY_BYTES;
-  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
-    throw new SirannonError(
-      "ServerOptions.maxBodyBytes must be a positive integer number of bytes",
-      "INVALID_MAX_BODY_BYTES"
-    );
-  }
-  if (value > UWS_MAX_LIMIT_BYTES) {
-    throw new SirannonError(
-      `ServerOptions.maxBodyBytes must be at most ${UWS_MAX_LIMIT_BYTES} bytes; uWebSockets.js stores the limit as an unsigned 32-bit integer and would silently wrap a larger value modulo 2^32`,
-      "INVALID_MAX_BODY_BYTES"
-    );
-  }
-  return value;
-}
-function resolveWsBackpressure(value, maxBodyBytes) {
-  const resolved = value ?? Math.max(DEFAULT_WS_BACKPRESSURE_BYTES, maxBodyBytes);
-  if (typeof resolved !== "number" || !Number.isInteger(resolved) || resolved <= 0) {
-    throw new SirannonError(
-      "ServerOptions.maxWebSocketBackpressureBytes must be a positive integer number of bytes",
-      "INVALID_WS_BACKPRESSURE"
-    );
-  }
-  if (resolved > UWS_MAX_LIMIT_BYTES) {
-    throw new SirannonError(
-      `ServerOptions.maxWebSocketBackpressureBytes must be at most ${UWS_MAX_LIMIT_BYTES} bytes; uWebSockets.js stores the limit as an unsigned 32-bit integer and would silently wrap a larger value modulo 2^32`,
-      "INVALID_WS_BACKPRESSURE"
-    );
-  }
-  if (resolved < maxBodyBytes) {
-    throw new SirannonError(
-      "ServerOptions.maxWebSocketBackpressureBytes must be at least maxBodyBytes so a single frame fits",
-      "INVALID_WS_BACKPRESSURE"
-    );
-  }
-  return resolved;
-}
 var SirannonServer = class {
   app;
   listenSocket = null;
@@ -2897,6 +2899,11 @@ var SirannonServer = class {
     this.app = uWS.App();
     this.registerRoutes();
   }
+  /**
+   * Binds the configured host and port and starts serving.
+   *
+   * @throws When the port is already in use.
+   */
   listen() {
     return new Promise((resolve, reject) => {
       this.app.listen(this.host, this.port, (socket) => {
@@ -2909,6 +2916,9 @@ var SirannonServer = class {
       });
     });
   }
+  /**
+   * Stops serving and closes every open connection.
+   */
   async close() {
     try {
       await this.wsHandler.close();
@@ -2919,6 +2929,9 @@ var SirannonServer = class {
       }
     }
   }
+  /**
+   * Port the server bound to, which is the resolved port when you asked for 0.
+   */
   get listeningPort() {
     if (!this.listenSocket) return -1;
     return uWS.us_socket_local_port(this.listenSocket);