@lumencast/server 0.1.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@lumencast/server",
+  "version": "0.1.0",
+  "description": "Node server kit for LSDP/1 — HTTP+WS, scene composition, leaf store, server-side adapters, token-agnostic auth hooks.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cli": "./dist/cli.js"
+  },
+  "bin": {
+    "lumencast-js": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "homepage": "https://github.com/Lumencast/lumencast-js/tree/main/packages/server",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Lumencast/lumencast-js.git",
+    "directory": "packages/server"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "ws": "^8.18.0",
+    "@lumencast/protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13",
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b --pretty",
+    "test": "vitest run"
+  }
+}

package/src/adapters/http-poll.ts

@@ -0,0 +1,59 @@
+// http_poll adapter — fetches a URL on an interval and writes the result
+// as leaf-grain patches into a Scene.
+
+import type { LeafPath, LeafValue, Patch } from "@lumencast/protocol";
+import type { Scene } from "../scene.js";
+
+export interface HttpPollOptions {
+  url: string;
+  intervalMs: number;
+  /** Path prefix the adapter writes under — same semantic as `external_adapters[].writes_to` in LSML. */
+  writesTo: LeafPath;
+  /** Extract a flat record of leaf paths from the response. */
+  extract: (response: unknown) => Record<LeafPath, LeafValue>;
+  /** Optional headers (e.g. Authorization). */
+  headers?: Record<string, string>;
+  /** Optional error reporter — defaults to silent. */
+  onError?: (err: unknown) => void;
+}
+
+export function startHttpPoll(scene: Scene, options: HttpPollOptions): () => void {
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  async function tick(): Promise<void> {
+    if (stopped) return;
+    try {
+      const res = await fetch(options.url, { headers: options.headers ?? {} });
+      if (res.ok) {
+        const body = (await res.json()) as unknown;
+        const extracted = options.extract(body);
+        const patches: Patch[] = Object.entries(extracted).map(([path, value]) => ({
+          path: pathJoin(options.writesTo, path),
+          value,
+        }));
+        if (patches.length > 0) scene.update(patches);
+      } else {
+        options.onError?.(new Error(`http_poll non-OK status: ${res.status}`));
+      }
+    } catch (err) {
+      options.onError?.(err);
+    }
+    if (!stopped) {
+      timer = setTimeout(() => void tick(), options.intervalMs);
+    }
+  }
+
+  void tick();
+
+  return () => {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+  };
+}
+
+function pathJoin(prefix: LeafPath, sub: LeafPath): LeafPath {
+  if (prefix.length === 0) return sub;
+  if (sub.length === 0) return prefix;
+  return `${prefix}.${sub}`;
+}

package/src/auth.ts

@@ -0,0 +1,81 @@
+// Auth model — token-agnostic. The server kit only consumes the result of
+// the user-supplied `authenticate` hook. LSDP/1 §8: the protocol does not
+// validate tokens, it transmits them.
+
+import type { LeafPath } from "@lumencast/protocol";
+
+export type Role = "viewer" | "operator" | "service" | "test";
+
+export interface AuthDecision {
+  role: Role;
+  /** For role=service: restrict input writes to this path prefix. Optional. */
+  paths?: LeafPath[];
+  /** Diagnostic — surfaced in logs / metrics, not in the wire frames. */
+  subject?: string;
+}
+
+export type Authenticate = (token: string) => Promise<AuthDecision> | AuthDecision;
+
+/**
+ * Default authenticate — accepts everything as `viewer`.
+ * Useful for local development; never deploy this to production.
+ */
+export const defaultAuthenticate: Authenticate = () => ({ role: "viewer" });
+
+/**
+ * Mutable token → AuthDecision map for test setups (interop control plane).
+ * NEVER use in production — tokens are kept in process memory and any caller
+ * with reset()/setMany() can rewrite the auth store.
+ */
+export class StaticTokens {
+  private readonly map = new Map<string, AuthDecision>();
+
+  /** Authenticate hook bound to this instance. Pass to `startServer()`. */
+  authenticate: Authenticate = (token: string) => {
+    const d = this.map.get(token);
+    if (!d) {
+      throw new (class extends Error {
+        readonly code = "AUTH_DENIED" as const;
+        readonly recoverable = false;
+      })(`unknown token`);
+    }
+    return d;
+  };
+
+  set(token: string, decision: AuthDecision): void {
+    this.map.set(token, decision);
+  }
+
+  setMany(entries: Iterable<[string, AuthDecision]>): void {
+    for (const [t, d] of entries) this.map.set(t, d);
+  }
+
+  delete(token: string): boolean {
+    return this.map.delete(token);
+  }
+
+  reset(): void {
+    this.map.clear();
+  }
+
+  size(): number {
+    return this.map.size;
+  }
+}
+
+/** Returns true if the role is permitted to write to the given path. */
+export function canWritePath(decision: AuthDecision, path: LeafPath): boolean {
+  // Test sessions have their own namespace.
+  if (decision.role === "test") return path.startsWith("__test.");
+  // Viewers can never write.
+  if (decision.role === "viewer") return false;
+  // Operators can write any __inputs.* path.
+  if (decision.role === "operator") return path.startsWith("__inputs.");
+  // Services can write __inputs.* paths, optionally restricted by `paths`.
+  if (decision.role === "service") {
+    if (!path.startsWith("__inputs.")) return false;
+    if (!decision.paths || decision.paths.length === 0) return true;
+    return decision.paths.some((p) => path.startsWith(p));
+  }
+  return false;
+}

package/src/cli.ts

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// lumencast-js server CLI.
+//
+// Subcommands:
+//   serve-scenario --ws-port N --test-control-port M [--host H]
+//     Boots the LSDP/1 server with the interop test control plane on a
+//     separate port. Prints exactly one JSON discovery line on stdout :
+//     {"control_url":"http://...","ws_url":"ws://.../lsdp/v1"}
+//     before any other output, then stays silent on stdout (logs go to stderr).
+
+import { parseArgs } from "node:util";
+import { createScene } from "./scene.js";
+import { startServer, type ServerHandle } from "./server.js";
+import { StaticTokens } from "./auth.js";
+import { startTestControl, type TestControlHandle } from "./test-control.js";
+
+async function main(argv: string[]): Promise<number> {
+  const sub = argv[0];
+  if (!sub || sub === "--help" || sub === "-h") {
+    printUsage();
+    return sub ? 0 : 2;
+  }
+  if (sub === "serve-scenario") return cmdServeScenario(argv.slice(1));
+  process.stderr.write(`lumencast-js: unknown subcommand "${sub}"\n`);
+  printUsage();
+  return 2;
+}
+
+function printUsage(): void {
+  process.stderr.write(
+    [
+      "usage: lumencast-js <subcommand> [flags]",
+      "",
+      "subcommands:",
+      "  serve-scenario --ws-port N --test-control-port M [--host H]",
+      "    Boot LSDP/1 server + interop test control plane (separate ports).",
+      "",
+    ].join("\n"),
+  );
+}
+
+async function cmdServeScenario(args: string[]): Promise<number> {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args,
+      options: {
+        "ws-port": { type: "string" },
+        "test-control-port": { type: "string" },
+        host: { type: "string", default: "127.0.0.1" },
+        help: { type: "boolean", short: "h" },
+      },
+      strict: true,
+      allowPositionals: false,
+    });
+  } catch (err) {
+    process.stderr.write(`serve-scenario: ${(err as Error).message}\n`);
+    return 2;
+  }
+
+  if (parsed.values["help"]) {
+    process.stderr.write("serve-scenario --ws-port N --test-control-port M [--host H]\n");
+    return 0;
+  }
+
+  const wsPort = parseIntFlag(parsed.values["ws-port"], "--ws-port");
+  const controlPort = parseIntFlag(parsed.values["test-control-port"], "--test-control-port");
+  if (wsPort === null || controlPort === null) return 2;
+  const host = (parsed.values["host"] as string | undefined) ?? "127.0.0.1";
+
+  // Bootstrap a synthetic scene + empty bundle provider. Both are immediately
+  // overridden by the first POST /test/setup.
+  const initialScene = createScene({
+    sceneId: "__interop_initial__",
+    sceneVersion: "sha256:" + "0".repeat(64),
+    initialState: {},
+  });
+  const auth = new StaticTokens();
+
+  let server: ServerHandle;
+  let control: TestControlHandle;
+  try {
+    server = await startServer({
+      port: wsPort,
+      host,
+      scene: initialScene,
+      bundleProvider: () => undefined,
+      authenticate: auth.authenticate,
+    });
+  } catch (err) {
+    process.stderr.write(`serve-scenario: bind ws: ${(err as Error).message}\n`);
+    return 1;
+  }
+  try {
+    control = await startTestControl({
+      port: controlPort,
+      host,
+      server,
+      auth,
+    });
+  } catch (err) {
+    await server.close();
+    process.stderr.write(`serve-scenario: bind control: ${(err as Error).message}\n`);
+    return 1;
+  }
+
+  // Discovery line — written before any other stdout output. The matrix
+  // driver greps for "control_url" to know we're ready.
+  process.stdout.write(
+    JSON.stringify({
+      control_url: control.url,
+      ws_url: server.wsUrl,
+    }) + "\n",
+  );
+
+  let shutdown: (() => Promise<void>) | null = async () => {
+    shutdown = null;
+    process.stderr.write("[lumencast-js] shutting down\n");
+    try {
+      await control.close();
+    } catch {
+      // ignore
+    }
+    try {
+      await server.close();
+    } catch {
+      // ignore
+    }
+  };
+
+  process.on("SIGINT", () => void shutdown?.());
+  process.on("SIGTERM", () => void shutdown?.());
+
+  await new Promise<void>((resolve) => {
+    const tick = (): void => {
+      if (shutdown === null) resolve();
+      else setTimeout(tick, 100);
+    };
+    tick();
+  });
+
+  return 0;
+}
+
+function parseIntFlag(raw: unknown, name: string): number | null {
+  if (typeof raw !== "string") {
+    process.stderr.write(`${name} required\n`);
+    return null;
+  }
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 0 || n > 65535) {
+    process.stderr.write(`${name}: invalid port\n`);
+    return null;
+  }
+  return n;
+}
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (err) => {
+    process.stderr.write(`lumencast-js: ${(err as Error).stack ?? String(err)}\n`);
+    process.exitCode = 1;
+  },
+);

package/src/index.ts

@@ -0,0 +1,20 @@
+// Public surface of @lumencast/server.
+
+export { startServer, type ServerConfig, type ServerHandle } from "./server.js";
+export { createScene, type Scene, type SceneInit } from "./scene.js";
+export { LeafStore, type LeafStoreListener } from "./store.js";
+export {
+  defaultAuthenticate,
+  canWritePath,
+  StaticTokens,
+  type Authenticate,
+  type AuthDecision,
+  type Role,
+} from "./auth.js";
+export { startHttpPoll, type HttpPollOptions } from "./adapters/http-poll.js";
+export {
+  startTestControl,
+  installTokens,
+  type TestControlOptions,
+  type TestControlHandle,
+} from "./test-control.js";

package/src/replay-buffer.ts

@@ -0,0 +1,72 @@
+// Per-scene replay buffer (LSDP/1.1 §18.1).
+// Bounded ring of recent (seq, patches, cause) emissions so a 1.1
+// client reconnecting with `since_sequence` can resume without a fresh
+// snapshot.
+
+import type { Cause, Patch } from "@lumencast/protocol";
+
+export interface ReplayRecord {
+  readonly seq: number;
+  readonly patches: Patch[];
+  readonly cause?: Cause;
+}
+
+/** Default capacity (LSDP/1.1 §18.1 SHOULD ≥ 256). */
+export const DEFAULT_REPLAY_BUFFER_SIZE = 256;
+
+export class ReplayBuffer {
+  private readonly cap: number;
+  private readonly records: (ReplayRecord | undefined)[];
+  private head = 0;
+  private size = 0;
+
+  constructor(capacity = DEFAULT_REPLAY_BUFFER_SIZE) {
+    this.cap = capacity > 0 ? capacity : DEFAULT_REPLAY_BUFFER_SIZE;
+    this.records = new Array<ReplayRecord | undefined>(this.cap);
+  }
+
+  /** Record one emission. Caller is responsible for monotonic seq. */
+  push(record: ReplayRecord): void {
+    this.records[this.head] = record;
+    this.head = (this.head + 1) % this.cap;
+    if (this.size < this.cap) this.size++;
+  }
+
+  /**
+   * Return every record with seq > sinceSeq, in monotonic order.
+   *
+   * The boolean is `false` when sinceSeq is older than the buffer's
+   * earliest retained entry — the caller MUST then fall back to a
+   * fresh snapshot per LSDP/1.1 §18.1.
+   */
+  since(sinceSeq: number): { records: ReplayRecord[]; covered: boolean } {
+    if (this.size === 0) {
+      // Empty buffer — caller decides whether sinceSeq matches the
+      // current scene seq (caught up) or warrants a snapshot.
+      return { records: [], covered: true };
+    }
+    const tail = (this.head - this.size + this.cap) % this.cap;
+    const earliest = this.records[tail]!.seq;
+    if (sinceSeq + 1 < earliest) {
+      return { records: [], covered: false };
+    }
+    const out: ReplayRecord[] = [];
+    for (let i = 0; i < this.size; i++) {
+      const idx = (tail + i) % this.cap;
+      const r = this.records[idx]!;
+      if (r.seq > sinceSeq) out.push(r);
+    }
+    return { records: out, covered: true };
+  }
+
+  /** Clear the buffer. Used on scene_changed. */
+  reset(): void {
+    this.head = 0;
+    this.size = 0;
+    this.records.fill(undefined);
+  }
+
+  get length(): number {
+    return this.size;
+  }
+}

package/src/scene.ts

@@ -0,0 +1,168 @@
+// Scene — the server's authoritative view of one Lumencast scene.
+// Wraps a LeafStore + identity (sceneId, sceneVersion) and an optional
+// operator_inputs schema used by the server to validate `input` frames.
+
+import type { Cause, LeafPath, LeafValue, Patch, SceneId, SceneVersion } from "@lumencast/protocol";
+import { LeafStore } from "./store.js";
+import { DEFAULT_REPLAY_BUFFER_SIZE, ReplayBuffer, type ReplayRecord } from "./replay-buffer.js";
+
+export interface OperatorInputDecl {
+  path: LeafPath;
+  /** "string" | "number" | "boolean" | "enum" | ... — see LSML 1.0 §8. */
+  type: string;
+  /** Type-specific constraints — currently maxLength, minLength, min, max, pattern. */
+  constraints?: {
+    maxLength?: number;
+    minLength?: number;
+    min?: number;
+    max?: number;
+    pattern?: string;
+  };
+  values?: unknown[];
+  writable_by?: string[];
+  [extra: string]: unknown;
+}
+
+export interface SceneInit {
+  sceneId: SceneId;
+  sceneVersion: SceneVersion;
+  initialState?: Record<LeafPath, LeafValue>;
+  /** Declared operator inputs. When set, `validateInput` enforces the schema. */
+  operatorInputs?: OperatorInputDecl[];
+}
+
+export type ValidationError =
+  | { code: "UNKNOWN_PATH"; path: LeafPath; message: string }
+  | { code: "INVALID_VALUE"; path: LeafPath; message: string };
+
+export interface Scene {
+  readonly sceneId: SceneId;
+  readonly sceneVersion: SceneVersion;
+  readonly store: LeafStore;
+  readonly operatorInputs: OperatorInputDecl[];
+  /** Update one or more leaves. Atomic per call. Optional `cause` propagates
+   * to subscribers as the resulting Delta.cause (LSDP/1.1 §3.2.3). */
+  update(patches: Patch[] | Record<LeafPath, LeafValue>, cause?: Cause): void;
+  /** Subscribe to all patches emitted by this scene. The listener receives
+   * the per-scene `seq` (LSDP/1.1 §18.1.1) — the same value across all
+   * concurrent listeners on a given delta. */
+  onPatches(listener: (seq: number, patches: Patch[], cause?: Cause) => void): () => void;
+  /** Current per-scene seq counter (LSDP/1.1 §18.1.1). 1 on a fresh
+   * scene ; increments on every emit. Late-joining subscribers ship
+   * snapshot at this value. */
+  currentSeq(): number;
+  /** Replay records strictly after `sinceSeq` for §18.1 resume.
+   * Returns `covered: false` when sinceSeq is older than the buffer's
+   * earliest entry — the caller MUST fall back to a fresh snapshot. */
+  replaySince(sinceSeq: number): { records: ReplayRecord[]; covered: boolean };
+  /**
+   * Validate input patches against the declared operator_inputs schema.
+   * Returns the first error or null. The reserved `__test.*` namespace is
+   * always permitted (test sessions own that namespace per LSDP/1 §10).
+   */
+  validateInput(patches: Patch[]): ValidationError | null;
+}
+
+export function createScene(init: SceneInit): Scene {
+  const store = new LeafStore(init.initialState ?? {});
+  const operatorInputs = init.operatorInputs ?? [];
+  const inputsByPath = new Map<LeafPath, OperatorInputDecl>();
+  for (const oi of operatorInputs) inputsByPath.set(oi.path, oi);
+
+  // LSDP/1.1 §18.1.1 — per-scene monotonic seq. Pre-seeded to 1 so the
+  // very first subscriber's snapshot ships at seq=1 (matches every
+  // existing 1.0 conformance scenario). Subsequent emits increment.
+  let seq = 1;
+  const replay = new ReplayBuffer(DEFAULT_REPLAY_BUFFER_SIZE);
+  type SceneListener = (seq: number, patches: Patch[], cause?: Cause) => void;
+  const sceneListeners = new Set<SceneListener>();
+
+  // Bridge LeafStore.onPatches → scene listeners. Single store listener
+  // increments `seq`, records to the buffer, fans out to scene listeners.
+  store.onPatches((patches, cause) => {
+    seq += 1;
+    replay.push({ seq, patches: patches.slice(), cause });
+    for (const l of sceneListeners) l(seq, patches, cause);
+  });
+
+  function update(input: Patch[] | Record<LeafPath, LeafValue>, cause?: Cause): void {
+    const patches: Patch[] = Array.isArray(input)
+      ? input
+      : Object.entries(input).map(([path, value]) => ({ path, value }));
+    store.apply(patches, cause);
+  }
+
+  function validateInput(patches: Patch[]): ValidationError | null {
+    // No declared schema → server accepts any path (legacy / dev-mode behavior).
+    if (operatorInputs.length === 0) return null;
+
+    for (const p of patches) {
+      if (p.path.startsWith("__test.")) continue; // test namespace bypass
+      const decl = inputsByPath.get(p.path);
+      if (!decl) {
+        return {
+          code: "UNKNOWN_PATH",
+          path: p.path,
+          message: `path ${p.path} not declared in operator_inputs`,
+        };
+      }
+      const err = checkConstraint(decl, p.value);
+      if (err) return { code: "INVALID_VALUE", path: p.path, message: err };
+    }
+    return null;
+  }
+
+  return {
+    sceneId: init.sceneId,
+    sceneVersion: init.sceneVersion,
+    store,
+    operatorInputs,
+    update,
+    onPatches: (listener) => {
+      sceneListeners.add(listener);
+      return () => {
+        sceneListeners.delete(listener);
+      };
+    },
+    currentSeq: () => seq,
+    replaySince: (sinceSeq) => replay.since(sinceSeq),
+    validateInput,
+  };
+}
+
+function checkConstraint(decl: OperatorInputDecl, value: unknown): string | null {
+  switch (decl.type) {
+    case "string":
+    case "text":
+      if (typeof value !== "string") return `expected string, got ${typeof value}`;
+      if (decl.constraints?.maxLength !== undefined && value.length > decl.constraints.maxLength) {
+        return `exceeds maxLength ${decl.constraints.maxLength}`;
+      }
+      if (decl.constraints?.minLength !== undefined && value.length < decl.constraints.minLength) {
+        return `below minLength ${decl.constraints.minLength}`;
+      }
+      if (decl.constraints?.pattern && !new RegExp(decl.constraints.pattern).test(value)) {
+        return `does not match pattern`;
+      }
+      return null;
+    case "number":
+      if (typeof value !== "number") return `expected number, got ${typeof value}`;
+      if (decl.constraints?.min !== undefined && value < decl.constraints.min) {
+        return `below min ${decl.constraints.min}`;
+      }
+      if (decl.constraints?.max !== undefined && value > decl.constraints.max) {
+        return `above max ${decl.constraints.max}`;
+      }
+      return null;
+    case "boolean":
+      if (typeof value !== "boolean") return `expected boolean, got ${typeof value}`;
+      return null;
+    case "enum":
+      if (decl.values && !decl.values.includes(value)) {
+        return `not in enum`;
+      }
+      return null;
+    default:
+      return null;
+  }
+}