Skip to content

Conduit v1.0.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 05 Jun 09:01
· 19 commits to main since this release
v1.0.0
9467b3b
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Conduit v1.0.0 — production-ready Rust reverse proxy and API gateway built on Cloudflare Pingora.

Highlights

  • API Gateway: JWT auth, consumer model, ForwardAuth, rate limiting, request/response transformation
  • Production resilience: circuit breaker, outlier detection, retry with jitter, traffic mirroring
  • Observable: Prometheus metrics (per-route + per-upstream), OpenTelemetry OTLP, structured JSON logs
  • Flexible caching: in-memory, disk, Redis backends; stale-while-revalidate; thundering herd prevention
  • Extensible: Rhai scripting + WASM plugins with request and response phase hooks
  • Modular: 14 optional feature flags — build only what you need

Core Proxy

  • HTTP/1.1 and HTTP/2 reverse proxy via Cloudflare Pingora
  • Static file serving with MIME detection and directory index
  • TCP passthrough proxy (type: tcp) with round-robin and random strategies
  • File upload handler (type: upload) with MIME allowlist and size limits
  • Health check endpoint (/__health__) with optional upstream status (includeUpstreams)
  • Prometheus metrics endpoint (/metrics)
  • Admin API on loopback port 2019 (hot reload, upstream management, cert rotation, IP deny list)
  • Hot reload via ArcSwap — zero-downtime config updates without restarting

Load Balancing (8 strategies)

  • Round Robin, Weighted Round Robin
  • Least Connections
  • IP Hash, Consistent Hash (ketama)
  • Random
  • Power of Two Choices (P2C) with Peak EWMA latency
  • Sticky sessions (cookie-based consistent hashing)
  • Service failover — automatic failover to backup upstreams when primaries are unhealthy
  • Outlier detection — consecutive 5xx ejection with exponential backoff and max ejection %
  • Circuit breaker — maxConnectionsPerUpstream prevents overload; returns 503 gracefully
  • Slow start — gradual traffic ramp-up for recovered upstreams (slowStartSecs)
  • Upstream connection pool warmup (prewarmConnections)

Authentication & Authorization

  • Basic Auth — htpasswd-compatible
  • API Key — header or query param, configurable header name
  • JWT — HS256, RS256/ES256; JWKS URL with TTL cache; audience + issuer validation (--features jwt)
  • Consumer model — per-consumer credentials (API key / Basic / JWT), rate limits, header injection (--features consumers)
  • ForwardAuth — delegate auth to external HTTP service; inject response headers (--features forward-auth)
  • mTLS — client certificate verification with CA bundle; optional mode
  • IP filter — CIDR allowlist/blocklist applied before auth; dry-run mode
  • Dynamic IP deny list — POST /admin/ip-deny adds CIDRs without reload
  • X-Request-ID — inject UUID v4 or forward existing; first in filter chain

Rate Limiting

  • Token bucket with configurable burst
  • Per-site, per-route, per-consumer granularity
  • Redis-backed distributed rate limiting (--features redis)
  • Dry-run mode for testing without enforcement

Caching (--features cache)

  • In-memory caching via Pingora native cache with custom key (host + scheme + path + query)
  • Disk cache backend — cache.store: "disk:/path" with atomic write and structured binary format (--features disk-cache)
  • Redis cache backend — cache.store: "redis://..." with TLS support; fail-open (--features redis)
  • Stale-while-revalidate + stale-if-error with configurable seconds
  • Cache thundering herd prevention via Pingora CacheLock (16 shards, 10s timeout)
  • Cache purge API — DELETE /admin/cache?url=https://...
  • Respects Cache-Control, s-maxage, Vary headers

Resilience

  • Retry on upstream errors — configurable status codes, methods, retry count
  • Exponential backoff with ±50% jitter (retry.backoffJitter)
  • Retry budget — soft cap on retry ratio to prevent cascade (retry.budgetPercent)
  • Per-try timeout (timeout.perTryMs)
  • Request body buffering for retry — up to limits.maxBodyBufferBytes (linkerd ReplayBody pattern)
  • Traffic mirroring — fire-and-forget mirror to secondary URL (proxy.*.mirror)
  • Inflight request limit — limits.maxInflightRequests → 503 when exceeded
  • Priority-based load shedding — low-priority routes shed traffic when inflight threshold reached
  • Half-open circuit breaker — single probe request after ejection period; re-ejects on failure

Observability

Prometheus metrics:

  • conduit_requests_total{site, status} — request counter
  • conduit_request_duration_seconds{site} — latency histogram
  • conduit_active_connections — current in-flight gauge
  • conduit_upstream_active_connections{upstream} — per-upstream gauge
  • conduit_upstream_requests_total{upstream, status} — per-upstream counter
  • conduit_upstream_latency_seconds{upstream} — per-upstream histogram
  • conduit_rate_limit_rejected_total{site} — rate limit counter
  • conduit_upstream_errors_total{route, status} — upstream error counter
  • conduit_retry_attempts_total{route, condition} — retry counter
  • conduit_cache_hits_total / conduit_cache_misses_total — cache counters

Distributed tracing (--features otlp):

  • OpenTelemetry OTLP via gRPC (Grafana Tempo, Jaeger, Honeycomb, Collector)
  • Spans include: method, path, status, duration, upstream URL, request_id
  • 5xx responses → span status ERROR; configurable sample rate

Access logging:

  • JSON and dev (pretty) formats
  • Fields: timestamp, method, path, status, duration_ms, request_id, upstream, ip
  • logging.skipPaths — suppress health/metrics noise
  • logging.stripQuery — omit query string from logs

Middleware & Extensibility

  • Rhai scripting — type: "script" in middleware[]; request and response phases; set/remove headers, abort, redirect (--features rhai)
  • WASM plugins — type: "wasm" in middleware[]; Wasmtime Cranelift JIT; 17 host functions (headers, body, redirect, request_id, log); module cache; fail-open (--features wasm)
  • Fault injection — abort N% + delay N%; chaos testing only (--features fault-injection)

Request/Response Transformation

  • requestTransform.setHeaders with {{ jwt.<claim> }} template expansion
  • requestTransform.removeHeaders
  • responseTransform.setHeaders / removeHeaders
  • Path transforms: strip_prefix, rewrite
  • X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host injection
  • X-Response-Time header

Security Headers

  • CORS — configurable origins, methods, headers, credentials, max-age
  • Security headers bundle: HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, CSP
  • allowedHosts — reject requests with unexpected Host headers
  • CRLF injection protection — strip CR/LF from upstream response headers
  • Error masking — replace 5xx responses with generic JSON body (maskErrors: true)
  • Upstream TLS verification — upstreamTls.verify, serverName, CA bundle

TLS

  • rustls backend (no OpenSSL dependency)
  • TLS 1.2/1.3 with configurable cipher suites (rustls names)
  • mTLS — tls.clientAuth: { ca, optional } via WebPKI client verifier
  • ACME / Let's Encrypt automatic certificate provisioning (--features acme)
  • SNI support for multi-domain deployments
  • Certificate rotation API — POST /admin/certs/reload with PEM validation

Routing

  • Header-based routing with regex matching (routes[].match.headers)
  • Cookie-based routing (routes[].match.cookies)
  • Query parameter routing (routes[].match.query)
  • Priority routing — proxy.*.priority: u8 (0–100) with X-Priority header override
  • Redirect rules — permanent and temporary, path/query rewriting

Configuration

  • YAML and JSON formats with auto-discovery (conduit.yaml, conduit.yml)
  • Environment variable interpolation — $VAR and ${VAR} in config values
  • Hot reload — conduit reload or POST /admin/reload
  • File provider — auto-reload on file change via notify
  • Kubernetes provider — ConduitSite CRD; list+watch; --kubernetes-namespace flag (--features kubernetes)
  • serde_path_to_error — precise error locations in config validation
  • 14 optional feature flags: jwt, consumers, forward-auth, rhai, wasm, tcp, upload, redis, cache, disk-cache, acme, fault-injection, otlp, kubernetes
  • full feature bundle — all features enabled

CLI

conduit start          # start the server
conduit validate       # validate config without starting
conduit init           # interactive config wizard
conduit probe          # check upstream health (parallel)
conduit reload         # hot reload running instance
conduit status         # show server status via Admin API
conduit upstreams add/remove/weight   # dynamic upstream management
conduit completion     # shell completions (bash, zsh, fish, PowerShell)
conduit man            # generate man pages

Binary Variants

Binary Features
conduit-<target> Standard: core proxy + static files + basic/apikey auth + rate limit + CORS + compression + TLS + health + Prometheus + hot reload
conduit-<target>-full All 14 optional features enabled

Platforms

  • Linux x86_64 (glibc), Linux x86_64 (musl/static), Linux ARM64, Linux RISC-V 64
  • macOS x86_64, macOS ARM64 (Apple Silicon)
  • Windows x86_64

Full Changelog: v0.3.0...v1.0.0

Assets 17
Loading