Skip to main content

Rust transport — what changed and what to watch

Starting in Whixp 3.1.0, the low-level connection, TLS, WebSocket, retry, and stanza framing moved from Dart to an optional Rust transport loaded via FFI. This page explains what you should pay attention to when using Whixp from that version onward.

What moved to Rust​

  • In Rust: TCP connect, TLS (DirectTLS and StartTLS via rustls), WebSocket (ws:// / wss://), connection retry, handshake error handling, and splitting the byte stream into XML stanzas.
  • Still in Dart: DNS resolution, high-level API (handlers, events, send queue, batching, rate limiting), and everything above the transport (stanza handling, sessions, etc.).

So: transport and framing live in Rust when the native library is present; the rest of Whixp is unchanged.

When the native lib is used​

  • If the native library is found on the current platform, Transport uses it. You do not need to import a special entrypoint for normal use; the default Whixp / Transport path uses the Rust transport when available.
  • If the library is not found, Transport construction throws with a clear message (e.g. you must build or add the binary for your OS — see Native binaries per platform).

So: users must have the correct native binary for their OS if they want the Rust transport. No binary ⇒ no Rust path; the error at construction time tells you.

What to pay attention to​

  1. Binaries per platform
    Each OS expects the built library in a specific place (e.g. macos/, linux/, windows/, Android jniLibs, iOS). If you ship or run on multiple platforms, ensure the right binary is present for each. See Native binaries per platform.

  2. Testing
    Under dart test, the native lib is not loaded by default (to avoid process kill from loading the dylib in test isolates). So normal dart test or make test does not exercise the Rust transport. To run Transport tests with the native lib:

    WHIXP_TEST_NATIVE=1 dart test test/transport_test.dart

    If the process is killed, try more heap:

    DART_VM_OPTIONS="--old_gen_heap_size=2048" WHIXP_TEST_NATIVE=1 dart test test/transport_test.dart

  3. Graceful disconnect (3.2.0+)
    On server down or connection termination, the transport tears down the native handle, emits TransportState.disconnected once, and cleans up so the app can reconnect. No special action required; just handle disconnected as before.

  4. Optional entrypoint
    If you want to depend explicitly on the native layer (e.g. for tree-shaking or clarity), you can import package:whixp/whixp_native.dart. For typical use, the default package:whixp/whixp.dart path is enough; it will use the Rust transport when the library is available.

  5. WebSocket
    Rust handles WebSocket. Use useWebSocket: true and optional wsPath (e.g. "/ws") on Transport / Whixp as documented.

Summary​

  • Version: Rust transport from 3.1.0; improvements (XCFramework, graceful disconnect, release profile) in 3.2.0 / 3.3.0.
  • User responsibility: Provide the correct native binary for each OS you target (or use a package/release that already includes them).
  • Tests: Use WHIXP_TEST_NATIVE=1 when you want to run Transport tests with the native lib.

For exact file names and paths per OS, see Native binaries per platform.