@lenso/realtime 0.0.0-stage → 0.2.0

package/dist/index-6fg21p7s.js

@@ -0,0 +1,563 @@
+import {
+  RealtimeError2,
+  part,
+  resourceTopic,
+  cursorToken,
+  parseCursor,
+  sameCursor,
+  serialize
+} from "./index-htkqerky.js";
+// src/config.ts
+var defaults = {
+  maxConnections: 1000,
+  maxConnectionsPerSubject: 8,
+  maxSubscriptionsPerConnection: 16,
+  maxSubscriptionsPerSubject: 64,
+  maxSubscribersPerTopic: 1000,
+  maxTopics: 1000,
+  maxPendingOperations: 64,
+  maxPayloadBytes: 16384,
+  maxBufferedEvents: 64,
+  maxBufferedBytes: 131072,
+  authorizationLeaseMs: 30000,
+  sweepMs: 250,
+  heartbeatMs: 15000,
+  retryMs: 2000,
+  cursorMaxAgeMs: 600000,
+  snapshotTimeoutMs: 5000
+};
+function resolveRealtimeConfig2(input = {}) {
+  const config = { ...defaults, ...input };
+  for (const key of Object.keys(config)) {
+    const value = config[key];
+    if (!(key in defaults) || !Number.isSafeInteger(value) || value < 1 || value > 1e7)
+      throw new RealtimeError2("invalid-input");
+  }
+  if (config.authorizationLeaseMs > 30000 || config.sweepMs > 1000 || config.sweepMs > config.authorizationLeaseMs || config.maxPayloadBytes > 32768 || config.maxBufferedBytes < 512 || config.maxBufferedBytes < config.maxPayloadBytes + 512)
+    throw new RealtimeError2("invalid-input");
+  return config;
+}
+// src/index.ts
+async function createRealtime2(options) {
+  const config = resolveRealtimeConfig2(options.config);
+  const provider = options.provider;
+  const connections = new Set;
+  const topics = new Map;
+  let stopped = false;
+  let failed = false;
+  let pending = 0;
+  let closing;
+  let sweep;
+  const lifetime = new AbortController;
+  const diagnostic = (event) => {
+    try {
+      options.onDiagnostic?.(event);
+    } catch {}
+  };
+  const assertOpen = () => {
+    if (failed)
+      throw new RealtimeError2("provider");
+    if (stopped)
+      throw new RealtimeError2("closed");
+  };
+  const live = (connection) => {
+    assertOpen();
+    if (connection.closed)
+      throw new RealtimeError2("closed");
+    if (connection.identity.expiresAt <= Date.now()) {
+      closeConnection(connection, { version: 1, kind: "closed", reason: "expired" });
+      throw new RealtimeError2("expired");
+    }
+  };
+  const subjectConnections = (identity) => [...connections].filter((c) => c.identity.scope === identity.scope && c.identity.subject === identity.subject);
+  const purge = (connection, subscription) => {
+    connection.queue = connection.queue.filter((item) => JSON.parse(item.text).subscription !== subscription);
+    connection.bytes = connection.queue.reduce((sum, item) => sum + item.bytes, 0);
+  };
+  const removeSub = (sub, reason, notify = true) => {
+    if (!sub.connection.subscriptions.delete(sub.handle.id))
+      return;
+    sub.abort.abort(new RealtimeError2("closed"));
+    const listeners = topics.get(sub.topic);
+    listeners?.delete(sub);
+    if (!listeners?.size)
+      topics.delete(sub.topic);
+    purge(sub.connection, sub.handle.id);
+    if (notify)
+      push(sub.connection, { version: 1, kind: "closed", subscription: sub.handle.id, reason });
+  };
+  function closeConnection(connection, terminal) {
+    if (connection.closed)
+      return;
+    connection.closed = true;
+    connections.delete(connection);
+    connection.removeAbort();
+    connection.abort.abort(new RealtimeError2("closed"));
+    for (const sub of [...connection.subscriptions.values()])
+      removeSub(sub, "shutdown", false);
+    connection.queue = [];
+    connection.bytes = 0;
+    connection.terminal = terminal;
+    if (connection.waiter) {
+      const waiter = connection.waiter;
+      connection.waiter = undefined;
+      connection.terminal = undefined;
+      waiter(terminal ? { done: false, value: terminal } : { done: true, value: undefined });
+    }
+  }
+  function push(connection, event) {
+    if (connection.closed)
+      return;
+    if (connection.identity.expiresAt <= Date.now()) {
+      closeConnection(connection, { version: 1, kind: "closed", reason: "expired" });
+      return;
+    }
+    const text = JSON.stringify(event);
+    if (new TextEncoder().encode(text).byteLength > config.maxPayloadBytes + 512) {
+      diagnostic("overflow");
+      closeConnection(connection, { version: 1, kind: "gap", reason: "overflow" });
+      return;
+    }
+    if (connection.waiter) {
+      const waiter = connection.waiter;
+      connection.waiter = undefined;
+      waiter({ done: false, value: JSON.parse(text) });
+      return;
+    }
+    const bytes = new TextEncoder().encode(text).byteLength;
+    if (connection.queue.length >= config.maxBufferedEvents || connection.bytes + bytes > config.maxBufferedBytes) {
+      diagnostic("overflow");
+      closeConnection(connection, { version: 1, kind: "gap", reason: "overflow" });
+      return;
+    }
+    connection.queue.push({ text, bytes });
+    connection.bytes += bytes;
+  }
+  const providerFailed = () => {
+    if (failed || stopped)
+      return;
+    failed = true;
+    clearInterval(sweep);
+    lifetime.abort(new RealtimeError2("provider"));
+    diagnostic("provider");
+    for (const connection of [...connections])
+      closeConnection(connection, { version: 1, kind: "gap", reason: "provider" });
+    provider.close().catch(() => {});
+  };
+  const receive = (delivery) => {
+    if (failed || stopped)
+      return;
+    const listeners = topics.get(delivery.topic);
+    if (!listeners)
+      return;
+    serialize(delivery.event, config.maxPayloadBytes);
+    const token = cursorToken(delivery.cursor);
+    for (const sub of [...listeners]) {
+      if (delivery.event.kind === "revoke" || delivery.event.kind === "deleted") {
+        removeSub(sub, delivery.event.kind === "revoke" ? "revoked" : "deleted");
+        continue;
+      }
+      if (sub.initializing)
+        continue;
+      if (sub.validUntil <= Date.now()) {
+        removeSub(sub, "expired");
+        continue;
+      }
+      const previous = sub.cursor;
+      const next = delivery.cursor;
+      if (sameCursor(previous, next))
+        continue;
+      let reason;
+      if (next.generation !== previous.generation)
+        reason = "generation";
+      else if (next.sequence < previous.sequence)
+        reason = "out-of-order";
+      else if (next.sequence !== previous.sequence + 1)
+        reason = "sequence";
+      if (reason)
+        push(sub.connection, {
+          version: 1,
+          kind: "gap",
+          subscription: sub.handle.id,
+          reason,
+          cursor: token
+        });
+      if (reason === "out-of-order")
+        continue;
+      sub.cursor = { ...next };
+      push(sub.connection, {
+        version: 1,
+        kind: "update",
+        subscription: sub.handle.id,
+        cursor: token,
+        type: delivery.event.type,
+        data: delivery.event.data
+      });
+    }
+  };
+  const deliver = (delivery) => {
+    try {
+      receive(delivery);
+    } catch {
+      providerFailed();
+    }
+  };
+  try {
+    await provider.start(deliver, providerFailed);
+    assertOpen();
+  } catch {
+    await provider.close().catch(() => {});
+    throw new RealtimeError2("provider");
+  }
+  const run = async (signal, operation) => {
+    assertOpen();
+    if (signal.aborted)
+      throw new RealtimeError2("closed");
+    if (pending >= config.maxPendingOperations)
+      throw new RealtimeError2("limit");
+    pending++;
+    const abort = new AbortController;
+    const cancelled = () => abort.abort(new RealtimeError2("closed"));
+    const shutdown = () => abort.abort(new RealtimeError2(failed ? "provider" : "closed"));
+    signal.addEventListener("abort", cancelled, { once: true });
+    lifetime.signal.addEventListener("abort", shutdown, { once: true });
+    const timer = setTimeout(() => abort.abort(new RealtimeError2("expired")), config.snapshotTimeoutMs);
+    let rejectAbort;
+    const interrupted = new Promise((_, reject) => {
+      rejectAbort = reject;
+    });
+    const onAbort = () => rejectAbort(abort.signal.reason);
+    abort.signal.addEventListener("abort", onAbort, { once: true });
+    const work = Promise.resolve().then(() => operation(abort.signal)).finally(() => {
+      pending--;
+    });
+    try {
+      return await Promise.race([work, interrupted]);
+    } finally {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", cancelled);
+      lifetime.signal.removeEventListener("abort", shutdown);
+      abort.signal.removeEventListener("abort", onAbort);
+    }
+  };
+  const current = async (topic) => {
+    try {
+      return await provider.current(topic);
+    } catch (error) {
+      if (error instanceof RealtimeError2 && error.code === "limit")
+        throw error;
+      providerFailed();
+      throw new RealtimeError2("provider");
+    }
+  };
+  const authorize = async (sub) => {
+    const startedAt = Date.now();
+    let result;
+    try {
+      result = await run(sub.abort.signal, (signal) => options.authorize(sub.connection.identity, sub.handle.resource, signal));
+    } catch (error) {
+      diagnostic("authorization");
+      if (error instanceof RealtimeError2)
+        throw error;
+      throw new RealtimeError2("denied");
+    }
+    live(sub.connection);
+    if (!sub.connection.subscriptions.has(sub.handle.id))
+      throw new RealtimeError2("closed");
+    const now = Date.now();
+    if (!result || !Number.isFinite(result.validUntil) || result.validUntil <= now)
+      throw new RealtimeError2("denied");
+    sub.validUntil = Math.min(result.validUntil, startedAt + config.authorizationLeaseMs, sub.connection.identity.expiresAt);
+    if (sub.validUntil <= now)
+      throw new RealtimeError2("expired");
+  };
+  const next = async (connection) => {
+    for (const sub of [...connection.subscriptions.values()])
+      if (!sub.initializing && sub.validUntil <= Date.now())
+        removeSub(sub, "expired");
+    if (!connection.closed && connection.identity.expiresAt <= Date.now())
+      closeConnection(connection, { version: 1, kind: "closed", reason: "expired" });
+    const item = connection.queue.shift();
+    if (item) {
+      connection.bytes -= item.bytes;
+      return { done: false, value: JSON.parse(item.text) };
+    }
+    if (connection.terminal) {
+      const value = connection.terminal;
+      connection.terminal = undefined;
+      return { done: false, value };
+    }
+    if (connection.closed)
+      return { done: true, value: undefined };
+    if (connection.waiter)
+      throw new RealtimeError2("invalid-input");
+    return new Promise((resolve) => {
+      connection.waiter = resolve;
+    });
+  };
+  sweep = setInterval(() => {
+    const now = Date.now();
+    for (const connection of [...connections]) {
+      if (connection.identity.expiresAt <= now) {
+        closeConnection(connection, { version: 1, kind: "closed", reason: "expired" });
+        continue;
+      }
+      for (const sub of [...connection.subscriptions.values()])
+        if (!sub.initializing && sub.validUntil <= now)
+          removeSub(sub, "expired");
+      if (now - connection.heartbeatAt >= config.heartbeatMs) {
+        connection.heartbeatAt = now;
+        push(connection, { version: 1, kind: "heartbeat" });
+      }
+    }
+  }, config.sweepMs);
+  const publish = async (resource, event) => {
+    assertOpen();
+    const topic = resourceTopic(resource);
+    const copy = JSON.parse(serialize(event, config.maxPayloadBytes));
+    try {
+      return cursorToken(await run(new AbortController().signal, () => provider.publish(topic, copy)));
+    } catch (error) {
+      if (error instanceof RealtimeError2 && (error.code === "limit" || error.code === "payload"))
+        throw error;
+      providerFailed();
+      throw new RealtimeError2("provider");
+    }
+  };
+  return {
+    connect(identity, { signal } = {}) {
+      assertOpen();
+      part(identity.scope);
+      part(identity.subject);
+      if (!Number.isFinite(identity.expiresAt) || identity.expiresAt <= Date.now())
+        throw new RealtimeError2("expired");
+      if (signal?.aborted)
+        throw new RealtimeError2("closed");
+      if (connections.size >= config.maxConnections || subjectConnections(identity).length >= config.maxConnectionsPerSubject)
+        throw new RealtimeError2("limit");
+      const connection = {
+        identity: Object.freeze({ ...identity }),
+        abort: new AbortController,
+        subscriptions: new Map,
+        queue: [],
+        bytes: 0,
+        closed: false,
+        consumed: false,
+        heartbeatAt: Date.now(),
+        removeAbort: () => {}
+      };
+      const disconnect = () => closeConnection(connection);
+      signal?.addEventListener("abort", disconnect, { once: true });
+      connection.removeAbort = () => signal?.removeEventListener("abort", disconnect);
+      connections.add(connection);
+      const api = {
+        async subscribe(input, subscriptionOptions = {}) {
+          live(connection);
+          const resource = Object.freeze({ scope: input.scope, type: input.type, id: input.id });
+          const topic = resourceTopic(resource);
+          if (resource.scope !== connection.identity.scope)
+            throw new RealtimeError2("denied");
+          const subjectCount = subjectConnections(connection.identity).reduce((sum, c) => sum + c.subscriptions.size, 0);
+          if (connection.subscriptions.size >= config.maxSubscriptionsPerConnection || subjectCount >= config.maxSubscriptionsPerSubject || (topics.get(topic)?.size ?? 0) >= config.maxSubscribersPerTopic || !topics.has(topic) && topics.size >= config.maxTopics)
+            throw new RealtimeError2("limit");
+          const id = crypto.randomUUID();
+          const sub = {
+            topic,
+            connection,
+            abort: new AbortController,
+            validUntil: 0,
+            initializing: true,
+            renewing: false,
+            handle: Object.freeze({
+              id,
+              resource,
+              unsubscribe: () => removeSub(sub, "unsubscribed"),
+              async renew() {
+                live(connection);
+                if (!connection.subscriptions.has(id))
+                  throw new RealtimeError2("closed");
+                if (sub.validUntil <= Date.now()) {
+                  removeSub(sub, "expired");
+                  throw new RealtimeError2("expired");
+                }
+                if (sub.renewing)
+                  throw new RealtimeError2("limit");
+                sub.renewing = true;
+                try {
+                  await authorize(sub);
+                } catch (error) {
+                  removeSub(sub, "revoked");
+                  throw error;
+                } finally {
+                  sub.renewing = false;
+                }
+              }
+            })
+          };
+          connection.subscriptions.set(id, sub);
+          if (!topics.has(topic))
+            topics.set(topic, new Set);
+          topics.get(topic).add(sub);
+          try {
+            await authorize(sub);
+            sub.cursor = await run(sub.abort.signal, () => current(topic));
+            live(connection);
+            if (!connection.subscriptions.has(id) || sub.validUntil <= Date.now())
+              throw new RealtimeError2("expired");
+            sub.initializing = false;
+            push(connection, {
+              version: 1,
+              kind: "ready",
+              subscription: id,
+              cursor: cursorToken(sub.cursor)
+            });
+            if (subscriptionOptions.cursor !== undefined) {
+              const parsed = parseCursor(subscriptionOptions.cursor);
+              const age = parsed ? Date.now() - parsed.issuedAt : Infinity;
+              push(connection, {
+                version: 1,
+                kind: "gap",
+                subscription: id,
+                cursor: cursorToken(sub.cursor),
+                reason: !parsed || age < 0 || age > config.cursorMaxAgeMs ? "cursor-expired" : "reconnect"
+              });
+            }
+            live(connection);
+            return sub.handle;
+          } catch (error) {
+            removeSub(sub, "revoked", false);
+            throw error;
+          }
+        },
+        async snapshot(subscription, read) {
+          live(connection);
+          const sub = connection.subscriptions.get(subscription.id);
+          if (!sub || sub.handle !== subscription || sub.initializing)
+            throw new RealtimeError2("denied");
+          if (sub.validUntil <= Date.now()) {
+            removeSub(sub, "expired");
+            throw new RealtimeError2("expired");
+          }
+          const result = await run(sub.abort.signal, async (snapshotSignal) => {
+            const before = await current(sub.topic);
+            const value = await read(snapshotSignal);
+            snapshotSignal.throwIfAborted();
+            const after = await current(sub.topic);
+            return { value, after, stable: sameCursor(before, after) };
+          });
+          live(connection);
+          if (!connection.subscriptions.has(subscription.id) || sub.validUntil <= Date.now())
+            throw new RealtimeError2("expired");
+          if (!result.stable)
+            push(connection, {
+              version: 1,
+              kind: "gap",
+              subscription: subscription.id,
+              reason: "snapshot-race",
+              cursor: cursorToken(result.after)
+            });
+          return { value: result.value, cursor: cursorToken(result.after), stable: result.stable };
+        },
+        [Symbol.asyncIterator]() {
+          if (connection.consumed)
+            throw new RealtimeError2("invalid-input");
+          connection.consumed = true;
+          return {
+            next: () => next(connection),
+            async return() {
+              closeConnection(connection);
+              return { done: true, value: undefined };
+            }
+          };
+        },
+        response() {
+          const iterator = api[Symbol.asyncIterator]();
+          const encoder = new TextEncoder;
+          let first = true;
+          const body = new ReadableStream({
+            async pull(controller) {
+              try {
+                const result = await iterator.next();
+                if (result.done) {
+                  controller.close();
+                  return;
+                }
+                const event = result.value;
+                const prefix = first ? `retry: ${config.retryMs}
+` : "";
+                first = false;
+                const id = event.cursor ? `id: ${event.cursor}
+` : "";
+                controller.enqueue(encoder.encode(`${prefix}${id}event: ${event.kind}
+data: ${JSON.stringify(event)}
+
+`));
+              } catch {
+                closeConnection(connection);
+                controller.error(new RealtimeError2("closed"));
+              }
+            },
+            cancel() {
+              closeConnection(connection);
+            }
+          }, { highWaterMark: 0 });
+          return new Response(body, {
+            headers: {
+              "content-type": "text/event-stream; charset=utf-8",
+              "cache-control": "no-store",
+              "x-accel-buffering": "no"
+            }
+          });
+        },
+        close() {
+          closeConnection(connection);
+        }
+      };
+      return api;
+    },
+    async publish(resource, type, data) {
+      if (typeof type !== "string" || !/^[a-zA-Z][a-zA-Z0-9._-]{0,63}$/.test(type))
+        throw new RealtimeError2("invalid-input");
+      return publish(resource, { kind: "update", type, data });
+    },
+    async revokeResource(resource) {
+      const topic = resourceTopic(resource);
+      for (const sub of [...topics.get(topic) ?? []])
+        removeSub(sub, "revoked");
+      await publish(resource, { kind: "revoke" });
+    },
+    async deleteResource(resource) {
+      const topic = resourceTopic(resource);
+      for (const sub of [...topics.get(topic) ?? []])
+        removeSub(sub, "deleted");
+      await publish(resource, { kind: "deleted" });
+    },
+    revokeSubject(scope, subject) {
+      part(scope);
+      part(subject);
+      for (const connection of [...connections])
+        if (connection.identity.scope === scope && connection.identity.subject === subject)
+          closeConnection(connection, { version: 1, kind: "closed", reason: "revoked" });
+    },
+    stats() {
+      return {
+        connections: connections.size,
+        topics: topics.size,
+        pending,
+        subscriptions: [...connections].reduce((sum, c) => sum + c.subscriptions.size, 0)
+      };
+    },
+    close() {
+      return closing ??= (async () => {
+        stopped = true;
+        clearInterval(sweep);
+        lifetime.abort(new RealtimeError2("closed"));
+        for (const connection of [...connections])
+          closeConnection(connection, { version: 1, kind: "closed", reason: "shutdown" });
+        await provider.close();
+      })();
+    }
+  };
+}
+
+export { defaults, resolveRealtimeConfig2, createRealtime2 };

package/dist/index-htkqerky.js

@@ -0,0 +1,81 @@
+// src/contracts.ts
+class RealtimeError2 extends Error {
+  code;
+  constructor(code) {
+    super(`Realtime ${code}`);
+    this.code = code;
+    this.name = "RealtimeError";
+  }
+}
+
+// src/wire.ts
+function part(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 256 || new TextEncoder().encode(value).byteLength > 256)
+    throw new RealtimeError2("invalid-input");
+  try {
+    return encodeURIComponent(value);
+  } catch {
+    throw new RealtimeError2("invalid-input");
+  }
+}
+function resourceTopic(resource) {
+  return `resource/${part(resource.scope)}/${part(resource.type)}/${part(resource.id)}`;
+}
+function cursorToken(cursor, now = Date.now()) {
+  return `${cursor.generation}.${cursor.sequence}.${now}`;
+}
+function parseCursor(token) {
+  if (typeof token !== "string" || token.length > 160)
+    return;
+  const match = /^([A-Za-z0-9-]{1,64})\.(\d{1,16})\.(\d{1,16})$/.exec(token);
+  if (!match)
+    return;
+  const sequence = Number(match[2]);
+  const issuedAt = Number(match[3]);
+  if (!Number.isSafeInteger(sequence) || !Number.isSafeInteger(issuedAt))
+    return;
+  return { generation: match[1], sequence, issuedAt };
+}
+function sameCursor(a, b) {
+  return a.generation === b.generation && a.sequence === b.sequence;
+}
+function serialize(value, maxBytes) {
+  const active = new Set;
+  let nodes = 0;
+  const visit = (input, depth) => {
+    if (++nodes > 1e4 || depth > 32)
+      throw new RealtimeError2("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 RealtimeError2("payload");
+    const proto = Object.getPrototypeOf(input);
+    if (Array.isArray(input) ? proto !== Array.prototype : proto !== Object.prototype && proto !== null)
+      throw new RealtimeError2("payload");
+    active.add(input);
+    if (Object.getOwnPropertySymbols(input).length)
+      throw new RealtimeError2("payload");
+    const keys = Object.keys(input);
+    const ownNames = Object.getOwnPropertyNames(input);
+    if (ownNames.length !== keys.length + (Array.isArray(input) ? 1 : 0))
+      throw new RealtimeError2("payload");
+    if (Array.isArray(input) && (keys.length !== input.length || keys.some((key, i) => key !== String(i))))
+      throw new RealtimeError2("payload");
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      if (!("value" in descriptor))
+        throw new RealtimeError2("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 RealtimeError2("payload");
+  return text;
+}
+
+export { RealtimeError2, part, resourceTopic, cursorToken, parseCursor, sameCursor, serialize };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type * from "./contracts";
+export { RealtimeError } from "./contracts";
+export { resolveRealtimeConfig } from "./config";
+import { type Realtime, type RealtimeOptions } from "./contracts";
+export declare function createRealtime<P>(options: RealtimeOptions<P>): Promise<Realtime<P>>;

package/dist/index.js

@@ -0,0 +1,12 @@
+import {
+  resolveRealtimeConfig2,
+  createRealtime2
+} from "./index-6fg21p7s.js";
+import {
+  RealtimeError2
+} from "./index-htkqerky.js";
+export {
+  RealtimeError2 as RealtimeError,
+  createRealtime2 as createRealtime,
+  resolveRealtimeConfig2 as resolveRealtimeConfig
+};

package/dist/memory.d.ts

@@ -0,0 +1,5 @@
+import { type RealtimeProvider } from "./contracts";
+export declare function createMemoryProvider(options?: {
+    maxTopics?: number;
+    watermarkTtlMs?: number;
+}): RealtimeProvider;