@graphorin/server 0.5.0

package/dist/ws/dispatcher.js

@@ -0,0 +1,303 @@
+import { createDeliveryCommentarySanitizer } from "../commentary/sanitizer.js";
+import "../commentary/index.js";
+import { createReplayBuffer } from "./replay-buffer.js";
+import { isSubjectAllowed, tryParseSubject } from "./subjects.js";
+import { ServerMessageSchema, isEventFrame } from "@graphorin/protocol";
+
+//#region src/ws/dispatcher.ts
+/**
+* Per-server WebSocket dispatcher. Owns the in-memory subscription
+* map, fans out events to matching connections, applies the
+* delivery-layer commentary-phase trace sanitization, validates
+* outbound frames against the `@graphorin/protocol` schema, and
+* exposes a tiny `emit(subject, event)` surface route handlers
+* (and the agent / workflow runtimes) consume.
+*
+* @packageDocumentation
+*/
+/**
+* Build a fresh dispatcher.
+*
+* @stable
+*/
+function createWsDispatcher(options = {}) {
+	const sanitizer = createDeliveryCommentarySanitizer(options.commentary);
+	const replayBuffer = createReplayBuffer(options.replayBuffer ?? {});
+	const now = options.now ?? Date.now;
+	const onWarn = options.onWarn;
+	const perConnectionQueueLimit = options.perConnectionQueueLimit ?? 1e3;
+	const subscribers = /* @__PURE__ */ new Map();
+	const subscriptions = /* @__PURE__ */ new Map();
+	const subjectIndex = /* @__PURE__ */ new Map();
+	let eventCounter = 0;
+	function indexSubject(subject, subscriptionId) {
+		let set = subjectIndex.get(subject);
+		if (set === void 0) {
+			set = /* @__PURE__ */ new Set();
+			subjectIndex.set(subject, set);
+		}
+		set.add(subscriptionId);
+	}
+	function deindexSubject(subject, subscriptionId) {
+		const set = subjectIndex.get(subject);
+		if (set === void 0) return;
+		set.delete(subscriptionId);
+		if (set.size === 0) subjectIndex.delete(subject);
+	}
+	function nextEventId() {
+		eventCounter += 1;
+		return `evt-${now().toString(36)}-${eventCounter.toString(36)}`;
+	}
+	function dispatchToSubscriber(record, frame) {
+		const subscriber = subscribers.get(record.subscriberId);
+		if (subscriber === void 0 || subscriber.closed) return;
+		const buffered = typeof subscriber.handle.bufferedAmount === "function" ? subscriber.handle.bufferedAmount() : 0;
+		if (subscriber.outstandingEvents >= perConnectionQueueLimit || buffered >= perConnectionQueueLimit * 1024) {
+			onWarn?.({
+				kind: "queue-overflow",
+				subscriptionId: record.subscriptionId
+			});
+			shutdownSubscriber(subscriber, 4006, "flow.throttled");
+			return;
+		}
+		subscriber.outstandingEvents += 1;
+		try {
+			subscriber.handle.send(frame);
+		} catch (err) {
+			onWarn?.({
+				kind: "queue-overflow",
+				subscriptionId: record.subscriptionId
+			});
+			shutdownSubscriber(subscriber, 4006, "flow.throttled");
+		} finally {
+			subscriber.outstandingEvents = Math.max(0, subscriber.outstandingEvents - 1);
+		}
+	}
+	function shutdownSubscriber(subscriber, code, reason) {
+		if (subscriber.closed) return;
+		subscriber.closed = true;
+		try {
+			subscriber.handle.close(code, reason);
+		} catch {}
+		for (const id of subscriber.subscriptions) {
+			const sub = subscriptions.get(id);
+			if (sub !== void 0) {
+				deindexSubject(sub.subject, id);
+				subscriptions.delete(id);
+			}
+		}
+		subscriber.subscriptions.clear();
+		subscribers.delete(subscriber.handle.id);
+	}
+	function validateAndDispatch(record, frame) {
+		const validated = ServerMessageSchema.safeParse(frame);
+		if (!validated.success) {
+			onWarn?.({
+				kind: "invalid-frame",
+				subscriptionId: record.subscriptionId,
+				issues: validated.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
+			});
+			return;
+		}
+		dispatchToSubscriber(record, validated.data);
+	}
+	function registerSubscriber(handle) {
+		subscribers.set(handle.id, {
+			handle,
+			subscriptions: /* @__PURE__ */ new Set(),
+			outstandingEvents: 0,
+			closed: false
+		});
+		return { unregister: () => {
+			const record = subscribers.get(handle.id);
+			if (record === void 0) return;
+			for (const id of record.subscriptions) {
+				const sub = subscriptions.get(id);
+				if (sub !== void 0) {
+					deindexSubject(sub.subject, id);
+					subscriptions.delete(id);
+				}
+			}
+			subscribers.delete(handle.id);
+		} };
+	}
+	function subscribe(input) {
+		const subscriber = subscribers.get(input.subscriberId);
+		if (subscriber === void 0) return {
+			ok: false,
+			reason: "subject-unknown"
+		};
+		const parseResult = tryParseSubject(input.subject);
+		if (!parseResult.ok) {
+			const reason = parseResult.reason;
+			onWarn?.({
+				kind: "subject-rejected",
+				subject: input.subject,
+				reason
+			});
+			if (reason === "wildcard-not-supported") return {
+				ok: false,
+				reason: "subject-wildcard"
+			};
+			if (reason === "unknown-subject") return {
+				ok: false,
+				reason: "subject-unknown"
+			};
+			return {
+				ok: false,
+				reason: "subject-malformed"
+			};
+		}
+		if (!isSubjectAllowed(subscriber.handle.grantedScopes, parseResult.subject)) return {
+			ok: false,
+			reason: "scope-denied"
+		};
+		const record = {
+			subscriberId: input.subscriberId,
+			tokenId: subscriber.handle.tokenId,
+			subscriptionId: input.subscriptionId,
+			subject: input.subject,
+			parsed: parseResult.subject,
+			createdAt: now(),
+			lastEventId: void 0
+		};
+		subscriptions.set(input.subscriptionId, record);
+		subscriber.subscriptions.add(input.subscriptionId);
+		indexSubject(input.subject, input.subscriptionId);
+		const replay = replayBuffer.replay(input.subject, input.sinceEventId);
+		let replayed = 0;
+		let snapshotEventId = replay.nextEventIdHint;
+		for (const event of replay.events) {
+			const frame = {
+				...event,
+				subscriptionId: input.subscriptionId
+			};
+			validateAndDispatch(record, frame);
+			record.lastEventId = frame.eventId;
+			replayed += 1;
+		}
+		if (replay.droppedCount > 0) {
+			validateAndDispatch(record, {
+				v: "1",
+				kind: "replay-marker",
+				subscriptionId: input.subscriptionId,
+				eventId: snapshotEventId ?? `evt-replay-${now().toString(36)}`,
+				droppedCount: replay.droppedCount,
+				note: `Replay buffer dropped ${replay.droppedCount} events before resume.`
+			});
+			snapshotEventId = snapshotEventId ?? `evt-replay-${now().toString(36)}`;
+		}
+		return {
+			ok: true,
+			subscription: snapshotForRecord(record),
+			replayedCount: replayed,
+			snapshotEventId
+		};
+	}
+	function unsubscribe(subscriptionId) {
+		const record = subscriptions.get(subscriptionId);
+		if (record === void 0) return false;
+		subscribers.get(record.subscriberId)?.subscriptions.delete(subscriptionId);
+		deindexSubject(record.subject, subscriptionId);
+		subscriptions.delete(subscriptionId);
+		return true;
+	}
+	function emit(subject, bare) {
+		const eventId = bare.eventId ?? nextEventId();
+		const bufferedFrame = {
+			v: "1",
+			kind: "event",
+			eventId,
+			subscriptionId: "__pending__",
+			subject,
+			type: bare.type,
+			payload: bare.payload
+		};
+		replayBuffer.push(subject, bufferedFrame);
+		const subjectSubscribers = subjectIndex.get(subject);
+		if (subjectSubscribers === void 0 || subjectSubscribers.size === 0) return;
+		for (const subscriptionId of subjectSubscribers) {
+			const record = subscriptions.get(subscriptionId);
+			if (record === void 0) continue;
+			const sanitized = sanitizer.sanitize({
+				...bufferedFrame,
+				subscriptionId
+			}, "ws");
+			validateAndDispatch(record, sanitized);
+			record.lastEventId = sanitized.eventId;
+			if (sanitized.eventId === eventId) continue;
+		}
+	}
+	function emitLifecycle(subscriptionId, status, reason) {
+		const record = subscriptions.get(subscriptionId);
+		if (record === void 0) return;
+		validateAndDispatch(record, {
+			v: "1",
+			kind: "lifecycle",
+			subscriptionId,
+			status,
+			...reason !== void 0 ? { reason } : {}
+		});
+	}
+	function listForSubscriber(subscriberId) {
+		const subscriber = subscribers.get(subscriberId);
+		if (subscriber === void 0) return Object.freeze([]);
+		return Object.freeze([...subscriber.subscriptions].map((id) => subscriptions.get(id)).filter((entry) => entry !== void 0).map(snapshotForRecord));
+	}
+	function snapshotSubscription(subscriptionId) {
+		const record = subscriptions.get(subscriptionId);
+		if (record === void 0) return void 0;
+		return snapshotForRecord(record);
+	}
+	function size() {
+		return Object.freeze({
+			subscribers: subscribers.size,
+			subscriptions: subscriptions.size
+		});
+	}
+	function shutdown() {
+		for (const subscription of subscriptions.values()) {
+			const subscriber = subscribers.get(subscription.subscriberId);
+			try {
+				subscriber?.handle.send({
+					v: "1",
+					kind: "lifecycle",
+					subscriptionId: subscription.subscriptionId,
+					status: "aborted",
+					reason: "server-shutdown"
+				});
+			} catch {}
+		}
+		subscriptions.clear();
+		subjectIndex.clear();
+		subscribers.clear();
+	}
+	return Object.freeze({
+		sanitizer,
+		replayBuffer,
+		registerSubscriber,
+		subscribe,
+		unsubscribe,
+		emit,
+		emitLifecycle,
+		listForSubscriber,
+		snapshotSubscription,
+		size,
+		shutdown
+	});
+}
+function snapshotForRecord(record) {
+	return Object.freeze({
+		subscriptionId: record.subscriptionId,
+		subject: record.subject,
+		subjectKind: record.parsed.kind,
+		subscriberId: record.subscriberId,
+		tokenId: record.tokenId,
+		createdAt: record.createdAt,
+		lastEventId: record.lastEventId
+	});
+}
+
+//#endregion
+export { createWsDispatcher };
+//# sourceMappingURL=dispatcher.js.map

package/dist/ws/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","names":["record: SubscriptionRecord","snapshotEventId: string | undefined","frame: ServerEventFrame","bufferedFrame: ServerEventFrame"],"sources":["../../src/ws/dispatcher.ts"],"sourcesContent":["/**\n * Per-server WebSocket dispatcher. Owns the in-memory subscription\n * map, fans out events to matching connections, applies the\n * delivery-layer commentary-phase trace sanitization, validates\n * outbound frames against the `@graphorin/protocol` schema, and\n * exposes a tiny `emit(subject, event)` surface route handlers\n * (and the agent / workflow runtimes) consume.\n *\n * @packageDocumentation\n */\n\nimport {\n  isEventFrame,\n  type ServerEventFrame,\n  type ServerLifecycleFrame,\n  type ServerMessage,\n  ServerMessageSchema,\n} from '@graphorin/protocol';\nimport type { ParsedScope } from '@graphorin/security/auth';\nimport {\n  createDeliveryCommentarySanitizer,\n  type DeliveryCommentaryConfig,\n  type DeliveryCommentarySanitizer,\n} from '../commentary/index.js';\nimport {\n  createReplayBuffer,\n  type ReplayBuffer,\n  type ReplayBufferOptions,\n} from './replay-buffer.js';\nimport { isSubjectAllowed, type ParsedSubject, tryParseSubject } from './subjects.js';\n\n/**\n * Public configuration accepted by {@link createWsDispatcher}.\n *\n * @stable\n */\nexport interface WsDispatcherOptions {\n  readonly commentary?: DeliveryCommentaryConfig;\n  readonly replayBuffer?: ReplayBufferOptions;\n  /**\n   * Cap on outstanding events queued for an offline subscriber.\n   * Defaults to the same value as the replay buffer per-subject cap.\n   */\n  readonly perConnectionQueueLimit?: number;\n  readonly now?: () => number;\n  /**\n   * Logger sink for protocol violations + dropped frames. When\n   * omitted, the dispatcher is silent (production wiring uses the\n   * server's structured logger).\n   */\n  readonly onWarn?: (event: WsDispatcherWarning) => void;\n}\n\n/**\n * Discriminator surfaced to the optional warn sink.\n *\n * @stable\n */\nexport type WsDispatcherWarning =\n  | {\n      readonly kind: 'invalid-frame';\n      readonly subscriptionId: string;\n      readonly issues: ReadonlyArray<string>;\n    }\n  | { readonly kind: 'queue-overflow'; readonly subscriptionId: string }\n  | { readonly kind: 'subject-rejected'; readonly subject: string; readonly reason: string };\n\n/**\n * Subscriber surface used by the dispatcher. Each WebSocket\n * connection wraps its `WSContext.send` in this interface so the\n * dispatcher does not depend on `@hono/node-ws` types directly.\n *\n * @stable\n */\nexport interface WsSubscriberHandle {\n  readonly id: string;\n  readonly tokenId: string;\n  readonly grantedScopes: ReadonlyArray<ParsedScope>;\n  /** Send a server frame; the dispatcher already validated it. */\n  send(frame: ServerMessage): void;\n  /** Close the underlying WebSocket with a Graphorin close code. */\n  close(code: number, reason: string): void;\n  /**\n   * Optional buffered-byte sample. The dispatcher reads this on every\n   * emit to detect sustained backpressure and close the connection\n   * with the Graphorin `flow.throttled` code (4006) before the OS-\n   * level send buffer collapses. Consumers backed by `@hono/node-ws`\n   * can return the underlying `ws.bufferedAmount`. When the field is\n   * not implemented, the dispatcher falls back to the per-connection\n   * outstanding-event counter.\n   */\n  bufferedAmount?(): number;\n}\n\n/**\n * Snapshot of an active subscription. Surfaced via\n * {@link WsDispatcher.snapshotSubscription}.\n *\n * @stable\n */\nexport interface WsSubscriptionSnapshot {\n  readonly subscriptionId: string;\n  readonly subject: string;\n  readonly subjectKind: ParsedSubject['kind'];\n  readonly subscriberId: string;\n  readonly tokenId: string;\n  readonly createdAt: number;\n  readonly lastEventId: string | undefined;\n}\n\n/**\n * Result of {@link WsDispatcher.subscribe}.\n *\n * @stable\n */\nexport type SubscribeResult =\n  | {\n      readonly ok: true;\n      readonly subscription: WsSubscriptionSnapshot;\n      readonly replayedCount: number;\n      readonly snapshotEventId: string | undefined;\n    }\n  | {\n      readonly ok: false;\n      readonly reason:\n        | 'subject-malformed'\n        | 'subject-unknown'\n        | 'subject-wildcard'\n        | 'scope-denied';\n    };\n\n/**\n * Public surface of the dispatcher.\n *\n * @stable\n */\nexport interface WsDispatcher {\n  readonly sanitizer: DeliveryCommentarySanitizer;\n  readonly replayBuffer: ReplayBuffer;\n  /**\n   * Register a subscriber (one per WebSocket connection).\n   * `unregister` is called on close.\n   */\n  registerSubscriber(handle: WsSubscriberHandle): { unregister(): void };\n  /**\n   * Open a new subscription for an active subscriber. Returns either\n   * the subscription snapshot + replayed-event count or a typed\n   * failure reason the caller maps to the appropriate close code /\n   * RPC error.\n   */\n  subscribe(input: {\n    readonly subscriberId: string;\n    readonly subject: string;\n    readonly subscriptionId: string;\n    readonly sinceEventId?: string;\n  }): SubscribeResult;\n  unsubscribe(subscriptionId: string): boolean;\n  /**\n   * Push an event into the dispatcher. Goes through the sanitizer,\n   * validates against the protocol schema, persists into the replay\n   * buffer, and fans out to every matching active subscription.\n   */\n  emit(subject: string, frame: BareEventFrame): void;\n  /** Push a lifecycle frame to a single subscription. */\n  emitLifecycle(\n    subscriptionId: string,\n    status: ServerLifecycleFrame['status'],\n    reason?: string,\n  ): void;\n  /** List active subscriptions for a given subscriber (diagnostics). */\n  listForSubscriber(subscriberId: string): ReadonlyArray<WsSubscriptionSnapshot>;\n  snapshotSubscription(subscriptionId: string): WsSubscriptionSnapshot | undefined;\n  size(): { readonly subscribers: number; readonly subscriptions: number };\n  /** Clear in-memory state (used during graceful shutdown). */\n  shutdown(): void;\n}\n\n/**\n * Frame argument accepted by {@link WsDispatcher.emit}. The\n * dispatcher fills in `subscriptionId`, `subject`, and `eventId`.\n *\n * @stable\n */\nexport interface BareEventFrame {\n  readonly type: string;\n  readonly payload: unknown;\n  readonly eventId?: string;\n}\n\ninterface SubscriberRecord {\n  readonly handle: WsSubscriberHandle;\n  readonly subscriptions: Set<string>;\n  outstandingEvents: number;\n  closed: boolean;\n}\n\ninterface SubscriptionRecord {\n  readonly subscriberId: string;\n  /** IP-18: the authenticating principal's token id (not the connection id). */\n  readonly tokenId: string;\n  readonly subscriptionId: string;\n  readonly subject: string;\n  readonly parsed: ParsedSubject;\n  readonly createdAt: number;\n  lastEventId: string | undefined;\n}\n\n/**\n * Build a fresh dispatcher.\n *\n * @stable\n */\nexport function createWsDispatcher(options: WsDispatcherOptions = {}): WsDispatcher {\n  const sanitizer = createDeliveryCommentarySanitizer(options.commentary);\n  const replayBuffer = createReplayBuffer(options.replayBuffer ?? {});\n  const now = options.now ?? Date.now;\n  const onWarn = options.onWarn;\n  const perConnectionQueueLimit = options.perConnectionQueueLimit ?? 1_000;\n  const subscribers = new Map<string, SubscriberRecord>();\n  const subscriptions = new Map<string, SubscriptionRecord>();\n  const subjectIndex = new Map<string, Set<string>>();\n  let eventCounter = 0;\n\n  function indexSubject(subject: string, subscriptionId: string): void {\n    let set = subjectIndex.get(subject);\n    if (set === undefined) {\n      set = new Set();\n      subjectIndex.set(subject, set);\n    }\n    set.add(subscriptionId);\n  }\n\n  function deindexSubject(subject: string, subscriptionId: string): void {\n    const set = subjectIndex.get(subject);\n    if (set === undefined) return;\n    set.delete(subscriptionId);\n    if (set.size === 0) subjectIndex.delete(subject);\n  }\n\n  function nextEventId(): string {\n    eventCounter += 1;\n    return `evt-${now().toString(36)}-${eventCounter.toString(36)}`;\n  }\n\n  function dispatchToSubscriber(record: SubscriptionRecord, frame: ServerMessage): void {\n    const subscriber = subscribers.get(record.subscriberId);\n    if (subscriber === undefined || subscriber.closed) return;\n    // Per-connection backpressure: track the outstanding-event counter\n    // and consult the optional `bufferedAmount()` sample. The\n    // dispatcher closes the connection with the Graphorin\n    // `flow.throttled` code (4006) when either signal exceeds the\n    // configured limit so the client can reconnect against the\n    // replay buffer instead of accumulating an unbounded send queue.\n    const buffered =\n      typeof subscriber.handle.bufferedAmount === 'function'\n        ? subscriber.handle.bufferedAmount()\n        : 0;\n    if (\n      subscriber.outstandingEvents >= perConnectionQueueLimit ||\n      buffered >= perConnectionQueueLimit * 1024\n    ) {\n      onWarn?.({ kind: 'queue-overflow', subscriptionId: record.subscriptionId });\n      shutdownSubscriber(subscriber, 4006, 'flow.throttled');\n      return;\n    }\n    subscriber.outstandingEvents += 1;\n    try {\n      subscriber.handle.send(frame);\n    } catch (err) {\n      onWarn?.({ kind: 'queue-overflow', subscriptionId: record.subscriptionId });\n      shutdownSubscriber(subscriber, 4006, 'flow.throttled');\n      void err;\n    } finally {\n      subscriber.outstandingEvents = Math.max(0, subscriber.outstandingEvents - 1);\n    }\n  }\n\n  function shutdownSubscriber(subscriber: SubscriberRecord, code: number, reason: string): void {\n    if (subscriber.closed) return;\n    subscriber.closed = true;\n    try {\n      subscriber.handle.close(code, reason);\n    } catch {\n      // ignore — we are tearing the subscriber down.\n    }\n    for (const id of subscriber.subscriptions) {\n      const sub = subscriptions.get(id);\n      if (sub !== undefined) {\n        deindexSubject(sub.subject, id);\n        subscriptions.delete(id);\n      }\n    }\n    subscriber.subscriptions.clear();\n    subscribers.delete(subscriber.handle.id);\n  }\n\n  function validateAndDispatch(record: SubscriptionRecord, frame: ServerMessage): void {\n    const validated = ServerMessageSchema.safeParse(frame);\n    if (!validated.success) {\n      onWarn?.({\n        kind: 'invalid-frame',\n        subscriptionId: record.subscriptionId,\n        issues: validated.error.issues.map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`),\n      });\n      return;\n    }\n    dispatchToSubscriber(record, validated.data);\n  }\n\n  function registerSubscriber(handle: WsSubscriberHandle): { unregister(): void } {\n    subscribers.set(handle.id, {\n      handle,\n      subscriptions: new Set(),\n      outstandingEvents: 0,\n      closed: false,\n    });\n    return {\n      unregister: () => {\n        const record = subscribers.get(handle.id);\n        if (record === undefined) return;\n        for (const id of record.subscriptions) {\n          const sub = subscriptions.get(id);\n          if (sub !== undefined) {\n            deindexSubject(sub.subject, id);\n            subscriptions.delete(id);\n          }\n        }\n        subscribers.delete(handle.id);\n      },\n    };\n  }\n\n  function subscribe(input: {\n    readonly subscriberId: string;\n    readonly subject: string;\n    readonly subscriptionId: string;\n    readonly sinceEventId?: string;\n  }): SubscribeResult {\n    const subscriber = subscribers.get(input.subscriberId);\n    if (subscriber === undefined) {\n      return { ok: false, reason: 'subject-unknown' };\n    }\n    const parseResult = tryParseSubject(input.subject);\n    if (!parseResult.ok) {\n      const reason = parseResult.reason;\n      onWarn?.({ kind: 'subject-rejected', subject: input.subject, reason });\n      if (reason === 'wildcard-not-supported') return { ok: false, reason: 'subject-wildcard' };\n      if (reason === 'unknown-subject') return { ok: false, reason: 'subject-unknown' };\n      return { ok: false, reason: 'subject-malformed' };\n    }\n    if (!isSubjectAllowed(subscriber.handle.grantedScopes, parseResult.subject)) {\n      return { ok: false, reason: 'scope-denied' };\n    }\n    const record: SubscriptionRecord = {\n      subscriberId: input.subscriberId,\n      tokenId: subscriber.handle.tokenId,\n      subscriptionId: input.subscriptionId,\n      subject: input.subject,\n      parsed: parseResult.subject,\n      createdAt: now(),\n      lastEventId: undefined,\n    };\n    subscriptions.set(input.subscriptionId, record);\n    subscriber.subscriptions.add(input.subscriptionId);\n    indexSubject(input.subject, input.subscriptionId);\n    const replay = replayBuffer.replay(input.subject, input.sinceEventId);\n    let replayed = 0;\n    let snapshotEventId: string | undefined = replay.nextEventIdHint;\n    for (const event of replay.events) {\n      const frame: ServerEventFrame = {\n        ...event,\n        subscriptionId: input.subscriptionId,\n      };\n      validateAndDispatch(record, frame);\n      record.lastEventId = frame.eventId;\n      replayed += 1;\n    }\n    if (replay.droppedCount > 0) {\n      validateAndDispatch(record, {\n        v: '1',\n        kind: 'replay-marker',\n        subscriptionId: input.subscriptionId,\n        eventId: snapshotEventId ?? `evt-replay-${now().toString(36)}`,\n        droppedCount: replay.droppedCount,\n        note: `Replay buffer dropped ${replay.droppedCount} events before resume.`,\n      });\n      snapshotEventId = snapshotEventId ?? `evt-replay-${now().toString(36)}`;\n    }\n    return {\n      ok: true,\n      subscription: snapshotForRecord(record),\n      replayedCount: replayed,\n      snapshotEventId,\n    };\n  }\n\n  function unsubscribe(subscriptionId: string): boolean {\n    const record = subscriptions.get(subscriptionId);\n    if (record === undefined) return false;\n    const subscriber = subscribers.get(record.subscriberId);\n    subscriber?.subscriptions.delete(subscriptionId);\n    deindexSubject(record.subject, subscriptionId);\n    subscriptions.delete(subscriptionId);\n    return true;\n  }\n\n  function emit(subject: string, bare: BareEventFrame): void {\n    const eventId = bare.eventId ?? nextEventId();\n    // Buffer first so the replay layer captures every event, even\n    // when there is no live subscriber. The buffered frame is\n    // sanitizer-neutral (the per-subscription dispatch sanitizes\n    // again on the wire so the second pass is idempotent — by\n    // construction matching wraps are not re-wrapped).\n    const bufferedFrame: ServerEventFrame = {\n      v: '1',\n      kind: 'event',\n      eventId,\n      subscriptionId: '__pending__',\n      subject,\n      type: bare.type,\n      payload: bare.payload,\n    };\n    replayBuffer.push(subject, bufferedFrame);\n    const subjectSubscribers = subjectIndex.get(subject);\n    if (subjectSubscribers === undefined || subjectSubscribers.size === 0) return;\n    for (const subscriptionId of subjectSubscribers) {\n      const record = subscriptions.get(subscriptionId);\n      if (record === undefined) continue;\n      const sanitized = sanitizer.sanitize({ ...bufferedFrame, subscriptionId }, 'ws');\n      validateAndDispatch(record, sanitized);\n      record.lastEventId = sanitized.eventId;\n      if (sanitized.eventId === eventId) continue;\n    }\n    void isEventFrame; // keep import warm\n  }\n\n  function emitLifecycle(\n    subscriptionId: string,\n    status: ServerLifecycleFrame['status'],\n    reason?: string,\n  ): void {\n    const record = subscriptions.get(subscriptionId);\n    if (record === undefined) return;\n    const frame: ServerLifecycleFrame = {\n      v: '1',\n      kind: 'lifecycle',\n      subscriptionId,\n      status,\n      ...(reason !== undefined ? { reason } : {}),\n    };\n    validateAndDispatch(record, frame);\n  }\n\n  function listForSubscriber(subscriberId: string): ReadonlyArray<WsSubscriptionSnapshot> {\n    const subscriber = subscribers.get(subscriberId);\n    if (subscriber === undefined) return Object.freeze([]);\n    return Object.freeze(\n      [...subscriber.subscriptions]\n        .map((id) => subscriptions.get(id))\n        .filter((entry): entry is SubscriptionRecord => entry !== undefined)\n        .map(snapshotForRecord),\n    );\n  }\n\n  function snapshotSubscription(subscriptionId: string): WsSubscriptionSnapshot | undefined {\n    const record = subscriptions.get(subscriptionId);\n    if (record === undefined) return undefined;\n    return snapshotForRecord(record);\n  }\n\n  function size(): { readonly subscribers: number; readonly subscriptions: number } {\n    return Object.freeze({\n      subscribers: subscribers.size,\n      subscriptions: subscriptions.size,\n    });\n  }\n\n  function shutdown(): void {\n    for (const subscription of subscriptions.values()) {\n      const subscriber = subscribers.get(subscription.subscriberId);\n      try {\n        subscriber?.handle.send({\n          v: '1',\n          kind: 'lifecycle',\n          subscriptionId: subscription.subscriptionId,\n          status: 'aborted',\n          reason: 'server-shutdown',\n        });\n      } catch {\n        // swallow — we are tearing down.\n      }\n    }\n    subscriptions.clear();\n    subjectIndex.clear();\n    subscribers.clear();\n  }\n\n  return Object.freeze({\n    sanitizer,\n    replayBuffer,\n    registerSubscriber,\n    subscribe,\n    unsubscribe,\n    emit,\n    emitLifecycle,\n    listForSubscriber,\n    snapshotSubscription,\n    size,\n    shutdown,\n  });\n}\n\nfunction snapshotForRecord(record: SubscriptionRecord): WsSubscriptionSnapshot {\n  return Object.freeze({\n    subscriptionId: record.subscriptionId,\n    subject: record.subject,\n    subjectKind: record.parsed.kind,\n    subscriberId: record.subscriberId,\n    tokenId: record.tokenId,\n    createdAt: record.createdAt,\n    lastEventId: record.lastEventId,\n  });\n}\n"],"mappings":"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"}

package/dist/ws/index.d.ts

@@ -0,0 +1,6 @@
+import { ReplayBuffer, ReplayBufferOptions, ReplayBufferSlice, createReplayBuffer } from "./replay-buffer.js";
+import { ParseSubjectResult, ParsedSubject, isSubjectAllowed, requiredScopeFor, tryParseSubject } from "./subjects.js";
+import { BareEventFrame, SubscribeResult, WsDispatcher, WsDispatcherOptions, WsDispatcherWarning, WsSubscriberHandle, WsSubscriptionSnapshot, createWsDispatcher } from "./dispatcher.js";
+import { WsTicket, WsTicketConsumeResult, WsTicketStore, WsTicketStoreOptions, createWsTicketStore } from "./ticket.js";
+import { WsUpgradeOptions, createWsUpgradeEvents } from "./upgrade.js";
+export { type BareEventFrame, type ParseSubjectResult, type ParsedSubject, type ReplayBuffer, type ReplayBufferOptions, type ReplayBufferSlice, type SubscribeResult, type WsDispatcher, type WsDispatcherOptions, type WsDispatcherWarning, type WsSubscriberHandle, type WsSubscriptionSnapshot, type WsTicket, type WsTicketConsumeResult, type WsTicketStore, type WsTicketStoreOptions, type WsUpgradeOptions, createReplayBuffer, createWsDispatcher, createWsTicketStore, createWsUpgradeEvents, isSubjectAllowed, requiredScopeFor, tryParseSubject };

package/dist/ws/index.js

@@ -0,0 +1,7 @@
+import { createReplayBuffer } from "./replay-buffer.js";
+import { isSubjectAllowed, requiredScopeFor, tryParseSubject } from "./subjects.js";
+import { createWsDispatcher } from "./dispatcher.js";
+import { createWsTicketStore } from "./ticket.js";
+import { createWsUpgradeEvents } from "./upgrade.js";
+
+export { createReplayBuffer, createWsDispatcher, createWsTicketStore, createWsUpgradeEvents, isSubjectAllowed, requiredScopeFor, tryParseSubject };

package/dist/ws/replay-buffer.d.ts

@@ -0,0 +1,47 @@
+import { ServerEventFrame } from "@graphorin/protocol";
+
+//#region src/ws/replay-buffer.d.ts
+
+/**
+ * Public configuration accepted by {@link createReplayBuffer}.
+ *
+ * @stable
+ */
+interface ReplayBufferOptions {
+  readonly maxEvents?: number;
+  readonly ttlMs?: number;
+  readonly now?: () => number;
+}
+/**
+ * Snapshot returned by {@link ReplayBuffer.replay}.
+ *
+ * @stable
+ */
+interface ReplayBufferSlice {
+  readonly events: ReadonlyArray<ServerEventFrame>;
+  readonly droppedCount: number;
+  readonly nextEventIdHint: string | undefined;
+}
+/**
+ * Per-subject replay buffer. Stores up to `maxEvents` per subject
+ * with a TTL; thread-safe under the single-writer Node event loop
+ * model.
+ *
+ * @stable
+ */
+interface ReplayBuffer {
+  push(subject: string, event: ServerEventFrame): void;
+  replay(subject: string, sinceEventId: string | undefined): ReplayBufferSlice;
+  size(subject: string): number;
+  forget(subject: string): void;
+  prune(): void;
+}
+/**
+ * Build an in-memory replay buffer.
+ *
+ * @stable
+ */
+declare function createReplayBuffer(options?: ReplayBufferOptions): ReplayBuffer;
+//#endregion
+export { ReplayBuffer, ReplayBufferOptions, ReplayBufferSlice, createReplayBuffer };
+//# sourceMappingURL=replay-buffer.d.ts.map

package/dist/ws/replay-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-buffer.d.ts","names":[],"sources":["../../src/ws/replay-buffer.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UAoBiB,mBAAA;;;;;;;;;;UAWA,iBAAA;mBACE,cAAc;;;;;;;;;;;UAYhB,YAAA;+BACc;6DAC8B;;;;;;;;;;iBAgB7C,kBAAA,WAA4B,sBAA2B"}

package/dist/ws/replay-buffer.js

@@ -0,0 +1,88 @@
+//#region src/ws/replay-buffer.ts
+/**
+* Build an in-memory replay buffer.
+*
+* @stable
+*/
+function createReplayBuffer(options = {}) {
+	const maxEvents = options.maxEvents ?? 1e3;
+	const ttlMs = options.ttlMs ?? 5 * 6e4;
+	const now = options.now ?? Date.now;
+	const buffers = /* @__PURE__ */ new Map();
+	const dropped = /* @__PURE__ */ new Map();
+	function pruneSubject(subject) {
+		const list = buffers.get(subject);
+		if (list === void 0 || list.length === 0) return;
+		const cutoff = now() - ttlMs;
+		let cutoffIndex = 0;
+		while (cutoffIndex < list.length) {
+			const entry = list[cutoffIndex];
+			if (entry === void 0 || entry.bufferedAt >= cutoff) break;
+			cutoffIndex += 1;
+		}
+		if (cutoffIndex > 0) {
+			list.splice(0, cutoffIndex);
+			dropped.set(subject, (dropped.get(subject) ?? 0) + cutoffIndex);
+		}
+		if (list.length === 0) buffers.delete(subject);
+	}
+	function push(subject, event) {
+		pruneSubject(subject);
+		let list = buffers.get(subject);
+		if (list === void 0) {
+			list = [];
+			buffers.set(subject, list);
+		}
+		list.push({
+			event,
+			bufferedAt: now()
+		});
+		if (list.length > maxEvents) {
+			const overflow = list.length - maxEvents;
+			list.splice(0, overflow);
+			dropped.set(subject, (dropped.get(subject) ?? 0) + overflow);
+		}
+	}
+	function replay(subject, sinceEventId) {
+		pruneSubject(subject);
+		const list = buffers.get(subject) ?? [];
+		const droppedCount = dropped.get(subject) ?? 0;
+		const last = list.at(-1);
+		if (sinceEventId === void 0) return {
+			events: list.map((entry) => entry.event),
+			droppedCount,
+			nextEventIdHint: last?.event.eventId
+		};
+		const startIndex = list.findIndex((entry) => entry.event.eventId === sinceEventId);
+		if (startIndex < 0) return {
+			events: list.map((entry) => entry.event),
+			droppedCount,
+			nextEventIdHint: last?.event.eventId
+		};
+		const replayed = list.slice(startIndex + 1).map((entry) => entry.event);
+		return {
+			events: replayed,
+			droppedCount: 0,
+			nextEventIdHint: replayed.at(-1)?.eventId
+		};
+	}
+	return Object.freeze({
+		push,
+		replay,
+		size(subject) {
+			pruneSubject(subject);
+			return buffers.get(subject)?.length ?? 0;
+		},
+		forget(subject) {
+			buffers.delete(subject);
+			dropped.delete(subject);
+		},
+		prune() {
+			for (const subject of [...buffers.keys()]) pruneSubject(subject);
+		}
+	});
+}
+
+//#endregion
+export { createReplayBuffer };
+//# sourceMappingURL=replay-buffer.js.map

package/dist/ws/replay-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-buffer.js","names":[],"sources":["../../src/ws/replay-buffer.ts"],"sourcesContent":["/**\n * Per-subscription replay buffer used by the dispatcher to support\n * short-disconnect resume. When a client reconnects with a\n * `lastEventId`, the dispatcher walks the buffer from the matching\n * cursor and re-emits every event the client missed.\n *\n * Defaults (configurable per-server):\n *  - `maxEvents`: 1000 (per subscription)\n *  - `ttlMs`: 5 minutes\n *\n * @packageDocumentation\n */\n\nimport type { ServerEventFrame } from '@graphorin/protocol';\n\n/**\n * Public configuration accepted by {@link createReplayBuffer}.\n *\n * @stable\n */\nexport interface ReplayBufferOptions {\n  readonly maxEvents?: number;\n  readonly ttlMs?: number;\n  readonly now?: () => number;\n}\n\n/**\n * Snapshot returned by {@link ReplayBuffer.replay}.\n *\n * @stable\n */\nexport interface ReplayBufferSlice {\n  readonly events: ReadonlyArray<ServerEventFrame>;\n  readonly droppedCount: number;\n  readonly nextEventIdHint: string | undefined;\n}\n\n/**\n * Per-subject replay buffer. Stores up to `maxEvents` per subject\n * with a TTL; thread-safe under the single-writer Node event loop\n * model.\n *\n * @stable\n */\nexport interface ReplayBuffer {\n  push(subject: string, event: ServerEventFrame): void;\n  replay(subject: string, sinceEventId: string | undefined): ReplayBufferSlice;\n  size(subject: string): number;\n  forget(subject: string): void;\n  prune(): void;\n}\n\ninterface BufferedEvent {\n  readonly event: ServerEventFrame;\n  readonly bufferedAt: number;\n}\n\n/**\n * Build an in-memory replay buffer.\n *\n * @stable\n */\nexport function createReplayBuffer(options: ReplayBufferOptions = {}): ReplayBuffer {\n  const maxEvents = options.maxEvents ?? 1_000;\n  const ttlMs = options.ttlMs ?? 5 * 60_000;\n  const now = options.now ?? Date.now;\n  const buffers = new Map<string, BufferedEvent[]>();\n  const dropped = new Map<string, number>();\n\n  function pruneSubject(subject: string): void {\n    const list = buffers.get(subject);\n    if (list === undefined || list.length === 0) return;\n    const cutoff = now() - ttlMs;\n    let cutoffIndex = 0;\n    while (cutoffIndex < list.length) {\n      const entry = list[cutoffIndex];\n      if (entry === undefined || entry.bufferedAt >= cutoff) break;\n      cutoffIndex += 1;\n    }\n    if (cutoffIndex > 0) {\n      list.splice(0, cutoffIndex);\n      dropped.set(subject, (dropped.get(subject) ?? 0) + cutoffIndex);\n    }\n    if (list.length === 0) buffers.delete(subject);\n  }\n\n  function push(subject: string, event: ServerEventFrame): void {\n    pruneSubject(subject);\n    let list = buffers.get(subject);\n    if (list === undefined) {\n      list = [];\n      buffers.set(subject, list);\n    }\n    list.push({ event, bufferedAt: now() });\n    if (list.length > maxEvents) {\n      const overflow = list.length - maxEvents;\n      list.splice(0, overflow);\n      dropped.set(subject, (dropped.get(subject) ?? 0) + overflow);\n    }\n  }\n\n  function replay(subject: string, sinceEventId: string | undefined): ReplayBufferSlice {\n    pruneSubject(subject);\n    const list = buffers.get(subject) ?? [];\n    const droppedCount = dropped.get(subject) ?? 0;\n    const last = list.at(-1);\n    if (sinceEventId === undefined) {\n      const slice: ReplayBufferSlice = {\n        events: list.map((entry) => entry.event),\n        droppedCount,\n        nextEventIdHint: last?.event.eventId,\n      };\n      return slice;\n    }\n    const startIndex = list.findIndex((entry) => entry.event.eventId === sinceEventId);\n    if (startIndex < 0) {\n      // Cursor predates the buffer; return everything we still have +\n      // signal the gap via `droppedCount`.\n      return {\n        events: list.map((entry) => entry.event),\n        droppedCount,\n        nextEventIdHint: last?.event.eventId,\n      };\n    }\n    const replayed = list.slice(startIndex + 1).map((entry) => entry.event);\n    return {\n      events: replayed,\n      droppedCount: 0,\n      nextEventIdHint: replayed.at(-1)?.eventId,\n    };\n  }\n\n  return Object.freeze({\n    push,\n    replay,\n    size(subject: string): number {\n      pruneSubject(subject);\n      return buffers.get(subject)?.length ?? 0;\n    },\n    forget(subject: string): void {\n      buffers.delete(subject);\n      dropped.delete(subject);\n    },\n    prune(): void {\n      for (const subject of [...buffers.keys()]) pruneSubject(subject);\n    },\n  });\n}\n"],"mappings":";;;;;;AA8DA,SAAgB,mBAAmB,UAA+B,EAAE,EAAgB;CAClF,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,QAAQ,QAAQ,SAAS,IAAI;CACnC,MAAM,MAAM,QAAQ,OAAO,KAAK;CAChC,MAAM,0BAAU,IAAI,KAA8B;CAClD,MAAM,0BAAU,IAAI,KAAqB;CAEzC,SAAS,aAAa,SAAuB;EAC3C,MAAM,OAAO,QAAQ,IAAI,QAAQ;AACjC,MAAI,SAAS,UAAa,KAAK,WAAW,EAAG;EAC7C,MAAM,SAAS,KAAK,GAAG;EACvB,IAAI,cAAc;AAClB,SAAO,cAAc,KAAK,QAAQ;GAChC,MAAM,QAAQ,KAAK;AACnB,OAAI,UAAU,UAAa,MAAM,cAAc,OAAQ;AACvD,kBAAe;;AAEjB,MAAI,cAAc,GAAG;AACnB,QAAK,OAAO,GAAG,YAAY;AAC3B,WAAQ,IAAI,UAAU,QAAQ,IAAI,QAAQ,IAAI,KAAK,YAAY;;AAEjE,MAAI,KAAK,WAAW,EAAG,SAAQ,OAAO,QAAQ;;CAGhD,SAAS,KAAK,SAAiB,OAA+B;AAC5D,eAAa,QAAQ;EACrB,IAAI,OAAO,QAAQ,IAAI,QAAQ;AAC/B,MAAI,SAAS,QAAW;AACtB,UAAO,EAAE;AACT,WAAQ,IAAI,SAAS,KAAK;;AAE5B,OAAK,KAAK;GAAE;GAAO,YAAY,KAAK;GAAE,CAAC;AACvC,MAAI,KAAK,SAAS,WAAW;GAC3B,MAAM,WAAW,KAAK,SAAS;AAC/B,QAAK,OAAO,GAAG,SAAS;AACxB,WAAQ,IAAI,UAAU,QAAQ,IAAI,QAAQ,IAAI,KAAK,SAAS;;;CAIhE,SAAS,OAAO,SAAiB,cAAqD;AACpF,eAAa,QAAQ;EACrB,MAAM,OAAO,QAAQ,IAAI,QAAQ,IAAI,EAAE;EACvC,MAAM,eAAe,QAAQ,IAAI,QAAQ,IAAI;EAC7C,MAAM,OAAO,KAAK,GAAG,GAAG;AACxB,MAAI,iBAAiB,OAMnB,QALiC;GAC/B,QAAQ,KAAK,KAAK,UAAU,MAAM,MAAM;GACxC;GACA,iBAAiB,MAAM,MAAM;GAC9B;EAGH,MAAM,aAAa,KAAK,WAAW,UAAU,MAAM,MAAM,YAAY,aAAa;AAClF,MAAI,aAAa,EAGf,QAAO;GACL,QAAQ,KAAK,KAAK,UAAU,MAAM,MAAM;GACxC;GACA,iBAAiB,MAAM,MAAM;GAC9B;EAEH,MAAM,WAAW,KAAK,MAAM,aAAa,EAAE,CAAC,KAAK,UAAU,MAAM,MAAM;AACvE,SAAO;GACL,QAAQ;GACR,cAAc;GACd,iBAAiB,SAAS,GAAG,GAAG,EAAE;GACnC;;AAGH,QAAO,OAAO,OAAO;EACnB;EACA;EACA,KAAK,SAAyB;AAC5B,gBAAa,QAAQ;AACrB,UAAO,QAAQ,IAAI,QAAQ,EAAE,UAAU;;EAEzC,OAAO,SAAuB;AAC5B,WAAQ,OAAO,QAAQ;AACvB,WAAQ,OAAO,QAAQ;;EAEzB,QAAc;AACZ,QAAK,MAAM,WAAW,CAAC,GAAG,QAAQ,MAAM,CAAC,CAAE,cAAa,QAAQ;;EAEnE,CAAC"}

package/dist/ws/subjects.d.ts

@@ -0,0 +1,71 @@
+import { ParsedScope } from "@graphorin/security/auth";
+
+//#region src/ws/subjects.d.ts
+
+/**
+ * Discriminated union of every recognised subject form. Surfaced on
+ * audit log entries + diagnostics; the wire still carries the raw
+ * string.
+ *
+ * @stable
+ */
+type ParsedSubject = {
+  readonly kind: 'session-events';
+  readonly sessionId: string;
+} | {
+  readonly kind: 'session-run-events';
+  readonly sessionId: string;
+  readonly runId: string;
+} | {
+  readonly kind: 'agent-run-events';
+  readonly agentId: string;
+  readonly runId: string;
+} | {
+  readonly kind: 'workflow-events';
+  readonly workflowId: string;
+} | {
+  readonly kind: 'workflow-run-events';
+  readonly workflowId: string;
+  readonly runId: string;
+} | {
+  readonly kind: 'memory-conflicts';
+} | {
+  readonly kind: 'audit-events';
+};
+/**
+ * Result of {@link tryParseSubject}.
+ *
+ * @stable
+ */
+type ParseSubjectResult = {
+  readonly ok: true;
+  readonly subject: ParsedSubject;
+} | {
+  readonly ok: false;
+  readonly reason: 'wildcard-not-supported' | 'unknown-subject' | 'malformed';
+};
+/**
+ * Parse a subject string into the {@link ParsedSubject} discriminator.
+ *
+ * @stable
+ */
+declare function tryParseSubject(raw: string): ParseSubjectResult;
+/**
+ * Required scope literal for every subject kind, expressed as a
+ * `ParsedScope`. The matcher `scopeMatches(granted, required)` uses
+ * the standard wildcard rules from `@graphorin/security/auth`
+ * (e.g. `agents:*` matches `agents:invoke:foo`).
+ *
+ * @stable
+ */
+declare function requiredScopeFor(subject: ParsedSubject): ParsedScope;
+/**
+ * Compatibility shim — re-exports `scopeMatches` so consumers don't
+ * have to learn the security package's surface.
+ *
+ * @stable
+ */
+declare function isSubjectAllowed(granted: ReadonlyArray<ParsedScope>, subject: ParsedSubject): boolean;
+//#endregion
+export { ParseSubjectResult, ParsedSubject, isSubjectAllowed, requiredScopeFor, tryParseSubject };
+//# sourceMappingURL=subjects.d.ts.map

package/dist/ws/subjects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subjects.d.ts","names":[],"sources":["../../src/ws/subjects.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;KAwBY,aAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA0BA,kBAAA;;oBAC+B;;;;;;;;;;iBAiB3B,eAAA,eAA8B;;;;;;;;;iBAqD9B,gBAAA,UAA0B,gBAAgB;;;;;;;iBAyB1C,gBAAA,UACL,cAAc,uBACd"}