# lmrc-proxy

HTTP reverse proxy and API gateway utilities for LMRC Stack applications.

A flexible, trait-based reverse proxy library for building API gateways and microservices routers with Axum.

## Features

- **HTTP Reverse Proxy**: Full-featured HTTP proxying with configurable behavior
- **Subdomain Routing**: Route requests based on subdomains
- **Flexible Route Resolution**: Trait-based routing for custom backend discovery
- **Axum Integration**: Ready-to-use middleware for Axum web framework
- **Header Management**: Automatic handling of hop-by-hop headers and X-Forwarded-* headers
- **Type-Safe**: Leverages Rust's type system for safe proxy operations

## Installation

```toml
[dependencies]
lmrc-proxy = "0.3.11"
```

## Quick Start

### Basic Reverse Proxy

```rust
use lmrc_proxy::{proxy_request, ProxyConfig};
use axum::{Router, routing::any, extract::Request};

async fn proxy_handler(request: Request) -> Result<axum::response::Response, lmrc_proxy::ProxyError> {
    proxy_request(request, "http://backend:8080", ProxyConfig::default()).await
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/*path", any(proxy_handler));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}
```

### Subdomain-Based Gateway

```rust
use lmrc_proxy::{
    routing::StaticRouteResolver,
    middleware::{subdomain_extractor, subdomain_proxy},
    ProxyConfig,
};
use axum::{Router, middleware};
use std::sync::Arc;

#[tokio::main]
async fn main() {
    // Configure routes
    let resolver = Arc::new(
        StaticRouteResolver::new()
            .add_route("api", "http://api-service:8080")
            .add_route("admin", "http://admin-service:9000")
            .add_route("auth", "http://auth-service:8081")
    );

    // Build router with subdomain routing
    let app = Router::new()
        .layer(middleware::from_fn(subdomain_extractor))
        .layer(middleware::from_fn_with_state(
            (resolver, ProxyConfig::default()),
            subdomain_proxy
        ));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}
```

Requests to `api.example.com` route to `http://api-service:8080`, requests to `admin.example.com` route to `http://admin-service:9000`, etc.

## Core Concepts

### ProxyConfig

Configure proxy behavior:

```rust
use lmrc_proxy::ProxyConfig;
use std::time::Duration;

let config = ProxyConfig {
    preserve_host: false,              // Forward original Host header
    timeout: Duration::from_secs(30),  // Request timeout
    max_body_size: 10 * 1024 * 1024,   // 10MB max body
    add_forwarded_headers: true,       // Add X-Forwarded-* headers
};
```

### RouteResolver Trait

Implement custom routing logic:

```rust
use lmrc_proxy::routing::RouteResolver;
use async_trait::async_trait;

struct DatabaseRouteResolver {
    // Database connection
}

#[async_trait]
impl RouteResolver for DatabaseRouteResolver {
    async fn resolve(&self, subdomain: &str) -> Option<String> {
        // Query database for backend URL
        self.db.get_backend_url(subdomain).await
    }
}
```

### Subdomain Extraction

Extract subdomains from requests:

```rust
use lmrc_proxy::routing::extract_subdomain;

assert_eq!(extract_subdomain("api.example.com"), Some("api".to_string()));
assert_eq!(extract_subdomain("example.com"), None);
assert_eq!(extract_subdomain("localhost"), Some("infra".to_string())); // Development
```

## Middleware

### subdomain_extractor

Extracts subdomain from Host header and stores it in request extensions.

```rust
use axum::{Router, middleware};
use lmrc_proxy::middleware::subdomain_extractor;

let app = Router::new()
    .layer(middleware::from_fn(subdomain_extractor));
```

### subdomain_proxy

Routes requests to backends based on subdomain.

```rust
use lmrc_proxy::{middleware::subdomain_proxy, routing::StaticRouteResolver, ProxyConfig};
use axum::{Router, middleware};
use std::sync::Arc;

let resolver = Arc::new(StaticRouteResolver::new()
    .add_route("api", "http://api-backend:8080"));

let app = Router::new()
    .layer(middleware::from_fn_with_state(
        (resolver, ProxyConfig::default()),
        subdomain_proxy
    ));
```

## Advanced Usage

### Custom Route Resolver with Caching

```rust
use lmrc_proxy::routing::RouteResolver;
use async_trait::async_trait;
use std::collections::HashMap;
use std::sync::RwLock;

struct CachedRouteResolver {
    cache: RwLock<HashMap<String, String>>,
    backend: Box<dyn RouteResolver>,
}

#[async_trait]
impl RouteResolver for CachedRouteResolver {
    async fn resolve(&self, key: &str) -> Option<String> {
        // Check cache first
        if let Some(url) = self.cache.read().unwrap().get(key) {
            return Some(url.clone());
        }

        // Query backend
        if let Some(url) = self.backend.resolve(key).await {
            self.cache.write().unwrap().insert(key.to_string(), url.clone());
            Some(url)
        } else {
            None
        }
    }
}
```

### Dynamic Backend Discovery

```rust
use lmrc_proxy::routing::RouteResolver;
use async_trait::async_trait;

struct ServiceDiscoveryResolver {
    consul_client: ConsulClient,
}

#[async_trait]
impl RouteResolver for ServiceDiscoveryResolver {
    async fn resolve(&self, service_name: &str) -> Option<String> {
        // Query service discovery (Consul, etcd, etc.)
        self.consul_client
            .get_service_address(service_name)
            .await
            .ok()
    }
}
```

## Configuration Examples

### Development Setup

```rust
use lmrc_proxy::{routing::StaticRouteResolver, ProxyConfig};

let resolver = StaticRouteResolver::new()
    .add_route("api", "http://localhost:8081")
    .add_route("admin", "http://localhost:8082");
```

### Production Setup

```rust
use std::time::Duration;
use lmrc_proxy::ProxyConfig;

let config = ProxyConfig {
    preserve_host: false,
    timeout: Duration::from_secs(60),
    max_body_size: 50 * 1024 * 1024, // 50MB
    add_forwarded_headers: true,
};
```

## Testing

```bash
cargo test -p lmrc-proxy
```

## Integration with lmrc-http-common

Works seamlessly with [lmrc-http-common](../lmrc-http-common) for error handling, logging, and HTTP utilities.

```rust
use lmrc_http_common::middleware::{add_request_id, log_request};
use lmrc_proxy::middleware::{subdomain_extractor, subdomain_proxy};
use axum::{Router, middleware};

let app = Router::new()
    .layer(middleware::from_fn(log_request))
    .layer(middleware::from_fn(add_request_id))
    .layer(middleware::from_fn(subdomain_extractor))
    .layer(middleware::from_fn_with_state(state, subdomain_proxy));
```

## Error Handling

All errors implement `IntoResponse` for seamless Axum integration:

- `ProxyError::ClientCreation` - Failed to create HTTP client
- `ProxyError::RequestBody` - Failed to read request body
- `ProxyError::BackendRequest` - Backend request failed (returns 502 Bad Gateway)
- `ProxyError::ResponseBody` - Failed to read response body
- `ProxyError::RouteNotFound` - No route found (returns 404 Not Found)

## Performance Considerations

1. **Connection Pooling**: Uses `reqwest` with automatic connection pooling
2. **Body Streaming**: Efficiently handles large request/response bodies
3. **Header Filtering**: Automatically filters hop-by-hop headers
4. **Timeout Management**: Configurable timeouts prevent hung connections

## Security

- **Header Sanitization**: Hop-by-hop headers are automatically filtered
- **X-Forwarded Headers**: Properly sets X-Forwarded-Host for backend awareness
- **Body Size Limits**: Configurable max body size prevents memory exhaustion
- **Timeout Protection**: Request timeouts prevent resource exhaustion

## Examples

See the [gateway app](../../apps/lmrc-cli/embedded-apps/gateway/) for a complete example of an API gateway using lmrc-proxy.

## Contributing

This library is part of the [LMRC Stack](https://gitlab.com/lemarco/lmrc-stack) monorepo.

## License

Dual licensed under MIT OR Apache-2.0 (your choice).
