@voltro/plugin-broadcast 0.24.0 → 0.26.0

package/dist/index.d.ts

@@ -23,10 +23,29 @@ export declare interface AttachBroadcastBusOptions {
     readonly logger?: BroadcastBusLogger;
     /** Channel override (tests). Default `voltro:changes`. */
     readonly channel?: string;
+    /**
+     * Called when this replica proves it missed changes from a peer.
+     *
+     * The count is EXACT — the difference between the serial in hand and the last
+     * one seen from that origin — not an estimate. There is nothing to replay
+     * (pub/sub keeps no log), so the caller's job is to make the loss irrelevant:
+     * a live query is idempotent, so re-running every one of them is always safe
+     * and always correct. `voltro dev` and `voltro serve` wire this to the
+     * dispatcher's refresh.
+     *
+     * Absent ⇒ the gap is still DETECTED and logged; only the recovery is
+     * missing. That is deliberate: a bus used without a dispatcher (a test, an
+     * embedder) should still say what it lost.
+     */
+    readonly onGap?: (origin: string, missed: number) => void;
 }
 
-/** The channel the bus fans ChangeEvents out on. */
-export declare const BROADCAST_CHANNEL = "voltro:changes";
+/**
+ * The changes channel when no namespace is known — a last resort, not the
+ * normal path. A real boot resolves a namespace from the app's name and passes
+ * the channel in, so two apps on one broker do not share it.
+ */
+export declare const BROADCAST_CHANNEL: string;
 
 export declare interface BroadcastBusHandle {
     /** Detach the onChange listener, the bus subscription, and close the
@@ -40,6 +59,9 @@ export declare interface BroadcastBusLogger {
     debug: (message: string, fields?: Record<string, unknown>) => void;
 }
 
+/** The channels the framework runs over one broker. */
+export declare type BroadcastChannelKind = 'changes' | 'events' | 'members' | 'presence';
+
 /**
  * What rides the wire on the `voltro:changes` channel. `origin` is the
  * publishing replica's id; subscribers skip their OWN origin (the writer
@@ -50,6 +72,21 @@ export declare interface BroadcastBusLogger {
 export declare interface BroadcastEnvelope {
     readonly origin: string;
     readonly event: ChangeEvent;
+    /**
+     * This origin's monotonic serial, from 1.
+     *
+     * The one thing a receiver cannot infer, and without it a dropped message is
+     * undetectable: pub/sub has no retention, so a replica whose broker
+     * connection blips simply never learns that a change happened. Its clients
+     * keep their sockets — the client-side reconnect never fires — and their live
+     * queries stay stale until something else touches the same table, which for a
+     * quiet table can be never.
+     *
+     * Optional on the type because a message from an older replica during a
+     * rolling deploy has none; the receiver treats that as "cannot tell" rather
+     * than as a gap.
+     */
+    readonly n?: number;
 }
 
 /**
@@ -87,6 +124,12 @@ export declare interface BroadcastPlugin extends VoltroPlugin {
         readonly provider: BroadcastProvider;
         readonly url: string | null;
         readonly crossReplica: boolean;
+        /**
+         * The namespace as DECLARED here, before the app name or env is consulted.
+         * `undefined` means "derive it" — the framework resolves the effective value
+         * at boot, because only it knows the app's name.
+         */
+        readonly namespace: string | undefined;
     };
 }
 
@@ -106,12 +149,18 @@ export declare interface BroadcastPluginOptions {
      *  `REDIS_URL`). Point broadcast at its own server or the shared one purely
      *  by which env var you set. */
     readonly connection?: string;
-    /** Channel the bus publishes/subscribes on. Namespace it per app/env
-     *  (e.g. `myapp:prod:changes`) when several deployments share one
-     *  broker — otherwise they inject each other's ChangeEvents (spurious
-     *  wake-ups; matcher-scoped, so no data leak, but wasted work).
-     *  Default `BROADCAST_CHANNEL` env, else `voltro:changes`. */
-    readonly channel?: string;
+    /**
+     * Namespace for EVERY framework channel on this broker — changes, events,
+     * membership and presence alike.
+     *
+     * Defaults to your app's name, so two different apps sharing one Redis or
+     * NATS separate without anyone remembering to do anything. Set it explicitly
+     * for the case that default cannot see: **several deployments of the SAME app
+     * on one broker** (staging and production, say) have the same name and the
+     * same code, so nothing derivable tells them apart. There, this — or
+     * `VOLTRO_BROADCAST_NAMESPACE` — is the only thing that works.
+     */
+    readonly namespace?: string;
     /** Disambiguates multiple instances of this plugin in one app. */
     readonly name?: string;
 }
@@ -150,6 +199,33 @@ export declare interface BroadcastStore {
     injectExternalChange: (event: ChangeEvent) => void;
 }
 
+/**
+ * One framework channel inside a namespace.
+ *
+ * Every channel goes through here so a fifth one cannot be added as a flat
+ * constant that quietly skips the namespace — which is how the first four came
+ * to be flat in the first place.
+ */
+export declare const channelFor: (namespace: string, kind: BroadcastChannelKind) => string;
+
+/**
+ * The namespace used when nothing else is known.
+ *
+ * Only reachable when there is no app name to derive from — a bare library use.
+ * A real boot always has one.
+ */
+export declare const DEFAULT_BROADCAST_NAMESPACE = "voltro";
+
+/**
+ * The channel for ONE declared event.
+ *
+ * Per event rather than per app, so a replica can decline the traffic it has no
+ * subscribers for. The event name comes from a declaration and is unique by boot
+ * audit, but it is sanitised anyway: a name containing a NATS wildcard would
+ * turn one event's channel into a pattern matching others.
+ */
+export declare const eventChannelFor: (namespace: string, event: string) => string;
+
 /**
  * Pull the resolved broadcast carrier off a plugin list (the framework's
  * serve pipeline calls this after building the store). Returns the FIRST
@@ -210,6 +286,32 @@ export declare interface RedisProviderOptions {
 
 /* Excluded from this release type: resetMemoryBus */
 
+/**
+ * Resolve the namespace every framework channel hangs off.
+ *
+ * Deriving from the app name by DEFAULT rather than requiring configuration, and
+ * that ordering is the whole point: a namespace you must remember to set is one
+ * two apps forget to set, and the failure is silent in the worst direction —
+ * one deployment's events arriving at another's clients. The default has to be
+ * safe; configuration is for where the default cannot see.
+ *
+ * And it genuinely cannot see one case, which is worth stating plainly rather
+ * than papering over: STAGING AND PRODUCTION OF THE SAME APP have the same name,
+ * the same code and the same fingerprint. Nothing derivable separates them. If
+ * one broker serves several deployments of one app, the env var is not optional
+ * — it is the only thing that can work, and the docs say so.
+ */
+export declare const resolveBroadcastNamespace: (input: ResolveBroadcastNamespaceInput) => string;
+
+export declare interface ResolveBroadcastNamespaceInput {
+    /** `broadcast({ namespace })` — explicit, and wins over everything. */
+    readonly option?: string | undefined;
+    /** `VOLTRO_BROADCAST_NAMESPACE` — for the case the code cannot see. */
+    readonly env?: string | undefined;
+    /** The app's name, the default. Different apps therefore separate on their own. */
+    readonly appName?: string | undefined;
+}
+
 export declare interface ResolveBroadcastOptions {
     /** Explicit provider name or a pre-built `BroadcastProvider`. */
     readonly provider?: BroadcastProviderName | BroadcastProvider;

package/dist/index.js

@@ -1,28 +1,39 @@
 import { Effect as e, Schema as t } from "effect";
 import { definePlugin as n } from "@voltro/protocol";
-//#region src/types.ts
-var r = class extends t.TaggedError()("BroadcastError", {
+//#region src/namespace.ts
+var r = "voltro", i = (e) => e.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, ""), a = (e) => {
+	for (let t of [
+		e.option,
+		e.env,
+		e.appName
+	]) {
+		if (t === void 0) continue;
+		let e = i(t);
+		if (e.length > 0) return e;
+	}
+	return r;
+}, o = (e, t) => `${e}:${t}`, s = (e, t) => `${o(e, "events")}:${i(t)}`, c = class extends t.TaggedError()("BroadcastError", {
 	provider: t.String,
 	message: t.String,
 	transient: t.Boolean,
 	cause: t.optional(t.Unknown)
-}) {}, i = "voltro:changes", a = (e, t, n) => new r({
+}) {}, l = o(r, "changes"), u = (e, t, n) => new c({
 	provider: e,
 	message: t,
 	transient: !0,
 	...n === void 0 ? {} : { cause: n }
-}), o = (e, t, n) => new r({
+}), d = (e, t, n) => new c({
 	provider: e,
 	message: t,
 	transient: !1,
 	...n === void 0 ? {} : { cause: n }
-}), s = /* @__PURE__ */ new Map(), c = (e) => {
-	let t = s.get(e);
-	return t || (t = { handlers: /* @__PURE__ */ new Map() }, s.set(e, t)), t;
-}, l = (e) => {
-	s.get(e)?.handlers.clear();
-}, u = (t = `default-${Math.random().toString(36).slice(2)}`) => {
-	let n = c(t);
+}), f = /* @__PURE__ */ new Map(), p = (e) => {
+	let t = f.get(e);
+	return t || (t = { handlers: /* @__PURE__ */ new Map() }, f.set(e, t)), t;
+}, m = (e) => {
+	f.get(e)?.handlers.clear();
+}, h = (t = `default-${Math.random().toString(36).slice(2)}`) => {
+	let n = p(t);
 	return {
 		name: "memory",
 		publish: (t, r) => e.sync(() => {
@@ -39,7 +50,7 @@ var r = class extends t.TaggedError()("BroadcastError", {
 		}),
 		close: () => e.void
 	};
-}, d = (t) => {
+}, g = (t) => {
 	let n = null, r = () => n || (n = (async () => {
 		let e;
 		if (t.client) e = t.client;
@@ -48,7 +59,7 @@ var r = class extends t.TaggedError()("BroadcastError", {
 			try {
 				n = (await import("ioredis")).default;
 			} catch (e) {
-				throw o("redis", "the 'redis' broadcast provider requires the 'ioredis' optional dependency. Install it to enable it.", e);
+				throw d("redis", "the 'redis' broadcast provider requires the 'ioredis' optional dependency. Install it to enable it.", e);
 			}
 			e = new n(t.url);
 		}
@@ -65,7 +76,7 @@ var r = class extends t.TaggedError()("BroadcastError", {
 				let { pub: e } = await r();
 				await e.publish(t, n);
 			},
-			catch: (e) => a("redis", `publish failed: ${String(e?.message ?? e)}`, e)
+			catch: (e) => u("redis", `publish failed: ${String(e?.message ?? e)}`, e)
 		}),
 		subscribe: (t, n) => e.tryPromise({
 			try: async () => {
@@ -76,7 +87,7 @@ var r = class extends t.TaggedError()("BroadcastError", {
 					e.off("message", i), e.unsubscribe(t);
 				};
 			},
-			catch: (e) => a("redis", `subscribe failed: ${String(e?.message ?? e)}`, e)
+			catch: (e) => u("redis", `subscribe failed: ${String(e?.message ?? e)}`, e)
 		}),
 		close: () => e.promise(async () => {
 			if (n) try {
@@ -85,28 +96,28 @@ var r = class extends t.TaggedError()("BroadcastError", {
 			} catch {}
 		})
 	};
-}, f = new TextEncoder(), p = new TextDecoder(), m = (t) => {
+}, _ = new TextEncoder(), v = new TextDecoder(), y = (t) => {
 	let n = null, r = () => import("@nats-io/transport-node").catch((e) => {
-		throw o("nats", "the 'nats' broadcast provider requires the '@nats-io/transport-node' optional dependency. Install it to enable it.", e);
+		throw d("nats", "the 'nats' broadcast provider requires the '@nats-io/transport-node' optional dependency. Install it to enable it.", e);
 	}), i = () => n || (n = (async () => t.connection ? t.connection : (await r()).connect({ servers: t.url }))(), n);
 	return {
 		name: "nats",
 		publish: (t, n) => e.tryPromise({
 			try: async () => {
-				(await i()).publish(t, f.encode(n));
+				(await i()).publish(t, _.encode(n));
 			},
-			catch: (e) => a("nats", `publish failed: ${String(e?.message ?? e)}`, e)
+			catch: (e) => u("nats", `publish failed: ${String(e?.message ?? e)}`, e)
 		}),
 		subscribe: (t, n) => e.tryPromise({
 			try: async () => {
 				let e = (await i()).subscribe(t);
 				return (async () => {
-					for await (let t of e) n(p.decode(t.data));
+					for await (let t of e) n(v.decode(t.data));
 				})(), () => {
 					e.unsubscribe();
 				};
 			},
-			catch: (e) => a("nats", `subscribe failed: ${String(e?.message ?? e)}`, e)
+			catch: (e) => u("nats", `subscribe failed: ${String(e?.message ?? e)}`, e)
 		}),
 		close: () => e.promise(async () => {
 			if (n) try {
@@ -115,7 +126,7 @@ var r = class extends t.TaggedError()("BroadcastError", {
 			} catch {}
 		})
 	};
-}, h = (e, t) => t[`${e.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_REDIS_URL`], g = (e, t) => {
+}, b = (e, t) => t[`${e.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_REDIS_URL`], x = (e, t) => {
 	if (e.provider && typeof e.provider == "object") {
 		let t = e.provider;
 		return {
@@ -124,16 +135,16 @@ var r = class extends t.TaggedError()("BroadcastError", {
 			crossReplica: t.name !== "memory"
 		};
 	}
-	let n = e.url ?? t.BROADCAST_URL ?? null, r = h(e.connection ?? "broadcast", t), i = e.connection !== void 0;
+	let n = e.url ?? t.BROADCAST_URL ?? null, r = b(e.connection ?? "broadcast", t), i = e.connection !== void 0;
 	switch ((e.provider ?? t.BROADCAST_PROVIDER)?.toLowerCase() ?? (n?.startsWith("nats://") ? "nats" : n?.startsWith("redis://") || n?.startsWith("rediss://") || r || i && t.REDIS_URL ? "redis" : void 0)) {
 		case "redis": {
 			let e = n ?? r ?? t.REDIS_URL;
 			return e ? {
-				provider: d({ url: e }),
+				provider: g({ url: e }),
 				url: e,
 				crossReplica: !0
 			} : {
-				provider: u(),
+				provider: h(),
 				url: null,
 				crossReplica: !1
 			};
@@ -141,22 +152,22 @@ var r = class extends t.TaggedError()("BroadcastError", {
 		case "nats": {
 			let e = n ?? t.NATS_URL;
 			return e ? {
-				provider: m({ url: e }),
+				provider: y({ url: e }),
 				url: e,
 				crossReplica: !0
 			} : {
-				provider: u(),
+				provider: h(),
 				url: null,
 				crossReplica: !1
 			};
 		}
 		default: return {
-			provider: u(),
+			provider: h(),
 			url: null,
 			crossReplica: !1
 		};
 	}
-}, _ = ["network:outbound:*"], v = [
+}, S = ["network:outbound:*"], C = [
 	{
 		name: "BROADCAST_URL",
 		required: !1,
@@ -192,8 +203,8 @@ var r = class extends t.TaggedError()("BroadcastError", {
 		description: "Fallback broker URL used when the resolved provider is nats and no BROADCAST_URL is set (comma-separated for a cluster).",
 		example: "nats://localhost:4222"
 	}
-], y = (t = {}) => {
-	let r = g({
+], w = (t = {}) => {
+	let r = x({
 		...t.provider === void 0 ? {} : { provider: t.provider },
 		...t.url === void 0 ? {} : { url: t.url },
 		...t.connection === void 0 ? {} : { connection: t.connection }
@@ -202,8 +213,8 @@ var r = class extends t.TaggedError()("BroadcastError", {
 		...n({
 			name: t.name ? `@voltro/plugin-broadcast#${t.name}` : "@voltro/plugin-broadcast",
 			description: "Cross-replica reactivity — fans out app-mutation ChangeEvents to every replica over a pub/sub bus (Redis / NATS). ADDITIVE to inline emit: local reactivity survives a broker outage. Closes the single-instance gap for every non-postgres dialect.",
-			permissions: _,
-			declaredEnv: v,
+			permissions: S,
+			declaredEnv: C,
 			onActivate: (t) => e.sync(() => {
 				r.crossReplica ? t.logger.info("broadcast active", {
 					provider: r.provider.name,
@@ -215,40 +226,61 @@ var r = class extends t.TaggedError()("BroadcastError", {
 		broadcast: {
 			provider: r.provider,
 			url: r.url,
-			crossReplica: r.crossReplica
+			crossReplica: r.crossReplica,
+			namespace: t.namespace
 		}
 	};
-}, b = (e) => {
-	for (let t of e) if (x(t)) return t;
+}, T = (e) => {
+	for (let t of e) if (E(t)) return t;
 	return null;
-}, x = (e) => typeof e.broadcast == "object" && e.broadcast !== null && typeof e.broadcast.provider == "object", S = {
+}, E = (e) => typeof e.broadcast == "object" && e.broadcast !== null && typeof e.broadcast.provider == "object", D = {
 	info: () => {},
 	warn: () => {},
 	debug: () => {}
-}, C = async (t) => {
-	let { store: n, provider: r, replicaId: i } = t, a = t.logger ?? S, o = t.channel ?? "voltro:changes", s = !1, c = !1, l = await e.runPromise(r.subscribe(o, (e) => {
-		let t;
+}, O = async (t) => {
+	let { store: n, provider: r, replicaId: i } = t, a = t.logger ?? D, o = t.channel ?? l, s = !1, c = !1, u = 0, d = /* @__PURE__ */ new Map(), f = await e.runPromise(r.subscribe(o, (e) => {
+		let r;
 		try {
-			t = JSON.parse(e);
+			r = JSON.parse(e);
 		} catch {
 			a.warn("broadcast: bad payload (not JSON)", { channel: o });
 			return;
 		}
-		if (t.origin !== i && !(!t.event || typeof t.event != "object")) {
+		if (r.origin !== i && !(!r.event || typeof r.event != "object")) {
+			if (typeof r.n == "number" && Number.isFinite(r.n)) {
+				let e = d.get(r.origin);
+				if (e !== void 0 && r.n > e + 1) {
+					let n = r.n - e - 1;
+					a.warn("broadcast: missed changes from a peer — refreshing live queries, which is safe because a query is idempotent", {
+						origin: r.origin,
+						missed: n,
+						from: e,
+						to: r.n
+					});
+					try {
+						t.onGap?.(r.origin, n);
+					} catch (e) {
+						a.warn("broadcast: gap recovery threw", { err: e });
+					}
+				}
+				(e === void 0 || r.n > e) && d.set(r.origin, r.n);
+			}
 			s = !0;
 			try {
-				n.injectExternalChange(t.event);
+				n.injectExternalChange(r.event);
 			} catch (e) {
 				a.warn("broadcast: inject failed", { err: e });
 			} finally {
 				s = !1;
 			}
 		}
-	})), u = n.onChange((t) => {
+	})), p = n.onChange((t) => {
 		if (s) return;
+		u += 1;
 		let n = {
 			origin: i,
-			event: t
+			event: t,
+			n: u
 		};
 		e.runPromise(r.publish(o, JSON.stringify(n)).pipe(e.tap(() => e.sync(() => {
 			c = !1;
@@ -265,16 +297,16 @@ var r = class extends t.TaggedError()("BroadcastError", {
 		channel: o,
 		replicaId: i
 	});
-	let d = !1;
+	let m = !1;
 	return { close: async () => {
-		if (!d) {
-			d = !0, u();
+		if (!m) {
+			m = !0, p();
 			try {
-				l();
+				f();
 			} catch {}
 			await e.runPromise(r.close());
 		}
 	} };
 };
 //#endregion
-export { i as BROADCAST_CHANNEL, r as BroadcastError, C as attachBroadcastBus, y as broadcastPlugin, b as getBroadcastPlugin, u as memoryProvider, m as natsProvider, d as redisProvider, l as resetMemoryBus, g as resolveBroadcastProvider };
+export { l as BROADCAST_CHANNEL, c as BroadcastError, r as DEFAULT_BROADCAST_NAMESPACE, O as attachBroadcastBus, w as broadcastPlugin, o as channelFor, s as eventChannelFor, T as getBroadcastPlugin, h as memoryProvider, y as natsProvider, g as redisProvider, m as resetMemoryBus, a as resolveBroadcastNamespace, x as resolveBroadcastProvider };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-broadcast",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Cross-replica reactivity — a pub/sub message bus (Redis / NATS / memory) that fans out app-mutation ChangeEvents to every replica behind a load balancer. ADDITIVE to inline emit: local reactivity survives a broker outage; cross-replica degrades gracefully. Closes the single-instance gap for every non-postgres dialect (postgres keeps native LISTEN/NOTIFY).",
   "keywords": [
     "voltro",
@@ -32,8 +32,8 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.24.0",
-    "@voltro/protocol": "0.24.0"
+    "@voltro/database": "0.26.0",
+    "@voltro/protocol": "0.26.0"
   },
   "optionalDependencies": {
     "@nats-io/transport-node": "^3.4.0",