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

package/src/javascript/grip-broadcast.js

@@ -0,0 +1,261 @@
+'use strict';
+
+const { fastlyJavascriptProviderError, isPulseRuntimeError } = require('./errors.js');
+
+const FASTLY_JAVASCRIPT_GRIP_BROADCAST_VERSION = 'pulse.fastly-javascript-grip-broadcast.v1';
+const DEFAULT_MAX_REQUEST_BYTES = 65536;
+const DEFAULT_MAX_RESPONSE_BYTES = 65536;
+
+function positiveSafeInteger(value, fallback, field) {
+  if (value === undefined) return fallback;
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number <= 0) {
+    throw new TypeError(`Pulse Fastly JavaScript GRIP ${field} must be a positive safe integer.`);
+  }
+  return number;
+}
+
+function normalizeEndpoint(input) {
+  let endpoint;
+  try { endpoint = new URL(String(input || '')); }
+  catch (error) {
+    throw fastlyJavascriptProviderError(
+      'PULSE_GRIP_BROADCAST_ENDPOINT_INVALID',
+      'Fastly JavaScript GRIP publish endpoint must be an absolute HTTP or HTTPS URL.',
+      { operation: 'broadcast', configuration: 'bindings.grip.publishEndpoint' },
+      error
+    );
+  }
+  if (!['http:', 'https:'].includes(endpoint.protocol)) {
+    throw fastlyJavascriptProviderError(
+      'PULSE_GRIP_BROADCAST_ENDPOINT_INVALID',
+      'Fastly JavaScript GRIP publish endpoint must use HTTP or HTTPS.',
+      { operation: 'broadcast', protocol: endpoint.protocol }
+    );
+  }
+  return endpoint;
+}
+
+function normalizeAuthentication(input) {
+  if (input === undefined) return undefined;
+  const scheme = input && String(input.scheme || 'bearer').toLowerCase();
+  const secretRef = input && typeof input.secretRef === 'string' ? input.secretRef.trim() : '';
+  if (scheme !== 'bearer') {
+    throw fastlyJavascriptProviderError(
+      'PULSE_GRIP_BROADCAST_AUTH_SCHEME_UNSUPPORTED',
+      'Fastly JavaScript GRIP supports bearer authentication only.',
+      { operation: 'broadcast', scheme }
+    );
+  }
+  if (!secretRef) {
+    throw fastlyJavascriptProviderError(
+      'PULSE_GRIP_BROADCAST_SECRET_REFERENCE_REQUIRED',
+      'Fastly JavaScript GRIP bearer authentication requires a secret reference.',
+      { operation: 'broadcast', configuration: 'bindings.grip.authentication.secretRef' }
+    );
+  }
+  return Object.freeze({ scheme, secretRef });
+}
+
+function requestBody(payload) {
+  const channel = payload && typeof payload.channel === 'string' ? payload.channel.trim() : '';
+  if (!channel || /[,\r\n]/.test(channel)) {
+    throw fastlyJavascriptProviderError(
+      'PULSE_GRIP_BROADCAST_CHANNEL_INVALID',
+      'GRIP broadcast channel must be non-empty and contain no commas or line breaks.',
+      { operation: 'broadcast' }
+    );
+  }
+  if (!payload || !Object.prototype.hasOwnProperty.call(payload, 'data') || payload.data === undefined) {
+    throw fastlyJavascriptProviderError(
+      'PULSE_GRIP_BROADCAST_MESSAGE_INVALID',
+      'GRIP broadcast requires a JSON-compatible data value.',
+      { operation: 'broadcast' }
+    );
+  }
+  try {
+    const body = JSON.stringify({
+      channel,
+      data: payload.data,
+      ...(payload.event === undefined ? {} : { event: String(payload.event) }),
+      ...(payload.id === undefined ? {} : { id: String(payload.id) })
+    });
+    if (typeof body !== 'string') throw new TypeError('not serializable');
+    return body;
+  } catch (error) {
+    throw fastlyJavascriptProviderError(
+      'PULSE_GRIP_BROADCAST_MESSAGE_INVALID',
+      'GRIP broadcast message must be JSON-compatible.',
+      { operation: 'broadcast' },
+      error
+    );
+  }
+}
+
+async function readBoundedResponseText(response, maxBytes) {
+  const length = Number(response.headers && response.headers.get && response.headers.get('content-length'));
+  if (Number.isFinite(length) && length > maxBytes) {
+    throw fastlyJavascriptProviderError(
+      'PULSE_GRIP_BROADCAST_RESPONSE_TOO_LARGE',
+      'GRIP broadcast provider response exceeded the configured byte limit.',
+      { operation: 'broadcast', maxResponseBytes: maxBytes }
+    );
+  }
+  if (!response.body) return '';
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let bytes = 0;
+  let text = '';
+  try {
+    for (;;) {
+      const part = await reader.read();
+      if (part.done) break;
+      bytes += part.value.byteLength;
+      if (bytes > maxBytes) {
+        try { await reader.cancel(); } catch (_) { /* Best-effort host stream cleanup. */ }
+        throw fastlyJavascriptProviderError(
+          'PULSE_GRIP_BROADCAST_RESPONSE_TOO_LARGE',
+          'GRIP broadcast provider response exceeded the configured byte limit.',
+          { operation: 'broadcast', maxResponseBytes: maxBytes }
+        );
+      }
+      text += decoder.decode(part.value, { stream: true });
+    }
+    return text + decoder.decode();
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function normalizeAck(status, text) {
+  if (!text.trim()) return Object.freeze({ accepted: true, status });
+  let parsed;
+  try { parsed = JSON.parse(text); }
+  catch (error) {
+    throw fastlyJavascriptProviderError(
+      'PULSE_GRIP_BROADCAST_RESPONSE_INVALID',
+      'GRIP broadcast provider returned an invalid acknowledgement.',
+      { operation: 'broadcast', status },
+      error
+    );
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw fastlyJavascriptProviderError(
+      'PULSE_GRIP_BROADCAST_RESPONSE_INVALID',
+      'GRIP broadcast provider acknowledgement must be an object.',
+      { operation: 'broadcast', status }
+    );
+  }
+  return Object.freeze({
+    accepted: parsed.accepted !== false,
+    status,
+    ...(parsed.messageId === undefined ? {} : { messageId: String(parsed.messageId) })
+  });
+}
+
+function createFastlyJavascriptGripBroadcast(options = {}) {
+  const grip = options.grip && typeof options.grip === 'object' ? options.grip : {};
+  const endpoint = normalizeEndpoint(grip.publishEndpoint || grip.publishUrl);
+  const authentication = normalizeAuthentication(grip.authentication);
+  const bindings = options.bindings && typeof options.bindings === 'object' ? options.bindings : {};
+  const backends = bindings.backends && typeof bindings.backends === 'object' ? bindings.backends : {};
+  const backend = typeof grip.publishBackend === 'string' && grip.publishBackend.trim()
+    ? grip.publishBackend.trim()
+    : (typeof backends[endpoint.origin] === 'string' ? backends[endpoint.origin].trim() : '');
+  if (!backend && bindings.dynamicBackends !== true) {
+    throw fastlyJavascriptProviderError(
+      'PULSE_GRIP_BROADCAST_BACKEND_REQUIRED',
+      'Fastly JavaScript GRIP requires a named publish backend unless dynamic backends are enabled.',
+      { operation: 'broadcast', origin: endpoint.origin, configuration: 'bindings.grip.publishBackend' }
+    );
+  }
+  if (typeof options.fetchImplementation !== 'function') {
+    throw fastlyJavascriptProviderError(
+      'PULSE_GRIP_BROADCAST_CAPABILITY_REQUIRED',
+      'Fastly JavaScript GRIP requires the provider fetch implementation.',
+      { operation: 'broadcast' }
+    );
+  }
+  const maxRequestBytes = positiveSafeInteger(grip.maxRequestBytes, DEFAULT_MAX_REQUEST_BYTES, 'maxRequestBytes');
+  const maxResponseBytes = positiveSafeInteger(grip.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES, 'maxResponseBytes');
+
+  return async function fastlyJavascriptGripBroadcast(payload, execution = {}) {
+    const body = requestBody(payload);
+    if (new TextEncoder().encode(body).byteLength > maxRequestBytes) {
+      throw fastlyJavascriptProviderError(
+        'PULSE_GRIP_BROADCAST_REQUEST_TOO_LARGE',
+        'GRIP broadcast request exceeded the configured byte limit.',
+        { operation: 'broadcast', maxRequestBytes }
+      );
+    }
+    const headers = new Headers({
+      accept: 'application/json',
+      'content-type': 'application/json; charset=utf-8'
+    });
+    if (authentication) {
+      const secret = typeof options.secretLookup === 'function'
+        ? await options.secretLookup(authentication.secretRef)
+        : undefined;
+      if (typeof secret !== 'string' || secret.length === 0) {
+        throw fastlyJavascriptProviderError(
+          'PULSE_GRIP_BROADCAST_SECRET_REQUIRED',
+          'GRIP broadcast authentication secret is unavailable.',
+          { operation: 'broadcast', secretRef: authentication.secretRef }
+        );
+      }
+      if (typeof execution.registerRedactionValue === 'function') execution.registerRedactionValue(secret);
+      headers.set('authorization', `Bearer ${secret}`);
+    }
+
+    let response;
+    let text;
+    try {
+      response = await options.fetchImplementation(endpoint.href, {
+        method: 'POST',
+        headers,
+        body,
+        signal: execution.signal,
+        redirect: 'error',
+        ...(backend ? { backend } : {})
+      });
+      if (!(response instanceof Response)) {
+        throw fastlyJavascriptProviderError(
+          'PULSE_GRIP_BROADCAST_RESPONSE_INVALID',
+          'GRIP broadcast provider must return a Web Response.',
+          { operation: 'broadcast' }
+        );
+      }
+      text = await readBoundedResponseText(response, maxResponseBytes);
+    } catch (error) {
+      if (isPulseRuntimeError(error)) throw error;
+      if (execution.signal && execution.signal.aborted) {
+        throw fastlyJavascriptProviderError(
+          'PULSE_GRIP_BROADCAST_ABORTED',
+          'GRIP broadcast was cancelled with its owning request.',
+          { operation: 'broadcast' }
+        );
+      }
+      throw fastlyJavascriptProviderError(
+        'PULSE_GRIP_BROADCAST_NETWORK',
+        'GRIP broadcast provider request failed.',
+        { operation: 'broadcast' },
+        error
+      );
+    }
+    if (response.status < 200 || response.status > 299) {
+      throw fastlyJavascriptProviderError(
+        'PULSE_GRIP_BROADCAST_REJECTED',
+        'GRIP broadcast provider rejected the publication.',
+        { operation: 'broadcast', status: response.status }
+      );
+    }
+    return normalizeAck(response.status, text);
+  };
+}
+
+module.exports = Object.freeze({
+  FASTLY_JAVASCRIPT_GRIP_BROADCAST_VERSION,
+  DEFAULT_MAX_REQUEST_BYTES,
+  DEFAULT_MAX_RESPONSE_BYTES,
+  createFastlyJavascriptGripBroadcast
+});

package/src/javascript/jwt-verifier.js

@@ -0,0 +1,147 @@
+'use strict';
+
+const {
+  normalizeJwtSignEffect,
+  normalizeJwtVerifyEffect
+} = require('@pulse-compute/wasm-contracts/jwt/contracts');
+const {
+  CRYPTO_ES256_RUNTIME_BUILTIN_IMPLEMENTATION,
+  CRYPTO_RS256_RUNTIME_BUILTIN_IMPLEMENTATION,
+  CRYPTO_RUNTIME_BUILTIN_IMPLEMENTATION
+} = require('@pulse-compute/wasm-contracts/crypto/contracts');
+
+const FASTLY_JAVASCRIPT_JWT_VERIFIER_VERSION = 'pulse.fastly-javascript-jwt-verifier.v2';
+const FASTLY_JAVASCRIPT_JWT_REALIZATIONS = Object.freeze({
+  HS256: Object.freeze({
+    algorithm: 'HS256',
+    realization: 'runtime-builtin',
+    implementation: CRYPTO_RUNTIME_BUILTIN_IMPLEMENTATION,
+    automaticFallback: false
+  }),
+  RS256: Object.freeze({ algorithm: 'RS256', realization: 'runtime-builtin', implementation: CRYPTO_RS256_RUNTIME_BUILTIN_IMPLEMENTATION, automaticFallback: false }),
+  ES256: Object.freeze({
+    algorithm: 'ES256',
+    realization: 'runtime-builtin',
+    implementation: CRYPTO_ES256_RUNTIME_BUILTIN_IMPLEMENTATION,
+    automaticFallback: false
+  })
+});
+const FASTLY_JAVASCRIPT_JWT_REALIZATION =
+  FASTLY_JAVASCRIPT_JWT_REALIZATIONS.HS256;
+
+let runtimeModules;
+
+function loadRuntimeModules() {
+  if (!runtimeModules) {
+    runtimeModules = Promise.all([
+      import('@pulse-compute/jwt/provider'),
+      import('@pulse-compute/crypto')
+    ]).then(([jwtProvider, cryptoProvider]) => Object.freeze({
+      jwtProvider,
+      cryptoProvider
+    }));
+  }
+  return runtimeModules;
+}
+
+function fastlyWallClock() {
+  return Object.freeze({
+    unixEpochSeconds: Date.now() / 1000,
+    trusted: true
+  });
+}
+
+function assertRequestActive(execution, jwtProvider) {
+  if (execution && execution.signal && execution.signal.aborted) {
+    throw jwtProvider.jwtError('PULSE_JWT_OPERATION_FAILED', {
+      category: 'request-cancelled',
+      automaticFallback: false
+    });
+  }
+}
+
+function assertRuntimeBuiltin(cryptoProvider, jwtProvider) {
+  if (
+    !cryptoProvider
+    || cryptoProvider.CRYPTO_RUNTIME_BUILTIN_IMPLEMENTATION !== CRYPTO_RUNTIME_BUILTIN_IMPLEMENTATION
+    || !cryptoProvider.crypto
+    || !cryptoProvider.crypto.mac
+    || typeof cryptoProvider.crypto.mac.verify !== 'function'
+    || !cryptoProvider.crypto.signature
+    || typeof cryptoProvider.crypto.signature.verify !== 'function'
+  ) {
+    throw jwtProvider.jwtError('PULSE_JWT_TARGET_UNSUPPORTED', {
+      category: 'crypto-realization',
+      realization: FASTLY_JAVASCRIPT_JWT_REALIZATION.realization,
+      implementation: FASTLY_JAVASCRIPT_JWT_REALIZATION.implementation,
+      automaticFallback: false
+    });
+  }
+  return cryptoProvider.crypto;
+}
+
+function createFastlyJavascriptJwtVerify(options = {}) {
+  const captureWallClock = options.captureWallClock || fastlyWallClock;
+  const secretLookup = options.secretLookup;
+  return async function verifyFastlyJavascriptJwt(effect, execution) {
+    const { jwtProvider, cryptoProvider } = await loadRuntimeModules();
+    assertRequestActive(execution, jwtProvider);
+    const signing = effect.operation === 'sign';
+    const input = signing ? normalizeJwtSignEffect(effect) : normalizeJwtVerifyEffect(effect);
+    if (!signing && execution && typeof execution.registerRedactionValue === 'function') {
+      execution.registerRedactionValue(input.token);
+    }
+    assertRequestActive(execution, jwtProvider);
+    const selectedCrypto = signing
+      ? (input.options.algorithm === 'RS256'
+        ? require('@pulse-compute/crypto/provider').bindJavascriptRs256Signer()
+        : input.options.algorithm === 'ES256'
+        ? require('@pulse-compute/crypto/provider').bindJavascriptEs256Signer()
+        : require('@pulse-compute/crypto/provider').bindJavascriptDigestMac(['HMAC-SHA256']))
+      : assertRuntimeBuiltin(cryptoProvider, jwtProvider);
+    const host = {
+      async captureWallClock() {
+        assertRequestActive(execution, jwtProvider);
+        const captured = await captureWallClock();
+        assertRequestActive(execution, jwtProvider);
+        return captured;
+      },
+      resolveSecret: typeof secretLookup === 'function'
+        ? async (binding) => {
+            assertRequestActive(execution, jwtProvider);
+            const secret = await secretLookup(binding, execution);
+            assertRequestActive(execution, jwtProvider);
+            return secret;
+          }
+        : undefined,
+      registerSensitiveValue(value) {
+        if (execution && typeof execution.registerRedactionValue === 'function') {
+          execution.registerRedactionValue(value);
+        }
+      }
+    };
+    if (execution && typeof execution.validateSchemaValue === 'function') {
+      host.validateClaims = async (schemaId, claims, context) => {
+        assertRequestActive(execution, jwtProvider);
+        const result = await execution.validateSchemaValue(schemaId, claims, context);
+        assertRequestActive(execution, jwtProvider);
+        return result;
+      };
+    }
+    const result = await (signing ? jwtProvider.signJwtWithCrypto : jwtProvider.verifyJwtWithCrypto)(
+      input,
+      Object.freeze(host),
+      selectedCrypto
+    );
+    assertRequestActive(execution, jwtProvider);
+    return result;
+  };
+}
+
+module.exports = Object.freeze({
+  FASTLY_JAVASCRIPT_JWT_VERIFIER_VERSION,
+  FASTLY_JAVASCRIPT_JWT_REALIZATION,
+  FASTLY_JAVASCRIPT_JWT_REALIZATIONS,
+  createFastlyJavascriptJwtVerify,
+  fastlyWallClock
+});

package/src/javascript/lifecycle.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const runtimeHost = require('@pulse-compute/runtime/host');
+const { executeFastlyJavascriptApplication } = require('./runtime-host.js');
+
+const FASTLY_JAVASCRIPT_LIFECYCLE_VERSION = 'pulse.fastly-javascript-lifecycle.v1';
+
+function requestForInput(input) {
+  if (input instanceof Request) return input;
+  if (input && input.request instanceof Request) return input.request;
+  throw new TypeError('Pulse Fastly JavaScript lifecycle requires a FetchEvent or Web Request.');
+}
+
+function safeFailureResponse() {
+  return new Response('Internal Server Error', {
+    status: 500,
+    headers: { 'content-type': 'text/plain; charset=utf-8' }
+  });
+}
+
+function createFastlyJavascriptHandler(application, options = {}) {
+  const normalizedApplication = runtimeHost.normalizeApplication(application);
+  return async function pulseFastlyJavascriptHandler(input) {
+    try {
+      const request = requestForInput(input);
+      return await executeFastlyJavascriptApplication(normalizedApplication, request, {
+        ...options,
+        signal: options.signal || request.signal
+      });
+    } catch (error) {
+      if (typeof options.onError === 'function') {
+        try { options.onError(error); } catch (_) { /* Lifecycle evidence is best effort. */ }
+      }
+      return safeFailureResponse();
+    }
+  };
+}
+
+function installFastlyJavascriptApplication(application, options = {}) {
+  const handler = createFastlyJavascriptHandler(application, options);
+  const addEventListener = options.addEventListener || globalThis.addEventListener;
+  if (typeof addEventListener !== 'function') {
+    throw new TypeError('Pulse Fastly JavaScript lifecycle requires addEventListener.');
+  }
+  addEventListener('fetch', (event) => event.respondWith(handler(event)));
+  return handler;
+}
+
+module.exports = Object.freeze({
+  FASTLY_JAVASCRIPT_LIFECYCLE_VERSION,
+  createFastlyJavascriptHandler,
+  installFastlyJavascriptApplication,
+  requestForInput,
+  safeFailureResponse
+});

package/src/javascript/local-loader.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const path = require('node:path');
+const vm = require('node:vm');
+const {
+  bundleFastlyJavascriptApplication
+} = require('./source-package.js');
+const {
+  assertFastlyJavascriptApplication
+} = require('./runtime-host.js');
+
+const FASTLY_JAVASCRIPT_LOCAL_LOADER_VERSION = 'pulse.fastly-javascript-local-loader.v1';
+const LOCAL_EXTERNALS = Object.freeze({
+  '@pulse-compute/runtime': require('@pulse-compute/runtime'),
+  '@pulse-compute/runtime/host': require('@pulse-compute/runtime/host'),
+  '@pulse-compute/runtime/package': require('@pulse-compute/runtime/package')
+});
+
+class PulseFastlyJavascriptLocalLoaderError extends Error {
+  constructor(code, message, detail = {}) {
+    super(message);
+    this.name = 'PulseFastlyJavascriptLocalLoaderError';
+    this.code = code;
+    this.detail = Object.freeze({ ...detail });
+  }
+}
+
+function moduleDefault(exports) {
+  return exports && Object.prototype.hasOwnProperty.call(exports, 'default')
+    ? exports.default
+    : exports;
+}
+
+function loadFastlyJavascriptLocalApplication(plan, options = {}) {
+  if (!plan || plan.provider !== 'fastly' || plan.target !== 'javascript' || plan.loadable !== true) {
+    throw new PulseFastlyJavascriptLocalLoaderError(
+      'PULSE_FASTLY_JAVASCRIPT_LOCAL_PLAN_UNAVAILABLE',
+      'Fastly JavaScript provider emulation requires a loadable Fastly JavaScript application plan.',
+      {
+        provider: plan && plan.provider,
+        target: plan && plan.target,
+        blockers: plan && plan.blockers || [],
+        automaticFallback: false
+      }
+    );
+  }
+
+  const projectRoot = path.resolve(options.projectRoot || options.workspaceRoot || '.');
+  const closure = bundleFastlyJavascriptApplication(
+    plan,
+    projectRoot,
+    options.schemaBundle,
+    { format: 'cjs', externalRuntime: true }
+  );
+  const module = { exports: {} };
+  const externalRequire = (request) => {
+    if (Object.prototype.hasOwnProperty.call(LOCAL_EXTERNALS, request)) {
+      return LOCAL_EXTERNALS[request];
+    }
+    throw new PulseFastlyJavascriptLocalLoaderError(
+      'PULSE_FASTLY_JAVASCRIPT_LOCAL_EXTERNAL_UNAVAILABLE',
+      `Bundled Fastly JavaScript provider emulation cannot load external module ${String(request)}.`,
+      { request: String(request), automaticFallback: false }
+    );
+  };
+
+  try {
+    const wrapper = new vm.Script(
+      `(function(module,exports,require,__filename,__dirname){\n${closure.source}\n})`,
+      { filename: 'pulse-fastly-javascript-local-application.cjs' }
+    ).runInThisContext();
+    wrapper(
+      module,
+      module.exports,
+      externalRequire,
+      path.join(projectRoot, 'pulse-fastly-javascript-local-application.cjs'),
+      projectRoot
+    );
+  } catch (error) {
+    if (error instanceof PulseFastlyJavascriptLocalLoaderError) throw error;
+    throw new PulseFastlyJavascriptLocalLoaderError(
+      error && error.code || 'PULSE_FASTLY_JAVASCRIPT_LOCAL_BUNDLE_LOAD_FAILED',
+      'The bundled Fastly JavaScript application could not be loaded for provider emulation.',
+      {
+        causeName: error && error.name,
+        causeCode: error && error.code,
+        planHash: plan.planHash,
+        graphHash: plan.graph && plan.graph.graphHash,
+        automaticFallback: false
+      }
+    );
+  }
+
+  let application;
+  try {
+    application = assertFastlyJavascriptApplication(moduleDefault(module.exports));
+  } catch (error) {
+    throw new PulseFastlyJavascriptLocalLoaderError(
+      error && error.code || 'PULSE_FASTLY_JAVASCRIPT_APPLICATION_EXPORT_INVALID',
+      error && error.message || 'The bundled Fastly JavaScript application export is invalid.',
+      {
+        planHash: plan.planHash,
+        graphHash: plan.graph && plan.graph.graphHash,
+        automaticFallback: false
+      }
+    );
+  }
+
+  return Object.freeze({
+    version: FASTLY_JAVASCRIPT_LOCAL_LOADER_VERSION,
+    mode: 'provider-emulation',
+    provider: 'fastly',
+    target: 'javascript',
+    providerReality: false,
+    realityRunner: 'fastly compute serve',
+    automaticFallback: false,
+    plan,
+    application,
+    schemaCodecs: module.exports && module.exports.schemaCodecs || null,
+    entry: plan.workspace.entry,
+    modulesLoaded: plan.graph.modules.length,
+    packagesLoaded: Object.freeze(plan.packages
+      .filter((entry) => entry.status !== 'unavailable')
+      .map((entry) => entry.packageName)
+      .sort()),
+    closure: Object.freeze({
+      format: closure.format,
+      sourceHash: closure.sourceHash,
+      inputs: closure.inputs
+    })
+  });
+}
+
+module.exports = Object.freeze({
+  FASTLY_JAVASCRIPT_LOCAL_LOADER_VERSION,
+  PulseFastlyJavascriptLocalLoaderError,
+  loadFastlyJavascriptLocalApplication
+});

package/src/javascript/logging.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const { normalizeFastlyLogEndpoint, MAX_LOG_BYTES } = require('../toolchain/logging.js');
+
+const FASTLY_JAVASCRIPT_LOGGING_VERSION = 'pulse.fastly-javascript-logging.v1';
+
+function createFastlyJavascriptLogEmitter(options = {}) {
+  const endpoint = normalizeFastlyLogEndpoint(options.logEndpoint);
+  const output = options.console || globalThis.console;
+  const methods = Object.freeze({
+    1: 'error',
+    2: 'warn',
+    3: 'info',
+    4: 'debug'
+  });
+  return function fastlyJavascriptLog(level, message, event) {
+    const method = methods[Number(level)] || 'log';
+    const record = `[pulse][${event && event.name || method}] ${String(message)}`;
+    if (endpoint !== undefined) {
+      if (new TextEncoder().encode(record).byteLength > MAX_LOG_BYTES) return;
+      try { new options.Logger(endpoint).log(record); } catch { /* Best effort, no fallback or retry. */ }
+      return;
+    }
+    if (!output) return;
+    const write = typeof output[method] === 'function'
+      ? output[method]
+      : (typeof output.log === 'function' ? output.log : undefined);
+    try { if (write) write.call(output, record); } catch { /* Logging does not change the HTTP outcome. */ }
+  };
+}
+
+module.exports = Object.freeze({
+  FASTLY_JAVASCRIPT_LOGGING_VERSION,
+  createFastlyJavascriptLogEmitter
+});