eggress-embed

Part of eggress — a Rust-native, embeddable, multi-protocol proxy framework targeting compatibility with Python pproxy==2.7.9.

Stable Rust embed API for embedding eggress in another Rust application. This is the public surface most downstream Rust users should depend on.

When to use this crate

Use eggress-embed when you want to start, stop, reload, and inspect an eggress proxy from within your own Rust application. This crate provides the EggressService and EggressConfig types that manage the full proxy lifecycle.

Feature flags

full (default) — Enables common, extended, operations, reverse, pproxy-compat, and pproxy-legacy.
common — Base protocol set (HTTP, SOCKS4/4a, SOCKS5, raw).
extended — Adds Shadowsocks, Trojan, WebSocket, and Shadowsocks UDP relay.
operations — Enable admin server and system-proxy integration.
reverse — Enable reverse/backward proxy protocol.
pproxy-compat — Enable pproxy URI and CLI flag translation.
pproxy-legacy — Enable pproxy-compatible Shadowsocks compression.
legacy-crypto — Enable legacy Shadowsocks stream ciphers.
quic — Enable QUIC/H3 transport and protocol.
ssh — Enable SSH upstream transport.

Quick example

use eggress_embed::{EggressService, EggressConfig};

let config = EggressConfig::from_toml_str(r#"
    version = 1

    [[listeners]]
    name = "proxy"
    bind = "127.0.0.1:0"
    protocols = ["socks5"]
"#)?;

let handle = EggressService::new(config).start().await?;
println!("Listening on {:?}", handle.bound_addresses());
handle.shutdown().await?;

Native outbound connector (no listener)

OutboundConnector executes a pproxy remote expression in-process via ChainExecutor, without starting a listener. It accepts canonical __ multi-hop chains, preserves hop order, and fails closed on unsupported chain members instead of dropping them:

let connector = OutboundConnector::from_pproxy_uri(
    "socks5://127.0.0.1:1080__http://127.0.0.1:8080"
)?;

let (stream, info) = connector.connect_tcp("api.example.com", 443).await?;
assert_eq!(info.hop_count, 2);

Requires the pproxy-compat feature. Protocol availability remains feature-gated, and malformed chained input returns credential-redacted errors.

Documentation

License

MIT OR Apache-2.0