mc-proxy/README.md

# mc-proxy

mc-proxy is a Layer 4 TLS SNI proxy and router for
[Metacircular Dynamics](https://metacircular.net) services. It reads the SNI
hostname from incoming TLS ClientHello messages and proxies the raw TCP stream
to the matched backend. It does not terminate TLS.

A global firewall (IP, CIDR, GeoIP country blocking) is evaluated before any
routing decision. Blocked connections receive a TCP RST with no further
information.

## Quick Start

```bash
# Build
make mc-proxy

# Run locally (creates srv/ with example config on first run)
make devserver

# Full CI pipeline: vet → lint → test → build
make all
```

## Configuration

Copy the example config and edit it:

```bash
cp mc-proxy.toml.example /srv/mc-proxy/mc-proxy.toml
```

See [ARCHITECTURE.md](ARCHITECTURE.md) for the full configuration reference.

Key sections:
- `[database]` — SQLite database path (required)
- `[[listeners]]` — TCP ports to bind and their route tables (seeds DB on first run)
- `[grpc]` — optional gRPC admin API with TLS/mTLS
- `[firewall]` — global blocklist (IP, CIDR, GeoIP country)
- `[proxy]` — connect timeout, idle timeout, shutdown timeout

## CLI Commands

| Command | Purpose |
|---------|---------|
| `mc-proxy server -c <config>` | Start the proxy |
| `mc-proxy status -c <config>` | Query a running instance's health via gRPC |
| `mc-proxy snapshot -c <config>` | Create a database backup (`VACUUM INTO`) |

## Deployment

See [RUNBOOK.md](RUNBOOK.md) for operational procedures.

```bash
# Install on a Linux host
sudo deploy/scripts/install.sh

# Or build and run as a container
make docker
docker run -v /srv/mc-proxy:/srv/mc-proxy mc-proxy server -c /srv/mc-proxy/mc-proxy.toml
```

## Design

mc-proxy intentionally omits a REST API and web frontend. The gRPC admin API
is the sole management interface. This is an intentional departure from the
Metacircular engineering standards — mc-proxy is pre-auth infrastructure and
a minimal attack surface is prioritized over interface breadth.

See [ARCHITECTURE.md](ARCHITECTURE.md) for the full system specification.

## License

Proprietary. Metacircular Dynamics.