# WarpDrive 0.1.0 Known Limitations

This document describes current limitations and workarounds for WarpDrive 0.1.0. These will be addressed in future releases.

## ACME/Let's Encrypt (EXPERIMENTAL)

**Status**: ⚠️ Experimental - Not recommended for production

### Current Limitations

1. **No automatic renewal**: Certificates expire after 90 days with no automatic renewal loop
2. **Startup failure on provision errors**: If ACME provisioning fails, WarpDrive aborts startup entirely
3. **Minimal error handling**: Limited retry logic and error recovery
4. **No rate limit protection**: Doesn't track Let's Encrypt rate limits

### Recommended Approach for 0.1.0

**Use manual TLS certificates instead:**

```bash
# Generate self-signed cert for testing
openssl req -x509 -newkey rsa:4096 -nodes \
  -keyout key.pem -out cert.pem -days 365 \
  -subj "/CN=localhost"

# Configure WarpDrive
export WARPDRIVE_TLS_CERT_PATH=./cert.pem
export WARPDRIVE_TLS_KEY_PATH=./key.pem
```

**For production with Let's Encrypt:**

Use an external certificate manager:
- **Recommended**: [Certbot](https://certbot.eff.org/) with cron renewal
- **Alternative**: Kubernetes cert-manager, Caddy, Traefik, or cloud provider cert management

```bash
# Example: Certbot with standalone mode
certbot certonly --standalone -d example.com -d www.example.com

# Point WarpDrive to managed certs
export WARPDRIVE_TLS_CERT_PATH=/etc/letsencrypt/live/example.com/fullchain.pem
export WARPDRIVE_TLS_KEY_PATH=/etc/letsencrypt/live/example.com/privkey.pem

# Reload WarpDrive when certs renew (certbot post-renewal hook)
systemctl reload warpdrive
```

### Future Plans (0.2.0+)

- Automatic renewal loop with configurable interval
- Exponential backoff for provision failures
- Graceful fallback when provisioning fails
- Rate limit tracking and compliance
- OCSP stapling support

---

## Process Supervisor

**Status**: ⚠️ Basic - No crash recovery

### Current Limitations

1. **No restart logic**: If the managed upstream process crashes, it stays dead
2. **No health checking**: WarpDrive doesn't monitor upstream health
3. **Silent failures**: Proxy continues serving requests to dead upstream (returns 502)
4. **Single process only**: Can't supervise multiple upstream instances

### Current Behavior

```bash
# WarpDrive spawns your app
export WARPDRIVE_UPSTREAM_COMMAND="bundle exec rails server"
export WARPDRIVE_UPSTREAM_ARGS="-p 3000"
warpdrive

# If Rails crashes → WarpDrive keeps running, returns 502 for all requests
# Manual intervention required (restart WarpDrive or use external supervisor)
```

### Recommended Approach for 0.1.0

**Use an external process supervisor:**

#### Option 1: systemd (Linux production)

```ini
# /etc/systemd/system/myapp.service
[Unit]
Description=My Rails App
After=network.target

[Service]
Type=simple
User=deploy
WorkingDirectory=/var/www/myapp
ExecStart=/usr/local/bin/bundle exec rails server -p 3000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```ini
# /etc/systemd/system/warpdrive.service
[Unit]
Description=WarpDrive Proxy
After=network.target myapp.service
Requires=myapp.service

[Service]
Type=simple
User=deploy
WorkingDirectory=/var/www/myapp
Environment="WARPDRIVE_TARGET_PORT=3000"
ExecStart=/usr/local/bin/warpdrive
Restart=always

[Install]
WantedBy=multi-user.target
```

#### Option 2: Foreman (development)

```yaml
# Procfile
web: bundle exec rails server -p 3000
proxy: warpdrive
```

```bash
foreman start
```

#### Option 3: Docker Compose

```yaml
services:
  app:
    build: .
    command: bundle exec rails server -p 3000
    ports:
      - "3000:3000"
    restart: always

  proxy:
    image: seuros/warpdrive:latest
    environment:
      - WARPDRIVE_TARGET_HOST=app
      - WARPDRIVE_TARGET_PORT=3000
    ports:
      - "8080:8080"
    depends_on:
      - app
    restart: always
```

### Current Supervisor Features (What Works)

✅ Spawn upstream process on start
✅ Pass environment variables to upstream
✅ Graceful shutdown (sends SIGTERM, waits for exit)
✅ Stdio forwarding (upstream logs appear in WarpDrive output)

### Future Plans (0.2.0+)

- Exponential backoff restart logic
- Health check polling (HTTP endpoint or TCP)
- Configurable restart limits (max retries, backoff timing)
- Multiple upstream instance support
- Process pool management
- Metrics for restart counts and upstream health

---

## Test Suite

**Status**: 68/70 tests passing (97%)

### Failing Tests

Two integration tests may fail in certain environments:

1. Tests requiring Docker (if Docker not running)
2. Tests requiring specific network configuration

**To run tests:**

```bash
# Run all tests (may have 2 failures in restricted environments)
cargo test

# Run only unit tests (should pass 100%)
cargo test --lib

# Run specific test
cargo test test_name
```

### CI/CD Recommendation

Mark environment-dependent tests as `#[ignore]` or use feature flags for optional dependencies.

---

## Documentation/Code Alignment

### Features Documented but Not Fully Implemented

The following features are mentioned in docs but have limited/placeholder implementation:

1. **TOML-based routing**: Router has placeholder methods, works but limited features
2. **Health check endpoints**: Mentioned but not exposed via HTTP
3. **Multi-upstream load balancing**: Basic support, needs more testing

These work for basic use cases but may have edge cases not yet handled.

### Recommendation

Test thoroughly in staging before production use. File issues for any gaps between documentation and behavior.

---

## Getting Help

- **Documentation**: [README.md](README.md), [ARCHITECTURE.md](docs/ARCHITECTURE.md)
- **Issues**: https://github.com/seuros/warpdrive/issues
- **Configuration examples**: [.env.example](.env.example)

For production deployments, consider:
- Starting with simple single-upstream configuration
- Using external tools for TLS and process supervision
- Thorough load testing before go-live
- Monitoring upstream health externally
