meridian-sdk 0.1.0

package/src/sync/delta.ts

@@ -0,0 +1,104 @@
+/**
+ * Delta application helpers.
+ *
+ * The server sends deltas as opaque msgpack bytes inside `ServerMsg.Delta`.
+ * Each CRDT type decodes its own delta format. This module provides typed
+ * delta decoders that match the Rust server's serde output.
+ */
+
+import { unpack } from "msgpackr";
+
+// ---------------------------------------------------------------------------
+// GCounter delta
+// ---------------------------------------------------------------------------
+
+/** Sparse map of client_id → new count. Only changed entries are included. */
+export interface GCounterDelta {
+  increments: Record<string, number>;
+}
+
+export function decodeGCounterDelta(bytes: Uint8Array): GCounterDelta {
+  const raw = unpack(bytes) as { increments?: Record<string, number> };
+  return { increments: raw.increments ?? {} };
+}
+
+// ---------------------------------------------------------------------------
+// PNCounter delta
+// ---------------------------------------------------------------------------
+
+export interface PNCounterDelta {
+  p: GCounterDelta;
+  n: GCounterDelta;
+}
+
+export function decodePNCounterDelta(bytes: Uint8Array): PNCounterDelta {
+  const raw = unpack(bytes) as {
+    p?: { increments?: Record<string, number> };
+    n?: { increments?: Record<string, number> };
+  };
+  return {
+    p: { increments: raw.p?.increments ?? {} },
+    n: { increments: raw.n?.increments ?? {} },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// ORSet delta
+// ---------------------------------------------------------------------------
+
+export interface ORSetDelta {
+  /** element → set of add-tags (UUIDs as strings) */
+  added: Record<string, string[]>;
+  /** element → set of removed tags */
+  removed: Record<string, string[]>;
+}
+
+export function decodeORSetDelta(bytes: Uint8Array): ORSetDelta {
+  const raw = unpack(bytes) as {
+    added?: Record<string, string[]>;
+    removed?: Record<string, string[]>;
+  };
+  return {
+    added: raw.added ?? {},
+    removed: raw.removed ?? {},
+  };
+}
+
+// ---------------------------------------------------------------------------
+// LWW Register delta
+// ---------------------------------------------------------------------------
+
+export interface LwwEntry {
+  value: unknown;
+  hlc: { wall_ms: number; logical: number; node_id: number };
+  author: number;
+}
+
+export interface LwwDelta {
+  entry: LwwEntry | null;
+}
+
+export function decodeLwwDelta(bytes: Uint8Array): LwwDelta {
+  const raw = unpack(bytes) as { entry?: LwwEntry | null };
+  return { entry: raw.entry ?? null };
+}
+
+// ---------------------------------------------------------------------------
+// Presence delta
+// ---------------------------------------------------------------------------
+
+export interface PresenceEntryDelta {
+  data: unknown;
+  hlc: { wall_ms: number; logical: number; node_id: number };
+  ttl_ms: number;
+}
+
+export interface PresenceDelta {
+  /** client_id → entry (null = removed/tombstone) */
+  changes: Record<string, PresenceEntryDelta | null>;
+}
+
+export function decodePresenceDelta(bytes: Uint8Array): PresenceDelta {
+  const raw = unpack(bytes) as { changes?: Record<string, PresenceEntryDelta | null> };
+  return { changes: raw.changes ?? {} };
+}

package/src/transport/http.ts

@@ -0,0 +1,150 @@
+/**
+ * HTTP transport — REST API client for Meridian.
+ *
+ * All methods return Effect<T, HttpError | NetworkError> so callers
+ * can handle network failures and server errors as typed values.
+ */
+
+import { encode, decode } from "../codec.js";
+import { Effect, Schema } from "effect";
+import { HttpError, NetworkError } from "../errors.js";
+import {
+  CrdtGetResponse,
+  CrdtOpResponse,
+  TokenIssueResponse,
+  ErrorResponse,
+  VectorClock,
+} from "../schema.js";
+import type { Permissions } from "../schema.js";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export interface HttpClientConfig {
+  /** Base URL of the Meridian server, e.g. "http://localhost:3000" */
+  baseUrl: string;
+  /** Bearer token. Can be updated after construction (e.g. after refresh). */
+  token: string;
+  /** Request timeout in ms. Default: 10_000 */
+  timeoutMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// HttpClient
+// ---------------------------------------------------------------------------
+
+export class HttpClient {
+  private readonly baseUrl: string;
+  private readonly timeoutMs: number;
+  token: string;
+
+  constructor(config: HttpClientConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.token = config.token;
+    this.timeoutMs = config.timeoutMs ?? 10_000;
+  }
+
+  // ---- CRDT REST ----
+
+  /** GET /v1/namespaces/:ns/crdts/:id */
+  getCrdt(ns: string, id: string): Effect.Effect<CrdtGetResponse, HttpError | NetworkError> {
+    return this.request(CrdtGetResponse, "GET", `/v1/namespaces/${ns}/crdts/${id}`);
+  }
+
+  /** POST /v1/namespaces/:ns/crdts/:id/ops */
+  postOp(ns: string, id: string, op: unknown): Effect.Effect<CrdtOpResponse, HttpError | NetworkError> {
+    return this.request(CrdtOpResponse, "POST", `/v1/namespaces/${ns}/crdts/${id}/ops`, op);
+  }
+
+  /** GET /v1/namespaces/:ns/crdts/:id/sync?since=<base64url(msgpack(vc))> */
+  syncCrdt(
+    ns: string,
+    id: string,
+    sinceVc?: VectorClock,
+  ): Effect.Effect<CrdtGetResponse, HttpError | NetworkError> {
+    let path = `/v1/namespaces/${ns}/crdts/${id}/sync`;
+    if (sinceVc && Object.keys(sinceVc).length > 0) {
+      const bytes = encode({ entries: sinceVc });
+      path += `?since=${base64urlEncode(bytes)}`;
+    }
+    return this.request(CrdtGetResponse, "GET", path);
+  }
+
+  /** POST /v1/namespaces/:ns/tokens  (admin-only) */
+  issueToken(
+    ns: string,
+    opts: { client_id: number; ttl_ms: number; permissions: Permissions },
+  ): Effect.Effect<TokenIssueResponse, HttpError | NetworkError> {
+    return this.request(TokenIssueResponse, "POST", `/v1/namespaces/${ns}/tokens`, opts);
+  }
+
+  // ---- Internal ----
+
+  private request<A, I>(
+    responseSchema: Schema.Schema<A, I>,
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Effect.Effect<A, HttpError | NetworkError> {
+    const url = `${this.baseUrl}${path}`;
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.token}`,
+      Accept: "application/msgpack",
+    };
+
+    let bodyBytes: Uint8Array | undefined;
+    if (body !== undefined) {
+      bodyBytes = encode(body);
+      headers["Content-Type"] = "application/msgpack";
+    }
+
+    const fetchEffect = Effect.tryPromise({
+      try: async () => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+          const response = await fetch(url, { method, headers, body: bodyBytes, signal: controller.signal });
+          const bytes = new Uint8Array(await response.arrayBuffer());
+          return { response, bytes };
+        } finally {
+          clearTimeout(timer);
+        }
+      },
+      catch: (e) =>
+        new NetworkError({ message: e instanceof Error ? e.message : "fetch failed", cause: e }),
+    });
+
+    return fetchEffect.pipe(
+      Effect.flatMap(({ response, bytes }): Effect.Effect<A, HttpError | NetworkError> => {
+        if (!response.ok) {
+          let errBody: ErrorResponse;
+          try {
+            errBody = Schema.decodeUnknownSync(ErrorResponse)(decode(bytes));
+          } catch {
+            errBody = { error: "unknown", message: `HTTP ${response.status}` };
+          }
+          return Effect.fail(new HttpError({ status: response.status, body: errBody }));
+        }
+        const raw = decode(bytes);
+        return Schema.decodeUnknown(responseSchema)(raw).pipe(
+          Effect.mapError((e) =>
+            new NetworkError({ message: `Response schema validation failed: ${e.message}` }),
+          ),
+        );
+      }),
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// base64url (no-padding) encoder
+// ---------------------------------------------------------------------------
+
+function base64urlEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (const b of bytes) {
+    binary += String.fromCharCode(b);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}

package/src/transport/websocket.ts

@@ -0,0 +1,189 @@
+/**
+ * WebSocket transport — reconnect FSM + Sync on reconnect.
+ *
+ * States:
+ *   DISCONNECTED → CONNECTING → AUTHENTICATING → CONNECTED → CLOSING
+ *
+ * On reconnect: re-subscribes to all known CRDTs and sends Sync(localVectorClock)
+ * so the server can push missed deltas.
+ *
+ * Backoff: 100ms → 200ms → 400ms → … → 30s (±20% jitter).
+ */
+
+import { Effect } from "effect";
+import { encodeClientMsg, decodeServerMsg, encodeVectorClock } from "../codec.js";
+import type { ServerMsg, VectorClock } from "../schema.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type WsState =
+  | "DISCONNECTED"
+  | "CONNECTING"
+  | "CONNECTED"
+  | "CLOSING";
+
+export interface WsTransportConfig {
+  /** Full WebSocket URL, e.g. "ws://localhost:3000/v1/namespaces/my-room/connect" */
+  url: string;
+  /** Bearer token passed as ?token= query param (WS can't set headers). */
+  token: string;
+  /** Called whenever a ServerMsg arrives. */
+  onMessage: (msg: ServerMsg) => void;
+  /** Called on state transitions. */
+  onStateChange?: (state: WsState) => void;
+  /** Maximum reconnect delay in ms. Default: 30_000 */
+  maxBackoffMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// WsTransport
+// ---------------------------------------------------------------------------
+
+export class WsTransport {
+  private readonly config: WsTransportConfig;
+  private readonly maxBackoffMs: number;
+
+  private ws: WebSocket | null = null;
+  private state: WsState = "DISCONNECTED";
+  private backoffMs = 100;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private closed = false;
+
+  /** CRDTs to re-subscribe on reconnect: crdt_id → last known VectorClock */
+  private readonly subscriptions = new Map<string, VectorClock>();
+
+  constructor(config: WsTransportConfig) {
+    this.config = config;
+    this.maxBackoffMs = config.maxBackoffMs ?? 30_000;
+  }
+
+  // ---- Public API ----
+
+  connect(): void {
+    if (this.closed) return;
+    this.closed = false;
+    this.doConnect();
+  }
+
+  /** Gracefully close — will not reconnect. */
+  close(): void {
+    this.closed = true;
+    this.clearReconnectTimer();
+    this.transitionTo("CLOSING");
+    this.ws?.close(1000, "client close");
+  }
+
+  /**
+   * Subscribe to a CRDT's deltas.
+   * If already connected, sends Subscribe immediately.
+   * On reconnect, the subscription is re-sent automatically.
+   */
+  subscribe(crdtId: string, sinceVc: VectorClock = {}): void {
+    this.subscriptions.set(crdtId, sinceVc);
+    if (this.state === "CONNECTED") {
+      this.sendSubscribe(crdtId, sinceVc);
+    }
+  }
+
+  /** Update the local vector clock for a CRDT (used for reconnect Sync). */
+  updateClock(crdtId: string, vc: VectorClock): void {
+    this.subscriptions.set(crdtId, vc);
+  }
+
+  /** Send a raw ClientMsg. Throws if not connected. */
+  send(msg: Parameters<typeof encodeClientMsg>[0]): void {
+    if (this.state !== "CONNECTED" || this.ws === null) {
+      throw new Error("WsTransport: not connected");
+    }
+    this.ws.send(encodeClientMsg(msg));
+  }
+
+  get currentState(): WsState {
+    return this.state;
+  }
+
+  // ---- FSM internals ----
+
+  private doConnect(): void {
+    if (this.closed) return;
+    this.transitionTo("CONNECTING");
+
+    const url = `${this.config.url}${this.config.url.includes("?") ? "&" : "?"}token=${encodeURIComponent(this.config.token)}`;
+    const ws = new WebSocket(url);
+    ws.binaryType = "arraybuffer";
+    this.ws = ws;
+
+    ws.addEventListener("open", () => {
+      if (ws !== this.ws) return; // stale socket
+      this.backoffMs = 100; // reset backoff on successful connect
+      this.transitionTo("CONNECTED");
+      this.resubscribeAll();
+    });
+
+    ws.addEventListener("message", (event: MessageEvent) => {
+      if (ws !== this.ws) return;
+      const bytes = new Uint8Array(event.data as ArrayBuffer);
+      Effect.runPromise(decodeServerMsg(bytes)).then(
+        (msg) => { this.config.onMessage(msg); },
+        (e) => { console.warn("[meridian] failed to decode server message", e); },
+      );
+    });
+
+    ws.addEventListener("close", () => {
+      if (ws !== this.ws) return;
+      this.ws = null;
+      if (!this.closed) {
+        this.transitionTo("DISCONNECTED");
+        this.scheduleReconnect();
+      }
+    });
+
+    ws.addEventListener("error", () => {
+      // The "close" event fires right after — let that handle reconnect.
+    });
+  }
+
+  private scheduleReconnect(): void {
+    if (this.closed) return;
+    const jitter = this.backoffMs * 0.2 * (Math.random() * 2 - 1); // ±20%
+    const delay = Math.round(this.backoffMs + jitter);
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.doConnect();
+    }, delay);
+    this.backoffMs = Math.min(this.backoffMs * 2, this.maxBackoffMs);
+  }
+
+  private clearReconnectTimer(): void {
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  private transitionTo(next: WsState): void {
+    if (this.state === next) return;
+    this.state = next;
+    this.config.onStateChange?.(next);
+  }
+
+  /** On reconnect: re-subscribe and send Sync for each known CRDT. */
+  private resubscribeAll(): void {
+    for (const [crdtId, vc] of this.subscriptions) {
+      this.sendSubscribe(crdtId, vc);
+    }
+  }
+
+  private sendSubscribe(crdtId: string, vc: VectorClock): void {
+    if (this.ws === null || this.state !== "CONNECTED") return;
+
+    // First subscribe so the server starts pushing future deltas
+    this.ws.send(encodeClientMsg({ Subscribe: { crdt_id: crdtId } }));
+
+    // Then sync to get missed deltas since our last known VC
+    const vcBytes = encodeVectorClock(vc);
+    this.ws.send(encodeClientMsg({ Sync: { crdt_id: crdtId, since_vc: vcBytes } }));
+  }
+}