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

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

@@ -0,0 +1,655 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import http from 'node:http';
+import net from 'node:net';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  validateCacheGeneration,
+  validateCacheGenerationReceipt,
+} from './cache-generation-preflight.mjs';
+
+const projectRoot = path.resolve(
+  process.env.MIAODA_WORKSPACE_ROOT || process.cwd()
+);
+const requestedCacheRoot = path.resolve(
+  process.env.MIAODA_CACHE_ROOT ||
+    path.join(projectRoot, '.miaoda-cache', 'current')
+);
+const cacheRoot = fs.realpathSync(requestedCacheRoot);
+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 publicHost = process.env.SERVER_HOST || '0.0.0.0';
+const publicPort = Number(process.env.SERVER_PORT || 3000);
+const cacheNodeModules = path.join(cacheRoot, 'server', 'node_modules');
+const cacheBundleFile = path.join(
+  cacheRoot,
+  'server',
+  'bundle',
+  'server.bundle.cjs'
+);
+const cacheBundleMetadataFile = `${cacheBundleFile}.meta.json`;
+const resolverFile = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  'server-cache-module-resolver.cjs'
+);
+const readyMarker =
+  process.env.MIAODA_NEST_TRANSITION_READY_FILE ||
+  '/tmp/event/MIAODA_NEST_TRANSITION_SERVING_READY';
+const pollIntervalMs = Number(
+  process.env.MIAODA_NEST_SOURCE_POLL_INTERVAL_MS || 250
+);
+const restartDebounceMs = Number(
+  process.env.MIAODA_NEST_SOURCE_RESTART_DEBOUNCE_MS || 120
+);
+const startupTimeoutMs = Number(
+  process.env.MIAODA_NEST_SOURCE_READY_TIMEOUT_MS || 60_000
+);
+const drainTimeoutMs = Number(
+  process.env.MIAODA_NEST_TRANSITION_DRAIN_TIMEOUT_MS || 5_000
+);
+
+function output(name, message) {
+  for (const line of String(message).split(/\r?\n/)) {
+    if (line) process.stdout.write(`MIAODA_LOG\t${name}\t${line}\n`);
+  }
+}
+
+function event(name, details = {}) {
+  process.stdout.write(
+    `${JSON.stringify({ event: name, runtime: 'nest-transition', ...details })}\n`
+  );
+}
+
+function validateGeneration() {
+  let validated;
+  const receiptFile = process.env.MIAODA_CACHE_VALIDATION_RECEIPT_FILE;
+  if (receiptFile) {
+    try {
+      validated = validateCacheGenerationReceipt({
+        projectRoot,
+        cacheRoot,
+        runtimeManifestFile,
+        receiptFile,
+        artifactScope: 'server',
+      });
+    } catch {
+      // Receipt is an optimization only; a miss falls back to full validation.
+    }
+  }
+  validated ??= validateCacheGeneration({
+    projectRoot,
+    cacheRoot,
+    runtimeManifestFile,
+    artifactScope: 'server',
+  });
+  if (
+    validated.generation.schemaVersion !== 4 ||
+    validated.generation.serverRuntimeMode !==
+      'workspace-source-dependencies' ||
+    !validated.serverDependencies
+  ) {
+    throw new Error('MIAODA_SERVER_TRANSITION_GENERATION_UNSUPPORTED');
+  }
+  return validated;
+}
+
+let validated;
+try {
+  validated = validateGeneration();
+  if (!fs.existsSync(resolverFile)) {
+    throw new Error(`MIAODA_CACHE_BOOTSTRAP_INPUT_MISSING: ${resolverFile}`);
+  }
+  if (validateOnly) {
+    process.stdout.write(
+      `${JSON.stringify({
+        valid: true,
+        generationId: validated.generation.generationId,
+        sourceEntry: validated.serverDependencies.sourceEntry,
+      })}\n`
+    );
+    process.exit(0);
+  }
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
+  process.exit(2);
+}
+
+if (
+  !Number.isSafeInteger(publicPort) ||
+  publicPort <= 0 ||
+  publicPort > 65_535
+) {
+  throw new Error('MIAODA_NEST_TRANSITION_PORT_INVALID');
+}
+
+const packageJsonFile = path.join(projectRoot, 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonFile, 'utf8'));
+const configuredProbe =
+  packageJson.miaodaCache?.availabilityProbe?.readiness ?? {};
+const probe = {
+  ...configuredProbe,
+  // The platform mounts the application server below CLIENT_BASE_PATH.  Use
+  // that runtime fact before template defaults so old and new workspaces share
+  // the same readiness contract.
+  path:
+    process.env.MIAODA_SERVER_READY_PATH ||
+    process.env.CLIENT_BASE_PATH ||
+    configuredProbe.path ||
+    '/',
+  expectedStatus: Number(configuredProbe.expectedStatus ?? 200),
+};
+const sourceEntry = path.resolve(
+  projectRoot,
+  validated.serverDependencies.sourceEntry
+);
+if (!fs.existsSync(sourceEntry)) {
+  throw new Error(`MIAODA_NEST_SOURCE_ENTRY_MISSING: ${sourceEntry}`);
+}
+const cacheRequire = createRequire(
+  path.join(cacheRoot, 'server', 'cache-runtime-entry.cjs')
+);
+const bootstrapFiles = validated.serverDependencies.bootstrapModules.map(
+  specifier => {
+    try {
+      return cacheRequire.resolve(specifier);
+    } catch {
+      throw new Error(`MIAODA_NEST_BOOTSTRAP_MODULE_MISSING: ${specifier}`);
+    }
+  }
+);
+const projectRootToken = '${MIAODA_WORKSPACE_ROOT}';
+const materializeProjectPaths = value => {
+  if (typeof value === 'string') {
+    if (value === projectRootToken) return projectRoot;
+    if (value.startsWith(`${projectRootToken}/`)) {
+      const resolved = path.resolve(
+        projectRoot,
+        value.slice(projectRootToken.length + 1)
+      );
+      if (!resolved.startsWith(`${projectRoot}${path.sep}`)) {
+        throw new Error('MIAODA_NEST_TRANSITION_TSCONFIG_PATH_REJECTED');
+      }
+      return resolved;
+    }
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(materializeProjectPaths);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        materializeProjectPaths(entry),
+      ])
+    );
+  }
+  return value;
+};
+const transitionTsconfigDirectory = path.join(
+  projectRoot,
+  '.miaoda-runtime',
+  'nest-transition'
+);
+fs.mkdirSync(transitionTsconfigDirectory, { recursive: true });
+const transitionTsconfigFile = path.join(
+  transitionTsconfigDirectory,
+  `tsconfig.${validated.generation.generationId}.json`
+);
+const transitionTsconfigTemporary = `${transitionTsconfigFile}.${process.pid}.tmp`;
+fs.writeFileSync(
+  transitionTsconfigTemporary,
+  `${JSON.stringify(
+    {
+      compilerOptions: {
+        ...materializeProjectPaths(
+          validated.serverDependencies.transitionCompilerOptions
+        ),
+        // The transition runtime only transpiles files that Node actually loads.
+        // Type-check/build outputs remain owned by the unchanged full service.
+        incremental: false,
+        composite: false,
+        declaration: false,
+        declarationMap: false,
+      },
+      'ts-node': { transpileOnly: true, files: false },
+    },
+    null,
+    2
+  )}\n`,
+  { mode: 0o600 }
+);
+fs.renameSync(transitionTsconfigTemporary, transitionTsconfigFile);
+
+function reservePort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      const port = address && typeof address !== 'string' ? address.port : 0;
+      server.close(error => (error ? reject(error) : resolve(port)));
+    });
+  });
+}
+
+async function waitForProbe(port, child) {
+  const deadline = Date.now() + startupTimeoutMs;
+  let lastError;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      throw new Error(
+        `MIAODA_NEST_TRANSITION_EXITED: ${child.exitCode ?? child.signalCode}`
+      );
+    }
+    try {
+      const response = await fetch(
+        `http://127.0.0.1:${port}${probe.path || '/'}`
+      );
+      const body = await response.text();
+      if (
+        response.status === Number(probe.expectedStatus ?? 200) &&
+        (!probe.bodyIncludes || body.includes(probe.bodyIncludes))
+      ) {
+        return;
+      }
+      lastError = new Error(
+        `probe returned ${response.status}, expected ${probe.expectedStatus ?? 200}`
+      );
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error(
+    `MIAODA_NEST_TRANSITION_READY_TIMEOUT: ${
+      lastError instanceof Error ? lastError.message : String(lastError)
+    }`
+  );
+}
+
+function terminate(child, signal = 'SIGTERM') {
+  if (!child || child.exitCode !== null || child.signalCode !== null) return;
+  try {
+    child.kill(signal);
+  } catch {}
+}
+
+let activeBackend;
+let closing = false;
+let starting = false;
+let preferInitialBundle = false;
+let restartPending = false;
+let restartTimer;
+let watchTimer;
+const children = new Set();
+
+function spawnSourceWorker(port) {
+  const args = [resolverFile, ...bootstrapFiles].flatMap(file => ['-r', file]);
+  args.push(sourceEntry);
+  const childEnvironment = {
+    ...process.env,
+    NODE_ENV: 'development',
+    SERVER_HOST: '127.0.0.1',
+    SERVER_PORT: String(port),
+    NODE_PATH: cacheNodeModules,
+    MIAODA_SERVER_CACHE_NODE_MODULES: cacheNodeModules,
+    MIAODA_CACHE_BOOTSTRAP_ENABLED: 'false',
+    TS_NODE_TRANSPILE_ONLY: 'true',
+    TS_NODE_PREFER_TS_EXTS: 'true',
+    TS_NODE_PROJECT: transitionTsconfigFile,
+  };
+  // This is a user-facing development service, not the isolated generation
+  // probe. Inherit the same real database/auth environment as the unchanged
+  // full service. In particular, never carry the OpenAPI probe's
+  // DEPRECATED_SKIP_INIT_DB_CONNECTION flag into the transition runtime: that
+  // flag injects a placeholder database object and makes business routes fail.
+  delete childEnvironment.MIAODA_SERVER_CACHE_PROBE;
+  delete childEnvironment.DEPRECATED_SKIP_INIT_DB_CONNECTION;
+  const child = spawn(process.execPath, args, {
+    cwd: projectRoot,
+    env: childEnvironment,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  children.add(child);
+  child.stdout?.on('data', chunk => output('server', chunk));
+  child.stderr?.on('data', chunk => output('server', chunk));
+  child.once('exit', (code, signal) => {
+    children.delete(child);
+    event('miaoda_nest_transition_worker_exit', {
+      pid: child.pid,
+      code,
+      signal,
+      active: activeBackend?.child === child,
+    });
+    if (!closing && activeBackend?.child === child) scheduleRestart(0);
+  });
+  return child;
+}
+
+function workspaceSourceSha256() {
+  const hash = crypto.createHash('sha256');
+  for (const file of workspaceFiles()) {
+    const relative = path.relative(projectRoot, file).split(path.sep).join('/');
+    if (
+      !['server/', 'shared/', 'src/'].some(root => relative.startsWith(root))
+    ) {
+      continue;
+    }
+    hash.update(relative);
+    hash.update('\0');
+    hash.update(fs.readFileSync(file));
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+function initialBundleIsConsumable() {
+  try {
+    const metadata = JSON.parse(
+      fs.readFileSync(cacheBundleMetadataFile, 'utf8')
+    );
+    return (
+      metadata.schemaVersion === 2 &&
+      metadata.consumable === true &&
+      metadata.workspaceSourceSha256 === workspaceSourceSha256() &&
+      metadata.bundleSha256 ===
+        crypto
+          .createHash('sha256')
+          .update(fs.readFileSync(cacheBundleFile))
+          .digest('hex')
+    );
+  } catch {
+    return false;
+  }
+}
+
+function spawnBundleWorker(port) {
+  const childEnvironment = {
+    ...process.env,
+    NODE_ENV: 'development',
+    SERVER_HOST: '127.0.0.1',
+    SERVER_PORT: String(port),
+    NODE_PATH: '',
+    MIAODA_WORKSPACE_ROOT: projectRoot,
+    MIAODA_CACHE_BOOTSTRAP_ENABLED: 'false',
+  };
+  delete childEnvironment.MIAODA_SERVER_CACHE_PROBE;
+  delete childEnvironment.DEPRECATED_SKIP_INIT_DB_CONNECTION;
+  const child = spawn(process.execPath, [cacheBundleFile], {
+    // Keep process.cwd() identical to the normal NestJS service. Application
+    // code and framework modules resolve .env, server/capabilities,
+    // dist/client and other workspace files from this root. Assets derived
+    // from __dirname, __filename and import.meta.url are still sealed beside
+    // the bundle and do not depend on cwd.
+    cwd: projectRoot,
+    env: childEnvironment,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  children.add(child);
+  child.stdout?.on('data', chunk => output('server', chunk));
+  child.stderr?.on('data', chunk => output('server', chunk));
+  child.once('exit', (code, signal) => {
+    children.delete(child);
+    event('miaoda_nest_transition_worker_exit', {
+      pid: child.pid,
+      code,
+      signal,
+      workerMode: 'bundle',
+      active: activeBackend?.child === child,
+    });
+    if (!closing && activeBackend?.child === child) {
+      preferInitialBundle = false;
+      scheduleRestart(0);
+    }
+  });
+  return child;
+}
+
+async function drainBackend(backend) {
+  const deadline = Date.now() + drainTimeoutMs;
+  while (backend.activeRequests > 0 && Date.now() < deadline) {
+    await new Promise(resolve => setTimeout(resolve, 25));
+  }
+  terminate(backend.child);
+  setTimeout(() => terminate(backend.child, 'SIGKILL'), 1_000).unref();
+}
+
+async function startCandidate() {
+  if (closing || starting) {
+    restartPending = true;
+    return;
+  }
+  starting = true;
+  const startedAt = Date.now();
+  let child;
+  let workerMode;
+  try {
+    const port = await reservePort();
+    workerMode = preferInitialBundle ? 'bundle' : 'workspace-source';
+    child = preferInitialBundle
+      ? spawnBundleWorker(port)
+      : spawnSourceWorker(port);
+    await waitForProbe(port, child);
+    const previous = activeBackend;
+    activeBackend = {
+      kind: 'transition',
+      workerMode,
+      port,
+      child,
+      activeRequests: 0,
+      sourceFingerprint: workspaceFingerprint(),
+    };
+    event('miaoda_nest_transition_ready', {
+      generationId: validated.generation.generationId,
+      pid: child.pid,
+      port: publicPort,
+      upstreamPort: port,
+      startupMs: Date.now() - startedAt,
+      workerMode,
+      replacedPid: previous?.child.pid,
+    });
+    publishReady();
+    if (previous) void drainBackend(previous);
+  } catch (error) {
+    terminate(child);
+    if (workerMode === 'bundle') {
+      // A bundle is attempted only once. If it cannot become ready, retrying
+      // the same immutable bytes cannot heal it; fall back to live Workspace
+      // source plus the sealed dependency tree.
+      preferInitialBundle = false;
+    }
+    output(
+      'server',
+      `Transition source candidate failed; keeping current service: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+    if (!activeBackend && !closing) scheduleRestart(500);
+  } finally {
+    starting = false;
+    if (restartPending) {
+      restartPending = false;
+      scheduleRestart(restartDebounceMs);
+    }
+  }
+}
+
+function scheduleRestart(delay = restartDebounceMs) {
+  if (closing) return;
+  if (restartTimer) clearTimeout(restartTimer);
+  restartTimer = setTimeout(() => {
+    restartTimer = undefined;
+    void startCandidate();
+  }, delay);
+}
+
+function workspaceFiles() {
+  const files = [];
+  const visit = directory => {
+    if (!fs.existsSync(directory)) return;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const candidate = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) visit(candidate);
+      else if (entry.isFile()) files.push(candidate);
+    }
+  };
+  for (const root of ['server', 'shared', 'src']) {
+    visit(path.join(projectRoot, root));
+  }
+  for (const relative of [
+    'package.json',
+    'nest-cli.json',
+    'tsconfig.json',
+    'tsconfig.node.json',
+    '.env',
+    '.env.development',
+    '.env.development.local',
+  ]) {
+    const file = path.join(projectRoot, relative);
+    if (fs.existsSync(file)) files.push(file);
+  }
+  return files.sort();
+}
+
+function workspaceFingerprint() {
+  return workspaceFiles()
+    .map(file => {
+      const stat = fs.statSync(file);
+      return `${path.relative(projectRoot, file)}:${stat.size}:${stat.mtimeMs}`;
+    })
+    .join('|');
+}
+
+preferInitialBundle =
+  process.env.MIAODA_NEST_DISABLE_INITIAL_BUNDLE !== 'true' &&
+  initialBundleIsConsumable();
+
+function publishReady() {
+  fs.mkdirSync(path.dirname(readyMarker), { recursive: true });
+  const temporary = `${readyMarker}.${process.pid}.tmp`;
+  fs.writeFileSync(
+    temporary,
+    `${JSON.stringify({
+      schemaVersion: 1,
+      generationId: validated.generation.generationId,
+      pid: process.pid,
+      port: publicPort,
+    })}\n`,
+    { mode: 0o600 }
+  );
+  fs.renameSync(temporary, readyMarker);
+}
+
+const proxy = http.createServer((request, response) => {
+  if (request.url === '/dev/cache-runtime') {
+    response.statusCode = activeBackend ? 200 : 503;
+    response.setHeader('content-type', 'application/json');
+    response.end(
+      JSON.stringify({
+        mode: 'transition',
+        runtime: 'nest',
+        generationId: validated.generation.generationId,
+        pid: activeBackend?.child.pid,
+        ready: Boolean(activeBackend),
+      })
+    );
+    return;
+  }
+  const backend = activeBackend;
+  if (!backend) {
+    response.statusCode = 503;
+    response.end('MIAODA_NEST_TRANSITION_NOT_READY');
+    return;
+  }
+  backend.activeRequests++;
+  const upstream = http.request(
+    {
+      host: '127.0.0.1',
+      port: backend.port,
+      method: request.method,
+      path: request.url,
+      headers: request.headers,
+    },
+    upstreamResponse => {
+      response.writeHead(
+        upstreamResponse.statusCode || 502,
+        upstreamResponse.headers
+      );
+      upstreamResponse.pipe(response);
+    }
+  );
+  const release = () => {
+    if (backend.activeRequests > 0) backend.activeRequests--;
+  };
+  response.once('close', release);
+  upstream.once('error', error => {
+    if (!response.headersSent) response.statusCode = 502;
+    response.end(error.message);
+  });
+  request.pipe(upstream);
+});
+
+proxy.on('upgrade', (request, socket, head) => {
+  const backend = activeBackend;
+  if (!backend) return socket.destroy();
+  const upstream = net.createConnection(
+    { host: '127.0.0.1', port: backend.port },
+    () => {
+      let headers = `${request.method} ${request.url} HTTP/${request.httpVersion}\r\n`;
+      for (let index = 0; index < request.rawHeaders.length; index += 2) {
+        headers += `${request.rawHeaders[index]}: ${request.rawHeaders[index + 1]}\r\n`;
+      }
+      upstream.write(`${headers}\r\n`);
+      if (head.length > 0) upstream.write(head);
+      socket.pipe(upstream).pipe(socket);
+    }
+  );
+  upstream.once('error', () => socket.destroy());
+});
+
+async function close(signal) {
+  if (closing) return;
+  closing = true;
+  if (watchTimer) clearInterval(watchTimer);
+  if (restartTimer) clearTimeout(restartTimer);
+  fs.rmSync(readyMarker, { force: true });
+  await new Promise(resolve => proxy.close(resolve));
+  for (const child of children) terminate(child);
+  setTimeout(() => {
+    for (const child of children) terminate(child, 'SIGKILL');
+  }, 1_000).unref();
+  event('miaoda_nest_transition_stopped', { signal });
+}
+
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.once(signal, () => void close(signal));
+}
+
+fs.rmSync(readyMarker, { force: true });
+await new Promise((resolve, reject) => {
+  proxy.once('error', reject);
+  proxy.listen(publicPort, publicHost, resolve);
+});
+await startCandidate();
+let fingerprint = workspaceFingerprint();
+watchTimer = setInterval(() => {
+  try {
+    const current = workspaceFingerprint();
+    if (current !== fingerprint) {
+      fingerprint = current;
+      preferInitialBundle = false;
+      scheduleRestart();
+    }
+  } catch (error) {
+    output('server', error instanceof Error ? error.message : String(error));
+  }
+}, pollIntervalMs);
+watchTimer.unref();