reflectdb 0.1.0

package/dist/transport/polling.d.ts

@@ -0,0 +1,210 @@
+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 PollingServerConfig {
+	/** Max queued messages per client. Older messages dropped when exceeded. Default: 1000. */
+	maxQueueLen?: number;
+	/** Idle timeout in ms — clients with no poll in this window are reaped. Default: 60_000. */
+	idleTimeoutMs?: number;
+	/** Reaper interval in ms. Default: 30_000. */
+	reaperIntervalMs?: number;
+	/** Max inbound JSON message bytes. Default: 1 MB. */
+	maxMessageBytes?: number;
+}
+/** Caller validates body size against this before parsing JSON; exported for convenience. */
+declare function pollingBodyTooLarge(body: string, limit?: number): boolean;
+declare function createPollingServerTransport(cfg?: PollingServerConfig): ServerTransport & {
+	handleConnect(clientId: string): void;
+	handleMessage(clientId: string, message: ClientMessage): void;
+	handleDisconnect(clientId: string): void;
+	handlePoll(clientId: string): ServerMessage[];
+};
+interface PollingClientConfig {
+	/** GET endpoint that returns `{ messages: ServerMessage[] }` */
+	pollUrl: string;
+	/** POST endpoint for sending client messages */
+	messageUrl: string;
+	/** Poll interval in ms (default: 1000) */
+	interval?: number;
+	headers?: Record<string, string>;
+}
+declare function createPollingClientTransport(config: PollingClientConfig): ClientTransport;
+export { pollingBodyTooLarge, createPollingServerTransport, createPollingClientTransport, PollingServerConfig, PollingClientConfig };

package/dist/transport/polling.js

@@ -0,0 +1,181 @@
+import {
+  TransportSendError
+} from "../shared/esm-3tkwvysa.js";
+import"../shared/esm-b7xs9cde.js";
+
+// src/transport/polling.ts
+function pollingBodyTooLarge(body, limit = 1e6) {
+  return body.length > limit;
+}
+function createPollingServerTransport(cfg = {}) {
+  const queues = new Map;
+  const lastPoll = new Map;
+  const maxQueueLen = cfg.maxQueueLen ?? 1000;
+  const idleTimeoutMs = cfg.idleTimeoutMs ?? 60000;
+  const reaperIntervalMs = cfg.reaperIntervalMs ?? 30000;
+  const maxMessageBytes = cfg.maxMessageBytes ?? 1e6;
+  let messageHandler = null;
+  let connectHandler = null;
+  let disconnectHandler = null;
+  const reaper = setInterval(() => {
+    const now = Date.now();
+    for (const [clientId, last] of lastPoll) {
+      if (now - last > idleTimeoutMs) {
+        queues.delete(clientId);
+        lastPoll.delete(clientId);
+        disconnectHandler?.(clientId);
+      }
+    }
+  }, reaperIntervalMs);
+  if (typeof reaper.unref === "function") {
+    reaper.unref();
+  }
+  function enqueue(queue, message) {
+    queue.push(message);
+    let dropped = false;
+    while (queue.length > maxQueueLen) {
+      queue.shift();
+      dropped = true;
+    }
+    return !dropped;
+  }
+  return {
+    handleConnect(clientId) {
+      if (!queues.has(clientId)) {
+        queues.set(clientId, []);
+      }
+      lastPoll.set(clientId, Date.now());
+      connectHandler?.(clientId, new Request("https://poll-connect"));
+    },
+    handleMessage(clientId, message) {
+      lastPoll.set(clientId, Date.now());
+      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] polling: message from ${clientId} exceeds ${maxMessageBytes} bytes (${byteLen}), dropping`);
+        return;
+      }
+      messageHandler?.(clientId, message);
+    },
+    handleDisconnect(clientId) {
+      queues.delete(clientId);
+      lastPoll.delete(clientId);
+      disconnectHandler?.(clientId);
+    },
+    handlePoll(clientId) {
+      lastPoll.set(clientId, Date.now());
+      const queue = queues.get(clientId);
+      if (!queue || queue.length === 0)
+        return [];
+      const messages = [...queue];
+      queue.length = 0;
+      return messages;
+    },
+    async send(clientId, message) {
+      const queue = queues.get(clientId);
+      if (!queue) {
+        throw new TransportSendError(clientId, "no queue registered for client");
+      }
+      if (!enqueue(queue, message)) {
+        throw new TransportSendError(clientId, `polling queue overflow (max ${maxQueueLen}); oldest message dropped undelivered`);
+      }
+    },
+    async broadcast(_roomId, message, exclude) {
+      for (const [clientId, queue] of queues) {
+        if (clientId !== exclude) {
+          enqueue(queue, message);
+        }
+      }
+    },
+    onMessage(handler) {
+      messageHandler = handler;
+    },
+    onConnect(handler) {
+      connectHandler = handler;
+    },
+    onDisconnect(handler) {
+      disconnectHandler = handler;
+    },
+    async close() {
+      clearInterval(reaper);
+      queues.clear();
+      lastPoll.clear();
+    },
+    disconnect(clientId) {
+      queues.delete(clientId);
+      lastPoll.delete(clientId);
+    }
+  };
+}
+function createPollingClientTransport(config) {
+  let handler = null;
+  let intervalId = null;
+  let intentionalClose = false;
+  const abortController = new AbortController;
+  async function poll() {
+    try {
+      const response = await fetch(config.pollUrl, {
+        headers: config.headers,
+        signal: abortController.signal
+      });
+      if (!response.ok) {
+        console.warn(`[reflectdb] Poll returned ${response.status}`);
+        return;
+      }
+      const data = await response.json();
+      for (const msg of data.messages) {
+        try {
+          handler?.(msg);
+        } catch (err) {
+          console.error("[reflectdb] Polling message handler error:", err);
+        }
+      }
+    } catch (err) {
+      if (intentionalClose || err.name === "AbortError")
+        return;
+      handler?.({ type: "disconnect", reason: "poll_error" });
+    }
+  }
+  return {
+    async send(message) {
+      const res = await fetch(config.messageUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...config.headers
+        },
+        body: JSON.stringify(message),
+        signal: abortController.signal
+      });
+      if (!res.ok) {
+        throw new Error(`Polling send failed: ${res.status} ${res.statusText}`);
+      }
+    },
+    subscribe(h) {
+      handler = h;
+      if (intervalId !== null)
+        return;
+      poll();
+      const ms = config.interval ?? 1000;
+      intervalId = setInterval(poll, ms);
+    },
+    async close() {
+      intentionalClose = true;
+      if (intervalId !== null) {
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+      abortController.abort();
+    }
+  };
+}
+export {
+  pollingBodyTooLarge,
+  createPollingServerTransport,
+  createPollingClientTransport
+};

package/dist/transport/sse.d.ts

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