underpost 3.2.70 → 3.2.80

package/src/server/conf.js

@@ -1772,6 +1772,165 @@ const loadConfServerJson = (jsonPath, options) => {
   return options && options.resolve === true ? resolveConfSecrets(raw) : raw;
 };
 
+/**
+ * @method deepReplaceToken
+ * @description Recursively replaces every occurrence of `from` with `to` in all
+ * string leaves of a JSON-shaped value, returning a new structure.
+ * @param {*} value - Any JSON-serialisable value.
+ * @param {string} from - Token to replace.
+ * @param {string} to - Replacement token.
+ * @returns {*} A structurally identical value with the token replaced.
+ * @memberof ServerConfBuilder
+ */
+const deepReplaceToken = (value, from, to) => {
+  if (typeof value === 'string') return value.split(from).join(to);
+  if (Array.isArray(value)) return value.map((entry) => deepReplaceToken(entry, from, to));
+  if (value && typeof value === 'object')
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, deepReplaceToken(v, from, to)]));
+  return value;
+};
+
+/**
+ * @method readConfInstances
+ * @description Reads `conf.instances.json` and returns the bare array of instance
+ * entries. The canonical shape is a plain array; the historical `{ instances }`
+ * object wrapper is still unwrapped for backward compatibility. Multi-instance is
+ * declared per entry under `entry.multiInstance` (not deploy-wide).
+ * @param {string} deployId - Deployment identifier (e.g. `dd-cyberia`).
+ * @returns {Array<object>} Instance entries.
+ * @memberof ServerConfBuilder
+ */
+const readConfInstances = (deployId) => {
+  const raw = JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.instances.json`, 'utf8'));
+  return Array.isArray(raw) ? raw : raw.instances || [];
+};
+
+/**
+ * @method loadInstanceTopology
+ * @description Returns `{ default, variants }` describing the deploy's instance
+ * variants, or `null` when the deploy is single-instance. The topology is
+ * declared per instance entry (`entry.multiInstance.default` / `.variants`); all
+ * multi-instance entries share the same variant set, so this returns it from the
+ * first entry that declares one.
+ * @param {string} deployId - Deployment identifier (e.g. `dd-cyberia`).
+ * @returns {?{default: string, variants: Array<object>}} The topology, or `null`.
+ * @memberof ServerConfBuilder
+ */
+const loadInstanceTopology = (deployId) => {
+  for (const entry of readConfInstances(deployId)) {
+    const mi = entry.multiInstance;
+    if (mi && Array.isArray(mi.variants) && mi.variants.length > 0)
+      return { default: mi.default || mi.variants[0].code, variants: mi.variants };
+  }
+  return null;
+};
+
+/**
+ * @method resolveInstanceEnvValue
+ * @description Resolves one declared env value. A plain string is used verbatim;
+ * an object is treated as env-scoped (`{ development, production }`), matching the
+ * convention already used by `lifecycle` / `readinessProbe` / `livenessProbe`.
+ * Placeholders are substituted from the variant tokens.
+ * @param {string|object} value - Declared value.
+ * @param {string} env - `development` | `production`.
+ * @param {Object<string,string>} tokens - Placeholder name → replacement.
+ * @returns {?string} Resolved value, or `null` when the env has no entry.
+ * @memberof ServerConfBuilder
+ */
+const resolveInstanceEnvValue = (value, env, tokens) => {
+  const scoped = value && typeof value === 'object' && !Array.isArray(value) ? value[env] : value;
+  if (scoped === undefined || scoped === null) return null;
+  return `${scoped}`.replace(/\{\{(\w+)\}\}/g, (match, token) => (token in tokens ? tokens[token] : match));
+};
+
+/**
+ * @method loadConfInstances
+ * @description Loads `conf.instances.json` and expands every entry carrying a
+ * `multiInstance` block into one concrete instance per declared variant.
+ *
+ * A template entry is never deployed as-is once variants exist: each variant
+ * produces its own entry whose id, env file path, volume mount and
+ * container-status strings are derived by replacing the template id token
+ * throughout. The variant whose `slug` is empty keeps the template id verbatim,
+ * so pre-existing deployments, PVCs and env directories survive the move to
+ * multi-instance untouched.
+ *
+ * Nothing here is application-specific: the variant set (`default` + `variants`),
+ * which env keys an instance needs (`env`), and prefix-stripping (`stripPathPrefix`)
+ * are all declared per entry under `entry.multiInstance`. Env values may use the
+ * `{{code}}`, `{{slug}}`, `{{path}}`, `{{id}}` and `{{default}}` placeholders and
+ * may be env-scoped objects.
+ *
+ * Every expanded entry carries three extra fields consumed by the deploy runners:
+ * `instanceCode` (the variant this instance serves), `templateId` (so targeting
+ * the template id acts on the whole family) and `instanceEnv` (the resolved env
+ * keys to write, keyed by environment: `{ development, production }`, so a build
+ * in either mode can emit a complete env directory).
+ *
+ * @param {string} deployId - Deployment identifier (e.g. `dd-cyberia`).
+ * @returns {Array<object>} Expanded instance entries.
+ * @memberof ServerConfBuilder
+ */
+const INSTANCE_ENVS = ['development', 'production'];
+
+const loadConfInstances = (deployId) => {
+  const expanded = [];
+  for (const entry of readConfInstances(deployId)) {
+    const spec = entry.multiInstance;
+    const variants = spec?.variants;
+    if (!Array.isArray(variants) || 0 === variants.length) {
+      expanded.push(entry);
+      continue;
+    }
+    for (const variant of variants) {
+      const id = variant.slug ? `${entry.id}-${variant.slug}` : entry.id;
+      const instance = variant.slug ? deepReplaceToken(entry, entry.id, id) : JSON.parse(JSON.stringify(entry));
+      delete instance.multiInstance;
+      instance.id = id;
+      instance.path = variant.path;
+      instance.instanceCode = variant.code;
+      instance.templateId = entry.id;
+
+      const tokens = {
+        code: variant.code,
+        slug: variant.slug || '',
+        path: variant.path,
+        id,
+        default: spec.default || '',
+      };
+      // Resolve the declared env keys for both environments so a build in either
+      // mode writes a complete env directory (development.env + production.env).
+      instance.instanceEnv = Object.fromEntries(INSTANCE_ENVS.map((e) => [e, {}]));
+      for (const [key, value] of Object.entries(spec.env || {}))
+        for (const e of INSTANCE_ENVS) {
+          const resolved = resolveInstanceEnvValue(value, e, tokens);
+          if (resolved !== null) instance.instanceEnv[e][key] = resolved;
+        }
+
+      // A backend that serves its routes at the root knows nothing about the
+      // variant prefix — it is selected by env instead. Strip the prefix at the
+      // proxy so the runtime stays instance-agnostic.
+      if (spec.stripPathPrefix && variant.path !== '/')
+        instance.pathRewritePolicy = [{ prefix: variant.path, replacement: '/' }];
+      expanded.push(instance);
+    }
+  }
+  return expanded;
+};
+
+/**
+ * @method selectConfInstances
+ * @description Filters expanded instances for a deploy target. Targeting a
+ * template id (`mmo-server`) selects the whole instance family; targeting a
+ * concrete id (`mmo-server-forest`) selects just that one.
+ * @param {Array<object>} instances - Expanded entries from {@link loadConfInstances}.
+ * @param {string} id - Target instance id or template id.
+ * @returns {Array<object>} Matching entries.
+ * @memberof ServerConfBuilder
+ */
+const selectConfInstances = (instances, id) =>
+  instances.filter((instance) => instance.id === id || instance.templateId === id);
+
 /**
  * Creates and writes the /etc/hosts file for a deployment.
  * @method etcHostFactory
@@ -2100,6 +2259,10 @@ git add .`);
 export {
   Config,
   loadConf,
+  loadConfInstances,
+  loadInstanceTopology,
+  readConfInstances,
+  selectConfInstances,
   loadReplicas,
   cloneConf,
   getCapVariableName,

package/src/server/downloader.js

@@ -41,18 +41,18 @@ class Downloader {
           const writer = fs.createWriteStream(fullPath);
           response.data.pipe(writer);
           writer.on('finish', () => {
-            logger.info('Download complete. File saved at', fullPath);
+            logger.info('Download completet');
             return resolve(fullPath);
           });
           writer.on('error', (error) => {
-            logger.error(error, 'Error downloading the file');
+            logger.error('Error downloading the file');
             // Cleanup incomplete file if possible
             if (fs.existsSync(fullPath)) fs.unlinkSync(fullPath);
             return reject(error);
           });
         })
         .catch((error) => {
-          logger.error(error, 'Error in the request');
+          logger.error('Error in the request');
           return reject(error);
         }),
     );

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,
+};