FARP: A Manifest Protocol for Gateway Route Derivation

#Abstract

Gateway configuration duplicates information the service already holds, producing two authorities that agree only when written. This specification describes a manifest published by each service and consumed by gateways, in which the routing table is a pure function of the manifests currently visible. Two implementations exist, written against the specification rather than against each other, and their agreement is the evidence offered that it is complete. Both share one author, so that independence is partial.

#Problem statement

A service knows its routes, since they are its handler registrations. It knows its request and response shapes, since they are its types. It knows its protocols and ports. This information is then restated in a gateway configuration held in a different repository, owned by a different team, deployed on a different cadence.

The resulting failure is mundane and continuous: an endpoint ships, the gateway is unaware, a ticket is raised, configuration is edited, and a deployment occurs whose entire content is catching up with a previous deployment. This is the module criterion violated across a process boundary [1]: knowledge of a component's interface is held outside the component.

#Routing as a function of manifests

Because ρ is a function rather than a merge of two authorities, two conforming gateways given identical manifest sets must produce identical routing tables. That is the central conformance requirement and it makes the specification testable independently of either implementation.

Static routes participate in the same precedence rules and are not a compromise of the model. The bootstrap route by which a gateway reaches discovery cannot itself be discovered, which is a general property of reconciliation-based systems rather than a defect here [2].

#Manifest contents

A service publishes its API surface across seven schema formats, together with health semantics and capability hints. The capability hints carry information the gateway cannot derive, of which the most valuable is whether an endpoint is idempotent and therefore safe to retry. That property is known to the service and has historically been supplied to gateways by a human estimate [3].

#Precedence

Two services may legitimately claim one path at different versions. Resolution is declared rather than first-writer-wins.

Version, then declared weight, then recency as a tiebreak. Recency is last deliberately, so that a restarted instance does not win a contest it would otherwise lose.

#Conformance requirements

1. Identical manifest sets produce identical routing tables.
2. A manifest failing validation removes its service from routing entirely. Partial application is not permitted.
3. Health semantics are declared by the service. A gateway may not substitute a default probe.
4. Precedence follows the ordering above with no implementation-defined tiebreak.

Requirements two and four were added only after a second implementation made different reasonable choices, which is the argument for two implementations being a completeness test rather than a duplication.

#Costs

Discovery moves onto the critical path for routing, and discovery has its own failure modes. Both implementations cache the last known good manifest set and continue serving from it, converting an outage into staleness.

Staleness has a distinct failure: an instance that is genuinely gone continues receiving traffic until health checks converge [4]. The specification requires that health semantics come from the service precisely so that this convergence time is declared rather than assumed.

The end-to-end argument applies to what belongs in the gateway at all [5]: the protocol deliberately performs no routing, rate limiting or traffic management, and holding that boundary is what allows two structurally different gateways to consume it.

#Limitations

No conformance suite is published alongside this specification. Until one exists, the claim that two implementations agree rests on manual comparison rather than an executable test, and that is the most significant gap.

Both implementations share one author, so the independence of the second is partial. An implementation by an unrelated party would test the specification considerably harder.