The contract is the configuration.

Flexway loads an OpenAPI 3.1 contract and derives the set of served routes from it: exactly the declared operations, nothing more and nothing less. A route missing from the contract answers 404 by construction, with no rule to write to close it. A declared operation with no upstream prevents start-up: the gateway refuses to serve a partial configuration.

The flexway.yaml file describes how to serve - hosts, upstreams, issuers, policies - and lists no operation. Anything specific to an operation lives in the contract, as extensions reviewed alongside it by the team that changes it: x-flexway-upstream, x-flexway-timeout, x-flexway-rate-class, x-flexway-cache, x-flexway-tool. A host can serve its own contracts (hosts.<host>.contracts); the same route twice on one host, an operationId present in two contracts or an operation relayed to two upstreams are refused at load.

Decoding is strict: an unknown key is refused, never ignored, and every problem is reported in one pass. When taking over an existing API, the 404 on undeclared operations often reveals routes the previous gateway exposed without the contract ever mentioning them.

flexway validate checks, with no cluster and no network, that the file matches its schema, that the contracts load, that every operation has an upstream and that no upstream is orphaned. It exits non-zero on error, which makes it a CI step, and prints config_digest: the semantic fingerprint of what it loaded, identical whatever the mount path. That is the value a CI job can expect to see served after a merge.

Reloading goes through an immutable snapshot: the content fingerprint is re-read every server.reload.interval (5 s by default) and on SIGHUP. One hundred reloads under load lost no request, in-flight streams included, and unchanged upstreams and issuers are reused. An invalid configuration never replaces the running one: the refusal is logged once per version, counted (flexway.config.reloads) and visible in last_reload under /config.

Secrets are written as references only, ${VAR} or file:/path; a plain value under a secret key refuses the load. A few settings cannot be reloaded (server.shutdown, observability, server.reload, server.in_flight, server.cache): changing them refuses the reload as a whole, naming the key.

Importing an existing gateway's configuration is a one-off, offline import, never something read at start-up. Each endpoint is matched to a contract operation by method and path template; an endpoint absent from the contract is listed, never invented. The generated flexway.yaml goes through the real loader before it is written: what comes out of the import starts.

The output, in an empty directory, holds the configuration, the annotated contract with the same patch as JSON Patch (RFC 6902), and a coverage report that classifies each item: taken over, taken over differently, no equivalent. Upstreams, timeouts, rate limits and circuit breakers land in upstreams, x-flexway-timeout and policies; a contract less strict than the old configuration is reported, never silently changed. Embedded scripts and native plugins have no equivalent: no third-party code runs in the process.

SSE responses and chunked bodies are relayed without buffering: each chunk leaves as soon as it arrives. A stream is governed only by the inactivity timeout between two bytes (server.timeouts.read), never by the total exchange timeout. WebSocket is relayed after identity and rate checks at opening, and the connection outlives the total budget. On shutdown, /readyz turns red and in-flight streams are drained within a declared bound (server.shutdown.drain).

A gRPC upstream described by its Protobuf descriptors (contracts.protobuf) becomes callable over REST: the mapping comes from google.api.http annotations, the response comes back as canonical proto3 JSON, and a server stream becomes a text/event-stream, one message per event. gRPC and gRPC-Web are also served end to end, over h2c or TLS on the traffic listener, with no second port. An error on the gRPC surface is a google.rpc.Status whose ErrorInfo.reason carries the problem code.

Mappings the translation cannot honour (multi-segment variables, wildcard segments, verbs, client or bidirectional streaming over REST) are refused at load rather than served approximately. HTTP/3 on the caller side is upcoming.