Tooling

The dev toolchain Pingora uses is conventional Rust.

Build system

Plain cargo with a workspace. The root Cargo.toml declares 21 member crates and pins shared workspace dependencies. There is no build.rs magic; no Makefile; no shell wrappers. cargo build, cargo test, cargo bench are it.

The Dockerfile at the repo root produces a build-environment image with rustup, the right toolchain, and the system libraries needed for OpenSSL/BoringSSL builds. Useful for reproducible CI runs.

Lint and format

• rustfmt — .rustfmt.toml is 17 bytes. Run cargo fmt before committing.
• clippy — clippy.toml is 14 bytes. CI runs cargo clippy --workspace -- -D warnings. The crate-level allow list (e.g. #![allow(clippy::new_without_default)]) lives in each lib.rs.

Cargo features cheat sheet

The umbrella pingora crate's feature flags:

Feature	Does what
openssl	OpenSSL TLS backend
boringssl	BoringSSL TLS backend
s2n	s2n-tls TLS backend
rustls	rustls TLS backend (experimental)
proxy	Pull in pingora-proxy
lb	Pull in pingora-load-balancing (implies proxy)
cache	Pull in pingora-cache
time	Re-export pingora-timeout
sentry	Sentry error reporting
connection_filter	Pre-TLS connection filtering
adjust_upstream_modules	Per-response module reconfiguration

Mutually exclusive: at most one TLS feature.

Documentation

• cargo doc --no-deps builds rustdoc.
• .github/workflows/docs.yml runs cargo doc on each push to verify docs build.
• The [package.metadata.docs.rs] section in pingora/Cargo.toml configures docs.rs to build with --cfg docsrs so feature gating shows up in the rendered docs.
• document-features is a build-time crate that turns the feature list in Cargo.toml into a markdown table in the generated docs.

CI workflows

.github/workflows/:

• build.yml — main matrix (stable, beta, MSRV; multiple feature combinations); runs build, test, clippy, fmt
• docs.yml — rustdoc build
• audit.yml — cargo audit
• semgrep.yml — Semgrep OSS rules (added Apr 2026)
• mark-stale.yaml — auto-marks stale issues

Release tooling

cliff.toml configures git-cliff, which is what generates CHANGELOG.md. Each release tag (0.7.0, 0.8.0, ...) produces a CHANGELOG section grouped by conventional-commit type (🚀 Features, 🐛 Bug Fixes, ⚙️ Miscellaneous Tasks).

The release process is:

1. Bump every member crate's version in lockstep.
2. Run git cliff to update CHANGELOG.md.
3. Tag the release.
4. cargo publish each crate in dependency order (the leaf crates first, then pingora-core, then pingora-proxy/pingora-cache/pingora-load-balancing, then pingora).

There's no automation tying these steps together; the maintainers run them by hand.

MSRV management

Pingora keeps a rolling MSRV of "at least six months old." The current value is 1.84 (declared in the README and pinned by the CI matrix in build.yml). MSRV bumps go through a normal PR. See commit 9855feb (Apr 2026) for the most recent change to the MSRV CI step ("use cargo check for MSRV instead of cargo test").

Scripts and helpers

Pingora has effectively zero auxiliary scripts. There's no scripts/ directory, no tools/ directory. If you need to do something repeatable that involves the workspace, you write a one-off shell command or use cargo's --workspace flag.