cyberia 3.1.3 → 3.2.9

package/src/api/file/file.service.js

@@ -27,7 +27,7 @@ const logger = loggerFactory(import.meta);
  * @namespace FileServiceServer.FileServiceDto
  * @memberof FileServiceServer
  */
-const FileServiceDto = {
+class FileServiceDto {
   /**
    * Returns file metadata only (no buffer data).
    * Used for list responses and API integration.
@@ -36,7 +36,7 @@ const FileServiceDto = {
    * @param {Object} file - File document from database.
    * @returns {Object|null} File metadata object, or null if file is falsy.
    */
-  toMetadata: (file) => {
+  static toMetadata = (file) => {
     if (!file) return null;
     return {
       _id: file._id,
@@ -48,7 +48,7 @@ const FileServiceDto = {
       createdAt: file.createdAt,
       updatedAt: file.updatedAt,
     };
-  },
+  };
 
   /**
    * Transforms array of files to metadata only.
@@ -57,10 +57,10 @@ const FileServiceDto = {
    * @param {Array} files - Array of file documents.
    * @returns {Array} Array of file metadata objects.
    */
-  toMetadataArray: (files) => {
+  static toMetadataArray = (files) => {
     if (!Array.isArray(files)) return [];
     return files.map((file) => FileServiceDto.toMetadata(file));
-  },
+  };
 
   /**
    * Ensures UTF-8 encoding for filenames.
@@ -70,14 +70,14 @@ const FileServiceDto = {
    * @param {string} filename - Raw filename from upload.
    * @returns {string} UTF-8 encoded filename.
    */
-  normalizeFilename: (filename) => {
+  static normalizeFilename = (filename) => {
     if (!filename) return '';
     // Ensure string and normalize to UTF-8
     let normalized = String(filename);
     // Replace any incorrectly encoded sequences
     normalized = Buffer.from(normalized, 'utf8').toString('utf8');
     return normalized;
-  },
+  };
 
   /**
    * Get select fields for metadata-only queries.
@@ -86,17 +86,17 @@ const FileServiceDto = {
    * @memberof FileServiceServer.FileServiceDto
    * @returns {string} Space-separated list of field names for metadata selection.
    */
-  metadataSelect: () => {
+  static metadataSelect = () => {
     return '_id name mimetype size encoding md5 cid createdAt updatedAt';
-  },
-};
+  };
+}
 
 /**
  * File Factory for file extraction, upload, and creation utilities.
  * @namespace FileServiceServer.FileFactory
  * @memberof FileServiceServer
  */
-const FileFactory = {
+class FileFactory {
   /**
    * Extract files from request.
    * Handles both standard 'file' field and custom fields.
@@ -105,7 +105,7 @@ const FileFactory = {
    * @param {Object} req - Express request object with files.
    * @returns {Array} Array of extracted file objects.
    */
-  filesExtract: (req) => {
+  static filesExtract = (req) => {
     const files = [];
     if (!req.files || Object.keys(req.files).length === 0) {
       return files;
@@ -139,7 +139,7 @@ const FileFactory = {
     }
 
     return files;
-  },
+  };
 
   /**
    * Upload files to database with UTF-8 encoding.
@@ -150,7 +150,7 @@ const FileFactory = {
    * @param {import('mongoose').Model} File - Mongoose File model.
    * @returns {Promise<Array>} Array of uploaded file metadata objects.
    */
-  upload: async function (req, File) {
+  static async upload(req, File) {
     const results = FileFactory.filesExtract(req);
     let index = -1;
 
@@ -172,7 +172,7 @@ const FileFactory = {
     }
 
     return results;
-  },
+  }
 
   /**
    * Convert string to hexadecimal.
@@ -181,9 +181,9 @@ const FileFactory = {
    * @param {string} [raw=''] - Raw string to convert.
    * @returns {string} Hexadecimal representation of the string.
    */
-  hex: (raw = '') => {
+  static hex = (raw = '') => {
     return Buffer.from(raw, 'utf8').toString('hex');
-  },
+  };
 
   /**
    * Get MIME type from file path based on extension.
@@ -192,7 +192,7 @@ const FileFactory = {
    * @param {string} path - File path or filename with extension.
    * @returns {string} MIME type string.
    */
-  getMymeTypeFromPath: (path) => {
+  static getMymeTypeFromPath = (path) => {
     const ext = String(path || '')
       .toLowerCase()
       .split('.')
@@ -210,7 +210,7 @@ const FileFactory = {
       json: 'application/json',
     };
     return mimeTypes[ext] || 'application/octet-stream';
-  },
+  };
 
   /**
    * Create file object with proper encoding.
@@ -220,7 +220,7 @@ const FileFactory = {
    * @param {string} [name=''] - File name.
    * @returns {Object} File object with name, data, size, encoding, mimetype, and md5.
    */
-  create: (data = Buffer.from([]), name = '') => {
+  static create = (data = Buffer.from([]), name = '') => {
     const normalizedName = FileServiceDto.normalizeFilename(name);
 
     return {
@@ -234,8 +234,8 @@ const FileFactory = {
       md5: crypto.createHash('md5').update(data).digest('hex'),
       cid: undefined,
     };
-  },
-};
+  };
+}
 
 /**
  * File cleanup utilities for preventing orphaned files.
@@ -244,7 +244,7 @@ const FileFactory = {
  * @namespace FileServiceServer.FileCleanup
  * @memberof FileServiceServer
  */
-const FileCleanup = {
+class FileCleanup {
   /**
    * Clean up old file references when document fields are updated.
    * Deletes old files that are being replaced by new file IDs.
@@ -258,7 +258,7 @@ const FileCleanup = {
    * @param {import('mongoose').Model} options.File - Mongoose File model.
    * @returns {Promise<Array>} Array of deleted file IDs.
    */
-  cleanupReplacedFiles: async ({ oldDoc, newData, fileFields, File }) => {
+  static cleanupReplacedFiles = async ({ oldDoc, newData, fileFields, File }) => {
     const deletedFileIds = [];
 
     for (const field of fileFields) {
@@ -281,7 +281,7 @@ const FileCleanup = {
     }
 
     return deletedFileIds;
-  },
+  };
 
   /**
    * Delete all files referenced in a document.
@@ -297,7 +297,7 @@ const FileCleanup = {
    * @param {import('mongoose').Model} options.File - Mongoose File model.
    * @returns {Promise<Array>} Array of deleted file IDs.
    */
-  deleteDocumentFiles: async ({ doc, fileFields, File }) => {
+  static deleteDocumentFiles = async ({ doc, fileFields, File }) => {
     const deletedFileIds = [];
 
     for (const field of fileFields) {
@@ -318,15 +318,15 @@ const FileCleanup = {
     }
 
     return deletedFileIds;
-  },
-};
+  };
+}
 
 /**
  * File Service for handling REST API file operations.
  * @namespace FileServiceServer.FileService
  * @memberof FileServiceServer
  */
-const FileService = {
+class FileService {
   /**
    * POST - Upload files.
    * Returns metadata-only response (no buffer data).
@@ -338,7 +338,7 @@ const FileService = {
    * @param {Object} options - Request options containing host and path.
    * @returns {Promise<Array>} Array of uploaded file metadata objects.
    */
-  post: async (req, res, options) => {
+  static post = async (req, res, options) => {
     // Check that user is authenticated and not a guest
     if (!req.auth || !req.auth.user || req.auth.user.role === 'guest') {
       throw new Error('Authentication required. Guest users cannot upload files.');
@@ -349,7 +349,7 @@ const FileService = {
 
     const uploadedFiles = await FileFactory.upload(req, File);
     return FileServiceDto.toMetadataArray(uploadedFiles);
-  },
+  };
 
   /**
    * GET - Retrieve files.
@@ -365,7 +365,7 @@ const FileService = {
    * @returns {Promise<Array|Buffer>} Array of file metadata objects or Buffer for blob endpoint.
    * @throws {Error} If file not found or user not authorized.
    */
-  get: async (req, res, options) => {
+  static get = async (req, res, options) => {
     /** @type {import('./file.model.js').FileModel} */
     const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
     /** @type {import('../document/document.model.js').DocumentModel} */
@@ -467,7 +467,7 @@ const FileService = {
         return FileServiceDto.toMetadataArray(files);
       }
     }
-  },
+  };
 
   /**
    * DELETE - Remove files.
@@ -480,7 +480,7 @@ const FileService = {
    * @returns {Promise<Object>} Deleted file metadata object.
    * @throws {Error} If file not found.
    */
-  delete: async (req, res, options) => {
+  static delete = async (req, res, options) => {
     /** @type {import('./file.model.js').FileModel} */
     const File = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.File;
 
@@ -491,7 +491,7 @@ const FileService = {
     }
 
     return FileServiceDto.toMetadata(result);
-  },
-};
+  };
+}
 
 export { FileService, FileFactory, FileServiceDto, FileCleanup };

package/src/api/instance/instance.controller.js

@@ -3,8 +3,8 @@ import { InstanceService } from './instance.service.js';
 
 const logger = loggerFactory(import.meta);
 
-const InstanceController = {
-  post: async (req, res, options) => {
+class InstanceController {
+  static post = async (req, res, options) => {
     try {
       const result = await InstanceService.post(req, res, options);
       return res.status(200).json({
@@ -18,8 +18,8 @@ const InstanceController = {
         message: error.message,
       });
     }
-  },
-  get: async (req, res, options) => {
+  };
+  static get = async (req, res, options) => {
     try {
       const result = await InstanceService.get(req, res, options);
       return res.status(200).json({
@@ -33,8 +33,8 @@ const InstanceController = {
         message: error.message,
       });
     }
-  },
-  put: async (req, res, options) => {
+  };
+  static put = async (req, res, options) => {
     try {
       const result = await InstanceService.put(req, res, options);
       return res.status(200).json({
@@ -48,8 +48,8 @@ const InstanceController = {
         message: error.message,
       });
     }
-  },
-  delete: async (req, res, options) => {
+  };
+  static delete = async (req, res, options) => {
     try {
       const result = await InstanceService.delete(req, res, options);
       return res.status(200).json({
@@ -63,7 +63,7 @@ const InstanceController = {
         message: error.message,
       });
     }
-  },
-};
+  };
+}
 
 export { InstanceController };

package/src/api/instance/instance.model.js

@@ -1,7 +1,5 @@
 import { Schema, model, Types } from 'mongoose';
-
 // https://mongoosejs.com/docs/2.7.x/docs/schematypes.html
-
 const InstanceSchema = new Schema(
   {
     deployId: { type: String },
@@ -20,9 +18,8 @@ const InstanceSchema = new Schema(
     timestamps: true,
   },
 );
-
-const InstanceDto = {
-  populate: {
+class InstanceDto {
+  static populate = {
     get: () => {
       return {
         path: 'userId',
@@ -30,11 +27,8 @@ const InstanceDto = {
         select: '_id email',
       };
     },
-  },
-};
-
+  };
+}
 const InstanceModel = model('Instance', InstanceSchema);
-
 const ProviderSchema = InstanceSchema;
-
 export { InstanceSchema, InstanceModel, ProviderSchema, InstanceDto };

package/src/api/instance/instance.service.js

@@ -5,13 +5,13 @@ import { InstanceDto } from './instance.model.js';
 
 const logger = loggerFactory(import.meta);
 
-const InstanceService = {
-  post: async (req, res, options) => {
+class InstanceService {
+  static post = async (req, res, options) => {
     /** @type {import('./instance.model.js').InstanceModel} */
     const Instance = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Instance;
     return await new Instance(req.body).save();
-  },
-  get: async (req, res, options) => {
+  };
+  static get = async (req, res, options) => {
     /** @type {import('./instance.model.js').InstanceModel} */
     const Instance = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Instance;
 
@@ -58,18 +58,18 @@ const InstanceService = {
             return { data: dataUser, total: totalUser, page, totalPages: Math.ceil(totalUser / limit) };
         }
     }
-  },
-  put: async (req, res, options) => {
+  };
+  static put = async (req, res, options) => {
     /** @type {import('./instance.model.js').InstanceModel} */
     const Instance = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Instance;
     return await Instance.findByIdAndUpdate(req.params.id, req.body);
-  },
-  delete: async (req, res, options) => {
+  };
+  static delete = async (req, res, options) => {
     /** @type {import('./instance.model.js').InstanceModel} */
     const Instance = DataBaseProvider.instance[`${options.host}${options.path}`].mongoose.models.Instance;
     if (req.params.id) return await Instance.findByIdAndDelete(req.params.id);
     else return await Instance.deleteMany();
-  },
-};
+  };
+}
 
 export { InstanceService };

package/src/api/ipfs/ipfs.controller.js

@@ -3,8 +3,8 @@ import { IpfsService } from './ipfs.service.js';
 
 const logger = loggerFactory(import.meta);
 
-const IpfsController = {
-  post: async (req, res, options) => {
+class IpfsController {
+  static post = async (req, res, options) => {
     try {
       const result = await IpfsService.post(req, res, options);
       return res.status(200).json({
@@ -18,8 +18,8 @@ const IpfsController = {
         message: error.message,
       });
     }
-  },
-  get: async (req, res, options) => {
+  };
+  static get = async (req, res, options) => {
     try {
       const { page, limit } = req.query;
       const result = await IpfsService.get(
@@ -38,8 +38,8 @@ const IpfsController = {
         message: error.message,
       });
     }
-  },
-  put: async (req, res, options) => {
+  };
+  static put = async (req, res, options) => {
     try {
       const result = await IpfsService.put(req, res, options);
       return res.status(200).json({
@@ -53,8 +53,8 @@ const IpfsController = {
         message: error.message,
       });
     }
-  },
-  delete: async (req, res, options) => {
+  };
+  static delete = async (req, res, options) => {
     try {
       const result = await IpfsService.delete(req, res, options);
       return res.status(200).json({
@@ -68,37 +68,16 @@ const IpfsController = {
         message: error.message,
       });
     }
-  },
-  pin: async (req, res, options) => {
+  };
+  static verify = async (req, res, options) => {
     try {
-      const result = await IpfsService.pin(req, res, options);
-      return res.status(200).json({
-        status: 'success',
-        data: result,
-      });
-    } catch (error) {
-      logger.error(error, error.stack);
-      return res.status(400).json({
-        status: 'error',
-        message: error.message,
-      });
-    }
-  },
-  unpin: async (req, res, options) => {
-    try {
-      const result = await IpfsService.unpin(req, res, options);
-      return res.status(200).json({
-        status: 'success',
-        data: result,
-      });
+      const result = await IpfsService.verify(req, res, options);
+      return res.status(200).json({ status: 'success', data: result });
     } catch (error) {
       logger.error(error, error.stack);
-      return res.status(400).json({
-        status: 'error',
-        message: error.message,
-      });
+      return res.status(400).json({ status: 'error', message: error.message });
     }
-  },
-};
+  };
+}
 
 export { IpfsController };

package/src/api/ipfs/ipfs.model.js

@@ -1,21 +1,27 @@
 /**
- * Mongoose model for IPFS API – a general-purpose pin record that relates
- * a user to a CID.
+ * Mongoose model for the IPFS CID Registry.
+ *
+ * Purpose: tracks every CID that the Engine has pinned to IPFS so that:
+ *   1. Deletions can cleanly unpin the right CID from the IPFS node/cluster.
+ *   2. Admins can run a health-check that verifies every DB-registered CID is
+ *      still actually pinned (GET /ipfs/verify).
+ *   3. Garbage-collection jobs can discover orphaned CIDs (pinned on the node
+ *      but not referenced by any DB document).
+ *
+ * Fields:
+ *   cid          - IPFS Content Identifier (CIDv0 or CIDv1).
+ *   resourceType - What kind of asset this CID belongs to:
+ *                    'object-layer-data'  - JSON payload of an ObjectLayer document.
+ *                    'atlas-sprite-sheet' - PNG sprite-sheet of an ObjectLayer.
+ *                    'atlas-metadata'     - JSON metadata of an AtlasSpriteSheet.
+ *   mfsPath      - MFS (Mutable File System) path used when the CID was added,
+ *                  e.g. /object-layer/sword/sword_data.json.
+ *                  Enables targeted removal via files/rm without knowing the CID.
  *
  * @module src/api/ipfs/ipfs.model.js
  * @namespace IpfsModel
  */
-
 import { Schema, model } from 'mongoose';
-
-/**
- * @typedef {Object} Ipfs
- * @property {string}         cid       – IPFS Content Identifier (CIDv0 or CIDv1).
- * @property {Types.ObjectId} userId    – Reference to the User who owns / requested the pin.
- * @property {Date}           createdAt – Auto-managed by Mongoose.
- * @property {Date}           updatedAt – Auto-managed by Mongoose.
- * @memberof IpfsModel
- */
 const IpfsSchema = new Schema(
   {
     cid: {
@@ -23,49 +29,43 @@ const IpfsSchema = new Schema(
       required: true,
       trim: true,
     },
-    userId: {
-      type: Schema.Types.ObjectId,
-      ref: 'User',
+    // Asset category - determines which service owns this CID.
+    resourceType: {
+      type: String,
       required: true,
+      trim: true,
+      enum: ['object-layer-data', 'atlas-sprite-sheet', 'atlas-metadata'],
+    },
+    // MFS path used when the content was added to IPFS.
+    // Empty string when the content was added without an MFS copy.
+    mfsPath: {
+      type: String,
+      default: '',
+      trim: true,
     },
   },
   {
     timestamps: true,
   },
 );
-
-// Compound index: one pin record per user + CID pair.
-IpfsSchema.index({ cid: 1, userId: 1 }, { unique: true });
-
-// Fast look-ups by user.
-IpfsSchema.index({ userId: 1 });
-
-// Fast look-ups by CID.
-IpfsSchema.index({ cid: 1 });
-
+// One DB record per (CID, resourceType) pair.
+IpfsSchema.index({ cid: 1, resourceType: 1 }, { unique: true });
+// Fast look-ups for health-check and garbage-collection by type.
+IpfsSchema.index({ resourceType: 1 });
+// Fast look-ups for targeted MFS cleanup.
+IpfsSchema.index({ mfsPath: 1 });
 const IpfsModel = model('Ipfs', IpfsSchema);
-
 const ProviderSchema = IpfsSchema;
-
-const IpfsDto = {
-  select: {
-    get: () => {
-      return {
-        _id: 1,
-        cid: 1,
-        userId: 1,
-        createdAt: 1,
-        updatedAt: 1,
-      };
-    },
-  },
-  populate: {
-    user: () => ({
-      path: 'userId',
-      model: 'User',
-      select: '_id username email role',
+class IpfsDto {
+  static select = {
+    get: () => ({
+      _id: 1,
+      cid: 1,
+      resourceType: 1,
+      mfsPath: 1,
+      createdAt: 1,
+      updatedAt: 1,
     }),
-  },
-};
-
+  };
+}
 export { IpfsSchema, IpfsModel, ProviderSchema, IpfsDto };

package/src/api/ipfs/ipfs.router.js

@@ -8,19 +8,14 @@ const logger = loggerFactory(import.meta);
 const IpfsRouter = (options) => {
   const router = express.Router();
   const authMiddleware = options.authMiddleware;
-  router.post(`/pin`, authMiddleware, adminGuard, async (req, res) => await IpfsController.pin(req, res, options));
-  router.delete(
-    `/pin/:cid`,
-    authMiddleware,
-    adminGuard,
-    async (req, res) => await IpfsController.unpin(req, res, options),
-  );
-  router.post(`/:id`, authMiddleware, async (req, res) => await IpfsController.post(req, res, options));
-  router.post(`/`, authMiddleware, async (req, res) => await IpfsController.post(req, res, options));
-  router.get(`/:id`, authMiddleware, async (req, res) => await IpfsController.get(req, res, options));
-  router.get(`/`, authMiddleware, async (req, res) => await IpfsController.get(req, res, options));
-  router.put(`/:id`, authMiddleware, async (req, res) => await IpfsController.put(req, res, options));
-  router.put(`/`, authMiddleware, async (req, res) => await IpfsController.put(req, res, options));
+  // Health / audit — must come before /:id to avoid matching conflicts.
+  router.get(`/verify`, authMiddleware, adminGuard, async (req, res) => await IpfsController.verify(req, res, options));
+  router.post(`/:id`, authMiddleware, adminGuard, async (req, res) => await IpfsController.post(req, res, options));
+  router.post(`/`, authMiddleware, adminGuard, async (req, res) => await IpfsController.post(req, res, options));
+  router.get(`/:id`, authMiddleware, adminGuard, async (req, res) => await IpfsController.get(req, res, options));
+  router.get(`/`, authMiddleware, adminGuard, async (req, res) => await IpfsController.get(req, res, options));
+  router.put(`/:id`, authMiddleware, adminGuard, async (req, res) => await IpfsController.put(req, res, options));
+  router.put(`/`, authMiddleware, adminGuard, async (req, res) => await IpfsController.put(req, res, options));
   router.delete(`/:id`, authMiddleware, adminGuard, async (req, res) => await IpfsController.delete(req, res, options));
   router.delete(`/`, authMiddleware, adminGuard, async (req, res) => await IpfsController.delete(req, res, options));
   return router;