nexus_async_net/
lib.rs

1//! nexus-async-net — async adapters for nexus-net.
2//!
3//! Thin async wrappers over nexus-net's synchronous protocol primitives.
4//! Same zero-copy parsing, same performance — just `.await` on I/O.
5//!
6//! # Runtime Features
7//!
8//! Exactly one async runtime must be enabled (mutually exclusive):
9//!
10//! - **`tokio-rt`** (default) — tokio-based adapters for WebSocket and REST.
11//! - **`nexus`** — nexus-async-rt-based adapters (single-threaded, pre-allocated).
12//!   *(Renamed from `nexus-rt` in v0.4.2.)*
13//!
14//! # Modules
15//!
16//! - [`ws`] — Async WebSocket (wraps FrameReader/FrameWriter).
17//!   Both backends provide `recv()`/`send_*()`. The tokio backend also
18//!   implements `Stream`/`Sink` for ecosystem integration.
19//! - [`rest`] — Async HTTP REST client (wraps RequestWriter/ResponseReader)
20//!
21//! # Custom transports
22//!
23//! `WsReader`/`WsWriter` and `HttpConnection<S>` accept any
24//! [`WireStream`](nexus_net::WireStream) — the canonical `MaybeTls`
25//! transport implements it directly. To plug a custom
26//! `AsyncRead+AsyncWrite` transport into the same API, wrap it at
27//! the call site:
28//!
29//! - tokio (`feature = "tokio-rt"`): [`AsyncReadAdapter`]
30//! - nexus-async-rt (`feature = "nexus"`): [`NexusAsyncReadAdapter`]
31//!
32//! ```ignore
33//! let tcp = tokio::net::TcpStream::connect(addr).await?;
34//! let (mut reader, mut writer, mut conn) = WsStreamBuilder::new()
35//!     .connect_with(AsyncReadAdapter::new(tcp), url)
36//!     .await?;
37//! ```
38
39#![warn(missing_docs)]
40
41#[cfg(all(feature = "tokio-rt", feature = "nexus"))]
42compile_error!("features `tokio-rt` and `nexus` are mutually exclusive — pick one async runtime");
43
44// `maybe_tls` is implementation surface for the connection builders;
45// exposed publicly only so integration tests in this crate's
46// `tests/` directory can construct `TlsInner` directly (the test
47// binary is a separate compilation unit).
48#[doc(hidden)]
49pub mod maybe_tls;
50pub mod rest;
51mod wire;
52pub mod ws;
53
54#[cfg(feature = "tokio-rt")]
55pub use wire::AsyncReadAdapter;
56#[cfg(feature = "nexus")]
57pub use wire::NexusAsyncReadAdapter;
58
59// Re-export nexus-net types that appear in our public API.
60// Users who need deeper access can depend on nexus-net directly.
61pub use nexus_net::ws::{
62    CloseCode, CloseFrame, Error as WsError, FrameReader, FrameReaderBuilder, FrameWriter,
63    HandshakeError, Message, OwnedCloseFrame, OwnedMessage, Role,
64};
65pub use nexus_net::{WireStream, buf::WriteBuf};
66
67/// REST types used in [`rest::HttpConnection`] and [`rest::ClientSlot`].
68pub mod rest_types {
69    pub use nexus_net::http::ResponseReader;
70    pub use nexus_net::rest::{Request, RequestWriter, RestError, RestResponse};
71}
72
73#[cfg(feature = "tls")]
74pub use nexus_net::tls::{TlsConfig, TlsError};
nexus_async_net/lib.rs

nexus_async_net/
lib.rs
