proxima-lib 0.1.0

A sans-IO core where everything is a Pipe — one async In -> Result<Out, Err> trait worn four ways (transform, source, sink, observe), composed into proxies, gateways, caches, codecs and telemetry pipelines. Config-driven, runtime-agnostic: the same pipe runs on the from-scratch Prime per-core runtime, on tokio, or on no_std bare metal.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219

//! Compile-checks every ```rust fenced block in `docs/tutorials/*.md`.
//!
//! `docs/tutorials/00-foundations.md` states its own contract: "every code
//! block below is copied verbatim from a real file in this repository —
//! either a doctest that `cargo test` compiles, a unit test, or a runnable
//! `examples/*/main.rs`". Nothing enforced that claim: `cargo test --doc`
//! never saw the tutorials at all, so a snippet could go stale the moment
//! the API it cites was renamed and nothing would fail.
//!
//! `#[cfg(doctest)]` items are only visible while rustdoc is extracting
//! doctests FROM this crate — they never link into a normal build, and (this
//! was verified empirically, not assumed) they are also invisible to the
//! doctest's own compiled snippet, which links against an ordinarily-built
//! `proxima` rlib. So `tutorial_gate_prelude` below is deliberately NOT
//! `cfg(doctest)`-gated: it is a real, always-compiled, `#[doc(hidden)]`
//! module of re-exports a fragment excerpted from a real file (which elides
//! its own imports "for space", per the tutorials' own convention) needs to
//! resolve. Each `docs/tutorials/*.md` line 5 words the same way: the
//! visible tutorial text never changes; `scripts/tutorials-gate.sh` writes a
//! transformed copy of each file into `.tutorial-gate-generated/` before
//! this compiles — untagged fences (terminal transcripts) retagged `text` so
//! rustdoc does not try to compile them, and one hidden
//! `# use proxima::tutorial_gate_prelude::*;` line injected after every
//! opening ` ```rust ` fence. Run `scripts/tutorials-gate.sh` before
//! `cargo test --doc`; without it these `include_str!` targets do not exist
//! and the crate fails to compile under `--doc`, which is the correct, loud
//! failure rather than a silently-skipped gate.
//!
//! The module count below must track `docs/tutorials/*.md` 1:1 (minus
//! `README.md`, which carries no code) — `scripts/tutorials-gate.sh` asserts
//! this so a new tutorial file can never land ungated.

#[doc(hidden)]
pub mod tutorial_gate_prelude {
    #[cfg(feature = "recording")]
    pub use crate::RecordUpstream;
    pub use crate::app::{App, IntoMountTarget, MountTarget, RunConfig};
    pub use crate::listen::ListenerSpec;
    pub use crate::listen::admission::{BlacklistConfig, ConnAdmission};
    pub use crate::listen::any::AnyHandler;
    pub use crate::prelude::*;
    #[cfg(feature = "runtime-tokio")]
    pub use crate::runtime::TokioPerCoreRuntime;
    pub use crate::runtime::{BackgroundHandle, BackgroundPool, CoreId, Runtime, SpawnError};
    pub use crate::runtime::{RuntimeBackend, RuntimeSelection};
    pub use crate::selection::Selection;
    pub use crate::server::Server;
    pub use crate::shutdown::ShutdownBarrier;
    pub use crate::upstreams::KvUpstream;
    #[cfg(feature = "recording")]
    pub use crate::{
        AccumulatingSink, DeferredRuntime, DynRecordingSink, FormatKind, HttpEvent, JsonlSource,
        LazyFanOut, ProtocolEvent, RecordingSource, SinkSpec, deferred_runtime,
    };
    pub use crate::{
        Fallthrough, KvCache, KvCaps, KvHandle, SynthUpstream, UpstreamRef, WriteBack,
    };
    pub use crate::{ListenProtocol, LoadContext, PipeFactoryRegistry, ServeContext};
    pub use crate::{PeerInfo, StreamConnection};
    pub use crate::{ProximaError, ProximaResult, Request, RequestBuilder, Response};
    // every one of these is `cfg(any(feature = "macros", test))` at the root;
    // an ungated re-export here broke any consumer building without `macros`
    #[cfg(any(feature = "macros", test))]
    pub use crate::{fanin, fanout, filter, fixture, instrument, main, pipe, piped, span, test};
    pub use bon::Builder;
    pub use bytes::Bytes;
    pub use conflaguration::{Settings, Validate, ValidationMessage};
    pub use futures::executor::block_on;
    pub use proxima_config::sugar::SpecBuilder;
    pub use proxima_core::markers::DropSafe;
    pub use proxima_core::signal::Signal;
    pub use proxima_net::packet::PacketListenerFactory;
    pub use proxima_primitives::pipe::DrainSink;
    pub use proxima_primitives::pipe::DrainState;
    pub use proxima_primitives::pipe::capabilities::Retryable;
    pub use proxima_primitives::pipe::demand::{
        AlwaysArmed, AtomicGate, AtomicGateController, Demand,
    };
    pub use proxima_primitives::pipe::ext::PipeExt;
    pub use proxima_primitives::pipe::fan_in::{Exhausted, FanIn, FanInStrategy, Select};
    pub use proxima_primitives::pipe::fanout::FanOut;
    pub use proxima_primitives::pipe::handler::{Handler, PipeHandle, into_handle};
    pub use proxima_primitives::pipe::pipe_factory::{DynPipeFactory, PipeFactory};
    pub use proxima_primitives::pipe::plugin::PluginRegistry;
    pub use proxima_primitives::pipe::primitives::{
        AndThen, Pipe, SendPipe, UnpinPipe, UnpinSendPipe,
    };
    pub use proxima_primitives::pipe::resilience::{
        Backoff, CircuitBreaker, CircuitState, Deadline, Fallback, Jitter, RetryAction,
        RetryController,
    };
    pub use proxima_primitives::pipe::retry_rules::RetryRules;
    pub use proxima_primitives::pipe::routing::MethodFilter;
    pub use proxima_primitives::stream::{
        AcceptorFactory, DatagramFactory, TcpAcceptor, TcpBindOptions, UnixUpstreamFactory,
    };
    pub use serde::{Deserialize, Serialize};
    pub use serde_json::Value;
    pub use std::cell::{Cell, RefCell};
    pub use std::collections::VecDeque;
    pub use std::convert::Infallible;
    pub use std::fmt::Debug;
    pub use std::future::Future;
    pub use std::net::{Ipv4Addr, SocketAddr};
    pub use std::ops::ControlFlow;
    pub use std::pin::Pin;
    pub use std::sync::Arc;
    pub use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
    pub use std::task::{Context, Poll, Waker};
    pub use std::time::Duration;

    #[cfg(all(
        feature = "runtime-prime-executor",
        feature = "runtime-prime-inbox-alloc",
        feature = "runtime-prime-reactor",
        feature = "runtime-prime-bgpool"
    ))]
    pub use crate::prime::PrimeRuntime;
}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/00-foundations.md")]
mod tutorial_00_foundations {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/01-ergonomics.md")]
mod tutorial_01_ergonomics {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/02-listener-builder.md")]
mod tutorial_02_listener_builder {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/03-native-runtime.md")]
mod tutorial_03_native_runtime {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/04-listener-hello.md")]
mod tutorial_04_listener_hello {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/05-listener-universal.md")]
mod tutorial_05_listener_universal {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/06-listener-production.md")]
mod tutorial_06_listener_production {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/07-sugar-composition.md")]
mod tutorial_07_sugar_composition {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/08-protocol-fleet.md")]
mod tutorial_08_protocol_fleet {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/09-extend-your-own-protocol.md")]
mod tutorial_09_extend_your_own_protocol {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/10-conflaguration.md")]
mod tutorial_10_conflaguration {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/11-any-transport-agnostic.md")]
mod tutorial_11_any_transport_agnostic {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/build-a-bare-metal-pipe.md")]
mod tutorial_build_a_bare_metal_pipe {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/build-a-caching-reverse-proxy.md")]
mod tutorial_build_a_caching_reverse_proxy {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/build-a-chaos-test-rig.md")]
mod tutorial_build_a_chaos_test_rig {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/build-a-crud-origin-service.md")]
mod tutorial_build_a_crud_origin_service {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/build-a-kafka-style-partitioner.md")]
mod tutorial_build_a_kafka_style_partitioner {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/build-a-load-balancer.md")]
mod tutorial_build_a_load_balancer {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/build-a-multi-runtime-service.md")]
mod tutorial_build_a_multi_runtime_service {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/build-a-plugin.md")]
mod tutorial_build_a_plugin {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/build-a-record-replay-harness.md")]
mod tutorial_build_a_record_replay_harness {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/build-an-api-gateway.md")]
mod tutorial_build_an_api_gateway {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/build-an-observability-pipeline.md")]
mod tutorial_build_an_observability_pipeline {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/build-delivery-guarantees.md")]
mod tutorial_build_delivery_guarantees {}

#[cfg(all(doctest, tutorial_gate))]
#[doc = include_str!("../.tutorial-gate-generated/outbound-tls-roots.md")]
mod tutorial_outbound_tls_roots {}