# Generating Gateway Routes from Domain Manifests

A hand-maintained gateway configuration accumulates routes whose purpose is forgotten and overlaps whose precedence is accidental, until adding a domain becomes a change-management exercise. Generating the table from domain manifests removes both problems at once: precedence becomes explicit, overlaps become compile errors, and a new domain becomes routable by registering rather than by editing a shared file. This guide builds that compiler, including the checks that make a bad table fail a build instead of a request. It implements the generation discipline in API Gateway Mapping for GIS Services within Federated Ownership & Routing Architecture.

# Prerequisites

# Step-by-Step Implementation

# 1. Compile manifests into routes with explicit precedence

# compile_routes.py — manifests in, gateway table out. Deterministic.
import hashlib
import json


def routes_for(manifest: dict) -> list[dict]:
    """One route per declared port. Precedence is derived from match specificity,
    so it cannot depend on the order manifests happen to be read in."""
    m, s = manifest["metadata"], manifest["spec"]
    out = []
    for port in s["ports"]:
        match = {
            "header:x-spatial-domain": m["domain"],
            "path_prefix": f"/{m['domain']}/{m['name']}",
            "port_type": port["type"],
        }
        if port.get("matrixSet"):
            match["header:x-spatial-matrixset"] = port["matrixSet"]
        if s["storage"].get("crs"):
            match["header:x-spatial-crs"] = s["storage"]["crs"]
        out.append({
            "id": f"{m['domain']}.{m['name']}.{port['type']}",
            "match": match,
            # More match conditions = more specific = higher precedence. Explicit,
            # total, and independent of file order.
            "priority": len(match) * 100,
            "backend": f"{m['domain']}-{m['name']}-{port['type']}.svc",
            "sla_tier": s.get("slo", {}).get("availability", 0.999),
            "owner": m["owner"],
        })
    return out


def compile_table(manifests: list[dict]) -> dict:
    routes = [r for m in manifests for r in routes_for(m)]
    routes.sort(key=lambda r: (-r["priority"], r["id"]))   # deterministic ordering
    digest = hashlib.sha256(
        json.dumps(routes, sort_keys=True, separators=(",", ":")).encode()
    ).hexdigest()[:16]
    return {"version": digest, "routes": routes}

Verify the compile is deterministic — the same manifests must always produce the same table digest, or the drift signal is worthless:

python3 compile_routes.py --registry "$REGISTRY_API" | jq -r .version
python3 compile_routes.py --registry "$REGISTRY_API" | jq -r .version
# The two digests must match.

# 2. Fail the build on an ambiguous or unreachable route

# checks.py — the two failures that must never reach production.
def check_no_ambiguity(routes: list[dict]) -> list[str]:
    """Two routes that can match one request without a defined ordering between
    them make dispatch depend on evaluation order rather than on ownership."""
    errors = []
    for i, a in enumerate(routes):
        for b in routes[i + 1:]:
            if a["priority"] != b["priority"]:
                continue                      # precedence resolves it
            shared = set(a["match"].items()) & set(b["match"].items())
            if len(shared) == len(a["match"]) == len(b["match"]):
                errors.append(
                    f"ambiguous: {a['id']} ({a['owner']}) and {b['id']} ({b['owner']}) "
                    f"match identically at priority {a['priority']}")
    return errors


def check_backends_exist(routes: list[dict], resolve) -> list[str]:
    """A route to a service that does not exist is a 503 waiting for a consumer."""
    return [f"unreachable: {r['id']} -> {r['backend']}"
            for r in routes if not resolve(r["backend"])]

Verify both checks bite, using a deliberately broken manifest:

python3 compile_routes.py --registry "$REGISTRY_API" --extra-manifest /tmp/conflicting.yaml \
  2>&1 | grep -E '^(ambiguous|unreachable):'
echo "exit=$?"    # non-zero — the build fails and names both owners

# 3. Review the generated diff, not the manifest patch

The reviewable artifact is what changes about routing, which a manifest diff does not show.

# What this change does to the table, in terms a reviewer can evaluate.
python3 compile_routes.py --registry "$REGISTRY_API" --ref main > /tmp/before.json
python3 compile_routes.py --registry "$REGISTRY_API" --ref HEAD > /tmp/after.json

python3 - <<'PY'
import json
before = {r["id"]: r for r in json.load(open("/tmp/before.json"))["routes"]}
after  = {r["id"]: r for r in json.load(open("/tmp/after.json"))["routes"]}
for rid in sorted(after.keys() - before.keys()):   print(f"+ {rid} -> {after[rid]['backend']}")
for rid in sorted(before.keys() - after.keys()):   print(f"- {rid}")
for rid in sorted(before.keys() & after.keys()):
    if before[rid] != after[rid]:
        print(f"~ {rid}: priority {before[rid]['priority']} -> {after[rid]['priority']}")
PY

# 4. Deploy as a full replacement, never a patch

# Idempotent by construction: applying the same table twice changes nothing, and
# rolling back is a rebuild from a previous registry state rather than an undo.
gateway-cli apply --table /tmp/after.json --env "$GATEWAY_ENV" --replace

# Confirm the live table's digest matches what was compiled.
gateway-cli describe --env "$GATEWAY_ENV" | jq -r .table_version
jq -r .version /tmp/after.json

# Configuration Reference

# Common Failure Modes & Fixes

The digest changes on every compile with no manifest change. Root cause: a non-deterministic input — a timestamp, an unsorted dictionary, a set iteration. Fix: sort everything before hashing; without determinism the digest cannot detect drift.

Two domains conflict and the build passes. Root cause: their match conditions differ by one inert field, so the priorities differ and the ambiguity check does not fire — yet both still match a real request. Fix: check for overlapping match sets, not identical ones, whenever priorities are close.

A generated route is edited by hand in an incident. Root cause: entirely understandable and it will happen. Fix: make the next compile overwrite it and alert on the divergence, so the fix is captured in a manifest rather than living in the gateway until someone rebuilds.

Reviewers approve a change that moves traffic unexpectedly. Root cause: the review artifact was the manifest patch. Fix: the route diff above; a rule intended to add a domain that captures a neighbour’s extent shows up as routes moving, which the patch does not reveal.

Deploy succeeds and old routes persist. Root cause: applying as a patch rather than a replacement. Fix: --replace; incremental application is how orphaned routes accumulate.

# FAQ

# Related

• API Gateway Mapping for GIS Services — the parent topic and the generation rationale
• Mapping API Gateways to Distributed GIS Endpoints — the route table’s runtime behaviour
• Cross-Domain Routing Strategies — the precedence and default rules this enforces