confium_net_ws/
lib.rs

1#![allow(rustdoc::broken_intra_doc_links)]
2#![allow(rustdoc::bare_urls)]
3#![allow(rustdoc::redundant_explicit_links)]
4#![allow(rustdoc::private_intra_doc_links)]
5#![allow(rustdoc::invalid_html_tags)]
6
7//! WebSocket transport for Confium.
8//!
9//! `ws://host:port[/path]` and `wss://host:port[/path]` URLs address a
10//! peer reachable over a WebSocket connection (RFC 6455). A
11//! [`WsListener`] bound via `ws://0.0.0.0:port` accepts inbound
12//! connections and yields [`WsTransport`] handles on
13//! [`confium_net::Listener::accept`].
14//!
15//! WebSocket is a natural fit for browser- or cloud-hosted threshold
16//! parties: it tunnels cleanly through HTTP infrastructure (proxies,
17//! load balancers, TLS terminators) while still carrying arbitrary
18//! binary protocol messages. Each [`confium_net::Transport::send`] is
19//! delivered as one WebSocket binary frame so the
20//! "one `send` == one `recv`" contract holds — message framing is
21//! native to the WebSocket protocol, no length-prefix layer is needed
22//! (unlike the raw-TCP transport in `confium-net-tcp`).
23//!
24//! `wss://` enables TLS via rustls using the platform's native CA
25//! store (the `rustls-tls-native-roots` feature of `tungstenite`).
26//! Server-side `wss://` (TLS termination at the listener) is not
27//! implemented in this crate; deploy a TLS-terminating reverse proxy
28//! (nginx, Caddy, an HTTP load balancer) in front of a plain
29//! `ws://` listener instead.
30//!
31//! See `TODO.roadmap/05-networking-primitives.md` for the design and
32//! the `confium_net` crate for the trait definitions.
33//!
34//! # Schemes
35//!
36//! - `ws` — plain WebSocket over TCP.
37//! - `wss` — TLS-protected WebSocket (client side only; see note
38//!   above).
39
40pub mod listener;
41pub mod transport;
42
43pub use listener::WsListener;
44pub use transport::WsTransport;
45pub use transport::WsTransportKind;
46
47use confium_net::register_transport;
48
49// One kind owns both schemes, mirroring how the built-in `InprocKind`
50// owns the `inproc` scheme. `register_transport!` submits it to the
51// link-time inventory so `confium_net::connect` /
52// `confium_net::listen` can dispatch to it by scheme.
53register_transport!(WsTransportKind);
confium_net_ws/lib.rs

confium_net_ws/
lib.rs
