Transport Trait

Overview

The transport layer provides a runtime-agnostic abstraction for network connections. It handles raw byte transmission without knowledge of WhatsApp’s protocol framing. The transport system consists of two main traits:

Transport - Represents an active connection for sending/receiving raw bytes
TransportFactory - Creates new transport instances and event streams

The Transport trait represents an active network connection as a simple byte pipe.

use async_trait::async_trait;
use wacore::sync_marker::MaybeSendSync;

#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
pub trait Transport: MaybeSendSync {
    /// Sends raw data to the server
    async fn send(&self, data: Vec<u8>) -> Result<(), anyhow::Error>;

    /// Closes the connection
    async fn disconnect(&self);
}

MaybeSendSync is Send + Sync on native targets and carries no bounds on wasm32. This means Arc<dyn Transport> remains thread-safe on native, while implementations backed by !Send JS handles (e.g. a browser WebSocket) compile on the wasm port without wrapping.

Methods

send

Sends raw bytes through the transport. The caller is responsible for any protocol framing.

async fn send(&self, data: Vec<u8>) -> Result<(), anyhow::Error>;

Parameters:

data - Raw bytes to send

Returns:

Ok(()) on success
Err(anyhow::Error) on failure

Example:

let data = vec![1, 2, 3, 4];
transport.send(data).await?;

disconnect

Gracefully closes the connection.

async fn disconnect(&self);

Example:

transport.disconnect().await;

resource_report

Best-effort per-session footprint of this transport: read/write framing buffers plus a TLS/noise session-state estimate. Defaulted to None (“not reported”) — a transport that can introspect its buffers overrides it.

fn resource_report(&self) -> Option<wacore::stats::TransportResourceReport> {
    None
}

Returns:

Some(TransportResourceReport) with any subset of read_buffer_bytes, write_buffer_bytes, tls_state_bytes filled in (each Option<u64>)
None (default) if the transport doesn’t report

Feeds into Client::resource_report(). The bundled Tokio WebSocket transport (below) overrides this with static estimates, since tokio-websockets and rustls don’t expose their live buffer sizes.

TransportFactory Trait

Creates new transport instances and associated event streams.

#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
pub trait TransportFactory: MaybeSendSync {
    /// Creates a new transport and returns it along with a stream of events
    async fn create_transport(
        &self,
    ) -> Result<(Arc<dyn Transport>, async_channel::Receiver<TransportEvent>), anyhow::Error>;
}

Like Transport, TransportFactory uses MaybeSendSync so that factory implementations holding !Send JS state compile on wasm32. On native the bound is Send + Sync as before.

Methods

create_transport

Establishes a new connection and returns both the transport handle and an event receiver.

async fn create_transport(
    &self,
) -> Result<(Arc<dyn Transport>, async_channel::Receiver<TransportEvent>), anyhow::Error>;

Returns:

Arc<dyn Transport> - The transport instance for sending data
async_channel::Receiver<TransportEvent> - Stream of transport events

Example:

let factory = TokioWebSocketTransportFactory::new();
let (transport, events) = factory.create_transport().await?;

// Use transport to send data
transport.send(data).await?;

// Listen for events
while let Ok(event) = events.recv().await {
    match event {
        TransportEvent::Connected => println!("Connected"),
        TransportEvent::DataReceived(bytes) => println!("Received {} bytes", bytes.len()),
        TransportEvent::Disconnected(reason) => { println!("Disconnected: {reason}"); break; }
    }
}

TransportEvent

Events produced by the transport layer:

pub enum TransportEvent {
    /// The transport has successfully connected
    Connected,
    
    /// Raw data has been received from the server
    DataReceived(Bytes),
    
    /// The connection was lost, carrying why it closed
    Disconnected(DisconnectReason),
}

Since v0.6 Disconnected carries a DisconnectReason instead of being a unit variant (a breaking change for custom transports — update your match arms and the value you emit). It surfaces why the socket closed in logs, so server-initiated closes can be told apart from local shutdowns.

Event Types

Connected

Emitted immediately after successful connection establishment.

TransportEvent::Connected

DataReceived

Emitted when raw data is received from the server.

TransportEvent::DataReceived(bytes)

Fields:

bytes: Bytes - Raw data received (from the bytes crate)

Disconnected

Emitted when the connection is closed (gracefully or due to error). The attached DisconnectReason says why:

pub enum DisconnectReason {
    /// Server sent a WebSocket close frame. `code` is the RFC 6455 close
    /// code when present; `reason` is the close payload text.
    ServerClose { code: Option<u16>, reason: String },
    /// The stream ended (EOF) without a close frame.
    StreamEnded,
    /// A transport-level read error occurred.
    ReadError(String),
    /// Local shutdown — no reason available from the wire.
    Unknown,
}

DisconnectReason implements Display for human-readable logging. Custom transports should emit the most specific variant they can determine.

impl DisconnectReason {
    pub fn is_clean_shutdown(&self) -> bool {
        // ...
    }
}

is_clean_shutdown() tells a benign, server-initiated stream recycle (the normal WhatsApp reconnect path) apart from a genuine transport failure, so consumers of events::Disconnected don’t have to parse logs to classify a disconnect. It’s deliberately conservative — anything ambiguous returns false (treated as a real failure):

Variant	`is_clean_shutdown()`
`StreamEnded`	`true` — EOF with no close frame is how the WA server recycles a connection
`ServerClose` with code `None`, `Some(1000)`, or `Some(1001)`	`true` — no code, normal closure, or going-away are graceful
`ServerClose` with any other code	`false` — protocol/server error, restart, etc.
`ReadError(_)`	`false` — a transport read/IO error is always a real failure
`Unknown`	`false` — an unreported reason is never assumed benign

TransportEvent::Disconnected(reason) => {
    tracing::info!(%reason, "transport closed");
    break;
}

Tokio WebSocket transport

The default transport implementation using tokio-websockets for async WebSocket connections.

Features

Async I/O - Built on Tokio runtime
TLS support - Uses rustls with webpki-roots for certificate validation
Split architecture - Separate read/write paths for efficiency
Generic over streams - Works with any AsyncRead + AsyncWrite stream type
Automatic reconnection - Handled by higher-level Client code
Development mode - Optional danger-skip-tls-verify feature

TokioWebSocketTransportFactory

The default factory handles DNS resolution, TCP connection, and TLS. For custom connection logic, use from_websocket directly. When no custom connector is supplied via with_connector, the factory builds default_tls_connector() once, on the first call to create_transport, and retains it in a OnceLock for every subsequent dial on that factory — a reconnect no longer pays for a fresh TLS config. Retaining the connector also lets a later dial reuse resumption tickets an earlier handshake received: previously (the pre-#1245 behavior), rebuilding the config per dial discarded the resumption store — tickets and all — before the next dial could ever use it. A connector supplied explicitly via with_connector is used as-is and never touches this cache.

use whatsapp_rust_tokio_transport::TokioWebSocketTransportFactory;

// Default - connects to WhatsApp Web
let factory = TokioWebSocketTransportFactory::new();

// Custom URL
let factory = TokioWebSocketTransportFactory::new()
    .with_url("wss://custom-endpoint.example.com/ws");

// Custom TLS connector (e.g. custom CA certificates, client certs)
let factory = TokioWebSocketTransportFactory::new()
    .with_connector(my_custom_connector);

// Custom Origin header (e.g. connecting through a relay that requires its own)
let factory = TokioWebSocketTransportFactory::new()
    .with_origin("https://relay.example");

with_connector

pub fn with_connector(self, connector: Connector) -> Self

Uses a custom TLS Connector instead of the built-in default. This is the primary extension point for custom TLS configuration — for example, adding custom CA certificates or client certificates. For full proxy support, implement TransportFactory directly and use from_websocket instead. Parameters:

connector - A tokio_websockets::Connector (re-exported as whatsapp_rust::transport::Connector)

Example — custom CA certificate:

use whatsapp_rust_tokio_transport::{TokioWebSocketTransportFactory, Connector, default_tls_connector};
use tokio_rustls::TlsConnector;
use rustls::RootCertStore;
use std::sync::Arc;

// Build a custom TLS config with your own CA
let mut root_store = RootCertStore::empty();
root_store.add_parsable_certificates(my_ca_certs);

let config = rustls::ClientConfig::builder()
    .with_root_certificates(root_store)
    .with_no_client_auth();

let connector = Connector::Rustls(TlsConnector::from(Arc::new(config)));

let factory = TokioWebSocketTransportFactory::new()
    .with_connector(connector);

Use default_tls_connector() to inspect or replicate the default TLS configuration as a starting point before customizing. A connector returned by that function already carries the single-host resumption sizing described below, even when supplied via with_connector. A connector built independently with Connector::Rustls — as in the example above — does not get that sizing unless you apply it yourself.

with_origin

pub fn with_origin(self, origin: impl Into<String>) -> Self

Sends a different Origin header on the WebSocket upgrade request. The default is WHATSAPP_WEB_ORIGIN ("https://web.whatsapp.com"), and it stays correct even when with_url points at a relay or a mock — a relay that simply forwards traffic to WhatsApp should still see the same Origin a real WA Web browser would send, regardless of which host you dial. Override it only when the peer you’re connecting to — the relay itself, not WhatsApp — validates Origin against its own value. Parameters:

origin - The value to send as the Origin header

without_origin

pub fn without_origin(self) -> Self

Opens the socket with no Origin header at all — this crate’s behavior before the header was added. Use it only for a peer that rejects the upgrade because of the header; no known WhatsApp endpoint does.

default_tls_connector

pub fn default_tls_connector() -> Connector

Returns the default TLS connector used by TokioWebSocketTransportFactory. Uses rustls with webpki_roots for certificate validation and ring as the crypto provider. This is useful as a starting point when you need to inspect or replicate the default TLS configuration before customizing it via with_connector. Its session-resumption store is sized for the one host a factory dials: 8 tickets, rustls’s per-server maximum, rather than the ~32-server table (⌈256/8⌉ slots) rustls’s Resumption::default() provisions for. A connector reused across several hosts (for example, shared deliberately across factories) still works, but only the most recently dialled hosts keep their tickets; build a larger rustls::client::Resumption store yourself if that’s the shape you need. TokioWebSocketTransportFactory itself only ever dials the one URL it was built with, so the default sizing is a straight win there — see TokioWebSocketTransportFactory above for how the resulting connector is cached and reused across reconnects.

Usage with Bot builder

use whatsapp_rust::Bot;
use whatsapp_rust_tokio_transport::TokioWebSocketTransportFactory;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let factory = TokioWebSocketTransportFactory::new();
    
    let mut bot = Bot::builder()
        .with_backend(backend)
        .with_transport_factory(factory)
        .with_http_client(http_client)
        .on_event(|event, client| async move { /* handle events */ })
        .build()
        .await?;
    
    Ok(())
}

from_websocket

Wraps an already-upgraded WebSocketStream into a Transport + event channel. This is useful when you need custom connection strategies such as IPv4 preference, TCP keepalive tuning, or connecting through a proxy.

pub fn from_websocket<S>(
    ws: WebSocketStream<S>,
) -> (Arc<dyn Transport>, async_channel::Receiver<TransportEvent>)
where
    S: AsyncRead + AsyncWrite + Send + Unpin + 'static,

Parameters:

ws - An already-connected WebSocketStream over any async stream type

Returns:

Arc<dyn Transport> - The transport instance for sending data
async_channel::Receiver<TransportEvent> - Stream of transport events

The function splits the WebSocket into read/write halves, spawns a background read pump task, and synchronously enqueues a Connected event before the read pump starts — ensuring it always precedes any DataReceived events. Example — IPv4-only connection with TCP keepalive:

use whatsapp_rust_tokio_transport::from_websocket;
use tokio::net::TcpStream;
use tokio_websockets::ClientBuilder;

// Custom TCP connection with keepalive
let tcp = TcpStream::connect("web.whatsapp.com:443").await?;
tcp.set_nodelay(true)?;

let sock_ref = socket2::SockRef::from(&tcp);
let keepalive = socket2::TcpKeepalive::new()
    .with_time(Duration::from_secs(30))
    .with_interval(Duration::from_secs(10));
sock_ref.set_tcp_keepalive(&keepalive)?;

// Upgrade to WebSocket (TLS handled externally)
let (ws, _response) = ClientBuilder::from_uri("wss://web.whatsapp.com/ws/chat".parse()?)
    .connect_on(tcp)
    .await?;

// Wrap into a Transport
let (transport, events) = from_websocket(ws);

Example — using with a custom TransportFactory:

use whatsapp_rust_tokio_transport::from_websocket;
use wacore::net::{Transport, TransportEvent, TransportFactory};

struct MyTransportFactory;

#[async_trait]
impl TransportFactory for MyTransportFactory {
    async fn create_transport(
        &self,
    ) -> Result<(Arc<dyn Transport>, async_channel::Receiver<TransportEvent>), anyhow::Error> {
        // Your custom connection logic here
        let ws = establish_custom_websocket().await?;
        Ok(from_websocket(ws))
    }
}

TokioWebSocketTransportFactory itself delegates to from_websocket internally. Use the factory when the default DNS/TCP/TLS behavior is sufficient, and from_websocket when you need full control over the connection.

Proxy support

The transport layer provides two approaches for proxy support, depending on your needs: Option 1: Implement TransportFactory directly — for full control over the connection (SOCKS5, HTTP CONNECT, etc.). Establish a WebSocket through the proxy yourself, then wrap it with from_websocket:

use whatsapp_rust_tokio_transport::from_websocket;
use wacore::net::{Transport, TransportEvent, TransportFactory};

struct ProxyTransportFactory {
    proxy_url: String,
}

#[async_trait]
impl TransportFactory for ProxyTransportFactory {
    async fn create_transport(
        &self,
    ) -> Result<(Arc<dyn Transport>, async_channel::Receiver<TransportEvent>), anyhow::Error> {
        // 1. Connect to proxy
        let proxy_stream = connect_to_proxy(&self.proxy_url).await?;

        // 2. Upgrade to WebSocket through the proxy
        let (ws, _) = tokio_websockets::ClientBuilder::from_uri(
            "wss://web.whatsapp.com/ws/chat".parse()?
        )
        .connect_on(proxy_stream)
        .await?;

        // 3. Wrap into Transport
        Ok(from_websocket(ws))
    }
}

Option 2: Use with_connector — for custom TLS only (no proxy routing). The factory still handles DNS and TCP, but you control the TLS layer:

let factory = TokioWebSocketTransportFactory::new()
    .with_connector(my_custom_tls_connector);

See custom backends — proxy and custom TLS for a complete guide with examples.

TLS configuration

By default, the transport validates TLS certificates using webpki-roots:

let mut root_store = rustls::RootCertStore::empty();
root_store.extend(webpki_roots::TLS_SERVER_ROOTS.iter().cloned());

let config = rustls::ClientConfig::builder()
    .with_root_certificates(root_store)
    .with_no_client_auth();

The config’s session-resumption store is then resized down from rustls’s default (provisioned for ~32 distinct server names) to 8 tickets — a single server’s worth — since a TokioWebSocketTransportFactory only ever dials the one host it was built with. See default_tls_connector for the sizing rationale.

Development mode (skip TLS verification)

Only use for development and testing.

Enable the danger-skip-tls-verify feature to disable certificate verification:

[dependencies]
whatsapp-rust-tokio-transport = { version = "0.7", features = ["danger-skip-tls-verify"] }

This allows connecting through MITM proxies or self-signed certificates.

Connection settings

The default WebSocket URL is:

pub const WHATSAPP_WEB_WS_URL: &str = "wss://web.whatsapp.com/ws/chat";

Every upgrade created by TokioWebSocketTransportFactory also carries an Origin header by default:

pub const WHATSAPP_WEB_ORIGIN: &str = "https://web.whatsapp.com";

RFC 6455 requires a browser client to send Origin on the WebSocket handshake, and both whatsmeow and Baileys send this exact value unconditionally, regardless of the platform their ClientPayload claims. Override it with with_origin, or drop it entirely with without_origin for a peer that rejects the header.

The Client wraps create_transport() in a 20-second timeout matching WhatsApp Web’s connect timeout. The transport itself does not enforce this timeout — it is applied at the client layer. If you use a custom transport, be aware that the client will abort the connection attempt after 20 seconds regardless of the transport’s own timeout behavior.

WsTransport resource report

WsTransport overrides Transport::resource_report with static, documented estimates rather than a live measurement, since tokio-websockets and rustls don’t surface their buffer sizes: read_buffer_bytes: 16 KiB, write_buffer_bytes: 16 KiB, tls_state_bytes: 32 KiB (record buffers + key schedule for one TLS session). These give a realistic order-of-magnitude for the transport’s per-session contribution — tens of KiB — rather than an exact figure.

Internal architecture

The transport is generic over any AsyncRead + AsyncWrite stream, split into separate read/write paths:

let (sink, stream) = ws.split();

// Sink - wrapped in Arc<Mutex> for sending
let sink: Arc<Mutex<Option<Sink<S>>>> = Arc::new(Mutex::new(Some(sink)));

// Stream - moved to read_pump task with shutdown signal
tokio::task::spawn(read_pump(stream, event_tx, shutdown_rx));

The read pump uses tokio::select! with a shutdown watch channel to ensure clean termination:

async fn read_pump<S: AsyncRead + AsyncWrite + Unpin + Send + 'static>(
    mut stream: SplitStream<WebSocketStream<S>>,
    tx: async_channel::Sender<TransportEvent>,
    mut shutdown: tokio::sync::watch::Receiver<bool>,
) {
    loop {
        tokio::select! {
            biased;
            _ = shutdown.changed() => break,
            next = stream.next() => match next {
                Some(Ok(msg)) if msg.is_binary() => {
                    let payload = msg.into_payload();
                    // Shutdown-aware send to prevent blocking on full channel
                    tokio::select! {
                        biased;
                        _ = shutdown.changed() => break,
                        r = tx.send(TransportEvent::DataReceived(Bytes::from(payload))) => {
                            if r.is_err() { break; }
                        }
                    }
                }
                Some(Ok(msg)) if msg.is_close() => break,
                Some(Err(e)) => break,
                None => break,
            },
        }
    }
    let _ = tx.send(TransportEvent::Disconnected(DisconnectReason::StreamEnded)).await;
}

Implementing custom transports

You can implement custom transports for different runtimes or protocols.

Example: mock transport for testing

use async_trait::async_trait;
use std::sync::Arc;
use wacore::net::{Transport, TransportEvent, TransportFactory};

/// A mock transport that does nothing
pub struct MockTransport;

#[async_trait]
impl Transport for MockTransport {
    async fn send(&self, _data: Vec<u8>) -> Result<(), anyhow::Error> {
        // Silently succeed
        Ok(())
    }

    async fn disconnect(&self) {
        // Nothing to do
    }
}

/// Factory for creating mock transports
pub struct MockTransportFactory;

impl MockTransportFactory {
    pub fn new() -> Self {
        Self
    }
}

#[async_trait]
impl TransportFactory for MockTransportFactory {
    async fn create_transport(
        &self,
    ) -> Result<(Arc<dyn Transport>, async_channel::Receiver<TransportEvent>), anyhow::Error>
    {
        let (_tx, rx) = async_channel::bounded(1);
        Ok((Arc::new(MockTransport), rx))
    }
}

Example: TCP transport (no TLS)

use async_trait::async_trait;
use tokio::net::TcpStream;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use std::sync::Arc;
use tokio::sync::Mutex;

pub struct TcpTransport {
    writer: Arc<Mutex<tokio::io::WriteHalf<TcpStream>>>,
}

#[async_trait]
impl Transport for TcpTransport {
    async fn send(&self, data: Vec<u8>) -> Result<(), anyhow::Error> {
        let mut writer = self.writer.lock().await;
        writer.write_all(&data).await?;
        Ok(())
    }

    async fn disconnect(&self) {
        // TCP disconnect handled by drop
    }
}

pub struct TcpTransportFactory {
    address: String,
}

impl TcpTransportFactory {
    pub fn new(address: impl Into<String>) -> Self {
        Self {
            address: address.into(),
        }
    }
}

#[async_trait]
impl TransportFactory for TcpTransportFactory {
    async fn create_transport(
        &self,
    ) -> Result<(Arc<dyn Transport>, async_channel::Receiver<TransportEvent>), anyhow::Error>
    {
        let stream = TcpStream::connect(&self.address).await?;
        let (reader, writer) = tokio::io::split(stream);
        
        let (event_tx, event_rx) = async_channel::bounded(100);
        
        let transport = Arc::new(TcpTransport {
            writer: Arc::new(Mutex::new(writer)),
        });
        
        // Spawn read task
        tokio::task::spawn(async move {
            let mut reader = reader;
            let mut buf = vec![0u8; 4096];
            
            event_tx.send(TransportEvent::Connected).await.ok();
            
            loop {
                match reader.read(&mut buf).await {
                    Ok(0) => break,
                    Ok(n) => {
                        let data = bytes::Bytes::copy_from_slice(&buf[..n]);
                        if event_tx.send(TransportEvent::DataReceived(data)).await.is_err() {
                            break;
                        }
                    }
                    Err(_) => break,
                }
            }
            
            event_tx.send(TransportEvent::Disconnected(DisconnectReason::StreamEnded)).await.ok();
        });
        
        Ok((transport, event_rx))
    }
}

Best Practices

Thread Safety - On native, implementations must be Send + Sync (enforced via MaybeSendSync). On wasm32, MaybeSendSync carries no bounds, so !Send implementations backed by JS handles compile.
Error Handling - Return descriptive errors from send()
Graceful Shutdown - Implement proper cleanup in disconnect()
Event Channel Size - Use bounded channels with reasonable capacity
Read Task - Spawn a separate task for receiving data
Resource Cleanup - Ensure sockets/resources are closed on drop

Testing Transports

Unit test example

#[cfg(test)]
mod tests {
    use super::*;
    
    #[tokio::test]
    async fn test_mock_transport() {
        let factory = MockTransportFactory::new();
        let (transport, events) = factory.create_transport().await.unwrap();
        
        // Should succeed without error
        transport.send(vec![1, 2, 3]).await.unwrap();
        
        // Disconnect should be no-op
        transport.disconnect().await;
    }
    
    #[tokio::test]
    async fn test_websocket_transport() {
        let factory = TokioWebSocketTransportFactory::new();
        let (transport, mut events) = factory.create_transport().await.unwrap();
        
        // Should receive Connected event
        match events.recv().await {
            Ok(TransportEvent::Connected) => {},
            other => panic!("Expected Connected, got {:?}", other),
        }
        
        transport.disconnect().await;
    }
}

​Overview

​Transport Trait

​Methods

​send

​disconnect

​resource_report

​TransportFactory Trait

​Methods

​create_transport

​TransportEvent

​Event Types

​Connected

​DataReceived

​Disconnected

​Tokio WebSocket transport

​Features

​TokioWebSocketTransportFactory

​with_connector

​with_origin

​without_origin

​default_tls_connector

​Usage with Bot builder

​from_websocket

​Proxy support

​TLS configuration

​Development mode (skip TLS verification)

​Connection settings

​WsTransport resource report

​Internal architecture

​Implementing custom transports

​Example: mock transport for testing

​Example: TCP transport (no TLS)

​Best Practices

​Testing Transports

​Unit test example

​See Also

Overview

Transport Trait

Methods

send

disconnect

resource_report

TransportFactory Trait

Methods

create_transport

TransportEvent

Event Types

Connected

DataReceived

Disconnected

Tokio WebSocket transport

Features

TokioWebSocketTransportFactory

with_connector

with_origin

without_origin

default_tls_connector

Usage with Bot builder

from_websocket

Proxy support

TLS configuration

Development mode (skip TLS verification)

Connection settings

WsTransport resource report

Internal architecture

Implementing custom transports

Example: mock transport for testing

Example: TCP transport (no TLS)

Best Practices

Testing Transports

Unit test example

See Also