praxis_protocol/lib.rs
1// SPDX-License-Identifier: Apache-2.0
2// Copyright (c) 2024 Praxis Contributors
3
4#![forbid(unsafe_code)]
5#![deny(unreachable_pub)]
6#![expect(
7 clippy::arithmetic_side_effects,
8 clippy::as_conversions,
9 clippy::iter_over_hash_type,
10 clippy::min_ident_chars,
11 clippy::mod_module_files,
12 clippy::partial_pub_fields,
13 clippy::pub_underscore_fields,
14 clippy::shadow_unrelated,
15 clippy::single_char_lifetime_names,
16 clippy::wildcard_enum_match_arm,
17 reason = "TODO(conventions-sync): fix violations and remove"
18)]
19
20//! Protocol adapters for Praxis.
21//!
22//! `praxis-protocol` sits below `server` and above `filter` in the
23//! crate dependency flow `server -> protocol -> filter -> core -> tls`.
24//! It binds the [`praxis_filter`] pipeline engine to Pingora's HTTP and
25//! TCP proxy services, so that inbound connections are served, filters
26//! run at the right lifecycle points, and requests are forwarded to
27//! upstream clusters.
28//!
29//! Responsibilities:
30//! - HTTP protocol implementations and Pingora adapters ([`http`]).
31//! - Raw TCP/L4 forwarding ([`tcp`]).
32//! - Active health-check probes and admin/observability endpoints.
33//! - TLS listener setup (the `tls_setup` module), plus holding the certificate hot-reload watcher shutdown handles so
34//! those watchers can be stopped early ([`CertWatcherShutdowns`]).
35//!
36//! Boundary with Pingora: Pingora owns request-smuggling prevention,
37//! HTTP/2 backpressure, connection-pool safety, and HTTP/1.1 upgrade
38//! detection with bidirectional forwarding (WebSocket and similar).
39//! Praxis code in this crate and in [`praxis_filter`] owns hop-by-hop
40//! header stripping (with conditional preservation for upgrade
41//! requests), Host validation, `X-Forwarded-*` injection, and retry
42//! logic.
43
44mod cert_watcher_shutdowns;
45pub use cert_watcher_shutdowns::CertWatcherShutdowns;
46
47mod pipelines;
48pub use pipelines::ListenerPipelines;
49
50mod protocol;
51pub use protocol::Protocol;
52
53/// Process-wide connection limit.
54pub mod connections;
55/// HTTP protocol implementations.
56pub mod http;
57/// Raw TCP/L4 forwarding protocol.
58pub mod tcp;
59
60/// Shared TLS settings builder for HTTP and TCP listeners.
61pub(crate) mod tls_setup;