@voltro/plugin-broadcast 0.83.1 → 0.85.0

package/THIRD-PARTY-NOTICES.md

@@ -5,66 +5,10 @@ property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/plugin-broadcast itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (21 packages).
+Generated from the resolved runtime dependency closure (19 packages).
 
 ---
 
-## @effect/experimental@0.61.1
-
-License: MIT
-
-```
-MIT License
-
-Copyright (c) 2023-present The Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
-## @effect/sql@0.52.1
-
-License: MIT
-
-```
-MIT License
-
-Copyright (c) 2023-present The Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
 ## @ioredis/commands@1.10.0
 
 License: MIT

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { ChangeEvent } from '@voltro/database';
 import { Effect } from 'effect';
 import { Schema } from 'effect';
 import { VoltroPlugin } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
 
 /**
  * Wire a store to a broadcast provider. Publishes local changes outward
@@ -40,6 +41,9 @@ export declare interface AttachBroadcastBusOptions {
      * embedder) should still say what it lost.
      */
     readonly onGap?: (gap: BroadcastGap) => void;
+    /** Bounded outbound buffering and broker/shutdown deadlines. Defaults:
+     * 1024 messages, 8 MiB, 5s publish, 1s shutdown. Overflow signals peer resync. */
+    readonly publishQueue?: BroadcastPublishQueueOptions;
 }
 
 /**
@@ -76,6 +80,9 @@ export declare type BroadcastChannelKind = 'changes' | 'events' | 'members' | 'p
  * into every OTHER replica's store emitter.
  */
 export declare interface BroadcastEnvelope {
+    /** Control delivery: refresh live queries rather than inject `event`.
+     * Sent after outbound loss, including when no later mutation occurs. */
+    readonly resync?: true;
     readonly origin: string;
     readonly event: ChangeEvent;
     /**
@@ -132,14 +139,12 @@ export declare interface BroadcastEnvelope {
 export declare class BroadcastError extends BroadcastError_base {
 }
 
-declare const BroadcastError_base: Schema.TaggedErrorClass<BroadcastError, "BroadcastError", {
-    readonly _tag: Schema.tag<"BroadcastError">;
-} & {
-    provider: typeof Schema.String;
-    message: typeof Schema.String;
-    transient: typeof Schema.Boolean;
-    cause: Schema.optional<typeof Schema.Unknown>;
-}>;
+declare const BroadcastError_base: Schema.Class<BroadcastError, Schema.TaggedStruct<"BroadcastError", {
+    readonly provider: Schema.String;
+    readonly message: Schema.String;
+    readonly transient: Schema.Boolean;
+    readonly cause: Schema.optional<Schema.Unknown>;
+}>, YieldableError>;
 
 /**
  * A proven — or presumed — hole in what this replica received.
@@ -274,6 +279,13 @@ export declare interface BroadcastProvider {
 /** Provider id understood by `resolveBroadcastProvider`. */
 export declare type BroadcastProviderName = 'redis' | 'nats' | 'memory';
 
+export declare interface BroadcastPublishQueueOptions {
+    readonly maxMessages?: number;
+    readonly maxBytes?: number;
+    readonly timeoutMs?: number;
+    readonly shutdownTimeoutMs?: number;
+}
+
 /** The minimal store surface the bus drives — a subset of `DataStore` so
  *  the bus stays decoupled from the concrete store classes. */
 export declare interface BroadcastStore {

package/dist/index.js

@@ -50,24 +50,28 @@ var i = "voltro", a = (e) => e.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-"
 	let t = h.get(e);
 	return t || (t = { handlers: /* @__PURE__ */ new Map() }, h.set(e, t)), t;
 }, _ = (e) => {
-	h.get(e)?.handlers.clear();
+	h.delete(e);
 }, v = (t = `default-${Math.random().toString(36).slice(2)}`) => {
-	let n = g(t);
+	let n = /* @__PURE__ */ new Set();
 	return {
 		name: "memory",
-		publish: (t, r) => e.sync(() => {
-			let e = n.handlers.get(t);
+		publish: (n, r) => e.sync(() => {
+			let e = h.get(t)?.handlers.get(n);
 			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);
+		subscribe: (r, i) => e.sync(() => {
+			let e = g(t), a = e.handlers.get(r) ?? /* @__PURE__ */ new Set(), o = (e) => i(e);
+			a.add(o), e.handlers.set(r, a);
+			let s = () => {
+				n.delete(s), a.delete(o), a.size === 0 && e.handlers.get(r) === a && e.handlers.delete(r), e.handlers.size === 0 && h.get(t) === e && h.delete(t);
 			};
+			return n.add(s), s;
 		}),
-		close: () => e.void
+		close: () => e.sync(() => {
+			for (let e of n) e();
+		})
 	};
 }, y = (t) => {
 	let n = null, r = m(), i = !0, a = () => n || (n = (async () => {
@@ -294,24 +298,87 @@ var i = "voltro", a = (e) => e.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-"
 }, 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 = {
+}, k = (e) => typeof e.broadcast == "object" && e.broadcast !== null && typeof e.broadcast.provider == "object", A = (t, n, r, i, a = {}, o = () => {}) => {
+	let s = a.maxMessages ?? 1024, c = a.maxBytes ?? 8388608, l = a.timeoutMs ?? 5e3, u = a.shutdownTimeoutMs ?? 1e3;
+	for (let [e, t] of Object.entries({
+		maxMessages: s,
+		maxBytes: c,
+		timeoutMs: l,
+		shutdownTimeoutMs: u
+	})) if (!Number.isSafeInteger(t) || t < 1) throw Error(`broadcast ${e} must be a positive safe integer`);
+	let d = [], f = 0, p = 0, m = !1, h = 0, g = !1, _ = !1, v, y, b = !1, x, S = /* @__PURE__ */ new Set(), C = () => {
+		for (let e of S) e();
+		S.clear();
+	}, w = (e) => {
+		m || i(e), m = !0;
+	}, T = () => {
+		if (g || b || v !== void 0) return;
+		let i = d[f];
+		if (!i && !m) {
+			C();
+			return;
+		}
+		let a = h, s = i?.payload ?? r(a);
+		i && (d[f] = void 0, f++, f * 2 >= d.length && (d = d.slice(f), f = 0)), x = new AbortController(), b = !0;
+		let c = setTimeout(() => {
+			w("publish timed out; peers need a resync");
+		}, l);
+		y = e.runPromise(t.publish(n, s), { signal: x.signal }).then(() => {
+			g || o(), !i && h === a && (m = !1);
+		}, () => {
+			g || (w("publish failed — cross-replica fan-out degraded, local reactivity unaffected; peers need a resync"), v = setTimeout(() => {
+				v = void 0, T();
+			}, 500));
+		}).finally(() => {
+			clearTimeout(c), i && (p -= i.bytes), y = void 0, b = !1, x = void 0, g ? C() : T();
+		});
+	};
+	return {
+		enqueue: (e, t) => {
+			if (_ || g) return;
+			if (h = t, m || d.length - f + +!!b >= s) {
+				w("publish queue full; peers need a resync"), T();
+				return;
+			}
+			let n = e(), r = Buffer.byteLength(n, "utf8");
+			if (p + r > c) {
+				w("publish byte budget exceeded; peers need a resync"), T();
+				return;
+			}
+			p += r, d.push({
+				payload: n,
+				bytes: r
+			}), T();
+		},
+		close: async () => {
+			_ = !0, v !== void 0 && (clearTimeout(v), v = void 0), T();
+			let e;
+			(y || d.length > f || m) && await new Promise((t) => {
+				let n = () => {
+					S.delete(n), t();
+				};
+				S.add(n), e = setTimeout(n, u);
+			}), e !== void 0 && clearTimeout(e), g = !0, (y || d.length > f || m) && i("shutdown deadline reached; unsent changes require peer resync"), d = [], f = 0, v !== void 0 && clearTimeout(v), x?.abort(), y && await Promise.race([y, new Promise((e) => setImmediate(e))]), p = 0, C();
+		}
+	};
+}, j = ({ origin: e, ...t }) => t, M = (e) => Math.min(500 * 2 ** Math.min(Math.max(e, 1) - 1, 5), 1e4), N = {
 	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 = {
+}, P = async (n) => {
+	let { store: r, provider: i, replicaId: a } = n, o = n.logger ?? N, s = n.channel ?? d, c = !1, l, u = 0, f = /* @__PURE__ */ new Map(), p = `${Date.now().toString(36)}.${Math.random().toString(36).slice(2, 10)}`, m = t.gauge("voltro_broadcast_connected").pipe(t.withAttributes({ provider: i.name })), h = t.counter("voltro_broadcast_gaps_total").pipe(t.withAttributes({ provider: i.name })), g = t.counter("voltro_broadcast_missed_total").pipe(t.withAttributes({ provider: i.name })), _ = t.counter("voltro_broadcast_reconnects_total").pipe(t.withAttributes({ provider: i.name })), v = {
 		connected: !1,
 		lastReceivedAt: null,
 		lastPublishedAt: null,
 		reconnects: 0,
 		gaps: 0,
 		missed: 0
-	}, b = (n) => {
-		y.connected = n, e.runSync(t.set(h, +!!n));
+	}, y = (n) => {
+		v.connected = n, e.runSync(t.update(m, +!!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`, {
+	y(!1);
+	let b = (r) => {
+		v.gaps += 1, e.runSync(t.update(h, 1)), r.missed !== void 0 && r.missed > 0 && (v.missed += r.missed, e.runSync(t.update(g, 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 }
 		});
@@ -320,8 +387,9 @@ var i = "voltro", a = (e) => e.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-"
 		} catch (e) {
 			o.warn("broadcast: gap recovery threw", { err: e });
 		}
-	}, S = (e) => {
-		y.lastReceivedAt = Date.now();
+	}, x = (e) => {
+		if (w) return;
+		v.lastReceivedAt = Date.now();
 		let t;
 		try {
 			t = JSON.parse(e);
@@ -330,35 +398,66 @@ var i = "voltro", a = (e) => e.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-"
 			return;
 		}
 		if (t.origin === a || !t.event || typeof t.event != "object") return;
+		let n = !1;
 		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, {
+			let e = t.epoch ?? "", r = f.get(t.origin);
+			if (r === void 0) f.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, {
+			});
+			else if (r.epoch !== e) f.set(t.origin, {
 				epoch: e,
 				n: t.n
 			});
+			else {
+				let i = t.n - r.n - (t.resync === !0 ? 0 : 1);
+				i > 0 && (n = !0, b({
+					reason: `missed ${i} change(s) from ${t.origin}`,
+					origin: t.origin,
+					missed: i
+				})), t.n > r.n && f.set(t.origin, {
+					epoch: e,
+					n: t.n
+				});
+			}
 		}
-		let n = A(t.event);
-		c = !0, l = n;
+		if (t.resync === !0) {
+			n || b({
+				reason: `the ${t.origin} publisher lost changes and requested a resync`,
+				origin: t.origin
+			});
+			return;
+		}
+		let i = j(t.event);
+		c = !0, l = i;
 		try {
-			r.injectExternalChange(n);
+			r.injectExternalChange(i);
 		} catch (e) {
 			o.warn("broadcast: inject failed", { err: e });
 		} finally {
 			c = !1, l = void 0;
 		}
-	}, C, w = !1, T = 0, E = async () => {
+	}, S = A(i, s, (e) => JSON.stringify({
+		origin: a,
+		epoch: p,
+		n: e,
+		resync: !0,
+		event: {
+			table: "",
+			op: "update",
+			old: null,
+			new: null
+		}
+	}), (e) => {
+		o.warn(`broadcast: ${e}`, {
+			provider: i.name,
+			channel: s
+		});
+	}, n.publishQueue, () => {
+		v.lastPublishedAt = Date.now();
+	}), C, w = !1, T = 0, E = async () => {
 		try {
-			return C = await e.runPromise(i.subscribe(s, S)), b(!0), !0;
+			return C = await e.runPromise(i.subscribe(s, x)), w ? (C(), C = void 0, !1) : (y(!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,
@@ -370,72 +469,78 @@ var i = "voltro", a = (e) => e.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-"
 	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 new Promise((e) => setTimeout(e, M(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` });
+				}), b({ 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", {
+		if (!w) {
+			if (n.kind === "disconnected") {
+				y(!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;
+			}
+			y(!0), v.reconnects += 1, e.runSync(t.update(_, 1)), o.warn("broadcast transport reconnected", {
 				provider: i.name,
-				...n.detail === void 0 ? {} : { detail: n.detail }
-			});
-			return;
+				channel: s,
+				replicaId: a,
+				reconnects: v.reconnects,
+				lastReceivedAt: v.lastReceivedAt
+			}), b({ reason: `the ${i.name} transport reconnected after an outage` });
 		}
-		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 = {
+	}), O = r.onChange((e) => {
+		if (e.origin === "injected" || c && e === l) return;
+		u += 1;
+		let t = {
 			origin: a,
-			event: t,
-			n: f,
-			epoch: m
+			event: e,
+			n: u,
+			epoch: p
 		};
-		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
-			}));
-		}))));
+		S.enqueue(() => JSON.stringify(t), u);
 	});
-	return o.info("broadcast bus attached", {
+	o.info("broadcast bus attached", {
 		provider: i.name,
 		channel: s,
 		replicaId: a
-	}), {
+	});
+	let k;
+	return {
 		health: () => ({
 			provider: i.name,
 			channel: s,
 			replicaId: a,
-			...y
+			...v
 		}),
-		close: async () => {
-			if (!w) {
-				w = !0, O(), D?.();
-				try {
-					C?.();
-				} catch {}
-				await e.runPromise(i.close());
+		close: () => (k ??= (async () => {
+			w = !0, O(), D?.(), y(!1);
+			try {
+				C?.();
+			} catch {}
+			await S.close();
+			let t = new AbortController(), r, a = e.runPromise(i.close(), { signal: t.signal }).catch((e) => {
+				o.warn("broadcast: provider close failed", { error: e });
+			});
+			try {
+				await Promise.race([a, new Promise((e) => {
+					r = setTimeout(() => {
+						o.warn("broadcast: provider shutdown timed out"), t.abort(), e();
+					}, n.publishQueue?.shutdownTimeoutMs ?? 1e3);
+				})]);
+			} finally {
+				r !== void 0 && clearTimeout(r);
 			}
-		}
+		})(), k)
 	};
 };
 //#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 };
+export { d as BROADCAST_CHANNEL, u as BroadcastError, i as DEFAULT_BROADCAST_NAMESPACE, P 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, M as subscribeRetryDelayMs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-broadcast",
-  "version": "0.83.1",
+  "version": "0.85.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",
@@ -33,15 +33,15 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.83.1",
-    "@voltro/protocol": "0.83.1"
+    "@voltro/database": "0.85.0",
+    "@voltro/protocol": "0.85.0"
   },
   "optionalDependencies": {
     "@nats-io/transport-node": "^3.4.0",
     "ioredis": "^5.11.1"
   },
   "peerDependencies": {
-    "effect": "^3.22.2"
+    "effect": "4.0.1"
   },
   "publishConfig": {
     "access": "public"