synclaire
TCP/TLS transport library for Rust — guards, routing, load balancing, and proxy built in.
Docs | Crate | GitHub | Examples
synclaire sits between raw sockets and application protocols. You write a handler, synclaire runs the accept loop, manages TLS, enforces connection guards, and routes traffic — so you ship protocol logic, not plumbing. Includes both Client and Server APIs.
your app
|
synclaire --- guards ─── TLS ─── routing ─── proxy ---> handler
|
TCP/TLS
What's included
| Async + Sync servers & clients | Tokio-based async or threaded sync — same API shape |
| TLS, mTLS, mixed-mode | rustls with ring or aws-lc-rs (FIPS); auto-detect TLS vs plain TCP per connection |
| Guard stack | Rate limiter, SYN flood, slow loris, throttle, IP ban — layered, rollback-safe |
| Routing & load balancing | IP-based rules, round-robin and consistent-hash pools, runtime-updatable |
| TCP proxy | Auth, TLS offload, credential rotation, pluggable routing |
| Metrics | Per-server, per-IP counters with real-time callbacks |
Quick start
[]
= "0.1.2"
Async echo server
use ;
;
async
Sync echo server
use ;
use ;
;
Graceful shutdown
Both async and sync servers support graceful shutdown via a channel:
let = shutdown_channel;
spawn;
// later...
shutdown.shutdown?;
SyncServer has the same API (shutdown_channel() + run_until_shutdown()).
Guard stack
Built-in connection guards that run before your handler sees the connection. Stack them to create layered transport defense:
use GuardStackConfig;
use *;
use Duration;
let guards = GuardStackConfig ;
| Guard | What it does |
|---|---|
| RateLimiter | Token-bucket rate limiting per IP |
| Throttle | Caps concurrent connections per IP and globally |
| SynGuard | Limits half-open connections to mitigate SYN floods |
| SlowLoris | Drops connections that go idle too long |
| IpBan | Runtime-mutable IP blocklist with ban()/unban() API |
Guards implement a lifecycle (on_reserve / on_established / on_payload / on_activity / on_close) and are automatically rolled back if a later guard in the stack rejects. All per-IP tracking maps are bounded to prevent memory exhaustion under IP rotation attacks.
Allowlist — trusted IPs skip the entire guard chain. Runtime-mutable via allow()/remove():
let guards = builder
.push
.build;
// At any time, from any thread:
guards.allowlist.allow;
guards.allowlist.remove;
TLS
TLS is handled by rustls. System root certificates are loaded by default.
use ;
let tls = builder
.enabled
.certificate_chain
.private_key
.build;
let config = builder
.tls
.accept_mode
.build;
Mixed mode — AcceptMode::Mixed auto-detects whether each incoming connection is TLS or plain TCP on the same port. Use connection.is_tls() in the handler to branch.
mTLS — set .require_client_auth(true) on the server's TlsConfig and provide .trust_anchor(...) with the client CA.
Client-side:
let tls = builder
.enabled
.server_name
.build; // uses system root CAs by default
let config = builder
.connect_addr
.tls
.build;
Routing and load balancing
Route connections to different backends based on source IP, with pluggable load balancing:
use Arc;
use ;
let pool = new;
let routing = new;
routing.add_group;
routing.add_rule;
Pool strategies: round_robin, consistent_hash (with StickyKey::Ip for session affinity and weighted backends).
Proxy
TCP proxy with optional auth, routing, guards, and TLS offload:
use ;
let config = new
.with_auth
.with_buffer_size;
new.run?;
Both sync (ProxyServer) and async (AsyncProxyServer) variants available.
Dynamic auth rotation — use ProxyAuthHandle to rotate credentials at runtime without restarting the proxy:
let auth_handle = new;
let server = new.with_auth_handle;
// later, from another thread:
auth_handle.set_basic?;
TLS offload (async only) — terminate TLS at the proxy, forward plaintext to the backend:
let tls = builder
.enabled
.certificate_chain
.private_key
.build;
let config = new
.with_tls_offload;
new.run.await?;
Metrics
use Arc;
use MetricsCollector;
let metrics = new;
// Pass to proxy via .with_metrics(metrics.clone())
let snapshot = metrics.snapshot;
println!;
Per-server, per-IP breakdowns and real-time callbacks via MetricsCallback trait.
Connection filters
Composable filters for custom accept/reject logic per connection:
use Arc;
use *;
let filter = new
.add_filter
.add_filter;
Implement the ConnectionFilter trait for custom auth — filter(&self, conn: &Connection) -> Result<(), SynError>.
Feature flags
| Flag | Default | What it enables |
|---|---|---|
async |
yes | Tokio-based async server/client (AsyncServer, AsyncClient) |
sync |
no | Sync server/client (SyncServer, SyncClient) |
rustls-backend |
yes | TLS via rustls + ring (pure Rust, no C compiler) |
aws-lc-backend |
no | TLS via rustls + aws-lc-rs (FIPS-capable, requires cmake) |
full |
no | async + sync + rustls-backend |
# Async only (default — uses ring crypto provider)
= "0.1"
# Sync only
= { = "0.1", = false, = ["sync", "rustls-backend"] }
# FIPS-capable TLS (aws-lc-rs instead of ring)
= { = "0.1", = false, = ["async", "aws-lc-backend"] }
# Both async + sync
= { = "0.1", = ["full"] }
Examples
# Async TCP echo (server + client demo)
# Sync TCP echo
# Standalone server / client
# Guard API demo
# Metrics API demo
# Proxy with routing + auth
# TLS examples require certificates — generate them first:
&& &&
# Mixed-mode (TCP + TLS on same port)
# Mutual TLS (mTLS)
License
MIT