# cloudflare/pingora architecture

> Architecture diagram of the GitHub repository cloudflare/pingora, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloudflare/pingora
- Repository: https://github.com/cloudflare/pingora

## Overview

Pingora is a Rust framework for building programmable network services, especially HTTP proxies. The principal workflow is a client request accepted by a server, decoded as HTTP, handled by proxy logic, routed to an upstream, and returned to the client. The workspace also provides load balancing, caching, TLS options, and observability integrations. The graph preserves major documented capabilities; several links use README-level evidence because the corresponding runtime wiring was not sampled.

Main entry points: [`pingora-proxy/src/lib.rs`](https://github.com/cloudflare/pingora/blob/main/pingora-proxy/src/lib.rs) (Proxy framework), [`pingora-core/src/server`](https://github.com/cloudflare/pingora/tree/main/pingora-core/src/server) (Server and listeners), [`pingora-cache/src/storage.rs`](https://github.com/cloudflare/pingora/blob/main/pingora-cache/src/storage.rs) (Cache storage), [`pingora-core/src/protocols/http/v1/server.rs`](https://github.com/cloudflare/pingora/blob/main/pingora-core/src/protocols/http/v1/server.rs) (HTTP/1 handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server_protocols["Server and protocols"]
  node_server["Server and listeners"]
  node_http1["HTTP/1 handling<br/>[server.rs]"]
  node_http2["HTTP/2 handling<br/>[server.rs]"]
  node_http_common["HTTP primitives<br/>[authority.rs]"]
  node_http_custom["Custom HTTP<br/>[server.rs]"]
  node_http_subrequest["HTTP subrequests<br/>[server.rs]"]
  node_raw_connect["Raw connections<br/>[raw_connect.rs]"]
end

subgraph group_proxy["Proxy workflow"]
  node_proxy_api["Proxy framework<br/>[lib.rs]"]
  node_proxy_h1["HTTP/1 proxying<br/>[proxy_h1.rs]"]
  node_proxy_custom["Custom proxying<br/>[proxy_custom.rs]"]
end

subgraph group_upstream["Upstream routing"]
  node_load_balancer["Load balancing<br/>[lib.rs]"]
  node_backend(("Upstream service"))
end

subgraph group_cache["Caching"]
  node_proxy_cache["Proxy cache integration<br/>[proxy_cache.rs]"]
  node_cache_store[("Cache storage<br/>[storage.rs]")]
  node_cache_key["Cache keys<br/>[key.rs]"]
  node_memory_cache["Memory cache<br/>[lib.rs]"]
end

subgraph group_workspace_services["Workspace services"]
  node_tls["TLS implementations"]
  node_observability["Telemetry integrations<br/>[lib.rs]"]
  node_public_crate["Public API crate<br/>[lib.rs]"]
end

node_client(("HTTP client"))

node_client -->|"sends requests"| node_server
node_server -.->|"accepts HTTP/1"| node_http1
node_server -.->|"accepts HTTP/2"| node_http2
node_http1 -.->|"serves proxy requests"| node_proxy_api
node_http2 -.->|"serves proxy requests"| node_proxy_api
node_proxy_api -.->|"selects upstream"| node_load_balancer
node_load_balancer -->|"selects backend"| node_backend
node_proxy_api -->|"proxies requests"| node_backend
node_backend -->|"returns responses"| node_proxy_api
node_proxy_api -->|"returns responses"| node_client
node_proxy_api -.->|"dispatches HTTP/1"| node_proxy_h1
node_proxy_api -.->|"supports custom logic"| node_proxy_custom
node_proxy_api -.->|"integrates caching"| node_proxy_cache
node_proxy_cache -.->|"reads and writes"| node_cache_store
node_cache_store -->|"keys entries"| node_cache_key
node_memory_cache -.->|"provides async caching"| node_cache_store
node_server -->|"supports TLS"| node_tls
node_server -->|"integrates telemetry"| node_observability
node_public_crate -.->|"exposes framework APIs"| node_server

click node_server "https://github.com/cloudflare/pingora/tree/main/pingora-core/src/server"
click node_http1 "https://github.com/cloudflare/pingora/blob/main/pingora-core/src/protocols/http/v1/server.rs"
click node_http2 "https://github.com/cloudflare/pingora/blob/main/pingora-core/src/protocols/http/v2/server.rs"
click node_http_common "https://github.com/cloudflare/pingora/blob/main/pingora-core/src/protocols/http/authority.rs"
click node_http_custom "https://github.com/cloudflare/pingora/blob/main/pingora-core/src/protocols/http/custom/server.rs"
click node_http_subrequest "https://github.com/cloudflare/pingora/blob/main/pingora-core/src/protocols/http/subrequest/server.rs"
click node_raw_connect "https://github.com/cloudflare/pingora/blob/main/pingora-core/src/protocols/raw_connect.rs"
click node_proxy_api "https://github.com/cloudflare/pingora/blob/main/pingora-proxy/src/lib.rs"
click node_proxy_h1 "https://github.com/cloudflare/pingora/blob/main/pingora-proxy/src/proxy_h1.rs"
click node_proxy_custom "https://github.com/cloudflare/pingora/blob/main/pingora-proxy/src/proxy_custom.rs"
click node_proxy_cache "https://github.com/cloudflare/pingora/blob/main/pingora-proxy/src/proxy_cache.rs"
click node_load_balancer "https://github.com/cloudflare/pingora/blob/main/pingora-load-balancing/src/lib.rs"
click node_cache_store "https://github.com/cloudflare/pingora/blob/main/pingora-cache/src/storage.rs"
click node_cache_key "https://github.com/cloudflare/pingora/blob/main/pingora-cache/src/key.rs"
click node_memory_cache "https://github.com/cloudflare/pingora/blob/main/pingora-memory-cache/src/lib.rs"
click node_tls "https://github.com/cloudflare/pingora/tree/main/pingora-core/src/protocols/tls"
click node_observability "https://github.com/cloudflare/pingora/blob/main/pingora-foundations/src/lib.rs"
click node_public_crate "https://github.com/cloudflare/pingora/blob/main/pingora/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_http1,node_http2,node_http_common,node_http_custom,node_http_subrequest,node_raw_connect,node_client toneBlue
class node_proxy_api,node_proxy_h1,node_proxy_custom toneAmber
class node_load_balancer,node_backend toneMint
class node_proxy_cache,node_cache_store,node_cache_key,node_memory_cache toneRose
class node_tls,node_observability,node_public_crate toneIndigo
```

## Components

### Server and protocols

- [Server and listeners](https://github.com/cloudflare/pingora/tree/main/pingora-core/src/server): `pingora-core/src/server`
- [HTTP/1 handling](https://github.com/cloudflare/pingora/blob/main/pingora-core/src/protocols/http/v1/server.rs): `pingora-core/src/protocols/http/v1/server.rs`
- [HTTP/2 handling](https://github.com/cloudflare/pingora/blob/main/pingora-core/src/protocols/http/v2/server.rs): `pingora-core/src/protocols/http/v2/server.rs`
- [HTTP primitives](https://github.com/cloudflare/pingora/blob/main/pingora-core/src/protocols/http/authority.rs): `pingora-core/src/protocols/http/authority.rs`
- [Custom HTTP](https://github.com/cloudflare/pingora/blob/main/pingora-core/src/protocols/http/custom/server.rs): `pingora-core/src/protocols/http/custom/server.rs`
- [HTTP subrequests](https://github.com/cloudflare/pingora/blob/main/pingora-core/src/protocols/http/subrequest/server.rs): `pingora-core/src/protocols/http/subrequest/server.rs`
- [Raw connections](https://github.com/cloudflare/pingora/blob/main/pingora-core/src/protocols/raw_connect.rs): `pingora-core/src/protocols/raw_connect.rs`

### Proxy workflow

- [Proxy framework](https://github.com/cloudflare/pingora/blob/main/pingora-proxy/src/lib.rs): `pingora-proxy/src/lib.rs`
- [HTTP/1 proxying](https://github.com/cloudflare/pingora/blob/main/pingora-proxy/src/proxy_h1.rs): `pingora-proxy/src/proxy_h1.rs`
- [Custom proxying](https://github.com/cloudflare/pingora/blob/main/pingora-proxy/src/proxy_custom.rs): `pingora-proxy/src/proxy_custom.rs`

### Upstream routing

- [Load balancing](https://github.com/cloudflare/pingora/blob/main/pingora-load-balancing/src/lib.rs): `pingora-load-balancing/src/lib.rs`
- **Upstream service**

### Caching

- [Proxy cache integration](https://github.com/cloudflare/pingora/blob/main/pingora-proxy/src/proxy_cache.rs): `pingora-proxy/src/proxy_cache.rs`
- [Cache storage](https://github.com/cloudflare/pingora/blob/main/pingora-cache/src/storage.rs): `pingora-cache/src/storage.rs`
- [Cache keys](https://github.com/cloudflare/pingora/blob/main/pingora-cache/src/key.rs): `pingora-cache/src/key.rs`
- [Memory cache](https://github.com/cloudflare/pingora/blob/main/pingora-memory-cache/src/lib.rs): `pingora-memory-cache/src/lib.rs`

### Workspace services

- [TLS implementations](https://github.com/cloudflare/pingora/tree/main/pingora-core/src/protocols/tls): `pingora-core/src/protocols/tls`
- [Telemetry integrations](https://github.com/cloudflare/pingora/blob/main/pingora-foundations/src/lib.rs): `pingora-foundations/src/lib.rs`
- [Public API crate](https://github.com/cloudflare/pingora/blob/main/pingora/src/lib.rs): `pingora/src/lib.rs`

### Other components

- **HTTP client**

## Connections

- HTTP client → Server and listeners: sends requests
- Server and listeners → HTTP/1 handling: accepts HTTP/1
- Server and listeners → HTTP/2 handling: accepts HTTP/2 (evidence: `pingora-core/src/protocols/http/v2/server.rs`)
- HTTP/1 handling → Proxy framework: serves proxy requests
- HTTP/2 handling → Proxy framework: serves proxy requests
- Proxy framework → Load balancing: selects upstream
- Load balancing → Upstream service: selects backend
- Proxy framework → Upstream service: proxies requests
- Upstream service → Proxy framework: returns responses
- Proxy framework → HTTP client: returns responses
- Proxy framework → HTTP/1 proxying: dispatches HTTP/1 (evidence: `pingora-proxy/src/lib.rs`)
- Proxy framework → Custom proxying: supports custom logic (evidence: `pingora-proxy/src/lib.rs`)
- Proxy framework → Proxy cache integration: integrates caching (evidence: `pingora-proxy/src/lib.rs`)
- Proxy cache integration → Cache storage: reads and writes
- Cache storage → Cache keys: keys entries (evidence: `pingora-cache/src/storage.rs`)
- Memory cache → Cache storage: provides async caching
- Server and listeners → TLS implementations: supports TLS
- Server and listeners → Telemetry integrations: integrates telemetry
- Public API crate → Server and listeners: exposes framework APIs
