PulseDocumentation
Pulse 1.0.0-beta.1 betaExact, immutable release documentation.Browse latest
Documentation platform maintainersactiveReviewed 2026-08-01Review by 2027-01-12

Project configuration reference#

Conventional .pulse/config.ts#

Conventional projects use one deferred, synchronous defineConfig factory from @pulse-compute/pulse. Every top-level key except pulse is a flat profile. The scope exposes symbolic config and secret references; it never resolves ambient values while the project plan is built.

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: 'node',
    target: 'native',
    apiBase: scope.config('API_BASE'),
    apiToken: scope.secret('API_TOKEN'),
  },
}))

Project pointers are workspace-relative. Profile selection is explicit and deterministic:

  1. --profile
  2. PULSE_PROFILE
  3. pulse.defaultProfile

Project commands accept one optional positional directory and otherwise start from the current directory. Discovery searches upward only for .pulse/config.ts. Public entry, config-file, workspace, provider, and target overrides are not supported.

  1. Discovery starts at the positional directory or the current working directory and searches upward for .pulse/config.ts.
  2. Profile precedence is --profile, PULSE_PROFILE, then pulse.defaultProfile.
  3. A selected-profile crypto declaration replaces pulse.crypto completely; array and object forms never merge.
  4. Command-line output, host, port, and watch values override the corresponding active-profile field for that command. Entry, provider, and target remain project-configured.
  5. Dedicated harness case inputs replace development inputs for that case; they do not configure deployment resources.
  6. Provider deployment bindings come from the configured provider object; handler source never receives provider SDK objects.

Project and provider selection#

Select the canonical entry, provider, and build output.

entry#

Project-relative TypeScript handler entry.

  • Type: string
  • Required/default: Optional; default ./src/index.ts.
  • Allowed values or constraints: —
  • Scope: all project commands
  • Precedence: pulse.entry in .pulse/config.ts.
  • Security and safety: Must resolve to an existing file.
  • Related diagnostics: PULSE_ENTRY_NOT_FOUND

provider#

Selects provider validation, local conformance, and build realization through the provider package toolchain contract.

outDir#

Project-relative artifact output directory.

  • Type: string
  • Required/default: Optional; default ./dist.
  • Allowed values or constraints: —
  • Scope: compile/build
  • Precedence: --out overrides this field for the current command.
  • Security and safety: Must remain a real child of the project root; absolute, parent-traversal, and symbolic-link traversal outside the project root is rejected.
  • Related diagnostics: PULSE_BUILD_OUT_UNSAFE

reporting#

Resolved synchronous logging threshold after the flat profile override is applied.

  • Type: 'off' | 'error' | 'warn' | 'info' | 'debug'
  • Required/default: Optional; default info.
  • Allowed values or constraints: off, error, warn, info, debug
  • Scope: compile/build/dev/test
  • Precedence: Selected-profile reporting, then pulse.reporting, then info.
  • Security and safety: Known request-owned secret values are redacted before provider emission.
  • Related diagnostics: PULSE_REPORTING_LEVEL_UNSUPPORTED (family fallback; reference root)

Cryptographic requirements#

Declare exact algorithms for the global or selected profile and resolve one target realization without fallback. This surface is part of the synchronized 1.0.0-beta.1 package set.

pulse.crypto#

Declares the complete global algorithm set. Array entries are canonical algorithm names; object entries may pin one exact known realization.

  • Type: readonly ('HS256' | 'ES256')[] | { readonly HS256?: { readonly realization?: PulseCryptoRealization }; readonly ES256?: { readonly realization?: PulseCryptoRealization } }
  • Required/default: Optional; default implicit no-crypto declaration.
  • Allowed values or constraints: HS256, ES256; exact pins runtime-builtin, guest-source:pulse-hmac-as, and guest-linked:pulse-es256-rustcrypto-p256
  • Scope: global crypto requirement default
  • Precedence: Used only when the selected profile omits crypto.
  • Security and safety: Keys and verification bytes are not configuration values. Target selection is deterministic and never probes or falls back.
  • Related diagnostics: PULSE_CRYPTO_CONFIG_SHAPE_INVALID (family fallback; reference root), PULSE_CRYPTO_ALGORITHM_DUPLICATE (family fallback; reference root), PULSE_CRYPTO_ALGORITHM_UNKNOWN (family fallback; reference root), PULSE_CRYPTO_REALIZATION_UNKNOWN (family fallback; reference root)

<profile>.crypto#

Replaces the complete global crypto declaration for the selected profile. Arrays and objects never merge with pulse.crypto.

  • Type: readonly ('HS256' | 'ES256')[] | { readonly HS256?: { readonly realization?: PulseCryptoRealization }; readonly ES256?: { readonly realization?: PulseCryptoRealization } }
  • Required/default: Optional; default inherit pulse.crypto when absent.
  • Allowed values or constraints: [] and {} explicitly select no crypto; otherwise HS256 and/or ES256
  • Scope: selected profile
  • Precedence: Selected-profile declaration replaces pulse.crypto; absence inherits it.
  • Security and safety: Every declared algorithm must resolve for the selected target before lowering. A failed exact realization cannot select another backend.
  • Related diagnostics: PULSE_CRYPTO_CONFIG_REQUIRED (family fallback; reference root), PULSE_CRYPTO_REALIZATION_PIN_INVALID (family fallback; reference root), PULSE_CRYPTO_REALIZATION_UNAVAILABLE (family fallback; reference root)

JSON schema policy#

Configure bounded schema-body policy. Conventional projects declare registry identity only through pulse.schema.

schemas#

Sets schema body limits and content-type policy. Schema identities come from the module selected by pulse.schema.

  • Type: PulseSchemaConfig
  • Required/default: Optional; default {}.
  • Allowed values or constraints: —
  • Scope: compile/dev/test/build
  • Precedence: Configuration value.
  • Security and safety: Structured bodies are bounded before decoding.
  • Related diagnostics: PULSE_SCHEMA_COMPILE_FAILED

schemas.contentTypePolicy#

Controls whether a JSON content type is mandatory.

  • Type: 'accept-json-or-missing' | 'require-json'
  • Required/default: Optional; default accept-json-or-missing.
  • Allowed values or constraints: accept-json-or-missing, require-json
  • Scope: request and fetched-body schema decode
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: PULSE_SCHEMA_CONTENT_TYPE_POLICY_INVALID (family fallback; reference root), PULSE_SCHEMA_DECODE

schemas.maxBytes#

Maximum buffered bytes accepted by schema decoding.

  • Type: positive safe integer
  • Required/default: Optional; default 65_536.
  • Allowed values or constraints: —
  • Scope: structured schema decode
  • Precedence: Configuration value.
  • Security and safety: Raise deliberately; this is a memory and request-amplification boundary.
  • Related diagnostics: PULSE_SCHEMA_BODY_LIMIT_INVALID (family fallback; reference root), PULSE_BODY_TOO_LARGE

Local development#

Configure the foreground local server and local-only provider inputs.

dev#

Development listener and local fixture inputs.

  • Type: object
  • Required/default: Optional; default {}.
  • Allowed values or constraints: —
  • Scope: pulse dev and local conformance
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: None specific.

dev.host#

Listener host.

  • Type: string
  • Required/default: Optional; default 127.0.0.1.
  • Allowed values or constraints: —
  • Scope: pulse dev
  • Precedence: --host overrides this field.
  • Security and safety: Binding a non-loopback address exposes the local development server.
  • Related diagnostics: PULSE_DEV_HOST_INVALID (family fallback; reference root)

dev.port#

Listener port.

  • Type: integer
  • Required/default: Optional; default 8787.
  • Allowed values or constraints: 0–65535; 0 requests an ephemeral port
  • Scope: pulse dev
  • Precedence: --port overrides this field.
  • Security and safety: No special handling.
  • Related diagnostics: PULSE_DEV_PORT_INVALID (family fallback; reference root)

dev.watch#

Watches the entry and schema dependency graph.

  • Type: boolean
  • Required/default: Optional; default true.
  • Allowed values or constraints: —
  • Scope: pulse dev
  • Precedence: --watch or --no-watch overrides this field.
  • Security and safety: Configuration-file changes still require a restart.
  • Related diagnostics: None specific.

dev.maxBodyBytes#

Maximum request body accepted by the local development server.

  • Type: positive safe integer
  • Required/default: Optional; default 65_536.
  • Allowed values or constraints: —
  • Scope: incoming local requests
  • Precedence: Configuration value.
  • Security and safety: Raise deliberately; this is a memory and request-amplification boundary.
  • Related diagnostics: PULSE_DEV_BODY_LIMIT_INVALID (family fallback; reference root), PULSE_REQUEST_BODY_TOO_LARGE

dev.networkFetch#

Allows unmatched local fetches to use the network.

  • Type: boolean
  • Required/default: Optional; default selected provider default.
  • Allowed values or constraints: —
  • Scope: local fetch realization
  • Precedence: This explicit field overrides the selected provider local default.
  • Security and safety: Keep disabled for deterministic or untrusted test inputs.
  • Related diagnostics: PULSE_FETCH_IMPLEMENTATION_UNAVAILABLE, PULSE_FETCH_NETWORK

dev.config#

Local configuration-store values.

  • Type: Readonly<Record<string, string>>
  • Required/default: Optional; default {}.
  • Allowed values or constraints: —
  • Scope: local config capability
  • Precedence: Configuration value.
  • Security and safety: Development input only; it does not configure deployed provider stores.
  • Related diagnostics: None specific.

dev.secrets#

Local secret-store values.

  • Type: Readonly<Record<string, string>>
  • Required/default: Optional; default {}.
  • Allowed values or constraints: —
  • Scope: local secret capability
  • Precedence: Configuration value.
  • Security and safety: Raw values are omitted from project JSON, diagnostics, and runtime error details; do not commit real production secrets.
  • Related diagnostics: None specific.

dev.kv#

Local KV stores keyed by configured logical store name.

  • Type: Readonly<Record<string, Readonly<Record<string, unknown>>>>
  • Required/default: Optional; default {}.
  • Allowed values or constraints: —
  • Scope: local KV capability
  • Precedence: Configuration value.
  • Security and safety: Development input only; it is not deployed.
  • Related diagnostics: None specific.

dev.fetches#

Deterministic fetch fixtures resolved before optional live network fetch.

  • Type: Readonly<Record<string, unknown>>
  • Required/default: Optional; default {}.
  • Allowed values or constraints: —
  • Scope: local fetch capability
  • Precedence: Configuration value.
  • Security and safety: Prefer fixtures for deterministic tests and offline development.
  • Related diagnostics: None specific.

Fastly provider options#

Options passed to fastly(...) from @pulse-compute/provider-fastly.

fastly.configStore#

Fastly Config Store resource name.

  • Type: string
  • Required/default: Optional; default pulse_config.
  • Allowed values or constraints: —
  • Scope: Fastly config capability
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: None specific.

fastly.secretStore#

Fastly Secret Store resource name.

  • Type: string
  • Required/default: Optional; default pulse_secrets.
  • Allowed values or constraints: —
  • Scope: Fastly secret capability
  • Precedence: Configuration value.
  • Security and safety: The name is build metadata; secret values are never embedded by this option.
  • Related diagnostics: None specific.

fastly.kv#

Maps logical ctx.kv names to Fastly KV Store resource names.

  • Type: Readonly<Record<string, string>>
  • Required/default: Optional; default {}.
  • Allowed values or constraints: —
  • Scope: Fastly KV capability
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: PULSE_FASTLY_KV_BINDINGS_INVALID

fastly.backends#

Maps static absolute origin URLs to named Fastly backends.

  • Type: Readonly<Record<string, string>>
  • Required/default: Optional; default {}.
  • Allowed values or constraints: —
  • Scope: Fastly fetch capability
  • Precedence: Configuration value.
  • Security and safety: Prefer explicit backends over dynamic origin authority.
  • Related diagnostics: PULSE_FASTLY_BACKEND_BINDINGS_INVALID, PULSE_FASTLY_BACKEND_REQUIRED

fastly.dynamicBackends#

Allows undeclared outbound origins to use dynamic backends.

  • Type: boolean
  • Required/default: Optional; default false.
  • Allowed values or constraints: —
  • Scope: Fastly fetch capability
  • Precedence: Configuration value.
  • Security and safety: Opt in deliberately because it broadens outbound authority.
  • Related diagnostics: PULSE_FASTLY_BACKEND_REQUIRED

fastly.grip#

Provider-owned bindings used by package-owned GRIP compatibility and canonical broadcast effects.

  • Type: object
  • Required/default: Optional; default omitted.
  • Allowed values or constraints: —
  • Scope: Fastly GRIP capability
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: None specific.

fastly.grip.fanoutBackend#

Named Fastly Fanout backend.

  • Type: string
  • Required/default: Optional; default omitted.
  • Allowed values or constraints: —
  • Scope: GRIP hold
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: PULSE_FASTLY_GRIP_FANOUT_BACKEND_REQUIRED

fastly.grip.publishEndpoint#

Provider-owned absolute publish/control endpoint; distinct from public gateway and ingress URLs.

  • Type: string
  • Required/default: Optional; default omitted.
  • Allowed values or constraints: —
  • Scope: GRIP broadcast
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: PULSE_FASTLY_GRIP_PUBLISH_BINDING_REQUIRED

fastly.grip.publishUrl#

Absolute publish endpoint URL.

  • Type: string
  • Required/default: Optional; default omitted.
  • Allowed values or constraints: —
  • Scope: GRIP publish
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: PULSE_FASTLY_GRIP_PUBLISH_BINDING_REQUIRED

fastly.grip.publishBackend#

Named backend for the provider publish endpoint.

  • Type: string
  • Required/default: Optional; default omitted.
  • Allowed values or constraints: —
  • Scope: GRIP broadcast/publish
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: PULSE_FASTLY_GRIP_PUBLISH_BINDING_REQUIRED

fastly.grip.authentication#

Authentication metadata containing references only; no credential value is accepted here.

  • Type: object
  • Required/default: Optional; default omitted.
  • Allowed values or constraints: —
  • Scope: GRIP broadcast authentication
  • Precedence: Configuration value.
  • Security and safety: Store the value in Fastly Secret Store and configure only secretRef.
  • Related diagnostics: None specific.

fastly.grip.authentication.scheme#

Provider authentication scheme.

  • Type: 'bearer'
  • Required/default: Optional; default bearer.
  • Allowed values or constraints: —
  • Scope: GRIP broadcast authentication
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: PULSE_FASTLY_NATIVE_GRIP_AUTH_SCHEME_UNSUPPORTED (family fallback; reference root)

fastly.grip.authentication.secretRef#

Named Fastly Secret Store key used for the bearer token.

  • Type: string
  • Required/default: Optional; default omitted.
  • Allowed values or constraints: —
  • Scope: GRIP broadcast authentication
  • Precedence: Configuration value.
  • Security and safety: The secret value is resolved only at request execution and is redacted from traces.
  • Related diagnostics: PULSE_FASTLY_NATIVE_GRIP_SECRET_REFERENCE_MISSING (family fallback; reference root)

fastly.grip.directHold#

Enables the direct host-owned hold response realization.

  • Type: boolean
  • Required/default: Optional; default true.
  • Allowed values or constraints: —
  • Scope: GRIP hold
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: None specific.

fastly.name#

Generated Fastly package name.

  • Type: string
  • Required/default: Optional; default pulse-app.
  • Allowed values or constraints: —
  • Scope: Fastly package metadata
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: None specific.

fastly.description#

Generated Fastly package description.

  • Type: string
  • Required/default: Optional; default Pulse application.
  • Allowed values or constraints: —
  • Scope: Fastly package metadata
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: None specific.

fastly.authors#

Generated Fastly package authors.

  • Type: readonly string[]
  • Required/default: Optional; default [].
  • Allowed values or constraints: —
  • Scope: Fastly package metadata
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: None specific.

fastly.local#

Local-only behavior; it does not alter the deployed target.

  • Type: object
  • Required/default: Optional; default {}.
  • Allowed values or constraints: —
  • Scope: local Fastly conformance
  • Precedence: Configuration value.
  • Security and safety: No special handling.
  • Related diagnostics: None specific.

fastly.local.networkFetch#

Allows unmatched local Fastly fetches to use the network.

  • Type: boolean
  • Required/default: Optional; default false.
  • Allowed values or constraints: —
  • Scope: local Fastly fetch realization
  • Precedence: dev.networkFetch overrides this value when explicitly set.
  • Security and safety: Keep disabled for deterministic tests and offline development.
  • Related diagnostics: None specific.

Fastly profile example#

local: {
  host: 'fastly',
  target: 'native',
  fastly: {
    bindings: {
      configStore: 'pulse_config',
      secretStore: 'pulse_secrets',
      kv: { sessions: 'sessions' },
      backends: { 'https://api.example.com': 'api_backend' },
      dynamicBackends: false,
      grip: {
        fanoutBackend: 'fanout',
        publishUrl: 'https://publisher.example.com/publish',
        publishBackend: 'publisher',
        directHold: true,
      },
    },
    build: { name: 'pulse-app', authors: ['Team'] },
    local: { networkFetch: false },
  },
}

Deployment resource names configure provider bindings; local dev.config, dev.secrets, dev.kv, and dev.fetches values never create or populate deployed resources.

Safety invariants#

  • Output directories must remain real descendants of the project root.
  • Structured request and schema bodies are bounded before decoding.
  • Live local network fetch is explicit for Fastly and can be disabled for Node.
  • Raw secret values are redacted from public JSON, diagnostics, and runtime error detail.
  • Provider SDK objects and provider-specific namespaces never enter canonical handler scope.
  • none is compile-only; it cannot execute pulse dev or pulse test.
Browse other documentation
Start
Examples
Guides
Concepts
Packages
Reference
Authors and contributors