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