proxima_primitives/lib.rs
1//! The pipe algebra and the runtime-agnostic primitives beneath it.
2//!
3//! One trait, [`pipe::Pipe`], carries typed `In -> Out` with an associated
4//! `Err`; picking `In` or `Out` as `()` gives the four forms (transform,
5//! source, sink, observe). Everything else here composes over it or sits
6//! under it.
7//!
8//! - [`pipe`] -- [`pipe::Pipe`] and its additive `Send` form
9//! [`pipe::SendPipe`], the [`PipeExt`] combinator sugar
10//! (`.and_then`/`.filter`/`.fanout`/`.fanin`), `Request`/`Response`
11//! envelopes over `Bytes`, `HeaderList`, the streaming bodies
12//! (`ResponseStream`/`RequestStream` over `ChunkStream`) and the in-process
13//! `Carry` payload, `Handler` (`Request<Bytes> -> Response<Bytes>`),
14//! `SourcePipe`, and the resilience, rate-limit, retry, routing and
15//! telemetry/capture surfaces. Plugin authors' primary surface.
16//! - [`sync`] -- runtime-agnostic concurrency primitives shaped like
17//! `tokio::sync` (`Mutex`, `Notify`, `mpsc`, `oneshot`, `watch`,
18//! `broadcast`, plus `blocking`, `task`, `shutdown`), so no pipe needs
19//! tokio to coordinate.
20//! - [`stream`] -- byte-stream and datagram traits (`StreamConnection`,
21//! `StreamListener`, `StreamUpstream`, `DatagramSocket`) built on
22//! `futures::io`, shared by every wire-protocol stack above them.
23//! - [`transport`] -- `Replay` (record-and-replay of a stream with fan-out
24//! sinks), the `tap_complete` taps and the `GenericStream` seam; sits below
25//! [`pipe`].
26//! - [`driver`] -- [`block_on`], the no-runtime way to drive one future to
27//! completion.
28//! - [`codec`], [`block_layout`], [`float_layout`] -- data descriptions of
29//! packed numeric storage: [`Codec`] names a packed byte layout,
30//! `BlockLayout` describes a block of stored numbers, `FloatLayout` one
31//! stored float.
32//!
33//! The crate is `no_std` unless the default `std` feature is on. `pipe`
34//! splits further: the pipe forms compile with no allocator, most of the
35//! envelope and combinator surface needs `alloc`, and registries and
36//! lifecycle helpers need `std`. Each item's own doc names its tier.
37
38#![cfg_attr(not(feature = "std"), no_std)]
39
40extern crate alloc;
41
42// the test harness always links std; a no_std crate must name it explicitly
43// so `sync::blocking::futex`'s tests (compiled only when `std` is off)
44// resolve `std::`.
45#[cfg(all(test, not(feature = "std")))]
46extern crate std;
47
48pub mod block_layout;
49pub mod codec;
50pub mod driver;
51pub mod float_layout;
52pub mod pipe;
53pub mod stream;
54pub mod sync;
55pub mod transport;
56
57pub use codec::Codec;
58pub use driver::block_on;
59// Fluent combinator sugar (`.and_then`/`.filter`/`.fanout`/`.fanin`) over the
60// pipe algebra — no prelude in this crate, so callers reach it via an
61// explicit `use proxima_primitives::PipeExt`.
62pub use pipe::PipeExt;