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
    - host

hosts:
  - id: "host-001"
    name: "localhost"
    domain: "localhost:8080"

targets:
  - id: "target-001"
    name: "httpbin"
    url: "https://httpbin.org"

apis:
  - id: "api-001"
    host: "host-001"
    target: "target-001"

routes:
  - id: "route-001"
    api: "api-001"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"
    security:
      auth:
        enabled: true
        type: "api_key"
        header: "X-Api-Key"
        path:
          include: []
          exclude: []
```

## 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 with structured JSON |
| `host` | Logs the host header for each request |

### Hosts

Virtual hosting configuration for domain-based routing.

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique host identifier (referenced by APIs) |
| `name` | string | Human-readable name |
| `domain` | string | Domain/host name to match |

### Targets

Backend service definitions referenced by APIs.

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique target identifier (referenced by APIs) |
| `name` | string | Human-readable name |
| `url` | string | Backend URL to proxy to |

### APIs

Links hosts to backend targets.

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique API identifier (referenced by routes) |
| `host` | string | Host ID to use |
| `target` | string | Target ID to proxy to |

### Routes

Route definitions with path patterns, prefix stripping, and authentication.

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique route identifier |
| `api` | string | API ID to use for this route |
| `path` | string | Chi route pattern (e.g., `/api/v1/*`) |
| `strip_prefix` | object | Prefix stripping configuration |
| `security` | object | Security policies (auth) |

#### 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 identifier (for documentation) |
| `header` | string | Header name to validate (e.g., `X-Api-Key`, `Authorization`) |
| `path` | object | Path-based filtering configuration |

##### Auth Path Filtering

| Field | Type | Description |
|-------|------|-------------|
| `include` | array | Paths that require auth (empty = all, if set only these) |
| `exclude` | array | Paths that skip auth (only used if include is empty) |

**Path Filtering Logic:**

| Include | Exclude | Behavior |
|---------|---------|----------|
| Empty | Empty | Auth required for ALL paths |
| Set | Empty | Auth required ONLY for paths matching include |
| Empty | Set | Auth required for ALL EXCEPT paths matching exclude |
| Set | Set | Include takes precedence (same as "Set, Empty") |

**Wildcards in Path Patterns:**
- `*` matches any path
- `/api/*` matches `/api/` and any subpath
- `/api/v1/public/test/*` matches the prefix and any subpath

## Example Configurations

### Public API (No Auth)

```yaml
routes:
  - id: "public-api"
    api: "api-001"
    path: "/public/*"
    strip_prefix:
      enabled: true
      prefix: "/public"
    security:
      auth:
        enabled: false
```

### Protected API (All Paths Require Auth)

```yaml
routes:
  - id: "protected-api"
    api: "api-001"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"
    security:
      auth:
        enabled: true
        header: "X-Api-Key"
        path:
          include: []
          exclude: []
```

### Public with Protected Sub-paths (Include)

```yaml
routes:
  - id: "mixed-api"
    api: "api-001"
    path: "/api/*"
    strip_prefix:
      enabled: true
      prefix: "/api"
    security:
      auth:
        enabled: true
        header: "X-Api-Key"
        path:
          include: ["/api/admin/*", "/api/users/*/profile"]
          exclude: []
```

In this example:
- `/api/admin/users` → Requires auth (matches include)
- `/api/users/123/profile` → Requires auth (matches include)
- `/api/public/data` → No auth (doesn't match include)
- `/api/health` → No auth (doesn't match include)

### Protected with Public Sub-paths (Exclude)

```yaml
routes:
  - id: "protected-with-public"
    api: "api-001"
    path: "/api/*"
    security:
      auth:
        enabled: true
        header: "Authorization"
        path:
          include: []
          exclude: ["/api/health", "/api/public/*", "/api/v1/public/test/*"]
```

In this example:
- `/api/health` → No auth (matches exclude)
- `/api/public/data` → No auth (matches exclude)
- `/api/v1/public/test/123` → No auth (matches exclude)
- `/api/users` → Requires auth (doesn't match exclude)
- `/api/admin/settings` → Requires auth (doesn't match exclude)

### Multiple Routes with Different Auth

```yaml
routes:
  - id: "public-route"
    api: "api-001"
    path: "/public/*"
    strip_prefix:
      enabled: true
      prefix: "/public"
    security:
      auth:
        enabled: false

  - id: "user-route"
    api: "api-001"
    path: "/users/*"
    strip_prefix:
      enabled: true
      prefix: "/users"
    security:
      auth:
        enabled: true
        header: "X-Api-Key"
        path:
          include: []
          exclude: ["/users/login", "/users/register"]

  - id: "admin-route"
    api: "api-001"
    path: "/admin/*"
    strip_prefix:
      enabled: true
      prefix: "/admin"
    security:
      auth:
        enabled: true
        header: "Authorization"
        path:
          include: []
          exclude: []
```

## Configuration Loading

The gateway loads configuration from a file path relative to the binary:

```go
cfg, err := config.NewFile("../gateway.yaml")
```

For Docker deployments, mount the config file:

```yaml
volumes:
  - ./gateway.yaml:/app/gateway.yaml:ro
```

## Chi Route Patterns

The gateway uses chi/v5 routing patterns. Common patterns:

| Pattern | Matches | Example |
|---------|---------|---------|
| `/api/*` | `/api/` and any subpath | `/api/users`, `/api/users/123` |
| `/api/v1/*` | `/api/v1/` and any subpath | `/api/v1/users` |
| `/users/{id}` | `/users/` with any value | `/users/123` |
| `/files/*` | `/files/` and any subpath | `/files/doc.pdf` |

Note: `/*` matches zero or more path segments.

## Debug Logging

To see detailed authentication decisions, enable DEBUG logging in `main.go`:

```go
masterlog.SetLevel(masterlog.LevelDebug)
```

This will output logs like:
```json
{
  "level": "debug",
  "msg": "AuthMiddleware: Checking if path requires auth",
  "path": "/api/v1/users",
  "requires_auth": true,
  "include": [],
  "exclude": ["/api/v1/public/*"]
}
```