weida/
lib.rs

1//! weida: a QUIC-native messaging framework.
2//!
3//! This crate hosts the runtime, the native QUIC transport, the raw stream core
4//! and the brokerless messaging patterns: Req/Rep, Push/Pull, Pub/Sub, PAIR,
5//! SURVEY and BUS — the whole nanomsg set, none of which adds wire
6//! vocabulary. A completion is a **cursor**: a level plus an absolute byte
7//! offset, reported on a unidirectional stream of its own
8//! ([`Cursors`], [`Reporter`]).
9//! `docs/ARCHITECTURE.md` describes the layer model,
10//! `docs/PROTOCOL.md` is the normative wire specification, and
11//! `docs/FAILURE_MODEL.md` defines what each outcome means.
12//!
13//! ```no_run
14//! use weida::{Runtime, RuntimeConfig, TransferMeta, Trust};
15//!
16//! # async fn example() -> weida::Result<()> {
17//! let runtime = Runtime::new(RuntimeConfig::default())?;
18//!
19//! // Trust belongs to the dialling endpoint, not to the runtime. Here the
20//! // address itself names the peer's public key, so nothing else is needed.
21//! let requester = runtime.requester(Trust::by_address());
22//! requester
23//!     .connect("weida://sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08@127.0.0.1:7443/transform")
24//!     .await?;
25//!
26//! // One bidirectional stream: the request half and the reply half. The
27//! // stream is the correlation, so nothing on the wire names the exchange.
28//! let (mut transfer, reply) = requester.open(TransferMeta::default()).await?;
29//! transfer.write_all(b"hello weida").await?;
30//! transfer.finish()?;
31//!
32//! let body = reply.recv().await?.collect(64 * 1024).await?;
33//! println!("{}", String::from_utf8_lossy(&body));
34//! # Ok(())
35//! # }
36//! ```
37//!
38//! The example above runs on the caller's ambient Tokio reactor. A caller
39//! that has none — or whose executor is not Tokio at all — uses
40//! [`Runtime::owned`] instead: the runtime then owns the reactor `quinn`
41//! needs, and every task, timer and name lookup weida performs runs there,
42//! while the futures it hands back may be driven by any executor. Transfer
43//! payloads implement both the `tokio::io` and the `futures-io` traits for
44//! the same reason.
45
46#[cfg(feature = "blocking")]
47pub mod blocking;
48
49// The chunk framing both socket transports share (B-245): a named pipe has no
50// half-close and a unix socket has no abort, so the end of a payload is a
51// frame rather than a socket state.
52#[cfg(any(unix, windows))]
53mod chunked;
54mod config;
55mod conn;
56mod cursor;
57mod dedup;
58mod drain;
59mod endpoint;
60#[cfg(any(unix, windows))]
61mod grouped;
62mod identity;
63mod inproc;
64mod listener;
65mod ordering;
66#[cfg(windows)]
67mod pipe;
68mod pool;
69mod pubsub;
70mod reconnect;
71mod runtime;
72mod stream;
73mod tls;
74mod transfer;
75mod transport;
76#[cfg(unix)]
77mod unix;
78
79pub use config::{ClientTls, Discovery, Identity, Pem, RuntimeConfig, ServerTls, Trust};
80pub use cursor::{CursorSet, Cursors, Reported, Reporter};
81pub use drain::Drained;
82pub use endpoint::{
83    Bus, BusMember, Endpoint, Pair, Paired, Pattern, Pub, Publisher, Pull, Puller, Push, Pusher,
84    Rep, Replier, Req, Requester, Respond, Respondent, Sub, Subscriber, Survey, SurveyRun,
85    Surveyor,
86};
87pub use identity::{FilesOptions, IdentityEvent, IdentityEvents, IdentitySource, TrustSource};
88#[cfg(windows)]
89pub use listener::PipeBinding;
90#[cfg(unix)]
91pub use listener::UnixBinding;
92pub use listener::{Binding, Listener, LocalBinding};
93pub use ordering::Gap;
94pub use pubsub::{FanOut, TopicDrops};
95pub use weida_core::DEFAULT_PORT;
96pub use weida_core::{
97    Address, EndpointAddr, Error, ErrorCode, Fingerprint, InprocAddr, Limits, LocalPrincipal,
98    LossCause, PeerIdentity, PipeAddr, Result, StopReason, TraceContext, UnixAddr,
99    WindowsPrincipal,
100};
101pub use weida_protocol::{ALPN, VERSION, codes, filter};
102pub use weida_runtime::{Resolved, Resolver, SharedResolver, SystemResolver};
103// `Delivery` keeps its transfer-receipt meaning at this level, so the
104// dimension of the same name is re-exported under the name the guarantee
105// documents use for it.
106pub use reconnect::{GiveUp, OutboxFull, PeerEvent, PeerEvents, ReconnectPolicy};
107pub use runtime::Runtime;
108pub use stream::{Acceptor, Consumer, ConsumerId, CreditGrant, Incoming, Peer};
109pub use transfer::{
110    Delivery, IncomingMeta, IncomingRequest, IncomingTransfer, OutgoingTransfer, ReplyStream,
111    TransferMeta, new_trace,
112};
113pub use weida_protocol::header::{
114    Acknowledgement, Backpressure, CursorLevel, Deduplication, Delivery as DeliveryLevel,
115    Durability, GuaranteeSet, OrderingMode, ProducerNaming, ReportMode,
116};
weida/lib.rs

weida/
lib.rs
