@c9up/aurora 0.1.10 → 0.1.11

package/src/liveRouter.ts

@@ -0,0 +1,70 @@
+/**
+ * Live router (Stage 4) — the server-side orchestration that ties the session
+ * registry to the relay transport, transport-agnostically.
+ *
+ *   - `mount(name, ownerId)` → mounts a session, wires its patches to a
+ *     per-session channel, returns `{ id, channel, html }` for the HTTP
+ *     response (the client renders `html` and subscribes to `channel`).
+ *   - `event(id, event, payload)` → routes an inbound client event (a relay
+ *     POST) to the session; its patches auto-broadcast on the channel.
+ *   - `disconnect(ownerId)` → disposes every session that owner opened.
+ *
+ * Pure orchestration over the duck-typed registry + relay — node-free, no
+ * `@c9up/ream` / `@c9up/relay` import. The thin HTTP/relay wiring (register the
+ * POST route, hook relay's disconnect) is the provider/app's job and feeds
+ * these three methods.
+ */
+
+import { connectPatches, type RelayBroadcaster } from "./liveBroadcast.js";
+import type { LiveRegistry } from "./liveRegistry.js";
+
+/** What a client needs after mounting: render this `html`, subscribe to `channel`. */
+export interface LiveMount {
+	id: string;
+	channel: string;
+	html: string;
+}
+
+export interface LiveRouter {
+	/** Mount a session, wire its channel, return the initial render + ids. */
+	mount(name: string, ownerId: string): LiveMount;
+	/** Route a client event to its session. Returns false if the id is unknown. */
+	event(id: string, event: string, payload?: unknown): boolean;
+	/** Tear down every session an owner opened (call on relay disconnect). */
+	disconnect(ownerId: string): void;
+	/** The relay channel a session id broadcasts on. */
+	channelFor(id: string): string;
+}
+
+/**
+ * Create the live router over a session registry + a relay broadcaster. One per
+ * app. The per-session channel is `live/<id>`; gate subscription with
+ * `relay.authorize("live/*", …)` if the components carry sensitive state.
+ */
+export function createLiveRouter(
+	registry: LiveRegistry,
+	relay: RelayBroadcaster,
+): LiveRouter {
+	const channelFor = (id: string): string => `live/${id}`;
+
+	return {
+		mount(name, ownerId) {
+			const { id, session } = registry.mount(name, ownerId);
+			const channel = channelFor(id);
+			// Patches flow to the channel; `disconnect` → registry disposes the
+			// session, which clears its patch listener (stops broadcasting).
+			connectPatches(session, relay, channel);
+			return { id, channel, html: session.renderToString() };
+		},
+		event(id, event, payload) {
+			const session = registry.get(id);
+			if (!session) return false;
+			session.dispatch(event, payload);
+			return true;
+		},
+		disconnect(ownerId) {
+			registry.disposeOwner(ownerId);
+		},
+		channelFor,
+	};
+}

package/src/liveServer.ts

@@ -0,0 +1,75 @@
+/**
+ * Live server wiring (Stage 6) — register the inbound-event HTTP route that
+ * feeds the {@link LiveRouter}. The client POSTs `{ id, event, payload }` here;
+ * the route dispatches it to the session, whose patches broadcast over relay.
+ *
+ * Agnostic: the host HTTP router + context are DUCK-TYPED (a `post(path,
+ * handler)` router; a `ctx.request.body()` / `ctx.response` context) — no
+ * `@c9up/ream` import. Mirrors how warden/blackhole middleware read the ctx.
+ * Mount (render + ids) is done by the page handler via `liveRouter.mount`;
+ * disconnect is wired by the app: relay's disconnect → `liveRouter.disconnect`.
+ */
+
+import type { LiveRouter } from "./liveRouter.js";
+
+/** The slice of the host HTTP router this needs. */
+export interface LiveHttpRouter {
+	post(path: string, handler: (ctx: LiveHttpContext) => unknown): unknown;
+}
+
+/** The slice of the host HTTP context this needs (Ream's HttpContext satisfies it). */
+export interface LiveHttpContext {
+	request: { body(): unknown };
+	response: {
+		status(code: number): unknown;
+		json(data: unknown): void;
+	};
+}
+
+export interface WireLiveEventsOptions {
+	/** Route path for inbound events (must match the client transport). */
+	path?: string;
+}
+
+interface LiveEventBody {
+	id: string;
+	event: string;
+	payload?: unknown;
+}
+
+/** Structural guard for the POST body — no casts (`in`-narrowing + typeof). */
+function isLiveEventBody(value: unknown): value is LiveEventBody {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("id" in value) || !("event" in value)) return false;
+	return typeof value.id === "string" && typeof value.event === "string";
+}
+
+/** Default inbound-event route — keep the client transport's `path` in sync. */
+export const DEFAULT_LIVE_EVENT_PATH = "/_live/event";
+
+/**
+ * Register the inbound live-event route on the host router. Call once at boot
+ * (e.g. from a provider that resolved the router + relay from the container).
+ */
+export function wireLiveEvents(
+	router: LiveHttpRouter,
+	live: LiveRouter,
+	options: WireLiveEventsOptions = {},
+): void {
+	const path = options.path ?? DEFAULT_LIVE_EVENT_PATH;
+	router.post(path, (ctx) => {
+		const body = ctx.request.body();
+		if (!isLiveEventBody(body)) {
+			ctx.response.status(400);
+			ctx.response.json({ error: "live event requires { id, event }" });
+			return;
+		}
+		const handled = live.event(body.id, body.event, body.payload);
+		if (!handled) {
+			ctx.response.status(404);
+			ctx.response.json({ error: "unknown live session" });
+			return;
+		}
+		ctx.response.json({ ok: true });
+	});
+}

package/src/relay.ts

@@ -27,12 +27,15 @@ interface RelayState {
 	sse: EventSource | null;
 	uid: string | null;
 	channels: Map<string, Set<(event: unknown) => void>>;
+	/** Channels we've already wired an SSE listener for on the current sse. */
+	attached: Set<string>;
 }
 
 const STATE: RelayState = {
 	sse: null,
 	uid: null,
 	channels: new Map(),
+	attached: new Set(),
 };
 
 export interface RelayOptions {
@@ -85,6 +88,11 @@ const CLIENT: RelayClient = {
 		const adapted = handler as (event: unknown) => void;
 		handlers.add(adapted);
 
+		// Wire the SSE listener for this channel's NAMED events — the relay
+		// broadcasts `event: <channel>`, so a per-channel addEventListener (not
+		// the default `onmessage`) is what actually receives the payload.
+		if (STATE.sse) attachChannel(STATE.sse, channel);
+
 		// Subscribe over POST as soon as we have a uid. Before the first uid (or
 		// during an auto-reconnect) the channel already lives in STATE.channels
 		// and is (re-)subscribed by the `connected` handler — so the server,
@@ -110,15 +118,17 @@ const CLIENT: RelayClient = {
 		}
 		STATE.uid = null;
 		STATE.channels.clear();
+		STATE.attached.clear();
 	},
 };
 
 function open(): void {
 	const sse = new EventSource(CONFIG.sseUrl);
 	STATE.sse = sse;
+	STATE.attached = new Set();
 
 	sse.addEventListener("connected", (ev) => {
-		const data = safeJson<{ uid?: string }>((ev as MessageEvent).data);
+		const data = safeJson<{ uid?: string }>(messageData(ev));
 		if (data && typeof data.uid === "string") {
 			STATE.uid = data.uid;
 			// Re-apply EVERY active subscription on each (re)connect. The server
@@ -137,21 +147,40 @@ function open(): void {
 		}
 	});
 
-	sse.onmessage = (ev) => {
-		const data = safeJson<{ channel?: string; [key: string]: unknown }>(
-			ev.data,
-		);
-		if (!data || typeof data.channel !== "string") return;
-		const handlers = STATE.channels.get(data.channel);
+	// Re-attach channel listeners — a close()+reopen builds a fresh EventSource
+	// that has lost the listeners wired by earlier subscribe() calls.
+	for (const channel of STATE.channels.keys()) attachChannel(sse, channel);
+}
+
+/**
+ * Wire one SSE listener for a channel's named broadcast events. The relay sends
+ * `event: <channel>\ndata: <JSON payload>`, so each channel is its own named
+ * event — `onmessage` (default/unnamed only) never sees them. The handler
+ * receives the broadcast payload verbatim (the value passed to
+ * `relay.broadcast(channel, payload)`).
+ */
+function attachChannel(sse: EventSource, channel: string): void {
+	if (STATE.attached.has(channel)) return;
+	STATE.attached.add(channel);
+	sse.addEventListener(channel, (ev) => {
+		const payload = safeJson<unknown>(messageData(ev));
+		if (payload === null) return;
+		const handlers = STATE.channels.get(channel);
 		if (!handlers) return;
 		for (const handler of handlers) {
 			try {
-				handler(data);
+				handler(payload);
 			} catch (err) {
-				console.warn(`[aurora/relay] listener for ${data.channel} threw:`, err);
+				console.warn(`[aurora/relay] listener for ${channel} threw:`, err);
 			}
 		}
-	};
+	});
+}
+
+/** Read an SSE event's string `data` without an unsafe DOM cast. */
+function messageData(ev: Event): string | null {
+	if ("data" in ev && typeof ev.data === "string") return ev.data;
+	return null;
 }
 
 async function postSubscribe(channel: string): Promise<void> {