Overview

The Nocleye API gateway is a self-hosted entry point for your backend services. Callers send requests to the gateway instead of to your services directly, and the gateway handles the parts every API needs before a request gets through:

Routing. Which service receives the request.
Identity. Who is calling, from a token, a header or an IP address.
Limits. Whether that caller has used up their allowed requests.
Headers. Which request headers reach the service.

Our focus is simple: make the easiest API gateway to use. Everything the gateway does is described by one YAML file, and one command tells you whether that file is correct before you ship it.

nocleye check   --gConfigPath gateway.yaml
nocleye gateway --gConfigPath gateway.yaml --gPort 8080

What you get

The gateway ships as one bundle with two parts. You install it once and get both.

Part	What it is	Where it runs
Gateway CLI	The `nocleye` binary. `nocleye gateway` runs the gateway, `nocleye check` validates a config, and three commands change the config of a running gateway.	Public listener, `0.0.0.0:8080` by default.
Support server	A second, internal HTTP server that starts next to the gateway. Health probes, Prometheus metrics, a live config API and a testing proxy.	Private listener, `127.0.0.1:8081` by default.

                  ┌──────────────────── nocleye ────────────────────┐
  callers  ────▶  │  gateway listener :8080   ──▶  your backends    │
                  │  support server   :8081   ◀──  probes, scrapers │
                  └─────────────────────────────────────────────────┘

The gateway CLI

One file drives everything. Servers, routes, header rules, client ID rules, usage control and authentication live in a single YAML file, passed with --gConfigPath.
Define once, bind by name. A rule is written once under Rules, then referenced by name from the global, server or route scope that needs it.
Check before you deploy. nocleye check lists every error and warning with where it is and how to fix it. Run it in CI.
Every flag has an environment variable, so the same command works in a shell, a container or an orchestrator.

See Command line and Configuration.

The support server

Probes. /healthz for liveness and /readyz for readiness, so load balancers stop sending traffic before the gateway drains.
Metrics. /metrics serves Prometheus metrics for the families you choose.
Live config API. Swap the running config, or load a testing config next to it and try it with the testing proxy, without a restart.

It is not part of the traffic path, and it is meant to stay on loopback or a private network. See Support server.

What the gateway supports

Feature	What it does
Servers and routes	Map public paths to backend services, rewrite paths, reach backends over HTTPS with a custom CA.
Header rules	Choose which request headers reach the backend, remove or add headers, preserve the original `Host`.
Client ID rules	Decide how a caller is identified: IP, token, header or query string.
Usage control	Rate limit callers per global, server or route scope.
Authentication	Validate signed JWT tokens before a request is forwarded.
Config check	Validate a config file without starting the gateway.
Live config commands	Load a testing config or swap the live one on a running gateway.
Support server	Health probes, `/metrics` and the live config API on an internal port.
Logs and metrics	Gateway log, access log and Prometheus metrics.

How a request is handled

The gateway matches a route, applies usage control, authenticates, shapes headers, forwards the request and logs it, in that order. See How requests are handled for each step and the status code it returns.