@underpostnet/cyberia 3.2.80

package/src/server/logger.js

@@ -0,0 +1,229 @@
+/**
+ * Module for managing logger control and configuration
+ * @module src/server/logger.js
+ * @namespace Logger
+ */
+
+'use strict';
+
+import winston from 'winston';
+import morgan from 'morgan';
+import { colorize, color } from 'json-colorizer';
+import colors from 'colors';
+import v8 from 'v8';
+import { clearTerminalStringColor, formatBytes } from '../client/components/core/CommonJs.js';
+
+colors.enable();
+
+// Define your severity levels.
+// With them, You can create log files,
+// see or hide levels based on the running ENV.
+const levels = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  http: 3,
+  debug: 4,
+};
+
+/**
+ * The `level` function determines the logging level based on the provided `logLevel` parameter or defaults to 'info'.
+ * @param {string} logLevel - The logging level to be used. If not provided, it defaults to 'info'.
+ * @returns {string} The logging level to be used for the logger.
+ * @memberof Logger
+ */
+const level = (logLevel = '') => logLevel || 'info';
+
+// Define different colors for each level.
+// Colors make the log message more visible,
+// adding the ability to focus or ignore messages.
+
+// Tell winston that you want to link the colors
+// defined above to the severity levels.
+winston.addColors({
+  error: 'red',
+  warn: 'yellow',
+  info: 'green',
+  http: 'magenta',
+  debug: 'white',
+});
+
+// Chose the aspect of your log customizing the log format.
+const format = (meta) =>
+  winston.format.combine(
+    // winston.format.errors({ stack: true }),
+    // Add the message timestamp with the preferred format
+    winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss:ms' }),
+    // Tell Winston that the logs must be colored
+    winston.format.colorize({ all: true }),
+    // Define the format of the message showing the timestamp, the level and the message
+    winston.format.printf((info) => {
+      const splatKey = Symbol.for('splat');
+      const splat = info[splatKey];
+      const hasSplat = Array.isArray(splat) && splat.length > 0 && splat[0] !== undefined;
+      let splatStr = '';
+      if (hasSplat) {
+        const seen = new WeakSet();
+        splatStr = JSON.stringify(
+          splat[0],
+          (key, value) => {
+            if (typeof value === 'function') return `[Function: ${value.name || 'anonymous'}]`;
+            if (typeof value === 'object' && value !== null) {
+              if (seen.has(value)) return '[Circular]';
+              seen.add(value);
+            }
+            return value;
+          },
+          4,
+        );
+      }
+      return `${`[${meta}]`.green} ${info.timestamp} ${info.level} ${
+        hasSplat
+          ? `${clearTerminalStringColor(info.message)}: ${colorize(splatStr, {
+              colors: {
+                StringKey: color.green,
+                StringLiteral: color.magenta,
+                NumberLiteral: color.red,
+                BooleanLiteral: color.cyan,
+                NullLiteral: color.white,
+              },
+            })}`
+          : info.message
+      }`;
+    }),
+  );
+
+/**
+ * Logs information about the current process environment to the console.
+ *
+ * This function is used to log details about
+ * the execution context, such as command-line arguments,
+ * environment variables, and the maximum available heap space size.
+ *
+ * @param {winston.Logger} logger - A pre-configured Winston logger object.
+ * @memberof Logger
+ */
+const setUpInfo = async (logger = new winston.Logger()) => {
+  logger.info('argv', process.argv);
+  logger.info('cwd', process.cwd());
+  logger.info('platform', process.platform);
+  logger.info('env', process.env.NODE_ENV);
+  logger.info('--max-old-space-size', {
+    total_available_size: formatBytes(v8.getHeapStatistics().total_available_size),
+  });
+};
+
+/**
+ * The function `loggerFactory` creates a logger instance with specified transports for printing out
+ * messages.
+ * @param meta - The `meta` parameter in the `loggerFactory` function is used to extract the last part
+ * of a URL and use it to create log files in a specific directory.
+ * @param logLevel - Specify the logging level for the logger instance. e.g., 'error', 'warn', 'info', 'debug'.
+ * @param enableFileLogs - Whether to write logs to files. Defaults to the value of the `ENABLE_FILE_LOGS` environment variable.
+ * @returns {underpostLogger} The `loggerFactory` function returns a logger instance created using Winston logger
+ * library. The logger instance is configured with various transports for printing out messages to
+ * different destinations such as the terminal, error.log file, and all.log file. The logger instance
+ * also has a method `setUpInfo` attached to it for setting up additional information.
+ * @memberof Logger
+ */
+const loggerFactory = (
+  meta = { url: '' },
+  logLevel = '',
+  enableFileLogs = process.env.ENABLE_FILE_LOGS === 'true' || process.env.ENABLE_FILE_LOGS === true,
+) => {
+  meta = meta.url.split('/').pop();
+  // Define which transports the logger must use to print out messages.
+  // In this example, we are using three different transports
+  const transports = [
+    // Allow the use the terminal to print the messages
+    new winston.transports.Console(),
+    // Optionally write log files when enableFileLogs is true
+    ...(enableFileLogs
+      ? [
+          // Allow to print all the error level messages inside the error.log file
+          new winston.transports.File({
+            filename: `logs/${meta}/error.log`,
+            level: 'error',
+          }),
+          // Allow to print all the error messages inside the all.log file
+          // (also includes error logs that are also printed inside error.log)
+          new winston.transports.File({ filename: `logs/${meta}/all.log` }),
+        ]
+      : []),
+  ];
+
+  // Create the logger instance that has to be exported
+  // and used to log messages.
+  const logger = winston.createLogger({
+    defaultMeta: meta,
+    level: level(logLevel),
+    levels,
+    format: format(meta),
+    transports,
+    // exceptionHandlers: [new winston.transports.File({ filename: 'exceptions.log' })],
+    // rejectionHandlers: [new winston.transports.File({ filename: 'rejections.log' })],
+    // exitOnError: false,
+  });
+  /**
+   * The returned logger is a real Winston logger instance with an extra `setUpInfo` method.
+   *
+   * @memberof Logger
+   * @typedef {winston.Logger & {
+   *  setUpInfo: (logger?: winston.Logger) => Promise<void>
+   * }} underpostLogger
+   */
+  logger.setUpInfo = () => setUpInfo(logger);
+
+  return logger;
+};
+
+/**
+ * The `loggerMiddleware` function is an Express middleware that uses the Morgan library to log HTTP requests.
+ * @param {Object} meta - An object containing metadata, such as the URL, to be used in the logger.
+ * @param {string} logLevel - The logging level to be used for the logger (e.g., 'error', 'warn', 'info', 'debug').
+ * @param {Function} skip - A function to determine whether to skip logging for a particular request.
+ * @param {boolean} enableFileLogs - Whether to write logs to files. Defaults to false.
+ * @returns {Function} A middleware function that can be used in an Express application to log HTTP requests.
+ * @memberof Logger
+ */
+const loggerMiddleware = (
+  meta = { url: '' },
+  logLevel = 'info',
+  skip = (req, res) => process.env.NODE_ENV === 'production',
+  enableFileLogs = process.env.ENABLE_FILE_LOGS === 'true' || process.env.ENABLE_FILE_LOGS === true,
+) => {
+  const stream = {
+    // Use the http severity
+    write: (message) => loggerFactory(meta, logLevel, enableFileLogs).http(message),
+  };
+
+  morgan.token('host', function (req, res) {
+    return req.headers['host'];
+  });
+
+  return morgan(
+    // Define message format string
+    `:remote-addr :method :host:url :status :res[content-length] - :response-time ms`,
+    { stream, skip },
+  );
+};
+
+const underpostASCII = () => `
+
+██╗░░░██╗███╗░░██╗██████╗░███████╗██████╗░██████╗░░█████╗░░██████╗████████╗
+██║░░░██║████╗░██║██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔════╝╚══██╔══╝
+██║░░░██║██╔██╗██║██║░░██║█████╗░░██████╔╝██████╔╝██║░░██║╚█████╗░░░░██║░░░
+██║░░░██║██║╚████║██║░░██║██╔══╝░░██╔══██╗██╔═══╝░██║░░██║░╚═══██╗░░░██║░░░
+╚██████╔╝██║░╚███║██████╔╝███████╗██║░░██║██║░░░░░╚█████╔╝██████╔╝░░░██║░░░
+░╚═════╝░╚═╝░░╚══╝╚═════╝░╚══════╝╚═╝░░╚═╝╚═╝░░░░░░╚════╝░╚═════╝░░░░╚═╝░░░
+                                                `;
+
+const actionInitLog = () =>
+  console.log(
+    underpostASCII() +
+      `
+    https://www.nexodev.org/docs
+`,
+  );
+
+export { loggerFactory, loggerMiddleware, setUpInfo, underpostASCII, actionInitLog };

package/src/server/middlewares.js

@@ -0,0 +1,152 @@
+/**
+ * Express middleware and controller/router helpers for engine APIs.
+ *
+ * @module src/server/middlewares.js
+ */
+
+import { loggerFactory } from './logger.js';
+import { moderatorGuard, adminGuard } from './auth.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * The public-read CORS policy: reflect the request origin (or allow any)
+ * and mark the resource embeddable cross-origin.
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ */
+const setCrossOriginHeaders = (req, res) => {
+  if (req && req.headers && req.headers.origin) res.set('Access-Control-Allow-Origin', req.headers.origin);
+  else res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');
+};
+
+/** Express middleware form of {@link setCrossOriginHeaders}. */
+const crossOriginMiddleware = (req, res, next) => {
+  setCrossOriginHeaders(req, res);
+  next();
+};
+
+/**
+ * Shallow request copy with `page`/`limit` parsed to integers.
+ * `path` and `params` are copied explicitly because spreading an Express
+ * request drops prototype getters.
+ * @param {import('express').Request} req
+ */
+const withParsedPagination = (req) => {
+  const { page, limit } = req.query;
+  return {
+    ...req,
+    path: req.path,
+    params: req.params,
+    query: { ...req.query, page: parseInt(page), limit: parseInt(limit) },
+  };
+};
+
+const sendSuccess = (res, data) => res.status(200).json({ status: 'success', data });
+
+const sendError = (res, error, status = 400) => res.status(status).json({ status: 'error', message: error.message });
+
+/**
+ * Binary response with cross-origin and content headers.
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {{ buffer: Buffer, mimetype: string, filename: string, disposition?: 'inline'|'attachment' }} blob
+ */
+const sendBlob = (req, res, { buffer, mimetype, filename, disposition = 'inline' }) => {
+  setCrossOriginHeaders(req, res);
+  res.setHeader('Content-Type', mimetype);
+  res.setHeader('Content-Length', buffer.length);
+  res.setHeader('Content-Disposition', `${disposition}; filename="${filename}"`);
+  return res.status(200).end(buffer);
+};
+
+/**
+ * Wraps a controller body with error logging and the error response envelope.
+ * @param {(req, res, options) => Promise<any>} fn
+ * @param {{ errorStatus?: number }} [config]
+ */
+const controllerHandler =
+  (fn, { errorStatus = 400 } = {}) =>
+  async (req, res, options) => {
+    try {
+      return await fn(req, res, options);
+    } catch (error) {
+      logger.error(error, error.stack);
+      return sendError(res, error, errorStatus);
+    }
+  };
+
+/**
+ * Builds a controller method that delegates to a service method and wraps the
+ * result in the success envelope.
+ * @param {(req, res, options) => Promise<any>} serviceFn
+ * @param {{ errorStatus?: number, crossOrigin?: boolean, pagination?: boolean }} [config]
+ */
+const serviceHandler = (serviceFn, { errorStatus = 400, crossOrigin = false, pagination = false } = {}) =>
+  controllerHandler(
+    async (req, res, options) => {
+      if (crossOrigin) setCrossOriginHeaders(req, res);
+      const result = await serviceFn(pagination ? withParsedPagination(req) : req, res, options);
+      return sendSuccess(res, result);
+    },
+    { errorStatus },
+  );
+
+/**
+ * Builds a standard CRUD controller class (static post/get/put/delete) from a
+ * service exposing the same methods. `get` parses pagination.
+ * @param {{ post, get, put, delete }} service
+ * @param {Object<string, Function>} [extend] - Extra or overriding static handlers.
+ */
+const buildCrudController = (service, extend = {}) => {
+  class CrudController {
+    static post = serviceHandler(service.post);
+    static get = serviceHandler(service.get, { pagination: true });
+    static put = serviceHandler(service.put);
+    static delete = serviceHandler(service.delete);
+  }
+  Object.assign(CrudController, extend);
+  return CrudController;
+};
+
+/**
+ * Registers the standard CRUD routes with the standard guard policy:
+ * public reads, moderator-guarded writes, admin-guarded collection delete.
+ * Custom routes must be registered before calling this (generic `/:id` routes
+ * capture everything).
+ * @param {import('express').Router} router
+ * @param {{ post, get, put, delete }} Controller
+ * @param {import('../../api/types.js').RouterOptions} options
+ * @param {{ readGuards?: Function[], writeGuards?: Function[], deleteAllGuards?: Function[] }} [config]
+ *   Pass empty arrays for unguarded endpoints (e.g. player-written progress)
+ *   or explicit guard chains (e.g. admin-only reads).
+ * @returns {import('express').Router}
+ */
+const registerCrudRoutes = (router, Controller, options, { readGuards = [], writeGuards, deleteAllGuards } = {}) => {
+  const write = writeGuards ?? [options.authMiddleware, moderatorGuard];
+  const deleteAll = deleteAllGuards ?? [options.authMiddleware, adminGuard];
+  const handle = (method) => async (req, res) => await Controller[method](req, res, options);
+  router.post(`/:id`, ...write, handle('post'));
+  router.post(`/`, ...write, handle('post'));
+  router.get(`/:id`, ...readGuards, handle('get'));
+  router.get(`/`, ...readGuards, handle('get'));
+  router.put(`/:id`, ...write, handle('put'));
+  router.put(`/`, ...write, handle('put'));
+  router.delete(`/:id`, ...write, handle('delete'));
+  router.delete(`/`, ...deleteAll, handle('delete'));
+  return router;
+};
+
+export {
+  setCrossOriginHeaders,
+  crossOriginMiddleware,
+  withParsedPagination,
+  sendSuccess,
+  sendError,
+  sendBlob,
+  controllerHandler,
+  serviceHandler,
+  buildCrudController,
+  registerCrudRoutes,
+};

package/src/server/peer.js

@@ -0,0 +1,75 @@
+/**
+ * Module for peerjs server management.
+ * Initializes and configures the PeerJS server instance, typically running
+ * alongside a main Node.js application.
+ *
+ * @module src/server/peer.js
+ * @namespace Peer
+ */
+
+import { PeerServer } from 'peer';
+import dotenv from 'dotenv';
+import { loggerFactory } from './logger.js';
+import Underpost from '../index.js';
+
+/**
+ * Logger instance for this module, utilizing the framework's factory.
+ * @type {function(*): void}
+ * @memberof Peer
+ * @private
+ */
+const logger = loggerFactory(import.meta);
+
+// Documentation references:
+// https://github.com/peers/peerjs
+// https://github.com/peers/peerjs-server
+
+/**
+ * Creates and starts a configured PeerJS server instance.
+ *
+ * This function handles port configuration, CORS origins, and paths, then uses
+ * a listener factory to start the server.
+ *
+ * @async
+ * @function createPeerServer
+ * @memberof Peer
+ * @param {object} config - Configuration object for the PeerJS server setup.
+ * @param {number} config.port - The primary port on which the PeerJS server will listen.
+ * @param {string[]} config.origins - An array of allowed domain origins for Cross-Origin Resource Sharing (CORS).
+ * @param {string} config.path - The base path for the API. The PeerJS path ('/peer') will be appended to this.
+ * @returns {Promise<object>} A promise that resolves to an object containing the final configuration and the server instance.
+ * @returns {import('peer').IConfig} return.options - The final options object used to create the PeerServer.
+ * @returns {import('peer').Server} return.peerServer - The created and listening PeerServer instance (wrapped by the listening server factory).
+ * @returns {object} return.meta - The module's import meta object (`import.meta`).
+ */
+const createPeerServer = async ({ port, origins, path }) => {
+  logger.info('origins', origins);
+
+  // In development, allow the local client origin (peer runs on port+1 relative to the client)
+  if (process.env.NODE_ENV === 'development') {
+    const clientPort = port - 1;
+    const devOrigin = `http://localhost:${clientPort}`;
+    if (!origins.includes(devOrigin)) origins.push(devOrigin);
+  }
+
+  /** @type {import('peer').IConfig} */
+  const options = {
+    port,
+    // Ensure the path is correctly formatted, handling the root path case
+    path: `${path === '/' ? '' : path}/peer`,
+    corsOptions: {
+      origin: origins,
+    },
+    proxied: true,
+    // key: fs.readFileSync(''), // Example for HTTPS/SSL
+    // cert: fs.readFileSync(''), // Example for HTTPS/SSL
+    // ca: fs.readFileSync(''),   // Example for HTTPS/SSL
+  };
+
+  // Use the framework's factory to listen on the server, ensuring graceful startup/shutdown
+  const peerServer = Underpost.start.listenServerFactory(async () => PeerServer(options));
+
+  return { options, peerServer, meta: import.meta };
+};
+
+export { createPeerServer };