mrapids 0.1.7

# Resource Protection Implementation

This document describes the high-value resource protection features implemented in the MicroRapid CLI and Agent.

## Implemented Features

### 1. Request Timeout Enforcement ✅

**Location**: `src/core/http/client.rs`

**Features**:
- Configurable timeout (default: 30 seconds)
- Enforced at both client and request level
- Prevents hanging on slow APIs

**Configuration**:
```toml
[performance]
request_timeout = 30  # seconds
```

**Implementation**:
```rust
// Client-level timeout
let client = ClientBuilder::new()
    .timeout(Duration::from_secs(config.timeout_secs))
    .build()?;

// Request-level timeout enforcement
let response = timeout(
    Duration::from_secs(self.config.timeout_secs),
    request_builder.send()
).await?;
```

### 2. Retry Logic with Exponential Backoff ✅

**Location**: `src/core/http/retry.rs`

**Features**:
- Configurable retry attempts (default: 3)
- Exponential backoff with jitter
- Smart retry detection (5xx, timeouts, network errors)
- Configurable delays and multipliers

**Configuration**:
```toml
[performance]
max_retries = 3

[performance.retry_policy]
max_retries = 3
initial_delay_ms = 1000
max_delay_ms = 30000
backoff_multiplier = 2.0
jitter = true
```

**Implementation**:
- Retries on: Timeouts, 5xx errors, network errors, rate limits (429)
- Does NOT retry on: 4xx client errors, validation errors
- Jitter prevents thundering herd problem

### 3. Request/Response Size Limits ✅

**Location**: `src/core/http/client.rs`

**Features**:
- Request body size limit (default: 10MB)
- Response body size limit (default: 50MB)
- Streaming response reading with size checks
- Early termination on size exceeded

**Configuration**:
```toml
[performance]
max_body_size_mb = 10  # For agent config
```

**Implementation**:
```rust
// Request size check
if body_size > self.config.max_request_body_size {
    return Err(anyhow!("Request body too large: {} bytes", body_size));
}

// Response size check with streaming
while let Some(chunk) = stream.next().await {
    body.extend_from_slice(&chunk);
    if body.len() > self.config.max_response_body_size {
        return Err(anyhow!("Response body too large"));
    }
}
```

## Value Delivered

### 1. **Reliability**
- No more hanging requests blocking AI agents
- Automatic recovery from transient failures
- Protection against resource exhaustion

### 2. **Performance**
- Faster failure detection (30s timeout vs indefinite wait)
- Smart retries reduce manual intervention
- Size limits prevent memory issues

### 3. **Security**
- Prevents DoS via large payloads
- Timeout prevents slowloris-style attacks
- Rate limit handling (429) prevents API bans

## Usage in Agent CLI

The Agent CLI automatically benefits from these features when using the core API:

```rust
// In agent/src/tools/run.rs
let response = run_operation(request.clone(), &spec, None).await
    .map_err(|e| {
        // Handles timeout, retry, and size limit errors
        create_error(4001, &format!("Operation failed: {}", e), None)
    })?;
```

## Error Handling

New error types added:
- `TimeoutError` - Request exceeded timeout
- `PayloadTooLarge` - Request/response too large
- `ClientError` - 4xx HTTP errors
- `ServerError` - 5xx HTTP errors

## Testing

To test the resource protection:

```bash
# Test timeout (using a slow endpoint)
mrapids run --operation slowEndpoint --spec api.yaml

# Test retry (using a flaky endpoint)
mrapids run --operation flakyEndpoint --spec api.yaml

# Test size limits (large request)
mrapids run --operation uploadLargeFile --body @large-file.json --spec api.yaml
```

## Future Enhancements

While not implemented yet, these would add additional value:

1. **Circuit Breaker** - Prevent cascading failures
2. **Response Streaming** - Handle very large responses efficiently
3. **Connection Pooling** - Reuse connections for better performance
4. **Adaptive Timeouts** - Adjust timeouts based on endpoint history

## Migration Guide

For existing users:
1. Update configuration with new timeout/retry settings
2. Monitor logs for timeout/retry events
3. Adjust limits based on your API characteristics

The implementation provides immediate value with zero configuration changes required - sensible defaults are already in place.