reflectdb 0.1.0

package/dist/cjs/transport/sse.cjs

@@ -0,0 +1,312 @@
+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/sse.ts
+init_types();
+var exports_sse = {};
+__export(exports_sse, {
+  createSseServerTransport: () => createSseServerTransport,
+  createSseClientTransport: () => createSseClientTransport
+});
+module.exports = __toCommonJS(exports_sse);
+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;
+      }
+    }
+  };
+}

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

@@ -0,0 +1,205 @@
+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 SseServerConfig {
+	/** Max replay buffer size per client. Default: 256. */
+	replayBufferSize?: number;
+	/**
+	* Defensive cap on inbound message JSON byte length. The HTTP POST handler
+	* should size-gate the request body before parsing, but this catches a
+	* caller that forgets — preferable to silently accepting unbounded JSON.
+	* Default: 1 MB.
+	*/
+	maxMessageBytes?: number;
+}
+declare function createSseServerTransport(cfg?: SseServerConfig): ServerTransport & {
+	handleSubscribe(clientId: string, controller: ReadableStreamDefaultController, lastEventId?: string): void;
+	handleMessage(clientId: string, message: ClientMessage): void;
+	handleDisconnect(clientId: string): void;
+	createEventStream(clientId: string, lastEventId?: string): ReadableStream;
+};
+interface SseClientConfig {
+	eventUrl: string;
+	messageUrl: string;
+	headers?: Record<string, string>;
+}
+declare function createSseClientTransport(config: SseClientConfig): ClientTransport;
+export { createSseServerTransport, createSseClientTransport, SseServerConfig, SseClientConfig };