@yunsoft/yuncms 0.1.3 → 0.1.5

package/src/runtime-probe.js

@@ -0,0 +1,165 @@
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+
+import { MAINTENANCE_BYPASS_ENV } from '@yunsoft/yuncms-core';
+
+function delay(ms) {
+  return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
+
+function probeError(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+export async function verifyInstalledRuntime({
+  cwd = process.cwd(),
+  env = process.env,
+  port,
+  maintenanceBypassToken = null,
+  fetchFn = globalThis.fetch,
+  spawnProcess = spawn,
+  timeoutMs = 15_000,
+  shutdownGraceMs = 3_000,
+} = {}) {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw probeError('UPDATE_PROBE_PORT_INVALID', `Invalid probe port: ${port}`);
+  }
+  if (typeof fetchFn !== 'function') {
+    throw probeError('UPDATE_PROBE_FETCH_UNAVAILABLE', 'Runtime probe requires fetch support');
+  }
+  if (maintenanceBypassToken !== null && (typeof maintenanceBypassToken !== 'string' || maintenanceBypassToken.length < 32)) {
+    throw probeError('UPDATE_PROBE_MAINTENANCE_TOKEN_INVALID', 'Runtime probe maintenance bypass token is invalid');
+  }
+  if (!Number.isInteger(shutdownGraceMs) || shutdownGraceMs < 1 || shutdownGraceMs > 30_000) {
+    throw probeError(
+      'UPDATE_PROBE_SHUTDOWN_GRACE_INVALID',
+      `Runtime probe shutdown grace must be an integer between 1 and 30000ms: ${shutdownGraceMs}`,
+    );
+  }
+
+  const cliPath = resolve(cwd, 'node_modules', '@yunsoft', 'yuncms', 'bin', 'yuncms.js');
+  const origin = `http://127.0.0.1:${port}`;
+  const childEnv = {
+    ...env,
+    HOST: '127.0.0.1',
+    PORT: String(port),
+    STUDIO_ORIGIN: origin,
+    AUTH_PUBLIC_URL: origin,
+  };
+  if (maintenanceBypassToken !== null) childEnv[MAINTENANCE_BYPASS_ENV] = maintenanceBypassToken;
+
+  const child = spawnProcess(process.execPath, [cliPath, 'start'], {
+    cwd,
+    env: childEnv,
+    stdio: ['ignore', 'ignore', 'pipe'],
+  });
+
+  let stderr = '';
+  child.stderr?.setEncoding?.('utf8');
+  child.stderr?.on?.('data', (chunk) => {
+    if (stderr.length < 64 * 1024) stderr += String(chunk).slice(0, (64 * 1024) - stderr.length);
+  });
+
+  let settled = false;
+  let shutdownAttempted = false;
+  const exitPromise = new Promise((resolveExit, rejectExit) => {
+    child.once('error', (error) => {
+      if (settled) return;
+      settled = true;
+      error.code ||= 'UPDATE_PROBE_START_FAILED';
+      rejectExit(error);
+    });
+    child.once('exit', (code, signal) => {
+      if (settled) return;
+      settled = true;
+      resolveExit({ code, signal });
+    });
+  });
+
+  function requestKill(signal) {
+    try {
+      child.kill(signal);
+    } catch {
+      // The bounded shutdown path still escalates and reports a timeout.
+    }
+  }
+
+  async function waitForExit() {
+    return new Promise((resolveWait, rejectWait) => {
+      const timeout = setTimeout(() => {
+        resolveWait({ exited: false, result: null });
+      }, shutdownGraceMs);
+      exitPromise.then(
+        (result) => {
+          clearTimeout(timeout);
+          resolveWait({ exited: true, result });
+        },
+        (error) => {
+          clearTimeout(timeout);
+          rejectWait(error);
+        },
+      );
+    });
+  }
+
+  async function stopProbe({ strict }) {
+    shutdownAttempted = true;
+    requestKill('SIGTERM');
+    let outcome = await waitForExit();
+    if (outcome.exited) return outcome.result;
+
+    requestKill('SIGKILL');
+    outcome = await waitForExit();
+    if (outcome.exited) return outcome.result;
+    if (!strict) return null;
+    throw probeError(
+      'UPDATE_PROBE_SHUTDOWN_TIMEOUT',
+      `Updated YunCMS did not stop within ${shutdownGraceMs * 2}ms after readiness`,
+    );
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  try {
+    while (Date.now() < deadline) {
+      const earlyExit = await Promise.race([
+        exitPromise.then((result) => ({ type: 'exit', result })),
+        delay(200).then(() => ({ type: 'tick' })),
+      ]);
+      if (earlyExit.type === 'exit') {
+        throw probeError(
+          'UPDATE_PROBE_EXITED',
+          `Updated YunCMS exited before readiness${stderr.trim() ? `: ${stderr.trim()}` : ''}`,
+          earlyExit.result,
+        );
+      }
+
+      try {
+        const response = await fetchFn(`${origin}/ready`, { signal: AbortSignal.timeout(1000) });
+        if (response.ok) {
+          const body = await response.json().catch(() => null);
+          if (body?.status === 'ready') {
+            const result = await stopProbe({ strict: true });
+            if (result.code !== 0 && result.signal !== 'SIGTERM') {
+              throw probeError('UPDATE_PROBE_SHUTDOWN_FAILED', 'Updated runtime did not stop cleanly', result);
+            }
+            return { ready: true, origin };
+          }
+        }
+      } catch (error) {
+        if (error?.code?.startsWith?.('UPDATE_PROBE_')) throw error;
+      }
+    }
+
+    throw probeError(
+      'UPDATE_PROBE_TIMEOUT',
+      `Updated YunCMS did not become ready within ${timeoutMs}ms${stderr.trim() ? `: ${stderr.trim()}` : ''}`,
+    );
+  } finally {
+    if (!settled && !shutdownAttempted) {
+      await stopProbe({ strict: false }).catch(() => null);
+    }
+  }
+}

package/src/service-state.js

@@ -0,0 +1,37 @@
+function probeHost(host) {
+  const value = String(host ?? '').trim();
+  if (!value || value === '0.0.0.0' || value === '::' || value === '::0' || value === '[::]') {
+    return '127.0.0.1';
+  }
+  if (value.includes(':') && !value.startsWith('[')) return `[${value}]`;
+  return value;
+}
+
+export function localYunCmsHealthUrl({ host, port } = {}) {
+  return `http://${probeHost(host)}:${port}/health`;
+}
+
+export async function isLocalYunCmsReachable({
+  host = '127.0.0.1',
+  port,
+  fetchFn = globalThis.fetch,
+  timeoutMs = 1200,
+} = {}) {
+  if (typeof fetchFn !== 'function') return false;
+  try {
+    const response = await fetchFn(localYunCmsHealthUrl({ host, port }), {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return response.status >= 100 && response.status < 600;
+  } catch {
+    return false;
+  }
+}
+
+export async function assertYunCmsStopped(options = {}) {
+  const running = await isLocalYunCmsReachable(options);
+  if (!running) return true;
+  const error = new Error('YunCMS is currently reachable; stop the service supervisor before backup, restore or update');
+  error.code = 'UPDATE_APPLICATION_RUNNING';
+  throw error;
+}

package/src/start-command.js

@@ -1,6 +1,8 @@
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
+import { assertMaintenanceStartupAllowed } from '@yunsoft/yuncms-core';
+
 export async function runStartCommand({
   env = process.env,
   cwd = process.cwd(),
@@ -8,6 +10,8 @@ export async function runStartCommand({
   spawnProcess = spawn,
   signalSource = process,
 } = {}) {
+  await assertMaintenanceStartupAllowed({ cwd, env });
+
   const serverUrl = import.meta.resolve('@yunsoft/yuncms-api/server');
   const serverPath = fileURLToPath(serverUrl);
 

package/src/update-command.js

@@ -0,0 +1,282 @@
+import { resolve } from 'node:path';
+
+import { loadConfig } from '@yunsoft/yuncms-core';
+
+import { parseCommandOptions } from './command-options.js';
+import { acquireDatabaseMaintenanceLock } from './maintenance-lock.js';
+import {
+  createProjectBackup,
+  readBackupManifest,
+  restoreProjectBackup,
+} from './project-backup.js';
+import { runCapturedProcess } from './process-runner.js';
+import { verifyInstalledRuntime } from './runtime-probe.js';
+import { assertYunCmsStopped } from './service-state.js';
+import {
+  assertUpdatePreflightReady,
+  collectUpdatePreflight,
+} from './update-preflight.js';
+import { acquireUpdateLock } from './update-lock.js';
+
+function formatBytes(value) {
+  const bytes = Number(value) || 0;
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ['KB', 'MB', 'GB', 'TB'];
+  let current = bytes;
+  let unit = -1;
+  do {
+    current /= 1024;
+    unit += 1;
+  } while (current >= 1024 && unit < units.length - 1);
+  return `${current.toFixed(current >= 10 ? 1 : 2)} ${units[unit]}`;
+}
+
+function printPreflight(report, output) {
+  output.log?.(`YunCMS update: ${report.currentVersion} -> ${report.targetVersion}`);
+  output.log?.(`Database migrations: ${report.pendingMigrations.length > 0 ? report.pendingMigrations.join(', ') : 'none'}`);
+  output.log?.(`Estimated database size: ${formatBytes(report.databaseBytes)}`);
+  if (report.localBackupBytes != null) {
+    output.log?.(`Estimated local backup assets: ${formatBytes(report.localBackupBytes)}`);
+  }
+  output.log?.(`Free disk: ${formatBytes(report.freeDiskBytes)}`);
+  if (report.s3Configured) {
+    output.log?.(`S3 storage: ${report.s3Bucket} (provider-side object backup required)`);
+  }
+  if (report.blockers.length > 0) output.warn?.(`Preflight blockers: ${report.blockers.join(', ')}`);
+}
+
+function localCliPath(cwd) {
+  return resolve(cwd, 'node_modules', '@yunsoft', 'yuncms', 'bin', 'yuncms.js');
+}
+
+function dependencySaveArgs(dependencySection = 'dependencies') {
+  if (dependencySection === 'dependencies') return [];
+  if (dependencySection === 'devDependencies') return ['--save-dev'];
+  if (dependencySection === 'optionalDependencies') return ['--save-optional'];
+  const error = new Error(`Unsupported YunCMS dependency section: ${dependencySection}`);
+  error.code = 'UPDATE_DEPENDENCY_SECTION_INVALID';
+  throw error;
+}
+
+function assertMaintenanceLockContract(lock) {
+  if (!lock || typeof lock.assertHeld !== 'function' || typeof lock.release !== 'function') {
+    const error = new Error('Database maintenance lock implementation is invalid');
+    error.code = 'DATABASE_MAINTENANCE_LOCK_INVALID';
+    throw error;
+  }
+  return lock;
+}
+
+function databaseStateRequiresAttention(report) {
+  return (report.pendingMigrations?.length ?? 0) > 0
+    || (report.unknownAppliedMigrations?.length ?? 0) > 0
+    || (report.migrationHistoryGap?.length ?? 0) > 0
+    || (report.incompleteMigrationAttempts?.length ?? 0) > 0;
+}
+
+async function installVersion({ cwd, env, targetVersion, dependencySection, runProcess }) {
+  return runProcess(
+    'npm',
+    [
+      'install',
+      '--save-exact',
+      ...dependencySaveArgs(dependencySection),
+      '--no-audit',
+      '--no-fund',
+      `@yunsoft/yuncms@${targetVersion}`,
+    ],
+    { cwd, env },
+  );
+}
+
+async function bootstrapInstalledVersion({ cwd, env, runProcess }) {
+  return runProcess(process.execPath, [localCliPath(cwd), 'bootstrap'], { cwd, env });
+}
+
+async function reinstallBackedUpDependencies({ cwd, env, manifest, runProcess }) {
+  const args = manifest.project.packageLock
+    ? ['ci', '--no-audit', '--no-fund']
+    : ['install', '--no-audit', '--no-fund'];
+  return runProcess('npm', args, { cwd, env });
+}
+
+function rollbackFailure(originalError, rollbackError) {
+  const error = new Error(
+    `YunCMS update failed and automatic rollback also failed. Update error: ${originalError.message}. Rollback error: ${rollbackError.message}`,
+  );
+  error.code = 'UPDATE_ROLLBACK_FAILED';
+  error.updateError = originalError;
+  error.rollbackError = rollbackError;
+  return error;
+}
+
+export async function runUpdateCommand({
+  args = [],
+  cwd = process.cwd(),
+  env = process.env,
+  output = console,
+  runProcess = runCapturedProcess,
+  collectPreflight = collectUpdatePreflight,
+  createBackup = createProjectBackup,
+  restoreBackup = restoreProjectBackup,
+  verifyRuntime = verifyInstalledRuntime,
+  acquireLock = acquireUpdateLock,
+  acquireMaintenanceLock = acquireDatabaseMaintenanceLock,
+  assertStopped = assertYunCmsStopped,
+  fetchFn = globalThis.fetch,
+} = {}) {
+  const { values } = parseCommandOptions(args, {
+    boolean: ['--dry-run', '--allow-unverified-s3'],
+    string: ['--to', '--backup-output'],
+    maxPositionals: 0,
+  });
+
+  const target = values['--to'] ?? 'latest';
+  const dryRun = values['--dry-run'] === true;
+  const allowUnverifiedS3 = values['--allow-unverified-s3'] === true;
+  const config = loadConfig(env);
+  const projectLock = dryRun ? null : await acquireLock({ cwd });
+  let maintenanceLock = null;
+
+  const assertServiceStopped = () => assertStopped({
+    host: config.server.host,
+    port: config.server.port,
+    fetchFn,
+  });
+  const assertMaintenanceHeld = async () => (
+    maintenanceLock ? maintenanceLock.assertHeld() : true
+  );
+  const maintenanceBypassToken = projectLock?.bypassToken ?? null;
+
+  try {
+    if (!dryRun) {
+      maintenanceLock = assertMaintenanceLockContract(await acquireMaintenanceLock({ env }));
+    }
+
+    const report = await collectPreflight({
+      cwd,
+      env,
+      target,
+      allowUnverifiedS3,
+      runProcess,
+      fetchFn,
+    });
+    printPreflight(report, output);
+
+    if (report.upToDate && !databaseStateRequiresAttention(report)) {
+      output.log?.('YunCMS package and database are already on the requested version.');
+      return { changed: false, dryRun, report, backupPath: null };
+    }
+    if (dryRun) {
+      output.log?.(
+        report.blockers.length === 0
+          ? 'Dry run passed; no changes were made.'
+          : 'Dry run found blockers; no changes were made.',
+      );
+      return { changed: false, dryRun: true, report, backupPath: null };
+    }
+
+    assertUpdatePreflightReady(report);
+    await assertServiceStopped();
+    await assertMaintenanceHeld();
+
+    const backupPath = values['--backup-output']
+      ? resolve(cwd, values['--backup-output'])
+      : null;
+    const backup = await createBackup({ cwd, env, output, backupPath });
+    await readBackupManifest(backup.backupPath);
+    await assertServiceStopped();
+    await assertMaintenanceHeld();
+
+    try {
+      if (!report.upToDate) {
+        output.log?.(`Installing @yunsoft/yuncms@${report.targetVersion}`);
+        await installVersion({
+          cwd,
+          env,
+          targetVersion: report.targetVersion,
+          dependencySection: report.dependencySection,
+          runProcess,
+        });
+      } else {
+        output.log?.('YunCMS package already matches the target; skipping npm reinstall.');
+      }
+
+      await assertServiceStopped();
+      await assertMaintenanceHeld();
+
+      output.log?.('Applying target database migrations');
+      await bootstrapInstalledVersion({ cwd, env, runProcess });
+      await assertServiceStopped();
+      await assertMaintenanceHeld();
+
+      output.log?.('Starting temporary readiness probe');
+      await verifyRuntime({
+        cwd,
+        env,
+        port: config.server.port,
+        maintenanceBypassToken,
+        fetchFn,
+      });
+      await assertServiceStopped();
+      await assertMaintenanceHeld();
+
+      output.log?.(`YunCMS update verified: ${report.currentVersion} -> ${report.targetVersion}`);
+      output.log?.('The verification process is stopped. Restart YunCMS through your normal service supervisor.');
+      return {
+        changed: true,
+        dryRun: false,
+        report,
+        backupPath: backup.backupPath,
+        rollbackPerformed: false,
+      };
+    } catch (updateError) {
+      output.warn?.(`Update failed; restoring backup ${backup.backupPath}`);
+      try {
+        const beforeDestructive = async () => {
+          await assertServiceStopped();
+          await assertMaintenanceHeld();
+        };
+        const restored = await restoreBackup({
+          backupPath: backup.backupPath,
+          cwd,
+          env,
+          output,
+          beforeDestructive,
+        });
+        await assertServiceStopped();
+        await assertMaintenanceHeld();
+
+        await reinstallBackedUpDependencies({
+          cwd,
+          env,
+          manifest: restored.manifest,
+          runProcess,
+        });
+        await assertServiceStopped();
+        await assertMaintenanceHeld();
+
+        await verifyRuntime({
+          cwd,
+          env,
+          port: config.server.port,
+          maintenanceBypassToken,
+          fetchFn,
+        });
+        await assertServiceStopped();
+        await assertMaintenanceHeld();
+
+        updateError.rollbackPerformed = true;
+        updateError.backupPath = backup.backupPath;
+        updateError.message = `${updateError.message} (automatic rollback completed successfully)`;
+        throw updateError;
+      } catch (rollbackError) {
+        if (rollbackError === updateError) throw updateError;
+        throw rollbackFailure(updateError, rollbackError);
+      }
+    }
+  } finally {
+    if (maintenanceLock) await maintenanceLock.release();
+    if (projectLock) await projectLock.release();
+  }
+}

package/src/update-lock.js

@@ -0,0 +1,68 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, open, rm } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+import {
+  hashMaintenanceBypassToken,
+  maintenanceLockPath,
+} from '@yunsoft/yuncms-core';
+
+export function updateLockPath(cwd = process.cwd()) {
+  return maintenanceLockPath(cwd);
+}
+
+export async function acquireUpdateLock({
+  cwd = process.cwd(),
+  now = new Date(),
+  pid = process.pid,
+  generateToken = () => randomBytes(32).toString('hex'),
+} = {}) {
+  const path = updateLockPath(cwd);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+
+  let handle;
+  try {
+    handle = await open(path, 'wx', 0o600);
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      const locked = new Error(
+        `Another YunCMS backup/update/restore operation may already be running. Inspect and remove the stale lock only after verifying no operation is active: ${path}`,
+      );
+      locked.code = 'UPDATE_ALREADY_RUNNING';
+      locked.lockPath = path;
+      throw locked;
+    }
+    throw error;
+  }
+
+  let bypassToken;
+  try {
+    bypassToken = generateToken();
+    const bypassTokenHash = hashMaintenanceBypassToken(bypassToken);
+    await handle.writeFile(
+      `${JSON.stringify({
+        pid,
+        startedAt: now.toISOString(),
+        cwd: resolve(cwd),
+        bypassTokenHash,
+      }, null, 2)}\n`,
+      'utf8',
+    );
+  } catch (error) {
+    await handle.close().catch(() => {});
+    await rm(path, { force: true }).catch(() => {});
+    throw error;
+  }
+
+  let released = false;
+  return {
+    path,
+    bypassToken,
+    async release() {
+      if (released) return;
+      released = true;
+      await handle.close().catch(() => {});
+      await rm(path, { force: true });
+    },
+  };
+}