@voltro/plugin-saves 0.0.0-stage → 0.87.0

package/dist/contract.js

@@ -0,0 +1,79 @@
+import { SaveSummarySchema as e, savesError as t } from "./errors.js";
+import { Schema as n } from "effect";
+//#region src/contract.ts
+var r = "_voltro_saves", i = "_voltro_saves_history", a = "_voltro_saves_requests", o = "_voltro_saves_subjects", s = n.Number.pipe(n.check(n.isInt()), n.check(n.isBetween({
+	minimum: 0,
+	maximum: 2147483647
+}))), c = n.Number.pipe(n.check(n.isInt()), n.check(n.isBetween({
+	minimum: 0,
+	maximum: 864e13
+}))), l = n.Struct({
+	slot: n.String,
+	version: s,
+	schemaVersion: s,
+	byteLength: s,
+	checksum: n.String,
+	deviceId: n.String,
+	clientVersion: n.String,
+	savedAt: c,
+	summary: e,
+	deletedUntil: n.NullOr(c)
+}), u = n.Struct({
+	...l.fields,
+	bytes: n.Uint8ArrayFromBase64
+}), d = (e) => {
+	if (typeof e != "string" || e.length > 120 || !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(e)) throw t("invalid_input");
+	return e;
+}, f = (e, n = 0, r = 2147483647) => {
+	if (typeof e != "number" || !Number.isSafeInteger(e) || e < n || e > r) throw t("invalid_input");
+	return e;
+}, p = (e, n) => {
+	if (typeof e != "object" || !e || Array.isArray(e)) throw t("invalid_input");
+	let r = Object.getPrototypeOf(e);
+	if (r !== Object.prototype && r !== null) throw t("invalid_input");
+	let i = Object.create(null);
+	for (let r of Reflect.ownKeys(e)) {
+		let a = Object.getOwnPropertyDescriptor(e, r);
+		if (typeof r != "string" || !n.includes(r) || !a || !a.enumerable || !("value" in a)) throw t("invalid_input");
+		i[r] = a.value;
+	}
+	return Object.freeze(i);
+}, m = (r) => {
+	if (typeof r != "object" || !r || Array.isArray(r)) throw t("invalid_input");
+	let i = Reflect.ownKeys(r);
+	if (i.length > 32 || i.some((e) => typeof e != "string" || !/^[A-Za-z][A-Za-z0-9._-]{0,63}$/.test(e))) throw t("invalid_input");
+	let a = p(r, i);
+	for (let e of Object.values(a)) if (!(e === null || typeof e == "boolean" || typeof e == "string" && e.length <= 512 || typeof e == "number" && Number.isFinite(e))) throw t("invalid_input");
+	return Object.freeze(n.decodeUnknownSync(e)(a));
+}, h = (e, n) => {
+	let r = p(e, [
+		"slot",
+		"requestId",
+		"baseVersion",
+		"schemaVersion",
+		"bytes",
+		"deviceId",
+		"clientVersion",
+		"summary"
+	]);
+	if (!(r.bytes instanceof Uint8Array) || r.bytes.byteLength > n) throw t("limit_exceeded");
+	return Object.freeze({
+		slot: d(r.slot),
+		requestId: d(r.requestId),
+		baseVersion: f(r.baseVersion),
+		schemaVersion: f(r.schemaVersion, 1),
+		bytes: Uint8Array.from(r.bytes),
+		deviceId: d(r.deviceId),
+		clientVersion: d(r.clientVersion),
+		summary: m(r.summary)
+	});
+}, g = (e) => {
+	let n = structuredClone(e);
+	if (n.type !== "user") throw t("forbidden");
+	return Object.freeze({
+		tenantId: d(n.tenantId),
+		ownerId: d(n.id)
+	});
+};
+//#endregion
+export { i as SAVE_HISTORY_TABLE, a as SAVE_REQUEST_TABLE, o as SAVE_SUBJECT_TABLE, r as SAVE_TABLE, u as SaveDocumentSchema, l as SaveHeaderSchema, h as captureSavePut, p as saveData, d as saveId, f as saveInteger, g as saveOwner, m as saveSummary };

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+import { Schema } from 'effect';
+import { YieldableError } from 'effect/Cause';
+
+export declare class SaveConflict extends SaveConflict_base {
+}
+
+declare const SaveConflict_base: Schema.Class<SaveConflict, Schema.TaggedStruct<"SaveConflict", {
+    readonly serverVersion: Schema.Number;
+    readonly server: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.Null]>>;
+    readonly client: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.Null]>>;
+}>, YieldableError>;
+
+export declare type SaveError = SavesError | SaveConflict;
+
+export declare class SavesError extends SavesError_base {
+}
+
+export declare const savesError: (code: SavesError["code"]) => SavesError;
+
+declare const SavesError_base: Schema.Class<SavesError, Schema.TaggedStruct<"SavesError", {
+    readonly code: Schema.Literals<readonly ["invalid_input", "invalid_record", "forbidden", "not_found", "erased", "limit_exceeded", "invalid_save", "rate_limited", "unavailable", "request_conflict"]>;
+}>, YieldableError>;
+
+export declare const SaveSummarySchema: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.Null]>>;
+
+export { }

package/dist/errors.js

@@ -0,0 +1,25 @@
+import { Schema as e } from "effect";
+//#region src/errors.ts
+var t = e.Record(e.String, e.Union([
+	e.String,
+	e.Number,
+	e.Boolean,
+	e.Null
+])), n = class extends e.TaggedError()("SavesError", { code: e.Literals([
+	"invalid_input",
+	"invalid_record",
+	"forbidden",
+	"not_found",
+	"erased",
+	"limit_exceeded",
+	"invalid_save",
+	"rate_limited",
+	"unavailable",
+	"request_conflict"
+]) }) {}, r = class extends e.TaggedError()("SaveConflict", {
+	serverVersion: e.Number,
+	server: t,
+	client: t
+}) {}, i = (e) => new n({ code: e });
+//#endregion
+export { r as SaveConflict, t as SaveSummarySchema, n as SavesError, i as savesError };

package/dist/index.d.ts

@@ -0,0 +1,166 @@
+import { ConnectionRef } from '@voltro/kv/connection';
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { HotStoreShape } from '@voltro/kv/hot';
+import { PluginPrivacyTarget } from '@voltro/protocol';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { VoltroPlugin } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+export declare const captureSavesService: (input: SavesService) => SavesService;
+
+/** Opaque saves convey no Wallet, Inventory, ranked-result or Room-state authority. */
+export declare const defaultSaveValidator: SaveValidator;
+
+export declare const resolveSaveValidation: (context: SaveValidationContext, validator?: SaveValidator) => void;
+
+export declare class SaveConflict extends SaveConflict_base {
+}
+
+declare const SaveConflict_base: Schema.Class<SaveConflict, Schema.TaggedStruct<"SaveConflict", {
+    readonly serverVersion: Schema.Number;
+    readonly server: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.Null]>>;
+    readonly client: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.Null]>>;
+}>, YieldableError>;
+
+export declare interface SaveDeleteIntent {
+    readonly slot: string;
+    readonly requestId: string;
+    readonly baseVersion: number;
+}
+
+export 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>;
+}>;
+
+export declare type SaveError = SavesError | SaveConflict;
+
+export declare type SaveHeader = typeof SaveHeaderSchema.Type;
+
+declare const SaveHeaderSchema: Schema.Struct<{
+    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>;
+}>;
+
+export 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 SaveRollbackIntent {
+    readonly slot: string;
+    readonly requestId: string;
+    readonly baseVersion: number;
+    readonly version: number;
+}
+
+export declare class SavesError extends SavesError_base {
+}
+
+declare const SavesError_base: Schema.Class<SavesError, Schema.TaggedStruct<"SavesError", {
+    readonly code: Schema.Literals<readonly ["invalid_input", "invalid_record", "forbidden", "not_found", "erased", "limit_exceeded", "invalid_save", "rate_limited", "unavailable", "request_conflict"]>;
+}>, YieldableError>;
+
+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;
+}
+
+export declare interface SavesPlugin extends VoltroPlugin {
+    readonly saves: () => SavesService;
+}
+
+export declare const savesPlugin: (input: SavesPluginOptions) => SavesPlugin;
+
+export declare interface SavesPluginOptions extends SavesOptions {
+    readonly service?: SavesService;
+    /** Actual app-owned invalidation sources required by a complete replacement. */
+    readonly querySources?: readonly string[];
+    readonly connection?: ConnectionRef<'redis'>;
+    /** Private fixture or single-node app-owned HotStore; never disposed here. */
+    readonly hotStore?: HotStoreShape;
+}
+
+export declare class SavesPort extends SavesPort_base {
+}
+
+declare const SavesPort_base: Context.ServiceClass<SavesPort, "@voltro/SavesPort", SavesService>;
+
+export declare interface SavesService {
+    readonly get: (subject: Subject, slot: string) => Effect.Effect<SaveDocument | null, SaveError>;
+    readonly list: (subject: Subject) => Effect.Effect<readonly SaveHeader[], SaveError>;
+    readonly history: (subject: Subject, slot: string) => Effect.Effect<readonly SaveHeader[], SaveError>;
+    readonly put: (subject: Subject, intent: SavePutIntent) => Effect.Effect<SaveHeader, SaveError>;
+    readonly rollback: (subject: Subject, intent: SaveRollbackIntent) => Effect.Effect<SaveHeader, SaveError>;
+    readonly remove: (subject: Subject, intent: SaveDeleteIntent) => Effect.Effect<SaveHeader, SaveError>;
+    readonly exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, SaveError>;
+    readonly eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, SaveError>;
+}
+
+export declare const savesSystemContract: Readonly<{
+    slots: {
+        validator: {
+            defaultExport: string;
+            fixtureExport: string;
+        };
+    };
+    ports: {
+        saves: {
+            tagExport: string;
+            fakeLayerExport: string;
+            fixtureExport: string;
+        };
+    };
+    events: readonly string[];
+}>;
+
+export 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/index.js

@@ -0,0 +1,5 @@
+import { SaveConflict as e, SavesError as t } from "./errors.js";
+import { SavesPort as n, captureSavesService as r } from "./port.js";
+import { defaultSaveValidator as i, resolveSaveValidation as a } from "./strategies.js";
+import { savesPlugin as o, savesSystemContract as s } from "./plugin.js";
+export { e as SaveConflict, t as SavesError, n as SavesPort, r as captureSavesService, i as defaultSaveValidator, a as resolveSaveValidation, o as savesPlugin, s as savesSystemContract };

package/dist/inspect.d.ts

@@ -0,0 +1,82 @@
+import { Schema } from 'effect';
+
+declare const base: Schema.Struct<{
+    observedAt: Schema.Number;
+    bound: Schema.Boolean;
+    backend: Schema.Literals<readonly ["sql", "custom"]>;
+    gameId: Schema.String;
+    version: Schema.String;
+    slots: Schema.$Array<Schema.String>;
+    validator: Schema.Literals<readonly ["default", "custom", "app-owned"]>;
+    budgets: Schema.NullOr<Schema.Struct<{
+        readonly maxBytes: Schema.Number;
+        readonly historyVersions: Schema.Number;
+        readonly maxRequests: Schema.Number;
+        readonly deleteGraceMs: Schema.Number;
+        readonly writesPerMinute: Schema.Literal<10>;
+    }>>;
+    schemaVersion: Schema.NullOr<Schema.Number>;
+    rateActive: Schema.Boolean;
+    tables: Schema.$Array<Schema.Literals<readonly ["_voltro_saves", "_voltro_saves_history", "_voltro_saves_requests", "_voltro_saves_subjects"]>>;
+    offlineInstalled: Schema.Literal<false>;
+    signaturesInstalled: Schema.Literal<false>;
+    externalStorageInstalled: Schema.Literal<false>;
+    purgeInstalled: Schema.Literal<false>;
+    gmRollbackInstalled: Schema.Literal<false>;
+}>;
+
+export declare const isSavesStatusConsistent: (value: typeof base.Type) => boolean;
+
+export declare type SavesStatus = typeof SavesStatusSchema.Type;
+
+export declare const SavesStatusFields: {
+    observedAt: Schema.Number;
+    bound: Schema.Boolean;
+    backend: Schema.Literals<readonly ["sql", "custom"]>;
+    gameId: Schema.String;
+    version: Schema.String;
+    slots: Schema.$Array<Schema.String>;
+    validator: Schema.Literals<readonly ["default", "custom", "app-owned"]>;
+    budgets: Schema.NullOr<Schema.Struct<{
+        readonly maxBytes: Schema.Number;
+        readonly historyVersions: Schema.Number;
+        readonly maxRequests: Schema.Number;
+        readonly deleteGraceMs: Schema.Number;
+        readonly writesPerMinute: Schema.Literal<10>;
+    }>>;
+    schemaVersion: Schema.NullOr<Schema.Number>;
+    rateActive: Schema.Boolean;
+    tables: Schema.$Array<Schema.Literals<readonly ["_voltro_saves", "_voltro_saves_history", "_voltro_saves_requests", "_voltro_saves_subjects"]>>;
+    offlineInstalled: Schema.Literal<false>;
+    signaturesInstalled: Schema.Literal<false>;
+    externalStorageInstalled: Schema.Literal<false>;
+    purgeInstalled: Schema.Literal<false>;
+    gmRollbackInstalled: Schema.Literal<false>;
+};
+
+export declare const SavesStatusSchema: Schema.Struct<{
+    observedAt: Schema.Number;
+    bound: Schema.Boolean;
+    backend: Schema.Literals<readonly ["sql", "custom"]>;
+    gameId: Schema.String;
+    version: Schema.String;
+    slots: Schema.$Array<Schema.String>;
+    validator: Schema.Literals<readonly ["default", "custom", "app-owned"]>;
+    budgets: Schema.NullOr<Schema.Struct<{
+        readonly maxBytes: Schema.Number;
+        readonly historyVersions: Schema.Number;
+        readonly maxRequests: Schema.Number;
+        readonly deleteGraceMs: Schema.Number;
+        readonly writesPerMinute: Schema.Literal<10>;
+    }>>;
+    schemaVersion: Schema.NullOr<Schema.Number>;
+    rateActive: Schema.Boolean;
+    tables: Schema.$Array<Schema.Literals<readonly ["_voltro_saves", "_voltro_saves_history", "_voltro_saves_requests", "_voltro_saves_subjects"]>>;
+    offlineInstalled: Schema.Literal<false>;
+    signaturesInstalled: Schema.Literal<false>;
+    externalStorageInstalled: Schema.Literal<false>;
+    purgeInstalled: Schema.Literal<false>;
+    gmRollbackInstalled: Schema.Literal<false>;
+}>;
+
+export { }

package/dist/inspect.js

@@ -0,0 +1,49 @@
+import { SAVE_HISTORY_TABLE as e, SAVE_REQUEST_TABLE as t, SAVE_SUBJECT_TABLE as n, SAVE_TABLE as r } from "./contract.js";
+import { Schema as i } from "effect";
+//#region src/inspect.ts
+var a = (e, t) => i.Number.pipe(i.check(i.isInt()), i.check(i.isBetween({
+	minimum: e,
+	maximum: t
+}))), o = {
+	observedAt: a(0, 864e13),
+	bound: i.Boolean,
+	backend: i.Literals(["sql", "custom"]),
+	gameId: i.String,
+	version: i.String,
+	slots: i.Array(i.String),
+	validator: i.Literals([
+		"default",
+		"custom",
+		"app-owned"
+	]),
+	budgets: i.NullOr(i.Struct({
+		maxBytes: a(1, 1048576),
+		historyVersions: a(1, 100),
+		maxRequests: a(1, 1e5),
+		deleteGraceMs: a(0, 31536e6),
+		writesPerMinute: i.Literal(10)
+	})),
+	schemaVersion: i.NullOr(a(1, 2147483647)),
+	rateActive: i.Boolean,
+	tables: i.Array(i.Literals([
+		r,
+		e,
+		t,
+		n
+	])),
+	offlineInstalled: i.Literal(!1),
+	signaturesInstalled: i.Literal(!1),
+	externalStorageInstalled: i.Literal(!1),
+	purgeInstalled: i.Literal(!1),
+	gmRollbackInstalled: i.Literal(!1)
+}, s = i.Struct(o), c = (e) => {
+	let t = (e) => /^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/.test(e);
+	return !t(e.gameId) || !t(e.version) || e.slots.length < 1 || e.slots.length > 64 || new Set(e.slots).size !== e.slots.length || !e.slots.every(t) || e.rateActive && !e.bound ? !1 : e.backend === "custom" ? e.validator === "app-owned" && e.budgets === null && e.schemaVersion === null && e.tables.length === 0 && !e.rateActive && e.version !== "default.v1" : e.validator !== "app-owned" && e.budgets !== null && JSON.stringify(e.tables) === JSON.stringify([
+		"_voltro_saves",
+		"_voltro_saves_history",
+		"_voltro_saves_requests",
+		"_voltro_saves_subjects"
+	]);
+}, l = s.pipe(i.check(i.makeFilter(c)));
+//#endregion
+export { o as SavesStatusFields, l as SavesStatusSchema, c as isSavesStatusConsistent };