rproxy/README.md

# rproxy

rproxy is a high-performance reverse proxy server written in C. It routes HTTP and WebSocket requests to upstream services based on hostname, with support for SSL/TLS termination and connection pooling.

## Features

- Reverse proxy routing by hostname
- SSL/TLS support for upstream connections with certificate verification
- WebSocket proxying
- Connection pooling and idle timeout management
- Real-time monitoring and statistics
- Web-based dashboard for metrics visualization
- SQLite-based persistent statistics storage
- Epoll-based event handling for high concurrency
- Graceful shutdown with connection draining
- Live configuration reload via SIGHUP
- Dashboard authentication (HTTP Basic Auth)
- Rate limiting per client IP
- Health checks for upstream servers
- Automatic upstream connection retries
- File logging support
- Stream data patching/rewriting for textual content

## Dependencies

- GCC
- OpenSSL (libssl, libcrypto)
- SQLite3
- pthreads
- cJSON library

## Build

```bash
make
```

This compiles the source files in `src/` and produces the `rproxy` executable.

## Configuration

Configuration is defined in `proxy_config.json`:

```json
{
  "port": 9998,
  "reverse_proxy": [
    {
      "hostname": "example.com",
      "upstream_host": "127.0.0.1",
      "upstream_port": 5000,
      "use_ssl": false,
      "rewrite_host": true,
      "patch": {
        "old_string": "new_string",
        "secret_key": "[REDACTED]",
        "blocked_content": null
      }
    }
  ]
}
```

- `port`: Listening port for incoming connections
- `reverse_proxy`: Array of routing rules
  - `hostname`: Host header to match for routing
  - `upstream_host`: Target server hostname/IP
  - `upstream_port`: Target server port
  - `use_ssl`: Enable SSL for upstream connection
  - `rewrite_host`: Rewrite Host header to upstream hostname
  - `patch`: Optional object for stream data patching (see below)

### Data Patching

The `patch` configuration allows rewriting or blocking content in HTTP streams. Patch rules are applied to textual content only (text/*, application/json, application/xml, etc.). Binary content passes through unmodified.

```json
{
  "patch": {
    "find_this": "replace_with_this",
    "another_string": "replacement",
    "blocked_term": null
  }
}
```

- **String replacement**: Each key-value pair defines a find-replace rule
- **Content blocking**: Setting value to `null` blocks the entire response/request when the key is found
- **Bidirectional**: Patches apply to both requests (client → upstream) and responses (upstream → client)

When content is blocked:
- Blocked responses return `502 Bad Gateway` to the client
- Blocked requests return `403 Forbidden` to the client

Supported textual content types:
- `text/*` (text/html, text/plain, text/css, etc.)
- `application/json`
- `application/xml`
- `application/javascript`
- `application/x-www-form-urlencoded`
- Any content type with `+xml` or `+json` suffix

## Environment Variables

| Variable | Description |
|----------|-------------|
| `DEBUG` | Enable debug logging (set to `1`) |
| `LOG_FILE` | Path to log file (default: stdout) |
| `RATE_LIMIT` | Max requests per minute per IP |
| `DASHBOARD_USER` | Dashboard authentication username |
| `DASHBOARD_PASS` | Dashboard authentication password |
| `SSL_VERIFY` | Disable SSL verification (set to `0`) |
| `SSL_CA_FILE` | Path to custom CA certificate file |
| `SSL_CA_PATH` | Path to CA certificate directory |

## Usage

```bash
./rproxy [config_file]
```

If no config file is specified, defaults to `proxy_config.json`.

Examples:

```bash
# Basic usage
./rproxy

# With custom config
./rproxy /etc/rproxy/config.json

# With debug logging
DEBUG=1 ./rproxy

# With file logging
LOG_FILE=/var/log/rproxy.log ./rproxy

# With rate limiting (100 requests/minute)
RATE_LIMIT=100 ./rproxy

# With dashboard authentication
DASHBOARD_USER=admin DASHBOARD_PASS=secret ./rproxy

# Reload configuration
kill -HUP $(pidof rproxy)
```

## Endpoints

- Dashboard: `http://localhost:{port}/rproxy/dashboard`
- API Stats: `http://localhost:{port}/rproxy/api/stats`

## Signals

| Signal | Action |
|--------|--------|
| `SIGINT` | Graceful shutdown |
| `SIGTERM` | Graceful shutdown |
| `SIGHUP` | Reload configuration |

## Architecture

- **main.c**: Entry point, event loop, signal handling
- **connection.c**: Connection management, epoll handling
- **http.c**: HTTP request/response parsing
- **ssl_handler.c**: SSL/TLS connection handling
- **monitor.c**: System and per-vhost statistics collection
- **dashboard.c**: Web dashboard generation
- **config.c**: JSON configuration parsing
- **buffer.c**: Circular buffer implementation
- **logging.c**: Logging utilities
- **rate_limit.c**: Per-IP rate limiting
- **auth.c**: Dashboard authentication
- **health_check.c**: Upstream health monitoring
- **patch.c**: Stream data patching engine

## Testing

```bash
make test
```

Runs unit tests for core components.