@voltro/plugin-broadcast 0.84.0 → 0.86.0

package/THIRD-PARTY-NOTICES.md

@@ -1,70 +1,14 @@
 # Third-Party Notices — @voltro/plugin-broadcast
 
-This package depends on the open-source software listed below. Each is the
+This package uses the open-source software listed below. Each is the
 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 (18 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
@@ -1236,34 +1180,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## layerr@3.0.0
-
-License: MIT
-
-```
-MIT License
-
-Copyright (c) 2020 Perry Mitchell
-
-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.
-```
-
 ## ms@2.1.3
 
 License: MIT
@@ -1616,14 +1532,14 @@ Apache License
    limitations under the License.
 ```
 
-## ulidx@2.4.1
+## ulid@3.0.2
 
 License: MIT
 
 ```
-MIT License
+The MIT License (MIT)
 
-Copyright (c) 2021 Perry Mitchell
+Copyright (c) 2017 Alizain Feerasta
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/bus.js

@@ -0,0 +1,181 @@
+import { BROADCAST_CHANNEL as e } from "./types.js";
+import { createPublishQueue as t } from "./publishQueue.js";
+import { Effect as n, Metric as r } from "effect";
+//#region src/bus.ts
+var i = ({ origin: e, ...t }) => t, a = (e) => Math.min(500 * 2 ** Math.min(Math.max(e, 1) - 1, 5), 1e4), o = {
+	info: () => {},
+	warn: () => {},
+	debug: () => {}
+}, s = async (s) => {
+	let { store: c, provider: l, replicaId: u } = s, d = s.logger ?? o, f = s.channel ?? e, p = !1, m, h = 0, g = /* @__PURE__ */ new Map(), _ = `${Date.now().toString(36)}.${Math.random().toString(36).slice(2, 10)}`, v = r.gauge("voltro_broadcast_connected").pipe(r.withAttributes({ provider: l.name })), y = r.counter("voltro_broadcast_gaps_total").pipe(r.withAttributes({ provider: l.name })), b = r.counter("voltro_broadcast_missed_total").pipe(r.withAttributes({ provider: l.name })), x = r.counter("voltro_broadcast_reconnects_total").pipe(r.withAttributes({ provider: l.name })), S = {
+		connected: !1,
+		lastReceivedAt: null,
+		lastPublishedAt: null,
+		reconnects: 0,
+		gaps: 0,
+		missed: 0
+	}, C = (e) => {
+		S.connected = e, n.runSync(r.update(v, +!!e));
+	};
+	C(!1);
+	let w = (e) => {
+		S.gaps += 1, n.runSync(r.update(y, 1)), e.missed !== void 0 && e.missed > 0 && (S.missed += e.missed, n.runSync(r.update(b, e.missed))), d.warn(`broadcast: ${e.reason} — refreshing live queries, which is safe because a query is idempotent`, {
+			...e.origin === void 0 ? {} : { origin: e.origin },
+			...e.missed === void 0 ? {} : { missed: e.missed }
+		});
+		try {
+			s.onGap?.(e);
+		} catch (e) {
+			d.warn("broadcast: gap recovery threw", { err: e });
+		}
+	}, T = (e) => {
+		if (O) return;
+		S.lastReceivedAt = Date.now();
+		let t;
+		try {
+			t = JSON.parse(e);
+		} catch {
+			d.warn("broadcast: bad payload (not JSON)", { channel: f });
+			return;
+		}
+		if (t.origin === u || !t.event || typeof t.event != "object") return;
+		let n = !1;
+		if (typeof t.n == "number" && Number.isFinite(t.n)) {
+			let e = t.epoch ?? "", r = g.get(t.origin);
+			if (r === void 0) g.set(t.origin, {
+				epoch: e,
+				n: t.n
+			});
+			else if (r.epoch !== e) g.set(t.origin, {
+				epoch: e,
+				n: t.n
+			});
+			else {
+				let i = t.n - r.n - (t.resync === !0 ? 0 : 1);
+				i > 0 && (n = !0, w({
+					reason: `missed ${i} change(s) from ${t.origin}`,
+					origin: t.origin,
+					missed: i
+				})), t.n > r.n && g.set(t.origin, {
+					epoch: e,
+					n: t.n
+				});
+			}
+		}
+		if (t.resync === !0) {
+			n || w({
+				reason: `the ${t.origin} publisher lost changes and requested a resync`,
+				origin: t.origin
+			});
+			return;
+		}
+		let r = i(t.event);
+		p = !0, m = r;
+		try {
+			c.injectExternalChange(r);
+		} catch (e) {
+			d.warn("broadcast: inject failed", { err: e });
+		} finally {
+			p = !1, m = void 0;
+		}
+	}, E = t(l, f, (e) => JSON.stringify({
+		origin: u,
+		epoch: _,
+		n: e,
+		resync: !0,
+		event: {
+			table: "",
+			op: "update",
+			old: null,
+			new: null
+		}
+	}), (e) => {
+		d.warn(`broadcast: ${e}`, {
+			provider: l.name,
+			channel: f
+		});
+	}, s.publishQueue, () => {
+		S.lastPublishedAt = Date.now();
+	}), D, O = !1, k = 0, A = async () => {
+		try {
+			return D = await n.runPromise(l.subscribe(f, T)), O ? (D(), D = void 0, !1) : (C(!0), !0);
+		} catch (e) {
+			return k += 1, k === 1 && d.warn("broadcast: could not subscribe — this replica will not receive other replicas' changes yet. Retrying in the background; local reactivity is unaffected.", {
+				provider: l.name,
+				channel: f,
+				err: e
+			}), !1;
+		}
+	};
+	await A() || (async () => {
+		let e = Date.now();
+		for (; !O && D === void 0;) {
+			if (await new Promise((e) => setTimeout(e, a(k))), O) return;
+			if (await A()) {
+				d.info("broadcast: subscribed", {
+					provider: l.name,
+					channel: f,
+					attempts: k
+				}), w({ reason: `this replica was not subscribed to '${f}' for ${Math.round((Date.now() - e) / 1e3)}s` });
+				return;
+			}
+		}
+	})();
+	let j = l.onTransportEvent?.((e) => {
+		O || (e.kind === "disconnected" ? (C(!1), d.warn("broadcast: transport disconnected — cross-replica fan-out is down until it re-dials", {
+			provider: l.name,
+			...e.detail === void 0 ? {} : { detail: e.detail }
+		})) : (C(!0), S.reconnects += 1, n.runSync(r.update(x, 1)), d.warn("broadcast transport reconnected", {
+			provider: l.name,
+			channel: f,
+			replicaId: u,
+			reconnects: S.reconnects,
+			lastReceivedAt: S.lastReceivedAt
+		}), w({ reason: `the ${l.name} transport reconnected after an outage` })));
+	}), M = c.onChange((e) => {
+		if (e.origin === "injected" || p && e === m) return;
+		h += 1;
+		let t = {
+			origin: u,
+			event: e,
+			n: h,
+			epoch: _
+		};
+		E.enqueue(() => JSON.stringify(t), h);
+	});
+	d.info("broadcast bus attached", {
+		provider: l.name,
+		channel: f,
+		replicaId: u
+	});
+	let N;
+	return {
+		health: () => ({
+			provider: l.name,
+			channel: f,
+			replicaId: u,
+			...S
+		}),
+		close: () => (N ??= (async () => {
+			O = !0, M(), j?.(), C(!1);
+			try {
+				D?.();
+			} catch {}
+			await E.close();
+			let e = new AbortController(), t, r = n.runPromise(l.close(), { signal: e.signal }).catch((e) => {
+				d.warn("broadcast: provider close failed", { error: e });
+			});
+			try {
+				await Promise.race([r, new Promise((n) => {
+					t = setTimeout(() => {
+						d.warn("broadcast: provider shutdown timed out"), e.abort(), n();
+					}, s.publishQueue?.shutdownTimeoutMs ?? 1e3);
+				})]);
+			} finally {
+				t !== void 0 && clearTimeout(t);
+			}
+		})(), N)
+	};
+};
+//#endregion
+export { s as attachBroadcastBus, a as subscribeRetryDelayMs, i as withoutWireOrigin };

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 {