cursedbelt 2.8.0 → 3.0.0

package/src/client/stream/stream.spec.ts

@@ -1,396 +0,0 @@
-/**
- * The client push tier. The properties under test are the ones `EventSource`
- * cannot give: a jittered reconnect loop that stops when told to, and a
- * lifecycle host that keeps the dirty ledger fed while no pane is mounted.
- */
-import { describe, expect, it } from 'bun:test';
-import { createReconnectSchedule } from '../../core/net/reconnectSchedule';
-import { createInstanceRuntime, createWireHub } from '../../core/wire/wireHub';
-import { createContextSyncBroker, nullSyncTransport, VAULT_LOCKED_CHANNEL } from '../contextSyncBroker';
-import { type CcStreamEvent, openCcEventSource, parseSseFrames } from './ccEventSource';
-import { type CdcFrame, createInstanceStreamHost } from './instanceStream';
-
-const sseResponse = (body: string): Response =>
-  new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream' } });
-
-describe('parseSseFrames', () => {
-  it('decodes an event/data pair', () => {
-    const { frames, rest } = parseSseFrames('event: cdc\ndata: {"rowId":"note_1"}\n\n');
-    expect(frames).toEqual([{ event: 'cdc', data: { rowId: 'note_1' } }]);
-    expect(rest).toBe('');
-  });
-
-  it('keeps a partial frame in the buffer until it completes', () => {
-    const first = parseSseFrames('event: cdc\ndata: {"a"');
-    expect(first.frames).toEqual([]);
-
-    const second = parseSseFrames(`${first.rest}:1}\n\n`);
-    expect(second.frames).toEqual([{ event: 'cdc', data: { a: 1 } }]);
-  });
-
-  it('swallows heartbeats and the retry hint rather than waking a handler', () => {
-    const { frames } = parseSseFrames(': keep-alive\n\nretry: 500\n\nevent: ready\ndata: {}\n\n');
-    expect(frames).toEqual([{ event: 'ready', data: {} }]);
-  });
-
-  it('delivers a non-JSON payload as raw text instead of dropping it', () => {
-    const { frames } = parseSseFrames('event: note\ndata: hello\n\n');
-    expect(frames).toEqual([{ event: 'note', data: 'hello' }]);
-  });
-
-  it('decodes several frames from one chunk', () => {
-    const { frames } = parseSseFrames('event: a\ndata: 1\n\nevent: b\ndata: 2\n\n');
-    expect(frames.map((f) => f.event)).toEqual(['a', 'b']);
-  });
-});
-
-describe('openCcEventSource', () => {
-  it('delivers frames from a live stream', async () => {
-    const seen: CcStreamEvent[] = [];
-    const source = openCcEventSource({
-      url: '/api/core/stream',
-      fetchImpl: (async () => sseResponse('event: ready\ndata: {"ok":true}\n\n')) as unknown as typeof fetch,
-      onEvent: (event) => seen.push(event),
-      setTimeoutFn: () => 1,
-      clearTimeoutFn: () => undefined,
-    });
-
-    await Bun.sleep(5);
-    expect(seen).toEqual([{ event: 'ready', data: { ok: true } }]);
-    source.close();
-  });
-
-  it('presents the bearer token on every connection', async () => {
-    const headers: Array<Record<string, string>> = [];
-    const source = openCcEventSource({
-      url: '/api/core/stream',
-      token: 'tok',
-      fetchImpl: (async (_url: string, init: RequestInit) => {
-        headers.push(init.headers as Record<string, string>);
-        return sseResponse('');
-      }) as unknown as typeof fetch,
-      onEvent: () => undefined,
-      setTimeoutFn: () => 1,
-      clearTimeoutFn: () => undefined,
-    });
-
-    await Bun.sleep(5);
-    expect(headers[0]?.authorization).toBe('Bearer tok');
-    source.close();
-  });
-
-  it('reads a token GETTER at every connection, so a stream opened signed-out can present a later session', async () => {
-    // The failure this pins: the tab mounts its stream before the user signs in.
-    // With a token captured at construction, that stream stays anonymous
-    // forever — and `bridgeCdcToPush` scopes every CDC frame to a tenant, so an
-    // anonymous subscriber receives NOTHING a real write produces.
-    let token: string | null = null;
-    const presented: Array<string | undefined> = [];
-    const source = openCcEventSource({
-      url: '/api/core/stream',
-      token: () => token,
-      fetchImpl: (async (_url: string, init: RequestInit) => {
-        presented.push((init.headers as Record<string, string>).authorization);
-        return sseResponse('');
-      }) as unknown as typeof fetch,
-      onEvent: () => undefined,
-      setTimeoutFn: () => 1,
-      clearTimeoutFn: () => undefined,
-    });
-
-    await Bun.sleep(5);
-    expect(presented[0]).toBeUndefined();
-
-    token = 'minted-after-mount';
-    source.reconnect();
-    await Bun.sleep(5);
-    expect(presented[1]).toBe('Bearer minted-after-mount');
-    source.close();
-  });
-
-  it('reconnect() leaves exactly ONE live connection — the aborted attempt does not also retry', async () => {
-    let connections = 0;
-    const pending: Array<() => void> = [];
-    const source = openCcEventSource({
-      url: '/api/core/stream',
-      // Never resolves until aborted: the shape of a real, open SSE read.
-      fetchImpl: ((_url: string, init: RequestInit) =>
-        new Promise((_resolve, reject) => {
-          connections += 1;
-          init.signal?.addEventListener('abort', () => reject(new Error('aborted')));
-        })) as unknown as typeof fetch,
-      onEvent: () => undefined,
-      setTimeoutFn: (fn) => {
-        pending.push(fn);
-        return pending.length;
-      },
-      clearTimeoutFn: () => undefined,
-    });
-
-    await Bun.sleep(5);
-    expect(connections).toBe(1);
-
-    source.reconnect();
-    await Bun.sleep(5);
-    // Two connections: the new one. NOT three — the aborted attempt's tail must
-    // not schedule a retry of its own, or one sign-in doubles the readers.
-    expect(connections).toBe(2);
-    expect(pending).toHaveLength(0);
-    source.close();
-  });
-
-  it('reconnects on the JITTERED schedule, not a fixed interval', async () => {
-    const delays: number[] = [];
-    let connections = 0;
-    const source = openCcEventSource({
-      url: '/api/core/stream',
-      fetchImpl: (async () => {
-        connections += 1;
-        return sseResponse('');
-      }) as unknown as typeof fetch,
-      onEvent: () => undefined,
-      // A deterministic "random" so the assertion is about the CEILING growing,
-      // which is what separates backoff from a fixed interval.
-      schedule: createReconnectSchedule({ random: () => 1 }),
-      setTimeoutFn: (fn, ms) => {
-        delays.push(ms);
-        // Only let the first few retries actually run.
-        if (delays.length <= 2) queueMicrotask(fn);
-        return delays.length;
-      },
-      clearTimeoutFn: () => undefined,
-    });
-
-    await Bun.sleep(20);
-    source.close();
-
-    expect(connections).toBeGreaterThan(1);
-    expect(delays.length).toBeGreaterThan(1);
-    expect(delays[1]).toBeGreaterThan(delays[0] as number);
-  });
-
-  it('stops retrying once closed', async () => {
-    let connections = 0;
-    let pending: (() => void) | null = null;
-    const source = openCcEventSource({
-      url: '/api/core/stream',
-      fetchImpl: (async () => {
-        connections += 1;
-        return sseResponse('');
-      }) as unknown as typeof fetch,
-      onEvent: () => undefined,
-      setTimeoutFn: (fn) => {
-        pending = fn;
-        return 1;
-      },
-      clearTimeoutFn: () => {
-        pending = null;
-      },
-    });
-
-    await Bun.sleep(5);
-    source.close();
-    expect(source.status()).toBe('closed');
-
-    // A retry that fired after close must not reopen the stream.
-    (pending as (() => void) | null)?.();
-    await Bun.sleep(5);
-    expect(connections).toBe(1);
-  });
-
-  it('retries a non-ok response rather than treating it as a stream', async () => {
-    let attempts = 0;
-    const source = openCcEventSource({
-      url: '/api/core/stream',
-      fetchImpl: (async () => {
-        attempts += 1;
-        return new Response('nope', { status: 503 });
-      }) as unknown as typeof fetch,
-      onEvent: () => undefined,
-      setTimeoutFn: (fn) => {
-        if (attempts < 2) queueMicrotask(fn);
-        return 1;
-      },
-      clearTimeoutFn: () => undefined,
-    });
-
-    await Bun.sleep(10);
-    source.close();
-    expect(attempts).toBeGreaterThan(1);
-  });
-});
-
-describe('createInstanceStreamHost', () => {
-  const cdc = (rev: number): CdcFrame => ({
-    domain: 'knowledge',
-    table: 'k_items',
-    op: 'update',
-    rowId: 'note_1',
-    rev,
-    at: '2026-07-22T00:00:00.000Z',
-  });
-
-  /** A stream seam that hands the test the event sink. */
-  const controllableStream = () => {
-    let emit: ((event: CcStreamEvent) => void) | null = null;
-    let closed = false;
-    let reconnects = 0;
-    const open = ((options: { onEvent: (event: CcStreamEvent) => void }) => {
-      emit = options.onEvent;
-      return {
-        status: () => 'open' as const,
-        attempt: () => 0,
-        reconnect: () => {
-          reconnects += 1;
-        },
-        close: () => {
-          closed = true;
-        },
-      };
-    }) as unknown as typeof openCcEventSource;
-    return {
-      open,
-      send: (event: CcStreamEvent) => emit?.(event),
-      isClosed: () => closed,
-      reconnects: () => reconnects,
-    };
-  };
-
-  it('runs the lifecycle hooks in order before the stream opens', async () => {
-    const hub = createWireHub();
-    const runtime = createInstanceRuntime({ id: 'notes', hub, intakeChannels: ['cdc:knowledge.k_items'] });
-    const stream = controllableStream();
-    const host = createInstanceStreamHost({ runtime, hub, url: '/s', openStream: stream.open });
-
-    expect(runtime.phase()).toBe('created');
-    await host.start();
-    expect(runtime.phase()).toBe('ready');
-    expect(runtime.lifecycleErrors()).toEqual([]);
-  });
-
-  it('reconnect() re-opens the stream, and is inert before start and after unmount', async () => {
-    const hub = createWireHub();
-    const runtime = createInstanceRuntime({ id: 'notes', hub, intakeChannels: ['cdc:knowledge.k_items'] });
-    const stream = controllableStream();
-    const host = createInstanceStreamHost({ runtime, hub, url: '/s', openStream: stream.open });
-
-    // Before start there is no stream to re-open — a sign-in that races mount
-    // must not throw.
-    host.reconnect();
-    expect(stream.reconnects()).toBe(0);
-
-    await host.start();
-    host.reconnect();
-    expect(stream.reconnects()).toBe(1);
-
-    host.unmount();
-    host.reconnect();
-    expect(stream.reconnects()).toBe(1);
-  });
-
-  it('marks the ledger dirty from a server CDC frame — the change no pane saw', async () => {
-    const hub = createWireHub();
-    const runtime = createInstanceRuntime({ id: 'notes', hub, intakeChannels: ['cdc:knowledge.k_items'] });
-    const stream = controllableStream();
-    const host = createInstanceStreamHost({ runtime, hub, url: '/s', openStream: stream.open });
-    await host.start();
-
-    stream.send({ event: 'cdc', data: cdc(7) });
-
-    expect(runtime.ledger().get('cdc:knowledge.k_items')).toEqual({ dirty: true, lastRev: 7 });
-    // A pane mounting now pulls the change it slept through.
-    expect(host.pullIfDirty('cdc:knowledge.k_items', -1)?.rev).toBe(7);
-  });
-
-  it('is idempotent against a redelivered frame — settle keys on rev', async () => {
-    const hub = createWireHub();
-    const runtime = createInstanceRuntime({ id: 'notes', hub, intakeChannels: ['cdc:knowledge.k_items'] });
-    const stream = controllableStream();
-    const host = createInstanceStreamHost({ runtime, hub, url: '/s', openStream: stream.open });
-    await host.start();
-
-    const seen: number[] = [];
-    hub.subscribe<CdcFrame>('cdc:knowledge.k_items', (envelope) => seen.push(envelope.rev));
-
-    stream.send({ event: 'cdc', data: cdc(3) });
-    stream.send({ event: 'cdc', data: cdc(3) });
-
-    expect(seen).toEqual([3]);
-  });
-
-  it('routes a CDC frame through a host-supplied channel map', async () => {
-    const hub = createWireHub();
-    const runtime = createInstanceRuntime({ id: 'notes', hub, intakeChannels: ['notes:refresh'] });
-    const stream = controllableStream();
-    const host = createInstanceStreamHost({
-      runtime,
-      hub,
-      url: '/s',
-      openStream: stream.open,
-      channelsForCdc: () => ['notes:refresh'],
-    });
-    await host.start();
-
-    stream.send({ event: 'cdc', data: cdc(1) });
-    expect(runtime.ledger().get('notes:refresh')?.dirty).toBe(true);
-  });
-
-  it('re-broadcasts VAULT_LOCKED across tabs rather than handling it locally', async () => {
-    const hub = createWireHub();
-    const runtime = createInstanceRuntime({ id: 'notes', hub, intakeChannels: [] });
-    const stream = controllableStream();
-    const posted: unknown[] = [];
-    const sync = createContextSyncBroker({
-      name: 'test',
-      transport: { ...nullSyncTransport(), post: (diff) => posted.push(diff) },
-    });
-    const host = createInstanceStreamHost({ runtime, hub, url: '/s', openStream: stream.open, sync });
-    await host.start();
-
-    stream.send({ event: 'lifecycle', data: { type: 'VAULT_LOCKED' } });
-
-    expect(posted).toHaveLength(1);
-    expect((posted[0] as { channel: string }).channel).toBe(VAULT_LOCKED_CHANNEL);
-  });
-
-  it('surfaces job completions', async () => {
-    const hub = createWireHub();
-    const runtime = createInstanceRuntime({ id: 'notes', hub, intakeChannels: [] });
-    const stream = controllableStream();
-    const jobs: unknown[] = [];
-    const host = createInstanceStreamHost({ runtime, hub, url: '/s', openStream: stream.open, onJob: (j) => jobs.push(j) });
-    await host.start();
-
-    stream.send({ event: 'job', data: { jobId: 'job_1', ok: true } });
-    expect(jobs).toEqual([{ jobId: 'job_1', ok: true }]);
-  });
-
-  it('keeps intake alive across a suspend — that is the whole two-tier point', async () => {
-    const hub = createWireHub();
-    const runtime = createInstanceRuntime({ id: 'notes', hub, intakeChannels: ['cdc:knowledge.k_items'] });
-    const stream = controllableStream();
-    const host = createInstanceStreamHost({ runtime, hub, url: '/s', openStream: stream.open });
-    await host.start();
-
-    host.suspend();
-    stream.send({ event: 'cdc', data: cdc(9) });
-
-    expect(stream.isClosed()).toBe(false);
-    expect(runtime.ledger().get('cdc:knowledge.k_items')).toEqual({ dirty: true, lastRev: 9 });
-  });
-
-  it('closes the stream and unsubscribes intake at unmount', async () => {
-    const hub = createWireHub();
-    const runtime = createInstanceRuntime({ id: 'notes', hub, intakeChannels: ['cdc:knowledge.k_items'] });
-    const stream = controllableStream();
-    const host = createInstanceStreamHost({ runtime, hub, url: '/s', openStream: stream.open });
-    await host.start();
-
-    host.unmount();
-
-    expect(stream.isClosed()).toBe(true);
-    expect(runtime.phase()).toBe('unmounted');
-    expect(hub.listenerCount('cdc:knowledge.k_items')).toBe(0);
-    expect(runtime.lifecycleErrors()).toEqual([]);
-  });
-});

package/src/client/ws.spec.ts

@@ -1,71 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import {
-  buildChannelSocketUrl,
-  createChannelSocket,
-  parseWsMessage,
-  sendWsMessage,
-  type WsLocation,
-} from './ws';
-
-const httpsLoc: WsLocation = { protocol: 'https:', host: 'app.example.com' };
-const httpLoc: WsLocation = { protocol: 'http:', host: 'localhost:3000' };
-
-describe('buildChannelSocketUrl', () => {
-  test('wss on https, ws on http', () => {
-    expect(buildChannelSocketUrl('chat', undefined, httpsLoc)).toBe(
-      'wss://app.example.com/ws/chat',
-    );
-    expect(buildChannelSocketUrl('chat', undefined, httpLoc)).toBe('ws://localhost:3000/ws/chat');
-  });
-
-  test('appends ?room= when a room is given, url-encoding both segments', () => {
-    expect(buildChannelSocketUrl('game room', 'r 1', httpLoc)).toBe(
-      'ws://localhost:3000/ws/game%20room?room=r%201',
-    );
-  });
-});
-
-describe('parseWsMessage', () => {
-  test('parses a valid { event, data } envelope', () => {
-    expect(parseWsMessage('{"event":"m","data":{"n":1}}')).toEqual({ event: 'm', data: { n: 1 } });
-  });
-
-  test('returns null for non-JSON, non-envelope, and non-string input', () => {
-    expect(parseWsMessage('not json')).toBeNull();
-    expect(parseWsMessage('{"data":1}')).toBeNull(); // missing event
-    expect(parseWsMessage('123')).toBeNull(); // not an object
-    expect(parseWsMessage({ event: 'm', data: 1 })).toBeNull(); // not a raw string frame
-  });
-});
-
-describe('sendWsMessage', () => {
-  test('serializes the { event, data } envelope through the socket', () => {
-    const sent: string[] = [];
-    // A BLOCK body, and the real return type: `ReconnectingWebSocket.send` answers
-    // whether the frame went out, and a concise arrow was quietly returning
-    // `Array.push`'s new length in its place.
-    sendWsMessage(
-      {
-        send: (p) => {
-          sent.push(String(p));
-          return true;
-        },
-      },
-      'chat:send',
-      { body: 'hi' },
-    );
-    expect(sent).toEqual(['{"event":"chat:send","data":{"body":"hi"}}']);
-  });
-});
-
-describe('createChannelSocket', () => {
-  test('constructs a reconnecting socket (startClosed avoids a live connection in tests)', () => {
-    const socket = createChannelSocket('chat', 'lobby', {
-      location: httpLoc,
-      socketOptions: { startClosed: true },
-    });
-    expect(typeof socket.send).toBe('function');
-    expect(typeof socket.close).toBe('function');
-    socket.close();
-  });
-});

package/src/client/ws.ts

@@ -1,58 +0,0 @@
-import ReconnectingWebSocket, { type Options as ReconnectingOptions } from 'partysocket/ws';
-
-/*
- * The browser half of the WS hub: a partysocket-backed channel socket with automatic
- * reconnection (exponential backoff) that speaks the hub's `{ event, data }` wire
- * envelope. Per-feature hooks (useChatSocket, presence, …) are app-business and build
- * on this primitive (tasks 32/36/40); they replace the old hand-rolled `new WebSocket(…)`.
- *
- * We use partysocket's `ReconnectingWebSocket` (the `WebSocket` named export) — a drop-in
- * reconnecting socket over a plain URL — rather than the default `PartySocket`, whose
- * `/parties/<name>/<room>` URL scheme + `_pk` query param are PartyKit-server-specific.
- * Our hub serves a plain `/ws/:channel`, so the URL primitive is the right fit. Same-origin
- * browser WS handshakes carry the httpOnly auth cookie automatically — no extra config.
- */
-
-/*
- * 🔴 The URL builder and the two envelope helpers MOVED to `./wsWire` and are
- * re-exported below, so this module's public surface is unchanged. They are pure
- * and this file is not: `partysocket` is an OPTIONAL peer, so an app that brings
- * its own socket could not reach the envelope without taking the library. See
- * that file's header.
- */
-export {
-  buildChannelSocketUrl,
-  parseWsMessage,
-  sendWsMessage,
-  type WsLocation,
-  type WsMessage,
-} from './wsWire';
-import { buildChannelSocketUrl, type WsLocation } from './wsWire';
-
-export interface CreateChannelSocketOptions {
-  /** Override the page location (tests / SSR). Defaults to `window.location`. */
-  location?: WsLocation;
-  /** Passed through to partysocket's `ReconnectingWebSocket` (backoff tuning, `startClosed`, …). */
-  socketOptions?: ReconnectingOptions;
-}
-
-/**
- * Open an auto-reconnecting socket to the hub's `channel` (optionally scoped to `roomId`).
- * The returned socket is a standard `WebSocket`-shaped object (`send`/`close`/`addEventListener`)
- * that reconnects on drop with exponential backoff. Pair sends with {@link sendWsMessage} and
- * reads with {@link parseWsMessage}.
- */
-export function createChannelSocket(
-  channel: string,
-  roomId?: string,
-  opts: CreateChannelSocketOptions = {},
-): ReconnectingWebSocket {
-  const loc = opts.location ?? window.location;
-  return new ReconnectingWebSocket(
-    buildChannelSocketUrl(channel, roomId, loc),
-    undefined,
-    opts.socketOptions,
-  );
-}
-
-export type { ReconnectingWebSocket };

package/src/client/wsWire.ts

@@ -1,83 +0,0 @@
-/**
- * The WS hub's WIRE, with no socket attached.
- *
- * ── Why this is a module of its own ─────────────────────────────────────────
- * `./ws` imports `partysocket/ws` at the top of the file to build the
- * auto-reconnecting socket. `partysocket` is an OPTIONAL peer of cursedbelt, so
- * a consumer that brings its own socket — because it already has a reconnect
- * strategy, or because its entry chunk is measured to the byte and it will not
- * spend it on a reconnect library — could not touch the URL builder or the
- * envelope helpers without pulling the library in. They are twenty lines of pure
- * string handling and they were only ever in that file because they were written
- * on the same afternoon.
- *
- * So: the WIRE lives here and is free of dependencies, and `./ws` re-exports it
- * beside the socket factory. Nothing moved for the callers that already had it —
- * `cursedbelt/client` still exports all of it from one place — and the split is
- * what makes `cursedbelt/client/ws-wire` a thing an app can import.
- *
- * 🔴 The contract is that the envelope has ONE definition. An app that hand-rolls
- * `JSON.stringify({ event, data })` is an app whose frames drift from the hub's
- * the day the envelope gains a field, and the drift presents as a message the
- * server silently ignores — `createWsHub` returns from `message` rather than
- * throwing, on purpose. Take the helpers.
- *
- * `apps/family` (cursed-satellites) is the first consumer of this subpath.
- */
-
-/** The minimal shape of `window.location` {@link buildChannelSocketUrl} needs. Injectable
- * so the URL builder is pure + testable (no `window` at module scope). */
-export interface WsLocation {
-  protocol: string;
-  host: string;
-}
-
-/** The hub's wire envelope, mirroring `cursedbelt/server`'s `WsMessage`. Re-declared here
- * (not imported) because the server module is Bun-typed and must not leak into the browser
- * surface. */
-export interface WsMessage<T = unknown> {
-  event: string;
-  data: T;
-}
-
-/** Build the `ws(s)://host/ws/<channel>[?room=<roomId>]` URL the hub upgrades. `wss` is
- * chosen iff the page is `https`. Pure — pass `loc` in tests. */
-export function buildChannelSocketUrl(
-  channel: string,
-  roomId: string | undefined,
-  loc: WsLocation,
-): string {
-  const scheme = loc.protocol === 'https:' ? 'wss' : 'ws';
-  const base = `${scheme}://${loc.host}/ws/${encodeURIComponent(channel)}`;
-  return roomId ? `${base}?room=${encodeURIComponent(roomId)}` : base;
-}
-
-/** Send a `{ event, data }` frame the hub understands. */
-export function sendWsMessage(
-  socket: { send(data: string): void },
-  event: string,
-  data: unknown,
-): void {
-  socket.send(JSON.stringify({ event, data }));
-}
-
-/** Parse an inbound frame into a `{ event, data }` envelope, or `null` if it isn't valid
- * JSON of that shape (so a stray non-envelope frame can't throw in a message handler). */
-export function parseWsMessage<T = unknown>(raw: unknown): WsMessage<T> | null {
-  if (typeof raw !== 'string') return null;
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return null;
-  }
-  if (
-    parsed &&
-    typeof parsed === 'object' &&
-    'event' in parsed &&
-    typeof parsed.event === 'string'
-  ) {
-    return parsed as WsMessage<T>;
-  }
-  return null;
-}