pingora

Active contributors: ewang, yuchen, kevinbartlett

Purpose

The umbrella crate. It pulls in the rest of the workspace and re-exports the public API behind feature flags. Most users cargo add pingora and never depend on the lower-level crates directly.

Directory layout

pingora/
├── Cargo.toml          Feature flags + dependency wiring
├── src/lib.rs          ~100 lines of pub use re-exports
└── examples/           Several runnable example binaries

Key abstractions

Nothing original — pingora's job is composition, not implementation. From pingora/src/lib.rs:

pub use pingora_core::*;

pub mod http { pub use pingora_http::*; }

#[cfg(feature = "cache")]
pub mod cache { pub use pingora_cache::*; }

#[cfg(feature = "lb")]
pub mod lb { pub use pingora_load_balancing::*; }

#[cfg(feature = "proxy")]
pub mod proxy { pub use pingora_proxy::*; }

#[cfg(feature = "time")]
pub mod time { pub use pingora_timeout::*; }

pub mod prelude {
    pub use pingora_core::prelude::*;
    pub use pingora_http::prelude::*;
    pub use pingora_timeout::*;
    // ... feature-gated re-exports
}

Users do use pingora::prelude::*; to pull Server, Result, HttpPeer, ProxyHttp, Session, and the rest into scope.

Feature flags

Every flag does one of three things: select a TLS backend, opt into an upstream/cache/lb/timeout module, or toggle a behavioral feature.

Flag	Effect
openssl, boringssl, s2n, rustls	Pick a TLS backend (mutually exclusive)
proxy	Include pingora_proxy
lb	Include pingora_load_balancing (implies proxy)
cache	Include pingora_cache
time	Re-export pingora_timeout
sentry	Wire pingora_core into Sentry
connection_filter	Pre-TLS connection filtering
adjust_upstream_modules	The adjust_upstream_modules() proxy phase
patched_http1	Use the patched httparse for HTTP/1
trace	Enable cache + proxy tracing spans
document-features	Auto-generate the feature table in rustdoc

How it works

pingora's Cargo.toml declares each lower crate as optional = true and turns it on via feature combinations. Compile-time:

graph TD
    user["User: cargo add pingora --features 'lb proxy openssl'"]
    pingora[pingora]
    pcore[pingora-core]
    pproxy[pingora-proxy]
    plb[pingora-load-balancing]
    popenssl[pingora-openssl]
    user --> pingora
    pingora --> pcore
    pingora --> pproxy
    pingora --> plb
    pcore --> popenssl
    pproxy --> pcore
    plb --> pcore

The pingora_core/openssl, pingora_proxy?/openssl, etc. feature unification ensures every transitively-included crate uses the same TLS backend.

Examples

pingora/examples/ ships a handful of runnable binaries:

• A simple TCP echo server
• A Unix-domain-socket variant
• A custom-protocol server illustrating non-HTTP use

The headline example for proxy users is pingora-proxy/examples/load_balancer.rs, walked through in docs/quick_start.md.

Integration points

• Re-exports types from pingora-core, pingora-http, pingora-cache, pingora-load-balancing, pingora-proxy, pingora-timeout.
• Is the recommended dependency for downstream users.

Entry points for modification

• Adding a new feature flag → edit pingora/Cargo.toml and add a #[cfg(feature = "...")] re-export in src/lib.rs.
• Bumping the workspace version → bump every member crate, including this one.

Key source files

File	Purpose
pingora/src/lib.rs	All re-exports + prelude
pingora/Cargo.toml	Feature gating, the canonical "what features exist" list
pingora/examples/	Runnable example binaries