Skip to content

Edge routes — implementation reference

Developer-oriented reference for the Gateway edge route layer (Sprint 1 foundation). For operator-facing route configuration, see Gateway API — Edge Route Configuration. For flow policies on routes, see Gateway flow policies.

Scope

Implemented capabilities:

  1. Edge route schema and validation (EdgeRouteConfig)
  2. Policy loader with TTL cache and last-known-good fallback
  3. Deterministic route matcher (method + path, exact and {param} templates)
  4. Gateway integration for alias endpoints (GET|POST|... /v1/api/{public_path})
  5. Structured edge.decision logs (allow/deny) for Loki + OTEL span attributes for Tempo

Route schema contract

The route contract is defined by EdgeRouteConfig in Gateway.

Top-level fields:

  • api_version (default meshflows.io/v1alpha1)
  • kind (default EdgeRouteConfig)
  • metadata (optional dictionary)
  • spec.routes (list of route entries)

Route entry fields:

  • id (required, unique)
  • method (required, normalized to uppercase)
  • path (required, must start with /; may include whole-segment params like {id})
  • target.workflow (required)
  • auth (optional, defaults applied)
  • constraints (optional, defaults applied)
  • rate_limit (optional)
  • transform (optional)

Validation rules:

  1. Duplicate route id is rejected.
  2. Duplicate (method, path) is rejected.
  3. Missing target.workflow is rejected.
  4. Invalid path templates (partial-segment {…}, duplicate param names) are rejected.

Policy loader lifecycle

Loader behavior (EdgeRoutePolicyLoader):

  1. Reads raw route config from configured source.
  2. Validates and parses config into typed model.
  3. Caches the parsed config for TTL (EDGE_ROUTE_CACHE_TTL_SECONDS).
  4. Supports explicit cache invalidation.
  5. On refresh failure, falls back to the last known good config if available.

Startup behavior:

  • Gateway performs startup validation in non-required mode.
  • Invalid startup config does not crash startup when no route is requested.
  • Runtime route resolution returns 503 if no valid config can be loaded.

Matcher semantics

Matcher behavior (EdgeRouteMatcher):

  1. Exact method + path match wins.
  2. Otherwise whole-segment templates are matched (/v1/api/products/{id} → /v1/api/products/10003).
  3. Among templates, prefer more static segments, then fewer params, then route id.
  4. Method match is case-insensitive via uppercase normalization.
  5. Path match is case-sensitive.
  6. Matched params are exposed to Orchestrator as query keys and X-Mesh-Property-* headers.

Gateway handler mapping:

  • /v1/api/{public_path} resolves route by incoming method and absolute path.
  • On hit: forwards to Orchestrator POST /run/{workflow}.
  • On miss: returns 404 and emits edge.decision deny log.

Environment variables

Route loader:

  • EDGE_ROUTE_CONFIG_JSON
  • EDGE_ROUTES_DIR (YAML files; see Gateway API)
  • EDGE_ROUTE_CACHE_TTL_SECONDS

Gateway forwarding path:

  • ORCHESTRATOR_URL
  • GATEWAY_MAX_XML_BYTES

Quickstart: add a new edge route

  1. Create or update route config with a unique route id and method/path pair.
  2. Set target.workflow to the internal workflow name.
  3. Load via EDGE_ROUTES_DIR or EDGE_ROUTE_CONFIG_JSON.
  4. Trigger cache refresh (or wait for TTL expiration).
  5. Validate with request tests.

Example config snippet:

{
  "api_version": "meshflows.io/v1alpha1",
  "kind": "EdgeRouteConfig",
  "metadata": { "name": "public-routes" },
  "spec": {
    "routes": [
      {
        "id": "orders-create-v1",
        "method": "POST",
        "path": "/v1/api/orders/create",
        "target": {
          "workflow": "sales_order_create_internal"
        }
      }
    ]
  }
}

Example request:

curl -s -X POST http://localhost:8080/v1/api/orders/create \
  -H "Content-Type: application/json" \
  -d '{"xml":"<order/>"}'

Expected behavior:

  • Route match forwards to orchestrator workflow sales_order_create_internal.
  • Unknown route under /v1/api/* returns 404.

Test coverage

  • engine/tests/test_gateway_edge_routes_schema.py
  • engine/tests/test_gateway_edge_policy_loader.py
  • engine/tests/test_gateway_edge_route_matcher.py
  • engine/tests/test_gateway_edge_route_integration.py

These tests validate schema constraints, loader fallback behavior, deterministic matching, and no-downstream-call behavior on deny paths.