reflectdb 0.1.0

package/dist/cjs/transport/bun-ws.cjs

@@ -0,0 +1,244 @@
+var import_node_module = require("node:module");
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/core/types.ts
+var exports_types = {};
+__export(exports_types, {
+  reasonFromError: () => reasonFromError,
+  isErrorReason: () => isErrorReason,
+  TransportSendError: () => TransportSendError,
+  TOMBSTONE_RETENTION_MS: () => TOMBSTONE_RETENTION_MS,
+  SUPPORTED_PROTOCOL_VERSIONS: () => SUPPORTED_PROTOCOL_VERSIONS,
+  SERVER_TOMBSTONE_RETENTION_MS: () => SERVER_TOMBSTONE_RETENTION_MS,
+  PROTOCOL_VERSION: () => PROTOCOL_VERSION,
+  MutationError: () => MutationError,
+  MAX_CLOCK_DRIFT_MS: () => MAX_CLOCK_DRIFT_MS,
+  MAX_BATCH_SIZE: () => MAX_BATCH_SIZE
+});
+function isErrorReason(value) {
+  return typeof value === "string" && VALID_ERROR_REASONS.has(value);
+}
+function reasonFromError(err) {
+  if (err instanceof MutationError && isErrorReason(err.reason)) {
+    return err.reason;
+  }
+  return "server_error";
+}
+var TransportSendError, PROTOCOL_VERSION = 1, SUPPORTED_PROTOCOL_VERSIONS, MAX_CLOCK_DRIFT_MS, MAX_BATCH_SIZE = 100, TOMBSTONE_RETENTION_MS, SERVER_TOMBSTONE_RETENTION_MS, MutationError, VALID_ERROR_REASONS;
+var init_types = __esm(() => {
+  TransportSendError = class TransportSendError extends Error {
+    clientId;
+    cause;
+    constructor(clientId, message, cause) {
+      super(message);
+      this.clientId = clientId;
+      this.cause = cause;
+      this.name = "TransportSendError";
+    }
+  };
+  SUPPORTED_PROTOCOL_VERSIONS = [1];
+  MAX_CLOCK_DRIFT_MS = 5 * 60 * 1000;
+  TOMBSTONE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+  SERVER_TOMBSTONE_RETENTION_MS = 90 * 24 * 60 * 60 * 1000;
+  MutationError = class MutationError extends Error {
+    reason;
+    constructor(reason, message) {
+      super(message ?? reason);
+      this.reason = reason;
+    }
+  };
+  VALID_ERROR_REASONS = new Set([
+    "outside_shape",
+    "readonly_query",
+    "rate_limited",
+    "buffer_full",
+    "server_conflict",
+    "custom_conflict",
+    "merge_stale",
+    "clock_drift",
+    "replay",
+    "batch_too_large",
+    "schema_outdated",
+    "auth_revoked",
+    "compacted",
+    "mutation_rejected",
+    "server_error",
+    "unknown_query"
+  ]);
+});
+
+// src/transport/bun-ws.ts
+init_types();
+var exports_bun_ws = {};
+__export(exports_bun_ws, {
+  createBunWsServerTransport: () => createBunWsServerTransport
+});
+module.exports = __toCommonJS(exports_bun_ws);
+function trySend(clientId, ws, data, maxBufferedBytes) {
+  if (ws.readyState !== undefined && ws.readyState !== 1) {
+    throw new TransportSendError(clientId, `bun-ws not open (readyState=${ws.readyState})`);
+  }
+  if (maxBufferedBytes > 0 && typeof ws.getBufferedAmount === "function") {
+    const buffered = ws.getBufferedAmount();
+    if (buffered > maxBufferedBytes) {
+      throw new TransportSendError(clientId, `bun-ws outbound buffer over limit (${buffered} > ${maxBufferedBytes})`);
+    }
+  }
+  try {
+    ws.send(data);
+  } catch (err) {
+    throw new TransportSendError(clientId, `bun-ws send failed: ${err instanceof Error ? err.message : String(err)}`, err);
+  }
+}
+function createBunWsServerTransport(cfg = {}) {
+  const clients = new Map;
+  const lastSeen = new Map;
+  const maxMessageBytes = cfg.maxMessageBytes ?? 1e6;
+  const pingIntervalMs = cfg.pingIntervalMs ?? 30000;
+  const pongTimeoutMs = cfg.pongTimeoutMs ?? pingIntervalMs * 2;
+  const maxBufferedBytes = cfg.maxBufferedBytes ?? 8000000;
+  let messageHandler = null;
+  let connectHandler = null;
+  let disconnectHandler = null;
+  let heartbeatTimer = null;
+  if (pingIntervalMs > 0) {
+    heartbeatTimer = setInterval(() => {
+      const now = Date.now();
+      for (const [id, ws] of clients) {
+        const last = lastSeen.get(id) ?? now;
+        if (now - last > pongTimeoutMs) {
+          try {
+            ws.close();
+          } catch {}
+          continue;
+        }
+        try {
+          ws.ping?.();
+        } catch {}
+      }
+    }, pingIntervalMs);
+    if (typeof heartbeatTimer.unref === "function") {
+      heartbeatTimer.unref();
+    }
+  }
+  const websocket = {
+    open(ws) {
+      const { id, req } = ws.data;
+      clients.set(id, ws);
+      lastSeen.set(id, Date.now());
+      connectHandler?.(id, req ?? new Request("https://ws-connect"));
+    },
+    message(ws, data) {
+      const { id } = ws.data;
+      lastSeen.set(id, Date.now());
+      const byteLen = typeof data === "string" ? typeof Buffer !== "undefined" ? Buffer.byteLength(data, "utf8") : new Blob([data]).size : data.length;
+      if (byteLen > maxMessageBytes) {
+        console.warn(`[reflectdb] bun-ws: message from ${id} exceeds ${maxMessageBytes} bytes (${byteLen}), closing`);
+        try {
+          ws.close();
+        } catch {}
+        return;
+      }
+      const raw = typeof data === "string" ? data : new TextDecoder().decode(data);
+      try {
+        messageHandler?.(id, JSON.parse(raw));
+      } catch (err) {
+        console.warn(`[reflectdb] bun-ws: malformed message from ${id}:`, err instanceof Error ? err.message : String(err));
+      }
+    },
+    close(ws) {
+      const { id } = ws.data;
+      clients.delete(id);
+      lastSeen.delete(id);
+      disconnectHandler?.(id);
+    },
+    pong(ws) {
+      lastSeen.set(ws.data.id, Date.now());
+    }
+  };
+  const transport = {
+    async send(clientId, message) {
+      const ws = clients.get(clientId);
+      if (!ws) {
+        throw new TransportSendError(clientId, "no socket registered for client");
+      }
+      trySend(clientId, ws, JSON.stringify(message), maxBufferedBytes);
+    },
+    async broadcast(_roomId, message, exclude) {
+      const data = JSON.stringify(message);
+      for (const [id, ws] of clients) {
+        if (id === exclude)
+          continue;
+        try {
+          trySend(id, ws, data, maxBufferedBytes);
+        } catch (err) {
+          console.warn("[reflectdb] bun-ws broadcast skipped a client:", err instanceof Error ? err.message : err);
+        }
+      }
+    },
+    disconnect(clientId) {
+      const ws = clients.get(clientId);
+      if (!ws)
+        return;
+      try {
+        ws.close();
+      } catch {}
+      clients.delete(clientId);
+    },
+    onMessage(handler) {
+      messageHandler = handler;
+    },
+    onConnect(handler) {
+      connectHandler = handler;
+    },
+    onDisconnect(handler) {
+      disconnectHandler = handler;
+    },
+    async close() {
+      if (heartbeatTimer)
+        clearInterval(heartbeatTimer);
+      for (const ws of clients.values())
+        ws.close();
+      clients.clear();
+      lastSeen.clear();
+    }
+  };
+  return { transport, websocket };
+}

package/dist/cjs/transport/bun-ws.d.cts

@@ -0,0 +1,215 @@
+type OpType = "insert" | "update" | "delete";
+type ErrorReason = "outside_shape" | "readonly_query" | "rate_limited" | "buffer_full" | "server_conflict" | "custom_conflict" | "merge_stale" | "clock_drift" | "replay" | "batch_too_large" | "schema_outdated" | "auth_revoked" | "compacted" | "mutation_rejected" | "server_error" | "unknown_query";
+interface HelloMessage {
+	type: "hello";
+	/** Highest protocol version the client prefers. Retained for back-compat. */
+	protocolVersion: number;
+	/** All versions the client can speak. Omit for legacy single-version clients. */
+	supportedVersions?: readonly number[];
+	clientId: string;
+	token: string;
+}
+interface BootstrapMessage {
+	type: "bootstrap";
+	syncParams?: Record<string, Record<string, unknown>>;
+}
+interface ResumeMessage {
+	type: "resume";
+	since: string;
+}
+interface OpsMessage {
+	type: "ops";
+	ops: ClientOp[];
+	token: string;
+}
+interface ClientOp {
+	id: string;
+	table: string;
+	op: OpType;
+	rowId: string;
+	payload: Record<string, unknown> | null;
+	hlc: string;
+	batchId?: string;
+	batchSize?: number;
+	batchSeq?: number;
+}
+interface SyncDeclareMessage {
+	type: "sync_declare";
+	table: string;
+	params?: Record<string, unknown>;
+	window?: number;
+}
+interface LoadMoreMessage {
+	type: "load_more";
+	table: string;
+	count: number;
+}
+interface UnsyncMessage {
+	type: "unsync";
+	table: string;
+}
+interface AuthMessage {
+	type: "auth";
+	token: string;
+}
+interface EphemeralMessage {
+	type: "ephemeral";
+	key: string;
+	userId: string;
+	data: Record<string, unknown>;
+	ttlMs?: number;
+}
+interface HelloAckMessage {
+	type: "hello_ack";
+	protocolVersion: number;
+	serverId: string;
+}
+interface HelloRejectMessage {
+	type: "hello_reject";
+	reason: string;
+	supported: number[];
+}
+interface SnapshotMessage {
+	type: "snapshot";
+	table: string;
+	rows: Record<string, unknown>[];
+	colClocks: Record<string, Record<string, string>>;
+	append?: boolean;
+	totalCount?: number;
+	/**
+	* Primary key column name for this table. Self-contained per message so the
+	* client doesn't depend on `bootstrap_complete.tableMeta` arriving first.
+	* When omitted (older servers), the client falls back to tableMeta, then "id".
+	*/
+	pk?: string;
+}
+interface BootstrapCompleteMessage {
+	type: "bootstrap_complete";
+	serverHlc: string;
+	tableMeta: Record<string, TableMeta>;
+}
+interface TableMeta {
+	serverSet: string[];
+	readonly: string[];
+	broadcast: "consistent" | "eager" | "eager-durable";
+	/** Primary key column name. Defaults to "id" when omitted (older servers). */
+	pk?: string;
+}
+interface DeltaMessage {
+	type: "delta";
+	table: string;
+	op: OpType;
+	rowId: string;
+	payload: Record<string, unknown> | null;
+	hlc: string;
+	colClocks?: Record<string, string>;
+}
+interface AckMessage {
+	type: "ack";
+	opIds: string[];
+}
+interface RejectMessage {
+	type: "reject";
+	opId?: string;
+	batchId?: string;
+	reason: ErrorReason;
+	serverRow?: Record<string, unknown>;
+}
+interface ResumeCompleteMessage {
+	type: "resume_complete";
+	serverHlc: string;
+}
+interface ResumeRejectedMessage {
+	type: "resume_rejected";
+	reason: string;
+	serverHlc: string;
+}
+interface ShapeChangedMessage {
+	type: "shape_changed";
+	table: string;
+	reason: "auth_changed" | "params_changed" | "server_policy";
+}
+interface DisconnectMessage {
+	type: "disconnect";
+	reason: string;
+}
+interface ReauthMessage {
+	type: "reauth";
+}
+interface CountChangedMessage {
+	type: "count_changed";
+	table: string;
+	totalCount: number;
+}
+interface EphemeralEvent {
+	type: "ephemeral";
+	key: string;
+	clientId: string;
+	userId: string;
+	data: Record<string, unknown>;
+	ttlMs?: number;
+}
+type ClientMessage = HelloMessage | BootstrapMessage | ResumeMessage | OpsMessage | SyncDeclareMessage | LoadMoreMessage | UnsyncMessage | AuthMessage | EphemeralMessage;
+type ServerMessage = HelloAckMessage | HelloRejectMessage | SnapshotMessage | BootstrapCompleteMessage | DeltaMessage | AckMessage | RejectMessage | ResumeCompleteMessage | ResumeRejectedMessage | ShapeChangedMessage | DisconnectMessage | ReauthMessage | EphemeralEvent | CountChangedMessage;
+interface ServerTransport {
+	/**
+	* Deliver a message to one client.
+	*
+	* MUST reject (ideally with `TransportSendError`) when the frame could not
+	* be handed to the peer — unknown/closed socket, full outbound queue, or a
+	* throw from the underlying socket. Resolving on a dropped frame makes the
+	* broadcast engine commit result-cache state the client never received.
+	*/
+	send(clientId: string, message: ServerMessage): Promise<void>;
+	broadcast(roomId: string, message: ServerMessage, exclude?: string): Promise<void>;
+	onMessage(handler: (clientId: string, message: ClientMessage) => void): void;
+	onConnect(handler: (clientId: string, req: Request) => void): void;
+	onDisconnect(handler: (clientId: string) => void): void;
+	close(): Promise<void>;
+	/**
+	* Force-disconnect a single client. Optional — if absent, the handler relies
+	* on the client honoring a `disconnect` server-message. Required for any
+	* transport that carries authentication state, since an adversarial client
+	* can otherwise ignore the message and continue using a revoked session.
+	*/
+	disconnect?(clientId: string): Promise<void> | void;
+}
+interface BunWsTransportData {
+	id: string;
+	/** Original upgrade request — forwarded to the onConnect handler if provided */
+	req?: Request;
+}
+/** Bun's ServerWebSocket shape (subset used by this transport) */
+interface BunServerWebSocket<T> {
+	data: T;
+	send(data: string): void;
+	ping?: (data?: string) => void;
+	close(): void;
+	readyState?: number;
+	/** Bun exposes queued-but-unflushed bytes here; used for backpressure. */
+	getBufferedAmount?: () => number;
+}
+interface BunWsServerConfig {
+	/** Max inbound message bytes before the connection is closed. Default: 1 MB. */
+	maxMessageBytes?: number;
+	/** Ping interval in ms. 0 disables. Default: 30_000. */
+	pingIntervalMs?: number;
+	/** Close a connection if no message/pong seen in this window. Default: 2× pingInterval. */
+	pongTimeoutMs?: number;
+	/**
+	* Outbound backpressure ceiling in bytes. `send` rejects once the socket has
+	* more than this queued, so a slow reader can't grow server memory without
+	* bound. 0 disables. Default: 8 MB.
+	*/
+	maxBufferedBytes?: number;
+}
+declare function createBunWsServerTransport(cfg?: BunWsServerConfig): {
+	transport: ServerTransport;
+	websocket: {
+		open(ws: BunServerWebSocket<BunWsTransportData>): void;
+		message(ws: BunServerWebSocket<BunWsTransportData>, data: string | Uint8Array): void;
+		close(ws: BunServerWebSocket<BunWsTransportData>): void;
+		pong?(ws: BunServerWebSocket<BunWsTransportData>): void;
+	};
+};
+export { createBunWsServerTransport, BunWsTransportData, BunWsServerConfig };