pingora-core

Active contributors: ewang, yuchen, kevinbartlett, andrew

Purpose

Pingora's foundation. Contains the Server and Service types, the L4 listener and connector machinery, HTTP/1 and HTTP/2 protocol implementations, the upstream Peer abstraction, and the module system. Everything else in the workspace depends on this crate.

Directory layout

pingora-core/src/
├── apps/                Server-app traits (HttpServerApp, ServerApp)
├── connectors/          Outbound connections (L4, HTTP, TLS)
│   ├── http/            HTTP client connector
│   ├── l4.rs            TCP/UDS dialer
│   ├── tls/             TLS client side
│   └── offload.rs       CPU-offload helper
├── listeners/           Inbound listeners
│   ├── l4.rs            TCP/UDS acceptor
│   ├── tls/             TLS acceptor
│   └── connection_filter.rs   Pre-TLS allow/deny
├── modules/             Per-request middleware
│   └── http/            HTTP modules (compression today)
├── protocols/           Wire protocols
│   ├── http/v1/         HTTP/1 client+server
│   ├── http/v2/         HTTP/2 client+server
│   ├── http/custom/     Encapsulated/custom HTTP transport
│   ├── http/subrequest/ Subrequest framing
│   ├── l4/              L4 stream abstraction
│   ├── tls/             TLS stream abstraction
│   ├── digest.rs        Connection digests (peer info, RTT, ciphers)
│   └── raw_connect.rs   Raw CONNECT tunnel
├── server/              Server lifecycle
│   ├── mod.rs           ExecutionPhase, Server, run_forever
│   ├── configuration/   Opt (CLI), ServerConf (YAML)
│   ├── daemon.rs        Daemonization
│   └── transfer_fd/     Graceful FD handoff
├── services/            Listener and background services
├── upstreams/           Peer types
│   └── peer.rs          HttpPeer, BasicPeer
├── tls/                 TLS backend dispatch shim
├── utils/               Misc helpers
└── lib.rs               Top-level re-exports

Key abstractions

Type	File	What it is
Server	pingora-core/src/server/mod.rs	Process owner; spawns services, handles signals
ExecutionPhase	pingora-core/src/server/mod.rs	Lifecycle states from Setup through Terminated
Opt, ServerConf	pingora-core/src/server/configuration/	CLI args and YAML config
Service<A>	pingora-core/src/services/mod.rs	Listener service generic over an app
BackgroundService	pingora-core/src/services/ (via re-export)	Periodic non-listener service
HttpServerApp, ServerApp	pingora-core/src/apps/	Traits the proxy/echo apps implement
Stream	pingora-core/src/protocols/mod.rs	Boxed async-readable+writable transport
ServerSession, ClientSession	pingora-core/src/protocols/http/	Downstream/upstream HTTP sessions
HttpPeer, BasicPeer	pingora-core/src/upstreams/peer.rs	Connection target + TLS settings
Connector<C>	pingora-core/src/connectors/http/mod.rs	Outbound HTTP connection factory
HttpModuleCtx	pingora-core/src/modules/http/mod.rs	Per-request module context
TransportStack	pingora-core/src/listeners/mod.rs	Listener + TLS acceptor + listen FDs

How it works

Server bootstrap

graph TD
    new[Server::new] --> bootstrap[Server::bootstrap]
    bootstrap --> readyaml[Read YAML config]
    bootstrap --> daemonize[Optional: daemonize]
    bootstrap --> fds[Acquire listen FDs<br/>maybe from old process]
    fds --> run[Server::run_forever]
    run --> spawnall[Spawn one runtime<br/>per service]
    spawnall --> dag[Resolve service<br/>dependency DAG]
    dag --> running[Phase: Running]
    running --> sig{Signal}
    sig -->|SIGTERM| graceful[Graceful shutdown]
    sig -->|SIGQUIT + new --upgrade| upgrade[Hand off FDs]

Key methods (all in pingora-core/src/server/mod.rs):

• Server::new(Option<Opt>) — construct, optionally parse CLI
• Server::bootstrap() — read config, daemonize, acquire FDs
• Server::add_service(impl IntoService) — register a service
• Server::run_forever() — block until termination

The EXIT_TIMEOUT (300s) and CLOSE_TIMEOUT (5s) constants control shutdown gracefulness.

Listeners and connectors

Listeners build a Vec<TransportStack> from Endpoints declared via Service::add_tcp(addr), add_uds(path), or add_tls(addr, settings). Each transport stack is (socket, optional TLS acceptor, optional listen FD). At service start, the service spawns one tokio task per stack.

Connectors do the reverse: dial outbound. The Connector (in connectors/http/mod.rs) provides connection pooling, optional TLS, and HTTP/1 vs HTTP/2 dispatch, and is the type the proxy uses to talk to upstreams.

Sessions

ServerSession (downstream) and ClientSession (upstream) are enums over the underlying protocol version. The proxy handles them generically; protocol-specific code lives in protocols/http/v1/server.rs, v1/client.rs, v2/server.rs, v2/client.rs, etc.

HttpTask (protocols/http/mod.rs) is the task enum that flows through the proxy: Header, Body(Bytes, end), Trailer, UpgradedBody(Bytes) (added in 0.7.0), Done, Failed(Error).

Modules

A module (modules/http/mod.rs) is a small unit of per-request behavior. Modules see the request at request_filter, see the response header before/after upstream, and can transform the response body. The current built-in is response compression (modules/http/compression). Users register modules per session.

The adjust_upstream_modules cargo feature adds a hook to reconfigure upstream modules based on the response header (added in 0.7.0).

Configuration

YAML keys are documented in docs/user_guide/conf.md. The struct is ServerConf (server/configuration/mod.rs). The CLI struct is Opt. They're parsed via clap (Opt) and serde_yaml (ServerConf).

The "User defined configuration" pattern: any unknown YAML keys are ignored, so projects can add their own keys to the same file and parse them separately.

Integration points

• Imported by every other crate in the workspace (directly or transitively).
• Public types re-exported via pingora::* and pingora::prelude::*.
• TLS backend selected via the openssl/boringssl/rustls/s2n cargo features.

Entry points for modification

• New protocol or transport → add a module under protocols/ and integrate via the Stream trait.
• New listener type → add to listeners/ and update Service::add_*.
• New module → add under modules/http/ following the compression module's shape.
• Server lifecycle change → server/mod.rs. Touching this file is high-blast-radius; add to ExecutionPhase rather than reordering.

Key source files

File	Purpose
pingora-core/src/server/mod.rs	Server lifecycle, ExecutionPhase, run_forever
pingora-core/src/services/mod.rs	Service, BackgroundService, dependency graph
pingora-core/src/listeners/mod.rs	TransportStack, listener wiring
pingora-core/src/listeners/l4.rs	TCP/UDS acceptor
pingora-core/src/connectors/mod.rs	Outbound connection orchestration
pingora-core/src/connectors/http/mod.rs	HTTP-aware Connector
pingora-core/src/protocols/http/v1/	HTTP/1 client + server
pingora-core/src/protocols/http/v2/	HTTP/2 client + server
pingora-core/src/upstreams/peer.rs	HttpPeer, BasicPeer
pingora-core/src/modules/http/mod.rs	Module trait
pingora-core/src/server/configuration/	Opt, ServerConf, YAML schema
pingora-core/src/server/transfer_fd/	Graceful FD handoff over Unix socket
pingora-core/src/lib.rs	Top-level re-exports