Init

2026-03-29 22:51:02 +07:00
commit 91f289c647
20 changed files with 2184 additions and 0 deletions
@@ -0,0 +1,9 @@
+.git
+.gitignore
+.cursor
+docs
+*.md
+!README.md
+.gitea
+docker-compose*.yml
+deploy
@@ -0,0 +1,61 @@
+name: ci
+
+on:
+  push:
+    branches: [main, master]
+    tags: ["v*"]
+  pull_request:
+
+env:
+  GO_VERSION: "1.22"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ env.GO_VERSION }}
+
+      - name: Test
+        run: go mod tidy && go test ./...
+
+  docker:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build image
+        run: docker build -t telemt-api:ci .
+
+      - name: Push to registry
+        if: github.event_name == 'push'
+        env:
+          REGISTRY_IMAGE: ${{ secrets.REGISTRY_IMAGE }}
+          REGISTRY_URL: ${{ secrets.REGISTRY_URL }}
+          REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
+          REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+        run: |
+          set -e
+          if [ -z "$REGISTRY_IMAGE" ] || [ -z "$REGISTRY_URL" ] || [ -z "$REGISTRY_USER" ] || [ -z "$REGISTRY_PASSWORD" ]; then
+            echo "Registry secrets not set (REGISTRY_IMAGE, REGISTRY_URL, REGISTRY_USER, REGISTRY_PASSWORD) — push skipped."
+            exit 0
+          fi
+          echo "$REGISTRY_PASSWORD" | docker login "$REGISTRY_URL" -u "$REGISTRY_USER" --password-stdin
+          docker tag telemt-api:ci "${REGISTRY_IMAGE}:sha-${GITHUB_SHA}"
+          docker push "${REGISTRY_IMAGE}:sha-${GITHUB_SHA}"
+          if [ "${GITHUB_REF}" = "refs/heads/main" ] || [ "${GITHUB_REF}" = "refs/heads/master" ]; then
+            docker tag telemt-api:ci "${REGISTRY_IMAGE}:latest"
+            docker push "${REGISTRY_IMAGE}:latest"
+          fi
+          if echo "${GITHUB_REF}" | grep -q '^refs/tags/'; then
+            TAG="${GITHUB_REF#refs/tags/}"
+            docker tag telemt-api:ci "${REGISTRY_IMAGE}:${TAG}"
+            docker push "${REGISTRY_IMAGE}:${TAG}"
+          fi
@@ -0,0 +1,7 @@
+/gateway
+/gateway.exe
+*.exe
+*.test
+.env
+.idea/
+.vscode/
@@ -0,0 +1,22 @@
+# syntax=docker/dockerfile:1
+
+FROM golang:1.22-bookworm AS build
+WORKDIR /src
+COPY go.mod ./
+COPY cmd/ ./cmd/
+COPY internal/ ./internal/
+RUN go mod tidy && go mod download
+RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o /out/gateway ./cmd/gateway
+
+# Alpine: non-root + wget for HEALTHCHECK (distroless has no shell/wget).
+FROM alpine:3.19
+RUN apk add --no-cache ca-certificates wget \
+    && addgroup -S gateway -g 65532 \
+    && adduser -S -u 65532 -G gateway gateway
+COPY --from=build /out/gateway /gateway
+USER gateway:gateway
+EXPOSE 8080
+ENV CONFIG_PATH=/etc/telemt-gateway/config.yaml
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD wget -q -O- http://127.0.0.1:8080/health >/dev/null || exit 1
+ENTRYPOINT ["/gateway"]
@@ -0,0 +1,68 @@
+package main
+
+import (
+	"context"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/telemt/telemt-api/internal/config"
+	"github.com/telemt/telemt-api/internal/server"
+)
+
+func main() {
+	log := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
+
+	cfgPath := os.Getenv("CONFIG_PATH")
+	if cfgPath == "" {
+		cfgPath = "/etc/telemt-gateway/config.yaml"
+	}
+	cfg, err := config.Load(cfgPath)
+	if err != nil {
+		log.Error("config load failed", "path", cfgPath, "err", err)
+		os.Exit(1)
+	}
+	parsed, err := cfg.Parse()
+	if err != nil {
+		log.Error("config parse failed", "err", err)
+		os.Exit(1)
+	}
+
+	gw, err := server.NewGateway(parsed, log)
+	if err != nil {
+		log.Error("gateway init failed", "err", err)
+		os.Exit(1)
+	}
+
+	srv := &http.Server{
+		Addr:              parsed.Config.Listen,
+		Handler:           gw.Handler(),
+		ReadHeaderTimeout: 10 * time.Second,
+		ReadTimeout:       0,
+		WriteTimeout:      0,
+		IdleTimeout:       120 * time.Second,
+	}
+
+	go func() {
+		log.Info("listening", "addr", parsed.Config.Listen)
+		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			log.Error("server error", "err", err)
+			os.Exit(1)
+		}
+	}()
+
+	sig := make(chan os.Signal, 1)
+	signal.Notify(sig, syscall.SIGINT, syscall.SIGTERM)
+	<-sig
+	log.Info("shutdown signal")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	_ = gw.Shutdown(ctx)
+	if err := srv.Shutdown(ctx); err != nil {
+		log.Error("shutdown error", "err", err)
+	}
+}
@@ -0,0 +1,9 @@
+# Пример для docker compose: без whitelist (только для локальной проверки).
+listen: ":8080"
+allow_all: true
+whitelist_cidrs: []
+trusted_proxies: []
+servers:
+  - alias: main_srv
+    # Telemt на хосте Windows/macOS/Linux:
+    base_url: http://host.docker.internal:9091
@@ -0,0 +1,31 @@
+# Telemt API gateway — copy to config.yaml and mount into the container.
+#
+# Semantics: client calls  GET /api/{alias}/health
+#            forwarded to   GET {base_url}/v1/health
+
+listen: ":8080"
+
+# If true, IP whitelist is not enforced (development only).
+allow_all: false
+
+# CIDR allowlist when allow_all is false. Empty list denies all clients.
+whitelist_cidrs:
+  - "127.0.0.1/32"
+  - "::1/128"
+  # Docker bridge (adjust to your environment):
+  # - "172.16.0.0/12"
+
+# When the direct TCP peer is in these CIDRs, client IP for whitelist is taken
+# from X-Forwarded-For (first hop) or X-Real-IP (e.g. behind nginx).
+# trusted_proxies:
+#   - "10.0.0.0/8"
+trusted_proxies: []
+
+servers:
+  - alias: main_srv
+    base_url: http://127.0.0.1:9091
+    # Default path prefix on upstream (Telemt Control API uses /v1).
+    path_prefix: /v1
+    # Optional: name of environment variable whose value is sent as Authorization
+    # to this upstream (exact string, Telemt auth_header semantics).
+    # authorization_env: TELEMT_API_AUTH
@@ -0,0 +1,10 @@
+services:
+  gateway:
+    build: .
+    image: telemt-api-gateway:local
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./config.compose.yaml:/etc/telemt-gateway/config.yaml:ro
+    environment:
+      CONFIG_PATH: /etc/telemt-gateway/config.yaml
@@ -0,0 +1,159 @@
+# Запуск Telemt API Gateway (Docker)
+
+Оглавление:
+
+1. [Назначение](#назначение)
+2. [Требования](#требования)
+3. [Минимальная конфигурация](#минимальная-конфигурация)
+4. [Переменные окружения](#переменные-окружения)
+5. [Сборка образа](#сборка-образа)
+6. [Запуск через Docker CLI](#запуск-через-docker-cli)
+7. [Запуск через Docker Compose](#запуск-через-docker-compose)
+8. [Проверка](#проверка)
+9. [Обновление и CI/CD](#обновление-и-cicd)
+10. [Устранение неполадок](#устранение-неполадок)
+
+## Назначение
+
+Шлюз — это один HTTP‑вход для нескольких экземпляров [Telemt Control API](API.md):
+
+- **Белый список IP** (CIDR): кто может обращаться к шлюзу (кроме `GET /health`, см. ниже).
+- **Маршрутизация по alias**: клиент вызывает `GET /api/{alias}/health`, шлюз проксирует на `{base_url}/v1/health` у соответствующего сервера.
+- **Метрики Prometheus**: `GET /metrics` (под тем же правилом whitelist, что и API).
+- **Доверенные прокси**: если прямой TCP‑peer входит в `trusted_proxies`, для проверки whitelist берётся первый адрес из `X-Forwarded-For` или `X-Real-IP`.
+
+Эндпоинты и контракт ответов бэкенда описаны в [API.md](API.md).
+
+## Требования
+
+- Установленные [Docker](https://docs.docker.com/get-docker/) и при необходимости [Docker Compose](https://docs.docker.com/compose/) v2.
+- Для локальной сборки из исходников: [Go 1.22+](https://go.dev/dl/) (опционально, если не используете только готовый образ из registry).
+
+## Минимальная конфигурация
+
+Скопируйте [config.example.yaml](../config.example.yaml) в свой `config.yaml` и отредактируйте.
+
+Минимальный рабочий фрагмент для **разработки** (без проверки IP):
+
+```yaml
+listen: ":8080"
+allow_all: true
+servers:
+  - alias: main_srv
+    base_url: http://127.0.0.1:9091
+```
+
+Минимальный фрагмент для **продакшена** (только перечисленные сети/хосты):
+
+```yaml
+listen: ":8080"
+allow_all: false
+whitelist_cidrs:
+  - "203.0.113.10/32"
+  - "10.0.0.0/8"
+servers:
+  - alias: main_srv
+    base_url: http://telemt-internal:9091
+```
+
+Правила:
+
+- При `allow_all: false` и **пустом** `whitelist_cidrs` доступ будет **закрыт для всех** (кроме `GET /health`).
+- `GET /health` на шлюзе **не** проверяется по whitelist — так проще настроить Docker `HEALTHCHECK` и оркестраторы.
+- Поле `path_prefix` по умолчанию равно `/v1` (префикс Telemt Control API).
+
+Опционально для бэкенда с включённым `auth_header` в Telemt задайте в конфиге имя переменной окружения, значение которой будет отправлено как заголовок `Authorization` на этот upstream:
+
+```yaml
+servers:
+  - alias: main_srv
+    base_url: http://telemt:9091
+    authorization_env: TELEMT_API_AUTH
+```
+
+Значение должно **точно** совпадать с настроенным в Telemt `auth_header` (см. [API.md](API.md)).
+
+## Переменные окружения
+
+| Переменная     | Описание |
+|----------------|----------|
+| `CONFIG_PATH`  | Путь к YAML внутри контейнера. По умолчанию: `/etc/telemt-gateway/config.yaml`. |
+| `TELEMT_API_AUTH` | Пример: секрет для `authorization_env` в конфиге (имя может быть любым). |
+
+## Сборка образа
+
+В каталоге репозитория:
+
+```powershell
+docker build -t telemt-api-gateway:local .
+```
+
+## Запуск через Docker CLI
+
+Пример для PowerShell (подставьте путь к своему `config.yaml`):
+
+```powershell
+docker run -d --name telemt-gateway `
+  -p 8080:8080 `
+  -v "C:\path\to\config.yaml:/etc/telemt-gateway/config.yaml:ro" `
+  -e CONFIG_PATH=/etc/telemt-gateway/config.yaml `
+  telemt-api-gateway:local
+```
+
+Проверка:
+
+```powershell
+Invoke-WebRequest -Uri http://127.0.0.1:8080/health -UseBasicParsing
+Invoke-WebRequest -Uri http://127.0.0.1:8080/api/main_srv/health -UseBasicParsing
+```
+
+Второй запрос проксируется на `{base_url}/v1/health` для alias `main_srv`.
+
+Остановка и удаление:
+
+```powershell
+docker stop telemt-gateway
+docker rm telemt-gateway
+```
+
+## Запуск через Docker Compose
+
+В репозитории есть [docker-compose.yml](../docker-compose.yml) и пример [config.compose.yaml](../config.compose.yaml) с `allow_all: true` и `base_url: http://host.docker.internal:9091` (Telemt на хосте).
+
+```powershell
+docker compose up -d --build
+docker compose logs -f gateway
+docker compose down
+```
+
+На старых Linux‑хостах, где нет `host.docker.internal`, замените `base_url` на IP хоста или добавьте сервис Telemt в тот же `docker-compose` и укажите его DNS‑имя.
+
+## Проверка
+
+| Сценарий | Ожидание |
+|----------|----------|
+| `GET /health` | `200`, JSON `{"status":"ok"}` |
+| Разрешённый IP, корректный alias | ответ бэкенда (например `200` для `/v1/health`) |
+| IP не в whitelist | `403`, JSON с `code: forbidden` |
+| Неизвестный alias | `404`, JSON с `code: not_found` |
+| Бэкенд недоступен | `502`, JSON с `code: bad_gateway` |
+| `GET /metrics` | текст метрик Prometheus (при разрешённом IP) |
+
+## Обновление и CI/CD
+
+- **Образ**: пересоберите тег или подтяните новый из registry, затем `docker compose up -d --build` или `docker stop` / `docker run ...` с тем же volume конфига.
+- **Конфиг**: отредактируйте файл на хосте и перезапустите контейнер (шлюз не перечитывает конфиг на лету).
+- **Gitea Actions**: workflow [.gitea/workflows/docker.yaml](../.gitea/workflows/docker.yaml) выполняет `go test` и собирает Docker‑образ. Для пуша в registry задайте secrets:
+
+  - `REGISTRY_IMAGE` — полное имя образа без тега, например `git.example.com/owner/telemt-api-gateway`
+  - `REGISTRY_URL` — хост registry, например `git.example.com`
+  - `REGISTRY_USER` / `REGISTRY_PASSWORD`
+
+  Если secrets не заданы, образ только собирается в runner без push.
+
+## Устранение неполадок
+
+- **`403 forbidden` с хоста при `allow_all: false`**: добавьте CIDR клиента в `whitelist_cidrs`. Запросы из контейнера к самому себе идут с `127.0.0.1` — при необходимости добавьте `127.0.0.1/32`.
+- **За reverse proxy**: укажите CIDR прокси в `trusted_proxies`, иначе whitelist видит IP прокси, а не клиента.
+- **`502 bad_gateway`**: проверьте `base_url`, DNS в Docker‑сети и то, что Telemt слушает API (`[server.api].enabled=true` и корректный `listen`).
+- **Сборка Go без Docker**: выполните `go mod tidy && go test ./...` в корне репозитория.
@@ -0,0 +1,8 @@
+module github.com/telemt/telemt-api
+
+go 1.22
+
+require (
+	github.com/prometheus/client_golang v1.20.5
+	gopkg.in/yaml.v3 v3.0.1
+)
@@ -0,0 +1,145 @@
+package config
+
+import (
+	"fmt"
+	"net/netip"
+	"net/url"
+	"os"
+	"regexp"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+var aliasRe = regexp.MustCompile(`^[a-z0-9][a-z0-9_-]*$`)
+
+// Config is the gateway YAML configuration.
+type Config struct {
+	Listen         string   `yaml:"listen"`
+	AllowAll       bool     `yaml:"allow_all"`
+	WhitelistCIDRs []string `yaml:"whitelist_cidrs"`
+	TrustedProxies []string `yaml:"trusted_proxies"`
+	Servers        []Server `yaml:"servers"`
+}
+
+// Server maps a URL alias to an upstream base URL.
+type Server struct {
+	Alias            string `yaml:"alias"`
+	BaseURL          string `yaml:"base_url"`
+	PathPrefix       string `yaml:"path_prefix"`
+	AuthorizationEnv string `yaml:"authorization_env"`
+}
+
+// Load reads and validates configuration from path.
+func Load(path string) (*Config, error) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("read config: %w", err)
+	}
+	var c Config
+	if err := yaml.Unmarshal(raw, &c); err != nil {
+		return nil, fmt.Errorf("parse yaml: %w", err)
+	}
+	if err := c.Validate(); err != nil {
+		return nil, err
+	}
+	return &c, nil
+}
+
+// Validate checks required fields and formats.
+func (c *Config) Validate() error {
+	if c.Listen == "" {
+		c.Listen = ":8080"
+	}
+	seen := make(map[string]struct{})
+	for i := range c.Servers {
+		s := &c.Servers[i]
+		if s.Alias == "" {
+			return fmt.Errorf("servers[%d]: alias is required", i)
+		}
+		if !aliasRe.MatchString(s.Alias) {
+			return fmt.Errorf("servers[%d]: alias %q must match %s", i, s.Alias, aliasRe.String())
+		}
+		if _, ok := seen[s.Alias]; ok {
+			return fmt.Errorf("duplicate alias %q", s.Alias)
+		}
+		seen[s.Alias] = struct{}{}
+		if s.BaseURL == "" {
+			return fmt.Errorf("servers[%d]: base_url is required", i)
+		}
+		u, err := url.Parse(s.BaseURL)
+		if err != nil || u.Scheme == "" || u.Host == "" {
+			return fmt.Errorf("servers[%d]: invalid base_url %q", i, s.BaseURL)
+		}
+		if s.PathPrefix == "" {
+			s.PathPrefix = "/v1"
+		}
+		s.PathPrefix = strings.TrimSuffix(s.PathPrefix, "/")
+		if !strings.HasPrefix(s.PathPrefix, "/") {
+			s.PathPrefix = "/" + s.PathPrefix
+		}
+	}
+	if len(c.Servers) == 0 {
+		return fmt.Errorf("at least one server entry is required")
+	}
+	for i, s := range c.WhitelistCIDRs {
+		if _, err := netip.ParsePrefix(strings.TrimSpace(s)); err != nil {
+			return fmt.Errorf("whitelist_cidrs[%d]: %w", i, err)
+		}
+	}
+	for i, s := range c.TrustedProxies {
+		if _, err := netip.ParsePrefix(strings.TrimSpace(s)); err != nil {
+			return fmt.Errorf("trusted_proxies[%d]: %w", i, err)
+		}
+	}
+	return nil
+}
+
+// Parsed holds compiled CIDR lists and server map.
+type Parsed struct {
+	Config           *Config
+	Whitelist        []netip.Prefix
+	Trusted          []netip.Prefix
+	ByAlias          map[string]*Server
+	AuthByAlias      map[string]string // non-empty Authorization value per alias
+}
+
+// Parse compiles CIDRs and resolves authorization from environment.
+func (c *Config) Parse() (*Parsed, error) {
+	var wl []netip.Prefix
+	for _, s := range c.WhitelistCIDRs {
+		p, err := netip.ParsePrefix(strings.TrimSpace(s))
+		if err != nil {
+			return nil, err
+		}
+		wl = append(wl, p)
+	}
+	var tr []netip.Prefix
+	for _, s := range c.TrustedProxies {
+		p, err := netip.ParsePrefix(strings.TrimSpace(s))
+		if err != nil {
+			return nil, err
+		}
+		tr = append(tr, p)
+	}
+	by := make(map[string]*Server, len(c.Servers))
+	auth := make(map[string]string)
+	for i := range c.Servers {
+		s := &c.Servers[i]
+		by[s.Alias] = s
+		if s.AuthorizationEnv != "" {
+			v := os.Getenv(s.AuthorizationEnv)
+			if v == "" {
+				return nil, fmt.Errorf("server %q: env %q is empty or unset", s.Alias, s.AuthorizationEnv)
+			}
+			auth[s.Alias] = v
+		}
+	}
+	return &Parsed{
+		Config:      c,
+		Whitelist:   wl,
+		Trusted:     tr,
+		ByAlias:     by,
+		AuthByAlias: auth,
+	}, nil
+}
@@ -0,0 +1,44 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestLoadExample(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "cfg.yaml")
+	if err := os.WriteFile(p, []byte(`
+listen: ":0"
+allow_all: true
+servers:
+  - alias: main_srv
+    base_url: http://127.0.0.1:9091
+`), 0644); err != nil {
+		t.Fatal(err)
+	}
+	c, err := Load(p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c.Listen != ":0" {
+		t.Fatalf("listen: %q", c.Listen)
+	}
+	_, err = c.Parse()
+	if err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestValidateDuplicateAlias(t *testing.T) {
+	c := &Config{
+		Servers: []Server{
+			{Alias: "a", BaseURL: "http://x:1"},
+			{Alias: "a", BaseURL: "http://y:2"},
+		},
+	}
+	if err := c.Validate(); err == nil {
+		t.Fatal("expected error")
+	}
+}
@@ -0,0 +1,33 @@
+package proxy
+
+import (
+	"net/http"
+	"net/http/httputil"
+	"net/url"
+	"strings"
+)
+
+// NewReverseProxy builds a reverse proxy to target base URL with path rewriting:
+// stripPrefix (/api/{alias}) + pathPrefix (/v1) + remainder.
+func NewReverseProxy(target *url.URL, stripPrefix, pathPrefix string, setAuth string) *httputil.ReverseProxy {
+	proxy := httputil.NewSingleHostReverseProxy(target)
+	orig := proxy.Director
+	proxy.Director = func(req *http.Request) {
+		orig(req)
+		p := req.URL.Path
+		if strings.HasPrefix(p, stripPrefix) {
+			rest := strings.TrimPrefix(p, stripPrefix)
+			rest = strings.TrimPrefix(rest, "/")
+			if rest == "" {
+				req.URL.Path = pathPrefix
+			} else {
+				req.URL.Path = pathPrefix + "/" + rest
+			}
+			req.URL.RawPath = ""
+		}
+		if setAuth != "" {
+			req.Header.Set("Authorization", setAuth)
+		}
+	}
+	return proxy
+}
@@ -0,0 +1,26 @@
+package proxy
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+)
+
+func TestReverseProxyPathRewrite(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/health" {
+			t.Fatalf("path %q", r.URL.Path)
+		}
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+	up, _ := url.Parse(srv.URL)
+	rp := NewReverseProxy(up, "/api/main_srv", "/v1", "")
+	req := httptest.NewRequest(http.MethodGet, "/api/main_srv/health", nil)
+	rec := httptest.NewRecorder()
+	rp.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status %d", rec.Code)
+	}
+}
@@ -0,0 +1,65 @@
+package server
+
+import (
+	"net"
+	"net/http"
+	"net/netip"
+	"strings"
+)
+
+// ClientIP returns the client address for access control, using X-Forwarded-For /
+// X-Real-IP only when the direct peer is in trusted CIDRs.
+func ClientIP(r *http.Request, trusted []netip.Prefix) netip.Addr {
+	host, _, err := net.SplitHostPort(r.RemoteAddr)
+	if err != nil {
+		host = r.RemoteAddr
+	}
+	peer, err := netip.ParseAddr(host)
+	if err != nil {
+		return netip.Addr{}
+	}
+	if !containsIP(trusted, peer) {
+		return peer
+	}
+	if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
+		parts := strings.Split(xff, ",")
+		for _, p := range parts {
+			p = strings.TrimSpace(p)
+			if p == "" {
+				continue
+			}
+			if a, err := netip.ParseAddr(p); err == nil {
+				return a
+			}
+		}
+	}
+	if xr := strings.TrimSpace(r.Header.Get("X-Real-IP")); xr != "" {
+		if a, err := netip.ParseAddr(xr); err == nil {
+			return a
+		}
+	}
+	return peer
+}
+
+func containsIP(prefixes []netip.Prefix, addr netip.Addr) bool {
+	for _, p := range prefixes {
+		if p.Contains(addr) {
+			return true
+		}
+	}
+	return false
+}
+
+// Allowed reports whether addr matches whitelist rules.
+func Allowed(addr netip.Addr, allowAll bool, whitelist []netip.Prefix) bool {
+	if !addr.IsValid() {
+		return false
+	}
+	if allowAll {
+		return true
+	}
+	if len(whitelist) == 0 {
+		return false
+	}
+	return containsIP(whitelist, addr)
+}
@@ -0,0 +1,34 @@
+package server
+
+import (
+	"net/http"
+	"net/netip"
+	"testing"
+)
+
+func TestAllowed(t *testing.T) {
+	p, _ := netip.ParsePrefix("127.0.0.1/32")
+	a := netip.MustParseAddr("127.0.0.1")
+	if !Allowed(a, false, []netip.Prefix{p}) {
+		t.Fatal("expected allowed")
+	}
+	if Allowed(a, false, nil) {
+		t.Fatal("empty whitelist should deny")
+	}
+	if !Allowed(a, true, nil) {
+		t.Fatal("allow_all")
+	}
+}
+
+func TestClientIPTrustedXFF(t *testing.T) {
+	trusted, _ := netip.ParsePrefix("10.0.0.1/32")
+	r := &http.Request{
+		Header: http.Header{},
+		RemoteAddr: "10.0.0.1:12345",
+	}
+	r.Header.Set("X-Forwarded-For", "203.0.113.5, 10.0.0.1")
+	ip := ClientIP(r, []netip.Prefix{trusted})
+	if ip.String() != "203.0.113.5" {
+		t.Fatalf("got %v", ip)
+	}
+}
@@ -0,0 +1,221 @@
+package server
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"net"
+	"net/http"
+	"net/http/httputil"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+
+	"github.com/telemt/telemt-api/internal/config"
+	"github.com/telemt/telemt-api/internal/proxy"
+)
+
+// Gateway serves health, metrics, and proxied API routes.
+type Gateway struct {
+	parsed        *config.Parsed
+	proxies       map[string]*httputil.ReverseProxy
+	log           *slog.Logger
+	transport     *http.Transport
+	promHandler   http.Handler
+}
+
+// NewGateway builds handlers and reverse proxies from parsed config.
+func NewGateway(p *config.Parsed, log *slog.Logger) (*Gateway, error) {
+	t := &http.Transport{
+		Proxy:                 http.ProxyFromEnvironment,
+		MaxIdleConns:          64,
+		IdleConnTimeout:       90 * time.Second,
+		TLSHandshakeTimeout:   10 * time.Second,
+		ExpectContinueTimeout: 1 * time.Second,
+		DialContext:           (&net.Dialer{Timeout: 5 * time.Second, KeepAlive: 30 * time.Second}).DialContext,
+		ResponseHeaderTimeout: 120 * time.Second,
+	}
+	g := &Gateway{
+		parsed:      p,
+		proxies:     make(map[string]*httputil.ReverseProxy),
+		log:         log,
+		transport:   t,
+		promHandler: promhttp.Handler(),
+	}
+	for i := range p.Config.Servers {
+		s := &p.Config.Servers[i]
+		u, err := url.Parse(s.BaseURL)
+		if err != nil {
+			return nil, err
+		}
+		auth := p.AuthByAlias[s.Alias]
+		strip := "/api/" + s.Alias
+		rp := proxy.NewReverseProxy(u, strip, s.PathPrefix, auth)
+		rp.Transport = t
+		rp.ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error) {
+			log.Error("upstream error", "alias", s.Alias, "err", err)
+			w.Header().Set("Content-Type", "application/json; charset=utf-8")
+			w.WriteHeader(http.StatusBadGateway)
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"ok":    false,
+				"error": map[string]string{"code": "bad_gateway", "message": "upstream unreachable"},
+			})
+		}
+		g.proxies[s.Alias] = rp
+	}
+	return g, nil
+}
+
+// Handler returns the root HTTP handler with middleware.
+func (g *Gateway) Handler() http.Handler {
+	var h http.Handler = http.HandlerFunc(g.serve)
+	h = g.withWhitelist(h)
+	h = g.withAccessLog(h)
+	h = g.withMetrics(h)
+	return h
+}
+
+func (g *Gateway) withWhitelist(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/health" {
+			next.ServeHTTP(w, r)
+			return
+		}
+		ip := ClientIP(r, g.parsed.Trusted)
+		if !Allowed(ip, g.parsed.Config.AllowAll, g.parsed.Whitelist) {
+			w.Header().Set("Content-Type", "application/json; charset=utf-8")
+			w.WriteHeader(http.StatusForbidden)
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"ok":    false,
+				"error": map[string]string{"code": "forbidden", "message": "source address not allowed"},
+			})
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+func (g *Gateway) withAccessLog(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		rid := r.Header.Get("X-Request-Id")
+		if rid == "" {
+			rid = randomID()
+			r.Header.Set("X-Request-Id", rid)
+		}
+		w.Header().Set("X-Request-Id", rid)
+		start := time.Now()
+		lw := &statusWriter{ResponseWriter: w, status: http.StatusOK}
+		next.ServeHTTP(lw, r)
+		g.log.Info("request",
+			"request_id", rid,
+			"method", r.Method,
+			"path", r.URL.Path,
+			"status", lw.status,
+			"duration_ms", time.Since(start).Milliseconds(),
+			"remote", r.RemoteAddr,
+		)
+	})
+}
+
+func (g *Gateway) withMetrics(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/health" {
+			next.ServeHTTP(w, r)
+			return
+		}
+		httpInFlight.Inc()
+		start := time.Now()
+		alias := routeAlias(r.URL.Path)
+		lw := &statusWriter{ResponseWriter: w, status: http.StatusOK}
+		defer observeRequest(r.Method, alias, lw.status, start)
+		next.ServeHTTP(lw, r)
+	})
+}
+
+func routeAlias(path string) string {
+	const pfx = "/api/"
+	if !strings.HasPrefix(path, pfx) {
+		if path == "/metrics" {
+			return "metrics"
+		}
+		return "_"
+	}
+	rest := strings.TrimPrefix(path, pfx)
+	if rest == "" {
+		return "_"
+	}
+	i := strings.IndexByte(rest, '/')
+	if i < 0 {
+		return rest
+	}
+	return rest[:i]
+}
+
+func (g *Gateway) serve(w http.ResponseWriter, r *http.Request) {
+	switch r.URL.Path {
+	case "/health":
+		if r.Method != http.MethodGet {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json; charset=utf-8")
+		_ = json.NewEncoder(w).Encode(map[string]any{"status": "ok"})
+		return
+	case "/metrics":
+		if r.Method != http.MethodGet {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		g.promHandler.ServeHTTP(w, r)
+		return
+	}
+	const prefix = "/api/"
+	if !strings.HasPrefix(r.URL.Path, prefix) {
+		http.NotFound(w, r)
+		return
+	}
+	trim := strings.TrimPrefix(r.URL.Path, prefix)
+	if trim == "" {
+		http.NotFound(w, r)
+		return
+	}
+	var alias string
+	if i := strings.IndexByte(trim, '/'); i >= 0 {
+		alias = trim[:i]
+	} else {
+		alias = trim
+	}
+	if alias == "" {
+		http.NotFound(w, r)
+		return
+	}
+	rp, ok := g.proxies[alias]
+	if !ok {
+		w.Header().Set("Content-Type", "application/json; charset=utf-8")
+		w.WriteHeader(http.StatusNotFound)
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"ok":    false,
+			"error": map[string]string{"code": "not_found", "message": "unknown alias"},
+		})
+		return
+	}
+	rp.ServeHTTP(w, r)
+}
+
+type statusWriter struct {
+	http.ResponseWriter
+	status int
+}
+
+func (s *statusWriter) WriteHeader(code int) {
+	s.status = code
+	s.ResponseWriter.WriteHeader(code)
+}
+
+// Shutdown idle connections on the shared transport.
+func (g *Gateway) Shutdown(ctx context.Context) error {
+	g.transport.CloseIdleConnections()
+	return nil
+}
@@ -0,0 +1,31 @@
+package server
+
+import (
+	"strconv"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promauto"
+)
+
+var (
+	httpInFlight = promauto.NewGauge(prometheus.GaugeOpts{
+		Name: "telemt_gateway_http_in_flight",
+		Help: "Current requests being served.",
+	})
+	httpRequests = promauto.NewCounterVec(prometheus.CounterOpts{
+		Name: "telemt_gateway_http_requests_total",
+		Help: "HTTP requests by status, method, alias.",
+	}, []string{"code", "method", "alias"})
+	httpDuration = promauto.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "telemt_gateway_http_request_duration_seconds",
+		Help:    "Request duration in seconds.",
+		Buckets: prometheus.DefBuckets,
+	}, []string{"method", "alias"})
+)
+
+func observeRequest(method, alias string, status int, started time.Time) {
+	httpInFlight.Dec()
+	httpRequests.WithLabelValues(strconv.Itoa(status), method, alias).Inc()
+	httpDuration.WithLabelValues(method, alias).Observe(time.Since(started).Seconds())
+}
@@ -0,0 +1,14 @@
+package server
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+)
+
+func randomID() string {
+	var b [16]byte
+	if _, err := rand.Read(b[:]); err != nil {
+		return "unknown"
+	}
+	return hex.EncodeToString(b[:])
+}