meridian-sdk 0.1.0

package/src/client.ts

@@ -0,0 +1,197 @@
+/**
+ * MeridianClient — top-level SDK entry point.
+ *
+ * Use `MeridianClient.create(config)` (returns Effect) to parse the token
+ * and validate it before connecting.
+ *
+ * ```ts
+ * const client = await Effect.runPromise(
+ *   MeridianClient.create({ url: "ws://localhost:3000", namespace: "room", token })
+ * );
+ * const counter = client.gcounter("gc:page-views");
+ * counter.increment();
+ * counter.onChange(v => console.log("views:", v));
+ * ```
+ */
+
+import { Effect, Schema } from "effect";
+import { WsTransport } from "./transport/websocket.js";
+import { HttpClient } from "./transport/http.js";
+import { GCounterHandle } from "./crdt/gcounter.js";
+import { PNCounterHandle } from "./crdt/pncounter.js";
+import { ORSetHandle } from "./crdt/orset.js";
+import { LwwRegisterHandle } from "./crdt/lwwregister.js";
+import { PresenceHandle } from "./crdt/presence.js";
+import {
+  decodeGCounterDelta,
+  decodePNCounterDelta,
+  decodeORSetDelta,
+  decodeLwwDelta,
+  decodePresenceDelta,
+} from "./sync/delta.js";
+import { parseAndValidateToken } from "./auth/token.js";
+import type { ServerMsg, TokenClaims } from "./schema.js";
+import type { TokenParseError, TokenExpiredError } from "./errors.js";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export interface MeridianClientConfig {
+  /** Base URL of the Meridian server, e.g. "http://localhost:3000" */
+  url: string;
+  /** Namespace to connect to. */
+  namespace: string;
+  /** Meridian token for this namespace. */
+  token: string;
+  /** If true, open the WebSocket immediately. Default: true */
+  autoConnect?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// MeridianClient
+// ---------------------------------------------------------------------------
+
+export class MeridianClient {
+  readonly namespace: string;
+  readonly clientId: number;
+  readonly claims: TokenClaims;
+
+  private readonly transport: WsTransport;
+  readonly http: HttpClient;
+
+  // Handle caches — keyed by crdt_id. Generic params erased at storage level;
+  // factories restore them via typed get+cast on retrieval.
+  private readonly gcHandles = new Map<string, GCounterHandle>();
+  private readonly pnHandles = new Map<string, PNCounterHandle>();
+  private readonly orHandles = new Map<string, ORSetHandle<unknown>>();
+  private readonly lwHandles = new Map<string, LwwRegisterHandle<unknown>>();
+  private readonly prHandles = new Map<string, PresenceHandle<unknown>>();
+
+  private constructor(config: MeridianClientConfig, claims: TokenClaims) {
+    this.namespace = config.namespace;
+    this.claims = claims;
+    this.clientId = claims.client_id;
+
+    const httpBase = config.url
+      .replace(/^wss:\/\//, "https://")
+      .replace(/^ws:\/\//, "http://");
+    this.http = new HttpClient({ baseUrl: httpBase, token: config.token });
+
+    const wsUrl = `${config.url.replace(/^http/, "ws")}/v1/namespaces/${config.namespace}/connect`;
+    this.transport = new WsTransport({
+      url: wsUrl,
+      token: config.token,
+      onMessage: (msg) => { this.handleServerMsg(msg); },
+    });
+
+    if (config.autoConnect !== false) {
+      this.transport.connect();
+    }
+  }
+
+  /**
+   * Create a MeridianClient, parsing and validating the token.
+   * Returns Effect<MeridianClient, TokenParseError | TokenExpiredError>.
+   */
+  static create(
+    config: MeridianClientConfig,
+  ): Effect.Effect<MeridianClient, TokenParseError | TokenExpiredError> {
+    return parseAndValidateToken(config.token).pipe(
+      Effect.map((claims) => new MeridianClient(config, claims)),
+    );
+  }
+
+  // ---- CRDT factory methods ----
+
+  gcounter(crdtId: string): GCounterHandle {
+    let h = this.gcHandles.get(crdtId);
+    if (!h) {
+      h = new GCounterHandle({ ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport });
+      this.gcHandles.set(crdtId, h);
+      this.transport.subscribe(crdtId);
+    }
+    return h;
+  }
+
+  pncounter(crdtId: string): PNCounterHandle {
+    let h = this.pnHandles.get(crdtId);
+    if (!h) {
+      h = new PNCounterHandle({ ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport });
+      this.pnHandles.set(crdtId, h);
+      this.transport.subscribe(crdtId);
+    }
+    return h;
+  }
+
+  orset<T>(crdtId: string, schema?: Schema.Schema<T>): ORSetHandle<T> {
+    let h = this.orHandles.get(crdtId) as ORSetHandle<T> | undefined;
+    if (!h) {
+      const base = { ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport };
+      h = schema ? new ORSetHandle<T>({ ...base, schema }) : new ORSetHandle<T>(base);
+      this.orHandles.set(crdtId, h as ORSetHandle<unknown>);
+      this.transport.subscribe(crdtId);
+    }
+    return h;
+  }
+
+  lwwregister<T>(crdtId: string, schema?: Schema.Schema<T>): LwwRegisterHandle<T> {
+    let h = this.lwHandles.get(crdtId) as LwwRegisterHandle<T> | undefined;
+    if (!h) {
+      const base = { ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport };
+      h = schema ? new LwwRegisterHandle<T>({ ...base, schema }) : new LwwRegisterHandle<T>(base);
+      this.lwHandles.set(crdtId, h as LwwRegisterHandle<unknown>);
+      this.transport.subscribe(crdtId);
+    }
+    return h;
+  }
+
+  presence<T>(crdtId: string, schema?: Schema.Schema<T>): PresenceHandle<T> {
+    let h = this.prHandles.get(crdtId) as PresenceHandle<T> | undefined;
+    if (!h) {
+      const base = { ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport };
+      h = schema ? new PresenceHandle<T>({ ...base, schema }) : new PresenceHandle<T>(base);
+      this.prHandles.set(crdtId, h as PresenceHandle<unknown>);
+      this.transport.subscribe(crdtId);
+    }
+    return h;
+  }
+
+  // ---- Lifecycle ----
+
+  close(): void {
+    this.transport.close();
+  }
+
+  // ---- Internal: route ServerMsg.Delta to the right handle ----
+
+  private handleServerMsg(msg: ServerMsg): void {
+    if (!("Delta" in msg)) return;
+    const { crdt_id, delta_bytes } = msg.Delta;
+
+    const gcHandle = this.gcHandles.get(crdt_id);
+    if (gcHandle) {
+      try { gcHandle.applyDelta(decodeGCounterDelta(delta_bytes)); } catch { /* stale */ }
+      return;
+    }
+    const pnHandle = this.pnHandles.get(crdt_id);
+    if (pnHandle) {
+      try { pnHandle.applyDelta(decodePNCounterDelta(delta_bytes)); } catch { /* stale */ }
+      return;
+    }
+    const orHandle = this.orHandles.get(crdt_id);
+    if (orHandle) {
+      try { orHandle.applyDelta(decodeORSetDelta(delta_bytes)); } catch { /* stale */ }
+      return;
+    }
+    const lwHandle = this.lwHandles.get(crdt_id);
+    if (lwHandle) {
+      try { lwHandle.applyDelta(decodeLwwDelta(delta_bytes)); } catch { /* stale */ }
+      return;
+    }
+    const prHandle = this.prHandles.get(crdt_id);
+    if (prHandle) {
+      try { prHandle.applyDelta(decodePresenceDelta(delta_bytes)); } catch { /* stale */ }
+    }
+  }
+}

package/src/codec.ts

@@ -0,0 +1,92 @@
+/**
+ * Msgpack codec — wraps msgpackr with Meridian-specific conventions.
+ *
+ * The server uses rmp-serde with `to_vec_named` (named fields) so enum
+ * variants are encoded as `{ "VariantName": { ...fields } }` maps.
+ * msgpackr handles this transparently in JS land.
+ */
+
+import { pack, unpack } from "msgpackr";
+import { Effect, Schema } from "effect";
+import { CodecError } from "./errors.js";
+import { ServerMsg } from "./schema.js";
+import type { ClientMsg, VectorClock } from "./schema.js";
+
+// ---------------------------------------------------------------------------
+// Low-level encode / decode
+// ---------------------------------------------------------------------------
+
+/** Encode any value to msgpack bytes. */
+export function encode(value: unknown): Uint8Array<ArrayBuffer> {
+  return pack(value) as Uint8Array<ArrayBuffer>;
+}
+
+/** Decode msgpack bytes to a plain JS value (unsafe — no schema validation). */
+export function decode(bytes: Uint8Array): unknown {
+  return unpack(bytes);
+}
+
+// ---------------------------------------------------------------------------
+// Typed helpers for WebSocket frames
+// ---------------------------------------------------------------------------
+
+/**
+ * Encode a ClientMsg to a binary WebSocket frame.
+ * The msgpack encoding matches rmp-serde's "named" enum format:
+ *   `{ Subscribe: { crdt_id: "foo" } }` → msgpack map with one key.
+ */
+export function encodeClientMsg(msg: ClientMsg): Uint8Array {
+  return encode(msg);
+}
+
+/**
+ * Decode a binary WebSocket frame into a ServerMsg.
+ * Returns Effect<ServerMsg, CodecError>.
+ */
+export function decodeServerMsg(bytes: Uint8Array): Effect.Effect<ServerMsg, CodecError> {
+  let raw: unknown;
+  try {
+    raw = unpack(bytes);
+  } catch {
+    return Effect.fail(new CodecError({ message: "msgpack decode failed", raw: bytes }));
+  }
+
+  // Schema.decodeUnknown accepts `unknown` input — correct for runtime decode boundaries
+  return Schema.decodeUnknown(ServerMsg)(raw).pipe(
+    Effect.mapError((parseError) =>
+      new CodecError({
+        message: `ServerMsg schema validation failed: ${parseError.message}`,
+        raw: bytes,
+      }),
+    ),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// VectorClock <-> msgpack bytes
+// ---------------------------------------------------------------------------
+
+export function encodeVectorClock(vc: VectorClock): Uint8Array {
+  // Server expects { entries: { "client_id": version, ... } }
+  return encode({ entries: vc });
+}
+
+export function decodeVectorClock(bytes: Uint8Array): Effect.Effect<VectorClock, CodecError> {
+  let raw: unknown;
+  try {
+    raw = unpack(bytes);
+  } catch {
+    return Effect.fail(new CodecError({ message: "VectorClock msgpack decode failed", raw: bytes }));
+  }
+
+  const entries = raw !== null && typeof raw === "object" && "entries" in raw
+    ? (raw as { entries: unknown }).entries
+    : {};
+  return Schema.decodeUnknown(Schema.Record({ key: Schema.String, value: Schema.Number }))(
+    entries ?? {},
+  ).pipe(
+    Effect.mapError((e) =>
+      new CodecError({ message: `VectorClock schema validation failed: ${e.message}`, raw: bytes }),
+    ),
+  );
+}

package/src/crdt/gcounter.ts

@@ -0,0 +1,101 @@
+/**
+ * GCounter handle — increment-only counter.
+ *
+ * Local state is kept as a sparse map `{ client_id → count }`.
+ * `value()` returns the sum. Deltas are merged on incoming ServerMsg.Delta.
+ */
+
+import { encode } from "../codec.js";
+import type { WsTransport } from "../transport/websocket.js";
+import type { GCounterDelta } from "../sync/delta.js";
+
+export interface GCounterState {
+  counts: Record<string, number>;
+}
+
+export class GCounterHandle {
+  private state: GCounterState;
+  private readonly clientId: number;
+  private readonly crdtId: string;
+  private readonly ns: string;
+  private readonly transport: WsTransport;
+
+  /** Emits on every state change. */
+  private readonly listeners = new Set<(value: number) => void>();
+
+  constructor(opts: {
+    ns: string;
+    crdtId: string;
+    clientId: number;
+    transport: WsTransport;
+    initial?: GCounterState;
+  }) {
+    this.ns = opts.ns;
+    this.crdtId = opts.crdtId;
+    this.clientId = opts.clientId;
+    this.transport = opts.transport;
+    this.state = opts.initial ?? { counts: {} };
+  }
+
+  // ---- Read ----
+
+  value(): number {
+    return Object.values(this.state.counts).reduce((a, b) => a + b, 0);
+  }
+
+  counts(): Readonly<Record<string, number>> {
+    return this.state.counts;
+  }
+
+  /** Subscribe to value changes. Returns an unsubscribe function. */
+  onChange(listener: (value: number) => void): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  // ---- Write ----
+
+  /** Increment by `amount` (must be > 0). */
+  increment(amount: number = 1): void {
+    if (amount <= 0) throw new RangeError("GCounter: increment amount must be > 0");
+
+    // Optimistic local update
+    const key = String(this.clientId);
+    this.state.counts[key] = (this.state.counts[key] ?? 0) + amount;
+    this.emit();
+
+    // Send Op to server
+    const op = encode({
+      GCounter: {
+        client_id: this.clientId,
+        amount,
+      },
+    });
+    this.transport.send({
+      Op: { crdt_id: this.crdtId, op_bytes: op },
+    });
+  }
+
+  // ---- Delta application (called by MeridianClient on incoming Delta) ----
+
+  applyDelta(delta: GCounterDelta): void {
+    let changed = false;
+    for (const [id, count] of Object.entries(delta.increments)) {
+      const current = this.state.counts[id] ?? 0;
+      if (count > current) {
+        this.state.counts[id] = count;
+        changed = true;
+      }
+    }
+    if (changed) this.emit();
+  }
+
+  // ---- Internal ----
+
+  private emit(): void {
+    const v = this.value();
+    for (const listener of this.listeners) {
+      listener(v);
+    }
+  }
+}

package/src/crdt/lwwregister.ts

@@ -0,0 +1,113 @@
+/**
+ * LWW Register handle — Last-Write-Wins single-value cell.
+ *
+ * The winning write is determined by HLC (highest wall_ms wins),
+ * tie-broken by author (higher client_id wins). The client sends its
+ * local wall clock as HLC wall_ms; the server enforces ±30s drift limit.
+ *
+ * Pass a `schema` to get runtime validation of incoming deltas:
+ *   client.lwwregister("id", Schema.Struct({ x: Schema.Number }))
+ */
+
+import { Schema } from "effect";
+import { encode } from "../codec.js";
+import type { WsTransport } from "../transport/websocket.js";
+import type { LwwDelta, LwwEntry } from "../sync/delta.js";
+
+export class LwwRegisterHandle<T> {
+  private entry: LwwEntry | null = null;
+  private readonly crdtId: string;
+  private readonly clientId: number;
+  private readonly transport: WsTransport;
+  private readonly schema: Schema.Schema<T> | null;
+  private readonly listeners = new Set<(value: T | null) => void>();
+
+  constructor(opts: {
+    ns: string;
+    crdtId: string;
+    clientId: number;
+    transport: WsTransport;
+    schema?: Schema.Schema<T>;
+    initial?: LwwEntry | null;
+  }) {
+    this.crdtId = opts.crdtId;
+    this.clientId = opts.clientId;
+    this.transport = opts.transport;
+    this.schema = opts.schema ?? null;
+    this.entry = opts.initial ?? null;
+  }
+
+  // ---- Read ----
+
+  value(): T | null {
+    if (this.entry === null) return null;
+    return this.decode(this.entry.value);
+  }
+
+  /** Metadata: when was the last write and by whom. */
+  meta(): { updatedAtMs: number; author: number } | null {
+    if (this.entry === null) return null;
+    return { updatedAtMs: this.entry.hlc.wall_ms, author: this.entry.author };
+  }
+
+  onChange(listener: (value: T | null) => void): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  // ---- Write ----
+
+  set(value: T): void {
+    const wallMs = Date.now();
+    const hlc = { wall_ms: wallMs, logical: 0, node_id: this.clientId };
+
+    const newEntry: LwwEntry = { value, hlc, author: this.clientId };
+    if (this.entryWins(newEntry, this.entry)) {
+      this.entry = newEntry;
+      this.emit();
+    }
+
+    this.transport.send({
+      Op: {
+        crdt_id: this.crdtId,
+        op_bytes: encode({ LwwRegister: { value, hlc, author: this.clientId } }),
+      },
+    });
+  }
+
+  // ---- Delta application ----
+
+  applyDelta(delta: LwwDelta): void {
+    if (delta.entry === null) return;
+    if (this.entryWins(delta.entry, this.entry)) {
+      this.entry = delta.entry;
+      this.emit();
+    }
+  }
+
+  // ---- Internal ----
+
+  private decode(raw: unknown): T {
+    if (this.schema !== null) {
+      return Schema.decodeUnknownSync(this.schema)(raw);
+    }
+    // No schema provided — T defaults to unknown, cast is the caller's responsibility
+    return raw as T;
+  }
+
+  private entryWins(candidate: LwwEntry, existing: LwwEntry | null): boolean {
+    if (existing === null) return true;
+    if (candidate.hlc.wall_ms !== existing.hlc.wall_ms) {
+      return candidate.hlc.wall_ms > existing.hlc.wall_ms;
+    }
+    if (candidate.hlc.logical !== existing.hlc.logical) {
+      return candidate.hlc.logical > existing.hlc.logical;
+    }
+    return candidate.author > existing.author;
+  }
+
+  private emit(): void {
+    const v = this.value();
+    for (const l of this.listeners) l(v);
+  }
+}

package/src/crdt/orset.ts

@@ -0,0 +1,131 @@
+/**
+ * ORSet handle — add-wins observed-remove set.
+ *
+ * Each element has a set of add-tags (UUIDs). Remove only removes tags
+ * known at remove time — a concurrent add with a new tag survives.
+ *
+ * Elements are serialized as JSON for the wire (serde_json::Value).
+ *
+ * Pass a `schema` to get runtime validation of elements deserialized from deltas:
+ *   client.orset("id", Schema.Struct({ id: Schema.String }))
+ */
+
+import { Schema } from "effect";
+import { encode } from "../codec.js";
+import type { WsTransport } from "../transport/websocket.js";
+import type { ORSetDelta } from "../sync/delta.js";
+
+export class ORSetHandle<T> {
+  /** element (JSON-stringified) → Set of live add-tags */
+  private readonly tags = new Map<string, Set<string>>();
+  private readonly crdtId: string;
+  private readonly clientId: number;
+  private readonly transport: WsTransport;
+  private readonly schema: Schema.Schema<T> | null;
+  private readonly listeners = new Set<(elements: T[]) => void>();
+
+  constructor(opts: {
+    ns: string;
+    crdtId: string;
+    clientId: number;
+    transport: WsTransport;
+    schema?: Schema.Schema<T>;
+  }) {
+    this.crdtId = opts.crdtId;
+    this.clientId = opts.clientId;
+    this.transport = opts.transport;
+    this.schema = opts.schema ?? null;
+  }
+
+  // ---- Read ----
+
+  /** Returns all live elements (add-wins). */
+  elements(): T[] {
+    return Array.from(this.tags.keys())
+      .filter(k => (this.tags.get(k)?.size ?? 0) > 0)
+      .map(k => this.decode(JSON.parse(k)));
+  }
+
+  has(element: T): boolean {
+    const key = JSON.stringify(element);
+    return (this.tags.get(key)?.size ?? 0) > 0;
+  }
+
+  onChange(listener: (elements: T[]) => void): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  // ---- Write ----
+
+  add(element: T): void {
+    const tag = crypto.randomUUID();
+    const key = JSON.stringify(element);
+
+    if (!this.tags.has(key)) this.tags.set(key, new Set());
+    this.tags.get(key)!.add(tag);
+    this.emit();
+
+    this.transport.send({
+      Op: {
+        crdt_id: this.crdtId,
+        op_bytes: encode({ ORSet: { Add: { element, tag, client_id: this.clientId } } }),
+      },
+    });
+  }
+
+  remove(element: T): void {
+    const key = JSON.stringify(element);
+    const currentTags = Array.from(this.tags.get(key) ?? []);
+    if (currentTags.length === 0) return;
+
+    this.tags.delete(key);
+    this.emit();
+
+    this.transport.send({
+      Op: {
+        crdt_id: this.crdtId,
+        op_bytes: encode({ ORSet: { Remove: { element, tags: currentTags, client_id: this.clientId } } }),
+      },
+    });
+  }
+
+  // ---- Delta application ----
+
+  applyDelta(delta: ORSetDelta): void {
+    let changed = false;
+
+    for (const [elem, addedTags] of Object.entries(delta.added)) {
+      if (!this.tags.has(elem)) this.tags.set(elem, new Set());
+      const set = this.tags.get(elem)!;
+      for (const tag of addedTags) {
+        if (!set.has(tag)) { set.add(tag); changed = true; }
+      }
+    }
+
+    for (const [elem, removedTags] of Object.entries(delta.removed)) {
+      const set = this.tags.get(elem);
+      if (!set) continue;
+      for (const tag of removedTags) {
+        if (set.has(tag)) { set.delete(tag); changed = true; }
+      }
+      if (set.size === 0) this.tags.delete(elem);
+    }
+
+    if (changed) this.emit();
+  }
+
+  // ---- Internal ----
+
+  private decode(raw: unknown): T {
+    if (this.schema !== null) {
+      return Schema.decodeUnknownSync(this.schema)(raw);
+    }
+    return raw as T;
+  }
+
+  private emit(): void {
+    const elems = this.elements();
+    for (const l of this.listeners) l(elems);
+  }
+}