Morphosis API Gateway
Design proposal; not production-ready

One policy, two execution points

Traffic Routing Policy Center

Explains how published policy guides entry-region selection and post-authentication backend selection through two independent execution points.

Explains how published policy guides entry-region selection and post-authentication backend selection through two independent execution points.

7. Routing and Multi-Region Design

7.1 Routing Model

Every route configuration contains at least:

Before publication, a route must pass static validation: no route conflict, an existing required scope, a registered target service, an explicit idempotency policy for write requests, and bounded timeouts.

7.1.1 Traffic Routing Policy Center Decision Logic

The Traffic Routing Policy Center maintains one versioned policy but executes it in two places. The first execution point is at global ingress and selects only the ingress region. The second execution point is at the regional gateway and selects the backend after API Key validation and route matching are complete. The merchant or platform hint used at ingress is unauthenticated and may only reduce ingress candidates; it cannot grant permissions. Once inside a region, it must be rechecked against the verified identity. If inconsistent, select another qualified backend or reject the request.

%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 34, "rankSpacing": 38, "htmlLabels": true}}}%% flowchart TB PUBLISHED["Published policy<br/>primary_region · allowed_regions<br/>Service capability · failover_mode"] --> CENTER["Traffic Routing Policy Center<br/>Compiles versioned policy and runtime-state view"] RUNTIME["Runtime signals<br/>Regional / backend health · Replication lag · Writer state"] --> CENTER HINT["Unauthenticated routing hint<br/>Used for ingress selection only · Grants no permission"] --> EDGE_FILTER["Execution point 1 · Ingress-candidate filter<br/>allowed_regions · Compliance · Regional health"] EDGE_FILTER --> MODE{"Configured policy mode"} MODE --> FIXED["Design baseline · Fixed preferred region<br/>No automatic switching"] MODE --> FAILOVER["Design baseline · Active-standby<br/>Switch only to a qualified standby region"] MODE --> MULTI["Proposed option · Disabled by default<br/>Weighted / proximity routing within allowed_regions<br/>Stateless reads only"] FIXED --> ENTRY["Ingress-region decision<br/>Stop resolution or return 503 on failure<br/>Depends on global traffic product"] FAILOVER --> ENTRY MULTI --> ENTRY ENTRY --> AUTH["Regional ingress<br/>API Key validation + route matching"] AUTH --> CONTEXT["Verified merchant<br/>route + request_class"] CANDIDATES["Execution point 2 · Post-authentication candidate filter<br/>Service deployed · Healthy<br/>Configuration boundedly stale under Section 10.4"] CONTEXT --> CLASS{"Request type"} CANDIDATES --> CLASS CLASS -->|"Read"| READ_GATE["Read gate<br/>Replication lag does not exceed threshold<br/>State signal is not expired"] CLASS -->|"Write"| WRITE_GATE["Write gate<br/>Current writer preferred<br/>Cross-region requires global idempotency · unique constraints · explicit primary switch"] READ_GATE --> ELIGIBLE{"Candidates remain after filtering?"} WRITE_GATE --> ELIGIBLE ELIGIBLE -->|"Yes"| DECISION["Output routing decision<br/>target · reason_code · policy_version"] ELIGIBLE -->|"No"| REJECT["Fail closed<br/>Return 503"] CENTER -.->|"Ingress policy and state view"| EDGE_FILTER CENTER -.->|"In-region policy and state view"| CANDIDATES classDef input fill:#F4F7FB,stroke:#72849A,color:#253954,stroke-width:1.5px classDef policy fill:#EDF8F3,stroke:#16835E,color:#124D3B,stroke-width:1.5px classDef baseline fill:#EAF2FF,stroke:#1264D6,color:#12345B,stroke-width:1.5px classDef proposed fill:#FFF7E8,stroke:#B7791F,color:#62420F,stroke-width:1.5px classDef runtime fill:#FFFFFF,stroke:#4F79A7,color:#18212F,stroke-width:1.5px classDef reject fill:#FFF2EC,stroke:#C7582B,color:#6B2812,stroke-width:1.5px class PUBLISHED,RUNTIME,HINT,CONTEXT input class CENTER,EDGE_FILTER,MODE,CANDIDATES,CLASS,ELIGIBLE policy class FIXED,FAILOVER,ENTRY,AUTH,READ_GATE,WRITE_GATE,DECISION baseline class MULTI proposed class REJECT reject

The meeting confirmed only multi-region redundancy and routing capability, not a specific algorithm. Fixed preferred-region and active-standby modes are the current design baseline. Weighted or proximity-based active-active operation is a proposed option, disabled by default, and may be used only for stateless reads within a merchant's explicitly permitted regional set. Execution point 1 cannot reliably determine request type before authentication. If a write request is sent to a non-writer region, execution point 2 must still select the current writer or return 503; it must not create blind cross-region writes. The global traffic product, TLS termination point, and unauthenticated routing-hint mechanism remain undecided, so ingress-failure behavior and available inputs require confirmation after product selection. The reason_code in the diagram is written only to internal decision logs and audit; external errors follow Section 6.2.

7.2 Merchant Regional Assignment

Maintain an explicit preferred region and an allowed-region list for every merchant. The Traffic Routing Policy Center publishes the policy to two execution points: global ingress preferentially sends the merchant request to its preferred region, and the regional gateway chooses a backend after authentication according to merchant routing partition, service capability, and request type.

Merchant regional assignment must not rely only on DNS geographic resolution, because merchant egress, private-connectivity ingress points, and business-data location may differ. Regional policy must be configured and audited by the control plane.

7.3 Regional Failover

  1. Deploy gateway data planes across multiple availability zones; a single instance or availability-zone failure is automatically removed by regional load balancing.
  2. After the ingress execution point of the Traffic Routing Policy Center confirms that a region is unavailable, switch only merchants permitted for failover to configured and qualified standby regions.
  3. During platform onboarding, every platform must declare its read-consistency level, maximum permitted replication lag, the collection method for replication-state signals, and the maximum signal-validity period. A read request may fail over automatically only when the standby region reports replication lag no greater than the route's maximum allowed value and the status signal has not expired.
  4. A payment write request may be retried across regions only when the backend platform provides a global idempotency key, unique constraints, and an explicit primary write-region switching mechanism.
  5. If the backend does not satisfy the preconditions for cross-region writes, the gateway returns a traceable 503 and must not write to two regions simultaneously.
  6. Use controlled failback after the original region recovers: first validate authorization-configuration version and backend replication state, then gradually restore traffic.

7.4 Boundary for Multiple Backend Databases

The meeting mentioned that Zero Confirmation may use three databases and that BPS may adopt a similar pattern in the future. The gateway stores only metadata stating which backend service a merchant or partition should be routed to. It does not directly hold business sharding connections or split business SQL.

Every platform must independently guarantee:

  1. Consistency of partition mappings and business-database topology.
  2. Unique constraints and idempotency semantics for transaction writes.
  3. Cross-region replication, recovery-point objectives, and recovery-time objectives.
  4. Publication of new available service endpoints or routing versions to the gateway after a database switchover completes.

7.5 Control-Plane Disaster Recovery

The unified control plane uses an active-and-standby cross-region model, and only one control-plane region may write at any time:

  1. PostgreSQL uses synchronous replication in the primary region and asynchronous WAL replication in the standby region, with a standby replication-lag target of no more than 60 seconds.
  2. Control-plane versions use two-part (epoch, sequence) versions compared lexicographically. A normal commit increments only sequence. A primary-region switchover increments epoch before starting a new sequence, preventing two regions from producing comparable but diverging versions.
  3. Before primary-region promotion or standby takeover, confirm through managed-database fencing or a consensus lease that the former primary has lost write permission. Takeover is prohibited if fencing cannot be completed.
  4. A control-plane instance may accept management writes only while it holds a valid single-writer lease; it fails closed immediately when the lease expires.
  5. When standby-region WAL apply lag exceeds 60 seconds, stop accepting ordinary configuration writes and alert. Emergency deny-only operations use the break-glass channel in Section 10.3.
  6. After takeover, first recover unpublished Outbox events, then publish a full configuration snapshot with the new epoch. Every region rejects events from an old epoch.
  7. The recommended control-plane recovery-time objective is 30 minutes and configuration recovery-point objective is 1 minute. Both targets must be verified through quarterly recovery drills.

Failure of the control plane should not interrupt data-plane requests using already loaded configuration, but it pauses ordinary Key creation, rotation, Scope changes, IP changes, and route publication.