@pulse-compute/provider-fastly 0.0.0 → 1.0.0-beta.1

package/src/compiler/fastly-command-entry.js

@@ -0,0 +1,390 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { getDefaultArtifactsDir } = require('@pulse-compute/wasm-build-support/artifacts-dir');
+const { spawnSync } = require('node:child_process');
+const { PACKAGE_VERSION, normalizeArtifact, normalizeDiagnostic } = loadContractsDiagnostics();
+const { resolveAsc } = require('@pulse-compute/wasm-build-support/assemblyscript-compile');
+
+
+function loadContractsDiagnostics() {
+  try {
+    return require('@pulse-compute/wasm-contracts/diagnostics');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND' && String(error.message).includes('@pulse-compute/wasm-contracts')) {
+      return require('../../../../wasm/packages/contracts/src/diagnostics.js');
+    }
+    throw error;
+  }
+}
+
+const PHASE = '13C.1';
+const FASTLY_COMMAND_ENTRY_VERSION = 'pulsewasm.fastly-command-entry.v1';
+const FASTLY_START_EXPORT_AUDIT_VERSION = 'pulsewasm.fastly-start-export-audit.v1';
+const FASTLY_COMMAND_IMPORT_AUDIT_VERSION = 'pulsewasm.fastly-command-import-audit.v1';
+const FASTLY_SERVE_GATE_VERSION = 'pulsewasm.fastly-serve-gate.v1';
+const FASTLY_COMMAND_SMOKE_VERSION = 'pulsewasm.fastly-command-smoke.v1';
+
+function sha256Text(text) { return crypto.createHash('sha256').update(String(text || ''), 'utf8').digest('hex'); }
+function sha256Buffer(buffer) { return crypto.createHash('sha256').update(buffer).digest('hex'); }
+function makeFile(file, text) { return { file, text, bytes: Buffer.byteLength(text, 'utf8'), sha256: sha256Text(text) }; }
+function normalizeSlash(value) { return String(value || '').replace(/\\/g, '/'); }
+function truncate(value, max = 12000) { const text = String(value || ''); return text.length > max ? `${text.slice(0, max)}\n…<truncated ${text.length - max} chars>` : text; }
+function diag(code, message, hint, details) {
+  return normalizeDiagnostic({ phase: 'fastly-command-entry', severity: 'error', code, message, hint, details, loc: { file: '<fastly-command-entry>' } });
+}
+function fileRecord(filePath, cwd, kind) {
+  const buffer = fs.readFileSync(filePath);
+  return { file: normalizeSlash(path.relative(cwd, filePath)), kind, bytes: buffer.length, sha256: sha256Buffer(buffer) };
+}
+
+function buildFastlyCommandEntrySource() {
+  return `/* Generated by PulseWasm.
+ * Fastly command-style entrypoint proof.
+ * This module is Fastly-target-specific. It deliberately exports _start.
+ * It is not the generic PulseWasm runtime and it is not an SDK dependency.
+ */
+type FastlyStatus = i32;
+type BodyHandle = u32;
+type BodyWriteEnd = u32;
+type ResponseHandle = u32;
+type ptr = usize;
+type strptr = ArrayBuffer;
+
+@external("fastly_http_body", "new")
+declare function fastly_http_body_new(handle_out: ptr): FastlyStatus;
+
+@external("fastly_http_body", "write")
+declare function fastly_http_body_write(
+  body_handle: BodyHandle,
+  buf: strptr,
+  buf_len: usize,
+  end: BodyWriteEnd,
+  nwritten_out: ptr
+): FastlyStatus;
+
+@external("fastly_http_resp", "new")
+declare function fastly_http_resp_new(resp_handle_out: ptr): FastlyStatus;
+
+@external("fastly_http_resp", "status_set")
+declare function fastly_http_resp_status_set(resp_handle: ResponseHandle, status: u16): FastlyStatus;
+
+@external("fastly_http_resp", "header_insert")
+declare function fastly_http_resp_header_insert(
+  resp_handle: ResponseHandle,
+  name: strptr,
+  name_len: usize,
+  value: strptr,
+  value_len: usize
+): FastlyStatus;
+
+@external("fastly_http_resp", "send_downstream")
+declare function fastly_http_resp_send_downstream(
+  resp_handle: ResponseHandle,
+  body_handle: BodyHandle,
+  streaming: u32
+): FastlyStatus;
+
+function check(status: FastlyStatus): void {
+  if (status != 0) unreachable();
+}
+
+function outPtr(): usize {
+  const ptr = __alloc(4);
+  store<u32>(ptr, 0);
+  return ptr;
+}
+
+function writeHeader(resp: ResponseHandle, name: string, value: string): void {
+  const encodedName = String.UTF8.encode(name, false);
+  const encodedValue = String.UTF8.encode(value, false);
+  check(fastly_http_resp_header_insert(resp, encodedName, encodedName.byteLength, encodedValue, encodedValue.byteLength));
+}
+
+function writeBody(body: BodyHandle, text: string): void {
+  const bytes = String.UTF8.encode(text, false);
+  const writtenOut = outPtr();
+  check(fastly_http_body_write(body, bytes, bytes.byteLength, 0, writtenOut));
+}
+
+export function __pulsewasm_abort(message: string | null, fileName: string | null, line: u32, column: u32): void {
+  unreachable();
+}
+
+export function _start(): void {
+  const responseOut = outPtr();
+  check(fastly_http_resp_new(responseOut));
+  const response = load<ResponseHandle>(responseOut);
+
+  const bodyOut = outPtr();
+  check(fastly_http_body_new(bodyOut));
+  const body = load<BodyHandle>(bodyOut);
+
+  check(fastly_http_resp_status_set(response, 200));
+  writeHeader(response, "Content-Type", "text/plain; charset=utf-8");
+  writeHeader(response, "X-PulseWasm-Fastly", "13C.1");
+  writeBody(body, "pulsewasm fastly command entrypoint ok\\n");
+  check(fastly_http_resp_send_downstream(response, body, 0));
+}
+`;
+}
+
+function buildFastlyToml() {
+  return `manifest_version = 3
+name = "pulsewasm-fastly-command-proof"
+description = "PulseWasm Fastly command entrypoint proof."
+language = "other"
+
+[scripts]
+build = "echo 'PulseWasm custom build: use fastly compute pack --wasm-binary artifacts/generated/fastly/pulsewasm-compute.wasm'"
+`;
+}
+
+function buildReadme() {
+  return `# PulseWasm Fastly Command Entrypoint
+
+This scaffold fixes the Fastly target shape discovered by \`fastly compute serve\`:
+
+\`\`\`text
+failed to find function export '_start'
+\`\`\`
+
+The generated Wasm is a command-style Fastly Compute candidate with an exported \`_start\` and a minimal downstream response path using Fastly hostcall imports.
+
+## Candidate commands
+
+\`\`\`bash
+fastly compute pack --wasm-binary artifacts/generated/fastly/pulsewasm-compute.wasm
+fastly compute serve
+curl -i http://127.0.0.1:7676/
+\`\`\`
+
+## Boundary
+
+This phase proves command target shape. It does not yet wire the full PulseWasm compiled runtime into Fastly hostcalls.
+`;
+}
+
+function compileCommandEntry({ cwd, outDir, sourceText }) {
+  const diagnostics = [];
+  const asc = resolveAsc(cwd);
+  if (!asc) {
+    diagnostics.push(diag('PULSEWASM_FASTLY_COMMAND_ASC_MISSING', 'AssemblyScript compiler dependency was not found.', 'Run npm install before generating the Fastly command entrypoint.'));
+    return { diagnostics, warnings: [], outputFiles: [] };
+  }
+
+  const stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pulsewasm-fastly-command-'));
+  const srcDir = path.join(stagingDir, 'generated', 'fastly');
+  fs.mkdirSync(srcDir, { recursive: true });
+  const entry = path.join(srcDir, 'fastly-entry.as.ts');
+  fs.writeFileSync(entry, sourceText, 'utf8');
+
+  const outputDir = path.join(outDir || getDefaultArtifactsDir(cwd), 'generated', 'fastly-command');
+  fs.mkdirSync(outputDir, { recursive: true });
+  const wasmFile = path.join(outputDir, 'pulsewasm-fastly-command.wasm');
+  const ascArgs = [
+    asc.script,
+    'generated/fastly/fastly-entry.as.ts',
+    '--outFile', wasmFile,
+    '--runtime', 'stub',
+    '--noAssert',
+    '--optimize',
+    '--use', 'abort=generated/fastly/fastly-entry.as/__pulsewasm_abort'
+  ];
+  const proc = spawnSync(asc.executable, ascArgs, { cwd: stagingDir, encoding: 'utf8', maxBuffer: 1024 * 1024 * 16 });
+  if (proc.error || proc.status !== 0) {
+    diagnostics.push(diag('PULSEWASM_FASTLY_COMMAND_AS_COMPILE_FAILED', `Fastly command entry AssemblyScript compile failed${proc.status !== undefined ? ` with exit code ${proc.status}` : ''}.`, 'Inspect fastly-command-smoke.json stderr/stdout.', { stdout: truncate(proc.stdout), stderr: truncate(proc.stderr), exitCode: proc.status }));
+  }
+
+  const outputFiles = [];
+  if (fs.existsSync(wasmFile)) outputFiles.push(fileRecord(wasmFile, cwd, 'fastly-command-wasm'));
+  return {
+    diagnostics,
+    warnings: [],
+    wasmFile,
+    outputFiles,
+    command: { executable: asc.display, args: ascArgs.slice(1).map((arg) => path.isAbsolute(arg) ? normalizeSlash(path.relative(cwd, arg)) : arg) },
+    result: { exitCode: proc.status, stdout: truncate(proc.stdout), stderr: truncate(proc.stderr) }
+  };
+}
+
+function wasmAudit(wasmFile) {
+  if (!wasmFile || !fs.existsSync(wasmFile)) return { imports: [], exports: [], hasStart: false, unexpectedImports: [] };
+  const mod = new WebAssembly.Module(fs.readFileSync(wasmFile));
+  const imports = WebAssembly.Module.imports(mod).map((item) => ({ module: item.module, name: item.name, kind: item.kind }));
+  const exports = WebAssembly.Module.exports(mod).map((item) => ({ name: item.name, kind: item.kind }));
+  const expected = new Set([
+    'fastly_http_body::new',
+    'fastly_http_body::write',
+    'fastly_http_resp::new',
+    'fastly_http_resp::status_set',
+    'fastly_http_resp::header_insert',
+    'fastly_http_resp::send_downstream'
+  ]);
+  const unexpectedImports = imports.filter((item) => !expected.has(`${item.module}::${item.name}`));
+  return { imports, exports, hasStart: exports.some((item) => item.name === '_start' && item.kind === 'function'), unexpectedImports };
+}
+
+function buildArtifacts({ generatedBy, compile, audit, cwd, sourceFile, wasmFile }) {
+  const importAudit = normalizeArtifact({
+    version: FASTLY_COMMAND_IMPORT_AUDIT_VERSION,
+    generatedBy,
+    phase: PHASE,
+    status: audit.unexpectedImports.length === 0 ? 'ok' : 'error',
+    imports: audit.imports,
+    unexpectedImports: audit.unexpectedImports,
+    policy: {
+      envAbortForbidden: true,
+      expectedFastlyImportsOnly: true,
+      packIsNotRuntimeGate: true
+    },
+    summary: {
+      imports: audit.imports.length,
+      unexpectedImports: audit.unexpectedImports.length,
+      envAbort: audit.imports.some((item) => item.module === 'env' && item.name === 'abort')
+    }
+  }, cwd);
+
+  const startAudit = normalizeArtifact({
+    version: FASTLY_START_EXPORT_AUDIT_VERSION,
+    generatedBy,
+    phase: PHASE,
+    status: audit.hasStart ? 'ok' : 'error',
+    exports: audit.exports,
+    requiredExport: '_start',
+    summary: { hasStart: audit.hasStart, exports: audit.exports.length }
+  }, cwd);
+
+  const commandSmoke = normalizeArtifact({
+    version: FASTLY_COMMAND_SMOKE_VERSION,
+    generatedBy,
+    phase: PHASE,
+    status: compile.diagnostics.length === 0 && audit.hasStart && audit.unexpectedImports.length === 0 ? 'ok' : 'error',
+    compile: compile.result,
+    command: compile.command,
+    wasm: wasmFile && fs.existsSync(wasmFile) ? fileRecord(wasmFile, cwd, 'fastly-command-wasm') : undefined,
+    smoke: {
+      executedUnderFastlyServe: false,
+      commandShapeCompiled: compile.diagnostics.length === 0,
+      startExportPresent: audit.hasStart,
+      importsExpectedOnly: audit.unexpectedImports.length === 0
+    },
+    summary: {
+      compiled: compile.diagnostics.length === 0,
+      hasStart: audit.hasStart,
+      unexpectedImports: audit.unexpectedImports.length,
+      serveExecuted: false
+    }
+  }, cwd);
+
+  const serveGate = normalizeArtifact({
+    version: FASTLY_SERVE_GATE_VERSION,
+    generatedBy,
+    phase: PHASE,
+    status: audit.hasStart && audit.unexpectedImports.length === 0 ? 'ready-for-serve' : 'error',
+    gatePolicy: {
+      packSuccessDoesNotProveRuntimeCompatibility: true,
+      serveIsFirstRuntimeGate: true,
+      requiredBeforeReadiness: ['_start export', 'expected Fastly imports only', 'fastly compute serve smoke request']
+    },
+    candidateCommands: [
+      'fastly compute pack --wasm-binary artifacts/generated/fastly/pulsewasm-compute.wasm',
+      'fastly compute serve',
+      'curl -i http://127.0.0.1:7676/'
+    ],
+    summary: {
+      packReady: true,
+      serveReady: audit.hasStart && audit.unexpectedImports.length === 0,
+      serveExecuted: false,
+      remoteDeployReady: false
+    }
+  }, cwd);
+
+  const commandEntry = normalizeArtifact({
+    version: FASTLY_COMMAND_ENTRY_VERSION,
+    generatedBy,
+    phase: PHASE,
+    status: commandSmoke.status,
+    posture: {
+      fastlySpecificTargetShape: true,
+      commandStyleWasm: true,
+      startExportRequired: true,
+      genericPulseRuntimeUntouched: true,
+      realFastlyHostcalls: true,
+      sdkDependency: false,
+      sdkReferenceOnly: true,
+      oldAssemblyScriptSdkRevived: false,
+      serveExecuted: false,
+      remoteDeployExecuted: false
+    },
+    source: sourceFile ? { file: sourceFile.file, bytes: sourceFile.bytes, sha256: sourceFile.sha256 } : undefined,
+    linkedArtifacts: {
+      commandSmoke: FASTLY_COMMAND_SMOKE_VERSION,
+      startExportAudit: FASTLY_START_EXPORT_AUDIT_VERSION,
+      importAudit: FASTLY_COMMAND_IMPORT_AUDIT_VERSION,
+      serveGate: FASTLY_SERVE_GATE_VERSION
+    },
+    summary: {
+      compiled: commandSmoke.summary.compiled,
+      hasStart: audit.hasStart,
+      imports: audit.imports.length,
+      unexpectedImports: audit.unexpectedImports.length,
+      envAbort: importAudit.summary.envAbort,
+      wasmBytes: wasmFile && fs.existsSync(wasmFile) ? fs.statSync(wasmFile).size : 0,
+      packReady: true,
+      serveExecuted: false,
+      diagnostics: compile.diagnostics.length + audit.unexpectedImports.length + (audit.hasStart ? 0 : 1)
+    }
+  }, cwd);
+
+  return { commandEntry, startAudit, importAudit, serveGate, commandSmoke };
+}
+
+function buildMarkdown(artifact) {
+  return `# PulseWasm Fastly Command Entrypoint\n\nStatus: **${artifact.status}**\n\n## Purpose\n\nFastly/Viceroy \`serve\` expects a command-style Compute guest with an exported \`_start\` function. The Fastly target generates that command entrypoint instead of reusing the generic library-style PulseWasm module.\n\n## Boundary\n\n- \`pack\` is package-shape validation.\n- \`serve\` is the runtime compatibility gate.\n- \`_start\` belongs to the Fastly adapter target, not the generic runtime.\n\n## Candidate commands\n\n\`\`\`bash\nfastly compute pack --wasm-binary artifacts/generated/fastly/pulsewasm-compute.wasm\nfastly compute serve\ncurl -i http://127.0.0.1:7676/\n\`\`\`\n\n## Summary\n\n\`\`\`json\n${JSON.stringify(artifact.summary, null, 2)}\n\`\`\`\n`;
+}
+
+function buildFastlyCommandEntry({ fastlyAdapter, fastlyHostcallBinding } = {}, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const outDir = options.outDir || getDefaultArtifactsDir(cwd);
+  const generatedBy = options.generatedBy || PACKAGE_VERSION;
+  const diagnostics = [];
+  const sourceText = buildFastlyCommandEntrySource();
+  const sourceFile = makeFile('generated/fastly/fastly-entry.as.ts', sourceText);
+  const compile = compileCommandEntry({ cwd, outDir, sourceText });
+  diagnostics.push(...compile.diagnostics);
+  const audit = wasmAudit(compile.wasmFile);
+  if (!audit.hasStart) diagnostics.push(diag('PULSEWASM_FASTLY_START_EXPORT_MISSING', 'Fastly command candidate does not export _start.', 'The Fastly target adapter must export _start for fastly compute serve.'));
+  if (audit.unexpectedImports.length > 0) diagnostics.push(diag('PULSEWASM_FASTLY_COMMAND_UNEXPECTED_IMPORT', 'Fastly command candidate has unexpected imports.', 'Only expected Fastly hostcall imports are allowed at this phase.', { unexpectedImports: audit.unexpectedImports }));
+  const artifacts = buildArtifacts({ generatedBy, compile, audit, cwd, sourceFile, wasmFile: compile.wasmFile });
+  const files = [
+    sourceFile,
+    makeFile('generated/fastly/fastly.toml', buildFastlyToml()),
+    makeFile('generated/fastly/README.md', buildReadme()),
+    makeFile('generated/host/fastly-command-entry.md', buildMarkdown(artifacts.commandEntry))
+  ];
+  const outputFiles = [];
+  if (compile.wasmFile && fs.existsSync(compile.wasmFile)) {
+    const fastlyDir = path.join(outDir, 'generated', 'fastly');
+    fs.mkdirSync(fastlyDir, { recursive: true });
+    const computeWasm = path.join(fastlyDir, 'pulsewasm-compute.wasm');
+    fs.copyFileSync(compile.wasmFile, computeWasm);
+    outputFiles.push(fileRecord(compile.wasmFile, cwd, 'fastly-command-wasm'));
+    outputFiles.push(fileRecord(computeWasm, cwd, 'fastly-compute-candidate-wasm'));
+  }
+  return {
+    artifact: artifacts.commandEntry,
+    startExportAudit: artifacts.startAudit,
+    importAudit: artifacts.importAudit,
+    serveGate: artifacts.serveGate,
+    commandSmoke: artifacts.commandSmoke,
+    files,
+    outputFiles,
+    diagnostics
+  };
+}
+
+module.exports = { buildFastlyCommandEntry };