@lazyapps/admin-api 0.0.0-init.0

package/index.js

@@ -0,0 +1,43 @@
+import {
+  startReplayHandler,
+  replayStatusHandler,
+  cancelReplayHandler,
+  legacyAdminHandler,
+} from './replay-handlers.js';
+
+import {
+  statusHandler,
+  readModelsHandler,
+  createBackupHandler,
+  listBackupsHandler,
+  deleteBackupHandler,
+  prepareReplayHandler,
+  replayReadModelStatusHandler,
+} from './readmodel-handlers.js';
+
+export const installReplayAdminApi = (context) => (app) => {
+  app.post('/api/admin/startReplay', startReplayHandler(context));
+  app.get('/api/admin/replayStatus/:readModel', replayStatusHandler(context));
+  app.post('/api/admin/cancelReplay', cancelReplayHandler(context));
+
+  // Legacy backward compat for command-replay CLI tool
+  app.post('/api/admin/:command', legacyAdminHandler(context));
+};
+
+export const installReadModelAdminApi = (context) => (app) => {
+  app.get('/admin/status', statusHandler(context));
+  app.get('/admin/readmodels', readModelsHandler(context));
+
+  app.post('/admin/backup/:readModelName', createBackupHandler(context));
+  app.get('/admin/backups/:readModelName', listBackupsHandler(context));
+  app.delete('/admin/backup/:backupId', deleteBackupHandler(context));
+
+  app.post(
+    '/admin/replay/:readModelName/prepare',
+    prepareReplayHandler(context),
+  );
+  app.get(
+    '/admin/replay/:readModelName/status',
+    replayReadModelStatusHandler(context),
+  );
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@lazyapps/admin-api",
+  "version": "0.0.0-init.0",
+  "description": "Admin API route handlers for LazyApps event replay and read model management",
+  "main": "index.js",
+  "files": [
+    "*.js"
+  ],
+  "scripts": {
+    "test": "vitest"
+  },
+  "keywords": [
+    "event-sourcing",
+    "cqrs",
+    "lazyapps",
+    "admin",
+    "replay"
+  ],
+  "author": "Oliver Sturm",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oliversturm/lazyapps-libs.git",
+    "directory": "packages/admin-api"
+  },
+  "bugs": {
+    "url": "https://github.com/oliversturm/lazyapps-libs/issues"
+  },
+  "homepage": "https://github.com/oliversturm/lazyapps-libs/tree/main/packages/admin-api#readme",
+  "engines": {
+    "node": ">=18.20.3 || >=20.18.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.46.0",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@lazyapps/logger": "workspace:^",
+    "nanoid": "^5.0.7"
+  },
+  "type": "module"
+}

package/readmodel-handlers.js

@@ -0,0 +1,261 @@
+import { getLogger } from '@lazyapps/logger';
+import { nanoid } from 'nanoid';
+
+const detectSharedCollections = (readModels, targetName, targetCollections) => {
+  const warnings = [];
+  const targetSet = new Set(targetCollections);
+
+  Object.keys(readModels).forEach((rmName) => {
+    if (rmName === targetName) return;
+    const rm = readModels[rmName];
+    const rmCollections = rm.collections || [rmName];
+    const shared = rmCollections.filter((c) => targetSet.has(c));
+    if (shared.length) {
+      warnings.push(
+        `Read model '${rmName}' shares collections: ${shared.join(', ')}`,
+      );
+    }
+  });
+
+  return warnings;
+};
+
+export const statusHandler = (context) => {
+  const startedAt = Date.now();
+  return (req, res) => {
+    const replayStates = context.projectionHandler.getReadModelReplayStates();
+
+    res.json({
+      service: context.correlationConfig.serviceId,
+      uptime: Date.now() - startedAt,
+      readModels: Object.keys(context.readModels).map((name) => ({
+        name,
+        lastProjectedEventTimestamp:
+          context.readModels[name].lastProjectedEventTimestamp || 0,
+        replaying: !!replayStates[name],
+      })),
+    });
+  };
+};
+
+export const readModelsHandler = (context) => (req, res) => {
+  const replayStates = context.projectionHandler.getReadModelReplayStates();
+
+  res.json(
+    Object.keys(context.readModels).map((name) => {
+      const rm = context.readModels[name];
+      return {
+        name,
+        lastProjectedEventTimestamp: rm.lastProjectedEventTimestamp || 0,
+        status: replayStates[name] ? 'replaying' : 'active',
+        collections: rm.collections || [name],
+      };
+    }),
+  );
+};
+
+export const createBackupHandler = (context) => (req, res) => {
+  const correlationId = req.body.correlationId || nanoid();
+  const log = getLogger('Admin/Backup', correlationId);
+  const { readModelName } = req.params;
+
+  const rm = context.readModels[readModelName];
+  if (!rm) {
+    res.status(404).json({ error: `Read model ${readModelName} not found` });
+    return;
+  }
+
+  if (!context.backup) {
+    res.status(501).json({ error: 'Backup not configured' });
+    return;
+  }
+
+  const collectionNames = rm.collections || [readModelName];
+  log.info(`Creating backup for ${readModelName}`);
+
+  return context.backup
+    .createBackup(correlationId, readModelName, collectionNames)
+    .then((result) => {
+      res.json(result);
+    })
+    .catch((err) => {
+      log.error(`Failed to create backup: ${err}`);
+      res.status(500).json({ error: String(err) });
+    });
+};
+
+export const listBackupsHandler = (context) => (req, res) => {
+  const { readModelName } = req.params;
+
+  const rm = context.readModels[readModelName];
+  if (!rm) {
+    res.status(404).json({ error: `Read model ${readModelName} not found` });
+    return;
+  }
+
+  if (!context.backup) {
+    res.status(501).json({ error: 'Backup not configured' });
+    return;
+  }
+
+  return context.backup
+    .listBackups(readModelName)
+    .then((backups) => {
+      res.json(backups);
+    })
+    .catch((err) => {
+      const log = getLogger('Admin/Backup', 'list');
+      log.error(`Failed to list backups: ${err}`);
+      res.status(500).json({ error: String(err) });
+    });
+};
+
+export const deleteBackupHandler = (context) => (req, res) => {
+  const correlationId = nanoid();
+  const log = getLogger('Admin/Backup', correlationId);
+  const { backupId } = req.params;
+
+  if (!context.backup) {
+    res.status(501).json({ error: 'Backup not configured' });
+    return;
+  }
+
+  log.info(`Deleting backup ${backupId}`);
+
+  return context.backup
+    .deleteBackup(correlationId, backupId)
+    .then(() => {
+      res.sendStatus(204);
+    })
+    .catch((err) => {
+      log.error(`Failed to delete backup: ${err}`);
+      res.status(500).json({ error: String(err) });
+    });
+};
+
+export const prepareReplayHandler = (context) => (req, res) => {
+  const correlationId = req.body.correlationId || nanoid();
+  const log = getLogger('Admin/Prepare', correlationId);
+  const { readModelName } = req.params;
+  const { backupId, fromScratch } = req.body;
+
+  const rm = context.readModels[readModelName];
+  if (!rm) {
+    res.status(404).json({ error: `Read model ${readModelName} not found` });
+    return;
+  }
+
+  if (context.projectionHandler.isReadModelReplaying(readModelName)) {
+    res.status(409).json({
+      error: `Replay already in progress for ${readModelName}`,
+    });
+    return;
+  }
+
+  if ((backupId || fromScratch) && !context.backup) {
+    res.status(501).json({
+      error: 'Backup module required for restore or from-scratch replay',
+    });
+    return;
+  }
+
+  const collectionNames = rm.collections || [readModelName];
+  const warnings = detectSharedCollections(
+    context.readModels,
+    readModelName,
+    collectionNames,
+  );
+
+  log.info(`Preparing replay for ${readModelName}`);
+
+  // Step 1: Create pre-replay safety backup
+  return (
+    context.backup
+      ? context.backup.createBackup(
+          correlationId,
+          readModelName,
+          collectionNames,
+        )
+      : Promise.resolve(null)
+  )
+    .then((backupResult) => {
+      const preReplayBackupId = backupResult ? backupResult.backupId : null;
+
+      // Step 2: Set per-read-model replay state
+      context.projectionHandler.setReadModelReplayState(readModelName, true);
+
+      // Step 3: Restore backup or clear collections
+      const restoreStep = backupId
+        ? context.backup.restoreBackup(correlationId, readModelName, backupId)
+        : fromScratch
+          ? context.backup.clearCollections(
+              correlationId,
+              readModelName,
+              collectionNames,
+            )
+          : Promise.resolve();
+
+      return restoreStep
+        .then(() => {
+          // Step 4: Determine fromTimestamp
+          if (backupId) {
+            return context.backup.listBackups(readModelName).then((backups) => {
+              const restored = backups.find((b) => b.backupId === backupId);
+              return restored ? restored.eventTimestamp : 0;
+            });
+          }
+          if (fromScratch) return Promise.resolve(0);
+          return Promise.resolve(rm.lastProjectedEventTimestamp || 0);
+        })
+        .then((fromTimestamp) =>
+          // Step 5: Mark replayInProgress in readmodel.state
+          context.storage
+            .perRequest(correlationId)
+            .updateOne(
+              'readmodel.state',
+              { name: readModelName },
+              {
+                $set: {
+                  replayInProgress: true,
+                  preReplayBackupId,
+                },
+              },
+            )
+            .then(() => {
+              res.json({
+                status: 'prepared',
+                readModel: readModelName,
+                fromTimestamp,
+                preReplayBackupId,
+                warnings,
+              });
+            }),
+        );
+    })
+    .catch((err) => {
+      log.error(`Failed to prepare replay: ${err}`);
+      context.projectionHandler.clearReadModelReplayState(readModelName);
+      res.status(500).json({ error: String(err) });
+    });
+};
+
+export const replayReadModelStatusHandler = (context) => (req, res) => {
+  const { readModelName } = req.params;
+
+  const rm = context.readModels[readModelName];
+  if (!rm) {
+    res.status(404).json({ error: `Read model ${readModelName} not found` });
+    return;
+  }
+
+  const isReplaying =
+    context.projectionHandler.isReadModelReplaying(readModelName);
+
+  res.json({
+    readModel: readModelName,
+    status: isReplaying ? 'in_progress' : 'idle',
+    lastProjectedEventTimestamp: rm.lastProjectedEventTimestamp || 0,
+  });
+};
+
+export const __testing__ = { detectSharedCollections };

package/replay-handlers.js

@@ -0,0 +1,97 @@
+import { getLogger } from '@lazyapps/logger';
+import { nanoid } from 'nanoid';
+
+export const startReplayHandler = (context) => (req, res) => {
+  const correlationId = req.body.correlationId || nanoid();
+  const log = getLogger('Admin/Replay', correlationId);
+  const { readModel, fromTimestamp, toTimestamp } = req.body;
+
+  if (!readModel) {
+    res.status(400).json({ error: 'readModel is required' });
+    return;
+  }
+
+  const currentStatus = context.replayHandler.getReplayStatus(readModel);
+  if (currentStatus.status === 'in_progress') {
+    res
+      .status(409)
+      .json({ error: `Replay already in progress for ${readModel}` });
+    return;
+  }
+
+  log.info(`Starting replay for ${readModel} from ${fromTimestamp || 0}`);
+
+  // Start replay in background (streaming runs asynchronously)
+  context.replayHandler
+    .startReplay(
+      correlationId,
+      readModel,
+      fromTimestamp || 0,
+      toTimestamp || null,
+    )
+    .catch((err) => {
+      log.error(`Replay failed for ${readModel}: ${err}`);
+    });
+
+  res.json({ status: 'started', readModel });
+};
+
+export const replayStatusHandler = (context) => (req, res) => {
+  const { readModel } = req.params;
+  res.json(context.replayHandler.getReplayStatus(readModel));
+};
+
+export const cancelReplayHandler = (context) => (req, res) => {
+  const correlationId = req.body.correlationId || nanoid();
+  const log = getLogger('Admin/Replay', correlationId);
+  const { readModel } = req.body;
+
+  if (!readModel) {
+    res.status(400).json({ error: 'readModel is required' });
+    return;
+  }
+
+  log.info(`Cancelling replay for ${readModel}`);
+
+  return context.replayHandler
+    .cancelReplay(correlationId, readModel)
+    .then(() => {
+      res.json({ status: 'cancelling', readModel });
+    })
+    .catch((err) => {
+      log.error(`Failed to cancel replay: ${err}`);
+      res.status(500).json({ error: String(err) });
+    });
+};
+
+export const legacyAdminHandler = (context) => (req, res) => {
+  const { correlationId } = req.body;
+  const log = getLogger('Admin/Legacy', correlationId);
+  const { command } = req.params;
+
+  const handler = context.handleAdminCommand;
+  if (!handler) {
+    log.error(`No admin command handler available`);
+    res.sendStatus(400);
+    return;
+  }
+
+  log.debug(
+    `Legacy admin command ${command} with params ${JSON.stringify(req.body.params)}`,
+  );
+
+  return handler(context, command, req.body.params, req.auth, correlationId)
+    .then(() => {
+      res.sendStatus(200);
+    })
+    .catch((err) => {
+      log.error(`Error: ${err}`);
+      if (err.name === 'ValidationError') {
+        res.sendStatus(400);
+      } else if (err.name === 'AuthorizationError') {
+        res.sendStatus(403);
+      } else {
+        res.sendStatus(500);
+      }
+    });
+};