Reference
novagateway reference
Every novagateway flag, its NOVAGATEWAY_* environment variable and default, and how the Gateway sits in front of the fleet
novagateway is the Gateway: the internet-facing tier that serves Nova's HTTP and SSE API and speaks gRPC to the fleet behind it. The component's design is the Gateway architecture page. This page lists every flag with its environment variable and default, copied from novagateway --help, and describes how the process is deployed. The API it serves is the HTTP reference; using it is the HTTP guide.
novagateway [global options]Every flag has an environment variable; a flag beats its variable. There is no config file.
Listening and the fleet
| Flag | Env | Default | Meaning |
|---|---|---|---|
--listen | NOVAGATEWAY_LISTEN | :8080 | HTTP listen address |
--addr (repeatable) | NOVAGATEWAY_ADDRS | — | novad fleet address; one suffices, more are fallbacks |
--metrics-listen | NOVAGATEWAY_METRICS_LISTEN | :9090 | Prometheus /metrics listen address (the nova.gateway.* series); empty disables |
TLS termination
| Flag | Env | Default | Meaning |
|---|---|---|---|
--tls-cert | NOVAGATEWAY_TLS_CERT | — | PEM certificate (a wildcard for the zone) arming TLS termination; empty serves plaintext behind a terminating load balancer |
--tls-key | NOVAGATEWAY_TLS_KEY | — | PEM private key for --tls-cert |
Both files together arm TLS with a 1.2 floor; neither serves plaintext; half a pair refuses to start.
Plan-driven serving
Settled history is served from object storage instead of proxied record-by-record through the fleet: the Gateway asks a star for a read plan and fetches the settled bytes itself. --serve-plan=false is the kill switch that proxies everything.
| Flag | Env | Default | Meaning |
|---|---|---|---|
--serve-plan | NOVAGATEWAY_SERVE_PLAN | true | Plan-driven serving: settled reads and subscribe backlogs vend from object storage instead of proxying through the fleet; false proxies everything |
--storage-bucket | NOVAGATEWAY_STORAGE_BUCKET | — | Object-store bucket for raw plan vending; the Gateway fetches settled bytes under its own storage identity; empty proxies raw plans (presigned plans vend regardless) |
--storage-endpoint | NOVAGATEWAY_STORAGE_ENDPOINT | — | Custom S3 endpoint for --storage-bucket (e.g. MinIO); empty uses AWS |
--storage-region | NOVAGATEWAY_STORAGE_REGION | — | Region for --storage-bucket |
--storage-path-style | NOVAGATEWAY_STORAGE_PATH_STYLE | false | Path-style addressing for --storage-endpoint (MinIO and most non-AWS endpoints) |
--fetch-inflight | NOVAGATEWAY_FETCH_INFLIGHT | 64MiB | Concurrent vended-fetch byte budget: one pool over every response; full means responses wait |
--footer-cache-bytes | NOVAGATEWAY_FOOTER_CACHE_BYTES | 32MiB | Decoded-footer cache budget |
The two byte budgets take an integer with an optional KiB, MiB, or GiB suffix and must be positive. Which vending mode the fleet uses (presigned or raw) is the star's --readplan-vending; the Gateway needs storage credentials only for raw, and its storage identity is read-only: the Gateway never holds cluster membership, coordination access, or a peer credential.
Object cache
Vended fetches can route through the same object cache the fleet uses, so both warm the same instances. Every cache failure falls back to a direct fetch; a malformed instance list refuses to start.
| Flag | Env | Default | Meaning |
|---|---|---|---|
--object-cache-instances | NOVAGATEWAY_OBJECT_CACHE_INSTANCES | — | Comma-separated object-cache instance base URLs (http://host:port; cached traffic is plain HTTP); empty keeps all fetches direct; use the fleet's instance list |
--object-cache-load-factor | NOVAGATEWAY_OBJECT_CACHE_LOAD_FACTOR | 1.25 | Bounded-load ceiling over the mean in-flight claims per instance; a hot key spills its overflow to the next instance at the ceiling; must exceed 1 |
--object-cache-connect-budget | NOVAGATEWAY_OBJECT_CACHE_CONNECT_BUDGET | 1s | Dial budget for one cache attempt; a breach charges the instance and the fetch goes direct |
--object-cache-first-byte-budget | NOVAGATEWAY_OBJECT_CACHE_FIRST_BYTE_BUDGET | 5s | Request-to-first-byte budget for one cache attempt, sized above direct-S3 p99 so S3's own slowness is not misread as a sick instance; a breach charges the instance and the fetch goes direct |
Version
| Flag | Meaning |
|---|---|
--version, -v | Print the version |
How it is deployed
The Gateway is the trust boundary above the fleet: novad is never internet-exposed, and the Gateway is the only thing a tenant reaches. It dials the stars over gRPC through its cluster client (any address in --addr serves or redirects, and a stream's leader is remembered from the first redirect so steady-state requests take one hop) and forwards the caller's Authorization bearer verbatim on every call. The star verifies that token and enforces its scope; the Gateway stores nothing and holds no credential of its own beyond the optional read-only storage identity for raw vending.
Redirect targets are the stars' advertised addresses (novad --advertise), dialed as given, so each star's advertised address must resolve and route from the Gateway's network position. The --addr seed may be one collective DNS name: a headless service, an internal load balancer.
TLS is optional twice over. Give the process a certificate pair and it terminates TLS itself; leave both empty and it serves plaintext for a load balancer that terminates in front. GET /healthz answers 200 outside the whole middleware stack, so a target check never depends on the fleet it is deciding to route around. On SIGTERM or SIGINT the listener stops accepting and pending requests get 30 seconds to finish.
The process is stateless and disposable: nothing survives a restart but caches. Scale it horizontally as a bandwidth tier (every client byte crosses its network interface twice, in from the client and out to the fleet, or the reverse for reads it vends) and, on Kubernetes, give it a pool of its own rather than co-locating it with the stars. The Kubernetes guide covers the chart and the controller's Gateway resource; the compose stack runs one at localhost:8080.
What this binary does not bind
The Gateway library can verify tokens at the edge, derive the bucket from a virtual-hosted Host header, enforce per-token limits, and serve CORS, but novagateway exposes no flags for those today. The process forwards without verifying (the star stays authoritative), serves path-style URLs on any host, and serves no browser origins.
Source documents
cmd/novagateway/main.go: flag binding, TLS, the draininternal/gateway/gateway.go:Optionsand the handler stackdocs/design/022-gateway.md: the Gateway's design