@voltro/kv 0.86.0 → 0.88.0

package/dist/connectionMetrics.js

@@ -0,0 +1,78 @@
+import { Effect as e, Metric as t } from "effect";
+// src/connectionMetrics.ts
+var n = /* @__PURE__ */ new Map(), r = t.gauge("voltro_connection_up", { description: "Whether every current pool for this reference has observed readiness and admits commands; not a persistence or capacity measurement." }), i = t.gauge("voltro_connection_pools", { description: "Owned physical generations, including draining generations." }), a = t.gauge("voltro_connection_active_commands", { description: "Borrowed generation leases, including complete streams and transactions." }), o = t.counter("voltro_connection_commands_total", { description: "Admitted commands and scoped streams; includes read-only probes." }), s = t.counter("voltro_connection_errors_total", { description: "Failed registry operations; includes rejected circuit admission and connection construction." }), c = t.gauge("voltro_connection_latency_ms", { description: "Duration of the most recently completed command or scoped stream in milliseconds." }), l = t.histogram("voltro_connection_duration_seconds", {
+	boundaries: t.exponentialBoundaries({
+		start: .001,
+		factor: 2,
+		count: 16
+	}),
+	description: "Complete command and scoped stream duration in seconds."
+}), u = t.counter("voltro_connection_rotations_total", { description: "Completed whole-registry rotations by outcome, including rolled-back attempts." }), d = t.histogram("voltro_connection_rotation_duration_seconds", {
+	boundaries: t.exponentialBoundaries({
+		start: .001,
+		factor: 2,
+		count: 16
+	}),
+	description: "Whole-registry rotation duration in seconds."
+}), f = (f) => {
+	let p = /* @__PURE__ */ new WeakMap(), m = (e, n) => t.withAttributes(t.withAttributes(e, { namespace: f }), { connection: n }), h = (o, s) => {
+		let c = [...n.get(o)?.values() ?? []], l = c.filter((e) => e.current);
+		e.runSync(e.all([
+			t.update(m(r, s), l.length > 0 && l.every((e) => e.available) ? 1 : 0),
+			t.update(m(i, s), c.length),
+			t.update(m(a, s), c.reduce((e, t) => e + t.active, 0))
+		], { discard: !0 }));
+	}, g = (e, t) => {
+		let n = p.get(e);
+		n !== void 0 && (t(n.measurement), h(n.key, n.reference));
+	};
+	return {
+		register: (r, i) => {
+			let a = JSON.stringify([f, i]), c = {}, l = {
+				current: !1,
+				available: !1,
+				active: 0
+			}, u = n.get(a) ?? /* @__PURE__ */ new Map();
+			u.set(c, l), n.set(a, u), p.set(r, {
+				key: a,
+				reference: i,
+				token: c,
+				measurement: l
+			}), e.runSync(e.andThen(t.update(m(o, i), 0), t.update(m(s, i), 0))), h(a, i);
+		},
+		available: (e, t) => g(e, (e) => {
+			e.available = t;
+		}),
+		activate: (e) => g(e, (e) => {
+			e.current = !0;
+		}),
+		retire: (e) => g(e, (e) => {
+			e.current = !1;
+		}),
+		acquire: (e) => g(e, (e) => {
+			e.active++;
+		}),
+		release: (e) => g(e, (e) => {
+			e.active--;
+		}),
+		close: (e) => {
+			let t = p.get(e);
+			if (t === void 0) return;
+			let r = n.get(t.key);
+			r?.delete(t.token), r?.size === 0 && n.delete(t.key), p.delete(e), h(t.key, t.reference);
+		},
+		command: (n) => {
+			e.runSync(t.update(m(o, n), 1));
+		},
+		error: (n) => {
+			e.runSync(t.update(m(s, n), 1));
+		},
+		completed: (n, r) => {
+			e.runSync(e.andThen(t.update(m(c, n), r), t.update(m(l, n), r / 1e3)));
+		},
+		rotated: (n, r) => {
+			e.runSync(e.andThen(t.update(t.withAttributes(t.withAttributes(u, { namespace: f }), { outcome: n }), 1), t.update(t.withAttributes(d, { namespace: f }), r / 1e3)));
+		}
+	};
+};
+export { f as makeConnectionMetrics };

package/dist/connectionNamespace.js

@@ -0,0 +1,18 @@
+// src/connectionNamespace.ts
+var e = (e) => encodeURIComponent(e).replace(/[!'()*]/g, (e) => `%${e.charCodeAt(0).toString(16).toUpperCase()}`), t = (t) => {
+	if (typeof t.appName != "string" || !t.appName.trim() || typeof t.environment != "string" || !t.environment.trim()) throw Error("Connection namespace requires a nonempty app name and environment");
+	return `voltro:${e(t.appName)}:${e(t.environment)}:`;
+}, n = (e, n) => {
+	let r = t(n), i = e.keyPrefix ?? r;
+	if (typeof i != "string") throw Error("Connection keyPrefix must be a string");
+	if (e.allowSharedNamespace !== void 0 && typeof e.allowSharedNamespace != "boolean") throw Error("Connection allowSharedNamespace must be a boolean");
+	if (n.environment === "production") {
+		if (!i.trim()) throw Error("Production connection keyPrefix must be nonempty");
+		if (i !== r && e.allowSharedNamespace !== !0) throw Error("A custom production connection keyPrefix requires allowSharedNamespace: true");
+	}
+	return {
+		...e,
+		keyPrefix: i
+	};
+};
+export { n as applyConnectionNamespace, t as connectionNamespace };

package/dist/connectionNats.js

@@ -0,0 +1,148 @@
+import { KvError as e } from "./errors.js";
+import { missingDriver as t } from "./driverModule.js";
+import { assertNatsSubject as n } from "./connectionNatsSubjects.js";
+import { Effect as r } from "effect";
+// src/connectionNats.ts
+var i = new TextEncoder(), a = new TextDecoder(), o = 5e3, s = 1e3, c = async (e, t) => {
+	let n;
+	try {
+		return await Promise.race([e, new Promise((e, r) => {
+			n = setTimeout(() => {
+				r(/* @__PURE__ */ Error("NATS transport deadline elapsed"));
+			}, t);
+		})]);
+	} finally {
+		n !== void 0 && clearTimeout(n);
+	}
+}, l = (e) => {
+	let t = /* @__PURE__ */ new Set(), r = /* @__PURE__ */ new Set(), l = /* @__PURE__ */ new Set(), u = /* @__PURE__ */ new Map(), d = !0, f = !1, p, m = (e) => {
+		for (let t of r) try {
+			t(e);
+		} catch {}
+	}, h = () => {
+		!f && d && (d = !1, m({ kind: "disconnected" }));
+	}, g = e.status()[Symbol.asyncIterator](), _ = (async () => {
+		try {
+			for (;;) {
+				let e = await g.next();
+				if (e.done) break;
+				f || (e.value.type === "disconnect" ? h() : e.value.type === "reconnect" && !d && (d = !0, m({ kind: "reconnected" })));
+			}
+		} finally {
+			h();
+		}
+	})().catch(() => {
+		h();
+	}), v = () => {
+		if (f) throw Error("NATS transport is closed");
+		if (!d) throw Error("NATS transport is disconnected");
+	}, y = async (e) => {
+		let t = u.get(e);
+		t !== void 0 && (t.released = !0, u.delete(e), t.subscription.unsubscribe(), await t.done);
+	};
+	return {
+		publish: async (t, r) => {
+			n(t), v(), e.publish(t, i.encode(r));
+		},
+		flush: async () => {
+			v(), await c(e.flush(), o);
+		},
+		subscribe: async (r) => {
+			n(r), v();
+			let i = u.get(r);
+			if (i !== void 0) return i.ready;
+			let s = e.subscribe(r), d = {
+				subscription: s,
+				released: !1,
+				done: Promise.resolve(),
+				ready: Promise.resolve()
+			};
+			u.set(r, d), d.done = (async () => {
+				try {
+					for await (let e of s) {
+						if (f || d.released) continue;
+						let n = a.decode(e.data);
+						for (let e of t) try {
+							e(r, n);
+						} catch {}
+					}
+				} finally {
+					d.released || h();
+				}
+			})().catch(() => {
+				d.released || h();
+			}), l.add(d.done), d.done.then(() => {
+				l.delete(d.done);
+			}), d.ready = c(e.flush(), o).then(() => {
+				if (v(), d.released) throw Error("NATS subscription is closed");
+			}).catch(async (e) => {
+				throw u.get(r) === d && await y(r), e;
+			}), await d.ready;
+		},
+		unsubscribe: y,
+		onMessage: (e) => {
+			if (f) throw Error("NATS transport is closed");
+			return t.add(e), () => {
+				t.delete(e);
+			};
+		},
+		onTransportEvent: (e) => {
+			if (f) throw Error("NATS transport is closed");
+			return r.add(e), () => {
+				r.delete(e);
+			};
+		},
+		close: () => p ??= (async () => {
+			f = !0, t.clear(), r.clear();
+			for (let e of u.values()) {
+				e.released = !0;
+				try {
+					e.subscription.unsubscribe();
+				} catch {}
+			}
+			u.clear();
+			try {
+				await c(e.drain(), s);
+			} catch {} finally {
+				await e.close(), await g.return?.(), await Promise.all([...l]), await _;
+			}
+		})()
+	};
+}, u = (n) => r.callback((i) => {
+	let a = !1, s, c = (async () => {
+		let e = await (await import("@nats-io/transport-node").catch(t("@nats-io/transport-node", "A NATS connection"))).connect({
+			servers: n.url.split(",").map((e) => e.trim()),
+			maxReconnectAttempts: -1,
+			waitOnFirstConnect: !0,
+			reconnectTimeWait: 2e3,
+			timeout: o,
+			...n.tls === "required" ? { tls: {} } : {},
+			...n.token === void 0 ? {} : { token: n.token },
+			...n.user === void 0 ? {} : { user: n.user },
+			...n.pass === void 0 ? {} : { pass: n.pass },
+			reconnectToServer: () => {
+				if (a) throw Error("NATS acquisition cancelled");
+				return null;
+			}
+		});
+		if (a) await e.close();
+		else {
+			try {
+				s = l(e);
+			} catch (t) {
+				throw await e.close(), t;
+			}
+			i(r.succeed(s));
+		}
+	})().catch(() => {
+		a || i(r.fail(new e({
+			operation: "connect",
+			key: "",
+			cause: "NATS driver could not be opened"
+		})));
+	});
+	return r.promise(async () => {
+		a = !0, await c, await s?.close();
+	});
+});
+export { u as connectNats };

package/dist/connectionNatsConfig.js

@@ -0,0 +1,86 @@
+import { connectionDefinitionsProblem as e, natsConnectionName as t } from "./connectionDefinitions.js";
+import { Config as n, ConfigProvider as r, Effect as i, Option as a } from "effect";
+// src/connectionNatsConfig.ts
+var o = (e) => e.toUpperCase().replace(/[^A-Z0-9]+/g, "_"), s = (e) => {
+	if (typeof e.url != "string" || !e.url.trim()) return "A NATS connection requires an endpoint";
+	for (let t of e.url.split(",")) try {
+		let e = new URL(t.trim());
+		if (!["nats:", "tls:"].includes(e.protocol) || !e.hostname || e.pathname && e.pathname !== "/" || e.search || e.hash) return "A NATS connection requires nats:// or tls:// servers";
+		if (e.username || e.password) return "NATS credentials must use token or user/pass declarations, not endpoint userinfo";
+	} catch {
+		return "A NATS connection requires valid servers";
+	}
+	for (let t of [
+		e.token,
+		e.user,
+		e.pass
+	]) if (t !== void 0 && (typeof t != "string" || !t.trim())) return "NATS credentials must be nonempty";
+	if (e.user === void 0 != (e.pass === void 0)) return "NATS user and pass must resolve together";
+	if (e.token !== void 0 && e.user !== void 0) return "NATS token and user/pass authentication are exclusive";
+	if (e.tls !== void 0 && !["auto", "required"].includes(e.tls)) return "Connection tls must be auto or required";
+	if (e.keyPrefix !== void 0 && typeof e.keyPrefix != "string") return "Connection keyPrefix must be a string";
+	if (e.keyPrefix !== void 0 && (/[\s*>]/u.test(e.keyPrefix) || e.keyPrefix.startsWith(".") || e.keyPrefix.includes(".."))) return "A NATS namespace must preserve exact subjects";
+	if (e.allowSharedNamespace !== void 0 && typeof e.allowSharedNamespace != "boolean") return "Connection allowSharedNamespace must be a boolean";
+}, c = (c, l = {}, u) => {
+	let d = u === void 0 ? void 0 : Object.freeze({ tenantId: u.tenantId });
+	return i.gen(function* () {
+		let u = e(l);
+		if (u) return yield* i.fail(new n.ConfigError(new r.SourceError({ message: u })));
+		if (c.includes(":") && !/^nats:[A-Za-z][A-Za-z0-9_-]*$/.test(c)) return yield* i.fail(new n.ConfigError(new r.SourceError({ message: "A NATS consumer requires a nats:name connection reference" })));
+		if (c && !c.includes(":") && !/^[A-Za-z][A-Za-z0-9_-]*$/.test(c)) return yield* i.fail(new n.ConfigError(new r.SourceError({ message: "Malformed NATS connection reference" })));
+		let f = t(c, l), p = l.nats ?? {}, m = Object.keys(p), h = Object.hasOwn(p, f) ? p[f] : void 0;
+		if (h === void 0 && m.length > 0) return yield* i.fail(new n.ConfigError(new r.SourceError({ message: `Unknown NATS connection ${f || "(default)"}. Known names: ${m.sort().join(", ")}` })));
+		let g = `CONNECTIONS_NATS_${o(f)}`, _ = yield* n.String(`${g}_URL`).pipe(n.option), v = yield* n.String(`${g}_TOKEN`).pipe(n.option), y = yield* n.String(`${g}_USER`).pipe(n.option), b = yield* n.String(`${g}_PASS`).pipe(n.option), x = yield* n.String(`${g}_KEY_PREFIX`).pipe(n.option), S = {
+			...a.isSome(_) ? { url: _.value } : {},
+			...a.isSome(v) ? { token: v.value } : {},
+			...a.isSome(y) ? { user: y.value } : {},
+			...a.isSome(b) ? { pass: b.value } : {},
+			...a.isSome(x) ? { keyPrefix: x.value } : {}
+		}, C;
+		if (h !== void 0 && "_tag" in h) {
+			if (!d?.tenantId) return yield* i.fail(new n.ConfigError(new r.SourceError({ message: "A dynamic NATS connection requires tenantId" })));
+			C = {
+				...yield* h.resolve(d),
+				...S
+			};
+		} else if (h !== void 0) {
+			let { url: e, token: t, user: o, pass: s, ...c } = h, l = (e) => e === void 0 ? i.succeed(a.none()) : n.String(e.name).pipe(n.option), u = a.isSome(v) ? v : yield* l(t), d = a.isSome(y) ? y : yield* l(o), f = a.isSome(b) ? b : yield* l(s);
+			for (let [e, c] of [
+				[t, u],
+				[o, d],
+				[s, f]
+			]) if (e !== void 0 && a.isNone(c)) return yield* i.fail(new n.ConfigError(new r.SourceError({ message: `Missing declared NATS credential ${e.name}` })));
+			C = {
+				...c,
+				url: a.isSome(_) ? _.value : yield* n.String(e.name),
+				...a.isSome(u) ? { token: u.value } : {},
+				...a.isSome(d) ? { user: d.value } : {},
+				...a.isSome(f) ? { pass: f.value } : {},
+				...a.isSome(x) ? { keyPrefix: x.value } : {}
+			};
+		} else {
+			let e = o(f), t = (t) => n.String(`${e}_NATS_${t}`).pipe(n.orElse(() => n.String(`NATS_${t}`)), n.option), r = a.isSome(v) ? v : yield* t("TOKEN"), i = a.isSome(y) ? y : yield* t("USER"), s = a.isSome(b) ? b : yield* t("PASS");
+			C = {
+				url: a.isSome(_) ? _.value : yield* n.String(`${e}_NATS_URL`).pipe(n.orElse(() => n.String("NATS_URL"))),
+				...a.isSome(r) ? { token: r.value } : {},
+				...a.isSome(i) ? { user: i.value } : {},
+				...a.isSome(s) ? { pass: s.value } : {},
+				...a.isSome(x) ? { keyPrefix: x.value } : {}
+			};
+		}
+		let w = s(C);
+		if (w) return yield* i.fail(new n.ConfigError(new r.SourceError({ message: w })));
+		let T = [
+			_,
+			v,
+			y,
+			b,
+			x
+		].some(a.isSome);
+		return {
+			...C,
+			source: T ? "override" : h === void 0 ? "environment" : "config"
+		};
+	});
+};
+export { s as natsConfigProblem, c as natsConnectionConfig };

package/dist/connectionNatsSubjects.js

@@ -0,0 +1,15 @@
+// src/connectionNatsSubjects.ts
+var e = (e) => {
+	if (!e || /[\s*>]/u.test(e) || e.split(".").some((e) => !e)) throw Error("Registry NATS channels must be exact nonempty subjects");
+}, t = (e, t = "") => ({
+	publish: (n, r) => e.publish(t + n, r),
+	subscribe: (n) => e.subscribe(t + n),
+	unsubscribe: (n) => e.unsubscribe(t + n),
+	onMessage: (n) => e.onMessage((e, r) => {
+		e.startsWith(t) && n(e.slice(t.length), r);
+	}),
+	onTransportEvent: e.onTransportEvent,
+	flush: e.flush,
+	close: e.close
+});
+export { e as assertNatsSubject, t as withNatsSubjectPrefix };

package/dist/connectionOwner.js

@@ -0,0 +1,43 @@
+import { KvError as e } from "./errors.js";
+import { Deferred as t, Effect as n, Scope as r } from "effect";
+// src/connectionOwner.ts
+var i = (i) => n.gen(function* () {
+	let a = yield* n.scope, o = /* @__PURE__ */ new Set(), s = /* @__PURE__ */ new Set(), c = !1, l = (e) => n.uninterruptible(n.suspend(() => e.closed ? t.await(e.closedSignal) : (e.closed = !0, i.dispose(e).pipe(n.ensuring(n.sync(() => {
+		o.delete(e);
+	}).pipe(n.andThen(t.succeed(e.closedSignal, void 0))))))));
+	return yield* r.addFinalizer(a, n.gen(function* () {
+		c = !0, i.onStopping(), yield* n.forEach([...s], t.await, {
+			concurrency: "unbounded",
+			discard: !0
+		}), yield* n.forEach([...o], (e) => n.gen(function* () {
+			e.retired = !0, e.active > 0 && !e.closed && (yield* (e.drainUntilReleased ? t.await(e.closedSignal) : n.raceFirst(n.sleep(i.rotationGraceMs), t.await(e.closedSignal))).pipe(n.interruptible)), yield* l(e);
+		}), {
+			concurrency: "unbounded",
+			discard: !0
+		}), i.onStopped();
+	})), {
+		get stopped() {
+			return c;
+		},
+		register: (e) => {
+			o.add(e);
+		},
+		close: l,
+		retire: (e) => n.gen(function* () {
+			e.retired = !0, e.active === 0 ? yield* l(e) : e.drainUntilReleased || (yield* n.raceFirst(n.sleep(i.rotationGraceMs), t.await(e.closedSignal)).pipe(n.andThen(l(e)), n.interruptible, n.forkIn(a)));
+		}),
+		release: (e) => n.suspend(() => (e.active--, e.retired && e.active === 0 ? l(e) : n.void)),
+		trackOpen: (r) => n.uninterruptibleMask((i) => n.gen(function* () {
+			if (c) return yield* n.fail(new e({
+				operation: "connect",
+				key: "",
+				cause: "Connection registry is closed"
+			}));
+			let a = yield* t.make();
+			return s.add(a), yield* i(r).pipe(n.ensuring(n.sync(() => {
+				s.delete(a);
+			}).pipe(n.andThen(t.succeed(a, void 0)))));
+		}))
+	};
+});
+export { i as makeConnectionOwner };