pingora_core/
lib.rs

1// Copyright 2026 Cloudflare, Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15#![warn(clippy::all)]
16#![allow(clippy::new_without_default)]
17#![allow(clippy::type_complexity)]
18#![allow(clippy::match_wild_err_arm)]
19#![allow(clippy::missing_safety_doc)]
20#![allow(clippy::upper_case_acronyms)]
21
22//! # Pingora
23//!
24//! Pingora is a collection of service frameworks and network libraries battle-tested by the Internet.
25//! It is to build robust, scalable and secure network infrastructures and services at Internet scale.
26//!
27//! # Features
28//! - Http 1.x and Http 2
29//! - Modern TLS with OpenSSL or BoringSSL (FIPS compatible)
30//! - Zero downtime upgrade
31//!
32//! # Usage
33//! This crate provides low level service and protocol implementation and abstraction.
34//!
35//! If looking to build a (reverse) proxy, see [`pingora-proxy`](https://docs.rs/pingora-proxy) crate.
36//!
37//! # Optional features
38//!
39//! ## TLS backends (mutually exclusive)
40//! - `openssl`: Use OpenSSL as the TLS library (default if no TLS feature is specified)
41//! - `boringssl`: Use BoringSSL as the TLS library (FIPS compatible)
42//! - `rustls`: Use Rustls as the TLS library
43//!
44//! ## Additional features
45//! - `connection_filter`: Enable early TCP connection filtering before TLS handshake.
46//!   This allows implementing custom logic to accept/reject connections based on peer address
47//!   with zero overhead when disabled.
48//! - `sentry`: Enable Sentry error reporting integration
49//! - `patched_http1`: Enable patched HTTP/1 parser
50//!
51//! # Connection Filtering
52//!
53//! With the `connection_filter` feature enabled, you can implement early connection filtering
54//! at the TCP level, before any TLS handshake or HTTP processing occurs. This is useful for:
55//! - IP-based access control
56//! - Rate limiting at the connection level
57//! - Geographic restrictions
58//! - DDoS mitigation
59//!
60//! ## Example
61//!
62//! ```rust,ignore
63//! # #[cfg(feature = "connection_filter")]
64//! # {
65//! use async_trait::async_trait;
66//! use pingora_core::listeners::ConnectionFilter;
67//! use std::net::SocketAddr;
68//! use std::sync::Arc;
69//!
70//! #[derive(Debug)]
71//! struct MyFilter;
72//!
73//! #[async_trait]
74//! impl ConnectionFilter for MyFilter {
75//!     async fn should_accept(&self, addr: &SocketAddr) -> bool {
76//!         // Custom logic to filter connections
77//!         !is_blocked_ip(addr.ip())
78//!     }
79//! }
80//!
81//! // Apply the filter to a service
82//! let mut service = my_service();
83//! service.set_connection_filter(Arc::new(MyFilter));
84//! # }
85//! ```
86//!
87//! When the `connection_filter` feature is disabled, the filter API remains available
88//! but becomes a no-op, ensuring zero overhead for users who don't need this functionality.
89
90// This enables the feature that labels modules that are only available with
91// certain pingora features
92#![cfg_attr(docsrs, feature(doc_cfg))]
93
94pub mod apps;
95pub mod connectors;
96pub mod listeners;
97pub mod modules;
98pub mod protocols;
99pub mod server;
100pub mod services;
101pub mod upstreams;
102pub mod utils;
103
104pub use pingora_error::{ErrorType::*, *};
105
106// If both openssl and boringssl are enabled, prefer boringssl.
107// This is to make sure that boringssl can override the default openssl feature
108// when this crate is used indirectly by other crates.
109#[cfg(feature = "boringssl")]
110pub use pingora_boringssl as tls;
111
112#[cfg(feature = "openssl")]
113pub use pingora_openssl as tls;
114
115#[cfg(feature = "rustls")]
116pub use pingora_rustls as tls;
117
118#[cfg(feature = "s2n")]
119pub use pingora_s2n as tls;
120
121#[cfg(not(feature = "any_tls"))]
122pub use protocols::tls::noop_tls as tls;
123
124pub mod prelude {
125    pub use crate::server::configuration::Opt;
126    pub use crate::server::Server;
127    pub use crate::services::background::background_service;
128    pub use crate::upstreams::peer::HttpPeer;
129    pub use pingora_error::{ErrorType::*, *};
130}
pingora_core/lib.rs

pingora_core/
lib.rs
