Files

Kyle Isom e84093b7fb Add documentation, Docker setup, and tests for server and gRPC packages

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>

2026-03-17 11:24:35 -07:00

2.1 KiB

Raw Blame History

mc-proxy

mc-proxy is a Layer 4 TLS SNI proxy and router for Metacircular Dynamics 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

# 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:

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

See 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 for operational procedures.

# 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 for the full system specification.

License

Proprietary. Metacircular Dynamics.

2.1 KiB Raw Blame History