@lark-apaas/fullstack-cli 1.1.59 → 1.1.61-alpha.20260818172555

package/templates/scripts/server-cache-runtime.mjs

@@ -0,0 +1,681 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import net from 'node:net';
+import http from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  validateCacheGeneration,
+  validateCacheGenerationReceipt,
+  writeCacheGenerationValidationReceipt,
+} from './cache-generation-preflight.mjs';
+
+const projectRoot = path.resolve(
+  process.env.MIAODA_WORKSPACE_ROOT || process.cwd()
+);
+const defaultCachePointer = path.join(projectRoot, '.miaoda-cache', 'current');
+const requestedCacheRoot = path.resolve(
+  process.env.MIAODA_CACHE_ROOT || defaultCachePointer
+);
+const cacheRoot = fs.realpathSync(requestedCacheRoot);
+if (!process.env.MIAODA_CACHE_ROOT) {
+  const generationStore = fs.realpathSync(
+    path.join(projectRoot, '.miaoda-cache', 'generations')
+  );
+  const generationRelative = path.relative(generationStore, cacheRoot);
+  if (!/^[a-f0-9]{64}$/.test(generationRelative)) {
+    throw new Error('MIAODA_CACHE_GENERATION_POINTER_REJECTED');
+  }
+}
+const runtimeManifestFile = path.resolve(
+  process.env.MIAODA_PLATFORM_RUNTIME_MANIFEST ||
+    '/opt/miaoda/preview-runtime/runtime-manifest.json'
+);
+const validateOnly = process.argv.includes('--validate-only');
+const artifactScopeOptionIndex = process.argv.indexOf('--artifact-scope');
+const validationArtifactScope =
+  artifactScopeOptionIndex >= 0
+    ? process.argv[artifactScopeOptionIndex + 1]
+    : 'all';
+const skipWorkspaceInputs = process.argv.includes('--skip-workspace-inputs');
+const servingReadyMarker = '/tmp/event/MIAODA_NEST_CACHE_SERVING_READY';
+const skipConfigEnvironment = process.argv.includes(
+  '--skip-config-environment'
+);
+const runtimeStartedAt = process.hrtime.bigint();
+const durationMs = startedAt =>
+  Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+function emitRuntimePhase(phase, startedAt, details = {}) {
+  if (validateOnly) return;
+  process.stdout.write(
+    `${JSON.stringify({
+      event: 'miaoda_cache_runtime_phase',
+      runtime: 'nest',
+      phase,
+      durationMs: Number(durationMs(startedAt).toFixed(3)),
+      ...details,
+    })}\n`
+  );
+}
+function publishServingReadyMarker(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporaryFile = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(
+    temporaryFile,
+    `${JSON.stringify({ schemaVersion: 1, readyAt: new Date().toISOString() })}\n`,
+    { mode: 0o600 }
+  );
+  fs.renameSync(temporaryFile, file);
+}
+if (!validateOnly) {
+  fs.rmSync(servingReadyMarker, { force: true });
+  process.once('exit', () => {
+    try {
+      fs.rmSync(servingReadyMarker, { force: true });
+    } catch {}
+  });
+}
+if (skipConfigEnvironment && !validateOnly) {
+  process.stderr.write(
+    'MIAODA_CACHE_CONFIG_ENVIRONMENT_SKIP_REQUIRES_VALIDATE_ONLY\n'
+  );
+  process.exit(2);
+}
+if (
+  (!validateOnly && artifactScopeOptionIndex >= 0) ||
+  (!validateOnly && skipWorkspaceInputs) ||
+  !['all', 'server', 'vite'].includes(validationArtifactScope) ||
+  (skipWorkspaceInputs && validationArtifactScope !== 'vite')
+) {
+  process.stderr.write('MIAODA_CACHE_VALIDATION_OPTIONS_INVALID\n');
+  process.exit(2);
+}
+
+let validated;
+let validatedBy = 'full-sha';
+let validationReceiptMiss;
+const validationStartedAt = process.hrtime.bigint();
+try {
+  const validationReceiptFile =
+    process.env.MIAODA_CACHE_VALIDATION_RECEIPT_FILE;
+  if (validationReceiptFile && !skipWorkspaceInputs) {
+    try {
+      validated = validateCacheGenerationReceipt({
+        projectRoot,
+        cacheRoot,
+        runtimeManifestFile,
+        receiptFile: validationReceiptFile,
+        validateConfigEnvironment: !skipConfigEnvironment,
+        artifactScope: validateOnly ? validationArtifactScope : 'server',
+      });
+      validatedBy = 'platform-receipt';
+    } catch (error) {
+      validationReceiptMiss = String(
+        error instanceof Error ? error.message : error
+      ).split(':')[0];
+      // A missing/stale receipt is only a fast-path miss. Preserve the legacy
+      // full preflight and dependency-backed fallback semantics below.
+    }
+  }
+  if (!validated) {
+    validated = validateCacheGeneration({
+      projectRoot,
+      cacheRoot,
+      runtimeManifestFile,
+      validateConfigEnvironment: !skipConfigEnvironment,
+      artifactScope: validateOnly ? validationArtifactScope : 'server',
+      validateWorkspaceInputs: !skipWorkspaceInputs,
+    });
+  }
+  if (
+    !process.env.MIAODA_CACHE_ROOT &&
+    path.basename(cacheRoot) !== validated.generation.generationId
+  ) {
+    throw new Error('MIAODA_CACHE_GENERATION_POINTER_ID_MISMATCH');
+  }
+  if (validateOnly) {
+    if (
+      validationReceiptFile &&
+      validatedBy === 'full-sha' &&
+      !skipWorkspaceInputs
+    ) {
+      writeCacheGenerationValidationReceipt({
+        validated,
+        receiptFile: validationReceiptFile,
+      });
+    }
+    process.stdout.write(
+      `${JSON.stringify({
+        valid: true,
+        generationId: validated.generation.generationId,
+        artifactScope: validationArtifactScope,
+        workspaceInputsValidated: !skipWorkspaceInputs,
+        validatedBy,
+        receiptWritten: Boolean(
+          validationReceiptFile &&
+          validatedBy === 'full-sha' &&
+          !skipWorkspaceInputs
+        ),
+      })}\n`
+    );
+    process.exit(0);
+  }
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
+  process.exit(2);
+}
+emitRuntimePhase('generation_validation', validationStartedAt, {
+  artifactScope: 'server',
+  validatedBy,
+  ...(validationReceiptMiss ? { validationReceiptMiss } : {}),
+});
+
+const publicPort = Number(process.env.SERVER_PORT || 3000);
+const publicHost = process.env.SERVER_HOST || '0.0.0.0';
+const dependencyReadyFile = path.resolve(
+  process.env.MIAODA_DEPENDENCY_READY_FILE ||
+    path.join(projectRoot, '.miaoda-runtime', 'dependencies-ready.json')
+);
+function positiveDuration(name, fallback) {
+  const value = Number(process.env[name] || fallback);
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+const sourceReadyTimeoutMs = positiveDuration(
+  'MIAODA_NEST_SOURCE_READY_TIMEOUT_MS',
+  60_000
+);
+const cacheDrainTimeoutMs = positiveDuration(
+  'MIAODA_NEST_CACHE_DRAIN_TIMEOUT_MS',
+  5_000
+);
+const serviceId = randomUUID();
+let stopping = false;
+
+function resolveProbeHost(host) {
+  const normalized = String(host || '').trim();
+  const lower = normalized.toLowerCase();
+  if (!normalized || lower === '0.0.0.0') return '127.0.0.1';
+  if (lower === '::' || lower === '[::]') return '::1';
+  if (normalized.startsWith('[') && normalized.endsWith(']')) {
+    return normalized.slice(1, -1);
+  }
+  return normalized;
+}
+
+function waitForPort(host, port, timeoutMs = 60_000) {
+  const deadline = Date.now() + timeoutMs;
+  const probeHost = resolveProbeHost(host);
+  return new Promise((resolve, reject) => {
+    const attempt = () => {
+      if (stopping) return reject(new Error('MIAODA_SERVER_RUNTIME_STOPPING'));
+      const socket = net.createConnection({ host: probeHost, port });
+      const failed = () => {
+        socket.destroy();
+        if (Date.now() >= deadline) {
+          reject(new Error(`MIAODA_SERVER_UPSTREAM_TIMEOUT: ${port}`));
+        } else {
+          setTimeout(attempt, 100);
+        }
+      };
+      socket.once('connect', () => {
+        socket.destroy();
+        resolve();
+      });
+      socket.once('error', failed);
+    };
+    attempt();
+  });
+}
+
+function reservePort(host) {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, host, () => {
+      const address = server.address();
+      if (!address || typeof address === 'string') {
+        server.close(() =>
+          reject(new Error('MIAODA_SERVER_UPSTREAM_PORT_RESERVATION_FAILED'))
+        );
+        return;
+      }
+      server.close(error => (error ? reject(error) : resolve(address.port)));
+    });
+  });
+}
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function childIsRunning(child) {
+  return Boolean(
+    child?.pid && child.exitCode === null && child.signalCode === null
+  );
+}
+
+function terminate(child) {
+  if (!child?.pid) return;
+  try {
+    process.kill(-child.pid, 'SIGTERM');
+  } catch {
+    try {
+      child.kill('SIGTERM');
+    } catch {}
+  }
+}
+
+function waitForChildExit(child, timeoutMs) {
+  if (!childIsRunning(child)) return Promise.resolve();
+  return Promise.race([
+    new Promise(resolve => child.once('exit', resolve)),
+    delay(timeoutMs),
+  ]);
+}
+
+function pruneSupersededGenerations() {
+  if (process.env.MIAODA_CACHE_ROOT) return;
+  const pruneScript = fileURLToPath(
+    new URL('./cache-generation-prune.mjs', import.meta.url)
+  );
+  if (!fs.existsSync(pruneScript)) {
+    process.stderr.write(
+      `${JSON.stringify({ event: 'miaoda_cache_generation_prune_failed', error: 'MIAODA_CACHE_GENERATION_PRUNE_SCRIPT_MISSING' })}\n`
+    );
+    return;
+  }
+  const pruneChild = spawn(process.execPath, [pruneScript, '--wait-ms=60000'], {
+    cwd: projectRoot,
+    stdio: 'inherit',
+    env: { ...process.env, MIAODA_WORKSPACE_ROOT: projectRoot },
+  });
+  pruneChild.once('error', error => {
+    process.stderr.write(
+      `${JSON.stringify({ event: 'miaoda_cache_generation_prune_failed', error: error.message })}\n`
+    );
+  });
+  pruneChild.once('exit', (code, signal) => {
+    if (code === 0) return;
+    process.stderr.write(
+      `${JSON.stringify({
+        event: 'miaoda_cache_generation_prune_failed',
+        error: signal ? `signal-${signal}` : `exit-${code}`,
+      })}\n`
+    );
+  });
+}
+
+const internalHost = resolveProbeHost(publicHost);
+const cacheUpstreamPort = await reservePort(internalHost);
+let sourceUpstreamPort = await reservePort(internalHost);
+while (sourceUpstreamPort === cacheUpstreamPort) {
+  sourceUpstreamPort = await reservePort(internalHost);
+}
+const cacheUpstream = {
+  name: 'cache',
+  host: internalHost,
+  port: cacheUpstreamPort,
+  inflight: 0,
+};
+const sourceUpstream = {
+  name: 'source',
+  host: internalHost,
+  port: sourceUpstreamPort,
+  inflight: 0,
+};
+let activeUpstream = cacheUpstream;
+let cacheRetired = false;
+let sourceChild;
+let actionPluginInitChild;
+let actionPluginsInitialized = false;
+
+function retain(upstream) {
+  upstream.inflight += 1;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    upstream.inflight = Math.max(0, upstream.inflight - 1);
+  };
+}
+
+const proxy = http.createServer((request, response) => {
+  const upstream = activeUpstream;
+  const release = retain(upstream);
+  const upstreamRequest = http.request(
+    {
+      hostname: upstream.host,
+      port: upstream.port,
+      method: request.method,
+      path: request.url,
+      headers: request.headers,
+    },
+    upstreamResponse => {
+      if (upstreamResponse.statusMessage) {
+        response.writeHead(
+          upstreamResponse.statusCode || 502,
+          upstreamResponse.statusMessage,
+          upstreamResponse.headers
+        );
+      } else {
+        response.writeHead(
+          upstreamResponse.statusCode || 502,
+          upstreamResponse.headers
+        );
+      }
+      upstreamResponse.pipe(response);
+    }
+  );
+  upstreamRequest.once('error', error => {
+    if (!response.headersSent) {
+      response.writeHead(502, { 'content-type': 'application/json' });
+      response.end(
+        `${JSON.stringify({
+          error: 'MIAODA_NEST_UPSTREAM_UNAVAILABLE',
+          upstream: upstream.name,
+        })}\n`
+      );
+    } else {
+      response.destroy(error);
+    }
+  });
+  request.once('aborted', () => upstreamRequest.destroy());
+  response.once('finish', release);
+  response.once('close', release);
+  request.pipe(upstreamRequest);
+});
+
+proxy.on('upgrade', (request, clientSocket, head) => {
+  const upstream = activeUpstream;
+  const release = retain(upstream);
+  const upstreamSocket = net.createConnection({
+    host: upstream.host,
+    port: upstream.port,
+  });
+  const close = () => {
+    release();
+    clientSocket.destroy();
+    upstreamSocket.destroy();
+  };
+  upstreamSocket.once('connect', () => {
+    const requestLine = `${request.method} ${request.url} HTTP/${request.httpVersion}\r\n`;
+    const headers = [];
+    for (let index = 0; index < request.rawHeaders.length; index += 2) {
+      headers.push(
+        `${request.rawHeaders[index]}: ${request.rawHeaders[index + 1]}`
+      );
+    }
+    upstreamSocket.write(`${requestLine}${headers.join('\r\n')}\r\n\r\n`);
+    if (head.length > 0) upstreamSocket.write(head);
+    clientSocket.pipe(upstreamSocket).pipe(clientSocket);
+  });
+  upstreamSocket.once('error', close);
+  clientSocket.once('error', close);
+  upstreamSocket.once('close', release);
+  clientSocket.once('close', release);
+});
+
+proxy.on('clientError', (_error, socket) => {
+  if (socket.writable) socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
+});
+
+function listen(server, host, port) {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, resolve);
+  });
+}
+
+const bundleSpawnStartedAt = process.hrtime.bigint();
+const cacheChild = spawn(process.execPath, [validated.artifacts.serverBundle], {
+  cwd: projectRoot,
+  detached: true,
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+    NODE_PATH: '',
+    SERVER_HOST: cacheUpstream.host,
+    SERVER_PORT: String(cacheUpstream.port),
+  },
+});
+emitRuntimePhase('bundle_spawn', bundleSpawnStartedAt, {
+  childPid: cacheChild.pid,
+  upstreamPort: cacheUpstream.port,
+});
+cacheChild.once('exit', (code, signal) => {
+  if (stopping || cacheRetired) return;
+  process.stderr.write(
+    `${JSON.stringify({ event: 'miaoda_nest_cache_runtime_exited', code, signal })}\n`
+  );
+  if (activeUpstream === cacheUpstream) process.exit(code || 1);
+});
+
+function dependenciesAreReady() {
+  try {
+    const marker = JSON.parse(fs.readFileSync(dependencyReadyFile, 'utf8'));
+    return (
+      marker?.schemaVersion === 1 &&
+      marker.generationId === validated.generation.generationId &&
+      fs.statSync(path.join(projectRoot, 'node_modules')).isDirectory()
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function waitForDependencies() {
+  while (!stopping) {
+    if (dependenciesAreReady()) return;
+    await delay(100);
+  }
+  throw new Error('MIAODA_SERVER_RUNTIME_STOPPING');
+}
+
+async function initializeActionPlugins() {
+  if (actionPluginsInitialized) return;
+  const cli = [
+    process.env.MIAODA_FULLSTACK_CLI_BIN,
+    path.join(
+      projectRoot,
+      'node_modules',
+      '@lark-apaas',
+      'fullstack-cli',
+      'bin',
+      'cli.js'
+    ),
+    '/usr/lib/node_modules/@lark-apaas/fullstack-cli/bin/cli.js',
+  ].find(candidate => candidate && fs.existsSync(candidate));
+  if (!cli) {
+    process.stdout.write(
+      `${JSON.stringify({ event: 'miaoda_action_plugin_init_skipped', reason: 'project-cli-missing' })}\n`
+    );
+    return;
+  }
+  const startedAt = process.hrtime.bigint();
+  actionPluginInitChild = spawn(
+    process.execPath,
+    [cli, 'action-plugin', 'init'],
+    {
+      cwd: projectRoot,
+      detached: true,
+      stdio: 'inherit',
+      env: { ...process.env },
+    }
+  );
+  const code = await new Promise(resolve => {
+    actionPluginInitChild.once('exit', exitCode => resolve(exitCode ?? 1));
+    actionPluginInitChild.once('error', () => resolve(1));
+  });
+  actionPluginInitChild = undefined;
+  process.stdout.write(
+    `${JSON.stringify({
+      event: 'miaoda_action_plugin_init_finished',
+      code,
+      durationMs: Number(durationMs(startedAt).toFixed(3)),
+    })}\n`
+  );
+  if (code !== 0) {
+    process.stderr.write(
+      `${JSON.stringify({
+        event: 'miaoda_action_plugin_init_failed',
+        code,
+        continueStartup: true,
+      })}\n`
+    );
+    return;
+  }
+  actionPluginsInitialized = true;
+}
+
+async function drainCacheRuntime() {
+  const deadline = Date.now() + cacheDrainTimeoutMs;
+  while (!stopping && cacheUpstream.inflight > 0 && Date.now() < deadline) {
+    await delay(25);
+  }
+  cacheRetired = true;
+  terminate(cacheChild);
+  await waitForChildExit(cacheChild, 1_000);
+  process.stdout.write(
+    `${JSON.stringify({
+      event: 'miaoda_nest_cache_runtime_retired',
+      remainingInflight: cacheUpstream.inflight,
+    })}\n`
+  );
+  pruneSupersededGenerations();
+}
+
+async function promoteSourceRuntime() {
+  await waitForDependencies();
+  if (stopping) return;
+  const startedAt = process.hrtime.bigint();
+  process.stdout.write(
+    `${JSON.stringify({
+      event: 'miaoda_nest_source_runtime_starting',
+      dependencyReadyFile,
+    })}\n`
+  );
+  await initializeActionPlugins();
+  if (stopping) return;
+  const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  sourceChild = spawn(npmCommand, ['run', 'dev:server'], {
+    cwd: projectRoot,
+    detached: true,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      MIAODA_CACHE_BOOTSTRAP_ENABLED: 'false',
+      SERVER_HOST: sourceUpstream.host,
+      SERVER_PORT: String(sourceUpstream.port),
+    },
+  });
+  let sourceExit;
+  let sourcePromoted = false;
+  const sourceExitPromise = new Promise((_, reject) => {
+    sourceChild.once('exit', (code, signal) => {
+      sourceExit = { code, signal };
+      if (stopping) return;
+      process.stderr.write(
+        `${JSON.stringify({ event: 'miaoda_nest_source_runtime_exited', code, signal })}\n`
+      );
+      if (sourcePromoted) {
+        // The outer dev supervisor restarts this bridge. It first restores the
+        // already-sealed cache worker, then promotes the dependency-backed worker.
+        process.exit(code || 1);
+        return;
+      }
+      reject(
+        new Error(
+          `MIAODA_NEST_SOURCE_RUNTIME_EXITED_BEFORE_READY: code=${code} signal=${signal}`
+        )
+      );
+    });
+    sourceChild.once('error', reject);
+  });
+  await Promise.race([
+    waitForPort(sourceUpstream.host, sourceUpstream.port, sourceReadyTimeoutMs),
+    sourceExitPromise,
+  ]);
+  sourcePromoted = true;
+  if (sourceExit || !childIsRunning(sourceChild)) {
+    throw new Error('MIAODA_NEST_SOURCE_RUNTIME_EXITED_DURING_PROMOTION');
+  }
+  if (stopping) return;
+  activeUpstream = sourceUpstream;
+  process.stdout.write(
+    `${JSON.stringify({
+      event: 'miaoda_nest_source_runtime_ready',
+      pid: sourceChild.pid,
+      supervisorPid: process.pid,
+      serviceId,
+      port: publicPort,
+      upstreamPort: sourceUpstream.port,
+      cutoverDurationMs: Number(durationMs(startedAt).toFixed(3)),
+    })}\n`
+  );
+  void drainCacheRuntime();
+}
+
+async function close(signal) {
+  if (stopping) return;
+  stopping = true;
+  process.stdout.write(
+    `${JSON.stringify({ event: 'miaoda_nest_runtime_stopping', signal })}\n`
+  );
+  proxy.close();
+  terminate(actionPluginInitChild);
+  terminate(sourceChild);
+  terminate(cacheChild);
+  setTimeout(() => process.exit(0), 250).unref();
+}
+
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.once(signal, () => void close(signal));
+}
+
+const listenWaitStartedAt = process.hrtime.bigint();
+await waitForPort(cacheUpstream.host, cacheUpstream.port);
+await listen(proxy, publicHost, publicPort);
+emitRuntimePhase('listen_wait', listenWaitStartedAt, {
+  port: publicPort,
+  cacheUpstreamPort: cacheUpstream.port,
+});
+publishServingReadyMarker(servingReadyMarker);
+process.stdout.write(
+  `${JSON.stringify({
+    event: 'miaoda_nest_cache_runtime_ready',
+    pid: cacheChild.pid,
+    supervisorPid: process.pid,
+    serviceId,
+    generationId: validated.generation.generationId,
+    port: publicPort,
+    startupDurationMs: Number(durationMs(runtimeStartedAt).toFixed(3)),
+  })}\n`
+);
+async function promoteSourceRuntimeWithRetry() {
+  try {
+    await promoteSourceRuntime();
+  } catch (error) {
+    if (stopping) return;
+    terminate(sourceChild);
+    await waitForChildExit(sourceChild, 1_000);
+    cacheRetired = true;
+    proxy.close();
+    terminate(cacheChild);
+    process.stderr.write(
+      `${JSON.stringify({
+        event: 'miaoda_nest_source_runtime_promotion_failed',
+        cacheServicePreserved: false,
+        fallback: 'original-preview-retry',
+        error: error instanceof Error ? error.message : String(error),
+      })}\n`
+    );
+    process.exitCode = 1;
+    setTimeout(() => process.exit(1), 250).unref();
+  }
+}
+
+void promoteSourceRuntimeWithRetry();
+await new Promise(() => {});