How requests are handled

For every request, the gateway decides which service receives it, who the caller is, whether the caller has exceeded a usage limit, and which headers are passed on. Everything is driven by one YAML file passed with --gConfigPath.

Request pipeline

1. Route match. The request path is matched against the PathPattern of every route. The longest matching pattern wins. No match returns 404.
2. Usage control (by IP). The caller’s IP is checked against the usage control rules that apply to the route. A caller over the limit gets 429.
3. Authentication. If an authentication method applies to the route, the token is validated. A failed validation returns 401. The identity inside the token becomes the caller ID.
4. Client identification. If no authentication method applies, the route’s client ID rule decides how the caller is identified. Each identifier found is checked against the usage control rules.
5. Header shaping. The header rule of the route decides which headers are forwarded, removed or added.
6. Forwarding. The path is optionally rewritten and the request is sent to the backend. If the backend can’t be reached, the caller gets an error response.
7. Logging. One access log line is written for the request, and Prometheus metrics are updated when enabled.

Where rules apply: global, server, route

Rules (header, client ID, usage control) and authentication methods are defined once and then referenced by name from three places:

• GlobalConfig: the default for everything.
• A server in ServerConfigs: applies to every route that targets the server.
• A route in ServerRoutes: applies to that route only.

For header rules, client ID rules and authentication methods, the closest scope wins: route, then server, then global. Usage control rules are different, they can stack. See Usage control.

Features

Feature	What it does	Page
Servers and routes	Map public paths to backend services, rewrite paths, reach backends over HTTPS with a custom CA	Servers and routes
Header rules	Choose which request headers reach the backend, remove or add headers, preserve the original Host	Header rules
Client ID rules	Decide how a caller is identified (IP, token, header, query string)	Client ID rules
Usage control	Rate limit callers per global, server or route scope	Usage control
Authentication	Validate signed JWT tokens before a request is forwarded	Authentication
Config check	Validate a config file without starting the gateway	Command line
Logs and metrics	Gateway log, access log and Prometheus metrics	Logs and metrics