@underpostnet/cyberia 3.3.73 → 3.3.77

package/src/api/cyberia-skill/cyberia-skill.model.js

@@ -2,9 +2,8 @@ import { Schema, model } from 'mongoose';
 
 // https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
 
-// Expanded metadata for one logic event a trigger item can fire. Mirrors the
-// `skills[]` entries in DefaultSkillConfig (cyberia-server-defaults.js) and the
-// SkillDefinition consumed by cyberia-server (game/skill.go).
+// Expanded metadata for one logic event a trigger item can fire. Same shape as
+// the `skills[]` entries of DefaultSkillConfig (cyberia-server-defaults.js).
 const SkillDefinitionSchema = new Schema(
   {
     // Handler key dispatched by the simulation skill engine (e.g. 'projectile',
@@ -20,9 +19,10 @@ const SkillDefinitionSchema = new Schema(
 );
 
 /**
- * Authoritative skill definition for a single trigger item. Owns the full skill
- * record (logic event keys + expanded metadata) so the simulation receives the
- * summoned-entity item ids the instance-conf skillConfig schema does not carry.
+ * Authoritative skill definition for a single trigger item. Owns the full skill record — logic
+ * event keys plus the expanded metadata, including the summoned-entity item ids the simulation
+ * needs. The collection is deployment-wide: which of these an instance runs is derived from the
+ * content that instance names, never stored on it. See cyberia-instance-items.js.
  */
 const CyberiaSkillSchema = new Schema(
   {

package/src/api/file/file.ref.js

@@ -0,0 +1,153 @@
+/**
+ * The File reference registry: which model fields hold a File `_id`.
+ *
+ * `file.ref.json` is the single source of that mapping — the orphan sweep in
+ * `underpost db --clean-fs` reads it, and so does every writer that deletes a
+ * document and has to take the blobs it owned with it. Reading it here rather
+ * than restating the fields at each call site is what keeps a newly added
+ * reference field from being cleaned up in one place and leaked in another.
+ *
+ * @module src/api/file/file.ref.js
+ * @namespace FileReferenceRegistry
+ */
+
+import fs from 'fs-extra';
+import { fileURLToPath } from 'node:url';
+
+// Resolved from this module rather than the working directory: the CLI, the
+// server and the test runner each start somewhere different.
+const REGISTRY_PATH = fileURLToPath(new URL('./file.ref.json', import.meta.url));
+
+let registry = null;
+
+/**
+ * @method fileRefRegistry
+ * @description The parsed registry, read once per process.
+ * @returns {Array<{api: string, model: Object}>} Registry entries.
+ * @memberof FileReferenceRegistry
+ */
+const fileRefRegistry = () => (registry ??= JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf8')));
+
+/**
+ * @method fileRefApis
+ * @description Every api that references File.
+ * @returns {string[]} Api names.
+ * @memberof FileReferenceRegistry
+ */
+const fileRefApis = () => fileRefRegistry().map((entry) => entry.api);
+
+/**
+ * @method fileRefFields
+ * @description The File-referencing fields of one api, as dot paths.
+ * @param {string} api - Api name, as registered.
+ * @returns {string[]} Field paths, empty for an api that references no File.
+ * @memberof FileReferenceRegistry
+ */
+const fileRefFields = (api) => {
+  const walk = (node, prefix) =>
+    Object.entries(node ?? {}).flatMap(([field, value]) => {
+      const path = prefix ? `${prefix}.${field}` : field;
+      if (value === true) return [path];
+      return value && typeof value === 'object' ? walk(value, path) : [];
+    });
+  return walk(fileRefRegistry().find((entry) => entry.api === api)?.model, '');
+};
+
+/**
+ * @method documentFileIds
+ * @description Collects the File ids a set of documents holds, as strings.
+ * @param {Array<Object>} docs - Documents, lean or hydrated.
+ * @param {string[]} fields - Field paths to read, as {@link fileRefFields} returns them.
+ * @returns {string[]} Unique ids.
+ * @memberof FileReferenceRegistry
+ */
+const documentFileIds = (docs, fields) => {
+  const ids = new Set();
+  const read = (doc, path) => path.split('.').reduce((value, part) => value?.[part], doc);
+  for (const doc of docs ?? []) {
+    for (const field of fields) {
+      const value = read(doc, field);
+      if (!value) continue;
+      if (Array.isArray(value)) value.forEach((entry) => entry && ids.add(String(entry)));
+      else ids.add(String(value));
+    }
+  }
+  return [...ids];
+};
+
+/**
+ * @method deleteOwnedFiles
+ * @description Deletes the File documents an owner collection no longer points at.
+ *
+ * An id still held by a surviving owner document is kept: renders are content
+ * addressed, so two documents describing the same item resolve to the same File
+ * id, and dropping one of them must not blind the other.
+ * @param {Object} params
+ * @param {import('mongoose').Model} params.File - File model.
+ * @param {import('mongoose').Model} params.Owner - The collection that owns these ids.
+ * @param {string[]} params.fields - Owner fields holding File ids.
+ * @param {Array<*>} params.ids - Candidate ids, as read before the owners were deleted.
+ * @returns {Promise<number>} How many File documents were removed.
+ * @memberof FileReferenceRegistry
+ */
+const deleteOwnedFiles = async ({ File, Owner, fields, ids }) => {
+  const candidates = [...new Set((ids ?? []).filter(Boolean).map(String))];
+  if (candidates.length === 0) return 0;
+
+  const held = new Set();
+  if (Owner && fields?.length) {
+    const survivors = await Owner.find(
+      { $or: fields.map((field) => ({ [field]: { $in: candidates } })) },
+      Object.fromEntries(fields.map((field) => [field, 1])),
+    ).lean();
+    for (const id of documentFileIds(survivors, fields)) held.add(id);
+  }
+
+  const removable = candidates.filter((id) => !held.has(id));
+  if (removable.length === 0) return 0;
+  const { deletedCount } = await File.deleteMany({ _id: { $in: removable } });
+  return deletedCount ?? 0;
+};
+
+/**
+ * @method deleteUnreferencedFiles
+ * @description Deletes the candidates no registered model references any more.
+ *
+ * Refuses to delete anything while a registered api has no model in this
+ * connection: an unreadable collection cannot be shown to hold no reference,
+ * and a sweep that assumed otherwise would delete a live blob of another domain.
+ * @param {Object} params
+ * @param {import('mongoose').Model} params.File - File model.
+ * @param {Array<*>} params.ids - Candidate ids.
+ * @param {function(string): import('mongoose').Model} params.getModel - Resolves an api to its model, throwing when it is not loaded.
+ * @returns {Promise<{removed: number, candidates: number, skipped: string}>} `skipped` names the api that could not be read, or is empty.
+ * @memberof FileReferenceRegistry
+ */
+const deleteUnreferencedFiles = async ({ File, ids, getModel }) => {
+  const candidates = [...new Set((ids ?? []).filter(Boolean).map(String))];
+  if (candidates.length === 0) return { removed: 0, candidates: 0, skipped: '' };
+
+  const referenced = new Set();
+  for (const api of fileRefApis()) {
+    const fields = fileRefFields(api);
+    if (fields.length === 0) continue;
+    let Model;
+    try {
+      Model = getModel(api);
+    } catch {
+      return { removed: 0, candidates: candidates.length, skipped: api };
+    }
+    const docs = await Model.find(
+      { $or: fields.map((field) => ({ [field]: { $in: candidates } })) },
+      Object.fromEntries(fields.map((field) => [field, 1])),
+    ).lean();
+    for (const id of documentFileIds(docs, fields)) referenced.add(id);
+  }
+
+  const removable = candidates.filter((id) => !referenced.has(id));
+  if (removable.length === 0) return { removed: 0, candidates: candidates.length, skipped: '' };
+  const { deletedCount } = await File.deleteMany({ _id: { $in: removable } });
+  return { removed: deletedCount ?? 0, candidates: candidates.length, skipped: '' };
+};
+
+export { fileRefRegistry, fileRefApis, fileRefFields, documentFileIds, deleteOwnedFiles, deleteUnreferencedFiles };

package/src/api/file/file.ref.json

@@ -2,7 +2,9 @@
   {
     "api": "atlas-sprite-sheet",
     "model": {
-      "fileId": true
+      "fileId": true,
+      "minifyFileId": true,
+      "idlePreviewFileId": true
     }
   },
   {
@@ -11,6 +13,12 @@
       "logo": true
     }
   },
+  {
+    "api": "cyberia-audio",
+    "model": {
+      "fileId": true
+    }
+  },
   {
     "api": "cyberia-instance",
     "model": {
@@ -20,7 +28,8 @@
   {
     "api": "cyberia-map",
     "model": {
-      "thumbnail": true
+      "thumbnail": true,
+      "preview": true
     }
   },
   {

package/src/api/object-layer/object-layer.model.js

@@ -4,8 +4,10 @@
  * @namespace CyberiaObjectLayerModel
  */
 import crypto from 'crypto';
+import { STAT_TYPES, STAT_DEFAULT, STAT_MODIFIER_MIN, STAT_MODIFIER_MAX, STAT_CONTRACT_VERSION, validateStats } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 import stringify from 'fast-json-stable-stringify';
 import { Schema, model } from 'mongoose';
+import { deleteOwnedFiles, documentFileIds, fileRefFields } from '../file/file.ref.js';
 /**
  * @typedef {Object} Stats
  * @property {number} effect - The effect attribute value
@@ -17,15 +19,11 @@ import { Schema, model } from 'mongoose';
  * @memberof CyberiaObjectLayerModel
  */
 const StatsSchema = new Schema(
-  {
-    effect: { type: Number, required: true, min: 0 },
-    resistance: { type: Number, required: true, min: 0 },
-    agility: { type: Number, required: true, min: 0 },
-    range: { type: Number, required: true, min: 0 },
-    intelligence: { type: Number, required: true, min: 0 },
-    utility: { type: Number, required: true, min: 0 },
-  },
-  { _id: false },
+  Object.fromEntries(STAT_TYPES.map((key) => [key, {
+    type: Number, required: true, default: STAT_DEFAULT, min: STAT_MODIFIER_MIN, max: STAT_MODIFIER_MAX,
+    validate: Number.isInteger,
+  }])),
+  { _id: false, strict: 'throw' },
 );
 /**
  * @typedef {Object} Item
@@ -112,6 +110,7 @@ const RenderSchema = new Schema(
  */
 const ObjectLayerSchema = new Schema(
   {
+    statContractVersion: { type: Number, default: STAT_CONTRACT_VERSION, enum: [STAT_CONTRACT_VERSION] },
     data: {
       stats: { type: StatsSchema, required: true },
       item: { type: ItemSchema, required: true },
@@ -228,7 +227,7 @@ function mergeObjectLayerData(existing, incoming) {
  * payload the writer hashed before merging.
  * @memberof CyberiaObjectLayerModel
  */
-const UPSERTABLE_FIELDS = ['data', 'cid', 'objectLayerRenderFramesId', 'atlasSpriteSheetId'];
+const UPSERTABLE_FIELDS = ['statContractVersion', 'data', 'cid', 'objectLayerRenderFramesId', 'atlasSpriteSheetId'];
 
 /**
  * Collapses any pre-existing duplicates of a given `data.item.id` down to a
@@ -247,12 +246,47 @@ async function collapseItemIdDuplicates(Model, itemId) {
   const removedIds = duplicates.map((duplicate) => duplicate._id);
   await Model.deleteMany({ _id: { $in: removedIds } });
 
+  // What the survivor still links is never collateral: a duplicate written by an older
+  // upsert can carry the very same render frames or atlas the survivor points at.
+  const survivorLinks = new Set(
+    [survivor.objectLayerRenderFramesId, survivor.atlasSpriteSheetId].filter(Boolean).map(String),
+  );
+  const droppedLinks = (field) =>
+    [
+      ...new Set(
+        duplicates
+          .map((duplicate) => duplicate[field])
+          .filter(Boolean)
+          .map(String),
+      ),
+    ].filter((id) => !survivorLinks.has(id));
+
   // Orphaned render frames have no other cleanup path once their owner is gone.
-  const renderFramesIds = duplicates.map((duplicate) => duplicate.objectLayerRenderFramesId).filter(Boolean);
+  const renderFramesIds = droppedLinks('objectLayerRenderFramesId');
   if (renderFramesIds.length > 0 && Model.db.models.ObjectLayerRenderFrames) {
     await Model.db.models.ObjectLayerRenderFrames.deleteMany({ _id: { $in: renderFramesIds } });
   }
 
+  // An atlas owns File renders, so dropping its document without them is what leaves
+  // unreachable blobs in the File collection.
+  const atlasIds = droppedLinks('atlasSpriteSheetId');
+  const AtlasSpriteSheet = Model.db.models.AtlasSpriteSheet;
+  if (atlasIds.length > 0 && AtlasSpriteSheet) {
+    const fields = fileRefFields('atlas-sprite-sheet');
+    const atlasDocs = await AtlasSpriteSheet.find(
+      { _id: { $in: atlasIds } },
+      Object.fromEntries(fields.map((field) => [field, 1])),
+    ).lean();
+    await AtlasSpriteSheet.deleteMany({ _id: { $in: atlasIds } });
+    if (Model.db.models.File)
+      await deleteOwnedFiles({
+        File: Model.db.models.File,
+        Owner: AtlasSpriteSheet,
+        fields,
+        ids: documentFileIds(atlasDocs, fields),
+      });
+  }
+
   return { survivor, removedIds };
 }
 
@@ -332,6 +366,7 @@ ObjectLayerSchema.statics.upsertByItemId = async function (payload, { setOnInser
   const itemId = payload?.data?.item?.id;
   if (!itemId) throw new Error('ObjectLayer.upsertByItemId requires data.item.id');
 
+  if (Object.hasOwn(payload.data, 'stats')) validateStats(payload.data.stats);
   const { survivor } = await collapseItemIdDuplicates(this, itemId);
 
   if (!survivor) {
@@ -348,7 +383,7 @@ ObjectLayerSchema.statics.upsertByItemId = async function (payload, { setOnInser
   }
   update.sha256 = computeObjectLayerSha256(update.data ?? existing.data);
 
-  return await this.findByIdAndUpdate(survivor._id, { $set: update }, { returnDocument: 'after' });
+  return await this.findByIdAndUpdate(survivor._id, { $set: update }, { returnDocument: 'after', runValidators: true });
 };
 
 // Create and export the model

package/src/api/object-layer/object-layer.router.js

@@ -347,8 +347,8 @@ class ObjectLayerRouter {
       /*
         #swagger.auto = false
         #swagger.tags = ['object-layer']
-        #swagger.summary = 'Search object layer item IDs'
-        #swagger.description = 'Returns partial matches of data.item.id for type-ahead autocomplete'
+        #swagger.summary = 'Resolve object layer item identity'
+        #swagger.description = 'Returns { id, type } for partial matches of data.item.id (type-ahead) or for an exact id list'
         #swagger.path = '/object-layer/search-item-ids'
         #swagger.method = 'get'
         #swagger.produces = ['application/json']
@@ -360,8 +360,15 @@ class ObjectLayerRouter {
             type: 'string'
         }
 
+        #swagger.parameters['ids'] = {
+            in: 'query',
+            description: 'Comma separated exact item IDs to resolve',
+            required: false,
+            type: 'string'
+        }
+
         #swagger.responses[200] = {
-          description: 'Item IDs matching the query',
+          description: 'Item identities matching the query',
           content: {
               'application/json': {
                   schema: {