Skip to content

Gateway flow policies (linear chains)

Flow policies are reusable YAML definitions. At request time the gateway builds a linear chain from four layers and evaluates inbound steps before forwarding and outbound steps on the response.

global → product → user → API

Auth remains on the EdgeRoute (gateway_auth_mode). Policies do not replace route authentication.

Where they apply

  • Yes: Edge routes — /v1/api/... and /v1/webhooks/...
  • No (default build): direct POST /v1/run/{workflow}

Layers

Layer Source
Global Git flows/policy_chains/global/{http,schedule,amqp}.yaml (deploy → storage artifacts/policy-chains/global/; local disk via POLICY_CHAIN_DIR). Identity is fallback only when no git/storage document exists for that trigger.
Product Identity product field policy_chain, plus an implicit quota throttle from rate_limit_max_requests / rate_limit_window_seconds (keyed by sub)
User Identity GET/PUT /users/{username}/policy-chain
API Trigger invocation.policy_chain (ordered refs; edit via Triggers → Policy chain designer)

Dashboard surfaces the shared chain editor in three places:

  • Admin → Policy layers for product and user chains (global is git-maintained when files are deployed)
  • Triggers detail view for API / trigger chains

Earlier layers cannot be overridden upward. To give one API more room than others: keep the product quota as the ceiling and put tighter API-layer throttles on the other endpoints.

Each chain step also exposes a Design action that opens the policy as a draft, lets you save a new derived policy, and swaps the chain reference to that derived definition.

Policy definitions

Env Default Meaning
POLICY_DIR /app/flows/policies Optional on-disk seed (local/dev). Overlayed by storage.
POLICY_CHAIN_DIR /app/flows/policy_chains Optional on-disk global chains (local/dev). Overlayed by storage artifacts.
POLICY_CACHE_TTL_SECONDS 30 In-memory disk catalog refresh

Runtime source of truth: policy YAML uploaded to storage (POST /internal/upload/policies/{name}, same deploy path as workflows). The gateway polls GET /internal/policies and overlays those docs onto any optional disk catalog. Missing chain refs fail closed (HTTP 500).

Global chains: maintain flows/policy_chains/global/{http,schedule,amqp}.yaml in git. Deploy uploads them to artifacts/policy-chains/global/; the gateway prefers those over Identity.

Common fields

Field Required Description
name yes Stable ref used in chains
type yes throttle | oauth_outbound | xml_json | headers
direction no (default inbound) inbound | outbound | both
config type-specific See below
description no Operator notes

Chain step

policy_chain:
  - example-throttle-ip
  - ref: example-headers-strip-secret
    direction: inbound   # optional override

Derived policy workflow

Use a derived policy when the chain needs a one-off variant of an existing reusable policy instead of editing the shared base definition.

Typical flow in the dashboard:

  1. Open the relevant chain (global, product, user, or API)
  2. Click Design on an existing step
  3. Adjust the generated YAML and derived policy name
  4. Save the new definition
  5. The chain step is automatically rewritten to the new derived ref

This keeps the original policy reusable while allowing trigger- or tenant-specific variants.

Supported types

throttle

Fixed-window rate limit.

type: throttle
direction: inbound
config:
  max_requests: 60
  window_seconds: 60
  key_from: ip   # ip | authorization | sub

Reject → HTTP 429.

Notes:

  • key_from: ip is the safest default for public webhooks and unauthenticated APIs
  • key_from: authorization is useful when callers share egress IPs
  • key_from: sub only makes sense when route auth already establishes a subject

headers

Add / set / remove headers on inbound request or outbound response.

type: headers
direction: both
config:
  remove: [X-Internal-Secret]
  add: { X-Mesh-Env: edge }
  set: { X-Tenant: acme }

Notes:

  • remove is useful for stripping internal or secret-bearing headers before forwarding
  • add only writes a header when it is absent
  • set overwrites an existing header value deterministically

xml_json

Convert body XML ↔ JSON.

type: xml_json
direction: inbound
config:
  mode: xml_to_json   # xml_to_json | json_to_xml | bidirectional | auto
  # root_tag: root

Bidirectional (XML on the wire both ways):

type: xml_json
direction: both
config:
  mode: bidirectional
  root_tag: root
  # Optional overrides:
  # inbound_mode: xml_to_json
  # outbound_mode: json_to_xml

Notes:

  • Use xml_to_json for SOAP/XML ingress before a JSON-oriented workflow
  • Use json_to_xml on outbound responses when an upstream consumer expects XML
  • Use bidirectional with direction: both for inbound XML→JSON and outbound JSON→XML
  • Omit mode (or set auto) to sniff Content-Type / payload shape
  • Keep transformations narrow and predictable; avoid mixing structure conversion with business mapping

oauth_outbound

Client-credentials token fetch; inject into outbound headers.

type: oauth_outbound
direction: outbound
config:
  token_url: https://idp.example.com/oauth/token
  client_id: meshflows-edge
  client_secret: change-me
  scope: api.read

Notes:

  • This policy is typically outbound
  • Prefer secret references or secured deployment-time injection for client_secret
  • Use it when the workflow/gateway must call a downstream API with client-credentials OAuth

Evaluation pipeline (edge)

  1. Route constraints / payload size
  2. Route-level rate_limit (EdgeRoute YAML)
  3. Route auth (gateway_auth_mode)
  4. Resolve chains: global + product + user + API
  5. Run inbound chain (throttle / headers / xml_json …)
  6. Forward to orchestrator
  7. Run outbound chain
  8. Route response header transforms

Examples live under flows/policies/.

Issue: MeshFlowsGPL/meshflows#41.