@voltro/plugin-broadcast 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+import { ChangeEvent } from '@voltro/database';
+import { Effect } from 'effect';
+import { Schema } from 'effect';
+import { VoltroPlugin } from '@voltro/protocol';
+
+/**
+ * Wire a store to a broadcast provider. Publishes local changes outward
+ * and injects remote changes inward (skipping own-origin). Returns a
+ * handle whose `close()` tears everything down.
+ *
+ * Publish failures are logged + dropped — they MUST NOT propagate onto
+ * the mutation path (the write already committed + inline-emitted
+ * locally; only cross-replica fan-out is affected).
+ */
+export declare const attachBroadcastBus: (options: AttachBroadcastBusOptions) => Promise<BroadcastBusHandle>;
+
+export declare interface AttachBroadcastBusOptions {
+    readonly store: BroadcastStore;
+    readonly provider: BroadcastProvider;
+    /** This replica's id — stamped as `origin` on every publish and matched
+     *  against incoming `origin` to skip own writes. */
+    readonly replicaId: string;
+    readonly logger?: BroadcastBusLogger;
+    /** Channel override (tests). Default `voltro:changes`. */
+    readonly channel?: string;
+}
+
+/** The channel the bus fans ChangeEvents out on. */
+export declare const BROADCAST_CHANNEL = "voltro:changes";
+
+export declare interface BroadcastBusHandle {
+    /** Detach the onChange listener, the bus subscription, and close the
+     *  provider. Idempotent. */
+    readonly close: () => Promise<void>;
+}
+
+export declare interface BroadcastBusLogger {
+    info: (message: string, fields?: Record<string, unknown>) => void;
+    warn: (message: string, fields?: Record<string, unknown>) => void;
+    debug: (message: string, fields?: Record<string, unknown>) => void;
+}
+
+/**
+ * What rides the wire on the `voltro:changes` channel. `origin` is the
+ * publishing replica's id; subscribers skip their OWN origin (the writer
+ * already inline-emitted locally) so there is no double-emit and no need
+ * for a dedup table. `event` is the app-mutation ChangeEvent to inject
+ * into every OTHER replica's store emitter.
+ */
+export declare interface BroadcastEnvelope {
+    readonly origin: string;
+    readonly event: ChangeEvent;
+}
+
+/**
+ * Transport failure. `transient` flags broker hiccups (connection reset,
+ * timeout) worth a retry vs configuration faults (bad URL, missing dep)
+ * that won't fix themselves. The wiring never rethrows it onto the
+ * mutation path — a publish failure logs + drops; local reactivity is
+ * unaffected.
+ *
+ * A `Schema.TaggedError` (the framework house style, same shape as
+ * `@voltro/plugin-storage`'s `StorageError`): it rides the Effect error
+ * channel with a stable `_tag`, is `instanceof`-checkable, and — should a
+ * future path ever surface it across the rpc wire — is Schema-encodable.
+ */
+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>;
+}>;
+
+/**
+ * A broadcast plugin instance also exposes the resolved provider so the
+ * CLI's serve pipeline can attach the bus to the live DataStore. The
+ * extra fields ride on the returned `VoltroPlugin` and are read by the
+ * framework via `getBroadcastProvider`.
+ */
+export declare interface BroadcastPlugin extends VoltroPlugin {
+    readonly broadcast: {
+        readonly provider: BroadcastProvider;
+        readonly url: string | null;
+        readonly crossReplica: boolean;
+    };
+}
+
+export declare const broadcastPlugin: (options?: BroadcastPluginOptions) => BroadcastPlugin;
+
+export declare interface BroadcastPluginOptions {
+    /** Provider name (`'redis' | 'nats' | 'memory'`) or a pre-built
+     *  `BroadcastProvider`. Default: inferred from `BROADCAST_URL` /
+     *  `BROADCAST_PROVIDER` / `REDIS_URL` env, else `'memory'`. */
+    readonly provider?: BroadcastProviderName | BroadcastProvider;
+    /** Broker URL — a broker-agnostic override (redis:// or nats://). Takes
+     *  precedence over the named-connection env. Default `BROADCAST_URL` env. */
+    readonly url?: string;
+    /** Named connection for the redis provider — resolves the broker URL via the
+     *  shared convention `<NAME>_REDIS_URL` → `REDIS_URL` (like cache / kv /
+     *  ratelimit). Default `'broadcast'` (→ `BROADCAST_REDIS_URL`, then
+     *  `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;
+    /** Disambiguates multiple instances of this plugin in one app. */
+    readonly name?: string;
+}
+
+/**
+ * Dumb pub/sub transport. One channel, string payloads, no framing.
+ *
+ *   - `publish` — fire-and-forget a payload onto a channel. Transient
+ *     broker hiccups should fail the Effect (the caller logs + drops;
+ *     cross-replica reactivity degrades, local reactivity is untouched).
+ *   - `subscribe` — register a handler for every payload on a channel.
+ *     Returns an unsubscribe Effect. The handler is invoked once per
+ *     received message; it must not throw (errors are swallowed by the
+ *     wiring's decode guard).
+ *   - `close` — tear down connections / the pub + sub sockets.
+ *
+ * Implementations are constructed eagerly but connect lazily where the
+ * backend allows, so a process that wires the plugin but never publishes
+ * doesn't pay a connect cost on an unrelated path.
+ */
+export declare interface BroadcastProvider {
+    /** Backend name — `'redis' | 'nats' | 'memory'`. Surfaced in the boot banner. */
+    readonly name: string;
+    readonly publish: (channel: string, payload: string) => Effect.Effect<void, BroadcastError>;
+    readonly subscribe: (channel: string, handler: (payload: string) => void) => Effect.Effect<() => void, BroadcastError>;
+    readonly close: () => Effect.Effect<void>;
+}
+
+/** Provider id understood by `resolveBroadcastProvider`. */
+export declare type BroadcastProviderName = 'redis' | 'nats' | 'memory';
+
+/** 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 {
+    onChange: (listener: (event: ChangeEvent) => void) => () => void;
+    injectExternalChange: (event: ChangeEvent) => void;
+}
+
+/**
+ * Pull the resolved broadcast carrier off a plugin list (the framework's
+ * serve pipeline calls this after building the store). Returns the FIRST
+ * broadcast plugin found, or `null`.
+ */
+export declare const getBroadcastPlugin: (plugins: ReadonlyArray<VoltroPlugin>) => BroadcastPlugin | null;
+
+/**
+ * In-process pub/sub over a named bus. Delivery is synchronous within the
+ * process. Two providers sharing a `bus` name see each other's publishes —
+ * the seam the cross-instance test exercises without a real broker.
+ */
+export declare const memoryProvider: (bus?: string) => BroadcastProvider;
+
+declare interface NatsLike {
+    publish: (subject: string, data: Uint8Array) => void;
+    subscribe: (subject: string) => NatsSubscription;
+    drain: () => Promise<void>;
+}
+
+export declare const natsProvider: (options: NatsProviderOptions) => BroadcastProvider;
+
+export declare interface NatsProviderOptions {
+    /** `nats://host:port` (comma-separated for a cluster). Required. */
+    readonly url: string;
+    /** Bring your own connected NATS connection (e.g. for shared creds). */
+    readonly connection?: NatsLike;
+}
+
+declare interface NatsSubscription extends AsyncIterable<{
+    data: Uint8Array;
+}> {
+    unsubscribe: () => void;
+}
+
+/** The slice of ioredis the provider touches — keeps the optional dep out
+ *  of the type surface. */
+declare interface RedisLike {
+    publish: (channel: string, message: string) => Promise<number>;
+    subscribe: (channel: string) => Promise<unknown>;
+    unsubscribe: (channel: string) => Promise<unknown>;
+    on: (event: 'message', listener: (channel: string, message: string) => void) => void;
+    off: (event: 'message', listener: (channel: string, message: string) => void) => void;
+    duplicate: () => RedisLike;
+    quit: () => Promise<unknown>;
+}
+
+export declare const redisProvider: (options: RedisProviderOptions) => BroadcastProvider;
+
+export declare interface RedisProviderOptions {
+    /** `redis://[:pass@]host:port[/db]`. Required. */
+    readonly url: string;
+    /** Bring your own ioredis client (publisher). A `subscriber` is
+     *  `client.duplicate()`d internally — a RESP connection in subscribe
+     *  mode can't issue normal commands. */
+    readonly client?: RedisLike;
+}
+
+/* Excluded from this release type: resetMemoryBus */
+
+export declare interface ResolveBroadcastOptions {
+    /** Explicit provider name or a pre-built `BroadcastProvider`. */
+    readonly provider?: BroadcastProviderName | BroadcastProvider;
+    /** Broker URL — a broker-agnostic override (redis:// or nats://). Takes
+     *  precedence over the named-connection env. Default `BROADCAST_URL` env. */
+    readonly url?: string;
+    /** Named connection for the redis provider. The broker URL resolves via the
+     *  shared convention `<NAME>_REDIS_URL` → `REDIS_URL` (like cache / kv /
+     *  ratelimit), so a deployment points broadcast at the same server or its own
+     *  purely by env. Default `'broadcast'` (→ `BROADCAST_REDIS_URL`). */
+    readonly connection?: string;
+}
+
+/**
+ * Resolve the bus backend. Order: an object provider is used verbatim; a
+ * named provider builds from `url`/env; absent → `BROADCAST_PROVIDER` env,
+ * else inferred from a `redis://` / `nats://` URL, else `memory`.
+ *
+ * Returns the provider plus the URL it resolved (for the boot banner) and
+ * whether the choice is a real cross-replica bus or the single-process
+ * memory fallback.
+ */
+export declare const resolveBroadcastProvider: (options: ResolveBroadcastOptions, env: NodeJS.ProcessEnv) => {
+    provider: BroadcastProvider;
+    url: string | null;
+    crossReplica: boolean;
+};
+
+export { }

package/dist/index.js

@@ -0,0 +1,280 @@
+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", {
+	provider: t.String,
+	message: t.String,
+	transient: t.Boolean,
+	cause: t.optional(t.Unknown)
+}) {}, i = "voltro:changes", a = (e, t, n) => new r({
+	provider: e,
+	message: t,
+	transient: !0,
+	...n === void 0 ? {} : { cause: n }
+}), o = (e, t, n) => new r({
+	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);
+	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
+	};
+}, d = (t) => {
+	let n = null, r = () => n || (n = (async () => {
+		let e;
+		if (t.client) e = t.client;
+		else {
+			let n;
+			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);
+			}
+			e = new n(t.url);
+		}
+		let n = e.duplicate();
+		return {
+			pub: e,
+			sub: n
+		};
+	})(), n);
+	return {
+		name: "redis",
+		publish: (t, n) => e.tryPromise({
+			try: async () => {
+				let { pub: e } = await r();
+				await e.publish(t, n);
+			},
+			catch: (e) => a("redis", `publish failed: ${String(e?.message ?? e)}`, e)
+		}),
+		subscribe: (t, n) => e.tryPromise({
+			try: async () => {
+				let { sub: e } = await r(), i = (e, r) => {
+					e === t && n(r);
+				};
+				return e.on("message", i), await e.subscribe(t), () => {
+					e.off("message", i), e.unsubscribe(t);
+				};
+			},
+			catch: (e) => a("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 {}
+		})
+	};
+}, f = new TextEncoder(), p = new TextDecoder(), m = (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);
+	}), 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));
+			},
+			catch: (e) => a("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));
+				})(), () => {
+					e.unsubscribe();
+				};
+			},
+			catch: (e) => a("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 {}
+		})
+	};
+}, h = (e, t) => t[`${e.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_REDIS_URL`], g = (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 = h(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 }),
+				url: e,
+				crossReplica: !0
+			} : {
+				provider: u(),
+				url: null,
+				crossReplica: !1
+			};
+		}
+		case "nats": {
+			let e = n ?? t.NATS_URL;
+			return e ? {
+				provider: m({ url: e }),
+				url: e,
+				crossReplica: !0
+			} : {
+				provider: u(),
+				url: null,
+				crossReplica: !1
+			};
+		}
+		default: return {
+			provider: u(),
+			url: null,
+			crossReplica: !1
+		};
+	}
+}, _ = ["network:outbound:*"], v = [
+	{
+		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"
+	}
+], y = (t = {}) => {
+	let r = g({
+		...t.provider === void 0 ? {} : { provider: t.provider },
+		...t.url === void 0 ? {} : { url: t.url },
+		...t.connection === void 0 ? {} : { connection: t.connection }
+	}, process.env);
+	return {
+		...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,
+			onActivate: (t) => e.sync(() => {
+				r.crossReplica ? t.logger.info("broadcast active", {
+					provider: r.provider.name,
+					url: r.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: r.provider,
+			url: r.url,
+			crossReplica: r.crossReplica
+		}
+	};
+}, b = (e) => {
+	for (let t of e) if (x(t)) return t;
+	return null;
+}, x = (e) => typeof e.broadcast == "object" && e.broadcast !== null && typeof e.broadcast.provider == "object", S = {
+	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;
+		try {
+			t = JSON.parse(e);
+		} catch {
+			a.warn("broadcast: bad payload (not JSON)", { channel: o });
+			return;
+		}
+		if (t.origin !== i && !(!t.event || typeof t.event != "object")) {
+			s = !0;
+			try {
+				n.injectExternalChange(t.event);
+			} catch (e) {
+				a.warn("broadcast: inject failed", { err: e });
+			} finally {
+				s = !1;
+			}
+		}
+	})), u = n.onChange((t) => {
+		if (s) return;
+		let n = {
+			origin: i,
+			event: t
+		};
+		e.runPromise(r.publish(o, JSON.stringify(n)).pipe(e.tap(() => e.sync(() => {
+			c = !1;
+		})), e.catchAll((t) => e.sync(() => {
+			c || (c = !0, a.warn("broadcast: publish failed — cross-replica fan-out degraded, local reactivity unaffected", {
+				provider: r.name,
+				transient: t.transient,
+				message: t.message
+			}));
+		}))));
+	});
+	a.info("broadcast bus attached", {
+		provider: r.name,
+		channel: o,
+		replicaId: i
+	});
+	let d = !1;
+	return { close: async () => {
+		if (!d) {
+			d = !0, u();
+			try {
+				l();
+			} 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 };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@voltro/plugin-broadcast",
+  "version": "0.1.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",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@voltro/database": "0.1.0",
+    "@voltro/protocol": "0.1.0"
+  },
+  "optionalDependencies": {
+    "@nats-io/transport-node": "^3.4.0",
+    "ioredis": "^5.11.1"
+  },
+  "peerDependencies": {
+    "effect": "^3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}