Kyle Isom
e84093b7fb
Rewrite README with project overview and quick start. Add RUNBOOK with operational procedures and incident playbooks. Fix Dockerfile for Go 1.25 with version injection. Add docker-compose.yml. Clean up golangci.yaml for mc-proxy. Add server tests (10) covering the full proxy pipeline with TCP echo backends, and grpcserver tests (13) covering all admin API RPCs with bufconn and write-through DB verification. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
75 lines
2.1 KiB
Markdown
75 lines
2.1 KiB
Markdown
# 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.
|