reflectdb 0.1.0

package/dist/transport/sse.js

@@ -0,0 +1,208 @@
+import {
+  TransportSendError
+} from "../shared/esm-3tkwvysa.js";
+import"../shared/esm-b7xs9cde.js";
+
+// src/transport/sse.ts
+function createSseServerTransport(cfg = {}) {
+  const controllers = new Map;
+  const buffers = new Map;
+  const counters = new Map;
+  const replayBufferSize = cfg.replayBufferSize ?? 256;
+  const maxMessageBytes = cfg.maxMessageBytes ?? 1e6;
+  let messageHandler = null;
+  let connectHandler = null;
+  let disconnectHandler = null;
+  const encoder = new TextEncoder;
+  function encode(id, message) {
+    const data = JSON.stringify(message);
+    return encoder.encode(`id: ${id}
+data: ${data}
+
+`);
+  }
+  function buffer(clientId, id, encoded, delivered) {
+    let buf = buffers.get(clientId);
+    if (!buf) {
+      buf = [];
+      buffers.set(clientId, buf);
+    }
+    buf.push({ id, encoded, delivered });
+    let lostUndelivered = false;
+    while (buf.length > replayBufferSize) {
+      const dropped = buf.shift();
+      if (dropped && !dropped.delivered)
+        lostUndelivered = true;
+    }
+    return lostUndelivered;
+  }
+  function nextId(clientId) {
+    const id = (counters.get(clientId) ?? 0) + 1;
+    counters.set(clientId, id);
+    return id;
+  }
+  return {
+    handleSubscribe(clientId, controller, lastEventId) {
+      controllers.set(clientId, controller);
+      if (lastEventId) {
+        const lastId = Number(lastEventId);
+        const buf = buffers.get(clientId);
+        if (buf && Number.isFinite(lastId)) {
+          for (const entry of buf) {
+            if (entry.id > lastId) {
+              controller.enqueue(entry.encoded);
+              entry.delivered = true;
+            }
+          }
+        }
+      }
+      connectHandler?.(clientId, new Request("https://sse-connect"));
+    },
+    handleMessage(clientId, message) {
+      let byteLen;
+      try {
+        const stringified = JSON.stringify(message);
+        byteLen = typeof Buffer !== "undefined" ? Buffer.byteLength(stringified, "utf8") : new Blob([stringified]).size;
+      } catch {
+        byteLen = 0;
+      }
+      if (byteLen > maxMessageBytes) {
+        console.warn(`[reflectdb] SSE: message from ${clientId} exceeds ${maxMessageBytes} bytes (${byteLen}), dropping`);
+        return;
+      }
+      messageHandler?.(clientId, message);
+    },
+    handleDisconnect(clientId) {
+      controllers.delete(clientId);
+      disconnectHandler?.(clientId);
+    },
+    createEventStream(clientId, lastEventId) {
+      return new ReadableStream({
+        start: (controller) => {
+          this.handleSubscribe(clientId, controller, lastEventId);
+        },
+        cancel: () => {
+          this.handleDisconnect(clientId);
+        }
+      });
+    },
+    async send(clientId, message) {
+      const id = nextId(clientId);
+      const encoded = encode(id, message);
+      const controller = controllers.get(clientId);
+      let sendError;
+      let delivered = false;
+      if (controller) {
+        try {
+          controller.enqueue(encoded);
+          delivered = true;
+        } catch (err) {
+          sendError = err;
+        }
+      }
+      const lostUndelivered = buffer(clientId, id, encoded, delivered);
+      if (sendError) {
+        throw new TransportSendError(clientId, `sse enqueue failed: ${sendError instanceof Error ? sendError.message : String(sendError)}`, sendError);
+      }
+      if (lostUndelivered) {
+        throw new TransportSendError(clientId, `sse replay buffer overflow (size ${replayBufferSize}); undelivered frames dropped`);
+      }
+    },
+    async broadcast(_roomId, message, exclude) {
+      for (const [clientId, controller] of controllers) {
+        if (clientId === exclude)
+          continue;
+        const id = nextId(clientId);
+        const encoded = encode(id, message);
+        let delivered = false;
+        try {
+          controller.enqueue(encoded);
+          delivered = true;
+        } catch (err) {
+          console.warn("[reflectdb] sse broadcast skipped a client:", err instanceof Error ? err.message : err);
+        }
+        buffer(clientId, id, encoded, delivered);
+      }
+    },
+    onMessage(handler) {
+      messageHandler = handler;
+    },
+    onConnect(handler) {
+      connectHandler = handler;
+    },
+    onDisconnect(handler) {
+      disconnectHandler = handler;
+    },
+    async close() {
+      for (const controller of controllers.values()) {
+        try {
+          controller.close();
+        } catch {}
+      }
+      controllers.clear();
+      buffers.clear();
+      counters.clear();
+    },
+    disconnect(clientId) {
+      const controller = controllers.get(clientId);
+      if (controller) {
+        try {
+          controller.close();
+        } catch {}
+      }
+      controllers.delete(clientId);
+      buffers.delete(clientId);
+      counters.delete(clientId);
+    }
+  };
+}
+function createSseClientTransport(config) {
+  let eventSource = null;
+  let handler = null;
+  let intentionalClose = false;
+  return {
+    async send(message) {
+      const res = await fetch(config.messageUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...config.headers
+        },
+        body: JSON.stringify(message)
+      });
+      if (!res.ok) {
+        throw new Error(`SSE send failed: ${res.status} ${res.statusText}`);
+      }
+    },
+    subscribe(h) {
+      handler = h;
+      if (eventSource)
+        return;
+      eventSource = new EventSource(config.eventUrl);
+      eventSource.onmessage = (event) => {
+        try {
+          const message = JSON.parse(event.data);
+          handler?.(message);
+        } catch (err) {
+          console.warn("[reflectdb] SSE: malformed message ignored:", err instanceof Error ? err.message : String(err));
+        }
+      };
+      eventSource.onerror = () => {
+        if (!intentionalClose) {
+          handler?.({ type: "disconnect", reason: "sse_error" });
+        }
+      };
+    },
+    async close() {
+      intentionalClose = true;
+      if (eventSource) {
+        eventSource.close();
+        eventSource = null;
+      }
+    }
+  };
+}
+export {
+  createSseServerTransport,
+  createSseClientTransport
+};

package/dist/transport/ws.d.ts

@@ -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 };

package/dist/transport/ws.js

@@ -0,0 +1,226 @@
+import {
+  TransportSendError
+} from "../shared/esm-3tkwvysa.js";
+import"../shared/esm-b7xs9cde.js";
+
+// src/transport/ws.ts
+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;
+    }
+  };
+}
+export {
+  isOriginAllowed,
+  createWsServerTransport,
+  createWsClientTransport
+};