impcurl

Rust WebSocket client with TLS fingerprint impersonation, powered by libcurl-impersonate.

Bypass TLS fingerprinting by impersonating real browser signatures (Chrome, Safari, Firefox, Edge, Tor).

Crates

Crate	Description
impcurl-sys	Dynamic FFI bindings for libcurl-impersonate with auto-fetch
impcurl	Safe blocking wrapper — WebSocket handshake, send, recv
impcurl-ws	Async tokio client with builder API

Quick Start

[dependencies]
impcurl-ws = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

use impcurl_ws::WsClient;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut ws = WsClient::connect("wss://echo.websocket.org").await?;

    ws.send_text("hello")?;

    if let Some(data) = ws.recv_timeout(std::time::Duration::from_secs(5)).await? {
        println!("{}", String::from_utf8_lossy(&data));
    }

    ws.shutdown().await
}

Builder API

use impcurl::ImpersonateTarget;
use impcurl_ws::WsClient;
use std::time::Duration;

let mut ws = WsClient::builder("wss://example.com/ws")
    .header("Origin", "https://example.com")
    .header("User-Agent", "Mozilla/5.0 ...")
    .proxy("socks5h://127.0.0.1:1080")
    .impersonate(ImpersonateTarget::Chrome136)
    .connect_timeout(Duration::from_secs(10))
    .verbose(true)
    .connect()
    .await?;

Runtime Library

The libcurl-impersonate shared library is resolved at runtime in this order:

1. WsClient::builder(...).lib_path(...) — explicit path
2. CURL_IMPERSONATE_LIB env var
3. Near executable (../lib/ and side-by-side)
4. IMPCURL_LIB_DIR env var
5. ~/.impcurl/lib, ~/.cuimp/binaries
6. Auto-fetch from curl_cffi wheel (enabled by default)

Auto-fetch Controls

Env Var	Description
IMPCURL_AUTO_FETCH=0	Disable auto-download
IMPCURL_CURL_CFFI_VERSION	curl_cffi release tag (default 0.11.3)
IMPCURL_AUTO_FETCH_CACHE_DIR	Override fetch cache directory

Architecture

impcurl-ws (async tokio client)
  └── impcurl (safe blocking wrapper)
       └── impcurl-sys (dynamic FFI + auto-fetch)
            └── libcurl-impersonate (runtime .so/.dylib/.dll)

On Unix, the async event loop uses CURLMOPT_SOCKETFUNCTION / CURLMOPT_TIMERFUNCTION with tokio::io::unix::AsyncFd for efficient socket-level readiness notification. Non-Unix falls back to curl_multi_poll.

License

MIT