@voltro/plugin-broadcast 0.84.0 → 0.86.0

package/dist/index.js

@@ -1,441 +1,7 @@
-import { Effect as e, Metric as t, Schema as n } from "effect";
-import { definePlugin as r } from "@voltro/protocol";
-//#region src/namespace.ts
-var i = "voltro", a = (e) => e.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, ""), o = (e) => {
-	let t = s(e), n = [e.option, e.env].find((e) => e !== void 0 && a(e).length > 0);
-	return {
-		resolved: t,
-		configured: n,
-		changed: n !== void 0 && n !== t
-	};
-}, s = (e) => {
-	for (let t of [
-		e.option,
-		e.env,
-		e.appName
-	]) {
-		if (t === void 0) continue;
-		let e = a(t);
-		if (e.length > 0) return e;
-	}
-	return i;
-}, c = (e, t) => `${e}:${t}`, l = (e, t) => `${c(e, "events")}:${a(t)}`, u = class extends n.TaggedError()("BroadcastError", {
-	provider: n.String,
-	message: n.String,
-	transient: n.Boolean,
-	cause: n.optional(n.Unknown)
-}) {}, d = c(i, "changes"), f = (e, t, n) => new u({
-	provider: e,
-	message: t,
-	transient: !0,
-	...n === void 0 ? {} : { cause: n }
-}), p = (e, t, n) => new u({
-	provider: e,
-	message: t,
-	transient: !1,
-	...n === void 0 ? {} : { cause: n }
-}), m = () => {
-	let e = /* @__PURE__ */ new Set();
-	return {
-		subscribe: (t) => (e.add(t), () => {
-			e.delete(t);
-		}),
-		emit: (t) => {
-			for (let n of e) try {
-				n(t);
-			} catch {}
-		}
-	};
-}, h = /* @__PURE__ */ new Map(), g = (e) => {
-	let t = h.get(e);
-	return t || (t = { handlers: /* @__PURE__ */ new Map() }, h.set(e, t)), t;
-}, _ = (e) => {
-	h.get(e)?.handlers.clear();
-}, v = (t = `default-${Math.random().toString(36).slice(2)}`) => {
-	let n = g(t);
-	return {
-		name: "memory",
-		publish: (t, r) => e.sync(() => {
-			let e = n.handlers.get(t);
-			if (e) for (let t of e) try {
-				t(r);
-			} catch {}
-		}),
-		subscribe: (t, r) => e.sync(() => {
-			let e = n.handlers.get(t) ?? /* @__PURE__ */ new Set();
-			return e.add(r), n.handlers.set(t, e), () => {
-				e.delete(r);
-			};
-		}),
-		close: () => e.void
-	};
-}, y = (t) => {
-	let n = null, r = m(), i = !0, a = () => n || (n = (async () => {
-		let e;
-		if (t.client) e = t.client;
-		else {
-			let n;
-			try {
-				n = (await import("ioredis")).default;
-			} catch (e) {
-				throw p("redis", "the 'redis' broadcast provider requires the 'ioredis' optional dependency. Install it to enable it.", e);
-			}
-			e = new n(t.url);
-		}
-		let n = e.duplicate();
-		return e.on("error", () => {}), n.on("error", () => {}), n.on("reconnecting", () => {
-			i && (i = !1, r.emit({
-				kind: "disconnected",
-				detail: "ioredis is re-dialling"
-			}));
-		}), n.on("ready", () => {
-			i || (i = !0, r.emit({ kind: "reconnected" }));
-		}), {
-			pub: e,
-			sub: n
-		};
-	})().catch((e) => {
-		throw n = null, e;
-	}), n);
-	return {
-		name: "redis",
-		onTransportEvent: r.subscribe,
-		publish: (t, n) => e.tryPromise({
-			try: async () => {
-				let { pub: e } = await a();
-				await e.publish(t, n);
-			},
-			catch: (e) => f("redis", `publish failed: ${String(e?.message ?? e)}`, e)
-		}),
-		subscribe: (t, n) => e.tryPromise({
-			try: async () => {
-				let { sub: e } = await a(), r = (e, r) => {
-					e === t && n(r);
-				};
-				return e.on("message", r), await e.subscribe(t), () => {
-					e.off("message", r), e.unsubscribe(t).catch(() => void 0);
-				};
-			},
-			catch: (e) => f("redis", `subscribe failed: ${String(e?.message ?? e)}`, e)
-		}),
-		close: () => e.promise(async () => {
-			if (n) try {
-				let { pub: e, sub: r } = await n;
-				await r.quit(), t.client || await e.quit();
-			} catch {}
-		})
-	};
-}, b = new TextEncoder(), x = new TextDecoder(), S = (t) => {
-	let n = null, r = m(), i = !0, a = (e) => {
-		(async () => {
-			try {
-				for await (let t of e.status()) t.type === "disconnect" && i ? (i = !1, r.emit({
-					kind: "disconnected",
-					detail: "nats disconnected"
-				})) : t.type === "reconnect" && !i && (i = !0, r.emit({ kind: "reconnected" }));
-			} catch {}
-		})();
-	}, o = () => import("@nats-io/transport-node").catch((e) => {
-		throw p("nats", "the 'nats' broadcast provider requires the '@nats-io/transport-node' optional dependency. Install it to enable it.", e);
-	}), s = () => n || (n = (async () => {
-		if (t.connection) return t.connection;
-		let e = await (await o()).connect({
-			servers: t.url,
-			maxReconnectAttempts: -1,
-			waitOnFirstConnect: !0,
-			reconnectTimeWait: 2e3
-		});
-		return a(e), e;
-	})().catch((e) => {
-		throw n = null, e;
-	}), n);
-	return {
-		name: "nats",
-		onTransportEvent: r.subscribe,
-		publish: (t, n) => e.tryPromise({
-			try: async () => {
-				(await s()).publish(t, b.encode(n));
-			},
-			catch: (e) => f("nats", `publish failed: ${String(e?.message ?? e)}`, e)
-		}),
-		subscribe: (t, n) => e.tryPromise({
-			try: async () => {
-				let e = (await s()).subscribe(t), a = !1;
-				return (async () => {
-					for await (let t of e) n(x.decode(t.data));
-					!a && i && (i = !1, r.emit({
-						kind: "disconnected",
-						detail: `the nats subscription to '${t}' ended while the connection was up`
-					}));
-				})(), () => {
-					a = !0, e.unsubscribe();
-				};
-			},
-			catch: (e) => f("nats", `subscribe failed: ${String(e?.message ?? e)}`, e)
-		}),
-		close: () => e.promise(async () => {
-			if (n) try {
-				let e = await n;
-				t.connection || await e.drain();
-			} catch {}
-		})
-	};
-}, C = (e, t) => t[`${e.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_REDIS_URL`], w = (e, t) => {
-	if (e.provider && typeof e.provider == "object") {
-		let t = e.provider;
-		return {
-			provider: t,
-			url: e.url ?? null,
-			crossReplica: t.name !== "memory"
-		};
-	}
-	let n = e.url ?? t.BROADCAST_URL ?? null, r = C(e.connection ?? "broadcast", t), i = (e.provider ?? t.BROADCAST_PROVIDER)?.toLowerCase() ?? (n?.startsWith("nats://") ? "nats" : n?.startsWith("redis://") || n?.startsWith("rediss://") || r || t.REDIS_URL ? "redis" : void 0), a = (e.provider ?? t.BROADCAST_PROVIDER)?.toLowerCase();
-	if (a !== void 0 && a !== "redis" && a !== "nats" && a !== "memory") throw Error(`broadcastPlugin: unknown provider "${a}".\n  Valid: 'redis', 'nats', 'memory'.
-  A name we do not recognise used to fall through to the in-process bus, which boots fine on one replica and drops cross-replica traffic on the second.`);
-	if (n !== null && n !== "" && !/^(redis|rediss|nats):\/\//.test(n)) throw Error(`broadcastPlugin: url "${n}" names no provider we support.\n  Expected a redis://, rediss:// or nats:// url.`);
-	switch (i) {
-		case "redis": {
-			let e = n ?? r ?? t.REDIS_URL;
-			if (!e) {
-				if (a === "redis") throw Error("broadcastPlugin: provider \"redis\" was requested but no url resolves.\n  Set BROADCAST_URL, BROADCAST_REDIS_URL or REDIS_URL, or pass `url`.\n  Falling back to the in-process bus here would answer a stated requirement with a silent downgrade.");
-				return {
-					provider: v(),
-					url: null,
-					crossReplica: !1
-				};
-			}
-			return {
-				provider: y({ url: e }),
-				url: e,
-				crossReplica: !0
-			};
-		}
-		case "nats": {
-			let e = n ?? t.NATS_URL;
-			return e ? {
-				provider: S({ url: e }),
-				url: e,
-				crossReplica: !0
-			} : {
-				provider: v(),
-				url: null,
-				crossReplica: !1
-			};
-		}
-		default: return {
-			provider: v(),
-			url: null,
-			crossReplica: !1
-		};
-	}
-}, T = ["network:outbound:*"], E = [
-	{
-		name: "BROADCAST_URL",
-		required: !1,
-		secret: !0,
-		description: "Broker URL for the cross-replica bus, e.g. redis://host:6379 or nats://host:4222 (the scheme selects the provider). Absent → in-process memory fallback (single-process).",
-		example: "redis://localhost:6379"
-	},
-	{
-		name: "BROADCAST_REDIS_URL",
-		required: !1,
-		secret: !0,
-		description: "Named-connection redis url for the bus (the shared <NAME>_REDIS_URL convention, like CACHE_REDIS_URL / KV_REDIS_URL). Used when the redis provider is selected and no broker-agnostic BROADCAST_URL is set; falls back to REDIS_URL. Set it to put broadcast on its own server.",
-		example: "redis://localhost:6379"
-	},
-	{
-		name: "BROADCAST_PROVIDER",
-		required: !1,
-		secret: !1,
-		description: "Explicit provider: 'redis' | 'nats' | 'memory'. Overrides the scheme inferred from BROADCAST_URL. Default: inferred from the URL, else memory.",
-		example: "redis"
-	},
-	{
-		name: "REDIS_URL",
-		required: !1,
-		secret: !0,
-		description: "Fallback broker URL used when the resolved provider is redis and no BROADCAST_URL is set (also infers the redis provider when no provider/URL is given).",
-		example: "redis://localhost:6379"
-	},
-	{
-		name: "NATS_URL",
-		required: !1,
-		secret: !0,
-		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"
-	}
-], D = (t = {}) => {
-	let n = w({
-		...t.provider === void 0 ? {} : { provider: t.provider },
-		...t.url === void 0 ? {} : { url: t.url },
-		...t.connection === void 0 ? {} : { connection: t.connection }
-	}, process.env);
-	return {
-		...r({
-			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: T,
-			declaredEnv: E,
-			onActivate: (t) => e.sync(() => {
-				n.crossReplica ? t.logger.info("broadcast active", {
-					provider: n.provider.name,
-					url: n.url
-				}) : t.logger.warn("broadcast: resolved to the in-process memory provider — NO cross-replica fan-out. Set BROADCAST_URL (redis:// or nats://) for a real bus.");
-			}),
-			onDeactivate: () => e.void
-		}),
-		broadcast: {
-			provider: n.provider,
-			url: n.url,
-			crossReplica: n.crossReplica,
-			namespace: t.namespace
-		}
-	};
-}, O = (e) => {
-	for (let t of e) if (k(t)) return t;
-	return null;
-}, k = (e) => typeof e.broadcast == "object" && e.broadcast !== null && typeof e.broadcast.provider == "object", A = ({ origin: e, ...t }) => t, j = (e) => Math.min(500 * 2 ** Math.min(Math.max(e, 1) - 1, 5), 1e4), M = {
-	info: () => {},
-	warn: () => {},
-	debug: () => {}
-}, N = async (n) => {
-	let { store: r, provider: i, replicaId: a } = n, o = n.logger ?? M, s = n.channel ?? d, c = !1, l, u = !1, f = 0, p = /* @__PURE__ */ new Map(), m = `${Date.now().toString(36)}.${Math.random().toString(36).slice(2, 10)}`, h = t.gauge("voltro_broadcast_connected").pipe(t.tagged("provider", i.name)), g = t.counter("voltro_broadcast_gaps_total").pipe(t.tagged("provider", i.name)), _ = t.counter("voltro_broadcast_missed_total").pipe(t.tagged("provider", i.name)), v = t.counter("voltro_broadcast_reconnects_total").pipe(t.tagged("provider", i.name)), y = {
-		connected: !1,
-		lastReceivedAt: null,
-		lastPublishedAt: null,
-		reconnects: 0,
-		gaps: 0,
-		missed: 0
-	}, b = (n) => {
-		y.connected = n, e.runSync(t.set(h, +!!n));
-	};
-	b(!1);
-	let x = (r) => {
-		y.gaps += 1, e.runSync(t.increment(g)), r.missed !== void 0 && r.missed > 0 && (y.missed += r.missed, e.runSync(t.incrementBy(_, r.missed))), o.warn(`broadcast: ${r.reason} — refreshing live queries, which is safe because a query is idempotent`, {
-			...r.origin === void 0 ? {} : { origin: r.origin },
-			...r.missed === void 0 ? {} : { missed: r.missed }
-		});
-		try {
-			n.onGap?.(r);
-		} catch (e) {
-			o.warn("broadcast: gap recovery threw", { err: e });
-		}
-	}, S = (e) => {
-		y.lastReceivedAt = Date.now();
-		let t;
-		try {
-			t = JSON.parse(e);
-		} catch {
-			o.warn("broadcast: bad payload (not JSON)", { channel: s });
-			return;
-		}
-		if (t.origin === a || !t.event || typeof t.event != "object") return;
-		if (typeof t.n == "number" && Number.isFinite(t.n)) {
-			let e = t.epoch ?? "", n = p.get(t.origin);
-			n === void 0 ? p.set(t.origin, {
-				epoch: e,
-				n: t.n
-			}) : n.epoch === e ? (t.n > n.n + 1 && x({
-				reason: `missed ${t.n - n.n - 1} change(s) from ${t.origin}`,
-				origin: t.origin,
-				missed: t.n - n.n - 1
-			}), t.n > n.n && p.set(t.origin, {
-				epoch: e,
-				n: t.n
-			})) : p.set(t.origin, {
-				epoch: e,
-				n: t.n
-			});
-		}
-		let n = A(t.event);
-		c = !0, l = n;
-		try {
-			r.injectExternalChange(n);
-		} catch (e) {
-			o.warn("broadcast: inject failed", { err: e });
-		} finally {
-			c = !1, l = void 0;
-		}
-	}, C, w = !1, T = 0, E = async () => {
-		try {
-			return C = await e.runPromise(i.subscribe(s, S)), b(!0), !0;
-		} catch (e) {
-			return T += 1, T === 1 && o.warn("broadcast: could not subscribe — this replica will not receive other replicas' changes yet. Retrying in the background; local reactivity is unaffected.", {
-				provider: i.name,
-				channel: s,
-				err: e
-			}), !1;
-		}
-	};
-	await E() || (async () => {
-		let e = Date.now();
-		for (; !w && C === void 0;) {
-			if (await new Promise((e) => setTimeout(e, j(T))), w) return;
-			if (await E()) {
-				o.info("broadcast: subscribed", {
-					provider: i.name,
-					channel: s,
-					attempts: T
-				}), x({ reason: `this replica was not subscribed to '${s}' for ${Math.round((Date.now() - e) / 1e3)}s` });
-				return;
-			}
-		}
-	})();
-	let D = i.onTransportEvent?.((n) => {
-		if (n.kind === "disconnected") {
-			b(!1), o.warn("broadcast: transport disconnected — cross-replica fan-out is down until it re-dials", {
-				provider: i.name,
-				...n.detail === void 0 ? {} : { detail: n.detail }
-			});
-			return;
-		}
-		b(!0), y.reconnects += 1, e.runSync(t.increment(v)), o.warn("broadcast transport reconnected", {
-			provider: i.name,
-			channel: s,
-			replicaId: a,
-			reconnects: y.reconnects,
-			lastReceivedAt: y.lastReceivedAt
-		}), x({ reason: `the ${i.name} transport reconnected after an outage` });
-	}), O = r.onChange((t) => {
-		if (t.origin === "injected" || c && t === l) return;
-		f += 1;
-		let n = {
-			origin: a,
-			event: t,
-			n: f,
-			epoch: m
-		};
-		y.lastPublishedAt = Date.now(), e.runPromise(i.publish(s, JSON.stringify(n)).pipe(e.tap(() => e.sync(() => {
-			u = !1;
-		})), e.catchAll((t) => e.sync(() => {
-			u || (u = !0, o.warn("broadcast: publish failed — cross-replica fan-out degraded, local reactivity unaffected", {
-				provider: i.name,
-				transient: t.transient,
-				message: t.message
-			}));
-		}))));
-	});
-	return o.info("broadcast bus attached", {
-		provider: i.name,
-		channel: s,
-		replicaId: a
-	}), {
-		health: () => ({
-			provider: i.name,
-			channel: s,
-			replicaId: a,
-			...y
-		}),
-		close: async () => {
-			if (!w) {
-				w = !0, O(), D?.();
-				try {
-					C?.();
-				} catch {}
-				await e.runPromise(i.close());
-			}
-		}
-	};
-};
-//#endregion
-export { d as BROADCAST_CHANNEL, u as BroadcastError, i as DEFAULT_BROADCAST_NAMESPACE, N as attachBroadcastBus, D as broadcastPlugin, c as channelFor, o as describeNamespaceResolution, l as eventChannelFor, O as getBroadcastPlugin, v as memoryProvider, S as natsProvider, y as redisProvider, _ as resetMemoryBus, s as resolveBroadcastNamespace, w as resolveBroadcastProvider, j as subscribeRetryDelayMs };
+import { DEFAULT_BROADCAST_NAMESPACE as e, channelFor as t, describeNamespaceResolution as n, eventChannelFor as r, resolveBroadcastNamespace as i } from "./namespace.js";
+import { BROADCAST_CHANNEL as a, BroadcastError as o } from "./types.js";
+import { memoryProvider as s, natsProvider as c, redisProvider as l, resetMemoryBus as u } from "./providers.js";
+import { resolveBroadcastProvider as d } from "./resolve.js";
+import { broadcastPlugin as f, getBroadcastPlugin as p } from "./plugin.js";
+import { attachBroadcastBus as m, subscribeRetryDelayMs as h } from "./bus.js";
+export { a as BROADCAST_CHANNEL, o as BroadcastError, e as DEFAULT_BROADCAST_NAMESPACE, m as attachBroadcastBus, f as broadcastPlugin, t as channelFor, n as describeNamespaceResolution, r as eventChannelFor, p as getBroadcastPlugin, s as memoryProvider, c as natsProvider, l as redisProvider, u as resetMemoryBus, i as resolveBroadcastNamespace, d as resolveBroadcastProvider, h as subscribeRetryDelayMs };

package/dist/namespace.js

@@ -0,0 +1,22 @@
+//#region src/namespace.ts
+var e = "voltro", t = (e) => e.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, ""), n = (e) => {
+	let n = r(e), i = [e.option, e.env].find((e) => e !== void 0 && t(e).length > 0);
+	return {
+		resolved: n,
+		configured: i,
+		changed: i !== void 0 && i !== n
+	};
+}, r = (n) => {
+	for (let e of [
+		n.option,
+		n.env,
+		n.appName
+	]) {
+		if (e === void 0) continue;
+		let n = t(e);
+		if (n.length > 0) return n;
+	}
+	return e;
+}, i = (e, t) => `${e}:${t}`, a = (e, n) => `${i(e, "events")}:${t(n)}`;
+//#endregion
+export { e as DEFAULT_BROADCAST_NAMESPACE, i as channelFor, n as describeNamespaceResolution, a as eventChannelFor, r as resolveBroadcastNamespace };

package/dist/plugin.js

@@ -0,0 +1,73 @@
+import { resolveBroadcastProvider as e } from "./resolve.js";
+import { Effect as t } from "effect";
+import { definePlugin as n } from "@voltro/protocol";
+//#region src/plugin.ts
+var r = ["network:outbound:*"], i = [
+	{
+		name: "BROADCAST_URL",
+		required: !1,
+		secret: !0,
+		description: "Broker URL for the cross-replica bus, e.g. redis://host:6379 or nats://host:4222 (the scheme selects the provider). Absent → in-process memory fallback (single-process).",
+		example: "redis://localhost:6379"
+	},
+	{
+		name: "BROADCAST_REDIS_URL",
+		required: !1,
+		secret: !0,
+		description: "Named-connection redis url for the bus (the shared <NAME>_REDIS_URL convention, like CACHE_REDIS_URL / KV_REDIS_URL). Used when the redis provider is selected and no broker-agnostic BROADCAST_URL is set; falls back to REDIS_URL. Set it to put broadcast on its own server.",
+		example: "redis://localhost:6379"
+	},
+	{
+		name: "BROADCAST_PROVIDER",
+		required: !1,
+		secret: !1,
+		description: "Explicit provider: 'redis' | 'nats' | 'memory'. Overrides the scheme inferred from BROADCAST_URL. Default: inferred from the URL, else memory.",
+		example: "redis"
+	},
+	{
+		name: "REDIS_URL",
+		required: !1,
+		secret: !0,
+		description: "Fallback broker URL used when the resolved provider is redis and no BROADCAST_URL is set (also infers the redis provider when no provider/URL is given).",
+		example: "redis://localhost:6379"
+	},
+	{
+		name: "NATS_URL",
+		required: !1,
+		secret: !0,
+		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"
+	}
+], a = (a = {}) => {
+	let o = e({
+		...a.provider === void 0 ? {} : { provider: a.provider },
+		...a.url === void 0 ? {} : { url: a.url },
+		...a.connection === void 0 ? {} : { connection: a.connection }
+	}, process.env);
+	return {
+		...n({
+			name: a.name ? `@voltro/plugin-broadcast#${a.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: r,
+			declaredEnv: i,
+			onActivate: (e) => t.sync(() => {
+				o.crossReplica ? e.logger.info("broadcast active", {
+					provider: o.provider.name,
+					url: o.url
+				}) : e.logger.warn("broadcast: resolved to the in-process memory provider — NO cross-replica fan-out. Set BROADCAST_URL (redis:// or nats://) for a real bus.");
+			}),
+			onDeactivate: () => t.void
+		}),
+		broadcast: {
+			provider: o.provider,
+			url: o.url,
+			crossReplica: o.crossReplica,
+			namespace: a.namespace
+		}
+	};
+}, o = (e) => {
+	for (let t of e) if (s(t)) return t;
+	return null;
+}, s = (e) => typeof e.broadcast == "object" && e.broadcast !== null && typeof e.broadcast.provider == "object";
+//#endregion
+export { a as broadcastPlugin, o as getBroadcastPlugin };