@c9up/aurora 0.1.22 → 0.1.24

package/src/relay.ts

@@ -18,8 +18,24 @@
  * `EventSource` being undefined.
  */
 
+/**
+ * Connection lifecycle status. Mirrors `@adonisjs/transmit-client`'s
+ * `TransmitStatus` (minus `initializing`, which the singleton never
+ * exposes — the first `relay()` call opens straight into `connecting`).
+ */
+export type RelayStatus =
+	| "connecting"
+	| "connected"
+	| "disconnected"
+	| "reconnecting";
+
 export interface RelayClient {
 	subscribe<E>(channel: string, handler: (event: E) => void): () => void;
+	/**
+	 * Register a connection-status listener. Returns a detacher. Mirrors
+	 * `transmit.on('connected' | 'disconnected' | ...)`.
+	 */
+	on(status: RelayStatus, callback: (status: RelayStatus) => void): () => void;
 	close(): void;
 }
 
@@ -29,6 +45,12 @@ interface RelayState {
 	channels: Map<string, Set<(event: unknown) => void>>;
 	/** Channels we've already wired an SSE listener for on the current sse. */
 	attached: Set<string>;
+	/** Current connection status. */
+	status: RelayStatus;
+	/** Status listeners, keyed by the status they fire on. */
+	statusListeners: Map<RelayStatus, Set<(status: RelayStatus) => void>>;
+	/** Consecutive failed-connection count, reset on every `connected` frame. */
+	reconnectAttempts: number;
 }
 
 const STATE: RelayState = {
@@ -36,6 +58,9 @@ const STATE: RelayState = {
 	uid: null,
 	channels: new Map(),
 	attached: new Set(),
+	status: "connecting",
+	statusListeners: new Map(),
+	reconnectAttempts: 0,
 };
 
 export interface RelayOptions {
@@ -43,26 +68,55 @@ export interface RelayOptions {
 	sseUrl?: string;
 	/** Subscribe POST endpoint. Defaults to `/__relay/subscribe`. */
 	subscribeUrl?: string;
+	/** Unsubscribe POST endpoint. Defaults to `/__relay/unsubscribe`. */
+	unsubscribeUrl?: string;
 	/** Optional bearer token (for guarded relay routes). */
 	bearer?: string;
+	/**
+	 * Give up after this many consecutive reconnect attempts. Default 5
+	 * (Transmit parity). `0` disables the cap — the browser's native
+	 * EventSource keeps retrying forever.
+	 */
+	maxReconnectAttempts?: number;
+	/** Fired before each reconnect attempt with the 1-based attempt count. */
+	onReconnectAttempt?: (attempt: number) => void;
+	/** Fired once when `maxReconnectAttempts` is exhausted and we give up. */
+	onReconnectFailed?: () => void;
 }
 
-let CONFIG: Required<RelayOptions> = {
+interface RelayConfigResolved {
+	sseUrl: string;
+	subscribeUrl: string;
+	unsubscribeUrl: string;
+	bearer: string;
+	maxReconnectAttempts: number;
+	onReconnectAttempt?: (attempt: number) => void;
+	onReconnectFailed?: () => void;
+}
+
+let CONFIG: RelayConfigResolved = {
 	sseUrl: "/__relay/events",
 	subscribeUrl: "/__relay/subscribe",
+	unsubscribeUrl: "/__relay/unsubscribe",
 	bearer: "",
+	maxReconnectAttempts: 5,
 };
 
 /**
- * Configure the relay endpoints + bearer. Call once at boot if you
- * need to override the defaults. Multiple calls overwrite — last call
- * wins.
+ * Configure the relay endpoints + bearer + reconnect policy. Call once
+ * at boot if you need to override the defaults. Multiple calls overwrite
+ * — last call wins.
  */
 export function configureRelay(options: RelayOptions): void {
 	CONFIG = {
 		sseUrl: options.sseUrl ?? CONFIG.sseUrl,
 		subscribeUrl: options.subscribeUrl ?? CONFIG.subscribeUrl,
+		unsubscribeUrl: options.unsubscribeUrl ?? CONFIG.unsubscribeUrl,
 		bearer: options.bearer ?? CONFIG.bearer,
+		maxReconnectAttempts:
+			options.maxReconnectAttempts ?? CONFIG.maxReconnectAttempts,
+		onReconnectAttempt: options.onReconnectAttempt ?? CONFIG.onReconnectAttempt,
+		onReconnectFailed: options.onReconnectFailed ?? CONFIG.onReconnectFailed,
 	};
 }
 
@@ -103,11 +157,36 @@ const CLIENT: RelayClient = {
 			});
 		}
 
-		// Detacher — only removes the local listener. The server-side
-		// subscription stays open; closing it would interrupt other
-		// listeners on the same channel.
+		// Detacher — removes the local listener. When it was the LAST handler
+		// on the channel, the server-side subscription is dropped too (POST
+		// /__relay/unsubscribe), so the server stops streaming a channel
+		// nobody's listening to. Other channels / other listeners are
+		// untouched.
 		return () => {
 			handlers?.delete(adapted);
+			if (handlers && handlers.size === 0) {
+				STATE.channels.delete(channel);
+				if (STATE.uid) {
+					postUnsubscribe(channel).catch((err: unknown) => {
+						console.warn(
+							`[aurora/relay] unsubscribe from ${channel} failed:`,
+							err,
+						);
+					});
+				}
+			}
+		};
+	},
+
+	on(status, callback) {
+		let set = STATE.statusListeners.get(status);
+		if (!set) {
+			set = new Set();
+			STATE.statusListeners.set(status, set);
+		}
+		set.add(callback);
+		return () => {
+			set?.delete(callback);
 		};
 	},
 
@@ -119,6 +198,7 @@ const CLIENT: RelayClient = {
 		STATE.uid = null;
 		STATE.channels.clear();
 		STATE.attached.clear();
+		STATE.reconnectAttempts = 0;
 	},
 };
 
@@ -126,11 +206,16 @@ function open(): void {
 	const sse = new EventSource(CONFIG.sseUrl);
 	STATE.sse = sse;
 	STATE.attached = new Set();
+	changeStatus("connecting");
 
 	sse.addEventListener("connected", (ev) => {
 		const data = safeJson<{ uid?: string }>(messageData(ev));
 		if (data && typeof data.uid === "string") {
 			STATE.uid = data.uid;
+			// A successful (re)connect clears the failure counter and flips the
+			// status back to `connected`.
+			STATE.reconnectAttempts = 0;
+			changeStatus("connected");
 			// Re-apply EVERY active subscription on each (re)connect. The server
 			// assigns a fresh uid per connection and has no memory of prior
 			// subscriptions, so both the first connect AND browser auto-reconnects
@@ -147,11 +232,46 @@ function open(): void {
 		}
 	});
 
+	// The native EventSource auto-reconnects on a dropped connection, firing
+	// `error` each time. Mirror Transmit's reconnect bookkeeping: surface a
+	// `disconnected` → `reconnecting` transition, count attempts, and once the
+	// cap is reached close the stream (stopping the native retry loop) and fire
+	// `onReconnectFailed`.
+	sse.addEventListener("error", () => {
+		if (STATE.status !== "reconnecting") changeStatus("disconnected");
+		changeStatus("reconnecting");
+		CONFIG.onReconnectAttempt?.(STATE.reconnectAttempts + 1);
+		if (
+			CONFIG.maxReconnectAttempts > 0 &&
+			STATE.reconnectAttempts >= CONFIG.maxReconnectAttempts
+		) {
+			sse.close();
+			if (STATE.sse === sse) STATE.sse = null;
+			CONFIG.onReconnectFailed?.();
+			return;
+		}
+		STATE.reconnectAttempts++;
+	});
+
 	// 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);
 }
 
+/** Update the status and notify every listener registered for it. */
+function changeStatus(status: RelayStatus): void {
+	STATE.status = status;
+	const set = STATE.statusListeners.get(status);
+	if (!set) return;
+	for (const cb of set) {
+		try {
+			cb(status);
+		} catch (err) {
+			console.warn(`[aurora/relay] status listener for ${status} threw:`, err);
+		}
+	}
+}
+
 /**
  * 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
@@ -183,21 +303,51 @@ function messageData(ev: Event): string | null {
 	return null;
 }
 
-async function postSubscribe(channel: string): Promise<void> {
+function postSubscribe(channel: string): Promise<void> {
+	return postHandshake(CONFIG.subscribeUrl, channel);
+}
+
+function postUnsubscribe(channel: string): Promise<void> {
+	return postHandshake(CONFIG.unsubscribeUrl, channel);
+}
+
+/**
+ * POST a `{ uid, channel }` handshake to a relay endpoint. Sends the
+ * signed-CSRF trio blackhole expects: the `XSRF-TOKEN` cookie echoed as
+ * the `X-XSRF-TOKEN` header plus `credentials: 'include'` so the cookie
+ * itself rides along. Without both, the POST is rejected by the signed
+ * double-submit guard. Mirrors `HttpClient.#retrieveXsrfToken` /
+ * `createRequest` in `@adonisjs/transmit-client`.
+ */
+async function postHandshake(url: string, channel: string): Promise<void> {
 	const headers: Record<string, string> = {
 		"content-type": "application/json",
 	};
 	if (CONFIG.bearer) headers.authorization = `Bearer ${CONFIG.bearer}`;
-	const res = await fetch(CONFIG.subscribeUrl, {
+	const xsrf = retrieveXsrfToken();
+	if (xsrf !== null) headers["x-xsrf-token"] = xsrf;
+	const res = await fetch(url, {
 		method: "POST",
 		headers,
 		body: JSON.stringify({ uid: STATE.uid, channel }),
+		credentials: "include",
 	});
 	if (!res.ok) {
 		throw new Error(`HTTP ${res.status}`);
 	}
 }
 
+/**
+ * Read the `XSRF-TOKEN` cookie so it can be echoed as the `X-XSRF-TOKEN`
+ * header (signed double-submit CSRF). Browser-only — returns `null` under
+ * SSR / any environment without `document`.
+ */
+function retrieveXsrfToken(): string | null {
+	if (typeof document === "undefined") return null;
+	const match = document.cookie.match(/(?:^|;\s*)XSRF-TOKEN=([^;]*)/);
+	return match ? decodeURIComponent(match[1]) : null;
+}
+
 function safeJson<T>(raw: unknown): T | null {
 	if (typeof raw !== "string") return null;
 	try {

package/src/server/renderPage.ts

@@ -52,6 +52,12 @@ export interface RenderPageOptions {
 	/**
 	 * Extra markup spliced into `<head>` after the importmap. Use to
 	 * inject `<title>`, meta tags, stylesheets.
+	 *
+	 * ⚠️ Injected RAW / unescaped — it IS `<head>` markup, so it cannot be
+	 * HTML-escaped. Pass ONLY trusted, server-authored strings; NEVER
+	 * interpolate request/user input into it (that is an HTML-injection
+	 * sink). Build any dynamic head content through an escaping helper
+	 * upstream before handing it here.
 	 */
 	headExtra?: string;
 	/**

package/src/server/serveAssets.ts

@@ -72,7 +72,10 @@ export interface ServeAssetsOptions {
 export function serveAssets(
 	options: ServeAssetsOptions,
 ): (ctx: AssetsHttpContext) => Promise<void> {
-	const root = options.root;
+	// Normalize the root ONCE so the lexical containment gate below compares
+	// like-for-like: a raw root with a trailing slash or a non-normalized
+	// segment would never match the resolved request path → spurious 403s.
+	const root = resolvePath(options.root);
 	const cacheControl = options.cacheControl ?? "public, max-age=60";
 	// Canonicalize the root ONCE at handler creation. The realpath check
 	// below compares against this canonical form so a symlinked root