cyberia 3.2.12 → 3.2.70

package/src/server/runtime-status.js

@@ -0,0 +1,252 @@
+/**
+ * Runtime status contract and the in-pod internal status endpoint.
+ *
+ * Single source of truth for the Underpost runtime readiness signal (Phase 2 of
+ * the two-phase deployment monitor). The runtime publishes its lifecycle here;
+ * the CD-side monitor (`src/cli/monitor.js`) reads it over HTTP via
+ * `kubectl port-forward`. Kubernetes pod readiness (Phase 1) is owned by kubelet
+ * and is intentionally not modeled in this module.
+ *
+ * Cross-process contract:
+ *   - In-pod, the canonical value lives in the underpost root env key
+ *     `container-status`, written by `start.js`. For non-error phases it carries
+ *     the namespaced form `<deployId>-<env>-<phase>`; a fatal fault collapses to
+ *     the bare value `error`.
+ *   - The internal HTTP server exposes that value (normalized to the bare
+ *     contract phase) and never exposes secrets, env dumps, or configuration.
+ *
+ * @module src/server/runtime-status.js
+ * @namespace RuntimeStatus
+ */
+
+import http from 'node:http';
+import fs from 'fs-extra';
+import dotenv from 'dotenv';
+import Underpost from '../index.js';
+import { loggerFactory } from './logger.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * Allowed runtime status contract values. These are the only Phase-2 signals
+ * the monitor reasons about.
+ * @memberof RuntimeStatus
+ */
+const RUNTIME_STATUS = {
+  BUILD: 'build-deployment',
+  INIT: 'initializing-deployment',
+  RUNNING: 'running-deployment',
+  ERROR: 'error',
+};
+
+const CONTAINER_STATUS_KEY = 'container-status';
+const START_CONTAINER_STATUS_KEY = 'start-container-status';
+const INTERNAL_STATUS_PATH = '/_internal/status';
+const INTERNAL_READY_PATH = '/_internal/ready';
+const INTERNAL_HEALTH_PATH = '/_internal/health';
+
+/**
+ * Resolves the internal status port. Defaults to the deployment base `PORT`
+ * (app instances bind `PORT + 1` upward, so the base port is free inside the
+ * pod). An explicit `UNDERPOST_INTERNAL_PORT` override wins.
+ * @memberof RuntimeStatus
+ * @returns {number|undefined}
+ */
+const resolveInternalStatusPort = () => {
+  const raw = process.env.UNDERPOST_INTERNAL_PORT || process.env.PORT;
+  const port = parseInt(raw);
+  return Number.isNaN(port) ? undefined : port;
+};
+
+/**
+ * Single source of truth for the internal status port of a specific deployment,
+ * used identically by the in-pod server bind (`start.js`) and the CD-side
+ * monitor target (`monitor.js`) so the two can never disagree.
+ *
+ * Resolution order: `UNDERPOST_INTERNAL_PORT` override → the deployment's
+ * `.env.<env>` `PORT` → the ambient `PORT`.
+ *
+ * @memberof RuntimeStatus
+ * @param {string} deployId
+ * @param {string} env
+ * @returns {number|undefined}
+ */
+const deployStatusPort = (deployId, env) => {
+  const override = parseInt(process.env.UNDERPOST_INTERNAL_PORT);
+  if (!Number.isNaN(override)) return override;
+  try {
+    const envPath = `./engine-private/conf/${deployId}/.env.${env}`;
+    if (fs.existsSync(envPath)) {
+      const port = parseInt(dotenv.parse(fs.readFileSync(envPath, 'utf8')).PORT);
+      if (!Number.isNaN(port)) return port;
+    }
+  } catch (_) {
+    /* fall through to ambient resolution */
+  }
+  return resolveInternalStatusPort();
+};
+
+/**
+ * Builds the `container-status` env value for a lifecycle phase.
+ * @memberof RuntimeStatus
+ */
+const containerStatusValue = (deployId, env, phase) =>
+  phase === RUNTIME_STATUS.ERROR ? RUNTIME_STATUS.ERROR : `${deployId}-${env}-${phase}`;
+
+/**
+ * Normalizes a raw `container-status` value to a bare contract phase.
+ * Strips the `<deployId>-<env>-` prefix; `error` and unknown/empty values are
+ * passed through (empty → undefined).
+ * @memberof RuntimeStatus
+ * @param {string} raw
+ * @returns {string|undefined}
+ */
+const normalizeContainerStatus = (raw) => {
+  if (!raw || typeof raw !== 'string') return undefined;
+  const value = raw.trim();
+  if (!value || value === 'undefined' || value.toLowerCase().includes('empty')) return undefined;
+  if (value === RUNTIME_STATUS.ERROR) return RUNTIME_STATUS.ERROR;
+  for (const phase of [RUNTIME_STATUS.BUILD, RUNTIME_STATUS.INIT, RUNTIME_STATUS.RUNNING])
+    if (value.endsWith(`-${phase}`)) return phase;
+  return value;
+};
+
+/**
+ * Reads the current normalized runtime status from the env file.
+ * @memberof RuntimeStatus
+ * @returns {string|undefined}
+ */
+const getRuntimeStatus = () =>
+  normalizeContainerStatus(Underpost.env.get(CONTAINER_STATUS_KEY, undefined, { disableLog: true }));
+
+/**
+ * Reads the start-container-status env key — an insulated marker set by the
+ * start pipeline after it completes the running phase. Unlike container-status
+ * (which external scripts / backup failures may clobber), this key is written
+ * once and survives globalSecretClean. Used exclusively by the readinessProbe
+ * endpoint so K8s pod readiness is never derailed by lifecycle noise.
+ * @memberof RuntimeStatus
+ * @returns {string|undefined}
+ */
+const getStartContainerStatus = () => {
+  const raw = Underpost.env.get(START_CONTAINER_STATUS_KEY, undefined, { disableLog: true });
+  return raw && typeof raw === 'string' && raw.trim() ? raw.trim() : undefined;
+};
+
+/**
+ * Minimal, secret-free payload served by the internal status endpoint and used
+ * by the monitor for failure classification and observability.
+ * @memberof RuntimeStatus
+ * @returns {{status: (string|null), deployId: (string|null), env: (string|null)}}
+ */
+const runtimeStatusPayload = () => ({
+  status: getRuntimeStatus() ?? null,
+  deployId: process.env.DEPLOY_ID ?? null,
+  env: process.env.NODE_ENV ?? null,
+});
+
+/**
+ * Emits a structured, secret-free deployment transition event.
+ * @memberof RuntimeStatus
+ */
+const emitRuntimeEvent = ({ deployId, env, phase }) => {
+  logger.info('runtime-status', {
+    deployId,
+    env,
+    phase: 'runtime',
+    status: phase,
+    timestamp: new Date().toISOString(),
+  });
+};
+
+/**
+ * Publishes a runtime lifecycle phase to the cross-process contract.
+ * @memberof RuntimeStatus
+ * @param {string} deployId
+ * @param {string} env
+ * @param {string} phase - One of {@link RUNTIME_STATUS}.
+ */
+const setRuntimeStatus = (deployId, env, phase) => {
+  Underpost.env.set(CONTAINER_STATUS_KEY, containerStatusValue(deployId, env, phase));
+  emitRuntimeEvent({ deployId, env, phase });
+};
+
+let internalServer;
+
+/**
+ * Starts the in-pod internal status server. Idempotent: repeated calls return
+ * the already-listening server. Exposes only the three internal endpoints and
+ * never serves secrets or configuration.
+ *
+ *   GET /_internal/status  → 200, `{status, deployId, env}` (monitor transport)
+ *   GET /_internal/ready   → 200 iff running-deployment, else 503 (readinessProbe)
+ *   GET /_internal/health  → 200 while the process is alive (livenessProbe)
+ *
+ * @memberof RuntimeStatus
+ * @param {number} [port]
+ * @returns {import('node:http').Server|undefined}
+ */
+const startInternalStatusServer = (port = resolveInternalStatusPort()) => {
+  if (internalServer) return internalServer;
+  if (!port) {
+    logger.warn('Internal status server not started: no resolvable port');
+    return undefined;
+  }
+  const server = http.createServer((req, res) => {
+    const url = (req.url || '').split('?')[0];
+    const sendJson = (code, body) => {
+      res.writeHead(code, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(body));
+    };
+    if (req.method !== 'GET') return sendJson(405, { error: 'method_not_allowed' });
+    switch (url) {
+      case INTERNAL_HEALTH_PATH:
+        return sendJson(200, { status: 'ok' });
+      case INTERNAL_READY_PATH:
+        return getStartContainerStatus()
+          ? sendJson(200, { status: RUNTIME_STATUS.RUNNING })
+          : sendJson(503, { status: getRuntimeStatus() ?? null });
+      case INTERNAL_STATUS_PATH:
+        return sendJson(200, runtimeStatusPayload());
+      default:
+        return sendJson(404, { error: 'not_found' });
+    }
+  });
+  server.on('error', (error) => logger.error('internal status server error', error?.message ?? error));
+  server.listen(port, () => logger.info(`Internal status endpoint listening on :${port}${INTERNAL_STATUS_PATH}`));
+  internalServer = server;
+  return internalServer;
+};
+
+/**
+ * Stops the internal status server if running. Returns a promise that resolves
+ * once the listener is closed. Primarily a test/teardown hook.
+ * @memberof RuntimeStatus
+ * @returns {Promise<void>}
+ */
+const stopInternalStatusServer = () =>
+  new Promise((resolve) => {
+    if (!internalServer) return resolve();
+    const server = internalServer;
+    internalServer = undefined;
+    server.close(() => resolve());
+  });
+
+export {
+  RUNTIME_STATUS,
+  CONTAINER_STATUS_KEY,
+  START_CONTAINER_STATUS_KEY,
+  INTERNAL_STATUS_PATH,
+  INTERNAL_READY_PATH,
+  INTERNAL_HEALTH_PATH,
+  resolveInternalStatusPort,
+  deployStatusPort,
+  containerStatusValue,
+  normalizeContainerStatus,
+  getRuntimeStatus,
+  getStartContainerStatus,
+  runtimeStatusPayload,
+  setRuntimeStatus,
+  startInternalStatusServer,
+  stopInternalStatusServer,
+};

package/src/server/start.js

@@ -8,6 +8,14 @@ import fs from 'fs-extra';
 import { awaitDeployMonitor } from './conf.js';
 import { actionInitLog, loggerFactory } from './logger.js';
 import { shellCd, shellExec } from './process.js';
+import {
+  RUNTIME_STATUS,
+  START_CONTAINER_STATUS_KEY,
+  setRuntimeStatus,
+  startInternalStatusServer,
+  deployStatusPort,
+  containerStatusValue,
+} from './runtime-status.js';
 import Underpost from '../index.js';
 const logger = loggerFactory(import.meta);
 
@@ -147,10 +155,20 @@ class UnderpostStartUp {
         pullBundle: false,
       },
     ) {
-      Underpost.env.set('container-status', `${deployId}-${env}-build-deployment`);
-      if (options.build === true) await Underpost.start.build(deployId, env, options);
-      Underpost.env.set('container-status', `${deployId}-${env}-initializing-deployment`);
-      if (options.run === true) await Underpost.start.run(deployId, env, options);
+      // Bring the internal status endpoint up first so Phase-2 readiness is
+      // observable through every lifecycle phase, including build and init. Bind
+      // the deployment-resolved port so it always matches the monitor's target.
+      startInternalStatusServer(deployStatusPort(deployId, env));
+      try {
+        setRuntimeStatus(deployId, env, RUNTIME_STATUS.BUILD);
+        if (options.build === true) await Underpost.start.build(deployId, env, options);
+        setRuntimeStatus(deployId, env, RUNTIME_STATUS.INIT);
+        if (options.run === true) await Underpost.start.run(deployId, env, options);
+      } catch (error) {
+        logger.error('Deployment build/init failed', { deployId, env, message: error?.message });
+        setRuntimeStatus(deployId, env, RUNTIME_STATUS.ERROR);
+        if (!Underpost.env.isInsideContainer()) throw error;
+      }
     },
     /**
      * Run itc-scripts and builds client bundle.
@@ -162,6 +180,8 @@ class UnderpostStartUp {
      * @param {boolean} options.skipFullBuild - Whether to skip building the full client bundle.
      * @param {boolean} options.pullBundle - When true, download pre-built client bundle from Cloudinary via pull-bundle (must be pushed first with push-bundle).
      *   This flag is independent of skipFullBuild: it can be combined with skipFullBuild or used alone.
+     * @param {boolean} options.privateTestRepo - When true, clone `engine-test-<id>` (the private test source repo
+     *   published by `node bin/build <deployId> --update-private`) instead of the production `engine-<id>` repo.
      * @memberof UnderpostStartUp
      */
     async build(
@@ -170,7 +190,11 @@ class UnderpostStartUp {
       options = { underpostQuicklyInstall: false, skipPullBase: false, skipFullBuild: false, pullBundle: false },
     ) {
       const buildBasePath = `/home/dd`;
-      const repoName = `engine-${deployId.split('-')[1]}`;
+      // `--private-test-repo` clones the isolated test source repo published by
+      // `node bin/build <deployId> --update-private`, instead of the production one.
+      const repoName = options?.privateTestRepo
+        ? `engine-test-${deployId.split('-')[1]}`
+        : `engine-${deployId.split('-')[1]}`;
       if (!options.skipPullBase) {
         shellExec(`cd ${buildBasePath} && underpost clone ${process.env.GITHUB_USERNAME}/${repoName}`);
         shellExec(`mkdir -p ${buildBasePath}/engine`);
@@ -201,7 +225,7 @@ class UnderpostStartUp {
       const makeDeployCallback = (cmd) => (code, out, msg) => {
         if (code !== 0) {
           logger.error(`Deployment process exited with code ${code}`, { cmd, msg });
-          Underpost.env.set('container-status', 'error');
+          setRuntimeStatus(deployId, env, RUNTIME_STATUS.ERROR);
         }
       };
       if (fs.existsSync(`./engine-private/replica`)) {
@@ -211,18 +235,25 @@ class UnderpostStartUp {
           shellExec(`node bin env ${replica} ${env}`);
           const replicaCmd = `npm ${runCmd} ${replica}`;
           shellExec(replicaCmd, { async: true, callback: makeDeployCallback(replicaCmd) });
-          await awaitDeployMonitor();
+          const result = await awaitDeployMonitor();
+          if (result !== true) {
+            setRuntimeStatus(deployId, env, RUNTIME_STATUS.ERROR);
+            return;
+          }
         }
       }
       shellExec(`node bin env ${deployId} ${env}`);
       const deployCmd = `npm ${runCmd} ${deployId}`;
       shellExec(deployCmd, { async: true, callback: makeDeployCallback(deployCmd) });
-      await awaitDeployMonitor(true);
-      if (Underpost.env.get('container-status') !== 'error') {
+      const result = await awaitDeployMonitor(true);
+      if (result === true) {
         if (env === 'production' && Underpost.env.isInsideContainer()) Underpost.secret.globalSecretClean();
-        Underpost.env.set('container-status', `${deployId}-${env}-running-deployment`);
+        setTimeout(() => {
+          setRuntimeStatus(deployId, env, RUNTIME_STATUS.RUNNING);
+          Underpost.env.set(START_CONTAINER_STATUS_KEY, containerStatusValue(deployId, env, RUNTIME_STATUS.RUNNING));
+        });
       } else {
-        Underpost.env.set('container-status', 'error');
+        setRuntimeStatus(deployId, env, RUNTIME_STATUS.ERROR);
       }
     },
   };

package/src/server.js

@@ -3,18 +3,22 @@
 // https://nodejs.org/api
 // https://expressjs.com/en/4x/api.html
 
+import dotenv from 'dotenv';
 import { loggerFactory } from './server/logger.js';
-import { buildClient } from './server/client-build.js';
+import { buildClient } from './client-builder/client-build.js';
 import { buildRuntime } from './server/runtime.js';
 import { ProcessController } from './server/process.js';
 import { Config } from './server/conf.js';
+
+dotenv.config();
+
 await Config.build();
 
 const logger = loggerFactory(import.meta);
 
 await logger.setUpInfo();
 
-await buildClient();
+if (process.env.NODE_ENV === 'development') await buildClient();
 
 await buildRuntime();
 

package/test/cyberia-instance-conf-defaults.test.js

@@ -0,0 +1,140 @@
+'use strict';
+
+import { expect } from 'chai';
+import {
+  fillInstanceConfDefaults,
+  CYBERIA_INSTANCE_CONF_DEFAULTS,
+} from '../src/api/cyberia-server-defaults/cyberia-server-defaults.js';
+
+// The CyberiaInstanceConfSchema fields that must always be present after a
+// backfill. Mirrors cyberia-instance-conf.model.js (minus instanceCode, which
+// is the lookup key and is only present when the source doc carries it).
+const SCHEMA_FIELDS = [
+  'tickRate',
+  'snapshotRate',
+  'aoiRadius',
+  'portalHoldTimeMs',
+  'portalSpawnRadius',
+  'entityBaseSpeed',
+  'entityBaseMaxLife',
+  'entityBaseActionCooldownMs',
+  'entityBaseMinActionCooldownMs',
+  'botAggroRange',
+  'defaultPlayerWidth',
+  'defaultPlayerHeight',
+  'playerBaseLifeRegenMin',
+  'playerBaseLifeRegenMax',
+  'sumStatsLimit',
+  'maxActiveLayers',
+  'initialLifeFraction',
+  'respawnDurationMs',
+  'collisionLifeLoss',
+  'economyRules',
+  'lifeRegenChance',
+  'maxChance',
+  'entityDefaults',
+  'statusIcons',
+  'skillConfig',
+  'skillRules',
+  'equipmentRules',
+];
+
+describe('fillInstanceConfDefaults', () => {
+  it('fills every schema field from canonical defaults for an empty doc', () => {
+    const out = fillInstanceConfDefaults({});
+    for (const field of SCHEMA_FIELDS) {
+      expect(out, `missing field: ${field}`).to.have.property(field);
+      expect(out[field], `null/undefined field: ${field}`).to.not.equal(undefined);
+      expect(out[field], `null field: ${field}`).to.not.equal(null);
+    }
+    expect(out.tickRate).to.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.tickRate);
+    expect(out.economyRules).to.deep.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.economyRules);
+    expect(out.skillRules).to.deep.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.skillRules);
+    expect(out.equipmentRules).to.deep.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.equipmentRules);
+  });
+
+  it('handles undefined / non-object input as an empty doc', () => {
+    for (const bad of [undefined, null, 42, 'x']) {
+      const out = fillInstanceConfDefaults(bad);
+      for (const field of SCHEMA_FIELDS) expect(out).to.have.property(field);
+    }
+  });
+
+  it('preserves author-set scalar values, including falsy 0 / false / empty string', () => {
+    const out = fillInstanceConfDefaults({
+      tickRate: 30,
+      collisionLifeLoss: 0,
+      portalFee: 0,
+    });
+    expect(out.tickRate).to.equal(30);
+    expect(out.collisionLifeLoss).to.equal(0);
+    // Fields not overridden still come from defaults.
+    expect(out.snapshotRate).to.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.snapshotRate);
+  });
+
+  it('backfills a missing nested sub-document (economyRules)', () => {
+    const out = fillInstanceConfDefaults({ tickRate: 60 });
+    expect(out.economyRules).to.deep.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.economyRules);
+  });
+
+  it('fills only the missing keys of a partial nested sub-document', () => {
+    const out = fillInstanceConfDefaults({
+      economyRules: { botSpawnCoins: 999 },
+    });
+    expect(out.economyRules.botSpawnCoins).to.equal(999);
+    expect(out.economyRules.playerSpawnCoins).to.equal(
+      CYBERIA_INSTANCE_CONF_DEFAULTS.economyRules.playerSpawnCoins,
+    );
+    expect(out.economyRules.portalFee).to.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.economyRules.portalFee);
+  });
+
+  it('keeps a present non-empty array and does not merge defaults into it', () => {
+    const custom = [{ entityType: 'player', liveItemIds: ['anon'], deadItemIds: [], dropItemIds: [] }];
+    const out = fillInstanceConfDefaults({ entityDefaults: custom });
+    expect(out.entityDefaults).to.deep.equal(custom);
+  });
+
+  it('populates an empty skillConfig from defaults, normalised to schema shape (no `skills`)', () => {
+    for (const input of [{}, { skillConfig: [] }, { skillConfig: null }]) {
+      const out = fillInstanceConfDefaults(input);
+      expect(out.skillConfig.length, JSON.stringify(input)).to.be.greaterThan(0);
+      for (const entry of out.skillConfig) {
+        expect(entry).to.have.property('triggerItemId');
+        expect(entry).to.have.property('logicEventIds');
+        expect(entry).to.not.have.property('skills');
+      }
+    }
+  });
+
+  it('keeps an author-set non-empty skillConfig verbatim', () => {
+    const custom = [{ triggerItemId: 'custom-weapon', logicEventIds: ['projectile'] }];
+    const out = fillInstanceConfDefaults({ skillConfig: custom });
+    expect(out.skillConfig).to.deep.equal(custom);
+  });
+
+  it('fills an empty config array (entityDefaults) from defaults', () => {
+    const out = fillInstanceConfDefaults({ entityDefaults: [] });
+    expect(out.entityDefaults.length).to.be.greaterThan(0);
+    expect(out.entityDefaults).to.deep.equal(CYBERIA_INSTANCE_CONF_DEFAULTS.entityDefaults);
+  });
+
+  it('preserves DB metadata (_id, instanceCode, timestamps)', () => {
+    const now = new Date().toISOString();
+    const out = fillInstanceConfDefaults({
+      _id: 'abc123',
+      instanceCode: 'amethyst-strata-expansion',
+      createdAt: now,
+      updatedAt: now,
+    });
+    expect(out._id).to.equal('abc123');
+    expect(out.instanceCode).to.equal('amethyst-strata-expansion');
+    expect(out.createdAt).to.equal(now);
+  });
+
+  it('does not mutate the input document', () => {
+    const input = { economyRules: { botSpawnCoins: 5 } };
+    const snapshot = JSON.parse(JSON.stringify(input));
+    fillInstanceConfDefaults(input);
+    expect(input).to.deep.equal(snapshot);
+  });
+});