reflectdb 0.1.0

package/dist/cjs/transport/ws.cjs

@@ -0,0 +1,330 @@
+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/ws.ts
+init_types();
+var exports_ws = {};
+__export(exports_ws, {
+  isOriginAllowed: () => isOriginAllowed,
+  createWsServerTransport: () => createWsServerTransport,
+  createWsClientTransport: () => createWsClientTransport
+});
+module.exports = __toCommonJS(exports_ws);
+function trySend(clientId, ws, data, maxBufferedBytes) {
+  const sock = ws;
+  const rs = sock.readyState;
+  if (rs !== undefined && rs !== 1) {
+    throw new TransportSendError(clientId, `ws not open (readyState=${rs})`);
+  }
+  if (maxBufferedBytes > 0 && (sock.bufferedAmount ?? 0) > maxBufferedBytes) {
+    throw new TransportSendError(clientId, `ws outbound buffer over limit (${sock.bufferedAmount} > ${maxBufferedBytes})`);
+  }
+  try {
+    ws.send(data);
+  } catch (err) {
+    throw new TransportSendError(clientId, `ws send failed: ${err instanceof Error ? err.message : String(err)}`, err);
+  }
+}
+function isOriginAllowed(req, allowed) {
+  const origin = req.headers.get("origin");
+  if (typeof allowed === "function")
+    return allowed(origin);
+  if (allowed.includes("*"))
+    return true;
+  if (!origin)
+    return false;
+  return allowed.includes(origin);
+}
+function createWsServerTransport(cfg = {}) {
+  const clients = new Map;
+  const rooms = 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 heartbeatTimer = null;
+  if (pingIntervalMs > 0) {
+    heartbeatTimer = setInterval(() => {
+      const now = Date.now();
+      for (const [clientId, ws] of clients) {
+        const last = lastSeen.get(clientId) ?? now;
+        if (now - last > pongTimeoutMs) {
+          try {
+            ws.close();
+          } catch {}
+          continue;
+        }
+        try {
+          ws.ping?.();
+        } catch {}
+      }
+    }, pingIntervalMs);
+    if (typeof heartbeatTimer.unref === "function") {
+      heartbeatTimer.unref();
+    }
+  }
+  let messageHandler = null;
+  let connectHandler = null;
+  let disconnectHandler = null;
+  return {
+    handleOpen(clientId, ws) {
+      clients.set(clientId, ws);
+      lastSeen.set(clientId, Date.now());
+      connectHandler?.(clientId, new Request("https://ws-connect"));
+    },
+    handleMessage(clientId, data) {
+      lastSeen.set(clientId, Date.now());
+      const byteLen = typeof Buffer !== "undefined" ? Buffer.byteLength(data, "utf8") : new Blob([data]).size;
+      if (byteLen > maxMessageBytes) {
+        console.warn(`[reflectdb] WS server: message from ${clientId} exceeds ${maxMessageBytes} bytes (${byteLen}), closing`);
+        const ws = clients.get(clientId);
+        try {
+          ws?.close();
+        } catch {}
+        return;
+      }
+      try {
+        const message = JSON.parse(data);
+        messageHandler?.(clientId, message);
+      } catch (err) {
+        console.warn(`[reflectdb] WS server: malformed message from ${clientId}:`, err instanceof Error ? err.message : String(err));
+      }
+    },
+    handleClose(clientId) {
+      clients.delete(clientId);
+      lastSeen.delete(clientId);
+      for (const members of rooms.values()) {
+        members.delete(clientId);
+      }
+      disconnectHandler?.(clientId);
+    },
+    handlePong(clientId) {
+      lastSeen.set(clientId, Date.now());
+    },
+    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 members = rooms.get(roomId);
+      if (!members)
+        return;
+      const data = JSON.stringify(message);
+      for (const clientId of members) {
+        if (clientId === exclude)
+          continue;
+        const ws = clients.get(clientId);
+        if (!ws)
+          continue;
+        try {
+          trySend(clientId, ws, data, maxBufferedBytes);
+        } catch (err) {
+          console.warn("[reflectdb] 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();
+      rooms.clear();
+    }
+  };
+}
+function createWsClientTransport(config) {
+  let ws = null;
+  let handler = null;
+  let intentionalClose = false;
+  const pending = [];
+  const MAX_PENDING = 1000;
+  function connect() {
+    const socket = new WebSocket(config.url, config.protocols);
+    socket.addEventListener("open", () => {
+      for (const msg of pending) {
+        socket.send(msg);
+      }
+      pending.length = 0;
+    });
+    socket.addEventListener("message", (event) => {
+      try {
+        const message = JSON.parse(event.data);
+        handler?.(message);
+      } catch (err) {
+        console.warn("[reflectdb] WS client: malformed message ignored:", err instanceof Error ? err.message : String(err));
+      }
+    });
+    socket.addEventListener("close", () => {
+      if (ws === socket)
+        ws = null;
+      if (!intentionalClose) {
+        handler?.({ type: "disconnect", reason: "ws_closed" });
+      }
+    });
+    socket.addEventListener("error", () => {
+      if (!intentionalClose) {
+        handler?.({ type: "disconnect", reason: "ws_error" });
+      }
+    });
+    return socket;
+  }
+  return {
+    async send(message) {
+      if (!ws) {
+        ws = connect();
+      }
+      const data = JSON.stringify(message);
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(data);
+      } else {
+        pending.push(data);
+        while (pending.length > MAX_PENDING)
+          pending.shift();
+      }
+    },
+    subscribe(h) {
+      handler = h;
+      if (!ws) {
+        ws = connect();
+      }
+    },
+    async close() {
+      intentionalClose = true;
+      if (ws) {
+        ws.close();
+        ws = null;
+      }
+    },
+    getSocket() {
+      return ws;
+    }
+  };
+}

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

@@ -0,0 +1,236 @@
+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 ClientTransport {
+	send(message: ClientMessage): Promise<void>;
+	subscribe(handler: (message: ServerMessage) => void): void;
+	close(): Promise<void>;
+}
+interface WsServerConfig {
+	server: {
+		upgrade(req: Request, options: {
+			data: {
+				clientId: string;
+			};
+		}): boolean;
+	};
+	path?: string;
+}
+interface WsServerTransportConfig {
+	/** 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 pong is seen in this window. Default: 2× pingInterval. */
+	pongTimeoutMs?: number;
+	/**
+	* Outbound backpressure ceiling. When the socket's `bufferedAmount` exceeds
+	* this, `send` rejects instead of queueing more — a slow reader can't make
+	* the server buffer without bound. 0 disables. Default: 8 MB.
+	*/
+	maxBufferedBytes?: number;
+}
+/**
+* Origin-check helper for WS/SSE/polling upgrade paths. Callers invoke this
+* before accepting a connection. The default browser WebSocket/EventSource
+* clients always send an Origin header, so a `null` return usually means
+* a non-browser peer — treat accordingly for your threat model.
+*
+*   if (!isOriginAllowed(req, ["https://app.example.com"])) return new Response("Forbidden", { status: 403 });
+*/
+declare function isOriginAllowed(req: Request, allowed: readonly string[] | ((origin: string | null) => boolean)): boolean;
+declare function createWsServerTransport(cfg?: WsServerTransportConfig): ServerTransport & {
+	handleOpen(clientId: string, ws: WebSocketLike): void;
+	handleMessage(clientId: string, data: string): void;
+	handleClose(clientId: string): void;
+	handlePong(clientId: string): void;
+};
+interface WsClientConfig {
+	url: string;
+	protocols?: string[];
+}
+declare function createWsClientTransport(config: WsClientConfig): ClientTransport & {
+	getSocket(): WebSocket | null;
+};
+interface WebSocketLike {
+	send(data: string): void;
+	close(): void;
+	/** WebSocket readyState. When present, only 1 (OPEN) accepts sends. */
+	readyState?: number;
+	/** Bytes queued but not yet flushed. Used for outbound backpressure. */
+	bufferedAmount?: number;
+}
+export { isOriginAllowed, createWsServerTransport, createWsClientTransport, WsServerTransportConfig, WsServerConfig, WsClientConfig, WebSocketLike };