# Configuration

All server configuration is done via environment variables or a `.env` file in the project root.

## Example .env

```env
PORT=8080
API_KEY=your-secret-api-key
CORS_ORIGINS=https://yourdomain.com,https://app.yourdomain.com
LOG_FORMAT=json
```

Copy `.env.example` to get started:

```bash
cp .env.example .env
```

---

## Environment Variables

| Variable | Default | Required | Description |
|---|---|---|---|
| `PORT` | `8080` | No | Port the HTTP server listens on. |
| `API_KEY` | — | No* | Shared secret for API key auth. Auth is disabled when empty — do not leave empty in production. |
| `CORS_ORIGINS` | `http://localhost:3000` | No | Comma-separated list of allowed CORS origins. |
| `LOG_FORMAT` | `text` | No | `text` for human-readable, `json` for structured logging (recommended for production). |

---

## API Key Authentication

The Go server uses a shared API key. This is intentional: the server is an internal service called only by the Next.js backend, not directly by end users.

When `API_KEY` is set, every request (except `GET /health`) must include:

```
X-API-Key: your-secret-api-key
```

Requests with a missing or incorrect key get `401 UNAUTHORIZED`:

```json
{
  "error": "missing or invalid API key",
  "code": "UNAUTHORIZED"
}
```

### Calling from Next.js

```typescript
const res = await fetch(`${process.env.DNS_SERVER_URL}/api/v1/dns/lookup`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.DNS_API_KEY!,
  },
  body: JSON.stringify({ domain, types }),
});
```

Store `DNS_API_KEY` as a secret environment variable in your Next.js deployment. Never expose it client-side.

---

## CORS

CORS is handled by [go-chi/cors](https://github.com/go-chi/cors). Configure allowed origins via `CORS_ORIGINS`.

```env
# Development
CORS_ORIGINS=http://localhost:3000

# Production (single domain)
CORS_ORIGINS=https://app.yourdomain.com

# Production (multiple domains)
CORS_ORIGINS=https://app.yourdomain.com,https://yourdomain.com
```

Since the Go server is an internal API called server-side by Next.js, CORS is mostly relevant for development. In production, only your Next.js server IP/domain needs access.

---

## Rate Limiting

Rate limiting is provided by [go-chi/httprate](https://github.com/go-chi/httprate) and is enabled by default.

- Rate limiting is applied per IP address.
- Limits are enforced at the router middleware level.
- Requests exceeding the limit receive `429 Too Many Requests`.

### Per-API-key rate limiting (planned)

When billing tiers are added, rate limits will be enforced per API key:

| Tier | Limit |
|---|---|
| Free | Limited requests per day, daily checks |
| Pro | Higher limits, hourly checks |
| Team | Highest limits, shared across org |

---

## Redis Caching (planned)

DNS result caching via Redis is on the roadmap. When available, the server will check Redis before querying upstream DNS, storing results with TTL-based expiry.

Planned configuration:

```env
REDIS_URL=redis://localhost:6379
REDIS_TTL=300  # seconds
```

The cache layer will use [go-redis](https://github.com/redis/go-redis) as middleware before DNS resolution. A `docker-compose.yml` bundling the Go server with Redis will be provided for self-hosting. See [self-hosting.md](./self-hosting.md) for the planned compose configuration.