Bundle Structure

A policy bundle is a single JSON file that defines all enforcement rules for an edge instance. The file is loaded on startup and can be hot-reloaded without restarting the process.

Top-level fields

{
  "bundle_version": 1,
  "issued_at":  "2026-01-01T00:00:00Z",
  "expires_at": "2030-01-01T00:00:00Z",
  "global_shadow": { ... },
  "kill_switch_override": { ... },
  "policies": [ ... ],
  "kill_switches": [ ... ],
  "defaults": {}
}

Runtime override blocks

Both override blocks are optional and validated at bundle load time.

{
  "global_shadow": {
    "enabled": true,
    "reason": "incident-2026-02-20",
    "expires_at": "2026-02-20T19:00:00Z"
  },
  "kill_switch_override": {
    "enabled": true,
    "reason": "incident-2026-02-20",
    "expires_at": "2026-02-20T19:00:00Z"
  }
}

Validation rules when enabled=true:

• reason is required, non-empty, max 256 chars
• expires_at is required, ISO 8601 UTC, and must be in the future at load time

Runtime behavior:

• global_shadow: converts matched policy outcomes to shadow semantics (client path is allow; calculations still run)
• kill_switch_override: bypasses kill-switch pre-check
• No extra client response headers are added for these modes; observability is via logs and metrics

Monotonic versioning

Each time you update a bundle you must increment bundle_version. The hot-reload timer will silently skip the file if the version is not higher than the current one, logging version_not_monotonic at debug level.

# Safe incremental update
jq '.bundle_version += 1' policy.json > policy.json.new && mv policy.json.new policy.json

Policy object

{
  "id": "my-api-limits",
  "spec": { ... }
}

Policy spec

{
  "selector": { ... },
  "mode": "enforce",
  "rules": [ ... ],
  "fallback_limit": { ... },
  "loop_detection": { ... },
  "circuit_breaker": { ... }
}

Minimal example

One policy applied to all /api/v1/ routes. Every unique IP address gets its own token bucket: up to 100 requests per second steady-state, with a burst allowance of 200. Requests beyond that are rejected with 429.

{
  "bundle_version": 1,
  "policies": [
    {
      "id": "api-v1",
      "spec": {
        "selector": { "pathPrefix": "/api/v1/" },
        "rules": [
          {
            "name": "global-rps",
            "limit_keys": ["ip:address"],
            "algorithm": "token_bucket",
            "algorithm_config": {
              "tokens_per_second": 100,
              "burst": 200
            }
          }
        ]
      }
    }
  ],
  "kill_switches": []
}

Bundle signing (optional)

When FAIRVISOR_BUNDLE_SIGNING_KEY is set, the edge verifies an HMAC-SHA256 signature prepended to the bundle file. The signature is placed on the first line as a base64-encoded string, followed by a newline, followed by the JSON payload:

<base64-hmac-sha256-signature>
{"bundle_version":1, ...}

This prevents loading a tampered or accidentally overwritten bundle. The constant-time comparison prevents timing attacks.

Hot reload

Policy bundles are reloaded on a configurable interval (FAIRVISOR_CONFIG_POLL_INTERVAL, default 30 s). The edge re-reads the file and applies the bundle only if bundle_version has increased. No traffic is dropped during reload.

To force an immediate reload via a running SaaS-connected edge:

fairvisor status  # confirm current version
# Then push a new bundle via the SaaS dashboard