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

## 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 and prefix stripping.

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

#### Strip Prefix

| Field | Type | Description |
|-------|------|-------------|
| `enabled` | boolean | Enable prefix stripping |
| `prefix` | string | Prefix to remove from path |

## Example Configurations

### Simple Proxy (No Prefix Stripping)

```yaml
gateway:
  host: "0.0.0.0"
  port: 8080
  features:
    - logger

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

targets:
  - id: "target-001"
    name: "backend"
    url: "https://api.example.com"

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

routes:
  - id: "route-001"
    api: "api-001"
    path: "/api/*"
```

**Request flow:**
- Client requests: `/api/users/123`
- Backend receives: `/api/users/123`

### Prefix Stripping

```yaml
routes:
  - id: "route-001"
    api: "api-001"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"
```

**Request flow:**
- Client requests: `/api/v1/users/123`
- Gateway strips: `/api/v1`
- Backend receives: `/users/123`

### Multiple Routes

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

  - id: "api-route"
    api: "api-001"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"
```

### Multiple Backends

```yaml
hosts:
  - id: "host-001"
    name: "api-host"
    domain: "api.example.com"
  - id: "host-002"
    name: "admin-host"
    domain: "admin.example.com"

targets:
  - id: "target-001"
    name: "api-backend"
    url: "https://api-backend.internal"
  - id: "target-002"
    name: "admin-backend"
    url: "https://admin-backend.internal"

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

routes:
  - id: "route-001"
    api: "api-001"
    path: "/api/*"
  - id: "route-002"
    api: "api-002"
    path: "/admin/*"
```

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