@voltro/plugin-saves 0.0.0-stage → 0.88.0

package/dist/service.server.js

@@ -0,0 +1,412 @@
+import { SaveConflict as e, SavesError as t, savesError as n } from "./errors.js";
+import { SaveHeaderSchema as r, captureSavePut as i, saveData as a, saveId as o, saveInteger as s, saveOwner as c, saveSummary as l } from "./contract.js";
+import { resolveSaveValidation as u, resolveSavesOptions as d } from "./strategies.js";
+import { savesHistoryTable as f, savesRequestsTable as p, savesSubjectsTable as m, savesTable as h } from "./tables.entity.js";
+import { Effect as g, Result as _, Schema as v } from "effect";
+import { createHash as y } from "node:crypto";
+import { and as b, eq as x, queryFor as S } from "@voltro/database";
+// src/service.server.ts
+var C = (e) => Array.isArray(e) ? e.map(C) : e && typeof e == "object" ? Object.fromEntries(Object.keys(e).sort().map((t) => [t, C(e[t])])) : e, w = (e) => y("sha256").update(JSON.stringify(C(e))).digest("hex"), T = (e) => y("sha256").update(e).digest("hex"), E = (e, ...t) => e + w(t).slice(0, 48), D = (r) => r instanceof t || r instanceof e ? r : n("unavailable"), O = (e) => g.tryPromise({
+	try: e,
+	catch: D
+}), k = (e) => {
+	let t = e instanceof Date ? e.getTime() : typeof e == "string" ? Date.parse(e) : e;
+	try {
+		return s(t, 0, 864e13);
+	} catch {
+		throw n("invalid_record");
+	}
+}, A = (e) => {
+	try {
+		let t = v.decodeUnknownSync(r)({
+			slot: e.slot,
+			version: e.version,
+			schemaVersion: e.schemaVersion,
+			byteLength: e.byteLength,
+			checksum: e.checksum,
+			deviceId: e.deviceId,
+			clientVersion: e.clientVersion,
+			savedAt: k(e.savedAt),
+			summary: e.summary,
+			deletedUntil: e.deletedUntil === null ? null : k(e.deletedUntil)
+		});
+		if (t.version < 1 || t.schemaVersion < 1 || t.byteLength > 1048576 || !/^[a-f0-9]{64}$/.test(t.checksum)) throw n("invalid_record");
+		return o(t.slot), o(t.deviceId), o(t.clientVersion), Object.freeze({
+			...t,
+			summary: l(t.summary)
+		});
+	} catch {
+		throw n("invalid_record");
+	}
+}, j = (e) => {
+	let t = A(e);
+	if (!(e.bytes instanceof Uint8Array) || e.bytes.byteLength !== t.byteLength || T(e.bytes) !== t.checksum) throw n("invalid_record");
+	return Object.freeze({
+		...t,
+		bytes: Uint8Array.from(e.bytes)
+	});
+}, M = [
+	"id",
+	"tenantId",
+	"gameId",
+	"ownerId",
+	"ownerKey",
+	"slot",
+	"version",
+	"schemaVersion",
+	"byteLength",
+	"checksum",
+	"deviceId",
+	"clientVersion",
+	"savedAt",
+	"summary",
+	"deletedUntil"
+], N = (l, y, C = () => {}) => {
+	let k = a(y, [
+		"gameId",
+		"slots",
+		"maxBytes",
+		"historyVersions",
+		"maxRequests",
+		"deleteGraceMs",
+		"version",
+		"validator",
+		"schema",
+		"schemaVersion",
+		"now",
+		"admitWrite"
+	]), N = k.admitWrite, P = Object.fromEntries(Object.entries(k).filter(([e]) => e !== "admitWrite")), F = d(P);
+	if (typeof N != "function" || typeof C != "function") throw n("invalid_input");
+	let I = (e) => E("svs_", e.tenantId, F.gameId, e.ownerId), L = (e, t) => E("sv_", I(e), t), R = (e, t, n) => E("svh_", I(e), t, n), z = (e) => b(x("tenantId", e.tenantId), x("gameId", F.gameId), x("ownerKey", I(e)), x("ownerId", e.ownerId)), B = (e, t) => {
+		if (e.tenantId !== t.tenantId || e.gameId !== F.gameId || e.ownerId !== t.ownerId || e.ownerKey !== I(t)) throw n("invalid_record");
+	}, V = (e) => {
+		let t = o(e);
+		if (!F.slots.includes(t)) throw n("not_found");
+		return t;
+	}, H = () => (C(), s(F.now(), 0, 864e13)), U = async (e) => {
+		C(), await l.insertIgnore(m.tableName, {
+			id: I(e),
+			tenantId: e.tenantId,
+			gameId: F.gameId,
+			ownerId: e.ownerId,
+			erased: !1,
+			admission: 0
+		}, { conflictColumns: ["id"] });
+	}, W = async (e, t, r = !1, i = !1) => {
+		if (C(), r && await e.updateMany(m.tableName, { admission: 0 }, { where: x("id", I(t)) }) !== 1) throw n("unavailable");
+		let a = (await e.query(S(m).where(x("id", I(t))).limit(1).descriptor))[0];
+		if (!a) return null;
+		if (a.id !== I(t) || a.tenantId !== t.tenantId || a.gameId !== F.gameId || a.admission !== 0 || typeof a.erased != "boolean") throw n("invalid_record");
+		if (a.erased) {
+			if (i && a.ownerId === null) return a;
+			throw n("erased");
+		}
+		if (a.ownerId !== t.ownerId) throw n("invalid_record");
+		return a;
+	}, G = async (e, t, r) => {
+		let i = (await e.query(S(h).where(x("id", L(t, r))).limit(1).descriptor))[0];
+		if (!i) return null;
+		if (B(i, t), i.slot !== r || i.id !== L(t, r)) throw n("invalid_record");
+		return i;
+	}, K = async (e, t, r, i) => {
+		let a = (await e.query(S(f).where(x("id", R(t, r, i))).limit(1).descriptor))[0];
+		if (!a) throw n("not_found");
+		if (B(a, t), a.slot !== r || a.version !== i) throw n("invalid_record");
+		return j(a);
+	}, q = async (e, t, i, a) => {
+		let o = (await e.query(S(p).where(x("id", i)).limit(1).descriptor))[0];
+		if (!o) return null;
+		if (B(o, t), o.digest !== a) throw n("request_conflict");
+		try {
+			return Object.freeze(v.decodeUnknownSync(r)(o.receipt));
+		} catch {
+			throw n("invalid_record");
+		}
+	}, J = async (e, t, r, i) => {
+		let a = await e.query(S(r).select(...M).where(z(t)).orderBy("id", "asc").limit(i + 1).descriptor);
+		if (a.length > i) throw n("limit_exceeded");
+		for (let e of a) B(e, t), A(e);
+		return a;
+	}, Y = (e, r) => {
+		let i = null;
+		if (F.schema) {
+			if (r.schemaVersion !== F.schemaVersion) throw n("invalid_save");
+			try {
+				i = v.decodeUnknownSync(v.toType(F.schema))(JSON.parse(new TextDecoder("utf-8", { fatal: !0 }).decode(r.bytes)));
+			} catch {
+				throw n("invalid_save");
+			}
+		}
+		try {
+			u(Object.freeze({
+				previous: e === null ? null : structuredClone(e),
+				proposed: structuredClone(r),
+				decoded: i
+			}), F.validator);
+		} catch (e) {
+			throw e instanceof t ? e : n("invalid_save");
+		}
+	}, X = (t, r, i) => O(async () => {
+		let a = w([r.kind, r.intent]), o = E("svr_", I(t), r.requestId);
+		await U(t);
+		let c = await l.transactional(async (n) => {
+			await W(n, t, !0);
+			let i = await q(n, t, o, a);
+			if (i) return { accepted: i };
+			let s = await G(n, t, r.slot), c = s ? j(s) : null;
+			if ((c?.version ?? 0) !== r.baseVersion) throw new e({
+				serverVersion: c?.version ?? 0,
+				server: c?.summary ?? {},
+				client: r.summary
+			});
+			return { previous: c };
+		});
+		if ("accepted" in c) return c.accepted;
+		let u = H(), d = await g.runPromise(g.result(N(I(t), u)));
+		if (_.isFailure(d)) throw d.failure;
+		let m = await i(l, c.previous, u);
+		return r.kind !== "remove" && Y(c.previous, m), C(), l.transactional(async (i) => {
+			await W(i, t, !0);
+			let l = await q(i, t, o, a);
+			if (l) return l;
+			let d = await G(i, t, r.slot), g = d ? j(d) : null;
+			if ((g?.version ?? 0) !== r.baseVersion) throw new e({
+				serverVersion: g?.version ?? 0,
+				server: g?.summary ?? {},
+				client: r.summary
+			});
+			if (g && c.previous && (g.checksum !== c.previous.checksum || g.deletedUntil !== c.previous.deletedUntil)) throw n("request_conflict");
+			if (r.kind === "rollback") {
+				let e = s(r.intent.version, 1);
+				if ((await K(i, t, r.slot, e)).checksum !== T(m.bytes)) throw n("request_conflict");
+			}
+			if ((await i.query(S(p).select("id").where(z(t)).limit(F.maxRequests + 1).descriptor)).length >= F.maxRequests) throw n("limit_exceeded");
+			let _ = s(r.baseVersion + 1, 1), v = r.kind === "remove" ? s(u + F.deleteGraceMs, 0, 864e13) : null, y = Object.freeze({
+				slot: r.slot,
+				version: _,
+				schemaVersion: m.schemaVersion,
+				byteLength: m.bytes.byteLength,
+				checksum: T(m.bytes),
+				deviceId: m.deviceId,
+				clientVersion: m.clientVersion,
+				savedAt: u,
+				summary: Object.freeze({ ...m.summary }),
+				deletedUntil: v
+			}), w = {
+				tenantId: t.tenantId,
+				gameId: F.gameId,
+				ownerId: t.ownerId,
+				ownerKey: I(t),
+				...y,
+				bytes: Uint8Array.from(m.bytes),
+				savedAt: new Date(u),
+				deletedUntil: v === null ? null : new Date(v)
+			};
+			d ? await i.updateMany(h.tableName, w, { where: x("id", L(t, r.slot)) }) : await i.insert(h.tableName, {
+				id: L(t, r.slot),
+				...w
+			}), await i.insert(f.tableName, {
+				id: R(t, r.slot, _),
+				...w
+			});
+			let E = await i.query(S(f).select("id", "version").where(b(z(t), x("slot", r.slot))).orderBy("version", "desc").limit(102).descriptor);
+			if (E.length > 101) throw n("invalid_record");
+			for (let e of E.slice(F.historyVersions)) await i.deleteMany(f.tableName, { where: x("id", e.id) });
+			return await i.insert(p.tableName, {
+				id: o,
+				tenantId: t.tenantId,
+				gameId: F.gameId,
+				ownerId: t.ownerId,
+				ownerKey: I(t),
+				digest: a,
+				receipt: y
+			}), C(), y;
+		});
+	}), Z = (e) => {
+		let t = a(e, [
+			"subjectId",
+			"tenantId",
+			"kind"
+		]);
+		if (t.kind !== "user" && t.kind !== "guest") throw n("invalid_input");
+		return {
+			tenantId: o(t.tenantId),
+			ownerId: o(t.subjectId)
+		};
+	}, Q = (e, t) => {
+		try {
+			return t(e());
+		} catch (e) {
+			return g.fail(D(e));
+		}
+	};
+	return Object.freeze({
+		get: (e, t) => {
+			try {
+				let n = c(e), r = V(t);
+				return O(() => l.transactional(async (e) => {
+					if (!await W(e, n)) return null;
+					let t = await G(e, n, r);
+					if (!t) return null;
+					let i = j(t);
+					return i.deletedUntil === null ? i : null;
+				}));
+			} catch (e) {
+				return g.fail(D(e));
+			}
+		},
+		list: (e) => {
+			try {
+				let t = c(e);
+				return O(() => l.transactional(async (e) => await W(e, t) ? (await J(e, t, h, 64)).map(A).filter((e) => e.deletedUntil === null) : []));
+			} catch (e) {
+				return g.fail(D(e));
+			}
+		},
+		history: (e, t) => {
+			try {
+				let n = c(e), r = V(t);
+				return O(() => l.transactional(async (e) => await W(e, n) ? (await J(e, n, f, 6400)).filter((e) => e.slot === r).map(A).sort((e, t) => t.version - e.version) : []));
+			} catch (e) {
+				return g.fail(D(e));
+			}
+		},
+		put: (e, t) => {
+			try {
+				let n = c(e), r = i(t, F.maxBytes);
+				V(r.slot);
+				let a = {
+					...r,
+					bytes: T(r.bytes)
+				};
+				return X(n, {
+					kind: "put",
+					...r,
+					intent: a
+				}, async () => r);
+			} catch (e) {
+				return g.fail(D(e));
+			}
+		},
+		rollback: (e, t) => {
+			try {
+				let r = c(e), l = a(t, [
+					"slot",
+					"requestId",
+					"baseVersion",
+					"version"
+				]), u = {
+					slot: V(l.slot),
+					requestId: o(l.requestId),
+					baseVersion: s(l.baseVersion),
+					version: s(l.version, 1)
+				};
+				return X(r, {
+					kind: "rollback",
+					...u,
+					summary: {},
+					intent: u
+				}, async (e, t, a) => {
+					if (!t || t.deletedUntil !== null && t.deletedUntil <= a) throw n("not_found");
+					let o = await K(e, r, u.slot, u.version);
+					return i({
+						slot: u.slot,
+						requestId: u.requestId,
+						baseVersion: u.baseVersion,
+						schemaVersion: o.schemaVersion,
+						bytes: o.bytes,
+						deviceId: o.deviceId,
+						clientVersion: o.clientVersion,
+						summary: o.summary
+					}, F.maxBytes);
+				});
+			} catch (e) {
+				return g.fail(D(e));
+			}
+		},
+		remove: (e, t) => {
+			try {
+				let r = c(e), i = a(t, [
+					"slot",
+					"requestId",
+					"baseVersion"
+				]), l = {
+					slot: V(i.slot),
+					requestId: o(i.requestId),
+					baseVersion: s(i.baseVersion)
+				};
+				return X(r, {
+					kind: "remove",
+					...l,
+					summary: {},
+					intent: l
+				}, async (e, t) => {
+					if (!t || t.deletedUntil !== null) throw n("not_found");
+					return {
+						...l,
+						schemaVersion: t.schemaVersion,
+						bytes: t.bytes,
+						deviceId: t.deviceId,
+						clientVersion: t.clientVersion,
+						summary: t.summary
+					};
+				});
+			} catch (e) {
+				return g.fail(D(e));
+			}
+		},
+		exportSubject: (e) => Q(() => Z(e), (e) => O(() => l.transactional(async (t) => {
+			let r = await W(t, e, !1, !0);
+			if (!r || r.erased) return {
+				saves: [],
+				history: []
+			};
+			let i = await J(t, e, h, 64), a = await J(t, e, f, 6400);
+			if ([...i, ...a].reduce((e, t) => e + A(t).byteLength, 0) > 67108864) throw n("limit_exceeded");
+			let o = async (r, i) => {
+				let a = [];
+				for (let o of i) {
+					let i = (await t.query(S(r).where(x("id", o.id)).limit(1).descriptor))[0];
+					if (!i) throw n("invalid_record");
+					B(i, e);
+					let s = j(i);
+					a.push({
+						...s,
+						bytes: Buffer.from(s.bytes).toString("base64")
+					});
+				}
+				return a;
+			};
+			return {
+				saves: await o(h, i),
+				history: await o(f, a)
+			};
+		}))),
+		eraseSubject: (e) => {
+			try {
+				let t = Z(e);
+				return O(async () => {
+					await U(t), await l.transactional(async (e) => {
+						await W(e, t, !0, !0);
+						for (let [r, i] of [
+							[h, 64],
+							[f, 6400],
+							[p, 1e5]
+						]) {
+							let a = await e.query(S(r).select("id", "tenantId", "gameId", "ownerId", "ownerKey").where(z(t)).limit(i + 1).descriptor);
+							if (a.length > i) throw n("limit_exceeded");
+							for (let n of a) B(n, t), await e.deleteMany(r.tableName, { where: x("id", n.id) });
+						}
+						await e.updateMany(m.tableName, {
+							erased: !0,
+							ownerId: null
+						}, { where: x("id", I(t)) }), C();
+					});
+				});
+			} catch (e) {
+				return g.fail(D(e));
+			}
+		}
+	});
+};
+export { N as dataStoreSaves };

package/dist/strategies.d.ts

@@ -0,0 +1,76 @@
+import { Schema } from 'effect';
+
+/** Opaque saves convey no Wallet, Inventory, ranked-result or Room-state authority. */
+export declare const defaultSaveValidator: SaveValidator;
+
+export declare const resolveSavesOptions: (input: SavesOptions) => Readonly<{
+    gameId: string;
+    slots: readonly string[];
+    maxBytes: number;
+    historyVersions: number;
+    maxRequests: number;
+    deleteGraceMs: number;
+    version: string;
+    validator: SaveValidator;
+    now: () => number;
+    schema: Schema.Top | undefined;
+    schemaVersion: number | null;
+}>;
+
+export declare const resolveSaveValidation: (context: SaveValidationContext, validator?: SaveValidator) => void;
+
+declare type SaveDocument = typeof SaveDocumentSchema.Type;
+
+declare const SaveDocumentSchema: Schema.Struct<{
+    readonly bytes: Schema.Uint8ArrayFromBase64;
+    readonly slot: Schema.String;
+    readonly version: Schema.Number;
+    readonly schemaVersion: Schema.Number;
+    readonly byteLength: Schema.Number;
+    readonly checksum: Schema.String;
+    readonly deviceId: Schema.String;
+    readonly clientVersion: Schema.String;
+    readonly savedAt: Schema.Number;
+    readonly summary: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.Null]>>;
+    readonly deletedUntil: Schema.NullOr<Schema.Number>;
+}>;
+
+declare interface SavePutIntent {
+    readonly slot: string;
+    readonly requestId: string;
+    readonly baseVersion: number;
+    readonly schemaVersion: number;
+    readonly bytes: Uint8Array;
+    readonly deviceId: string;
+    readonly clientVersion: string;
+    readonly summary: SaveSummary;
+}
+
+export declare interface SavesOptions {
+    /** Server configuration, never a game/owner selector from the player. */
+    readonly gameId: string;
+    readonly slots?: readonly string[];
+    readonly maxBytes?: number;
+    readonly historyVersions?: number;
+    readonly maxRequests?: number;
+    readonly deleteGraceMs?: number;
+    readonly version?: string;
+    readonly validator?: SaveValidator;
+    readonly schema?: Schema.Top | undefined;
+    readonly schemaVersion?: number | undefined;
+    readonly now?: (() => number) | undefined;
+}
+
+declare type SaveSummary = typeof SaveSummarySchema.Type;
+
+declare const SaveSummarySchema: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.Null]>>;
+
+export declare interface SaveValidationContext {
+    readonly previous: SaveDocument | null;
+    readonly proposed: SavePutIntent;
+    readonly decoded: unknown;
+}
+
+export declare type SaveValidator = (context: SaveValidationContext) => boolean;
+
+export { }

package/dist/strategies.js

@@ -0,0 +1,47 @@
+import { savesError as e } from "./errors.js";
+import { saveData as t, saveId as n, saveInteger as r } from "./contract.js";
+import { Schema as i } from "effect";
+// src/strategies.ts
+var a = () => !0, o = (t, n = a) => {
+	if (typeof n != "function" || n(t) !== !0) throw e("invalid_save");
+}, s = (o) => {
+	let s = t(o, [
+		"gameId",
+		"slots",
+		"maxBytes",
+		"historyVersions",
+		"maxRequests",
+		"deleteGraceMs",
+		"version",
+		"validator",
+		"schema",
+		"schemaVersion",
+		"now"
+	]), c = s.slots ?? ["main"];
+	if (!Array.isArray(c) || c.length < 1 || c.length > 64 || Reflect.ownKeys(c).length !== c.length + 1) throw e("invalid_input");
+	let l = [];
+	for (let t = 0; t < c.length; t++) {
+		let r = Object.getOwnPropertyDescriptor(c, String(t));
+		if (!r || !("value" in r)) throw e("invalid_input");
+		l.push(n(r.value));
+	}
+	if (new Set(l).size !== l.length) throw e("invalid_input");
+	let u = s.validator ?? a, d = s.now ?? Date.now, f = n(s.version ?? "default.v1");
+	if (typeof u != "function" || typeof d != "function" || u !== a && f === "default.v1" || s.schema !== void 0 && !i.isSchema(s.schema)) throw e("invalid_input");
+	let p = s.schema === void 0 ? null : r(s.schemaVersion, 1);
+	if (s.schema === void 0 && s.schemaVersion !== void 0) throw e("invalid_input");
+	return Object.freeze({
+		gameId: n(s.gameId),
+		slots: Object.freeze(l),
+		maxBytes: r(s.maxBytes ?? 1048576, 1, 1048576),
+		historyVersions: r(s.historyVersions ?? 5, 1, 100),
+		maxRequests: r(s.maxRequests ?? 1e4, 1, 1e5),
+		deleteGraceMs: r(s.deleteGraceMs ?? 6048e5, 0, 31536e6),
+		version: f,
+		validator: u,
+		now: d,
+		schema: s.schema,
+		schemaVersion: p
+	});
+};
+export { a as defaultSaveValidator, o as resolveSaveValidation, s as resolveSavesOptions };

package/dist/tables.entity.js

@@ -0,0 +1,60 @@
+import { SAVE_HISTORY_TABLE as e, SAVE_REQUEST_TABLE as t, SAVE_SUBJECT_TABLE as n, SAVE_TABLE as r } from "./contract.js";
+import { boolean as i, bytes as a, id as o, integer as s, json as c, table as l, text as u, timestamp as d } from "@voltro/database";
+// src/tables.entity.ts
+var f = () => ({
+	tenantId: u().maxLength(120).externalId().sensitive("pii"),
+	gameId: u().maxLength(120).serverOnly(),
+	ownerId: u().maxLength(120).externalId().sensitive("pii"),
+	ownerKey: u().maxLength(64).serverOnly()
+}), p = () => ({
+	slot: u().maxLength(120).safe(),
+	version: s().safe(),
+	schemaVersion: s().safe(),
+	bytes: a().sensitive("pii"),
+	byteLength: s().safe(),
+	checksum: u().maxLength(64).safe(),
+	deviceId: u().maxLength(120).sensitive("pii"),
+	clientVersion: u().maxLength(120).safe(),
+	savedAt: d().safe(),
+	summary: c().sensitive("pii"),
+	deletedUntil: d().nullable().serverOnly()
+}), m = l(r, {
+	id: o({ prefix: "sv" }),
+	...f(),
+	...p()
+}).index([
+	"tenantId",
+	"gameId",
+	"ownerId",
+	"slot"
+]), h = l(e, {
+	id: o({ prefix: "svh" }),
+	...f(),
+	...p()
+}).index([
+	"ownerKey",
+	"slot",
+	"version"
+]), g = l(t, {
+	id: o({ prefix: "svr" }),
+	...f(),
+	digest: u().maxLength(64).serverOnly(),
+	receipt: c().sensitive("pii")
+}).index(["ownerKey"]), _ = l(n, {
+	id: o({ prefix: "svs" }),
+	tenantId: u().maxLength(120).externalId().sensitive("pii"),
+	gameId: u().maxLength(120).serverOnly(),
+	ownerId: u().maxLength(120).nullable().externalId().sensitive("pii"),
+	erased: i().serverOnly(),
+	admission: s().serverOnly()
+}).index([
+	"tenantId",
+	"gameId",
+	"ownerId"
+]), v = [
+	m,
+	h,
+	g,
+	_
+];
+export { h as savesHistoryTable, g as savesRequestsTable, _ as savesSubjectsTable, m as savesTable, v as savesTables };