gal-gateway 1.2.0

Gateway Abstraction Layer - Provider-agnostic API Gateway configuration system

Gateway Abstraction Layer (GAL) - Python Edition

Gateway-Abstraktionsschicht - Provider-agnostisches API-Gateway-Konfigurations- und Transformationssystem in Python.

Definiere deine API-Gateway-Konfiguration einmal und deploye sie auf Envoy, Kong, APISIX, Traefik, Nginx, HAProxy oder anderen Gateways - ohne Vendor Lock-in.

Features

• ✅ Einheitliche YAML-Konfiguration für mehrere API-Gateway-Provider
• ✅ Unterstützung für 6 Provider: Envoy, Kong, APISIX, Traefik, Nginx, HAProxy
• ✅ Automatische Payload-Transformationsgenerierung
• ✅ REST- und gRPC-Service-Unterstützung (3 gRPC + 2 REST Services)
• ✅ Default-Wert-Injektion
• ✅ Berechnete Felder (UUIDs, Zeitstempel)
• ✅ Feldvalidierung
• ✅ Strukturiertes Logging mit konfigurierbaren Log-Levels
• ✅ Reines Python - kein Go erforderlich!
• ✅ CI/CD Ready - GitHub Actions Workflows integriert
• ✅ Umfassende Tests - 364 Tests mit 89% Coverage
• 🆕 Traffic Management - Rate Limiting, Circuit Breaker, Health Checks & Load Balancing
• 🆕 Security - Authentication (Basic, API Key, JWT), Header Manipulation, CORS
• 🆕 WebSocket Support - Real-time bidirectional communication (all 6 providers)
• 🆕 Body Transformation - Request/Response body manipulation with dynamic fields
• 🆕 Timeout & Retry - Connection/read/send timeouts, automatic retries with exponential backoff
• 🆕 Logging & Observability - Structured logging (JSON), Prometheus/OpenTelemetry metrics, log sampling, custom fields

Installation

🐳 Docker (Empfohlen)

Von GitHub Container Registry (Fertig)

# Latest Version ziehen
docker pull ghcr.io/pt9912/x-gal:latest

# Direkt verwenden
docker run --rm ghcr.io/pt9912/x-gal:latest list-providers

# Mit Volume für Ausgabe
docker run --rm -v $(pwd)/generated:/app/generated \
  ghcr.io/pt9912/x-gal:latest \
  generate --config examples/gateway-config.yaml --provider envoy --output generated/envoy.yaml

# Spezifische Version
docker pull ghcr.io/pt9912/x-gal:v1.0.0

Lokal bauen

# Image bauen
docker build -t gal:latest .

# Verwenden
docker run --rm gal:latest list-providers

🐍 Python (Lokal)

# Repository klonen
git clone https://github.com/pt9912/x-gal.git
cd x-gal

# Virtuelle Umgebung erstellen
python3 -m venv venv
source venv/bin/activate  # Unter Windows: venv\Scripts\activate

# Abhängigkeiten installieren
pip install -e .         # Runtime dependencies
pip install -e .[dev]    # Mit Dev-Tools (pytest, black, flake8, isort)

# CLI ausführbar machen
chmod +x gal-cli.py

📦 PyPI (Empfohlen für Produktion)

# Stabile Version von PyPI installieren
pip install gal-gateway

# CLI verwenden
gal --help
gal --version

# Mit Development Tools
pip install gal-gateway[dev]

# Spezifische Version
pip install gal-gateway==1.0.0

# Pre-Release von TestPyPI (optional)
pip install --index-url https://test.pypi.org/simple/ \
            --extra-index-url https://pypi.org/simple/ \
            gal-gateway

PyPI Links:

• Stable Releases: https://pypi.org/project/gal-gateway/
• Pre-Releases (TestPyPI): https://test.pypi.org/project/gal-gateway/
• Dokumentation: PyPI Publishing Guide

Schnellstart

🐳 Mit Docker

# Alle Provider generieren
docker run --rm -v $(pwd)/generated:/app/generated gal:latest \
  generate-all --config examples/gateway-config.yaml --output-dir generated

# Einzelnen Provider generieren
docker run --rm -v $(pwd)/generated:/app/generated gal:latest \
  generate --config examples/gateway-config.yaml --provider kong --output generated/kong.yaml

# Mit Docker Compose
docker-compose up gal-generate  # Generiert Envoy-Konfiguration
PROVIDER=kong docker-compose up gal-generate  # Generiert Kong-Konfiguration

🐍 Mit Python

# Envoy-Konfiguration generieren
python gal-cli.py generate --config examples/gateway-config.yaml --provider envoy --output generated/envoy.yaml

# Oder das Convenience-Script verwenden
./generate-envoy.sh

# Für alle Provider generieren
python gal-cli.py generate-all --config examples/gateway-config.yaml

Konfigurationsbeispiel

Das Beispiel enthält:

• 3 gRPC Services: user_service, order_service, notification_service
• 2 REST Services: product_service, payment_service

Jeder mit Transformationsregeln für:

• Standard-Werte
• Berechnete Felder (UUID, Zeitstempel-Generierung)
• Feldvalidierung

Unterstützte Provider

Provider	Status	Features
Envoy	✅	Vollständige Unterstützung mit Wasm/Lua
Kong	✅	Lua Plugins
APISIX	✅	Lua Scripts
Traefik	✅	Middleware
Nginx	✅	Open Source (ngx_http modules)
HAProxy	✅	Advanced Load Balancing & ACLs

Projektstruktur

x-gal/
├── gal/
│   ├── __init__.py
│   ├── config.py              # Konfigurationsmodelle
│   ├── manager.py             # Haupt-Orchestrator
│   ├── provider.py            # Provider-Interface
│   ├── providers/
│   │   ├── __init__.py
│   │   ├── envoy.py
│   │   ├── kong.py
│   │   ├── apisix.py
│   │   ├── traefik.py
│   │   ├── nginx.py
│   │   └── haproxy.py
│   └── transformation/
│       ├── __init__.py
│       ├── engine.py
│       └── generators.py
├── gal-cli.py                 # CLI-Tool
├── examples/
│   └── gateway-config.yaml
├── tests/
└── docs/

CLI-Befehle

# Konfiguration generieren
python gal-cli.py generate --config CONFIG --provider PROVIDER --output FILE

# Konfiguration validieren
python gal-cli.py validate --config CONFIG

# Für alle Provider generieren
python gal-cli.py generate-all --config CONFIG --output-dir OUTPUT

# Konfigurationsinformationen anzeigen
python gal-cli.py info --config CONFIG

# Verfügbare Provider auflisten
python gal-cli.py list-providers

# Mit Logging (für Debugging)
python gal-cli.py --log-level debug generate --config CONFIG --provider envoy

# Log Levels: debug, info, warning (default), error
python gal-cli.py --log-level info generate-all --config CONFIG

Logging-Optionen

GAL unterstützt strukturiertes Logging mit verschiedenen Verbosity-Levels:

• --log-level debug: Detaillierte Debug-Informationen (Parsing, Validierung, Generation)
• --log-level info: Haupt-Operationen und Zusammenfassungen
• --log-level warning: Warnungen und nicht-kritische Probleme (Standard)
• --log-level error: Nur kritische Fehler

Beispiel:

# Debugging aktivieren
docker run --rm ghcr.io/pt9912/x-gal:latest \
  --log-level debug \
  generate --config examples/gateway-config.yaml --provider envoy

🐳 Docker Deployment

Image bauen

# Standard-Build
docker build -t gal:latest .

# Mit spezifischer Version
docker build -t gal:1.0.0 .

Docker Compose Services

# Standard CLI (interaktiv)
docker-compose up gal

# Development mit Live-Reload
docker-compose --profile dev up gal-dev

# Konfiguration generieren
docker-compose --profile generate up gal-generate

# Konfiguration validieren
CONFIG_FILE=examples/gateway-config.yaml docker-compose --profile validate up gal-validate

Environment Variables

• PROVIDER: Gateway-Provider (envoy, kong, apisix, traefik, nginx, haproxy)
• CONFIG_FILE: Pfad zur Konfigurationsdatei
• OUTPUT_DIR: Ausgabeverzeichnis für generierte Configs

Dokumentation

Grundlagen

• Schnellstart-Anleitung
• Architektur-Übersicht
• Provider-Details
• Transformations-Anleitung
• Docker-Anleitung

Feature-Guides

• Rate Limiting - API-Schutz vor Überlastung
• Authentication - Basic, API Key, JWT
• Headers - Request/Response Header Manipulation
• CORS - Cross-Origin Resource Sharing
• Circuit Breaker - Fehlertoleranz & Resilienz
• Health Checks & Load Balancing - Hochverfügbarkeit
• WebSocket Support - Real-time bidirectional communication
• Body Transformation - Request/Response body manipulation (add/remove/rename fields, PII filtering)
• Timeout & Retry Policies - Connection/read/send timeouts, automatic retries with exponential backoff
• Logging & Observability - Structured logging (JSON/text), Prometheus/OpenTelemetry metrics, log sampling, custom fields

Provider-Guides

• Envoy Provider - CNCF cloud-native proxy, Filter-Architektur, xDS API
• Kong Provider - Plugin-Ökosystem, Admin API, DB-less mode
• APISIX Provider - Ultra-high performance, etcd integration, Lua scripting
• Traefik Provider - Auto-discovery, Let's Encrypt, Cloud-native
• Nginx Provider - Open Source, ngx_http modules, OpenResty
• HAProxy Provider - Advanced Load Balancing, ACLs, High performance

Roadmap & Changelog

• Roadmap - Geplante Features und Releases
• v1.1.0 Plan - v1.1.0 Implementierungsplan (100% abgeschlossen)
• v1.2.0 Plan - v1.2.0 Implementierungsplan (✅ 100% abgeschlossen - 6/6 Features)
• Changelog

Testing & Development

Tests ausführen

# Alle Tests
pytest

# Mit Coverage
pytest --cov=gal --cov-report=term-missing

# Spezifische Test-Datei
pytest tests/test_providers.py -v

# Mit Logging
pytest -v --log-cli-level=DEBUG

Test-Suite

• 364 Tests mit 89% Code Coverage
• Unit Tests für alle Module
• Provider-spezifische Tests (Envoy, Kong, APISIX, Traefik, Nginx, HAProxy)
• CLI Tests mit Click CliRunner
• End-to-End Workflow Tests
• Deployment Tests (mit Mocking)
• Real-World Szenario Tests
• Feature Tests (Rate Limiting, Auth, Headers, CORS, Circuit Breaker, Health Checks, WebSocket, Body Transformation, Timeout & Retry, Logging & Observability)

Code Quality

# Formatting mit black
black .

# Import sorting mit isort
isort .

# Linting mit flake8
flake8 .

CI/CD

Das Projekt verwendet GitHub Actions für kontinuierliche Integration:

Workflows

1. Tests (.github/workflows/test.yml)

   • Läuft auf Python 3.10, 3.11, 3.12
   • Automatische Tests bei jedem Push/PR
   • Code Quality Checks
   • Coverage Reporting

2. Docker Build (.github/workflows/docker-build.yml)

   • Automatischer Build und Push zu ghcr.io
   • Multi-Platform Support (amd64, arm64)
   • Intelligentes Tagging (semver, branch, sha)

3. Release (.github/workflows/release.yml)

   • Automatische Releases bei Git Tags
   • Changelog-Generierung
   • Package Building
   • GitHub Release Creation

Release erstellen

# Version Tag erstellen
git tag v1.0.1
git push origin v1.0.1

# GitHub Actions erstellt automatisch:
# - GitHub Release mit Changelog
# - Docker Images auf ghcr.io
# - Distribution Packages

Contributing

Beiträge sind willkommen! Bitte:

1. Fork das Repository
2. Erstelle einen Feature Branch (git checkout -b feature/amazing-feature)
3. Committe deine Änderungen (git commit -m 'Add amazing feature')
4. Pushe zum Branch (git push origin feature/amazing-feature)
5. Öffne einen Pull Request

Richtlinien

• Schreibe Tests für neue Features
• Befolge den bestehenden Code-Stil
• Aktualisiere die Dokumentation
• Füge Eintrag im CHANGELOG.md hinzu

Lizenz

MIT - siehe LICENSE für Details.

Links

• GitHub Repository
• GitHub Container Registry
• Issues
• Releases

Autor

Dietmar Burkard - Gateway Abstraction Layer

---

⭐ Wenn dir dieses Projekt gefällt, gib ihm einen Stern auf GitHub!