Gateway Overview

gateway.svc is the platform’s API gateway: a TLS-terminating, multi-tenant edge proxy and static/SPA file server. It embeds a router engine in-process (a Traefik v3 fork) and translates a kis.ai YAML model — domainmaps, backends, endpoints, routes, staticpaths — into router configuration, adding tenant resolution, header/path transforms, auth enforcement, and metrics.

Request path

client
  → entrypoint listener        (websecure :443 / websecureinternal, or custom)
  → route selection            Host + routing-domain header + path prefix
  → middleware chain           CORS → metrics → [rewrite | timeout | auth | tenant-mapper | tracker] → header transforms
  → backend load balancer      (mTLS to backends when zerotrust: true)
  → backend service            — or a gateway-spawned static/SPA file server

Tenancy resolution (host-based CPET)

A domainmap binds one or more Host values to a CPET tuple (customer / product / environment / tenant):

1. The gateway stamps an internal routing-domain header from the request’s own Host. X-Forwarded-Host is honored only when the peer IP is listed in the entrypoint’s trustedips — otherwise all X-Forwarded-* headers are stripped, so clients cannot spoof routing.
2. The tenant-mapper middleware resolves that domain and injects X-Customer, X-Product, X-Env, X-Tenant for the backend. An unmapped domain → 400.
3. X-Target-Tenant (cross-tenant operator access, stamped with X-SuperAdmin: true) is honored only on domainmaps explicitly marked superadmin.

Auth enforcement

The optional kisai-auth endpoint middleware verifies Bearer JWTs locally against the configured jwt_public_key — the IAM service is the token issuer and login-redirect target, not a per-request dependency. Unauthenticated requests get a redirect to loginurl if configured, else 403. publicPaths regexes exempt open paths.

The five routing nouns

Entity	Meaning
domainmaps	Host(s) → CPET tuple; optional per-map CORS config, superadmin flag
backends	Named pool of upstream URLs, optionally bound to a load-balancing profile
endpoints	Path prefix → backend + middleware chain + rewrite/redirect/header transforms
routes	domainmap × entrypoint × endpoints/staticpaths, plus TLS settings
staticpaths	A folder served by a spawned file server — static (with 404 page) or spa (index fallback)

Two configuration planes

Plane	Content	Where it lives
Boot	listeners, TLS posture, log, identity, pointer to routing config	the -f bootstrap file (default .gateway.yaml)
Routing	the five nouns above + LB profiles + raw passthrough	inline in the bootstrap, or a local directory (config.router.dir), or served remotely by config.svc with SSE hot-reload

How it learns about backends

1. Static urls lists on backends.
2. Remote routing config from config.svc (hot-reloaded over SSE).
3. The service-discovery watcher — when a discovery client is configured, the gateway polls it (default every 5s) for the services referenced by its routing config and rewrites backend server lists live.

Listeners and ports

Listener	Purpose
websecure (port)	Public traffic; per-route TLS (ACME certresolver, custom tlsoptions, or passthrough)
websecureinternal (internal.port)	Mesh traffic; requires client certs when zerotrust: true
custom entrypoints:	Arbitrary extra http/tcp/udp listeners, each with its own timeouts, trusted IPs, and redirects
metrics (127.0.0.1:8088)	Prometheus /metrics + pprof — never exposed on the data plane

Continue with:

• Configuration — every key, with examples
• Operations — bootstrap, hot reload, TLS, failure modes