api-gateway/.docs/configuration.md

# 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
```