proxima-primitives

The pipe algebra itself. Pipe is one async trait, In -> Result<Out, Err>, that becomes a transform, a source, a sink or an observe by your choice of In and Out. Everything else in proxima composes what is defined here.

Add it with cargo add proxima-primitives.

The one trait

From the Pipe doc comment (it is compiled by cargo test there):

use core::convert::Infallible;
use core::future::Future;
use proxima_primitives::pipe::Pipe;

// transform: In -> Out
struct Double;
impl Pipe for Double {
    type In = u64;
    type Out = u64;
    type Err = Infallible;
    fn call(&self, input: u64) -> impl Future<Output = Result<u64, Infallible>> {
        async move { Ok(input * 2) }
    }
}

Pipe has no Send bound, so it runs on a per-core, shared-nothing worker. The additive tiers are standalone traits: SendPipe (pipe and future are Send), UnpinPipe (the returned future is Unpin) and UnpinSendPipe. AndThen is the composition law, reached through PipeExt (use proxima_primitives::PipeExt).

What is in it

Four modules, folded together from what were separate crates:

• pipe: the Pipe family; Handler (request to response); SourcePipe (Signal -> ()); HeaderList; the payload types Carry, ResponseStream and RequestStream; and combinators and plugin surface (fan-in and fan-out, filters, retry, rate limiting, routing, and more).
• stream: sans-IO byte-stream traits (StreamConnection, StreamListener, StreamUpstream, datagram sockets) over futures::io, shared by the wire-protocol crates.
• sync: runtime-agnostic concurrency primitives shaped like tokio::sync (Mutex, Notify, mpsc, oneshot, watch, broadcast, blocking, task, shutdown, and others).
• transport: Replay (record-and-replay) and the GenericStream seam, below pipe.

Also at the root: block_on (drive a future to completion with no runtime and no allocator), Codec (a payload-less tag for a packed byte layout), and the float_layout / block_layout modules (FloatLayout, BlockLayout: data descriptions of packed numeric formats).

What it composes

• proxima-core: markers, ProximaError, time, and the registry and live-swap cells, enabled per tier.
• proxima-runtime (optional, from alloc up): the runtime traits.
• proxima-config (optional, pulled in by std with its schema-std feature).
• External: bytes, futures, serde, heapless, crossbeam-queue, portable-atomic; event-listener and async-lock from alloc; arc-swap, parking_lot, tracing, bon and conflaguration under std.

Proxima's own telemetry, clock, codec and runtime crates all sit on top of this one.

Features and tiers

Default feature: std.

• no_std, no alloc: the pipe::primitives module (Pipe, SendPipe, UnpinPipe, UnpinSendPipe, AndThen) allocates nothing and touches no std (its module doc says it compiles on a bare #![no_std] target).
• alloc: no_std + alloc floor. The pipe forms and combinators that need a heap, sync::notify, sync::oneshot, sync::shutdown (ResourceRegistry) and the async semaphore.
• std (default): implies alloc; adds sync::{mpsc, watch, broadcast, rwlock, once_cell} and Mutex, the stream traits and transport::Replay (these use futures::io and std Mutex; the alloc tier carries only stream's BindAddr / PeerInfo re-export and TcpBindOptions), and the config mirror.

Opt-in features: fan-concurrent (Race / ScatterGather), config (layered conflaguration loader for the filter registry), part-source, atomic-permits, async-mutex (waker-based async mutex that reaches bare metal), blocking (futex sync::blocking::Mutex for no_std + OS), runtime-shaped-mutex, runtime-tokio (sync::task::JoinSet), io-async and io-bridge (ring sources and sinks as AsyncRead / AsyncWrite), test-support (MockClock / RecordingClock doubles), bon, conflaguration. runtime-prime-full is empty and kept for feature forwarding.

License

MIT OR Apache-2.0.

Repository: https://github.com/brianbruggeman/proxima