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

package/src/javascript/assets-adapter.js

@@ -0,0 +1,122 @@
+'use strict';
+
+const runtimeHost = require('@pulse-compute/runtime/host');
+const { fastlyJavascriptProviderError, isPulseRuntimeError } = require('./errors.js');
+
+const FASTLY_JAVASCRIPT_ASSETS_ADAPTER_VERSION = 'pulse.fastly-javascript-assets-adapter.v1';
+
+function contentTypeForKey(key) {
+  const extension = String(key).toLowerCase().split('.').pop();
+  return Object.freeze({
+    css: 'text/css; charset=utf-8',
+    html: 'text/html; charset=utf-8',
+    js: 'text/javascript; charset=utf-8',
+    json: 'application/json; charset=utf-8',
+    mjs: 'text/javascript; charset=utf-8',
+    svg: 'image/svg+xml',
+    txt: 'text/plain; charset=utf-8',
+    webp: 'image/webp',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    ico: 'image/x-icon'
+  })[extension] || 'application/octet-stream';
+}
+
+function responseHeaders(payload) {
+  const headers = new Headers(payload && payload.headers);
+  if (!headers.has('content-type')) headers.set('content-type', contentTypeForKey(payload && payload.key));
+  if (payload && payload.cacheControl !== undefined) headers.set('cache-control', String(payload.cacheControl));
+  return headers;
+}
+
+function createFastlyJavascriptAssetsLookup(options = {}) {
+  const apis = options.apis || {};
+  const bindings = options.bindings && typeof options.bindings === 'object' ? options.bindings : {};
+  const kvBindings = bindings.kv && typeof bindings.kv === 'object' ? bindings.kv : {};
+  const stores = new Map();
+
+  function storeFor(logicalStore) {
+    const store = typeof logicalStore === 'string' ? logicalStore.trim() : '';
+    const resource = store && typeof kvBindings[store] === 'string' ? kvBindings[store].trim() : '';
+    if (!store || !resource) {
+      throw fastlyJavascriptProviderError(
+        'PULSE_FASTLY_ASSETS_BINDING_REQUIRED',
+        'Fastly JavaScript Assets requires a logical store-to-KV mapping.',
+        { store, configuration: store ? `bindings.kv.${store}` : 'bindings.kv' }
+      );
+    }
+    if (!stores.has(resource)) {
+      if (typeof apis.KVStore !== 'function') {
+        throw fastlyJavascriptProviderError(
+          'PULSE_FASTLY_JAVASCRIPT_API_UNAVAILABLE',
+          'Fastly JavaScript Assets requires the KVStore API.',
+          { api: 'KVStore' }
+        );
+      }
+      try { stores.set(resource, new apis.KVStore(resource)); }
+      catch (error) {
+        throw fastlyJavascriptProviderError(
+          'PULSE_FASTLY_ASSETS_STORE_OPEN_FAILED',
+          'Fastly JavaScript could not open the configured Assets KV Store.',
+          { store, resource },
+          error
+        );
+      }
+    }
+    return Object.freeze({ store, resource, value: stores.get(resource) });
+  }
+
+  return async function fastlyJavascriptAssetsLookup(payload = {}) {
+    const opened = storeFor(payload.store);
+    const key = typeof payload.key === 'string' ? payload.key : '';
+    if (!key) {
+      throw fastlyJavascriptProviderError(
+        'PULSE_FASTLY_ASSETS_KEY_INVALID',
+        'Fastly JavaScript Assets requires a non-empty asset key.',
+        { store: opened.store }
+      );
+    }
+    let entry;
+    try { entry = await opened.value.get(key); }
+    catch (error) {
+      if (isPulseRuntimeError(error)) throw error;
+      throw fastlyJavascriptProviderError(
+        'PULSE_FASTLY_ASSETS_LOOKUP_FAILED',
+        'Fastly JavaScript Assets lookup failed.',
+        { store: opened.store, key },
+        error
+      );
+    }
+    if (entry === null || entry === undefined) {
+      return runtimeHost.markOpaqueResponse(new Response(null, {
+        status: 404,
+        headers: { 'content-type': 'text/plain; charset=utf-8' }
+      }));
+    }
+    if (!entry || !('body' in Object(entry))) {
+      throw fastlyJavascriptProviderError(
+        'PULSE_FASTLY_ASSETS_ENTRY_INVALID',
+        'Fastly JavaScript Assets received an invalid KV entry.',
+        { store: opened.store, key }
+      );
+    }
+    const body = entry.body;
+    const method = String(payload.method || 'GET').toUpperCase();
+    const headers = responseHeaders(payload);
+    if (method === 'HEAD') {
+      if (body && typeof body.cancel === 'function') {
+        try { await body.cancel(); } catch (_) { /* Best-effort host stream cleanup. */ }
+      }
+      return runtimeHost.markOpaqueResponse(new Response(null, { status: 200, headers }));
+    }
+    return runtimeHost.markOpaqueResponse(new Response(body, { status: 200, headers }));
+  };
+}
+
+module.exports = Object.freeze({
+  FASTLY_JAVASCRIPT_ASSETS_ADAPTER_VERSION,
+  contentTypeForKey,
+  createFastlyJavascriptAssetsLookup
+});

package/src/javascript/bindings-adapter.js

@@ -0,0 +1,237 @@
+'use strict';
+
+const runtimeHost = require('@pulse-compute/runtime/host');
+const { fastlyJavascriptProviderError, isPulseRuntimeError } = require('./errors.js');
+
+const FASTLY_JAVASCRIPT_BINDINGS_ADAPTER_VERSION = 'pulse.fastly-javascript-bindings-adapter.v1';
+
+function requireConstructor(apis, name) {
+  const value = apis && apis[name];
+  if (typeof value !== 'function') {
+    throw fastlyJavascriptProviderError(
+      'PULSE_FASTLY_JAVASCRIPT_API_UNAVAILABLE',
+      `Fastly JavaScript ${name} capability is unavailable.`,
+      { api: name }
+    );
+  }
+  return value;
+}
+
+function requireResourceName(value, field) {
+  const normalized = typeof value === 'string' ? value.trim() : '';
+  if (!normalized) {
+    throw fastlyJavascriptProviderError(
+      'PULSE_FASTLY_JAVASCRIPT_BINDING_REQUIRED',
+      `Fastly JavaScript ${field} must name a configured resource.`,
+      { configuration: field }
+    );
+  }
+  return normalized;
+}
+
+function providerFailure(error, code, message, detail) {
+  if (isPulseRuntimeError(error)) throw error;
+  throw fastlyJavascriptProviderError(code, message, detail, error);
+}
+
+function createFastlyJavascriptBindingCapabilities(options = {}) {
+  const apis = options.apis || {};
+  const bindings = options.bindings && typeof options.bindings === 'object' ? options.bindings : {};
+  const kvBindings = bindings.kv && typeof bindings.kv === 'object' ? bindings.kv : {};
+  const limits = {
+    maxBindingNameBytes: options.maxBindingNameBytes,
+    maxBindingValueBytes: options.maxBindingValueBytes,
+    maxKvNamespaceBytes: options.maxKvNamespaceBytes,
+    maxKvKeyBytes: options.maxKvKeyBytes,
+    maxKvValueBytes: options.maxKvValueBytes,
+    maxKvValueDepth: options.maxKvValueDepth,
+    maxKvValueEntries: options.maxKvValueEntries
+  };
+  let configStore;
+  let secretStore;
+  const kvStores = new Map();
+
+  function openConfigStore() {
+    if (!configStore) {
+      const ConfigStore = requireConstructor(apis, 'ConfigStore');
+      const resource = requireResourceName(bindings.configStore, 'bindings.configStore');
+      try { configStore = new ConfigStore(resource); }
+      catch (error) {
+        providerFailure(
+          error,
+          'PULSE_FASTLY_CONFIG_STORE_OPEN_FAILED',
+          'Fastly JavaScript could not open the configured Config Store.',
+          { configuration: 'bindings.configStore', resource }
+        );
+      }
+    }
+    return configStore;
+  }
+
+  function openSecretStore() {
+    if (!secretStore) {
+      const SecretStore = requireConstructor(apis, 'SecretStore');
+      const resource = requireResourceName(bindings.secretStore, 'bindings.secretStore');
+      try { secretStore = new SecretStore(resource); }
+      catch (error) {
+        providerFailure(
+          error,
+          'PULSE_FASTLY_SECRET_STORE_OPEN_FAILED',
+          'Fastly JavaScript could not open the configured Secret Store.',
+          { configuration: 'bindings.secretStore', resource }
+        );
+      }
+    }
+    return secretStore;
+  }
+
+  function physicalKvStore(namespaceInput) {
+    const namespace = runtimeHost.normalizeKvNamespace(namespaceInput, limits);
+    const resource = typeof kvBindings[namespace] === 'string' ? kvBindings[namespace].trim() : '';
+    if (!resource) {
+      throw fastlyJavascriptProviderError(
+        'PULSE_FASTLY_KV_BINDING_REQUIRED',
+        'Fastly JavaScript KV requires a logical namespace mapping.',
+        { namespace, configuration: `bindings.kv.${namespace}` }
+      );
+    }
+    if (!kvStores.has(resource)) {
+      const KVStore = requireConstructor(apis, 'KVStore');
+      try { kvStores.set(resource, new KVStore(resource)); }
+      catch (error) {
+        providerFailure(
+          error,
+          'PULSE_FASTLY_KV_STORE_OPEN_FAILED',
+          'Fastly JavaScript could not open a configured KV Store.',
+          { namespace, resource }
+        );
+      }
+    }
+    return Object.freeze({ namespace, resource, store: kvStores.get(resource) });
+  }
+
+  return Object.freeze({
+    version: FASTLY_JAVASCRIPT_BINDINGS_ADAPTER_VERSION,
+    config(nameInput) {
+      const name = runtimeHost.normalizeBindingName('config', nameInput, limits);
+      try {
+        const value = openConfigStore().get(name);
+        return value === null ? undefined : value;
+      } catch (error) {
+        providerFailure(
+          error,
+          'PULSE_FASTLY_CONFIG_GET_FAILED',
+          'Fastly JavaScript Config Store lookup failed.',
+          { name }
+        );
+      }
+    },
+    async secret(nameInput) {
+      const name = runtimeHost.normalizeBindingName('secret', nameInput, limits);
+      let entry;
+      try { entry = await openSecretStore().get(name); }
+      catch (error) {
+        providerFailure(
+          error,
+          'PULSE_FASTLY_SECRET_GET_FAILED',
+          'Fastly JavaScript Secret Store lookup failed.',
+          { name }
+        );
+      }
+      if (entry === null || entry === undefined) return undefined;
+      try {
+        if (!entry || typeof entry.plaintext !== 'function') {
+          throw fastlyJavascriptProviderError(
+            'PULSE_FASTLY_SECRET_ENTRY_INVALID',
+            'Fastly JavaScript Secret Store returned an invalid entry.',
+            { name }
+          );
+        }
+        return entry.plaintext();
+      } catch (error) {
+        providerFailure(
+          error,
+          'PULSE_FASTLY_SECRET_PLAINTEXT_FAILED',
+          'Fastly JavaScript could not read a Secret Store entry.',
+          { name }
+        );
+      }
+    },
+    kv(namespaceInput) {
+      const opened = physicalKvStore(namespaceInput);
+      return Object.freeze({
+        async get(keyInput) {
+          const key = runtimeHost.normalizeKvKey(keyInput, limits);
+          let entry;
+          try { entry = await opened.store.get(key); }
+          catch (error) {
+            providerFailure(
+              error,
+              'PULSE_FASTLY_KV_GET_FAILED',
+              'Fastly JavaScript KV lookup failed.',
+              { namespace: opened.namespace, key }
+            );
+          }
+          if (entry === null || entry === undefined) return undefined;
+          try {
+            if (!entry || typeof entry.json !== 'function') {
+              throw fastlyJavascriptProviderError(
+                'PULSE_FASTLY_KV_ENTRY_INVALID',
+                'Fastly JavaScript KV returned an invalid entry.',
+                { namespace: opened.namespace, key }
+              );
+            }
+            return await entry.json();
+          } catch (error) {
+            providerFailure(
+              error,
+              'PULSE_FASTLY_KV_VALUE_INVALID',
+              'Fastly JavaScript KV value is not valid Pulse JSON data.',
+              { namespace: opened.namespace, key }
+            );
+          }
+        },
+        async put(keyInput, value) {
+          const key = runtimeHost.normalizeKvKey(keyInput, limits);
+          let body;
+          try { body = JSON.stringify(value); }
+          catch (error) {
+            providerFailure(
+              error,
+              'PULSE_FASTLY_KV_VALUE_INVALID',
+              'Fastly JavaScript KV value is not valid Pulse JSON data.',
+              { namespace: opened.namespace, key }
+            );
+          }
+          try { await opened.store.put(key, body); }
+          catch (error) {
+            providerFailure(
+              error,
+              'PULSE_FASTLY_KV_PUT_FAILED',
+              'Fastly JavaScript KV write failed.',
+              { namespace: opened.namespace, key }
+            );
+          }
+          return true;
+        }
+      });
+    }
+  });
+}
+
+function withFastlyBindingCapabilities(capabilities, options = {}) {
+  const base = capabilities && typeof capabilities === 'object' ? capabilities : {};
+  const configured = options.bindingCapabilities || createFastlyJavascriptBindingCapabilities(options);
+  return Object.freeze({
+    ...base,
+    ...(typeof base.config === 'function' ? {} : { config: configured.config }),
+    ...(typeof base.secret === 'function' ? {} : { secret: configured.secret }),
+    ...(typeof base.kv === 'function' ? {} : { kv: configured.kv })
+  });
+}
+
+module.exports = Object.freeze({
+  FASTLY_JAVASCRIPT_BINDINGS_ADAPTER_VERSION,
+  createFastlyJavascriptBindingCapabilities,
+  withFastlyBindingCapabilities
+});

package/src/javascript/errors.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const runtimeHost = require('@pulse-compute/runtime/host');
+
+const FASTLY_JAVASCRIPT_PROVIDER_ERROR_VERSION = 'pulse.fastly-javascript-provider-error.v1';
+
+function fastlyJavascriptProviderError(code, message, detail = {}, cause) {
+  const safeDetail = {
+    ...detail,
+    ...(cause && typeof cause.name === 'string' ? { causeName: cause.name } : {})
+  };
+  return new runtimeHost.PulseRuntimeContractError(code, message, {
+    detail: Object.freeze(safeDetail)
+  });
+}
+
+function isPulseRuntimeError(error) {
+  return error instanceof runtimeHost.PulseRuntimeContractError
+    || Boolean(error && typeof error.code === 'string' && error.code.startsWith('PULSE_'));
+}
+
+module.exports = Object.freeze({
+  FASTLY_JAVASCRIPT_PROVIDER_ERROR_VERSION,
+  fastlyJavascriptProviderError,
+  isPulseRuntimeError
+});

package/src/javascript/fetch-adapter.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const runtimeHost = require('@pulse-compute/runtime/host');
+const { fastlyJavascriptProviderError, isPulseRuntimeError } = require('./errors.js');
+
+const FASTLY_JAVASCRIPT_FETCH_ADAPTER_VERSION = 'pulse.fastly-javascript-fetch-adapter.v1';
+
+function normalizeOrigin(url) {
+  try {
+    const parsed = new URL(String(url));
+    if (!['http:', 'https:'].includes(parsed.protocol)) throw new TypeError('unsupported protocol');
+    return parsed.origin;
+  } catch (error) {
+    throw fastlyJavascriptProviderError(
+      'PULSE_FASTLY_FETCH_URL_INVALID',
+      'Fastly JavaScript fetch requires an absolute HTTP or HTTPS URL.',
+      { url: String(url) },
+      error
+    );
+  }
+}
+
+function createFastlyJavascriptFetchCapability(options = {}) {
+  const implementation = options.fetchImplementation;
+  const bindings = options.bindings && typeof options.bindings === 'object' ? options.bindings : {};
+  const backends = bindings.backends && typeof bindings.backends === 'object' ? bindings.backends : {};
+  const dynamicBackends = bindings.dynamicBackends === true;
+
+  return async function fastlyJavascriptFetch(url, init = {}, execution = {}) {
+    if (typeof implementation !== 'function') {
+      throw fastlyJavascriptProviderError(
+        'PULSE_FASTLY_FETCH_IMPLEMENTATION_UNAVAILABLE',
+        'Fastly JavaScript fetch is unavailable.',
+        { capability: 'fetch' }
+      );
+    }
+    const origin = normalizeOrigin(url);
+    const configuredBackend = typeof backends[origin] === 'string' ? backends[origin].trim() : '';
+    if (!configuredBackend && !dynamicBackends) {
+      throw fastlyJavascriptProviderError(
+        'PULSE_FASTLY_FETCH_BACKEND_REQUIRED',
+        'Fastly JavaScript fetch requires an origin-to-backend mapping unless dynamic backends are enabled.',
+        { origin, configuration: `bindings.backends.${origin}`, dynamicBackends: false }
+      );
+    }
+
+    const requestInit = {
+      method: init.method,
+      headers: init.headers,
+      body: init.body,
+      signal: execution.signal || init.signal,
+      redirect: 'follow',
+      ...(configuredBackend ? { backend: configuredBackend } : {})
+    };
+    try {
+      const response = await implementation(String(url), requestInit);
+      if (!(response instanceof Response) && !runtimeHost.isPulseFetchResponse(response)) {
+        throw fastlyJavascriptProviderError(
+          'PULSE_FASTLY_FETCH_RESPONSE_INVALID',
+          'Fastly JavaScript fetch must resolve to a Web Response.',
+          { origin, type: typeof response }
+        );
+      }
+      return response;
+    } catch (error) {
+      if (isPulseRuntimeError(error)) throw error;
+      if (requestInit.signal && requestInit.signal.aborted) {
+        const reason = requestInit.signal.reason;
+        if (reason instanceof Error) throw reason;
+      }
+      throw fastlyJavascriptProviderError(
+        'PULSE_FASTLY_FETCH_NETWORK',
+        'Fastly JavaScript fetch failed.',
+        { origin, method: String(init.method || 'GET').toUpperCase() },
+        error
+      );
+    }
+  };
+}
+
+function withFastlyFetchCapability(capabilities, options = {}) {
+  const base = capabilities && typeof capabilities === 'object' ? capabilities : {};
+  return Object.freeze({
+    ...base,
+    ...(typeof base.fetch === 'function' ? {} : { fetch: createFastlyJavascriptFetchCapability(options) })
+  });
+}
+
+module.exports = Object.freeze({
+  FASTLY_JAVASCRIPT_FETCH_ADAPTER_VERSION,
+  createFastlyJavascriptFetchCapability,
+  withFastlyFetchCapability
+});