@pulse-compute/provider-node 0.0.0 → 1.0.0-beta.2

package/src/runtime/s3-reader.js

@@ -0,0 +1,131 @@
+'use strict';
+const https = require('node:https');
+const { Readable } = require('node:stream');
+const { performance } = require('node:perf_hooks');
+const protocol = require('@pulse-compute/s3/provider');
+
+function originRequest(request, signal) {
+  return new Promise((resolve, reject) => {
+    const req = https.request(request.url, { method: request.method, headers: request.headers, signal, maxHeaderSize: 16384 }, (response) => {
+      let headers = [];
+      try {
+        const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+        // Node exposes HTTP header octets as Latin-1 strings. Interpret the
+        // bounded protocol metadata as UTF-8, matching the Native host ABI.
+        for (let i = 0; i < response.rawHeaders.length; i += 2) headers.push([response.rawHeaders[i], decoder.decode(Buffer.from(response.rawHeaders[i + 1], 'latin1'))]);
+      } catch { headers = null; }
+      resolve({ status: response.statusCode, headers, body: response, close: () => response.destroy() });
+    });
+    req.once('error', reject);
+    req.end(request.body);
+  });
+}
+async function fetchFixture(fetch, request, signal) {
+  const pending = Promise.resolve().then(() => fetch(request.url, { method: request.method, headers: request.headers, ...(request.body === undefined ? {} : { body: request.body }), redirect: 'manual', cache: 'no-store', signal }));
+  pending.then((response) => { if (signal.aborted && response.body) void response.body.cancel().catch(() => {}); }, () => {});
+  const response = await abortable(pending, signal);
+  const body = response.body ? Readable.fromWeb(response.body, { signal }) : null;
+  // A deadline can fire before iteration begins; always observe the stream error.
+  if (body) body.on('error', () => {});
+  return { status: response.status, headers: [...response.headers], body, close: () => { if (body) body.destroy(); } };
+}
+function abortable(promise, signal) {
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener('abort', abort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    if (signal.aborted) abort();
+  });
+}
+async function readS3(effect, options, lookup) {
+  const operation = effect.operation, put = operation === 'putText';
+  const payload = effect.payload || {};
+  if (!['head', 'getText', 'putText'].includes(operation) || effect.kind !== `s3.${operation}` || effect.capability !== effect.kind
+    || effect.package !== '@pulse-compute/s3' || effect.contractId !== 'pulse.s3' || effect.providerKind !== 's3') throw new TypeError('Invalid S3 package effect authority.');
+  let dispatched = false, status;
+  const failure = (reason) => put ? protocol.putFailure(reason, dispatched, status) : protocol.failure(reason, status);
+  if (options.signal && options.signal.aborted) throw options.signal.reason || new Error('Request cancelled.');
+  const configured = typeof payload.binding === 'string' && options.s3 && Object.hasOwn(options.s3, payload.binding) && options.s3[payload.binding];
+  let binding;
+  try { binding = protocol.normalizeBinding(configured); } catch { return failure('configuration'); }
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(options.signal.reason);
+  if (options.signal) options.signal.addEventListener('abort', onAbort, { once: true });
+  let timedOut = false;
+  const deadline = performance.now() + binding.timeoutMs;
+  const check = () => {
+    if (performance.now() >= deadline) { timedOut = true; controller.abort(); }
+    if (controller.signal.aborted) throw controller.signal.reason || new Error('S3 deadline expired.');
+  };
+  const timer = setTimeout(() => { timedOut = true; controller.abort(); }, binding.timeoutMs);
+  const wait = async (value) => { const result = await abortable(Promise.resolve(value), controller.signal); check(); return result; };
+  let response;
+  try {
+    const key = protocol.encodeKey(payload.key);
+    if (key === null) return failure('invalid-key');
+    let body, contentType;
+    if (put) {
+      if (typeof payload.text !== 'string' || !payload.text.isWellFormed()) return failure('invalid-text');
+      body = protocol.bytes(payload.text);
+      if (body.length > binding.maxTextBytes) return failure('too-large');
+      try { contentType = protocol.normalizePutOptions({ contentType: payload.contentType }).contentType; }
+      catch { return failure('configuration'); }
+    }
+    let accessId, secret, token;
+    try {
+      accessId = await wait(lookup(binding.accessKeyIdSecret));
+      secret = await wait(lookup(binding.secretAccessKeySecret));
+      token = binding.sessionTokenSecret === undefined ? undefined : await wait(lookup(binding.sessionTokenSecret));
+    } catch (error) { check(); return failure('credentials'); }
+    if (!protocol.credentialsValid(accessId, secret, token)) return failure('credentials');
+    for (const value of [accessId, secret, token]) if (typeof options.registerRedactionValue === 'function' && typeof value === 'string') options.registerRedactionValue(value);
+    const crypto = options.cryptoVerifier && options.cryptoVerifier.bytes;
+    const algorithms = options.cryptoRealization && options.cryptoRealization.algorithms;
+    const realization = options.cryptoTarget === 'javascript' ? 'runtime-builtin' : 'guest-source:pulse-hmac-as';
+    if (!crypto || !Array.isArray(algorithms) || ['SHA-256', 'HMAC-SHA256'].some((algorithm) => !algorithms.some((entry) => entry.algorithm === algorithm && entry.available && entry.realization === realization))) return failure('configuration');
+    let request;
+    try {
+      request = await wait(protocol.signRequest({ binding, method: put ? 'PUT' : operation === 'head' ? 'HEAD' : 'GET', encodedKey: key, accessId, secret, token, now: Date.now(), body, contentType }, crypto));
+    } catch (error) { check(); return failure('configuration'); }
+    check();
+    // The send primitive may have side effects even if it throws synchronously.
+    dispatched = true;
+    response = options.fetchImplementation
+      ? await fetchFixture(options.fetchImplementation, request, controller.signal)
+      : await originRequest(request, controller.signal);
+    status = response.status;
+    check();
+    const rejected = put ? protocol.putStatusResult(status) : protocol.statusResult(status);
+    if (rejected && (!put || rejected.status === 'unknown')) return rejected;
+    const metadata = protocol.metadataFromHeaders(response.headers, operation === 'head');
+    if (!metadata) return failure('protocol');
+    if (operation === 'head') return protocol.normalizeResult(operation, { status: 'found', ...metadata });
+    const maximum = put ? rejected ? binding.maxTextBytes : 0 : binding.maxTextBytes;
+    if (metadata.byteLength > maximum) return failure(put ? 'protocol' : 'too-large');
+    const chunks = []; let total = 0;
+    if (response.body) for await (const chunk of response.body) {
+      check(); total += chunk.length;
+      if (total > maximum) return failure(put ? 'protocol' : 'too-large');
+      if (!put) chunks.push(Buffer.from(chunk));
+    }
+    check();
+    if (metadata.byteLength !== undefined && metadata.byteLength !== total) return failure('protocol');
+    if (put) return rejected || protocol.normalizeResult(operation, { status: 'stored', byteLength: body.length, sha256: request.headers['x-amz-content-sha256'], ...(metadata.etag === undefined ? {} : { etag: metadata.etag }) });
+    const raw = Buffer.concat(chunks, total);
+    const digest = protocol.hex(await wait(crypto.sha256(raw)));
+    let text;
+    try { text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(raw); }
+    catch { return failure('invalid-utf8'); }
+    check();
+    return protocol.normalizeResult(operation, { status: 'found', ...metadata, byteLength: total, text, sha256: digest });
+  } catch (error) {
+    if (options.signal && options.signal.aborted) throw options.signal.reason || error;
+    return failure(timedOut ? 'timeout' : status === undefined ? 'transport' : 'protocol');
+  } finally {
+    clearTimeout(timer);
+    if (options.signal) options.signal.removeEventListener('abort', onAbort);
+    controller.abort();
+    if (response) { try { await response.close(); } catch {} }
+  }
+}
+module.exports = { readS3, originRequest };

package/src/toolchain.js

@@ -0,0 +1,269 @@
+'use strict';
+
+const path = require('node:path');
+const {
+  PROVIDER_DRIVER_VERSION,
+  PROVIDER_TARGET_RESULT_VERSION,
+  PROVIDER_PACKAGING_AUDIT_VERSION,
+  defineProviderToolchain,
+  defineProviderDriver,
+  normalizeProviderTargetResult,
+  normalizeProviderJavascriptPackageResult
+} = require('@pulse-compute/wasm-contracts/provider/toolchain');
+const canonicalProvider = require('@pulse-compute/wasm-contracts/provider/canonical-provider');
+const nodeRuntime = require('./runtime/canonical-api-runtime.js');
+const { NODE_NATIVE_TARGET_DESCRIPTOR } = require('./native/target.js');
+const { NODE_JAVASCRIPT_TARGET_DESCRIPTOR } = require('./javascript/target.js');
+const { NODE_JAVASCRIPT_TARGET_SUPPORT_DECLARATION } = require('./javascript/support.js');
+const {
+  classifyNodeJavascriptCapability,
+  classifyNodeJavascriptProviderRequirement
+} = require('./javascript/target-support-policy.js');
+const nodeJavascriptHost = require('./javascript/runtime-host.js');
+const nodeJavascriptLifecycle = require('./javascript/lifecycle.js');
+const nodeJavascriptTestRuntime = require('./javascript/test-runtime.js');
+const { createNodeEventReferenceAdapter } = require('./events/reference-adapter.js');
+const { writeNodeJavascriptSourcePackage } = require('./javascript/source-package.js');
+const packageManifest = require('../package.json');
+
+const reportingTargetCapability = Object.freeze({
+  supported: true,
+  default: 'info',
+  levels: Object.freeze(['off', 'error', 'warn', 'info', 'debug'])
+});
+
+function genericProviderConfig(value) {
+  const input = value && typeof value === 'object' ? value : {};
+  const bindings = input.bindings || {};
+  if (Object.keys(bindings).some((key) => key !== 's3')) throw new TypeError('Unknown Node binding field.');
+  return Object.freeze({ kind: 'node', bindings: Object.freeze({ s3: require('./config/s3.js').normalizeNodeS3(bindings.s3) }), local: Object.freeze({}) });
+}
+
+function nodeRealization(nativeArtifact) {
+  return Object.freeze({
+    target: 'node-native-host',
+    provider: 'node',
+    providerNeutralWasm: true,
+    nativeWasm: true,
+    compiledWasmPresent: true,
+    sourceOnly: false,
+    sourceOnlySupported: false,
+    javascriptRuntime: false,
+    jsComputeRuntime: false,
+    wasm: nativeArtifact.manifest.wasm,
+    wat: nativeArtifact.manifest.wat,
+    importModules: nativeArtifact.manifest.importModules,
+    imports: nativeArtifact.manifest.imports,
+    exports: nativeArtifact.manifest.exports,
+    packageRealizationArtifacts: nativeArtifact.manifest.packageRealizationArtifacts,
+    compiler: Object.freeze({
+      package: nativeArtifact.manifest.assemblyScript.package,
+      version: nativeArtifact.manifest.assemblyScript.version,
+      targetCompilerVersion: nativeArtifact.compilerVersion
+    }),
+    optimization: nativeArtifact.manifest.optimization
+  });
+}
+
+function targetSupportContext(_compiled, _project, declaration) {
+  const gates = declaration.availability && declaration.availability.gates || [];
+  return Object.freeze({
+    bindingsRedaction: gates.some((entry) => entry.id === 'bindings-redaction' && entry.status === 'satisfied'),
+    gripRealized: gates.some((entry) => entry.id === 'grip-readiness' && entry.evidence && entry.evidence.status === 'passed')
+  });
+}
+
+async function executeNodeEventTestCase(invocation = {}) {
+  const target = String(invocation.target || '');
+  if (!['javascript', 'native'].includes(target)) {
+    throw new TypeError(`Node event test execution does not support target ${JSON.stringify(target)}.`);
+  }
+  const testCase = invocation.testCase || {};
+  const options = invocation.options || {};
+  const adapter = createNodeEventReferenceAdapter({
+    id: `pulse-test-${target}`,
+    maxQueueDepth: 1024
+  });
+  let executionEvidence = null;
+  const common = {
+    application: options.application,
+    config: testCase.config || {},
+    secrets: testCase.secrets || {},
+    kv: testCase.kv || {},
+    grip: testCase.grip || {},
+    fetches: testCase.fetches || {},
+    eventAdapter: adapter,
+    schemaCodecs: options.schemaCodecs,
+    reporting: options.reporting,
+    maxEffects: options.maxEffects,
+    maxBindingNameBytes: options.maxBindingNameBytes,
+    maxBindingValueBytes: options.maxBindingValueBytes,
+    maxKvNamespaceBytes: options.maxKvNamespaceBytes,
+    maxKvKeyBytes: options.maxKvKeyBytes,
+    maxKvValueBytes: options.maxKvValueBytes,
+    maxKvValueDepth: options.maxKvValueDepth,
+    maxKvValueEntries: options.maxKvValueEntries
+  };
+  const result = target === 'javascript'
+    ? await nodeJavascriptHost.executeNodeJavascriptEvent(invocation.application, testCase.event, {
+        ...common,
+        fetchImplementation: nodeJavascriptHost.createNodeJavascriptFixtureFetch(
+          testCase.fetches || {},
+          options.networkFetch === true ? globalThis.fetch : undefined
+        ),
+        onEffectSummary(value) { executionEvidence = value; }
+      })
+    : await nodeRuntime.executeNodeNativeEvent(invocation.application, testCase.event, {
+        ...common,
+        onEventExecutionEvidence(value) { executionEvidence = value; }
+      });
+  return Object.freeze({
+    version: 'pulse.provider-event-test-result.v1',
+    target,
+    result,
+    emittedFrames: adapter.acceptedFrames(),
+    adapter: adapter.summary(),
+    executionEvidence
+  });
+}
+
+function createDriver() {
+  return defineProviderDriver({
+    version: PROVIDER_DRIVER_VERSION,
+    id: 'node',
+    descriptor: nodeRuntime.NODE_PROVIDER_DESCRIPTOR,
+    executable: true,
+    localExecution: true,
+    deployable: true,
+    deploymentValidated: false,
+    sourcePackage: false,
+    compiledWasm: true,
+    defaultBuildMode: 'native-provider',
+    sourceOnlySupported: false,
+    targetSupport: Object.freeze({ javascript: NODE_JAVASCRIPT_TARGET_SUPPORT_DECLARATION }),
+    normalizeConfig: genericProviderConfig,
+    configReference: Object.freeze({
+      sections: [{ id: 'node', title: 'Node provider options', description: 'Provider-owned Node profile configuration.' }],
+      fields: [{ section: 'node', path: 'node.bindings.s3', type: 'Readonly<Record<string, S3Binding>>', default: '`{}`', scope: 'Node Native and JavaScript S3',
+        description: 'Maps literal logical names to fixed HTTPS endpoint, bucket, region, accessKeyIdSecret, secretAccessKeySecret, optional sessionTokenSecret, maxTextBytes (1–32768, default 32768) and timeoutMs (1–30000, default 10000).',
+        security: 'Only named credential references are configuration. Runtime keys cannot override authority.' }]
+    }),
+    defaultLocalNetworkFetch: true,
+    projectConfigDocument(config) { return Object.keys(config.bindings.s3).length ? config : undefined; },
+    initTemplate() {
+      return Object.freeze({ profileFragment: '', dependencies: Object.freeze({}) });
+    },
+    executionOptions(config, values) {
+      return Object.freeze({
+        ...values,
+        s3: config.bindings.s3,
+        providerAdapter: nodeRuntime.createNodeProviderAdapter()
+      });
+    },
+    javascript: Object.freeze({
+      kind: 'reference-node',
+      localEmulation: false,
+      buildTimeLoader: false,
+      validateApplication: nodeJavascriptHost.assertNodeJavascriptApplication,
+      targetSupportPolicy: Object.freeze({
+          providerId: 'node',
+          declaration: NODE_JAVASCRIPT_TARGET_SUPPORT_DECLARATION,
+          context: targetSupportContext,
+          classifyCapability: classifyNodeJavascriptCapability,
+          classifyProviderRequirement: classifyNodeJavascriptProviderRequirement
+      }),
+      writeSourcePackage(invocation) {
+        return normalizeProviderJavascriptPackageResult(writeNodeJavascriptSourcePackage({
+          plan: invocation.applicationPlan,
+          projectRoot: invocation.project.root,
+          outDir: invocation.project.outDir,
+          schemaBundle: invocation.javascript.schemaBundle
+        }), { provider: 'node' });
+      },
+      describeSourcePackage(sourcePackage) {
+        return Object.freeze({
+          deploymentCandidate: false,
+          downstreamJavascriptRuntimeWasm: false,
+          application: Object.freeze({
+            entry: path.basename(sourcePackage.paths.entry),
+            modules: sourcePackage.manifest.summary.modules
+          }),
+          files: Object.freeze({})
+        });
+      },
+      executeTestCase(application, testCase, options) {
+        return nodeJavascriptTestRuntime.executeNodeJavascriptTestCase(application, testCase, options);
+      },
+      createServer: nodeJavascriptLifecycle.createNodeJavascriptServer,
+      createFixtureFetch: nodeJavascriptHost.createNodeJavascriptFixtureFetch
+    }),
+    events: Object.freeze({
+      targets: Object.freeze(['javascript', 'native']),
+      executeTestCase: executeNodeEventTestCase
+    }),
+    targets: Object.freeze({
+      native: Object.freeze({
+        ...NODE_NATIVE_TARGET_DESCRIPTOR,
+        target: 'native',
+        targetId: 'node-native-host',
+        runtimeClass: 'native',
+        status: 'supported',
+        automaticFallback: false,
+        reporting: reportingTargetCapability,
+        commands: Object.freeze({ compile: true, inspect: true, doctor: true, build: true, test: true, dev: true })
+      }),
+      javascript: NODE_JAVASCRIPT_TARGET_DESCRIPTOR
+    }),
+    execute: nodeRuntime.executeCanonicalProgram,
+    createLoweringPlan(metadata, config = {}) {
+      require('./config/s3.js').validateNodeS3Operations(metadata, config.bindings || {});
+      return canonicalProvider.createProviderLoweringPlan(metadata, nodeRuntime.NODE_PROVIDER_DESCRIPTOR, {
+        grip: 'node-reference-broadcaster'
+      });
+    },
+    inspectRealization(invocation) {
+      const realization = nodeRealization(invocation.nativeArtifact);
+      return normalizeProviderTargetResult({
+        version: PROVIDER_TARGET_RESULT_VERSION,
+        action: 'inspect-native',
+        provider: 'node',
+        target: 'native',
+        status: 'inspected',
+        automaticFallback: false,
+        files: Object.freeze({}),
+        build: null,
+        realization,
+        packaging: null
+      });
+    },
+    writeTarget(invocation) {
+      const realization = nodeRealization(invocation.nativeArtifact);
+      const audit = invocation.nativeArtifact.guestAudit;
+      return normalizeProviderTargetResult({
+        version: PROVIDER_TARGET_RESULT_VERSION,
+        action: 'write-native',
+        provider: 'node',
+        target: 'native',
+        status: 'built',
+        automaticFallback: false,
+        files: Object.freeze({}),
+        build: realization,
+        realization,
+        packaging: audit ? Object.freeze({
+          version: PROVIDER_PACKAGING_AUDIT_VERSION,
+          artifactSha256: invocation.nativeArtifact.finalArtifact.sha256,
+          auditedSha256: audit.finalArtifact.sha256,
+          authorized: audit.providerPackaging.authorized === true
+        }) : null
+      });
+    }
+  });
+}
+
+module.exports = defineProviderToolchain({
+  version: 'pulse.provider-toolchain.v1',
+  id: 'node',
+  packageName: packageManifest.name,
+  packageVersion: packageManifest.version,
+  createDriver
+});