Gateway Overview

gateway.svc is the platform’s API gateway: a TLS-terminating, multi-tenant edge proxy and static/SPA file server.

It is built on Traefik, the MIT-licensed edge router, which it embeds in-process as a fork. Traefik provides the router, the middleware chain, TLS termination and certificate issuance, the listeners and the load-balancer primitives. The gateway translates a kis.ai YAML model, domainmaps, backends, endpoints, routes and staticpaths, into router configuration, and adds tenant resolution, header and path transforms, auth enforcement and metrics around it.

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 CEPT)

A domainmap binds one or more Host values to a CEPT tuple (customer / environment / product / 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) → CEPT 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

Concern	Page
Routing recipes, SPA and static hosting, rewrites, TLS and ACME	Usage
Every key, with examples	Configuration
Listeners, TCP and UDP, per-listener timeouts and redirects	Entrypoints
Profiles, sticky sessions, mirrors, failover, adaptive weights	Load balancing
Reaching Traefik features the kis.ai model does not surface	Passthrough
Tenancy spoofing, forwarded headers, mTLS, the review checklist	Security
Bootstrap, hot reload, observability, failure modes	Operations