@lopatnov/conduit

v1.1.2

Published

2 days ago

Production-grade reverse proxy and API gateway built on Cloudflare Pingora. TLS, JWT auth, rate limiting, load balancing, caching, Prometheus metrics, hot reload. One config file, one binary, no runtime dependencies.

Downloads

802

@lopatnov/conduit

Production-grade reverse proxy and API gateway — TLS, rate limiting, JWT auth, load balancing, caching, Prometheus metrics. One config file, one binary, zero runtime dependencies.

Built on Cloudflare Pingora — the same engine that routes ~1 trillion requests/day at Cloudflare. Distributed as a native Rust binary via npm for convenience.

Getting Started

No installation needed:

npx @lopatnov/conduit init    # interactive setup wizard
npx @lopatnov/conduit         # start

Install globally — then just type conduit:

npm install -g @lopatnov/conduit
conduit init
conduit

How it works: postinstall downloads the correct pre-built native binary for your platform from GitHub Releases. No compilation. Node.js is only needed for the download — the server itself is a standalone Rust binary with no Node.js dependency at runtime.

Standard vs Full binary

The npm package installs the standard binary (--features standard). It covers the majority of production use cases: TLS, reverse proxying, static files, rate limiting, basic/API-key/JWT auth, the consumer model, ForwardAuth, response caching, auto-TLS (Let's Encrypt), compression, hot-reload, health checks, and Prometheus metrics.

Features that require the full build are not included in the standard npm binary:

| Feature | Requires | How to get it | | ---------------------------- | ------------------ | ---------------------------------------------------------------------- | | Redis rate limiting & caching | --features redis | Download full binary ↗ | | WASM plugin middleware | --features wasm | Download full binary ↗ | | Rhai scripting middleware | --features rhai | Download full binary ↗ | | OpenTelemetry OTLP tracing | --features otlp | Download full binary ↗ | | TCP proxy mode | --features tcp | Download full binary ↗ |

To get all features download conduit-*-full.tar.gz from GitHub Releases, or build from source with cargo install lopatnov-conduit --features full.

Minimal Config

Create conduit.yaml (or conduit.json):

port: 3000
proxy:
  /api: "http://localhost:4000"

Run:

conduit

GET /api/users → http://localhost:4000/api/users. Done.

Common Recipes

Serve static files

port: 3000
static: ./dist

Reverse proxy to a backend

port: 3000
proxy: "http://localhost:4000"

SPA + API (most common)

port: 3000
static: ./dist
proxy:
  /api: "http://localhost:4000"
fallback:
  status: 200
  file: ./dist/index.html

Dev server with hot reload

port: 3000
logging: dev
hotReload: true
cors: true
static: ./src
proxy:
  /api: "http://localhost:4000"
fallback:
  status: 200
  file: ./src/index.html

Load-balanced backend with health checks

port: 8080
proxy:
  /api:
    targets:
      - "http://api1:4000"
      - "http://api2:4000"
      - "http://api3:4000"
    strategy: least-conn
    healthCheck:
      path: /health
      intervalSecs: 10
    retry:
      attempts: 3
      conditions: [connection_error, "5xx"]

Production HTTPS with manual certificates

port: 443
tls:
  cert: /etc/tls/fullchain.pem
  key: /etc/tls/privkey.pem
  httpRedirectPort: 80
http2: true
securityHeaders: true
compression: true
static: ./dist
proxy:
  /api:
    targets: ["http://api1:4000", "http://api2:4000"]
    strategy: least-conn
    stripPrefix: true
rateLimit:
  windowSecs: 60
  limit: 200
healthCheck: true
metrics:
  path: /__metrics__
  token: "$METRICS_TOKEN"

Multiple sites from one process

global:
  admin:
    bind: "127.0.0.1:2019"

sites:
  - host: app.example.com
    port: 443
    tls:
      cert: "$CERT_PATH"
      key: "$KEY_PATH"
    static: ./dist
    proxy:
      /api: "http://api:4000"

  - host: admin.example.com
    port: 443
    tls:
      cert: "$CERT_PATH"
      key: "$KEY_PATH"
    basicAuth:
      users: { admin: "$ADMIN_PASS" }
      challenge: true
    static: ./admin-ui

CLI Reference

conduit                       start server (reads conduit.yaml / conduit.json)
conduit -c <file>             use a specific config file (.yaml or .json)
conduit --version             print version
conduit --help                show all options

conduit init [--yes]          interactive setup wizard (--yes = non-interactive)
conduit validate              validate config (exit 0 = OK, exit 1 = errors)
conduit probe                 HEAD each upstream, show latency table
conduit fmt [--write]         pretty-print / normalise config

conduit reload   [--admin ADDR]    hot-reload config without restart
conduit status   [--admin ADDR]    show uptime and in-flight requests
conduit status   [--admin ADDR] --upstream   show upstream health table
conduit upstreams [--admin ADDR]   list upstream health and latency
conduit upstreams add    --route PATH --target URL [--weight N] [--site LABEL]
conduit upstreams remove --route PATH --target URL [--site LABEL]
conduit upstreams weight --route PATH --target URL --weight N [--site LABEL]
conduit shutdown [--admin ADDR]    graceful shutdown

conduit completions bash|zsh|fish|power-shell|elvish
conduit man                   generate man page (roff)

Admin commands connect to 127.0.0.1:2019 by default. Override with --admin ADDR or CONDUIT_ADMIN environment variable.

Features

| Feature | -------------------------- | Reverse proxy | Static files | TLS | Auto-TLS | HTTP/2 | Compression | WebSocket | Proxy cache | IP filtering | Rate limiting | Auth | CORS | Security headers | Request transforms | Response transforms | Scripting middleware | Reliability | Hot reload | Health check | Prometheus | OpenTelemetry ¹ | File upload ¹ | TCP proxy ¹ | Redirects | Advanced routing | Virtual hosting | SPA fallback | Structured logging | YAML config | Kubernetes ¹ | Details | | --------------------------------------------------------------------------------------- | | 8 load-balancing strategies; health checks; retry; failover; traffic mirroring | | ETag, Last-Modified, Range requests, pre-compressed .br/.gz sidecars | | Manual certificates, HTTP→HTTPS redirect, mTLS client certificates | | Let's Encrypt via ACME — automatic issue and renewal | | ALPN negotiation, h2c (cleartext), upstream H/2 support | | gzip + Brotli + Zstd (async, streaming, configurable Content-Type filter) | | Transparent Connection: Upgrade proxying | | Memory store; stale-while-revalidate; thundering-herd lock; Redis/disk store ¹ | | CIDR allow/deny lists; trust X-Forwarded-For; runtime deny-list via Admin API | | Token-bucket, per-IP or per-header; burst capacity; Redis-backed for clusters ¹ | | Basic Auth, API key, JWT (HS256/RS256/ES256 + JWKS), Forward Auth, Consumer model | | Origin allow-list, credentials mode, preflight | | HSTS, CSP, X-Frame-Options, Permissions-Policy, Referrer-Policy, allowedHosts | | Set/remove headers before upstream; inject JWT claims ({{ jwt.sub }}) | | Set/remove headers on upstream response | ¹ | Rhai scripts or WASM plugins — request and response phase | | Circuit breaker, outlier detection, retry budget, priority load-shedding | | conduit reload — zero-downtime, no dropped connections | | /__health__ with optional upstream status, latency, ejection state | | /__metrics__ — 11 metrics including per-upstream counters and latency histograms | | OTLP distributed tracing to Grafana Tempo / Jaeger | | multipart/form-data — UUID filenames, MIME allowlist, size limits | | Raw TCP passthrough — MySQL, PostgreSQL, Redis, SMTP | | Named params (:slug), 301/302/307/308 | | Glob path + method + header regex + query + cookie predicates | | Multiple sites (host matching) from one process | | Per-Accept-type fallback rules | | dev, combined, json, short, common formats | | conduit.yaml / conduit.yml — YAML recommended; JSON also supported | | ConduitSite CRD config provider |

¹ Not included in the standard npm binary — requires the full binary.

Supported Platforms

| Platform | Architecture | Standard | Full | | -------- | ---------------------- | :------: | :--: | | Linux | x86-64 (glibc) | ✅ | ✅ | | Linux | x86-64 (musl / Docker) | ✅ | ✅ | | Linux | ARM64 | ✅ | ✅ | | Linux | RISC-V 64 | ✅ | — | | macOS | Intel (x86-64) | ✅ | ✅ | | macOS | Apple Silicon (ARM64) | ✅ | ✅ | | Windows | x86-64 | ✅ | ✅ |

Unsupported platform? Build from source:

cargo install lopatnov-conduit                      # minimal (default = [])
cargo install lopatnov-conduit --features standard  # standard (matches published binaries)
cargo install lopatnov-conduit --features full      # all features

Contributing

Contributions are welcome! Read CONTRIBUTING.md before opening a pull request.

Bug reports → GitHub Issues.
Security vulnerabilities → GitHub Security Advisories.
Found it useful? A ⭐ on GitHub helps others discover the project.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@lopatnov/conduit

Getting Started

Standard vs Full binary

Minimal Config

Common Recipes

Serve static files

Reverse proxy to a backend

SPA + API (most common)

Dev server with hot reload

Load-balanced backend with health checks

Production HTTPS with manual certificates

Multiple sites from one process

CLI Reference

Features

Supported Platforms

Links

Contributing

License