vortice

BEEP implementation for Rust.

Vortice implements BEEP (RFC3080/RFC3081) for Rust. It is developed by Advanced Software Production Line (ASPL) maintainers of LibVortex 1.1

Documentation

• doc/design-decisions.md — architecture and API design, with rationale
• doc/development-plan.md — phased plan with exit criteria
• doc/http-port-sharing.md — running BEEP and HTTP on the same port

Crates

Crate	Contents
vortice-proto	Sans-IO core: framing, greetings, channel management, flow control and the session state machine. no_std + alloc, no unsafe
vortice	Async sessions over tokio: client, server, profile router
vortice-http	BEEP reached through an HTTP/1.1 upgrade, so it shares a port with an HTTP server
vortice-ws	BEEP over WebSocket (RFC6455), which reaches through infrastructure that only passes web traffic. Also shares a port with plain BEEP
vortice-tls	The BEEP TLS profile (RFC3080 §3.1) over rustls: a session begins in the clear and is tuned in band
vortice-interop	Test harness driving the LibVortex regression suite. Not published

vortice-ws has no optional features and no WebSocket dependency: the binding needs to receive text frames without validating UTF-8, which is what LibVortex sends and what a conforming library refuses, so the framing is implemented here.

vortice has one optional feature, tower, which lets a profile be served by a tower::Service so that any middleware written for tower — timeouts, retries, rate limits, tracing — applies to it unchanged. vortice-http has axum, which adds the BeepUpgrade extractor; without it the crate still works through serve_upgraded.

More crates are added as their phase in the development plan arrives.

Build and test

cargo test                      # unit tests and doctests
cargo clippy --all-targets      # warnings are errors in CI

Conformance is checked against a built LibVortex 1.1 checkout, whose regression suite is the oracle for this project:

export VORTICE_LIBVORTEX_TEST_DIR=/path/to/libvortex-1.1/test
cargo test

Without that variable the interop tests report themselves as skipped rather than failing. Do not read a skipped run as a passing one.

The regression suite binds fixed ports, so these tests shift them by 1000 through the suite's own --offset-port option. That keeps them clear of a suite someone is running by hand on the default ports, and of any listener an earlier run left behind. Set VORTICE_LIBVORTEX_PORT_OFFSET to move them somewhere else.

Fuzzing the frame decoder and the greeting parser (needs nightly and cargo-fuzz):

cd vortice-proto/fuzz
cargo +nightly fuzz run decode_frames