@pulse-compute/provider-fastly#

@pulse-compute/provider-fastly supplies typed Fastly project configuration, canonical capability lowering, direct JavaScript execution, local conformance runtimes, Native and JavaScript Compute target generation, and an explicit Fastly CLI boundary.

Install it only in projects that select the Fastly provider.

Install#

npm install @pulse-compute/provider-fastly@1.0.0-beta.1

Configure a project#

import { defineConfig } from '@pulse-compute/pulse'

export default defineConfig((scope) => ({
  pulse: {
    entry: 'src/index.ts',
    tests: 'tests/pulse.harness.ts',
    defaultProfile: 'local',
    strict: true,
  },
  local: {
    host: 'fastly',
    target: 'native',
    outDir: 'dist',
    apiBase: scope.config('API_BASE'),
    apiToken: scope.secret('API_TOKEN'),
    dev: {
      config: { API_BASE: 'https://api.example.com' },
      secrets: {
        API_TOKEN: 'local-example-secret',
        GRIP_TOKEN: 'local-grip-secret',
      },
      kv: {
        sessions: { 'session:123': { userId: 123 } },
      },
      fetches: {
        'https://api.example.com/users/7': {
          value: { id: 7, name: 'Ada' },
        },
        'POST https://publisher.example.com/publish': {
          status: 202,
          value: { accepted: true, messageId: 'message-1' },
        },
      },
    },
    fastly: {
      bindings: {
        configStore: 'app_config',
        secretStore: 'app_secrets',
        kv: { sessions: 'app_sessions' },
        backends: {
          'https://api.example.com': 'api_backend',
          'https://publisher.example.com': 'publisher_backend',
        },
        dynamicBackends: false,
        grip: {
          publishEndpoint: 'https://publisher.example.com/publish',
          publishBackend: 'publisher_backend',
          authentication: {
            scheme: 'bearer',
            secretRef: 'GRIP_TOKEN',
          },
        },
      },
      build: { name: 'pulse-fastly-capabilities-example' },
    },
  },
}))

The provider maps logical origins and stores used by canonical handler calls to Fastly deployment resources. Local values and fixtures do not create or populate deployed resources.

Configuration groups#

The root fastly() helper supports:

• Config Store and Secret Store names;
• logical KV namespace to Fastly KV Store mappings;
• origin to backend-name mappings;
• explicit dynamic-backend policy;
• GRIP/Fanout hold and publish bindings;
• package name, description, and authors;
• local network-fetch policy.

See Project configuration for field-level defaults, precedence, and constraints.

Build outputs#

The active .pulse/config.ts profile selects one target explicitly:

pulse build ./my-app

Fastly Native#

target: 'native' compiles the provider-neutral plan and emits generated src/main.as.ts plus compact bin/main.wasm importing the required fastly_* hostcalls directly. It contains no JavaScript runtime image, pulse_host, or WASI dependency.

Fastly JavaScript#

target: 'javascript' emits a deterministic, self-contained source closure:

src/index.js
src/application.js
fastly.toml
package.json
pulse-esbuild.config.js
pulse-fastly-javascript-candidate.json
pulse-fastly-javascript-deployment.json
pulse-fastly-javascript-source-package.json

The closure pins esbuild and @fastly/js-compute, bundles the reachable Pulse application and package implementations, and contains no Pulse Native artifact. The generated build first produces dist/index.js, then the pinned Fastly JavaScript compiler produces bin/main.wasm. Candidate, source-package, deployment, and top-level manifests agree on the selected fastly-javascript target and retain automaticFallback: false.

The release gate builds the source closure twice, compares its bytes, and successfully invokes the pinned downstream compiler. The resulting runtime Wasm is bound to the candidate by SHA-256. Wizer-owned runtime snapshot bytes are not claimed byte-reproducible; the Pulse-owned closure and deployment metadata are.

Provider selection is configuration-owned. Removed public --provider and --source-only flags are rejected with stable diagnostics.

Use:

pulse doctor ./my-app --json

to inspect compiler and Fastly CLI readiness before a release build.

Local conformance and external reality#

For Fastly Native, pulse test and pulse dev use the provider’s local canonical runtime. For Fastly JavaScript, they use explicit provider emulation and the same provider-owned bundled application closure. Both paths use configured values, fixtures, and optional network fetch; neither silently runs through the Node provider.

The native provider module is checked by the explicit reality profile through an inspected local Compute launcher. PULSE_FASTLY_BIN selects CLI-owned fastly compute serve --file; PULSE_VICEROY_BIN selects direct viceroy serve when no explicit Fastly CLI launcher is selected. Both are documented in Environment variables.

The Fastly reality gate proves Native local host-ABI compatibility through real HTTP requests covering schemas, configuration, secrets, KV persistence, named-backend fetch, opaque bytes, repeated headers, and GRIP hold/publish. The JavaScript candidate gate proves downstream runtime compilation but does not invoke fastly compute serve. Neither gate claims that remote resources or a deployed Fastly service are healthy; remote deployment remains separately unvalidated.

Fastly JavaScript is generally available under the full-target-support policy: all declared runtime, capability, packaging, four-mode, tooling, and offline candidate gates are satisfied. General availability is a supported-target statement, not evidence that a particular candidate was deployed.

Public entry points#

Other exported compiler/runtime subpaths are compatibility or implementation surfaces and do not gain the same application-facing promise.

Handler isolation#

Application source continues to import only @pulse-compute/runtime and supported package facades. The provider plan records:

{
  "providerSpecificUserland": false,
  "providerSdkUserland": false,
  "capabilityDiscoveryFromUserland": false
}

Do not import Fastly SDK objects into canonical handlers. Bindings belong in project configuration.

Current limitations#

• The official fastly shorthand resolves this package's explicit

./toolchain export. That narrow bootstrap is not automatic plugin discovery, self-registration, or a lowerer extension API.

• Local fixtures do not provision Fastly resources.
• Offline candidate validation does not deploy, activate, or publish a Fastly service.
• Dynamic backends are disabled unless explicitly enabled.
• GRIP requires the documented Fanout/publish bindings for the operations used.
• Full userland stream processing and provider SDK escape hatches remain

outside the Beta.

Related documentation#

• Fastly deployment candidates
• Fastly config, secrets, and KV
• GRIP and Fanout
• Contracts and providers
• Add a core provider
• Fastly diagnostics