# Usage

## Running the Gateway

### Local Development

```bash
cd app
go run main.go
```

The gateway will start on the configured host and port (default: `0.0.0.0:8080`).

### Docker

```bash
# Pull and run (builds locally if image not available)
docker compose up -d

# View logs
docker compose logs -f gateway

# Stop
docker compose down
```

### Build from Source

```bash
cd app
go build -o gateway main.go
./gateway
```

## Health Check

Check if the gateway is running:

```bash
curl http://localhost:8080/_/health
```

Response: `OK`

## Making Requests

After configuring routes in `gateway.yaml`, make requests to the gateway:

```bash
# Example: Request to a route configured at /api/v1/dev/*
curl http://localhost:8080/api/v1/dev/users

# With API key authentication
curl -H "X-Api-Key: your-key-here" http://localhost:8080/api/v1/dev/data

# With session authentication
curl -H "Authorization: Bearer token" http://localhost:8080/api/v1/protected
```

## Route Examples

### Strip Prefix Example

**Configuration:**
```yaml
routes:
  - id: "api"
    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`

### Authentication Example

**Configuration:**
```yaml
security:
  auth:
    enabled: true
    type: "api_key"
    header: "X-Api-Key"
```

**Valid request:**
```bash
curl -H "X-Api-Key: secret123" http://localhost:8080/api/v1/data
```

**Invalid request (missing header):**
```bash
curl http://localhost:8080/api/v1/data
# Returns: 401 Unauthorized
```

### WAF Method Filtering Example

**Configuration:**
```yaml
security:
  waf:
    enabled: true
    methods: ["GET", "POST"]
```

**Allowed:**
```bash
curl -X GET http://localhost:8080/api/v1/data
curl -X POST http://localhost:8080/api/v1/data
```

**Blocked:**
```bash
curl -X DELETE http://localhost:8080/api/v1/data
# Returns: 403 Forbidden
```

## Logging

The gateway uses structured logging via `masterlog`. Logs include:

- Request ID (if enabled)
- Client IP (if real_ip enabled)
- Request method and path
- Response status

**Example log output:**
```json
{
  "level": "info",
  "msg": "Registering route",
  "path": "/api/v1/dev/*"
}
```

## Troubleshooting

### Gateway fails to start

1. Check if port is already in use:
```bash
lsof -i :8080
```

2. Verify configuration file exists and is valid YAML

3. Check logs for detailed error messages

### 401 Unauthorized

- Verify auth header is included
- Check header name matches configuration
- Verify path is not excluded from auth

### 403 Forbidden

- Check WAF method configuration
- Verify HTTP method is allowed

### Backend connection errors

- Verify API target URL is correct
- Check backend service is running
- Verify network connectivity

## Performance Considerations

- The gateway uses Go's `httputil.ReverseProxy` for efficient proxying
- Keep-alive connections are reused by default
- Consider connection pooling for high-traffic scenarios
- Monitor memory usage with high request volumes