@modular-rest/server 1.11.12 → 1.11.14

package/src/services/file/router.ts

@@ -0,0 +1,88 @@
+import Router from 'koa-router';
+import { validateObject } from '../../class/validator';
+import { create as reply } from '../../class/reply';
+import { Context, Next } from 'koa';
+import { AccessTypes } from './../../class/security';
+import * as DataService from './../data_provider/service';
+import { main as service } from './service';
+import * as middleware from '../../middlewares';
+
+const name = 'file';
+const fileRouter = new Router();
+
+fileRouter.use('/', middleware.auth, async (ctx: Context, next: Next) => {
+  await next();
+});
+
+fileRouter.post('/', async (ctx: Context) => {
+  const body = ctx.request.body;
+
+  // validate result
+  const bodyValidate = validateObject(body, 'tag');
+
+  // fields validation
+  if (!bodyValidate.isValid) {
+    ctx.status = 412;
+    ctx.body = reply('e', { e: bodyValidate.requires });
+    return;
+  }
+
+  // Access validation
+  const hasAccess = DataService.checkAccess('cms', 'file', AccessTypes.write, body, ctx.state.user);
+  if (!hasAccess) {
+    ctx.throw(403, 'access denied');
+    return;
+  }
+
+  const files = ctx.request.files;
+  const file = files && files.file;
+  let result;
+
+  if (!file) {
+    ctx.status = 412;
+    result = reply('f', { message: 'file field required' });
+  } else {
+    await service
+      .storeFile({
+        file: file as any,
+        ownerId: ctx.state.user.id,
+        tag: body.tag,
+      })
+      .then(file => {
+        result = reply('s', { file });
+      })
+      .catch(error => {
+        ctx.status = 412;
+        result = reply('e', error);
+      });
+  }
+
+  ctx.body = result;
+});
+
+fileRouter.delete('/', async (ctx: Context) => {
+  const body = ctx.request.query;
+  // validate
+  const bodyValidate = validateObject(body as Record<string, any>, 'id');
+
+  let result;
+
+  if (!bodyValidate.isValid) {
+    ctx.status = 412;
+    result = reply('f', { message: 'some fields required.', error: bodyValidate.requires });
+  } else {
+    await service
+      .removeFile(body.id as string)
+      .then(() => {
+        result = reply('s');
+      })
+      .catch(e => {
+        ctx.status = 412;
+        result = reply('e', { error: e });
+      });
+  }
+
+  ctx.body = result;
+});
+
+export { name, fileRouter as main };

package/src/services/file/service.ts

@@ -0,0 +1,387 @@
+import fs from 'fs';
+import pathModule from 'path';
+import * as DataProvider from '../data_provider/service';
+import triggerService from '../../class/trigger_operator';
+import { config } from '../../config';
+import { IFile } from '../../class/db_schemas';
+
+/**
+ * Service name constant
+ * @constant {string}
+ */
+export const name = 'file';
+
+/**
+ * File storage detail interface
+ * @interface StoredFileDetail
+ * @property {string} fileName - Generated unique filename
+ * @property {string} fullPath - Full path to the stored file
+ * @property {string} fileFormat - File format/extension
+ */
+interface StoredFileDetail {
+  fileName: string;
+  fullPath: string;
+  fileFormat: string;
+}
+
+/**
+ * File upload options interface
+ * @interface StoreFileOptions
+ * @property {Object} file - File details
+ * @property {string} file.path - Temporary file path
+ * @property {string} file.type - MIME type of the file
+ * @property {string} file.name - Original filename
+ * @property {number} file.size - File size in bytes
+ * @property {string} ownerId - ID of the file owner
+ * @property {string} tag - Tag for file organization
+ * @property {boolean} [removeFileAfterStore=true] - Whether to remove the temporary file after storage
+ */
+interface StoreFileOptions {
+  file: {
+    path: string;
+    type: string;
+    name: string;
+    size: number;
+  };
+  ownerId: string;
+  tag: string;
+  removeFileAfterStore?: boolean;
+}
+
+/**
+ * File service for handling file storage and retrieval.
+ *
+ * This service provides functionality for storing, retrieving, and managing files.
+ * It handles file storage on disk and maintains file metadata in the database.
+ * Files are organized by format and tag in the upload directory.
+ */
+class FileService {
+  /**
+   * @hidden
+   */
+  private directory: string | null = null;
+
+  /**
+   * @hidden
+   */
+  static instance: FileService;
+
+  /**
+   * @hidden
+   */
+  constructor() {}
+
+  /**
+   * @hidden
+   *
+   * Sets the upload directory for file storage
+   * @param {string} directory - Directory path for file storage
+   * @throws {Error} If directory is invalid or not writable
+   * @example
+   * ```typescript
+   * import { fileService } from '@modular-rest/server';
+   *
+   * fileService.setUploadDirectory('/path/to/uploads');
+   * ```
+   */
+  setUploadDirectory(directory: string): void {
+    if (!fs.existsSync(directory)) {
+      fs.mkdirSync(directory, { recursive: true });
+    }
+    this.directory = directory;
+  }
+
+  /**
+   * @hidden
+   *
+   * Creates stored file details with unique filename
+   * @param {string} fileType - MIME type of the file
+   * @param {string} tag - Tag for file organization
+   * @returns {StoredFileDetail} Storage details including filename and path
+   * @throws {Error} If upload directory is not set
+   *
+   * @example
+   * ```typescript
+   * import { fileService } from '@modular-rest/server';
+   *
+   * const details = fileService.createStoredDetail('image/jpeg', 'profile');
+   * // Returns: { fileName: '1234567890.jpeg', fullPath: '/uploads/jpeg/profile/1234567890.jpeg', fileFormat: 'jpeg' }
+   * ```
+   */
+  createStoredDetail(fileType: string, tag: string): StoredFileDetail {
+    const typeParts = fileType.split('/');
+    const fileFormat = typeParts[1] || typeParts[0] || 'unknown';
+
+    const time = new Date().getTime();
+    const fileName = `${time}.${fileFormat}`;
+
+    if (!FileService.instance.directory) {
+      throw new Error('Upload directory has not been set');
+    }
+
+    const fullPath = pathModule.join(FileService.instance.directory, fileFormat, tag, fileName);
+
+    return { fileName, fullPath, fileFormat };
+  }
+
+  /**
+   * @hidden
+   *
+   * Stores a file, removes the temporary file, and saves metadata to database
+   * @param {StoreFileOptions} options - File storage options
+   * @returns {Promise<IFile>} Promise resolving to stored file document
+   * @throws {Error} If upload directory is not set or storage fails
+   * @example
+   * ```typescript
+   * import { fileService } from '@modular-rest/server';
+   *
+   * const file = await fileService.storeFile({
+   *   file: {
+   *     path: '/tmp/upload.jpg',
+   *     type: 'image/jpeg',
+   *     name: 'profile.jpg',
+   *     size: 1024
+   *   },
+   *   ownerId: 'user123',
+   *   tag: 'profile',
+   *   removeFileAfterStore: true
+   * });
+   * ```
+   */
+  storeFile({ file, ownerId, tag, removeFileAfterStore = true }: StoreFileOptions): Promise<IFile> {
+    if (!FileService.instance.directory) {
+      throw new Error('Upload directory has not been set');
+    }
+
+    let storedFile: StoredFileDetail;
+
+    return new Promise(async (done, reject) => {
+      storedFile = FileService.instance.createStoredDetail(file.type, tag);
+
+      fs.copyFile(file.path, storedFile.fullPath, (err: Error | null) => {
+        if (err) {
+          reject(err);
+        } else {
+          done(null);
+        }
+
+        // remove temp file
+        if (removeFileAfterStore) {
+          fs.unlinkSync(file.path);
+        }
+      });
+    })
+      .then(() => {
+        // Get collection model for access to relative collection
+        const CollectionModel = DataProvider.getCollection<IFile>('cms', 'file');
+
+        if (!CollectionModel) {
+          throw new Error('Collection model not found');
+        }
+
+        const data = {
+          owner: ownerId,
+          fileName: storedFile.fileName,
+          originalName: file.name,
+          format: storedFile.fileFormat,
+          tag,
+          size: file.size,
+        };
+
+        // Create new document
+        const doc = new CollectionModel(data);
+
+        return doc.save().then(savedDoc => {
+          triggerService.call('insert-one', 'cms', 'file', {
+            query: null,
+            queryResult: savedDoc,
+          });
+
+          return savedDoc;
+        });
+      })
+      .catch(err => {
+        // remove stored file
+        fs.unlinkSync(storedFile.fullPath);
+
+        throw err;
+      });
+  }
+
+  /**
+   * @hidden
+   *
+   * Removes a file from the disk
+   * @param {string} path - File path to remove
+   * @returns {Promise<void>} Promise resolving when file is removed
+   * @throws {Error} If file removal fails
+   * @example
+   * ```typescript
+   * import { fileService } from '@modular-rest/server';
+   *
+   * await fileService.removeFromDisc('/uploads/jpeg/profile/1234567890.jpeg');
+   * ```
+   */
+  removeFromDisc(path: string): Promise<void> {
+    return new Promise((done, reject) => {
+      fs.unlink(path, (err: Error | null) => {
+        if (err) reject(err);
+        else done();
+      });
+    });
+  }
+
+  /**
+   * Removes a file from both database and disk
+   *
+   * @param {string} fileId - File ID to remove
+   * @returns {Promise<void>} Promise resolving when file is removed
+   * @throws {Error} If file is not found or removal fails
+   * @example
+   * ```typescript
+   * import { fileService } from '@modular-rest/server';
+   *
+   * try {
+   *   await fileService.removeFile('file123');
+   *   console.log('File removed successfully');
+   * } catch (error) {
+   *   console.error('Failed to remove file:', error);
+   * }
+   * ```
+   */
+  removeFile(fileId: string): Promise<void> {
+    if (!FileService.instance.directory) {
+      throw new Error('Upload directory has not been set');
+    }
+
+    return new Promise(async (done, reject) => {
+      const CollectionModel = DataProvider.getCollection<IFile>('cms', 'file');
+
+      if (!CollectionModel) {
+        return reject(new Error('Collection model not found'));
+      }
+
+      const fileDoc = await CollectionModel.findOne({ _id: fileId }).exec();
+
+      if (!fileDoc) {
+        return reject(new Error('File not found'));
+      }
+
+      await CollectionModel.deleteOne({ _id: fileId })
+        .exec()
+        .then(() => {
+          // create file path
+          const filePath = pathModule.join(
+            FileService.instance.directory as string,
+            fileDoc.format,
+            fileDoc.tag,
+            fileDoc.fileName
+          );
+
+          // Remove file from disc
+          return FileService.instance.removeFromDisc(filePath).catch(async err => {
+            // Recreate fileDoc if removing file operation has error
+            await new CollectionModel(fileDoc).save();
+
+            throw err;
+          });
+        })
+        .then(() => {
+          triggerService.call('remove-one', 'cms', 'file', {
+            query: { _id: fileId },
+            queryResult: null,
+          });
+        })
+        .then(done)
+        .catch(reject);
+    });
+  }
+
+  /**
+   * Retrieves a file document from the database
+   *
+   * @param {string} fileId - File ID to retrieve
+   * @returns {Promise<IFile>} Promise resolving to file document
+   * @throws {Error} If collection model is not found or file is not found
+   * @example
+   * ```typescript
+   * import { fileService } from '@modular-rest/server';
+   *
+   * const fileDoc = await fileService.getFile('file123');
+   * console.log('File details:', fileDoc);
+   * ```
+   */
+  getFile(fileId: string): Promise<IFile> {
+    const CollectionModel = DataProvider.getCollection<IFile>('cms', 'file');
+
+    if (!CollectionModel) {
+      throw new Error('Collection model not found');
+    }
+
+    return CollectionModel.findOne({ _id: fileId })
+      .exec()
+      .then(doc => {
+        if (!doc) {
+          throw new Error('File not found');
+        }
+        return doc;
+      });
+  }
+
+  /**
+   * Retrieves the public URL link for a file
+   *
+   * @param {string} fileId - File ID to get link for
+   * @returns {Promise<string>} Promise resolving to file URL
+   * @throws {Error} If static path root is not defined or file is not found
+   * @example
+   * ```typescript
+   * import { fileService } from '@modular-rest/server';
+   *
+   * const link = await fileService.getFileLink('file123');
+   * // Returns: '/static/jpeg/profile/1234567890.jpeg'
+   * ```
+   */
+  async getFileLink(fileId: string): Promise<string> {
+    const fileDoc = await FileService.instance.getFile(fileId);
+
+    if (!config.staticPath?.actualPath) {
+      throw new Error('Static path root is not defined');
+    }
+
+    const link =
+      config.staticPath.actualPath + `/${fileDoc.format}/${fileDoc.tag}/` + fileDoc.fileName;
+
+    return link;
+  }
+
+  /**
+   * Gets the full filesystem path for a file
+   *
+   * @param {string} fileId - File ID to get path for
+   * @returns {Promise<string>} Promise resolving to full file path
+   * @throws {Error} If upload directory is not set or file is not found
+   * @example
+   * ```typescript
+   * import { fileService } from '@modular-rest/server';
+   *
+   * const path = await fileService.getFilePath('file123');
+   * // Returns: '/uploads/jpeg/profile/1234567890.jpeg'
+   * ```
+   */
+  async getFilePath(fileId: string): Promise<string> {
+    const { fileName, format, tag } = await FileService.instance.getFile(fileId);
+
+    if (!FileService.instance.directory) {
+      throw new Error('Upload directory has not been set');
+    }
+
+    return pathModule.join(FileService.instance.directory, format, tag, fileName);
+  }
+}
+
+/**
+ * Main file service instance
+ * @constant {FileService}
+ */
+export const main = new FileService();

package/src/services/functions/router.ts

@@ -0,0 +1,34 @@
+import Router from 'koa-router';
+import * as service from './service';
+import * as middleware from '../../middlewares';
+import { validateObject } from '../../class/validator';
+import { create as reply } from '../../class/reply';
+import { Context, Next } from 'koa';
+
+const functionRouter = new Router();
+const name = 'function';
+
+functionRouter.use('/', middleware.auth, async (ctx: Context, next: Next) => {
+  const body = ctx.request.body;
+  const bodyValidated = validateObject(body, 'name args');
+
+  // fields validation
+  if (!bodyValidated.isValid) {
+    ctx.throw(412, JSON.stringify(reply('e', { error: bodyValidated.requires })));
+  }
+
+  await next();
+});
+
+functionRouter.post('/run', middleware.auth, async (ctx: Context) => {
+  const { name, args } = ctx.request.body;
+
+  try {
+    const result = await service.runFunction(name, args, ctx.state.user);
+    ctx.body = JSON.stringify(reply('s', { data: result }));
+  } catch (e) {
+    ctx.throw(400, JSON.stringify(reply('e', { error: (e as Error).message })));
+  }
+});
+
+export { name, functionRouter as main };

package/src/services/functions/service.ts

@@ -0,0 +1,203 @@
+import { AccessType } from '../../class/security';
+import { User } from '../../class/user';
+
+/**
+ * Service name constant
+ * @constant {string}
+ */
+export const name = 'functions';
+
+/**
+ * Storage for registered functions
+ * @private
+ */
+const functions: DefinedFunction[] = [];
+
+/**
+ * Interface for defined functions.
+ *
+ * @interface DefinedFunction
+ * @inline
+ * @example
+ * ```typescript
+ * const myFunction: DefinedFunction = {
+ *   name: 'calculateTotal',
+ *   permissionTypes: ['user_access'],
+ *   callback: (args) => args.items.reduce((sum, item) => sum + item.price, 0)
+ * };
+ * ```
+ */
+export interface DefinedFunction {
+  /**
+   * Unique name of the function
+   * @type {string}
+   */
+  name: string;
+  /**
+   * List of permission types required to run the function
+   * @type {AccessType[]}
+   */
+  permissionTypes: AccessType[];
+
+  /**
+   * The actual function implementation
+   * @type {(args: any) => any}
+   */
+  callback: (args: any) => any;
+}
+
+/**
+ * To define a function you need to create a `functions.[js|ts]` in each module of your app and return am array called `functions`, and then define all your functions with calling the `defineFunction` method.
+ *
+ * The `defineFunction` method serves as a core utility for creating custom functions dynamically. This method allows you to specify various parameters, including the name of the function, the permissions required for access, and the corresponding logic that should be executed when the function is invoked.
+ *
+ * @summary
+ * Define a server function to be called by clients.
+ *
+ * @param {DefinedFunction} options - The function definition options. See {@link DefinedFunction} for detailed parameter descriptions.
+ * @expandType DefinedFunction
+ *
+ * @returns {Object} The defined function object which system will use to generate a router for the function, generall the client library will use the router to call the function.
+ * @throws {Error} If function name already exists, permission types are missing, or callback is invalid
+ *
+ * @example
+ * Here is an example illustrating how to use the `defineFunction` method effectively:
+ * ```typescript
+ * // /modules/myModule/functions.ts
+ *
+ * import { defineFunction } from "@modular-rest/server";
+ *
+ * const getServerTime = defineFunction({
+ *   name: "getServerTime",
+ *   permissionTypes: ["anonymous_access"],
+ *   callback: (params) => {
+ *     // return your data only
+ *     return `
+ *       Welcome, ${params.username}!
+ *       The current server time is ${new Date().toLocaleString()}.
+ *     `;
+ *
+ *     // error handling,
+ *     // client gets error code 400, and the message
+ *     // throw new Error('An error occurred');
+ *   },
+ * });
+ *
+ * module.exports.functions = [getServerTime];
+ * ```
+ * In this example, we define a function named `getServerTime` that requires the `user` permission type to access. When the function is called, it will return a message containing the current server time and the username of the user who invoked the function.
+ *
+ * ---
+ *
+ * By utilizing the `defineFunction` method, developers are empowered to create custom functionality effortlessly within the Modular REST framework, enhancing both the versatility and security of their applications.
+ */
+export function defineFunction(options: DefinedFunction): DefinedFunction {
+  // Check if the function already exists
+  const existingFunction = functions.find(f => f.name === name);
+  if (existingFunction) {
+    throw new Error(`Function with name ${name} already exists`);
+  }
+
+  // Check if the permission types provided
+  if (!options.permissionTypes || !options.permissionTypes.length) {
+    throw new Error(`Permission types not provided for function ${name}`);
+  }
+
+  // Check if the callback is a function
+  if (typeof options.callback !== 'function') {
+    throw new Error(`Callback is not a function for function ${name}`);
+  }
+
+  // Add the function to the list of functions
+  return options;
+}
+
+/**
+ * Runs a function by name with arguments and user context
+ *
+ * @param {string} name - Name of the function to run
+ * @param {any} args - Arguments to pass to the function
+ * @param {User} user - User attempting to run the function
+ * @returns {Promise<any>} Promise resolving to function result
+ * @throws {Error} If function not found or user lacks required permissions
+ *
+ * @private
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await runFunction('calculateTotal', {
+ *     items: [
+ *       { price: 10 },
+ *       { price: 20 }
+ *     ]
+ *   }, currentUser);
+ *   console.log('Total:', result); // 30
+ * } catch (error) {
+ *   console.error('Function execution failed:', error);
+ * }
+ * ```
+ */
+export function runFunction(name: string, args: any, user: User): Promise<any> {
+  return new Promise((resolve, reject) => {
+    const func = functions.find(f => f.name === name);
+    if (!func) {
+      return reject(new Error(`Function with name ${name} not found`));
+    }
+
+    const hasPermission = func.permissionTypes.some(permissionType =>
+      user.hasPermission(permissionType)
+    );
+
+    if (!hasPermission) {
+      const userBrief = user.getBrief();
+      const userPermissions =
+        typeof userBrief.permissionGroup === 'object' && userBrief.permissionGroup
+          ? userBrief.permissionGroup.allowedAccessTypes
+          : 'none';
+
+      reject(
+        new Error(`User does not have permission to run function ${name}:
+        Function permissions: ${func.permissionTypes}
+        User permissions: ${userPermissions}
+        `)
+      );
+    } else {
+      try {
+        resolve(func.callback(args));
+      } catch (e) {
+        reject(e);
+      }
+    }
+  });
+}
+
+/**
+ * Adds a function to the registry, this method is used for internal use only,
+ * it will add all defined functions to the registry.
+ *
+ * @param {DefinedFunction} func - Function to add
+ * @throws {Error} If function name already exists
+ *
+ * @private
+ *
+ * @example
+ * ```typescript
+ * const myFunction = defineFunction({
+ *   name: 'myFunction',
+ *   permissionTypes: ['user_access'],
+ *   callback: (args) => args.value * 2
+ * });
+ *
+ * addFunction(myFunction);
+ * ```
+ */
+export function addFunction(func: DefinedFunction): void {
+  // Check if the function already exists
+  const existingFunction = functions.find(f => f.name === func.name);
+  if (existingFunction) {
+    throw new Error(`Function with name ${func.name} already exists`);
+  }
+
+  functions.push(func);
+}