@voltro/plugin-rooms 0.0.0-stage → 0.87.0

package/dist/hostBinding.js

@@ -0,0 +1,277 @@
+import { ProtocolError as e } from "./errors.js";
+import { simulationOwnData as t } from "./simulationAuthoring.js";
+import { captureWorldCatalog as n } from "./world.js";
+import { captureRoomPoolCatalog as r, roomPoolHostedNames as i } from "./roomPoolTopology.js";
+import { captureRoomHostDrainPolicy as a } from "./hostDrain.js";
+import { frameworkStartCause as o } from "./startFailureCause.js";
+import { RoomHostLane as s, RoomHostLaneStartFailure as c } from "./hostLane.js";
+import { assertRoomHostListenerDeployment as l } from "./hostListenerBinding.js";
+import { captureRoomHostShutdownPolicy as u, superviseRoomHostDrain as d } from "./hostShutdown.js";
+import { captureRoomHostDeployment as f } from "./hostDeployment.js";
+import { validateWorldRooms as p } from "./worldCatalog.js";
+import { performance as m } from "node:perf_hooks";
+//#region src/hostBinding.ts
+var h = (n) => {
+	let r = t(n, ["pool", "region"], []), i = {};
+	for (let t of ["pool", "region"]) {
+		if (!Object.hasOwn(r, t)) continue;
+		let n = r[t];
+		if (typeof n != "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,95}$/.test(n) || [
+			"__proto__",
+			"prototype",
+			"constructor"
+		].includes(n)) throw new e({ detail: "Room host selection requires bounded pool and region identifiers" });
+		i[t] = n;
+	}
+	return Object.freeze(i);
+}, g = class extends Error {
+	retryCleanup;
+	name = "RoomsHostBindFailure";
+	constructor(e) {
+		super("Room host provider cleanup remains incomplete"), this.retryCleanup = e;
+	}
+}, _ = class extends Error {
+	stage;
+	retryCleanup;
+	name = "RoomsHostStartFailure";
+	constructor(e, t, n) {
+		super(`Room host startup failed during ${e}; cleanup remains owned`, o(n) === void 0 ? void 0 : { cause: n }), this.stage = e, this.retryCleanup = t;
+	}
+}, v = class extends Error {
+	retryCleanup;
+	name = "RoomsHostStopFailure";
+	constructor(e) {
+		super("Room host cleanup remains incomplete"), this.retryCleanup = e;
+	}
+}, y = class {
+	pluginName;
+	binder;
+	phase = "idle";
+	abort = new AbortController();
+	acquisition = null;
+	closing = null;
+	lane = null;
+	laneClosing = null;
+	control = null;
+	partialLane = null;
+	partialControl = null;
+	release = null;
+	failed = !1;
+	plannedDrain = null;
+	shutdownPolicy = null;
+	shutdownDeadline = null;
+	stopping = null;
+	worldState;
+	constructor(t, n, r = {}) {
+		if (this.pluginName = t, this.binder = n, !t.trim() || typeof n != "function") throw new e({ detail: "Room host requires an explicit complete provider" });
+		let i = r.worldState ?? "none";
+		if (![
+			"none",
+			"entities",
+			"transitions"
+		].includes(i)) throw new e({ detail: "Room host World state must be none, entities or transitions" });
+		this.worldState = i;
+	}
+	get status() {
+		return this.phase;
+	}
+	get signal() {
+		return this.abort.signal;
+	}
+	get hasRuntimeFailure() {
+		return this.failed;
+	}
+	start(t, a, o = [], d = {}, m, v) {
+		if (this.phase !== "idle") return Promise.reject(new e({ detail: "Room host owner is single-use" }));
+		let y, b;
+		try {
+			if (y = h(d), b = m === void 0 ? void 0 : r(m, a.inventory().map((e) => e.descriptor.name)), b) {
+				let t = y.pool ?? b.default, n = b.pools[t];
+				if (!n || y.region !== void 0 && !n.regions.includes(y.region)) throw new e({ detail: "Room host selection is outside the app pool topology" });
+				y = Object.freeze({
+					...y,
+					pool: t
+				});
+			}
+		} catch (e) {
+			return Promise.reject(e);
+		}
+		let x, S;
+		try {
+			x = n(o), S = p(x, a);
+		} catch {
+			return Promise.reject(new e({ detail: "World catalogue does not match the admitted Room inventory" }));
+		}
+		let C = new Set(i(b, b === void 0 ? void 0 : y.pool, a.inventory().map((e) => e.descriptor.name))), w = Object.freeze(a.inventory().filter((e) => C.has(e.descriptor.name))), T = Object.freeze(x.filter((e) => S.some((t) => t.worldId === e.name && C.has(t.room))));
+		if (this.phase = "starting", v !== void 0 && typeof v != "function") return Promise.reject(new e({ detail: "Room host app dependencies must be a function" }));
+		let E = Object.freeze({
+			root: t,
+			pluginName: this.pluginName,
+			catalog: a,
+			hostedRooms: w,
+			hostedWorlds: T,
+			worlds: x,
+			worldRooms: S,
+			worldState: this.worldState,
+			selection: y,
+			pools: b,
+			signal: this.abort.signal,
+			...v === void 0 ? {} : { appDependencies: v }
+		}), D = Object.freeze({
+			VOLTRO_ROOMS_HOST_DEPLOYMENT: process.env.VOLTRO_ROOMS_HOST_DEPLOYMENT,
+			VOLTRO_ROOMS_HOST_METRICS_TOKEN: process.env.VOLTRO_ROOMS_HOST_METRICS_TOKEN,
+			VOLTRO_ROOMS_HOST_METRICS_TOKEN_PREVIOUS: process.env.VOLTRO_ROOMS_HOST_METRICS_TOKEN_PREVIOUS,
+			VOLTRO_ROOMS_HOST_POD_NAME: process.env.VOLTRO_ROOMS_HOST_POD_NAME
+		}), O = (async () => {
+			let t = "provider";
+			try {
+				let n = await this.binder(E);
+				if (typeof n?.release != "function") throw new e({ detail: "Room host provider must return its owned release operation" });
+				if (this.release = n.release.bind(n), this.shutdownPolicy = n.shutdown === void 0 ? null : u(n.shutdown), !n.store || !n.options || typeof n.openControl != "function") throw new e({ detail: "Room host provider must supply SQL, host configuration and control transport" });
+				if (b !== void 0 && n.options.host.pools !== b) throw new e({ detail: "Room host provider did not retain the app pool topology" });
+				if (y.pool !== void 0 && n.options.host.pool !== y.pool || y.region !== void 0 && n.options.host.region !== y.region) throw new e({ detail: "Room host provider did not honor the process pool and region selection" });
+				let r = f(D, n.options.host.pool, n.options.host.region);
+				if (r) {
+					if (r.shutdown && (!this.shutdownPolicy || this.shutdownPolicy.drainMs > r.shutdown.drainMs)) throw new e({ detail: "Room host shutdown policy exceeds or is missing from its deployment drain budget" });
+					if (l(n.options.listener, r), r.publicAddress !== void 0 && n.options.host.address !== r.publicAddress) throw new e({ detail: "Room host provider did not apply its deployment public address" });
+				}
+				let i = n.openControl.bind(n);
+				this.requireAcquiring(), t = "lane";
+				let o = n.options.driver.onFailure.bind(n.options.driver);
+				this.lane = await s.start(n.store, a, {
+					...n.options,
+					processRole: "rooms",
+					startSuspended: !0,
+					host: {
+						...n.options.host,
+						worlds: T
+					},
+					driver: {
+						...n.options.driver,
+						onFailure: (t) => {
+							this.failed = !0, this.abort.abort(), this.close().catch(() => void 0);
+							let n = o(t);
+							if (n !== void 0) throw n instanceof Promise && n.catch(() => void 0), new e({ detail: "Room host failure observer must return synchronous void" });
+						}
+					}
+				}), this.requireAcquiring(), t = "control";
+				let c = await i(this.lane, E);
+				if (typeof c?.close != "function") throw new e({ detail: "Room control provider must return its owned cleanup" });
+				if (this.control = {
+					fence: typeof c.fence == "function" ? c.fence.bind(c) : () => {
+						throw new e({ detail: "Room control provider has no admission fence" });
+					},
+					close: c.close.bind(c)
+				}, typeof c.fence != "function") throw new e({ detail: "Room control provider must return a synchronous fence" });
+				return this.requireAcquiring(), t = "activation", await this.lane.activate(), this.requireAcquiring(), this.phase = "running", this.lane;
+			} catch (e) {
+				this.phase = "closing", this.abort.abort(), e instanceof c && !this.lane && (this.partialLane = e.retryCleanup), e instanceof g && (t === "control" ? this.partialControl = e.retryCleanup : this.release = e.retryCleanup);
+				try {
+					await this.releaseResources();
+				} catch {}
+				throw new _(t, () => this.close(), e);
+			}
+		})();
+		return this.acquisition = O, O.then(() => {
+			this.acquisition = null;
+		}, () => {
+			this.acquisition = null;
+		}), O;
+	}
+	requireAcquiring() {
+		if (this.abort.signal.aborted || this.phase !== "starting") throw new e({ detail: "Room host acquisition was cancelled" });
+	}
+	fenceLane() {
+		if (this.laneClosing) return this.laneClosing;
+		if (!this.lane) return Promise.resolve();
+		try {
+			this.laneClosing = this.plannedDrain ? this.lane.drain(this.plannedDrain) : this.lane.close();
+		} catch (e) {
+			this.laneClosing = Promise.reject(e);
+		}
+		return this.laneClosing.catch(() => void 0), this.laneClosing;
+	}
+	async releaseResources() {
+		let t = [];
+		if (this.control) try {
+			this.control.fence();
+		} catch (e) {
+			t.push(e);
+		}
+		let n = this.lane, r = this.control, i = await Promise.allSettled([
+			n ? this.fenceLane().then(() => {
+				this.lane = null;
+			}).finally(() => {
+				this.laneClosing = null;
+			}) : Promise.resolve(),
+			r ? Promise.resolve().then(() => r.close()).then(() => {
+				this.control = null;
+			}) : Promise.resolve(),
+			this.partialLane ? Promise.resolve().then(() => this.partialLane()).then(() => {
+				this.partialLane = null;
+			}) : Promise.resolve(),
+			this.partialControl ? Promise.resolve().then(() => this.partialControl()).then(() => {
+				this.partialControl = null;
+			}) : Promise.resolve()
+		]);
+		for (let e of i) e.status === "rejected" && t.push(e.reason);
+		if (t.length > 0) throw new e({ detail: "Room host lane or control cleanup remains incomplete" });
+		this.release &&= (await this.release(), null), this.phase = "closed";
+	}
+	stop() {
+		if (this.phase === "closed") return Promise.resolve();
+		if (this.stopping) return this.stopping;
+		if (!this.shutdownPolicy || !this.plannedDrain && (this.phase !== "running" || this.failed)) return this.close();
+		let e = this.plannedDrain ?? this.shutdownPolicy;
+		this.shutdownDeadline ??= m.now() + this.shutdownPolicy.drainMs;
+		let t = Promise.withResolvers();
+		return this.stopping = t.promise, d(() => this.drain({
+			graceMs: e.graceMs,
+			maxCheckpointBytes: e.maxCheckpointBytes
+		}), this.shutdownDeadline, () => this.close()).then(t.resolve, t.reject), t.promise.then(() => {
+			this.stopping = null;
+		}, () => {
+			this.stopping = null;
+		}), t.promise;
+	}
+	drain(t) {
+		try {
+			let n = a(t);
+			if (this.plannedDrain) {
+				if (n.graceMs !== this.plannedDrain.graceMs || n.maxCheckpointBytes !== this.plannedDrain.maxCheckpointBytes) throw new e({ detail: "Room host owner drain retry cannot change its retained policy" });
+			} else {
+				if (this.phase !== "running" || !this.lane?.controller.host.membership || this.failed) throw new e({ detail: "Planned owner drain requires a running registered process" });
+				this.plannedDrain = n;
+			}
+			return this.close();
+		} catch (e) {
+			return Promise.reject(e);
+		}
+	}
+	close() {
+		if (this.phase === "closed") return Promise.resolve();
+		if (this.closing) return this.closing;
+		this.phase = "closing", this.abort.abort();
+		try {
+			this.control?.fence();
+		} catch {}
+		this.lane && this.fenceLane().catch(() => void 0);
+		let e = (async () => {
+			try {
+				await this.acquisition;
+			} catch {}
+			try {
+				await this.releaseResources();
+			} catch {
+				throw new v(() => this.close());
+			}
+		})();
+		return this.closing = e, e.then(() => {
+			this.closing = null;
+		}, () => {
+			this.closing = null;
+		}), e;
+	}
+};
+//#endregion
+export { g as RoomsHostBindFailure, y as RoomsHostOwner, _ as RoomsHostStartFailure, v as RoomsHostStopFailure };

package/dist/hostCellObservation.js

@@ -0,0 +1,114 @@
+import { ROOMS_TABLE as e } from "./identities.js";
+import { captureWorldCatalog as t } from "./world.js";
+import { WORLD_CELLS_TABLE as n } from "./worldCells.js";
+import { and as r, eq as i } from "@voltro/database";
+import { performance as a } from "node:perf_hooks";
+//#region src/hostCellObservation.ts
+var o = class {
+	hostId;
+	capacity;
+	now;
+	worlds;
+	observed = null;
+	next = 0;
+	last = 0;
+	invalidClock = !1;
+	constructor(e, n, r, i = () => a.now()) {
+		this.hostId = n, this.capacity = r, this.now = i, this.worlds = e === void 0 ? void 0 : t(e);
+	}
+	time() {
+		try {
+			let e = this.now();
+			return (!Number.isFinite(e) || e < this.last) && (this.invalidClock = !0), this.invalidClock ? null : (this.last = e, e);
+		} catch {
+			return this.invalidClock = !0, null;
+		}
+	}
+	identity(e) {
+		return JSON.stringify(e.map((e) => [
+			e.roomId,
+			e.tenantId,
+			e.epoch,
+			e.name,
+			e.published
+		]).sort((e, t) => String(e[0]).localeCompare(String(t[0]))));
+	}
+	snapshot(e) {
+		let t = this.time(), n = this.observed;
+		return t !== null && n !== null && t - n.at < 5e3 && n.owners === this.identity(e) ? n.count : null;
+	}
+	async refresh(t, a) {
+		let o = this.time(), s = this.identity(a);
+		if (o === null || this.worlds === void 0) this.observed = null;
+		else if (!(o < this.next)) {
+			this.next = o + 1e3, this.observed = null;
+			try {
+				let c = this.worlds, l = new Map(a.map((e) => [e.roomId, e]));
+				if (l.size !== a.length || a.length > this.capacity) return;
+				let u = c.length === 0 ? 0 : await t.transactional(async (t) => {
+					let o = await t.query({
+						table: n,
+						predicate: i("hostId", this.hostId),
+						order: [{
+							column: "id",
+							direction: "asc"
+						}],
+						take: this.capacity + 1,
+						skip: void 0,
+						projection: [
+							"tenantId",
+							"worldId",
+							"zoneId",
+							"cellId",
+							"layer",
+							"roomId",
+							"hostId",
+							"epoch",
+							"state"
+						]
+					});
+					if (o.length > this.capacity) return null;
+					let s = await t.query({
+						table: e,
+						predicate: r(i("hostId", this.hostId), i("state", "live")),
+						order: [{
+							column: "id",
+							direction: "asc"
+						}],
+						take: this.capacity + 1,
+						skip: void 0,
+						projection: [
+							"id",
+							"tenantId",
+							"hostId",
+							"epoch",
+							"name",
+							"state"
+						]
+					});
+					if (s.length > this.capacity) return null;
+					let u = new Map(s.map((e) => [e.id, e]));
+					if (u.size !== s.length) return null;
+					let d = /* @__PURE__ */ new Set();
+					for (let e of o) {
+						let t = typeof e.roomId == "string" ? l.get(e.roomId) : void 0, n = c.find((t) => t.name === e.worldId);
+						if (!t?.published || !n || e.hostId !== this.hostId || e.state !== "live" || e.tenantId !== t.tenantId || e.epoch !== t.epoch || !n.zones.some((n) => n.id === e.zoneId && n.room === t.name) || typeof e.cellId != "string" || !e.cellId || !Number.isSafeInteger(e.layer) || Number(e.layer) < 1 || d.has(t.roomId)) return null;
+						d.add(t.roomId);
+						let r = u.get(t.roomId);
+						if (!r || r.tenantId !== t.tenantId || r.hostId !== this.hostId || r.epoch !== t.epoch || r.name !== t.name || r.state !== "live") return null;
+					}
+					return a.some((e) => c.some((t) => t.zones.some((t) => t.room === e.name)) && !d.has(e.roomId)) ? null : o.length;
+				});
+				u !== null && (this.observed = {
+					count: u,
+					at: o,
+					owners: s
+				});
+			} catch {
+				this.observed = null;
+			}
+		}
+	}
+};
+//#endregion
+export { o as RoomHostCellObservation };

package/dist/hostClientCapacity.js

@@ -0,0 +1,90 @@
+import { ProtocolError as e, RoomFull as t, RoomGone as n } from "./errors.js";
+import { ROOMS_TABLE as r, ROOM_HOSTS_TABLE as i } from "./identities.js";
+import { and as a, eq as o, or as s } from "@voltro/database";
+//#region src/hostClientCapacity.ts
+function c() {
+	throw new e({ detail: "Host client capacity authority is inconsistent or exceeds its scan budget" });
+}
+var l = (e) => typeof e == "number" && Number.isSafeInteger(e) && e >= 0 ? e : c(), u = async (e, t, s) => {
+	let l = [...new Set(t)].sort(), u = /* @__PURE__ */ new Map();
+	for (let t of l) {
+		let i = (await e.query({
+			table: r,
+			predicate: a(o("id", t), o("tenantId", s)),
+			order: [],
+			take: 1,
+			skip: void 0,
+			projection: ["hostId"]
+		}))[0];
+		if (!i) throw new n({ roomId: t });
+		let l = i.hostId;
+		if (l !== null && (typeof l != "string" || !l)) return c();
+		u.set(t, l);
+	}
+	for (let t of [...new Set([...u.values()].filter((e) => e !== null))].sort()) await e.query({
+		table: i,
+		predicate: o("id", t),
+		order: [],
+		take: 1,
+		skip: void 0,
+		projection: ["id"],
+		lock: "update"
+	});
+	let d = /* @__PURE__ */ new Map();
+	for (let t of l) {
+		let i = (await e.query({
+			table: r,
+			predicate: a(o("id", t), o("tenantId", s)),
+			order: [],
+			take: 1,
+			skip: void 0,
+			projection: void 0,
+			lock: "update"
+		}))[0];
+		if (!i || i.hostId !== u.get(t)) throw new n({ roomId: t });
+		d.set(t, i);
+	}
+	return d;
+}, d = async (e, u, d, f) => {
+	if (l(d), !Number.isSafeInteger(f) || f < 1 || f >= 2 ** 53 - 1) return c();
+	let p = (await e.query({
+		table: i,
+		predicate: o("id", u),
+		order: [],
+		take: 1,
+		skip: void 0,
+		projection: [
+			"pool",
+			"clientCapacity",
+			"capacity"
+		],
+		lock: "update"
+	}))[0];
+	if (!p) throw new n({ roomId: "host" });
+	if (p.pool == null && p.clientCapacity == null) return;
+	if (typeof p.pool != "string" || !p.pool) return c();
+	let m = l(p.clientCapacity), h = l(p.capacity);
+	if (m < 1 || h < 1 || h > f) return c();
+	let g = await e.query({
+		table: r,
+		predicate: a(o("hostId", u), s(o("state", "live"), o("state", "creating"), o("state", "hibernating"))),
+		order: [{
+			column: "id",
+			direction: "asc"
+		}],
+		take: h + 1,
+		skip: void 0,
+		projection: ["clients"],
+		lock: "update"
+	});
+	if (g.length > h) return c();
+	let _ = m;
+	for (let e of g) {
+		let n = l(e.clients);
+		if (n > _) throw new t({ roomId: "host" });
+		_ -= n;
+	}
+	if (d > _) throw new t({ roomId: "host" });
+};
+//#endregion
+export { d as assertHostClientCapacity, u as lockRoomReservationOwners };

package/dist/hostCommandScope.js

@@ -0,0 +1,64 @@
+import { ProtocolError as e } from "./errors.js";
+import { AsyncLocalStorage as t } from "node:async_hooks";
+//#region src/hostCommandScope.ts
+var n = new t(), r = (e) => {
+	for (let t = n.getStore(); t; t = t.parent) if (t.owner === e) return !0;
+	return !1;
+}, i = () => n.getStore() !== void 0, a = (e, t) => {
+	let n = Promise.resolve().then(t);
+	return e.pending = n, n.then(() => {
+		e.pending === n && (e.pending = null);
+	}, (t) => {
+		e.failed = !0, e.failure = t, e.pending === n && (e.pending = null);
+	}), n;
+}, o = (t, i, o) => {
+	let s = n.getStore();
+	if (!s) return o();
+	if (r(t) || !s.active || s.pending || i) return Promise.reject(new e({ detail: "Host command cannot wait on an occupied, ancestral or expired control lane" }));
+	let c;
+	try {
+		c = o();
+	} catch (e) {
+		c = Promise.reject(e);
+	}
+	return a(s, () => c);
+}, s = (t, i) => {
+	let o = n.getStore();
+	if (o) return o.owner === t ? !o.active || o.pending ? Promise.reject(new e({ detail: "Host command operation scope is expired or already occupied" })) : a(o, () => o.dispatch ? o.dispatch(i) : i()) : r(t) ? Promise.reject(new e({ detail: "Host command cannot reenter an ancestral control lane" })) : void 0;
+}, c = async (e, t, r, i) => {
+	let a = {
+		owner: e,
+		parent: r,
+		dispatch: i,
+		active: !0,
+		pending: null,
+		failure: void 0,
+		failed: !1
+	};
+	return n.run(a, async () => {
+		try {
+			let e = await t();
+			if (a.active = !1, a.pending && await a.pending, a.failed) throw a.failure;
+			return e;
+		} finally {
+			a.active = !1, a.pending && await a.pending;
+		}
+	});
+}, l = async (t, i, a) => {
+	if (r(t)) throw new e({ detail: "Host command delivery cannot recursively deliver commands" });
+	return c(t, i, n.getStore(), a);
+}, u = (t) => {
+	let r = !0, i = Promise.resolve();
+	return Object.freeze({
+		run: (a) => {
+			if (!r) return Promise.reject(new e({ detail: "Host command World operation window is closed" }));
+			let o = n.getStore(), s = i.then(() => c(t, a, o));
+			return i = s.then(() => void 0, () => void 0), s;
+		},
+		close: async () => {
+			r = !1, await i;
+		}
+	});
+};
+//#endregion
+export { r as hasRoomHostCommandScope, i as insideRoomHostCommandScope, u as makeRoomHostCommandWindow, o as queueRoomHostCommandOperation, s as runRoomHostCommandOperation, l as withRoomHostCommandScope };