@lenso/realtime 0.0.0-stage → 0.2.0

package/dist/memory.js

@@ -0,0 +1,62 @@
+import {
+  RealtimeError2,
+  serialize
+} from "./index-htkqerky.js";
+
+// src/memory.ts
+function createMemoryProvider(options = {}) {
+  const maxTopics = options.maxTopics ?? 1e4;
+  const ttl = options.watermarkTtlMs ?? 600000;
+  if (!Number.isSafeInteger(maxTopics) || maxTopics < 1 || !Number.isSafeInteger(ttl) || ttl < 1)
+    throw new RealtimeError2("invalid-input");
+  const marks = new Map;
+  let deliver;
+  let closed = false;
+  const current = (topic) => {
+    if (!deliver || closed)
+      throw new RealtimeError2("closed");
+    const now = Date.now();
+    const old = marks.get(topic);
+    if (old && old.expiresAt > now) {
+      old.expiresAt = now + ttl;
+      return { ...old.cursor };
+    }
+    if (marks.size >= maxTopics) {
+      for (const [key, mark] of marks)
+        if (mark.expiresAt <= now)
+          marks.delete(key);
+      if (marks.size >= maxTopics)
+        throw new RealtimeError2("limit");
+    }
+    const cursor = { generation: crypto.randomUUID(), sequence: 0 };
+    marks.set(topic, { cursor, expiresAt: now + ttl });
+    return { ...cursor };
+  };
+  return {
+    kind: "memory",
+    async start(listener) {
+      if (deliver || closed)
+        throw new RealtimeError2("closed");
+      deliver = listener;
+    },
+    async current(topic) {
+      return current(topic);
+    },
+    async publish(topic, event) {
+      const copy = JSON.parse(serialize(event, 49152));
+      const previous = current(topic);
+      const cursor = { ...previous, sequence: previous.sequence + 1 };
+      marks.set(topic, { cursor, expiresAt: Date.now() + ttl });
+      deliver({ topic, event: copy, cursor });
+      return { ...cursor };
+    },
+    async close() {
+      closed = true;
+      deliver = undefined;
+      marks.clear();
+    }
+  };
+}
+export {
+  createMemoryProvider
+};

package/dist/plugin.d.ts

@@ -0,0 +1,30 @@
+import { type ConfigSource } from "@lenso/core/config";
+import type { Plugin } from "@lenso/core/plugin";
+import type { Realtime, RealtimeConfig, RealtimeOptions, RealtimeProvider } from "./contracts";
+export declare const realtimeConfig: import("@lenso/core/config").ConfigContract<{
+    "~standard": {
+        version: 1;
+        vendor: string;
+        types: {
+            input: RealtimeConfig;
+            output: Required<RealtimeConfig>;
+        } | undefined;
+        validate(input: unknown): {
+            issues: {
+                message: string;
+            }[];
+            value?: undefined;
+        } | {
+            issues?: undefined;
+            value: Required<RealtimeConfig>;
+        };
+    };
+}>;
+/** Provider factory executes in setup, never at trusted config import time. */
+export declare function createRealtimePlugin<P>(options: {
+    id: string;
+    requires?: readonly Plugin<unknown>[];
+    config: RealtimeConfig | readonly ConfigSource[];
+    provider(): RealtimeProvider;
+    authorize: RealtimeOptions<P>["authorize"];
+}): Plugin<Realtime<P>>;

package/dist/plugin.js

@@ -0,0 +1,68 @@
+import {
+  defaults,
+  resolveRealtimeConfig2,
+  createRealtime2
+} from "./index-6fg21p7s.js";
+
+// src/plugin.ts
+import { bindConfig, definePluginConfig } from "@lenso/core/config";
+var schema = {
+  "~standard": {
+    version: 1,
+    vendor: "lenso-realtime",
+    types: undefined,
+    validate(input) {
+      try {
+        if (!input || typeof input !== "object" || Array.isArray(input))
+          return { issues: [{ message: "Invalid realtime configuration" }] };
+        return { value: resolveRealtimeConfig2(input) };
+      } catch {
+        return { issues: [{ message: "Invalid realtime configuration" }] };
+      }
+    }
+  }
+};
+var realtimeConfig = definePluginConfig({
+  schema,
+  description: "Bounded resource subscriptions; no stream or publisher is automatically exposed.",
+  fields: Object.keys(defaults).map((name) => ({
+    path: [name],
+    description: `Realtime ${name} limit.`
+  })),
+  jsonSchema: () => ({
+    type: "object",
+    additionalProperties: false,
+    properties: Object.fromEntries(Object.keys(defaults).map((key) => [
+      key,
+      {
+        type: "integer",
+        minimum: key === "maxBufferedBytes" ? 512 : 1,
+        maximum: key === "authorizationLeaseMs" ? 30000 : key === "sweepMs" ? 1000 : key === "maxPayloadBytes" ? 32768 : 1e7
+      }
+    ]))
+  })
+});
+function createRealtimePlugin(options) {
+  return bindConfig(realtimeConfig, options.config, {
+    id: options.id,
+    requires: options.requires,
+    async setup(context, config) {
+      const provider = options.provider();
+      context.onCleanup(() => provider.close());
+      const realtime = await createRealtime2({
+        config,
+        provider,
+        authorize: options.authorize,
+        onDiagnostic(event) {
+          context.logger?.warn({ category: event }, "Realtime lifecycle diagnostic");
+        }
+      });
+      context.onCleanup(() => realtime.close());
+      return realtime;
+    }
+  });
+}
+export {
+  createRealtimePlugin,
+  realtimeConfig
+};

package/dist/redis.d.ts

@@ -0,0 +1,11 @@
+import { type RealtimeProvider } from "./contracts";
+export interface RedisProviderOptions {
+    readonly url: string;
+    readonly namespace: string;
+    readonly watermarkTtlMs?: number;
+    readonly commandTimeoutMs?: number;
+    readonly connectionTimeoutMs?: number;
+    readonly maxPendingOperations?: number;
+}
+/** Standalone Redis only: two owned sockets, non-durable namespace Pub/Sub. */
+export declare function createRedisProvider(options: RedisProviderOptions): RealtimeProvider;

package/dist/redis.js

@@ -0,0 +1,275 @@
+// @bun
+// src/redis.ts
+var {RedisClient } = globalThis.Bun;
+
+// src/contracts.ts
+class RealtimeError extends Error {
+  code;
+  constructor(code) {
+    super(`Realtime ${code}`);
+    this.code = code;
+    this.name = "RealtimeError";
+  }
+}
+
+// src/wire.ts
+function serialize(value, maxBytes) {
+  const active = new Set;
+  let nodes = 0;
+  const visit = (input, depth) => {
+    if (++nodes > 1e4 || depth > 32)
+      throw new RealtimeError("payload");
+    if (input === null || typeof input === "string" || typeof input === "boolean")
+      return;
+    if (typeof input === "number" && Number.isFinite(input))
+      return;
+    if (typeof input !== "object" || input === null || active.has(input))
+      throw new RealtimeError("payload");
+    const proto = Object.getPrototypeOf(input);
+    if (Array.isArray(input) ? proto !== Array.prototype : proto !== Object.prototype && proto !== null)
+      throw new RealtimeError("payload");
+    active.add(input);
+    if (Object.getOwnPropertySymbols(input).length)
+      throw new RealtimeError("payload");
+    const keys = Object.keys(input);
+    const ownNames = Object.getOwnPropertyNames(input);
+    if (ownNames.length !== keys.length + (Array.isArray(input) ? 1 : 0))
+      throw new RealtimeError("payload");
+    if (Array.isArray(input) && (keys.length !== input.length || keys.some((key, i) => key !== String(i))))
+      throw new RealtimeError("payload");
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      if (!("value" in descriptor))
+        throw new RealtimeError("payload");
+      visit(descriptor.value, depth + 1);
+    }
+    active.delete(input);
+  };
+  visit(value, 0);
+  const text = JSON.stringify(value);
+  if (new TextEncoder().encode(text).byteLength > maxBytes)
+    throw new RealtimeError("payload");
+  return text;
+}
+
+// src/redis.ts
+var MAX_WIRE_BYTES = 48 * 1024;
+var encoder = new TextEncoder;
+var WATERMARK = `
+if redis.call('EXISTS', KEYS[1]) == 0 then
+  redis.call('HSET', KEYS[1], 'generation', ARGV[1], 'sequence', '0')
+end
+local generation = redis.call('HGET', KEYS[1], 'generation')
+local sequence = redis.call('HGET', KEYS[1], 'sequence')
+if ARGV[3] == 'publish' then
+  if tonumber(sequence) >= 9007199254740991 then
+    return redis.error_reply('sequence exhausted')
+  end
+  redis.call('HINCRBY', KEYS[1], 'sequence', 1)
+  sequence = redis.call('HGET', KEYS[1], 'sequence')
+  local delivery = '{"topic":' .. ARGV[4] .. ',"cursor":{"generation":"' ..
+    generation .. '","sequence":' .. sequence .. '},"event":' .. ARGV[5] .. '}'
+  redis.call('PUBLISH', ARGV[6], delivery)
+end
+redis.call('PEXPIRE', KEYS[1], ARGV[2])
+return {generation, sequence}
+`;
+function validCursor(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const cursor = value;
+  return Object.keys(cursor).length === 2 && typeof cursor.generation === "string" && /^[A-Za-z0-9-]{1,64}$/.test(cursor.generation) && Number.isSafeInteger(cursor.sequence) && cursor.sequence >= 0;
+}
+function validEvent(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const event = value;
+  if (event.kind === "deleted" || event.kind === "revoke")
+    return Object.keys(event).length === 1;
+  return event.kind === "update" && typeof event.type === "string" && event.type.length > 0 && event.type.length <= 256 && Object.hasOwn(event, "data") && Object.keys(event).length === 3;
+}
+function validTopic(topic) {
+  return typeof topic === "string" && topic.length > 0 && topic.length <= 4096;
+}
+function createRedisProvider(options) {
+  if (!options || typeof options.url !== "string" || !options.url || typeof options.namespace !== "string" || !/^[A-Za-z0-9:_-]{1,128}$/.test(options.namespace))
+    throw new RealtimeError("invalid-input");
+  const ttl = options.watermarkTtlMs ?? 600000;
+  const timeout = options.commandTimeoutMs ?? 5000;
+  const connectionTimeout = options.connectionTimeoutMs ?? 2000;
+  const maxPending = options.maxPendingOperations ?? 64;
+  for (const value of [ttl, timeout, connectionTimeout, maxPending]) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 1e7)
+      throw new RealtimeError("invalid-input");
+  }
+  const url = options.url;
+  const namespace = options.namespace;
+  const channel = `${namespace}:events`;
+  const keyPrefix = `${namespace.length}:${namespace}:watermark:`;
+  let state = "new";
+  let command;
+  let subscription;
+  let deliver;
+  let fail;
+  let pending = 0;
+  const cancellations = new Set;
+  function release(error) {
+    deliver = undefined;
+    fail = undefined;
+    for (const cancel of cancellations)
+      cancel(error);
+    for (const client of [command, subscription]) {
+      if (!client)
+        continue;
+      client.onclose = () => {};
+      client.onconnect = () => {};
+      try {
+        client.close();
+      } catch {}
+    }
+    command = undefined;
+    subscription = undefined;
+  }
+  function terminate() {
+    if (state === "failed" || state === "closed")
+      return;
+    const notify = fail;
+    state = "failed";
+    release(new RealtimeError("provider"));
+    notify?.();
+  }
+  function deadline(run) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (error, value) => {
+        if (settled)
+          return;
+        settled = true;
+        clearTimeout(timer);
+        cancellations.delete(cancel);
+        if (error)
+          reject(error);
+        else
+          resolve(value);
+      };
+      const cancel = (error) => finish(error);
+      const timer = setTimeout(() => terminate(), timeout);
+      cancellations.add(cancel);
+      try {
+        run().then((value) => finish(undefined, value), () => {
+          terminate();
+          finish(new RealtimeError("provider"));
+        });
+      } catch {
+        terminate();
+        finish(new RealtimeError("provider"));
+      }
+    });
+  }
+  function receive(message) {
+    if (state !== "starting" && state !== "ready")
+      return;
+    try {
+      if (encoder.encode(message).byteLength > MAX_WIRE_BYTES)
+        throw new Error;
+      const value = JSON.parse(message);
+      if (!value || typeof value !== "object" || Object.keys(value).length !== 3 || !validTopic(value.topic) || !validCursor(value.cursor) || !validEvent(value.event) || value.cursor.sequence < 1)
+        throw new Error;
+      serialize(value.event, MAX_WIRE_BYTES);
+      deliver?.(value);
+    } catch {
+      terminate();
+    }
+  }
+  async function watermark(topic, event) {
+    if (state !== "ready")
+      throw new RealtimeError(state === "failed" ? "provider" : "closed");
+    if (pending >= maxPending)
+      throw new RealtimeError("limit");
+    if (!validTopic(topic))
+      throw new RealtimeError("invalid-input");
+    const generation = crypto.randomUUID();
+    const topicJson = serialize(topic, MAX_WIRE_BYTES);
+    let eventJson = "";
+    if (event !== undefined) {
+      if (!validEvent(event))
+        throw new RealtimeError("payload");
+      eventJson = serialize(event, MAX_WIRE_BYTES);
+      const wire = JSON.stringify({
+        topic,
+        cursor: { generation, sequence: Number.MAX_SAFE_INTEGER },
+        event: JSON.parse(eventJson)
+      });
+      if (encoder.encode(wire).byteLength > MAX_WIRE_BYTES)
+        throw new RealtimeError("payload");
+    }
+    pending++;
+    try {
+      const result = await deadline(() => command.send("EVAL", [
+        WATERMARK,
+        "1",
+        `${keyPrefix}${topic}`,
+        generation,
+        String(ttl),
+        event === undefined ? "current" : "publish",
+        topicJson,
+        eventJson,
+        channel
+      ]));
+      if (!Array.isArray(result) || result.length !== 2 || typeof result[1] !== "string" || !/^\d+$/.test(result[1])) {
+        terminate();
+        throw new RealtimeError("provider");
+      }
+      const cursor = { generation: result[0], sequence: Number(result[1]) };
+      if (!validCursor(cursor)) {
+        terminate();
+        throw new RealtimeError("provider");
+      }
+      return cursor;
+    } finally {
+      pending--;
+    }
+  }
+  return {
+    kind: "redis",
+    async start(onDelivery, onFailure) {
+      if (state !== "new")
+        throw new RealtimeError(state === "failed" ? "provider" : "closed");
+      state = "starting";
+      deliver = onDelivery;
+      fail = onFailure;
+      try {
+        const clientOptions = {
+          connectionTimeout,
+          autoReconnect: false,
+          maxRetries: 0,
+          enableOfflineQueue: false,
+          enableAutoPipelining: false
+        };
+        command = new RedisClient(url, clientOptions);
+        subscription = new RedisClient(url, clientOptions);
+        command.onclose = terminate;
+        subscription.onclose = terminate;
+        await deadline(() => Promise.all([command.connect(), subscription.connect()]));
+        await deadline(() => subscription.subscribe(channel, receive));
+        if (state !== "starting")
+          throw new RealtimeError("provider");
+        state = "ready";
+      } catch {
+        terminate();
+        throw new RealtimeError("provider");
+      }
+    },
+    current: (topic) => watermark(topic),
+    publish: (topic, event) => watermark(topic, event),
+    async close() {
+      if (state === "closed")
+        return;
+      state = "closed";
+      release(new RealtimeError("closed"));
+    }
+  };
+}
+export {
+  createRedisProvider
+};

package/dist/wire.d.ts

@@ -0,0 +1,10 @@
+import { type Cursor, type Resource } from "./contracts";
+export declare function part(value: string): string;
+export declare function resourceTopic(resource: Resource): string;
+export declare function cursorToken(cursor: Cursor, now?: number): string;
+export declare function parseCursor(token: string): (Cursor & {
+    issuedAt: number;
+}) | undefined;
+export declare function sameCursor(a: Cursor, b: Cursor): boolean;
+/** No toJSON, accessors, classes, sparse arrays, cycles, non-finite numbers or lossy values. */
+export declare function serialize(value: unknown, maxBytes: number): string;

package/examples/notes.ts

@@ -0,0 +1,65 @@
+import {
+  createRealtime,
+  RealtimeError,
+  type Identity,
+  type RealtimeProvider,
+} from "@lenso/realtime";
+
+export interface Note {
+  id: string;
+  title: string;
+  body: string;
+  revision: number;
+}
+
+/** Implement with the existing authorized Notes service, not a second HTTP policy. */
+export interface NotesPort<P> {
+  read(identity: Identity<P>, id: string, signal: AbortSignal): Promise<Note | null>;
+  update(
+    identity: Identity<P>,
+    id: string,
+    input: { title: string; body: string },
+  ): Promise<Note | null>;
+}
+
+export async function createNotesRealtime<P>(notes: NotesPort<P>, provider: RealtimeProvider) {
+  const realtime = await createRealtime<P>({
+    provider,
+    async authorize(identity, resource, signal) {
+      if (resource.type !== "note") return false;
+      const note = await notes.read(identity, resource.id, signal);
+      return note ? { validUntil: identity.expiresAt } : false;
+    },
+  });
+  return {
+    realtime,
+    async open(identity: Identity<P>, id: string, signal?: AbortSignal, cursor?: string) {
+      const connection = realtime.connect(identity, { signal });
+      try {
+        const subscription = await connection.subscribe(
+          { scope: identity.scope, type: "note", id },
+          { cursor },
+        );
+        const snapshot = await connection.snapshot(subscription, (snapshotSignal) =>
+          notes.read(identity, id, snapshotSignal),
+        );
+        if (!snapshot.value) throw new RealtimeError("denied");
+        return { connection, subscription, snapshot };
+      } catch (error) {
+        connection.close();
+        throw error;
+      }
+    },
+    async update(identity: Identity<P>, id: string, input: { title: string; body: string }) {
+      const note = await notes.update(identity, id, input);
+      if (note) {
+        // Publish invalidation after the durable write, never uncommitted note contents.
+        await realtime.publish({ scope: identity.scope, type: "note", id }, "note.updated", {
+          revision: note.revision,
+        });
+      }
+      return note;
+    },
+    close: () => realtime.close(),
+  };
+}

package/examples/run-notes.ts

@@ -0,0 +1,43 @@
+import { createMemoryProvider } from "@lenso/realtime/memory";
+import { createNotesRealtime, type Note, type NotesPort } from "./notes";
+import type { Identity } from "@lenso/realtime";
+
+// Trusted in-process fixture, not a login endpoint or production authentication.
+const principal = Object.freeze({});
+const identity: Identity<object> = {
+  scope: "single-application",
+  subject: "note-owner",
+  principal,
+  expiresAt: Date.now() + 60000,
+};
+let stored: Note = { id: "welcome", title: "Notes", body: "Initial text", revision: 1 };
+const notes: NotesPort<object> = {
+  async read(actor, id, signal) {
+    signal.throwIfAborted();
+    if (actor.principal !== principal || actor.scope !== identity.scope) throw new Error("Denied");
+    return id === stored.id ? { ...stored } : null;
+  },
+  async update(actor, id, input) {
+    if (actor.principal !== principal || actor.scope !== identity.scope) throw new Error("Denied");
+    if (id !== stored.id) return null;
+    stored = { ...stored, ...input, revision: stored.revision + 1 };
+    return { ...stored };
+  },
+};
+const bridge = await createNotesRealtime(notes, createMemoryProvider());
+try {
+  const first = await bridge.open(identity, "welcome");
+  const second = await bridge.open(identity, "welcome");
+  const a = first.connection[Symbol.asyncIterator](),
+    b = second.connection[Symbol.asyncIterator]();
+  await a.next();
+  await b.next();
+  console.log(JSON.stringify({ snapshot: first.snapshot }));
+  await bridge.update(identity, "welcome", { title: "Notes", body: "Updated text" });
+  console.log(JSON.stringify({ first: (await a.next()).value, second: (await b.next()).value }));
+  first.subscription.unsubscribe();
+  first.connection.close();
+  second.connection.close();
+} finally {
+  await bridge.close();
+}

package/examples/tasks.ts

@@ -0,0 +1,10 @@
+import type { Realtime } from "@lenso/realtime";
+
+/** Call only after the existing Tasks owner commits a status transition. */
+export async function taskStatusCommitted(
+  realtime: Realtime,
+  resource: { scope: string; id: string },
+  status: "queued" | "running" | "succeeded" | "failed",
+) {
+  return realtime.publish({ ...resource, type: "task" }, "task.status", { status });
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@lenso/realtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LioRael/lenso.git",
+    "directory": "packages/realtime"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "examples"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./memory": {
+      "types": "./dist/memory.d.ts",
+      "import": "./dist/memory.js"
+    },
+    "./redis": {
+      "types": "./dist/redis.d.ts",
+      "import": "./dist/redis.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js"
+    }
+  },
+  "scripts": {
+    "build": "bun -e \"await import('node:fs/promises').then(({rm}) => rm('dist', {recursive:true, force:true}))\" && bun build src/index.ts src/memory.ts src/plugin.ts --root src --outdir dist --target browser --packages external --splitting && bun build src/redis.ts --outdir dist --target bun --packages external && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test test",
+    "test:redis": "bun test integration/redis.test.ts",
+    "measure": "BUN_CONFIG_MAX_HTTP_REQUESTS=1024 bun scripts/measure.ts"
+  },
+  "devDependencies": {
+    "@lenso/core": "^0.3.0",
+    "@lenso/web": "^0.3.1",
+    "@lenso/workers": "^0.2.1",
+    "@orpc/server": "2.0.0-beta.42"
+  },
+  "peerDependencies": {
+    "@lenso/core": "^0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@lenso/core": {
+      "optional": true
+    }
+  }
+}