@voltro/plugin-rooms 0.0.0-stage → 0.88.0

package/dist/commandDelivery.js

@@ -0,0 +1,100 @@
+import { BudgetExceeded as e, ProtocolError as t } from "./errors.js";
+import "./ports.js";
+import { Effect as n, Result as r } from "effect";
+// src/commandDelivery.ts
+var i = "Room app command deferred; it stays pending for the next delivery turn", a = () => new t({ detail: i }), o = "Room application command failed", s = 3e5, c = (e) => {
+	let { roomId: t, requestId: n } = e, [r, i, ...a] = n.startsWith(t + ":") ? n.slice(t.length + 1).split(":") : [];
+	return a.length === 0 && r !== void 0 && i !== void 0 && /^[1-9][0-9]*$/.test(r) && /^[0-9]+$/.test(i) && Number.isSafeInteger(Number(r)) ? Number(r) : null;
+}, l = (e) => {
+	let r = new Map(Object.entries(e.run)), i = new Map(Object.entries(e.publish));
+	return Object.freeze({ deliver: (e) => n.suspend(() => {
+		let { command: a, roomId: s, tenantId: c, requestId: l } = structuredClone(e);
+		if (!s.trim() || !c.trim() || !l.trim() || l !== a.requestId) return n.fail(new t({ detail: "Room command identity is malformed" }));
+		let u = Object.freeze({
+			roomId: s,
+			tenantId: c,
+			requestId: l
+		});
+		if (!(a.kind === "run" ? r.get(a.name) : i.get(a.name)) || a.kind === "publish" && !a.key?.trim()) return n.fail(new t({ detail: "Room command does not name an admitted application descriptor" }));
+		let d = a.kind === "run" ? r.get(a.name)(a.payload, u) : i.get(a.name)(a.payload, Object.freeze({
+			...u,
+			key: a.key
+		}));
+		return n.isEffect(d) ? d.pipe(n.mapError(() => new t({ detail: o }))) : n.fail(new t({ detail: "Room app commands must return an Effect" }));
+	}).pipe(n.catchCause(() => n.fail(new t({ detail: o })))) });
+}, u = class {
+	checkpoints;
+	application;
+	maxRooms;
+	maxCommands;
+	executeOwned;
+	active = /* @__PURE__ */ new Set();
+	attempts = /* @__PURE__ */ new Map();
+	maxAttempts;
+	parkAfterMs;
+	now;
+	constructor(e, n, r = 256, i = 128, a, o = {}) {
+		if (this.checkpoints = e, this.application = n, this.maxRooms = r, this.maxCommands = i, this.executeOwned = a, this.maxAttempts = o.maxAttempts ?? 5, this.parkAfterMs = o.afterMs ?? 3e5, this.now = o.now ?? Date.now, a !== void 0 && typeof a != "function") throw new t({ detail: "Command delivery requires an actual execution scope" });
+		if (![
+			r,
+			i,
+			this.maxAttempts
+		].every((e) => Number.isSafeInteger(e) && e > 0) || !Number.isSafeInteger(this.parkAfterMs) || this.parkAfterMs < 0 || typeof this.now != "function") throw new t({ detail: "Invalid app-command delivery budgets" });
+	}
+	async deliver(i, a, o = this.maxCommands) {
+		if (!Number.isSafeInteger(o) || o < 1 || o > this.maxCommands) throw new e({
+			budget: "deliveredRoomCommands",
+			limit: this.maxCommands
+		});
+		let s = JSON.stringify([a, i]);
+		if (this.active.has(s)) throw new t({ detail: "Room command delivery cannot overlap for the same room" });
+		if (this.active.size >= this.maxRooms) throw new e({
+			budget: "activeRoomCommandDeliveries",
+			limit: this.maxRooms
+		});
+		this.active.add(s);
+		let c = async (e) => {
+			let t = await n.runPromise(n.result(e));
+			if (r.isFailure(t)) throw t.failure;
+			return t.success;
+		};
+		try {
+			let e = await c(this.checkpoints.pending(i, a, o));
+			if (e.length > o) throw new t({ detail: "Checkpoint port exceeded its command-query budget" });
+			let n = 0;
+			for (let r of e) {
+				let e = () => c(this.application.deliver({
+					roomId: i,
+					tenantId: a,
+					requestId: r.requestId,
+					command: structuredClone(r)
+				}));
+				try {
+					this.executeOwned ? await this.executeOwned(e) : await e();
+				} catch (e) {
+					if (e instanceof t && e.detail === "Room app command deferred; it stays pending for the next delivery turn") return n;
+					let o = JSON.stringify([
+						a,
+						i,
+						r.requestId
+					]), s = this.now(), l = this.attempts.get(o), u = {
+						firstAt: l?.firstAt ?? s,
+						failures: (l?.failures ?? 0) + 1
+					}, d = this.checkpoints.park;
+					if (!(e instanceof t && e.detail === "Room application command failed") || u.failures < this.maxAttempts || s - u.firstAt < this.parkAfterMs || d === void 0) throw (this.attempts.size < this.maxRooms * this.maxCommands || l) && this.attempts.set(o, u), e;
+					await c(d(i, a, r.requestId)), this.attempts.delete(o);
+					continue;
+				}
+				this.attempts.delete(JSON.stringify([
+					a,
+					i,
+					r.requestId
+				])), await c(this.checkpoints.acknowledge(i, a, r.requestId)), n++;
+			}
+			return n;
+		} finally {
+			this.active.delete(s);
+		}
+	}
+};
+export { i as ROOM_COMMAND_DEFERRED, o as ROOM_COMMAND_FAILED, s as ROOM_COMMAND_PARK_AFTER_MS, u as RoomCommandDelivery, l as applicationRoomCommands, a as roomCommandDeferred, c as roomCommandEpoch };

package/dist/commandRecord.js

@@ -0,0 +1,10 @@
+import { ProtocolError as e } from "./errors.js";
+import { canonicalRoomJson as t } from "./checkpointJson.js";
+import { createHash as n } from "node:crypto";
+// src/commandRecord.ts
+var r = (r, i, a, o) => {
+	let s = t(r.command), c = JSON.parse(s);
+	if (r.roomId !== i || r.tenantId !== a || Buffer.byteLength(s, "utf8") > o || !c || typeof c != "object" || Array.isArray(c) || ![r.epoch, r.sequence].every((e) => typeof e == "number" && Number.isSafeInteger(e) && e > 0) || r.digest !== n("sha256").update(s).digest("hex") || c.requestId !== r.requestId || c.requestId !== `${i}:${r.epoch}:${r.sequence}` || !["run", "publish"].includes(c.kind) || typeof c.name != "string" || !c.name.trim() || c.kind === "publish" && (typeof c.key != "string" || !c.key.trim())) throw new e({ detail: "Durable Room command integrity failed" });
+	return c;
+};
+export { r as decodeDurableRoomCommand };

package/dist/commandWithdrawal.js

@@ -0,0 +1,182 @@
+import { ProtocolError as e } from "./errors.js";
+import { ROOMS_TABLE as t, ROOM_COMMANDS_TABLE as n } from "./identities.js";
+import { RoomExternalWorkWithdrawalPort as r } from "./ports.js";
+import { captureRoomSnapshotEffectRunner as i } from "./snapshotBlobIndex.js";
+import { readRoomErasureJournal as a } from "./roomErasure.js";
+import { decodeDurableRoomCommand as o } from "./commandRecord.js";
+import { captureRoomHostWithdrawalInput as s } from "./ownershipWithdrawal.js";
+import { and as c, eq as l } from "@voltro/database";
+import { Effect as u, Layer as d } from "effect";
+// src/commandWithdrawal.ts
+function f(t) {
+	throw new e({ detail: t });
+}
+var p = (e) => typeof e == "string" && e.trim() && e.length <= 191 ? e : f("Invalid command withdrawal request"), m = (e) => {
+	if (!e || typeof e != "object" || Array.isArray(e) || Object.keys(e).some((e) => ![
+		"roomId",
+		"tenantId",
+		"priorEpoch",
+		"withdrawnEpoch",
+		"requestId"
+	].includes(e))) return f("Invalid command withdrawal input");
+	let t = s({
+		roomId: e.roomId,
+		tenantId: e.tenantId,
+		priorEpoch: e.priorEpoch,
+		withdrawnEpoch: e.withdrawnEpoch
+	});
+	return Object.freeze({
+		...t,
+		requestId: p(e.requestId)
+	});
+}, h = (e, t) => {
+	let n = e.withdrawal;
+	if (n == null) return null;
+	if (!n || typeof n != "object" || Array.isArray(n)) return f("Malformed command withdrawal receipt");
+	let r = n;
+	return Object.keys(r).some((e) => ![
+		"version",
+		"requestId",
+		"withdrawnEpoch",
+		"commandDigest",
+		"state"
+	].includes(e)) || r.version !== 1 || r.requestId !== t.requestId || r.withdrawnEpoch !== t.withdrawnEpoch || r.commandDigest !== e.digest || r.state !== "complete" ? f("Command withdrawal receipt changed scope or data") : Object.freeze({
+		version: 1,
+		requestId: r.requestId,
+		withdrawnEpoch: r.withdrawnEpoch,
+		commandDigest: r.commandDigest,
+		state: "complete"
+	});
+}, g = (r, s, d = {}) => {
+	if (!s || typeof s != "object" || !s.run || !s.publish) return f("Missing app command withdrawal bindings");
+	let p = new Map(Object.entries(s.run)), g = new Map(Object.entries(s.publish));
+	if ([...p.values(), ...g.values()].some((e) => typeof e != "function")) return f("Invalid app command withdrawal handler");
+	let _ = d.maxCommands ?? 4096, v = d.maxCommandBytes ?? 1048576;
+	if (!Number.isSafeInteger(_) || _ < 1 || _ > 65536 || !Number.isSafeInteger(v) || v < 1 || v > 67108864) return f("Invalid command withdrawal budgets");
+	let y = async (e, n) => {
+		let r = await e.query({
+			table: t,
+			predicate: c(l("id", n.roomId), l("tenantId", n.tenantId)),
+			order: [],
+			take: 2,
+			skip: void 0,
+			projection: [
+				"id",
+				"tenantId",
+				"epoch",
+				"hostId",
+				"state",
+				"clients",
+				"locked",
+				"private",
+				"erasure"
+			],
+			lock: "update"
+		});
+		if (r.length !== 1) return f("Command withdrawal has no exact room authority");
+		let i = a(r[0], n.roomId, n.tenantId);
+		return !i || i.requestId !== n.requestId || i.priorEpoch !== n.priorEpoch || i.withdrawnEpoch !== n.withdrawnEpoch || i.phase === "fenced" ? f("Command withdrawal requires confirmed former-owner withdrawal") : i.phase === "data-erased" || i.phase === "complete" ? "removed" : "present";
+	}, b = (e, t) => {
+		let n = o(e, t.roomId, t.tenantId, v);
+		return typeof e.id != "string" || !e.id.trim() || e.id.length > 191 || Number(e.epoch) >= t.withdrawnEpoch ? f("Command withdrawal encountered an unfenced writer") : (n.kind === "run" ? p.get(n.name) : g.get(n.name)) ? {
+			row: e,
+			command: n,
+			saved: h(e, t)
+		} : f("Command withdrawal has no admitted app handler");
+	}, x = [
+		"id",
+		"roomId",
+		"tenantId",
+		"epoch",
+		"sequence",
+		"command",
+		"digest",
+		"requestId",
+		"withdrawal"
+	], S = async (e, t) => {
+		let r = await e.query({
+			table: n,
+			predicate: c(l("roomId", t.roomId), l("tenantId", t.tenantId)),
+			order: [{
+				column: "epoch",
+				direction: "asc"
+			}, {
+				column: "sequence",
+				direction: "asc"
+			}],
+			take: _ + 1,
+			skip: void 0,
+			projection: x,
+			lock: "update"
+		});
+		return r.length > _ || new Set(r.map((e) => e.id)).size !== r.length || new Set(r.map((e) => e.requestId)).size !== r.length ? f("Invalid or oversized command withdrawal inventory") : r.map((e) => b(e, t));
+	}, C = async (e, t, r) => {
+		let i = await e.query({
+			table: n,
+			predicate: c(l("id", r), l("roomId", t.roomId), l("tenantId", t.tenantId)),
+			order: [],
+			take: 2,
+			skip: void 0,
+			projection: x,
+			lock: "update"
+		});
+		return i.length !== 1 || i[0].id !== r ? f("Command withdrawal lost its exact durable operation") : b(i[0], t);
+	};
+	return Object.freeze({ withdraw: (t) => {
+		let n;
+		try {
+			n = m(t);
+		} catch {
+			return u.fail(new e({ detail: "Command withdrawal admission failed" }));
+		}
+		return u.flatMap(u.context(), (t) => u.uninterruptible(u.tryPromise({
+			try: async () => {
+				let e = i(t), a = await r.transactional(async (e) => {
+					let t = await y(e, n), r = await S(e, n);
+					return t === "removed" && r.length ? f("Erased room has reintroduced app commands") : r;
+				});
+				for (let t of a) {
+					let i = await r.transactional(async (e) => {
+						await y(e, n);
+						let r = await C(e, n, t.row.id);
+						return r.row.digest === t.row.digest ? r : f("Command withdrawal lost its durable operation");
+					});
+					if (i.saved) continue;
+					let a = Object.freeze({
+						roomId: n.roomId,
+						tenantId: n.tenantId,
+						priorEpoch: n.priorEpoch,
+						withdrawnEpoch: n.withdrawnEpoch,
+						requestId: i.command.requestId,
+						erasureRequestId: n.requestId
+					}), o = i.command, s = o.kind === "run" ? p.get(o.name)(o.payload, a) : g.get(o.name)(o.payload, Object.freeze({
+						...a,
+						key: o.key
+					}));
+					if (!u.isEffect(s)) return f("Command withdrawal handler must return an Effect");
+					await e(s), await r.transactional(async (e) => {
+						await y(e, n);
+						let r = await C(e, n, t.row.id);
+						if (r.row.digest !== t.row.digest) return f("Command withdrawal lost its completion receipt");
+						if (r.saved) return;
+						let i = {
+							version: 1,
+							requestId: n.requestId,
+							withdrawnEpoch: n.withdrawnEpoch,
+							commandDigest: String(r.row.digest),
+							state: "complete"
+						};
+						if (await e.updateMany("_voltro_room_outbox", { withdrawal: i }, { where: c(l("id", r.row.id), l("roomId", n.roomId), l("tenantId", n.tenantId), l("digest", r.row.digest)) }) !== 1) return f("Command withdrawal lost its SQL write");
+					});
+				}
+				await r.transactional(async (e) => {
+					await y(e, n);
+					let t = await S(e, n), r = new Map(a.map((e) => [e.row.id, e.row.digest]));
+					if (t.length !== a.length || t.some((e) => !e.saved || r.get(e.row.id) !== e.row.digest)) return f("Command withdrawal inventory is not completely confirmed");
+				});
+			},
+			catch: () => new e({ detail: "Room app command withdrawal remains unconfirmed" })
+		})));
+	} });
+}, _ = (e, t, n = {}) => d.succeed(r, g(e, t, n));
+export { g as applicationRoomExternalWorkWithdrawal, _ as roomExternalWorkWithdrawalLayer };