# Cross-Domain Routing Strategies

How a federated mesh resolves, validates, and steers spatial traffic across autonomous domains without reintroducing a central choke point.

Cross-domain routing is the moment a request leaves one team’s ownership and enters another’s. Inside a geospatial data mesh that crossing is not a network hop — it is a domain boundary enforcement event that must preserve data sovereignty, compute locality, and query semantics in a single deterministic decision. This page sits under Federated Ownership & Routing Architecture, which establishes that routing decisions derive from decentralized ownership registries rather than centralized DNS or static load balancers. Here the focus narrows to the steering logic itself: how a resolved domain identifier becomes a policy-checked, contract-validated route to either a synchronous domain node or an asynchronous job queue. The contract the edge enforces on each hop is defined upstream by the API Gateway Mapping for GIS Services layer; this page owns what happens once that gateway has decided a request belongs to another domain. The audience is data architects, platform engineers, GIS data stewards, and enterprise tech teams who need production-ready patterns, not topology slides.

Figure — Every cross-domain request is resolved, policy-checked, then steered to synchronous routing or an async job queue.

# Architectural Boundaries & Design Rationale

Routing in a geospatial mesh operates on strict domain isolation. Each spatial domain maintains independent compute topology, storage tiers, and access policies, and cross-domain traffic must never bypass a domain’s policy engine or rely on implicit network trust. The pattern exists to prevent three specific failure modes that centralized routing makes invisible: a consumer reaching authoritative data through a stale or guessed endpoint, a heavy spatial operation executing inline and exhausting a shared connection pool, and a payload crossing a boundary in a coordinate reference system the receiving domain cannot interpret. Each of those is a silent correctness failure, not a network error, so the boundary enforces them explicitly rather than hoping the network does.

Implementation requires a routing control plane that resolves domain identifiers to authoritative endpoints. Every ingress request carries domain-scoped routing headers (X-Spatial-Domain-Id, X-Data-Mesh-Context) evaluated against a real-time routing registry that tracks health states, capacity thresholds, and jurisdictional compliance flags. Deterministic path selection prioritizes geographic locality, schema compatibility, and SLA tier alignment, and is computed at the edge proxy using consistent hashing over domain identifiers so that cache locality holds and traffic distribution stays predictable under churn. The registry that feeds these decisions is kept current by Domain Sync Protocols for Spatial Data; a routing decision is only as fresh as the sync drift behind it, which is why drift appears as a first-class SLA below. When a primary domain endpoint degrades, the steering logic does not fail the client — it hands off to the Fallback Chains for Geocoding Services pattern as the last tier of its precedence chain.

# Specification & Contract Reference

Cross-domain routing degrades silently when spatial payloads lack structural guarantees, so the boundary defines an explicit contract surface. The headers, policy fields, and CRS requirements below are evaluated on every inter-domain hop; a request missing any required field is rejected at the edge rather than forwarded to a domain that cannot satisfy it.

These definitions are the routing-time projection of the versioned Schema Contracts for Vector/Tile Data; the edge pins the contract version so a producer schema bump cannot quietly drift a live route. Validation itself is declarative policy-as-code (OPA/Rego or Envoy WASM), and invalid payloads return a structured 400 Bad Request carrying the contract violation, not a generic gateway error.

# Production Implementation

The routing boundary is implemented in two coordinated layers: a policy module that validates the contract synchronously at the edge, and a Gateway API route that attaches that policy, injects the idempotency key, and bounds the request with strict timeouts. Both are committed to source control so the live boundary is reproducible.

Contract validation — spatial/ingress/validation.rego:

package spatial.ingress.validation

import rego.v1

# Zero-trust default: deny unless the contract is fully satisfied.
default allow := false

# Enforce CRS compliance and geometry precision for vector exchange.
allow if {
    input.request.method == "POST"
    crs := input.request.headers["X-Spatial-CRS"]
    crs == "EPSG:4326"
    precision := input.request.headers["X-Geometry-Precision"]
    precision in ["1e-6", "1e-7"]
}

# Emit a structured diagnostic the proxy returns verbatim on rejection.
deny contains msg if {
    not allow
    msg := sprintf("Contract violation: CRS=%s, Precision=%s. Expected EPSG:4326 with precision 1e-6 or 1e-7.", [
        input.request.headers["X-Spatial-CRS"],
        input.request.headers["X-Geometry-Precision"],
    ])
}

Policy evaluation is synchronous at the proxy layer, and rejected requests return a standardized envelope with trace_id, policy_version, and violation_code for downstream observability. Heavy spatial operations — spatial joins, raster resampling, topology validation — must never execute synchronously across a boundary; the route below injects an idempotency key, delegates validation to the OPA extension, and steers to an async dispatcher that hands off to the Async Execution for Heavy Spatial Queries backends. Idempotency is the zero-trust safety net here: a duplicate Idempotency-Key returns the cached 202 rather than re-dispatching compute, so retries under a thundering-herd retry storm stay safe.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: spatial-cross-domain-route
spec:
  parentRefs:
    - name: mesh-ingress-gateway
  hostnames:
    - "spatial.mesh.enterprise.internal"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: "/v1/spatial/join"
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Idempotency-Key       # promote client key into the routing fabric
                value: "from-header:Idempotency-Key"
        - type: ExtensionRef
          extensionRef:
            group: opa.io
            kind: PolicyBinding
            name: spatial-contract-validator   # the Rego module above
      backendRefs:
        - name: spatial-join-async-dispatcher   # 202 + Location, never inline compute
          port: 8080
          weight: 100
      timeouts:
        request: "10s"        # bound the boundary; never hold a cross-domain connection open
        backendRequest: "5s"

The strict timeout boundary is deliberate: a cross-domain connection held open waiting on a heavy operation is how one domain’s slowness becomes another domain’s connection-pool exhaustion. The dispatcher returns 202 Accepted with a Location header pointing at a job status endpoint, and the idempotency cache (Redis Cluster or DynamoDB) carries a TTL aligned to the job completion window.

# Diagnostic Runbook

When a cross-domain route misbehaves, the fault is almost always in header propagation, policy evaluation, registry sync, idempotency state, or the mTLS handshake — not the underlying network. Work the steps in order; each isolates one boundary the router enforces.

1. Recover the trace. Read traceparent from the client response and query the tracing backend for the routing-decision span and downstream latency breakdown. A missing trace means the request never cleared ingress validation — jump to step 3.
2. Confirm header propagation. Verify X-Spatial-Domain-Id, X-Data-Mesh-Context, and Authorization survived the proxy hop intact, using OpenTelemetry baggage for continuity. A dropped domain header collapses resolution to a default route and surfaces as a spurious 404 or a cross-domain data leak.
3. Audit policy evaluation. Query the OPA/Envoy decision logs for 403 (policy denial) or 400 (contract violation), and correlate policy_version with the deployed Rego/WASM module hash. A version skew here is a contract drift, not a bug.
4. Check registry sync latency. Validate routing-registry propagation; a decision latency above 50ms points to stale endpoint resolution or a control-plane partition. Confirm against the sync-drift budget owned by the domain sync controller.
5. Inspect the idempotency cache. Monitor hit/miss ratios for Idempotency-Key. High miss rates during retry storms indicate TTL misalignment or cache partitioning — both re-dispatch compute that should have been deduplicated.
6. Verify the mTLS handshake. Confirm SPIFFE ID rotation and certificate-chain validation; failed handshakes manifest as 502 Bad Gateway with SSL handshake failure in proxy error logs.
7. Force topology refresh on suspected desync. If endpoint resolution is suspect, trigger a forced refresh via the domain sync controller and re-run step 1 to confirm the corrected route resolves within budget.

# SLA Targets & Performance Baselines

Cross-domain routing carries thin, predictable overhead by design; the heavy work belongs to the domains behind it. The budget below is what the steering layer must hold so that downstream domain SLAs remain meaningful.

Holding these baselines relies on geographic affinity routing, HTTP/2 connection multiplexing, and edge caching for tile-matrix metadata, with proxies pre-warming domain endpoints from historical query patterns. Cache invalidation must stay event-driven — triggered by domain-ownership registry updates or schema-contract version bumps rather than fixed expiry — so a stale route is corrected within the sync-drift budget above. For interoperability, routing payloads align with the OGC API - Features specification, and custom spatial validation runs as Envoy Proxy WASM filters.

# Governance & Compliance Notes

Every routing decision is a governance decision, so the boundary treats route manifests as auditable artifacts. The Rego policy, the HTTPRoute, the WASM filter, and the tenant scope claims are all policy-as-code: committed to source control, reviewed, and promoted only after a CI pipeline validates schema compliance, replays idempotency behavior, and simulates policy-denial thresholds. This keeps a consumer-visible route bound to a governed data product whose catalog record lives in Metadata Cataloging for Raster/Vector.

Audit requirements are concrete. The router captures every routing decision, contract-validation failure, and idempotency cache hit in append-only, tenant-partitioned streams, and injects W3C Trace-Context plus OpenTelemetry baggage at ingress so each decision correlates with downstream spatial-engine logs. Structured error envelopes return a consistent violation_code, trace_id, retry_after, and policy_version for every 4xx/5xx, giving compliance reviewers a deterministic record. Where jurisdictional constraints apply — data-residency rules that bind a tenant’s vector features to a permitted extent — the router enforces them at the highest precedence tier, refusing to steer a request whose X-Data-Mesh-Context or bbox falls outside the allowed region, before any backend is contacted. The domain isolation this depends on is itself defined upstream by the boundary rules in the parent architecture; routing only enforces what ownership has already declared.

# Related

• Up to the parent: Federated Ownership & Routing Architecture
• API Gateway Mapping for GIS Services — the ingress contract a cross-domain request clears before it is steered
• Domain Sync Protocols for Spatial Data — keeps the routing registry fresh within the sync-drift budget
• Schema Contracts for Vector/Tile Data — the versioned definitions pinned at the routing edge
• Async Execution for Heavy Spatial Queries — the backends behind every 202 async route
• Fallback Chains for Geocoding Services — the degradation tier when a primary domain endpoint fails