@underpostnet/cyberia 3.3.0 → 3.3.76

package/src/projects/cyberia/hot-reload-trigger.js

@@ -1,30 +1,25 @@
 /**
- * Hot-reload trigger — engine-cyberia → cyberia-server control channel.
+ * Hot-reload trigger — the engine's control channel to a running game server.
  *
- * Asks a running cyberia-server to rebuild its world NOW instead of waiting
- * for its polling loop (ENGINE_GRPC_RELOAD_INTERVAL_SEC). Two transports, in
- * order:
+ * Asks the server to rebuild its world now instead of waiting for its polling
+ * loop. Two transports, in order:
  *
- *   1. gRPC  — cyberia-server's CyberiaControlService. Preferred.
- *   2. REST  — POST {baseUrl}/api/v1/hot-reload. Fallback when the control
- *              gRPC port is unreachable (not exposed, different network).
+ *   1. gRPC, the server's CyberiaControlService. Preferred.
+ *   2. REST, POST {baseUrl}/api/v1/hot-reload. Used when the control gRPC port
+ *      is unreachable.
  *
- * The gRPC control service is served with a JSON codec, so this client is
- * hand-rolled with makeUnaryRequest + JSON serializers — no .proto codegen on
- * either side. Keep SERVICE/METHOD in sync with cyberia-server/hotreload/grpc.go.
+ * The control service uses a JSON codec, so this client is hand-rolled with
+ * makeUnaryRequest and JSON serializers. There is no .proto codegen; SERVICE
+ * and METHOD must match the server's control service.
  *
- * AUTHORIZATION
- * -------------
- * Both transports carry CYBERIA_SERVER_API_KEY, the INTERNAL shared secret
- * between engine-cyberia and cyberia-server. It is read from the environment
- * here and never returned to a browser: the engine's REST endpoint is the only
- * public surface, and it is moderator/admin guarded.
+ * Both transports carry CYBERIA_SERVER_API_KEY, the internal shared secret. It
+ * is read from the environment and never returned to a browser.
  *
  * @module src/projects/cyberia/hot-reload-trigger.js
  */
 
 import * as grpc from '@grpc/grpc-js';
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -49,11 +44,9 @@ const serverApiKey = () => process.env.CYBERIA_SERVER_API_KEY || '';
  * gRPC target. The gRPC host reuses the hostname with the control port, since
  * the control service listens on its own port.
  *
- * The URL sub-path is preserved as `basePath` ("", "/FOREST", "/TEST") and kept
- * on `restBaseUrl`: a path-based multi-instance proxy routes the REST trigger to
- * the right variant, and cyberia-server consumes that same base path natively.
- * Using `url.origin` alone would drop the sub-path and land every trigger on the
- * default (root) deployment.
+ * The URL sub-path is kept as `basePath` ("", "/FOREST", "/TEST") and stays on
+ * `restBaseUrl`. A path-based multi-instance proxy routes the REST trigger by
+ * it; `url.origin` alone would send every trigger to the root deployment.
  */
 const resolveTargets = (rawUrl, { grpcPort = DEFAULT_GRPC_PORT } = {}) => {
   const trimmed = String(rawUrl || '').trim();
@@ -133,11 +126,8 @@ const triggerHotReload = async ({
   const { restBaseUrl, grpcTarget, basePath } = resolveTargets(serverUrl, { grpcPort });
   const call = { apiKey, mode, instanceCode, timeoutMs };
 
-  // A path-based multi-instance proxy routes by URL sub-path, but a gRPC method
-  // path is fixed (/cyberia.CyberiaControlService/…) and can't carry the
-  // /FOREST prefix — a control call to hostname:port reaches the default
-  // variant. When the target names a variant sub-path, use the sub-path-aware
-  // REST transport directly instead of triggering the wrong world over gRPC.
+  // A gRPC method path is fixed and cannot carry the variant sub-path, so a
+  // control call would reach the default variant. Use REST for a sub-path target.
   if (basePath) {
     const result = await triggerViaRest({ ...call, restBaseUrl });
     logger.info(`hot reload via REST ${restBaseUrl}: ${result?.message}`);
@@ -149,8 +139,7 @@ const triggerHotReload = async ({
     logger.info(`hot reload via gRPC ${grpcTarget}: ${result?.message}`);
     return { transport: 'grpc', result };
   } catch (grpcError) {
-    // A rejected key is a real answer, not a transport failure — do not retry
-    // over REST, or a misconfigured key would be reported twice.
+    // A rejected key is an answer, not a transport failure. Do not retry.
     if (grpcError?.code === grpc.status.PERMISSION_DENIED) throw new Error(grpcError.details || grpcError.message);
     logger.warn(`hot reload gRPC (${grpcTarget}) unavailable: ${grpcError.message} — falling back to REST`);
 

package/src/projects/cyberia/instance-backup.js

@@ -0,0 +1,210 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
+import { loggerFactory } from '../../server/ops/logger.js';
+import { createPinRecord } from '../../api/ipfs/ipfs.service.js';
+import { IpfsClient } from './ipfs-client.js';
+import { documentFileIds } from '../../api/file/file.ref.js';
+import { ATLAS_FILE_FIELDS, AtlasSpriteSheetStore, atlasMfsPaths } from './atlas-sprite-sheet-store.js';
+import { DEFAULT_ATLAS_UPSCALE_FACTOR } from './atlas-sprite-sheet-generator.js';
+import { ObjectLayerEngine } from './object-layer.js';
+
+const logger = loggerFactory(import.meta);
+
+/* The `files/` name each atlas render is exported under; one per registered File field, so an
+ * export overwrites its own previous copy instead of leaving one behind. */
+const ATLAS_BACKUP_FILE_PREFIX = { fileId: 'atlas', minifyFileId: 'atlas-minify', idlePreviewFileId: 'atlas-idle' };
+export const atlasBackupFileKey = (field, itemKey) => `${ATLAS_BACKUP_FILE_PREFIX[field]}-${itemKey}`;
+
+/* A File's bytes as the export wrote them: base64, or a serialised Buffer. */
+const decodeFileData = (data) => {
+  if (!data) return data;
+  if (data.$base64) return Buffer.from(data.$base64, 'base64');
+  if (data.type === 'Buffer' && Array.isArray(data.data)) return Buffer.from(data.data);
+  return data;
+};
+
+const readJsonIfPresent = (file) => (fs.existsSync(file) ? fs.readJsonSync(file) : null);
+
+/**
+ * Reads everything an instance backup holds for one object layer.
+ *
+ * The object layer names its render frames and atlas by `_id`; the atlas names its render
+ * Files the same way. Files are matched on that `_id`, never on file name, so a backup that
+ * renamed its renders still resolves. The IPFS payloads are the raw bytes behind the three
+ * CIDs the item references, when the backup carried them.
+ *
+ * @param {{backupDir: string, itemId: string}} params
+ * @returns {{
+ *   objectLayer: object, renderFrames: object|null, atlas: object|null,
+ *   files: object[], payloads: Map<string, Buffer>,
+ * }}
+ * @throws {Error} When the backup has no object layer for the item.
+ */
+export function readObjectLayerBackup({ backupDir, itemId }) {
+  const objectLayer = readJsonIfPresent(path.join(backupDir, 'object-layers', `${itemId}.json`));
+  if (!objectLayer) throw new Error(`Backup at ${backupDir} has no object layer '${itemId}'`);
+
+  const renderFrames = readJsonIfPresent(path.join(backupDir, 'render-frames', `${itemId}.json`));
+  const atlas = readJsonIfPresent(path.join(backupDir, 'atlas-sprite-sheets', `${itemId}.json`));
+
+  const wanted = new Set(documentFileIds(atlas ? [atlas] : [], ATLAS_FILE_FIELDS));
+  const filesDir = path.join(backupDir, 'files');
+  const files = [];
+  if (wanted.size > 0 && fs.existsSync(filesDir)) {
+    for (const name of fs.readdirSync(filesDir)) {
+      if (!name.endsWith('.json')) continue;
+      const doc = fs.readJsonSync(path.join(filesDir, name));
+      if (!wanted.has(String(doc._id))) continue;
+      files.push({ ...doc, data: decodeFileData(doc.data) });
+    }
+  }
+
+  const payloads = new Map();
+  const contentDir = path.join(backupDir, 'ipfs', 'content');
+  for (const cid of [objectLayer.cid, objectLayer.data?.render?.cid, objectLayer.data?.render?.metadataCid]) {
+    if (!cid) continue;
+    const payload = path.join(contentDir, `${cid}.bin`);
+    if (fs.existsSync(payload)) payloads.set(cid, fs.readFileSync(payload));
+  }
+
+  return { objectLayer, renderFrames, atlas, files, payloads };
+}
+
+/* Re-adds one payload and pins it under its canonical path. Returns the CID IPFS assigned, or
+ * the backup's own when IPFS is unreachable, so the documents still point at something real. */
+const restorePayload = async ({ cid, payload, mfsPath, resourceType, options }) => {
+  if (!payload) return cid;
+  const added = await IpfsClient.addToIpfs(payload, path.basename(mfsPath), mfsPath);
+  if (!added?.cid) {
+    logger.warn(`IPFS add failed for ${mfsPath}; keeping the backup CID ${cid}`);
+    return cid;
+  }
+  if (added.cid !== cid) logger.warn(`IPFS assigned ${added.cid} to ${mfsPath}; the backup said ${cid}`);
+  await createPinRecord({ cid: added.cid, resourceType, mfsPath, options });
+  return added.cid;
+};
+
+/**
+ * Restores one object layer from an instance backup, making the backup the authority for that
+ * item id: its render frames, atlas, atlas render Files, IPFS pins and payloads, and the static
+ * frame PNGs, replacing whatever the database holds under that id.
+ *
+ * Payloads go to IPFS first, so the documents are written with the CIDs IPFS actually
+ * assigned. `_id`s are kept, so references between the restored documents stay intact.
+ *
+ * @param {{backupDir: string, itemId: string, options: {host: string, path: string}}} params
+ * @returns {Promise<{itemId: string, files: number, renderFrames: boolean, atlas: boolean, pins: number, staticFiles: number}>}
+ */
+export async function restoreObjectLayerBackup({ backupDir, itemId, options }) {
+  const { objectLayer, renderFrames, atlas, files, payloads } = readObjectLayerBackup({ backupDir, itemId });
+  const ObjectLayer = DataBaseProviderService.getModel('ObjectLayer', options);
+  const ObjectLayerRenderFrames = DataBaseProviderService.getModel('ObjectLayerRenderFrames', options);
+  const AtlasSpriteSheet = DataBaseProviderService.getModel('AtlasSpriteSheet', options);
+  const File = DataBaseProviderService.getModel('File', options);
+
+  // 1. IPFS, so every CID below is one the node will serve.
+  const mfs = atlasMfsPaths(itemId);
+  const targets = [
+    {
+      key: 'cid',
+      get: () => objectLayer.cid,
+      set: (v) => (objectLayer.cid = v),
+      mfsPath: `/object-layer/${itemId}/${itemId}_data.json`,
+      resourceType: 'object-layer-data',
+    },
+    {
+      key: 'render',
+      get: () => objectLayer.data?.render?.cid,
+      set: (v) => (objectLayer.data.render.cid = v),
+      mfsPath: mfs.png,
+      resourceType: 'atlas-sprite-sheet',
+    },
+    {
+      key: 'metadata',
+      get: () => objectLayer.data?.render?.metadataCid,
+      set: (v) => (objectLayer.data.render.metadataCid = v),
+      mfsPath: mfs.metadata,
+      resourceType: 'atlas-metadata',
+    },
+  ];
+  let pins = 0;
+  for (const target of targets) {
+    const cid = target.get();
+    if (!cid) continue;
+    const finalCid = await restorePayload({
+      cid,
+      payload: payloads.get(cid),
+      mfsPath: target.mfsPath,
+      resourceType: target.resourceType,
+      options,
+    });
+    if (payloads.has(cid)) pins++;
+    target.set(finalCid);
+    if (target.key === 'render' && atlas) atlas.cid = finalCid;
+  }
+
+  // 2. Documents, leaves first so every reference resolves as it lands.
+  for (const file of files) {
+    await File.deleteOne({ _id: file._id });
+    await File.create(file);
+  }
+  if (renderFrames?._id) {
+    await ObjectLayerRenderFrames.deleteOne({ _id: renderFrames._id });
+    await ObjectLayerRenderFrames.create(renderFrames);
+  }
+  if (atlas) {
+    await AtlasSpriteSheet.deleteOne({ _id: atlas._id });
+    await AtlasSpriteSheet.deleteOne({ 'metadata.itemKey': itemId });
+    await AtlasSpriteSheet.create(atlas);
+    // A backup from before the still existed restores without one; cut it from the render now.
+    await AtlasSpriteSheetStore.syncIdlePreview({ itemKey: itemId, options });
+    await AtlasSpriteSheetStore.pruneOrphanRenders({ options });
+  }
+  // An item the database already has keeps its own _id and takes the backup's values, so an
+  // item id can never fork into two documents.
+  const existing = await ObjectLayer.findByItemId(itemId);
+  if (!existing && objectLayer._id) await ObjectLayer.deleteOne({ _id: objectLayer._id });
+  await ObjectLayer.upsertByItemId(objectLayer);
+
+  // An atlas restored without its minified render cannot be served, and a render cut from the
+  // frames alone is refused wherever the stored layout moved: regenerate the whole atlas from
+  // the frames just restored, and relink the object layer to it.
+  if (atlas && !atlas.minifyFileId && renderFrames) {
+    const live = await ObjectLayer.findByItemId(itemId);
+    const { atlasDoc, atlasCid, atlasMetadataCid } = await AtlasSpriteSheetStore.persist({
+      itemKey: itemId,
+      objectLayerRenderFrames: renderFrames,
+      options,
+    });
+    live.atlasSpriteSheetId = atlasDoc._id;
+    if (!live.data.render) live.data.render = {};
+    live.data.render.cid = atlasCid;
+    live.data.render.metadataCid = atlasMetadataCid;
+    live.markModified('data.render');
+    await live.save();
+    await ObjectLayerEngine.computeAndSaveFinalSha256({ objectLayer: live, options });
+    logger.info(`Rebuilt the atlas of '${itemId}': the backup carried no minified render`);
+  }
+
+  // 3. The static frame PNGs the web client serves, from the same render frames.
+  let staticFiles = 0;
+  const itemType = objectLayer.data?.item?.type;
+  if (renderFrames && itemType) {
+    const written = await ObjectLayerEngine.writeStaticFrameAssets({
+      basePaths: ['./src/client/public/cyberia/', `./public/${options.host}${options.path}`],
+      itemType,
+      itemId,
+      objectLayerRenderFramesData: {
+        frames: renderFrames.frames || {},
+        colors: renderFrames.colors || [],
+        frame_duration: renderFrames.frame_duration ?? 100,
+      },
+      objectLayerData: objectLayer,
+      cellPixelDim: DEFAULT_ATLAS_UPSCALE_FACTOR,
+    });
+    staticFiles = written.length;
+  }
+
+  return { itemId, files: files.length, renderFrames: !!renderFrames, atlas: !!atlas, pins, staticFiles };
+}