# Migration Tables → nginx mapping

This document explains the purpose of each migration table added under `public/migration/src/migrations` and how the rows map to generated nginx configuration (HTTP `http {}` and `stream {}` contexts).

Summary of tables covered:

- `upstream`
- `upstream_target`
- `proxy_host`
- `location`
- `stream_service`
- `access_list`
- `access_list_entry`
- `audit_log`

---

## `upstream`

Purpose: A named backend pool of servers. Shared by HTTP and stream services.

Key fields:

- `id`: UUID primary key
- `name`: identifier used when generating nginx `upstream <name> {}`
- `protocol`: `http` | `tcp` | `udp` — determines how nginx will use the pool
- `algorithm`: load balancing strategy (`round_robin`, `least_conn`, `ip_hash`)
- `sticky_session`: whether to enable sticky behavior when supported
- `health_check`: optional JSON describing health probes

nginx mapping (HTTP):

```nginx
upstream <name> {
    server 10.0.0.5:8080 weight=2;
    server 10.0.0.6:8080 backup;
    # optional LB settings generated from `algorithm` and `sticky_session`
}

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://<name>;
    }
}
```

nginx mapping (stream):

```nginx
stream {
  upstream <name> {
    server 10.0.0.5:3306;
    server 10.0.0.6:3306 backup;
  }

  server {
    listen 3306;
    proxy_pass <name>;
  }
}
```

Notes: `upstream.protocol` selects which block and directive forms to generate;

---

## `upstream_target`

Purpose: One row per backend server in an `upstream` pool.

Key fields:

- `upstream_id`: FK to `upstream`
- `target_host`, `target_port`
- `weight`, `is_backup`, `enabled`

nginx mapping: each row becomes a `server` line in the generated `upstream` block (weights and backup flags applied). Disabled targets are omitted.

Example generated line:

```nginx
server 10.0.0.5:8080 weight=3;
server 10.0.0.6:8080 backup;
```

---

## `proxy_host`

Purpose: Represents an HTTP(S) host (a top-level `server` block in nginx `http` context).

Key fields:

- `domain`: `server_name` value (may be a wildcard)
- `listen_port`: port to listen on (80/443)
- `scheme`: http|https (informs UI; TLS handled elsewhere)
- `forward_host/forward_port` or `default_upstream_id`: host-level forwarding fallback
- `preserve_host_header`: whether to forward original `Host` header
- `enable_websocket`: toggles websocket header handling
- `meta`: JSON for optional host-level settings (timeouts, client_max_body_size, custom snippets)

nginx mapping (host-level default):

```nginx
server {
  listen <listen_port>;
  server_name <domain>;

  # host-level fallback if no matching location
  location / {
    proxy_pass http://<default_upstream_name>;
  }
}
```

If `forward_host`/`forward_port` is set instead of `default_upstream_id`, generate `proxy_pass http://forward_host:forward_port;`.

`meta` entries are injected into the `server` block (careful: snippets can break reloads).

---

## `location`

Purpose: Path-level routing (`location` blocks inside a `server`). More specific than `proxy_host` default.

Key fields:

- `host_id`: FK to `proxy_host`
- `path`: `location` match (e.g., `/api`, `~^/assets/`)
- `match_type`: `prefix` | `exact` | `regex`
- `upstream_id` or `proxy_pass_host`/`proxy_pass_port`
- `allowed_methods`: optional method whitelist
- `custom_config`: raw nginx snippet inserted inside the `location`

nginx mapping:

```nginx
location /api {
  proxy_pass http://api_upstream;
  # optional custom_config injected here
}
```

Ordering and match type produce correct nginx `location` selection semantics; `order` field can break ties for equal specificity.

---

## `stream_service`

Purpose: A TCP/UDP service in nginx `stream` context — corresponds to a `server` block inside `stream {}`.

Key fields:

- `listen_host`, `listen_port`
- `protocol`: `tcp` | `udp`
- `mode`: `direct` | `upstream` (direct forwards to `forward_host:forward_port`, `upstream` uses `upstream_id` pool)
- `preserved_client_ip`: whether to enable proxy_protocol or other client-ip forwarding
- `meta`: JSON for advanced stream options (ssl_preread, proxy_timeout, buffer sizes)

nginx mapping (stream):

```nginx
stream {
  upstream <name> {
    server 10.0.0.5:3306;
  }

  server {
    listen 3306;
    proxy_pass <name>; # or proxy_pass 10.0.0.10:3306 for direct
  }
}
```

Notes: Stream services bypass HTTP processing. Use `meta` for `proxy_protocol` and `ssl_preread` toggles.

---

## `access_list` and `access_list_entry`

Purpose: Nameable allow/deny lists for IP/CIDR or other entry types that can be applied to hosts/locations/stream services.

Key fields (access_list): `id`, `name`, `description`.
Key fields (entry): `access_list_id`, `entry_type` (e.g., `allow`, `deny`, `note`), `value` (IP or CIDR), `comment`.

nginx mapping (HTTP example):

```nginx
location /admin {
  allow 10.0.0.0/24;
  deny all;
  proxy_pass http://admin_upstream;
}
```

nginx mapping (stream example):

```nginx
server {
  listen 3306;
  allow 10.0.0.0/24;
  deny all;
  proxy_pass backend_pool;
}
```