Skip to content
NocleyeNocleye Docs

Overview

The Nocleye API gateway is self-hosted. It sits in front of your backend services and, for every request, decides which service receives it, who the caller is, whether the caller has exceeded a usage limit, and which headers are passed on.

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.

Terminal window
nocleye check   --gConfigPath ./gateway.yaml
nocleye gateway --gConfigPath ./gateway.yaml --gPort 8080

What you get

Section titled “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 without starting it. 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 and a live config API. Private listener, 127.0.0.1:8081 by default. 
                  ┌──────────────────── nocleye ────────────────────┐
  callers  ────▶  │  gateway listener :8080   ──▶  your backends    │
                  │  support server   :8081   ◀──  probes, scrapers │
                  └─────────────────────────────────────────────────┘

The gateway CLI

Section titled “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

Section titled “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, 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

Section titled “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.
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

Section titled “How a request is handled”
  1. Route match. The longest matching PathPattern wins. No match returns 404.
  2. Usage control by IP. A caller over the limit gets 429.
  3. Authentication. A failed validation returns 401. The identity inside the token becomes the caller ID.
  4. Client identification. Without authentication, the route’s client ID rule decides who the caller is.
  5. Header shaping. The header rule decides which headers are forwarded, removed or added.
  6. Forwarding. The path is optionally rewritten and the request is sent to the backend.
  7. Logging. One access log line is written, and Prometheus metrics are updated when enabled.

The full walkthrough is in How requests are handled.