# Configuration Management

Gobstopper provides a comprehensive configuration system that supports multiple sources, environment-based settings, and validation. This guide covers how to configure your Gobstopper applications for different environments.

## Quick Start

```python
from gobstopper import Gobstopper, Config

# Load configuration automatically
config = Config.load()

# Create app with config
app = Gobstopper()
```

## Configuration Sources

Configuration is loaded from multiple sources with the following precedence (highest to lowest):

1. **Environment Variables** (highest priority)
2. **Configuration Files** (TOML or JSON)
3. **Default Values** (lowest priority)

This allows you to have sensible defaults, override them with config files, and further override specific settings with environment variables.

## Configuration Files

### TOML Format (Recommended)

Create `config.toml` in your project root:

```toml
env = "development"
debug = true

[server]
host = "127.0.0.1"
port = 8000
workers = 1

[security]
secret_key = "your-secret-key-min-32-chars"
enable_csrf = true

[tasks]
enabled = true
max_workers = 4
```

### JSON Format

Create `config.json` in your project root:

```json
{
  "env": "development",
  "debug": true,
  "server": {
    "host": "127.0.0.1",
    "port": 8000,
    "workers": 1
  },
  "security": {
    "secret_key": "your-secret-key-min-32-chars",
    "enable_csrf": true
  }
}
```

### Environment-Specific Configs

Gobstopper automatically searches for environment-specific configs:

1. `config.{env}.toml` (e.g., `config.production.toml`)
2. `config.toml`
3. `config.{env}.json`
4. `config.json`

Set the environment with:
- `ENV` environment variable
- `env` parameter in `Config.load()`

```python
# Load production config
config = Config.load(env="production")

# Or use environment variable
# ENV=production python app.py
```

## Environment Variables

All configuration options can be set via environment variables using the `GOBSTOPPER_` prefix:

```bash
# Server settings
export GOBSTOPPER_SERVER_HOST=0.0.0.0
export GOBSTOPPER_SERVER_PORT=8080
export GOBSTOPPER_SERVER_WORKERS=4

# Security settings
export GOBSTOPPER_SECRET_KEY="your-production-secret-key"
export GOBSTOPPER_ENABLE_CSRF=true

# Database/storage
export GOBSTOPPER_SESSION_STORAGE_TYPE=redis
export GOBSTOPPER_TASKS_STORAGE_PATH=/data/tasks.db

# Features
export GOBSTOPPER_CORS_ENABLED=true
export GOBSTOPPER_METRICS_ENABLED=true
```

## Configuration Sections

### Server Configuration

```python
@dataclass
class ServerConfig:
    host: str = "127.0.0.1"
    port: int = 8000
    workers: int = 1
    interface: str = "rsgi"
    log_level: str = "info"
```

### Security Configuration

```python
@dataclass
class SecurityConfig:
    secret_key: Optional[str] = None
    enable_csrf: bool = True
    enable_security_headers: bool = True
    hsts_max_age: int = 31536000
    hsts_include_subdomains: bool = True
    csp_policy: str = "default-src 'self'; object-src 'none'"
    referrer_policy: str = "strict-origin-when-cross-origin"
    coop_policy: str = "same-origin"
    coep_policy: str = "require-corp"
    cookie_secure: bool = True
    cookie_httponly: bool = True
    cookie_samesite: str = "Strict"
    cookie_max_age: int = 3600
    session_storage_type: str = "file"
    session_storage_path: Optional[str] = None
```

### CORS Configuration

```python
@dataclass
class CORSConfig:
    enabled: bool = False
    allow_origins: list[str] = ["*"]
    allow_methods: list[str] = ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
    allow_headers: list[str] = ["*"]
    allow_credentials: bool = False
    max_age: int = 86400
```

### Static Files Configuration

```python
@dataclass
class StaticFilesConfig:
    enabled: bool = True
    url_path: str = "/static"
    directory: str = "static"
    use_rust: bool = True
```

### Template Configuration

```python
@dataclass
class TemplateConfig:
    directory: str = "templates"
    use_rust: bool = True
    auto_reload: bool = False
    cache_size: int = 400
```

### Task Configuration

```python
@dataclass
class TaskConfig:
    enabled: bool = True
    storage_type: str = "duckdb"
    storage_path: Optional[str] = None
    max_workers: int = 4
    default_priority: int = 5
    enable_retries: bool = True
    max_retries: int = 3
    cleanup_days: int = 7
```

### Rate Limit Configuration

```python
@dataclass
class RateLimitConfig:
    enabled: bool = False
    default_rate: int = 100
    default_period: int = 60
    storage_type: str = "memory"
```

### Logging Configuration

```python
@dataclass
class LoggingConfig:
    level: str = "info"
    format: str = "text"
    enable_correlation_id: bool = False
    log_file: Optional[str] = None
```

### Metrics Configuration

```python
@dataclass
class MetricsConfig:
    enabled: bool = False
    export_type: str = "prometheus"
    endpoint: str = "/metrics"
    include_hostname: bool = True
```

## Loading Configuration

### Automatic Loading

```python
from gobstopper import Config

# Auto-detect config file and environment
config = Config.load()
```

### Explicit Loading

```python
# Load specific file
config = Config.load(config_file="config.production.toml")

# Load specific environment
config = Config.load(env="production")

# Disable auto-detection
config = Config.load(auto_detect=False)
```

## Validation

Validate your configuration before starting the app:

```python
config = Config.load()

# Validate and get list of issues
issues = config.validate()

if issues:
    for issue in issues:
        print(f"Config issue: {issue}")

    # Check for critical issues
    critical = [i for i in issues if i.startswith("CRITICAL:")]
    if critical:
        raise ValueError("Configuration has critical issues")
```

## Production Configuration

For production deployments, follow these best practices:

### 1. Set Environment

```bash
export ENV=production
```

### 2. Use Secure Secret Key

```bash
# Generate a secure key
export GOBSTOPPER_SECRET_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
```

### 3. Production Config File

Create `config.production.toml`:

```toml
env = "production"
debug = false

[server]
host = "0.0.0.0"
port = 8000
workers = 4
log_level = "warning"

[security]
# Set via environment variable
enable_csrf = true
enable_security_headers = true
cookie_secure = true
cookie_httponly = true
cookie_samesite = "Strict"
session_storage_type = "sql"

[cors]
enabled = true
allow_origins = ["https://yourdomain.com"]
allow_credentials = true

[templates]
auto_reload = false
cache_size = 1000

[logging]
level = "warning"
format = "json"
enable_correlation_id = true

[metrics]
enabled = true
```

### 4. Production Checklist

The config validation will warn you about:

- ✅ Secret key is set and at least 32 characters
- ✅ Debug mode is disabled
- ✅ Cookie secure flag is enabled
- ✅ Template auto-reload is disabled
- ✅ Appropriate session storage (not memory)
- ✅ HTTPS settings are enabled
- ✅ Security headers are enabled

## Custom Configuration

Add custom application-specific configuration:

```toml
[custom]
app_name = "My App"
max_upload_size = 10485760
feature_flags = { experimental = false, beta = true }
```

Access custom config:

```python
config = Config.load()
app_name = config.custom.get("app_name", "Default App")
max_upload = config.custom.get("max_upload_size", 5242880)
```

## Docker Integration

In Docker, use environment variables:

```dockerfile
ENV ENV=production
ENV GOBSTOPPER_SERVER_HOST=0.0.0.0
ENV GOBSTOPPER_SERVER_WORKERS=4
ENV GOBSTOPPER_SECRET_KEY=${SECRET_KEY}
```

Or mount config file:

```dockerfile
COPY config.production.toml /app/config.toml
```

## Configuration as Code

For programmatic configuration:

```python
from gobstopper import Config, ServerConfig, SecurityConfig

# Build config manually
config = Config(
    env="production",
    debug=False,
    server=ServerConfig(
        host="0.0.0.0",
        port=8000,
        workers=4
    ),
    security=SecurityConfig(
        secret_key="your-secret-key",
        enable_csrf=True
    )
)

# Validate
issues = config.validate()
if issues:
    print("Configuration issues:", issues)
```

## Best Practices

1. **Never commit secrets** - Use environment variables for sensitive data
2. **Use environment-specific configs** - `config.production.toml`, `config.development.toml`
3. **Validate in CI/CD** - Run `config.validate()` in your deployment pipeline
4. **Use TOML for readability** - TOML is easier to read and write than JSON
5. **Document custom settings** - Add comments to your config files
6. **Start with defaults** - Only override what you need
7. **Test configs** - Have separate test configs with test databases

## Troubleshooting

### Config file not found

Gobstopper automatically searches for config files. If none found, it uses defaults.

```python
# Explicitly specify config file
config = Config.load(config_file="path/to/config.toml")
```

### Environment variables not working

Ensure you use the `GOBSTOPPER_` prefix and correct section names:

```bash
# Correct
export GOBSTOPPER_SERVER_PORT=8080

# Incorrect (won't work)
export SERVER_PORT=8080
```

### Secret key warnings

In production, you'll get a critical warning if secret key is missing:

```python
config = Config.load(env="production")
issues = config.validate()
# ['CRITICAL: secret_key is required in production']
```

Set it via environment variable:

```bash
export GOBSTOPPER_SECRET_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
```

## Migration from Legacy Config

If you're using hardcoded values or environment variables directly:

### Before

```python
import os

app = Gobstopper(
    secret_key=os.getenv("SECRET_KEY"),
    debug=True
)
```

### After

```python
from gobstopper import Gobstopper, Config

config = Config.load()
app = Gobstopper()  # Config automatically loaded
```

## API Reference

See the [API documentation](api/config.md) for complete details on all configuration options and the Config API.