@kne/fastify-app-manager 0.1.1

package/libs/utils/env.js

@@ -0,0 +1,79 @@
+const SECRET_MASK = '********';
+
+const pickHostEnv = (passthroughEnvKeys = []) => {
+  const result = {};
+  for (const key of passthroughEnvKeys) {
+    if (Object.prototype.hasOwnProperty.call(process.env, key) && process.env[key] != null) {
+      result[key] = process.env[key];
+    }
+  }
+  return result;
+};
+
+const mergeEnv = ({ passthroughEnvKeys = [], appEnv = {}, port }) => {
+  const merged = Object.assign({}, pickHostEnv(passthroughEnvKeys), appEnv || {}, {
+    PORT: String(port)
+  });
+  return merged;
+};
+
+const isSecretKey = (key, pattern) => {
+  const re = pattern instanceof RegExp ? pattern : new RegExp(pattern || '(SECRET|PASSWORD|TOKEN|KEY|PRIVATE)', 'i');
+  return re.test(key);
+};
+
+const maskEnvForResponse = (appEnv = {}, { secretEnvKeyPattern } = {}) => {
+  const masked = {};
+  for (const [key, value] of Object.entries(appEnv || {})) {
+    if (isSecretKey(key, secretEnvKeyPattern)) {
+      masked[key] = value == null || value === '' ? null : SECRET_MASK;
+    } else {
+      masked[key] = value;
+    }
+  }
+  return masked;
+};
+
+/**
+ * merge patch into current env.
+ * null => delete key
+ * SECRET_MASK => keep existing
+ * other => set
+ */
+const applyEnvPatch = (current = {}, patch = {}, { secretEnvKeyPattern } = {}) => {
+  const next = Object.assign({}, current);
+  for (const [key, value] of Object.entries(patch || {})) {
+    if (value === null) {
+      delete next[key];
+      continue;
+    }
+    if (value === SECRET_MASK && isSecretKey(key, secretEnvKeyPattern)) {
+      continue;
+    }
+    next[key] = value;
+  }
+  return next;
+};
+
+const PM2_CONFIG_KEYS = ['exec_mode', 'instances', 'autorestart', 'max_memory_restart', 'max_restarts', 'min_uptime', 'kill_timeout', 'merge_logs'];
+
+const mergePm2Config = (defaults = {}, appConfig = {}) => {
+  const merged = Object.assign({}, defaults);
+  for (const key of PM2_CONFIG_KEYS) {
+    if (appConfig && Object.prototype.hasOwnProperty.call(appConfig, key) && appConfig[key] != null) {
+      merged[key] = appConfig[key];
+    }
+  }
+  return merged;
+};
+
+module.exports = {
+  SECRET_MASK,
+  pickHostEnv,
+  mergeEnv,
+  isSecretKey,
+  maskEnvForResponse,
+  applyEnvPatch,
+  PM2_CONFIG_KEYS,
+  mergePm2Config
+};

package/libs/utils/logFiles.js

@@ -0,0 +1,52 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const { EventEmitter } = require('node:events');
+
+const createLogHub = () => {
+  const emitter = new EventEmitter();
+  emitter.setMaxListeners(0);
+  return emitter;
+};
+
+const ensureLogFiles = async appRoot => {
+  const logsDir = path.join(appRoot, 'logs');
+  await fs.ensureDir(logsDir);
+  const outFile = path.join(logsDir, 'out.log');
+  const errFile = path.join(logsDir, 'err.log');
+  await fs.ensureFile(outFile);
+  await fs.ensureFile(errFile);
+  return { logsDir, outFile, errFile };
+};
+
+const appendLog = async (filePath, content) => {
+  await fs.appendFile(filePath, content.endsWith('\n') ? content : `${content}\n`);
+};
+
+const readLogTail = async (filePath, { perPage = 100, currentPage = 1 } = {}) => {
+  if (!(await fs.pathExists(filePath))) {
+    return { pageData: [], totalCount: 0 };
+  }
+  const text = await fs.readFile(filePath, 'utf8');
+  const lines = text.split(/\r?\n/).filter((line, idx, arr) => !(idx === arr.length - 1 && line === ''));
+  const totalCount = lines.length;
+  const start = Math.max(0, totalCount - perPage * currentPage);
+  const end = Math.max(0, totalCount - perPage * (currentPage - 1));
+  const pageData = lines.slice(start, end).map((content, i) => ({
+    line: start + i + 1,
+    content
+  }));
+  return { pageData: pageData.reverse(), totalCount };
+};
+
+const readLastLines = async (filePath, n = 100) => {
+  const { pageData } = await readLogTail(filePath, { perPage: n, currentPage: 1 });
+  return pageData.reverse();
+};
+
+module.exports = {
+  createLogHub,
+  ensureLogFiles,
+  appendLog,
+  readLogTail,
+  readLastLines
+};

package/libs/utils/logStream.js

@@ -0,0 +1,39 @@
+const { Transform } = require('node:stream');
+
+const createSseReply = (reply, { heartbeatMs = 15000 } = {}) => {
+  reply.hijack();
+  reply.raw.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+    'X-Accel-Buffering': 'no'
+  });
+
+  const writeEvent = (event, data) => {
+    if (event) {
+      reply.raw.write(`event: ${event}\n`);
+    }
+    reply.raw.write(`data: ${typeof data === 'string' ? data : JSON.stringify(data)}\n\n`);
+  };
+
+  const heartbeat = setInterval(() => {
+    reply.raw.write(`: ping\n\n`);
+  }, heartbeatMs);
+
+  const close = () => {
+    clearInterval(heartbeat);
+    try {
+      reply.raw.end();
+    } catch (e) {
+      // ignore
+    }
+  };
+
+  reply.raw.on('close', close);
+
+  return { writeEvent, close, raw: reply.raw };
+};
+
+module.exports = {
+  createSseReply
+};

package/libs/utils/migrate.js

@@ -0,0 +1,70 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const { Sequelize } = require('sequelize');
+const { listSqlFiles } = require('./validatePackage');
+
+const SQL_MIGRATIONS_TABLE = '_fs_sql_migrations';
+
+/**
+ * Run .sql files under server/{sqlPath} with the same tracking semantics as @kne/fastify-sequelize.
+ */
+const runSqlMigrations = async ({ serverDir, sqlPath = 'sql', env = {} }) => {
+  const sqlDir = path.join(serverDir, sqlPath);
+  const files = await listSqlFiles(sqlDir);
+  if (!files.length) {
+    return { executed: [], skipped: true };
+  }
+
+  const sequelize = createSequelizeFromEnv(env);
+  try {
+    await sequelize.authenticate();
+    await sequelize.query(
+      `CREATE TABLE IF NOT EXISTS ${SQL_MIGRATIONS_TABLE} (
+        name VARCHAR(255) PRIMARY KEY,
+        executed_at DATETIME
+      )`
+    );
+
+    const [rows] = await sequelize.query(`SELECT name FROM ${SQL_MIGRATIONS_TABLE}`);
+    const done = new Set((rows || []).map(r => r.name));
+    const executed = [];
+
+    for (const file of files) {
+      if (done.has(file)) {
+        continue;
+      }
+      const sql = await fs.readFile(path.join(sqlDir, file), 'utf8');
+      await sequelize.query(sql);
+      await sequelize.query(`INSERT INTO ${SQL_MIGRATIONS_TABLE} (name, executed_at) VALUES (?, ?)`, {
+        replacements: [file, new Date().toISOString()]
+      });
+      executed.push(file);
+    }
+    return { executed, skipped: false };
+  } finally {
+    await sequelize.close();
+  }
+};
+
+const createSequelizeFromEnv = env => {
+  const dialect = env.DB_DIALECT || 'sqlite';
+  if (dialect === 'sqlite') {
+    return new Sequelize({
+      dialect: 'sqlite',
+      storage: env.DB_HOST || env.DB_STORAGE || path.join(process.cwd(), 'data.db'),
+      logging: false
+    });
+  }
+  return new Sequelize(env.DB_DATABASE, env.DB_USERNAME, env.DB_PASSWORD, {
+    host: env.DB_HOST || '127.0.0.1',
+    port: env.DB_PORT ? Number(env.DB_PORT) : undefined,
+    dialect,
+    logging: false
+  });
+};
+
+module.exports = {
+  SQL_MIGRATIONS_TABLE,
+  runSqlMigrations,
+  createSequelizeFromEnv
+};

package/libs/utils/pathRewrite.js

@@ -0,0 +1,55 @@
+const rewriteLocation = (location, mountPrefix) => {
+  if (!location || !mountPrefix) {
+    return location;
+  }
+  if (/^https?:\/\//i.test(location) || location.startsWith('//')) {
+    return location;
+  }
+  if (location.startsWith(mountPrefix)) {
+    return location;
+  }
+  if (location.startsWith('/')) {
+    return `${mountPrefix}${location}`.replace(/\/{2,}/g, '/').replace(':/', '://');
+  }
+  return location;
+};
+
+const rewriteSetCookiePath = (setCookie, mountPrefix) => {
+  if (!setCookie || !mountPrefix) {
+    return setCookie;
+  }
+  const cookies = Array.isArray(setCookie) ? setCookie : [setCookie];
+  return cookies.map(cookie => {
+    if (/;\s*Path=/i.test(cookie)) {
+      return cookie.replace(/;\s*Path=\/?(?=[;]|$)/i, `; Path=${mountPrefix}`);
+    }
+    return `${cookie}; Path=${mountPrefix}`;
+  });
+};
+
+const TEXTUAL_TYPES = /text\/|javascript|json|xml|svg/i;
+
+const shouldRewriteBody = contentType => TEXTUAL_TYPES.test(contentType || '');
+
+const rewriteBody = (body, mountPrefix, prefixes = ['/static', '/api', '/account']) => {
+  if (!body || !mountPrefix) {
+    return body;
+  }
+  let text = Buffer.isBuffer(body) ? body.toString('utf8') : String(body);
+  for (const p of prefixes) {
+    const from = `"${p}/`;
+    const to = `"${mountPrefix}${p}/`;
+    text = text.split(from).join(to);
+    const from2 = `'${p}/`;
+    const to2 = `'${mountPrefix}${p}/`;
+    text = text.split(from2).join(to2);
+  }
+  return text;
+};
+
+module.exports = {
+  rewriteLocation,
+  rewriteSetCookiePath,
+  shouldRewriteBody,
+  rewriteBody
+};

package/libs/utils/pm2.js

@@ -0,0 +1,96 @@
+const path = require('node:path');
+const pm2 = require('pm2');
+const { mergePm2Config } = require('./env');
+
+const connect = () =>
+  new Promise((resolve, reject) => {
+    pm2.connect(err => (err ? reject(err) : resolve()));
+  });
+
+const disconnect = () => {
+  try {
+    pm2.disconnect();
+  } catch (e) {
+    // ignore
+  }
+};
+
+const describe = name =>
+  new Promise((resolve, reject) => {
+    pm2.describe(name, (err, list) => {
+      if (err) {
+        return reject(err);
+      }
+      resolve(list || []);
+    });
+  });
+
+const deleteProcess = name =>
+  new Promise(resolve => {
+    pm2.delete(name, () => resolve());
+  });
+
+const startApp = async ({ pm2Name, cwd, env, pm2Defaults, pm2Config, outFile, errorFile }) => {
+  const cfg = mergePm2Config(pm2Defaults, pm2Config);
+  const existing = await describe(pm2Name);
+  if (existing.length) {
+    await deleteProcess(pm2Name);
+  }
+
+  const script = path.join(cwd, 'index.js');
+  return new Promise((resolve, reject) => {
+    pm2.start(
+      {
+        name: pm2Name,
+        script,
+        cwd,
+        env,
+        exec_mode: cfg.exec_mode,
+        instances: cfg.instances,
+        autorestart: cfg.autorestart,
+        max_memory_restart: cfg.max_memory_restart,
+        max_restarts: cfg.max_restarts,
+        min_uptime: cfg.min_uptime,
+        kill_timeout: cfg.kill_timeout,
+        merge_logs: cfg.merge_logs,
+        out_file: outFile,
+        error_file: errorFile,
+        time: true
+      },
+      (err, apps) => (err ? reject(err) : resolve(apps))
+    );
+  });
+};
+
+const stopApp = name =>
+  new Promise((resolve, reject) => {
+    pm2.stop(name, err => (err ? reject(err) : resolve()));
+  });
+
+const restartApp = name =>
+  new Promise((resolve, reject) => {
+    pm2.restart(name, err => (err ? reject(err) : resolve()));
+  });
+
+const list = () =>
+  new Promise((resolve, reject) => {
+    pm2.list((err, list) => (err ? reject(err) : resolve(list || [])));
+  });
+
+const launchBus = () =>
+  new Promise((resolve, reject) => {
+    pm2.launchBus((err, bus) => (err ? reject(err) : resolve(bus)));
+  });
+
+module.exports = {
+  connect,
+  disconnect,
+  describe,
+  deleteProcess,
+  startApp,
+  stopApp,
+  restartApp,
+  list,
+  launchBus,
+  raw: pm2
+};

package/libs/utils/portPool.js

@@ -0,0 +1,29 @@
+const net = require('node:net');
+
+const isPortFree = port =>
+  new Promise(resolve => {
+    const server = net.createServer();
+    server.unref();
+    server.once('error', () => resolve(false));
+    server.once('listening', () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, '127.0.0.1');
+  });
+
+module.exports = {
+  isPortFree,
+  async allocate({ models, portMin, portMax, excludePorts = [] }) {
+    const rows = await models.app.findAll({ attributes: ['port'] });
+    const used = new Set([...rows.map(r => r.port), ...excludePorts]);
+    for (let port = portMin; port <= portMax; port++) {
+      if (used.has(port)) {
+        continue;
+      }
+      if (await isPortFree(port)) {
+        return port;
+      }
+    }
+    throw new Error(`No free port in range ${portMin}-${portMax}`);
+  }
+};

package/libs/utils/validatePackage.js

@@ -0,0 +1,59 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+
+const ENTRY_CANDIDATES = ['index.html', 'entry.html', 'entry-prod.html'];
+
+const validatePackageRoot = async rootDir => {
+  const errors = [];
+  const rootPkg = path.join(rootDir, 'package.json');
+  const serverPkg = path.join(rootDir, 'server', 'package.json');
+  const serverIndex = path.join(rootDir, 'server', 'index.js');
+  const buildDir = path.join(rootDir, 'build');
+
+  if (!(await fs.pathExists(rootPkg))) {
+    errors.push('missing root package.json');
+  }
+  if (!(await fs.pathExists(serverPkg))) {
+    errors.push('missing server/package.json');
+  }
+  if (!(await fs.pathExists(serverIndex))) {
+    errors.push('missing server/index.js');
+  }
+  if (!(await fs.pathExists(buildDir))) {
+    errors.push('missing root build/ directory');
+  } else {
+    const hasEntry = (await Promise.all(ENTRY_CANDIDATES.map(name => fs.pathExists(path.join(buildDir, name))))).some(Boolean);
+    if (!hasEntry) {
+      errors.push(`build/ must contain one of: ${ENTRY_CANDIDATES.join(', ')}`);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    hasMigration: await hasSqlMigrations(path.join(rootDir, 'server', 'sql'))
+  };
+};
+
+const hasSqlMigrations = async sqlDir => {
+  if (!(await fs.pathExists(sqlDir))) {
+    return false;
+  }
+  const files = await fs.readdir(sqlDir);
+  return files.some(f => f.endsWith('.sql'));
+};
+
+const listSqlFiles = async sqlDir => {
+  if (!(await fs.pathExists(sqlDir))) {
+    return [];
+  }
+  const files = await fs.readdir(sqlDir);
+  return files.filter(f => f.endsWith('.sql')).sort();
+};
+
+module.exports = {
+  ENTRY_CANDIDATES,
+  validatePackageRoot,
+  hasSqlMigrations,
+  listSqlFiles
+};

package/libs/utils/version.js

@@ -0,0 +1,77 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const { spawn } = require('node:child_process');
+const { extractZipSafe, resolvePackageRoot } = require('./zip');
+const { validatePackageRoot, listSqlFiles } = require('./validatePackage');
+
+const runNpmInstall = (cwd, timeoutMs) =>
+  new Promise((resolve, reject) => {
+    const child = spawn('npm', ['install', '--production', '--no-fund', '--no-audit'], {
+      cwd,
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    let stderr = '';
+    child.stderr.on('data', chunk => {
+      stderr += chunk.toString();
+    });
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      reject(new Error(`npm install timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    child.on('error', err => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    child.on('close', code => {
+      clearTimeout(timer);
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`npm install failed (${code}): ${stderr.slice(-2000)}`));
+      }
+    });
+  });
+
+const prepareVersionArtifact = async ({ zipBuffer, artifactPath, maxZipSize, maxZipEntries, npmInstallTimeoutMs, sqlPath }) => {
+  await fs.emptyDir(artifactPath);
+  const extractDir = path.join(artifactPath, '_extract');
+  await extractZipSafe(zipBuffer, extractDir, { maxZipSize, maxZipEntries });
+  const packageRoot = await resolvePackageRoot(extractDir);
+
+  const validation = await validatePackageRoot(packageRoot);
+  if (!validation.ok) {
+    await fs.remove(artifactPath);
+    throw new Error(`invalid package: ${validation.errors.join('; ')}`);
+  }
+
+  // Move package contents to artifact root
+  const staging = path.join(artifactPath, '_pkg');
+  await fs.move(packageRoot, staging, { overwrite: true });
+  await fs.remove(extractDir);
+  const entries = await fs.readdir(staging);
+  for (const entry of entries) {
+    await fs.move(path.join(staging, entry), path.join(artifactPath, entry), { overwrite: true });
+  }
+  await fs.remove(staging);
+
+  await fs.copy(path.join(artifactPath, 'build'), path.join(artifactPath, 'server', 'build'), {
+    overwrite: true
+  });
+
+  const serverDir = path.join(artifactPath, 'server');
+  await runNpmInstall(serverDir, npmInstallTimeoutMs);
+
+  const sqlDir = path.join(serverDir, sqlPath || 'sql');
+  const sqlFiles = await listSqlFiles(sqlDir);
+  return {
+    hasMigration: sqlFiles.length > 0,
+    migrationPath: sqlPath || 'sql',
+    sqlFiles
+  };
+};
+
+module.exports = {
+  runNpmInstall,
+  prepareVersionArtifact
+};

package/libs/utils/zip.js

@@ -0,0 +1,69 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const AdmZip = require('adm-zip');
+
+const isPathInside = (parent, child) => {
+  const relative = path.relative(parent, child);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+};
+
+const extractZipSafe = async (zipBuffer, destDir, { maxZipSize, maxZipEntries }) => {
+  if (!Buffer.isBuffer(zipBuffer)) {
+    throw new Error('zip content must be a Buffer');
+  }
+  if (zipBuffer.length > maxZipSize) {
+    throw new Error(`zip exceeds max size ${maxZipSize}`);
+  }
+
+  await fs.ensureDir(destDir);
+  const zip = new AdmZip(zipBuffer);
+  const entries = zip.getEntries();
+  if (entries.length > maxZipEntries) {
+    throw new Error(`zip has too many entries (${entries.length} > ${maxZipEntries})`);
+  }
+
+  for (const entry of entries) {
+    const entryName = entry.entryName.replace(/^[/\\]+/, '').replace(/\\/g, '/');
+    if (!entryName || entryName.includes('\0')) {
+      throw new Error('invalid zip entry name');
+    }
+    if (entryName.split('/').some(part => part === '..')) {
+      throw new Error(`zip slip detected: ${entry.entryName}`);
+    }
+    const target = path.resolve(destDir, entryName);
+    if (!isPathInside(path.resolve(destDir), target)) {
+      throw new Error(`zip slip detected: ${entry.entryName}`);
+    }
+    if (entry.isDirectory) {
+      await fs.ensureDir(target);
+      continue;
+    }
+    await fs.ensureDir(path.dirname(target));
+    await fs.writeFile(target, entry.getData());
+  }
+
+  // If zip has a single top-level folder, flatten optional? Keep as-is; callers resolve package root.
+  return destDir;
+};
+
+const resolvePackageRoot = async extractDir => {
+  const direct = path.join(extractDir, 'package.json');
+  if (await fs.pathExists(direct)) {
+    return extractDir;
+  }
+  const children = await fs.readdir(extractDir);
+  for (const child of children) {
+    const candidate = path.join(extractDir, child);
+    const stat = await fs.stat(candidate);
+    if (stat.isDirectory() && (await fs.pathExists(path.join(candidate, 'package.json')))) {
+      return candidate;
+    }
+  }
+  return extractDir;
+};
+
+module.exports = {
+  isPathInside,
+  extractZipSafe,
+  resolvePackageRoot
+};