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 layersfor product and user chains (global is git-maintained when files are deployed)Triggersdetail 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:
- Open the relevant chain (
global,product,user, orAPI) - Click
Designon an existing step - Adjust the generated YAML and derived policy name
- Save the new definition
- 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: ipis the safest default for public webhooks and unauthenticated APIskey_from: authorizationis useful when callers share egress IPskey_from: subonly 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:
removeis useful for stripping internal or secret-bearing headers before forwardingaddonly writes a header when it is absentsetoverwrites 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_jsonfor SOAP/XML ingress before a JSON-oriented workflow - Use
json_to_xmlon outbound responses when an upstream consumer expects XML - Use
bidirectionalwithdirection: bothfor inbound XML→JSON and outbound JSON→XML - Omit
mode(or setauto) 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)¶
- Route constraints / payload size
- Route-level
rate_limit(EdgeRoute YAML) - Route auth (
gateway_auth_mode) - Resolve chains: global + product + user + API
- Run inbound chain (throttle / headers / xml_json …)
- Forward to orchestrator
- Run outbound chain
- Route response header transforms
Examples live under flows/policies/.
Issue: MeshFlowsGPL/meshflows#41.