init: Initial commit

2026-02-05 18:37:35 +01:00
commit 31f5b4081a
25 changed files with 1759 additions and 0 deletions
--- a/.docs/configuration.md
+++ b/.docs/configuration.md
@@ -0,0 +1,203 @@
+# Configuration
+
+The gateway is configured via a single YAML file (`gateway.yaml`). This document describes all available configuration options.
+
+## Configuration File Structure
+
+```yaml
+gateway:
+  host: "0.0.0.0"
+  port: 8080
+  features:
+    - request_id
+    - real_ip
+    - logger
+
+proxies:
+  - id: "proxy-id"
+    host: "example.com"
+    target: "http://backend:3000"
+
+apis:
+  - id: "api-id"
+    target: "https://api.example.com"
+
+routes:
+  - id: "route-id"
+    path: "/api/v1/*"
+    strip_prefix:
+      enabled: true
+      prefix: "/api/v1"
+    security:
+      auth:
+        enabled: true
+        type: "api_key"
+        header: "X-Api-Key"
+        path:
+          include: []
+          exclude: []
+      waf:
+        enabled: true
+        methods: ["GET", "POST"]
+```
+
+## Sections
+
+### Gateway
+
+Global gateway configuration.
+
+| Field | Type | Description | Default |
+|-------|------|-------------|---------|
+| `host` | string | Host address to bind to | Required |
+| `port` | integer | Port number | Required |
+| `features` | array | Global middleware features | Required |
+
+#### Features
+
+Available global features:
+
+| Feature | Description |
+|---------|-------------|
+| `request_id` | Adds unique request ID to each request |
+| `real_ip` | Determines real client IP from headers |
+| `logger` | Logs all HTTP requests |
+
+### Proxies
+
+Virtual hosting configuration for host-based routing.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique proxy identifier |
+| `host` | string | Domain/host name to match |
+| `target` | string | Backend URL to proxy to |
+
+### APIs
+
+Backend service definitions referenced by routes.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique API identifier (referenced by routes) |
+| `target` | string | Backend URL |
+
+### Routes
+
+Route definitions with security policies.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique route identifier (must match API ID) |
+| `path` | string | Chi route pattern (e.g., `/api/v1/*`) |
+| `strip_prefix` | object | Prefix stripping configuration |
+| `security` | object | Security policies (auth, WAF) |
+
+#### Strip Prefix
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `enabled` | boolean | Enable prefix stripping |
+| `prefix` | string | Prefix to remove from path |
+
+#### Security
+
+##### Authentication
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `enabled` | boolean | Enable authentication |
+| `type` | string | Auth type (`api_key`, `session`, etc.) |
+| `header` | string | Header name to validate |
+| `path` | object | Path-based filtering |
+
+##### Auth Path Filtering
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `include` | array | Paths that require auth (empty = all) |
+| `exclude` | array | Paths that skip auth |
+
+**Include/Exclude Logic:**
+- If `include` is set → only matching paths require auth
+- If `include` is empty → all paths require auth except `exclude`
+
+Wildcards (`*`) are supported in path patterns.
+
+##### WAF (Web Application Firewall)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `enabled` | boolean | Enable WAF |
+| `methods` | array | Allowed HTTP methods (`["*"]` for all) |
+
+## Example Configurations
+
+### Public API (No Auth)
+
+```yaml
+routes:
+  - id: "public-api"
+    path: "/public/*"
+    strip_prefix:
+      enabled: true
+      prefix: "/public"
+    security:
+      auth:
+        enabled: false
+      waf:
+        enabled: true
+        methods: ["GET", "POST"]
+```
+
+### Protected API with API Key
+
+```yaml
+routes:
+  - id: "protected-api"
+    path: "/api/v1/*"
+    strip_prefix:
+      enabled: true
+      prefix: "/api/v1"
+    security:
+      auth:
+        enabled: true
+        type: "api_key"
+        header: "X-Api-Key"
+      waf:
+        enabled: true
+        methods: ["*"]
+```
+
+### Mixed Auth (Path-based)
+
+```yaml
+routes:
+  - id: "mixed-api"
+    path: "/api/*"
+    security:
+      auth:
+        enabled: true
+        header: "Authorization"
+        path:
+          include: ["/api/admin/*", "/api/users/*/profile"]
+          exclude: ["/api/health", "/api/public/*"]
+      waf:
+        enabled: true
+        methods: ["*"]
+```
+
+## Configuration Loading
+
+The gateway loads configuration from a file path relative to the binary:
+
+```go
+cfg, err := config.NewFileConfig("../gateway.yaml")
+```
+
+For Docker deployments, mount the config file:
+
+```yaml
+volumes:
+  - ./gateway.yaml:/app/gateway.yaml:ro
+```