# it-nilesh/pingora architecture

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

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

## Overview

Pingora is a Rust framework for programmable network services, especially HTTP reverse proxies. A request arrives through a configured server/listener, is handled as an HTTP session, and—when proxy logic is used—is routed to an upstream and returned to the client. The workspace also provides protocol/TLS implementations, load-balancing extensions, caching, connection pooling, limits, and observability integrations. Some links below are documented capabilities rather than inspected call sites; those are marked dashed where source-level wiring was not shown.

Main entry points: [`pingora-proxy/src/lib.rs`](https://github.com/it-nilesh/pingora/blob/main/pingora-proxy/src/lib.rs) (Proxy Engine), [`pingora-core/src/protocols/http/server.rs`](https://github.com/it-nilesh/pingora/blob/main/pingora-core/src/protocols/http/server.rs) (HTTP Session), [`pingora-core/src/services`](https://github.com/it-nilesh/pingora/tree/main/pingora-core/src/services) (Services), [`pingora-core/src/listeners`](https://github.com/it-nilesh/pingora/tree/main/pingora-core/src/listeners) (Listeners)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server Runtime"]
  node_server_config["Server Setup"]
  node_listeners["Listeners"]
  node_services["Services"]
  node_http_app["HTTP Application<br/>[http_app.rs]"]
  node_runtime["Async Runtime<br/>[lib.rs]"]
end

subgraph group_protocols["Network Protocols"]
  node_http_session["HTTP Session<br/>[server.rs]"]
  node_http1["HTTP/1<br/>[server.rs]"]
  node_http2["HTTP/2<br/>[server.rs]"]
  node_upstream_client["Upstream Client<br/>[client.rs]"]
  node_tls["TLS"]
end

subgraph group_proxy["Proxy and Routing"]
  node_proxy_engine["Proxy Engine<br/>[lib.rs]"]
  node_proxy_modes["Proxy Modes<br/>[proxy_h1.rs]"]
  node_proxy_cache["Proxy Cache<br/>[proxy_cache.rs]"]
  node_load_balancer["Load Balancer<br/>[lib.rs]"]
end

subgraph group_state["State and Resilience"]
  node_connection_pool["Connection Pool<br/>[connection.rs]"]
  node_cache[("Cache Storage<br/>[storage.rs]")]
  node_memory_cache[("Memory Cache<br/>[lib.rs]")]
  node_limits["Request Limits<br/>[rate.rs]"]
end

subgraph group_integrations["Integrations"]
  node_telemetry["Telemetry<br/>[lib.rs]"]
  node_prometheus["Prometheus<br/>[lib.rs]"]
end

node_client(("Client"))

node_client -.->|"opens connection"| node_listeners
node_server_config -.->|"configures"| node_services
node_services -.->|"accepts traffic"| node_listeners
node_listeners -.->|"dispatches"| node_http_app
node_http_app -.->|"serves session"| node_http_session
node_http_session -->|"dispatches"| node_http1
node_http_session -->|"dispatches"| node_http2
node_http_session -.->|"supports proxying"| node_proxy_engine
node_proxy_engine -->|"delegates"| node_proxy_modes
node_proxy_engine -.->|"proxies upstream"| node_upstream_client
node_proxy_engine -.->|"selects backend"| node_load_balancer
node_proxy_engine -->|"uses cache logic"| node_proxy_cache
node_proxy_engine -.->|"reads and writes"| node_http_session
node_upstream_client -.->|"reuses connections"| node_connection_pool
node_listeners -.->|"secures transport"| node_tls
node_proxy_cache -.->|"reads and writes"| node_cache
node_memory_cache -.->|"provides caching"| node_cache
node_proxy_engine -.->|"applies limits"| node_limits
node_services -.->|"integrates telemetry"| node_telemetry
node_telemetry -.->|"exports metrics"| node_prometheus
node_services -.->|"runs asynchronously"| node_runtime

click node_server_config "https://github.com/it-nilesh/pingora/tree/main/pingora-core/src/server/configuration"
click node_listeners "https://github.com/it-nilesh/pingora/tree/main/pingora-core/src/listeners"
click node_services "https://github.com/it-nilesh/pingora/tree/main/pingora-core/src/services"
click node_http_app "https://github.com/it-nilesh/pingora/blob/main/pingora-core/src/apps/http_app.rs"
click node_proxy_engine "https://github.com/it-nilesh/pingora/blob/main/pingora-proxy/src/lib.rs"
click node_proxy_modes "https://github.com/it-nilesh/pingora/blob/main/pingora-proxy/src/proxy_h1.rs"
click node_proxy_cache "https://github.com/it-nilesh/pingora/blob/main/pingora-proxy/src/proxy_cache.rs"
click node_http_session "https://github.com/it-nilesh/pingora/blob/main/pingora-core/src/protocols/http/server.rs"
click node_http1 "https://github.com/it-nilesh/pingora/blob/main/pingora-core/src/protocols/http/v1/server.rs"
click node_http2 "https://github.com/it-nilesh/pingora/blob/main/pingora-core/src/protocols/http/v2/server.rs"
click node_upstream_client "https://github.com/it-nilesh/pingora/blob/main/pingora-core/src/protocols/http/client.rs"
click node_tls "https://github.com/it-nilesh/pingora/tree/main/pingora-core/src/protocols/tls"
click node_load_balancer "https://github.com/it-nilesh/pingora/blob/main/pingora-load-balancing/src/lib.rs"
click node_connection_pool "https://github.com/it-nilesh/pingora/blob/main/pingora-pool/src/connection.rs"
click node_cache "https://github.com/it-nilesh/pingora/blob/main/pingora-cache/src/storage.rs"
click node_memory_cache "https://github.com/it-nilesh/pingora/blob/main/pingora-memory-cache/src/lib.rs"
click node_limits "https://github.com/it-nilesh/pingora/blob/main/pingora-limits/src/rate.rs"
click node_telemetry "https://github.com/it-nilesh/pingora/blob/main/pingora-foundations/src/lib.rs"
click node_prometheus "https://github.com/it-nilesh/pingora/blob/main/pingora-prometheus/src/lib.rs"
click node_runtime "https://github.com/it-nilesh/pingora/blob/main/pingora-runtime/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_config,node_listeners,node_services,node_http_app,node_runtime,node_client toneBlue
class node_http_session,node_http1,node_http2,node_upstream_client,node_tls toneAmber
class node_proxy_engine,node_proxy_modes,node_proxy_cache,node_load_balancer toneMint
class node_connection_pool,node_cache,node_memory_cache,node_limits toneRose
class node_telemetry,node_prometheus toneIndigo
```

## Components

### Server Runtime

- [Server Setup](https://github.com/it-nilesh/pingora/tree/main/pingora-core/src/server/configuration): `pingora-core/src/server/configuration`
- [Listeners](https://github.com/it-nilesh/pingora/tree/main/pingora-core/src/listeners): `pingora-core/src/listeners`
- [Services](https://github.com/it-nilesh/pingora/tree/main/pingora-core/src/services): `pingora-core/src/services`
- [HTTP Application](https://github.com/it-nilesh/pingora/blob/main/pingora-core/src/apps/http_app.rs): `pingora-core/src/apps/http_app.rs`
- [Async Runtime](https://github.com/it-nilesh/pingora/blob/main/pingora-runtime/src/lib.rs): `pingora-runtime/src/lib.rs`

### Network Protocols

- [HTTP Session](https://github.com/it-nilesh/pingora/blob/main/pingora-core/src/protocols/http/server.rs): `pingora-core/src/protocols/http/server.rs`
- [HTTP/1](https://github.com/it-nilesh/pingora/blob/main/pingora-core/src/protocols/http/v1/server.rs): `pingora-core/src/protocols/http/v1/server.rs`
- [HTTP/2](https://github.com/it-nilesh/pingora/blob/main/pingora-core/src/protocols/http/v2/server.rs): `pingora-core/src/protocols/http/v2/server.rs`
- [Upstream Client](https://github.com/it-nilesh/pingora/blob/main/pingora-core/src/protocols/http/client.rs): `pingora-core/src/protocols/http/client.rs`
- [TLS](https://github.com/it-nilesh/pingora/tree/main/pingora-core/src/protocols/tls): `pingora-core/src/protocols/tls`

### Proxy and Routing

- [Proxy Engine](https://github.com/it-nilesh/pingora/blob/main/pingora-proxy/src/lib.rs): `pingora-proxy/src/lib.rs`
- [Proxy Modes](https://github.com/it-nilesh/pingora/blob/main/pingora-proxy/src/proxy_h1.rs): `pingora-proxy/src/proxy_h1.rs`
- [Proxy Cache](https://github.com/it-nilesh/pingora/blob/main/pingora-proxy/src/proxy_cache.rs): `pingora-proxy/src/proxy_cache.rs`
- [Load Balancer](https://github.com/it-nilesh/pingora/blob/main/pingora-load-balancing/src/lib.rs): `pingora-load-balancing/src/lib.rs`

### State and Resilience

- [Connection Pool](https://github.com/it-nilesh/pingora/blob/main/pingora-pool/src/connection.rs): `pingora-pool/src/connection.rs`
- [Cache Storage](https://github.com/it-nilesh/pingora/blob/main/pingora-cache/src/storage.rs): `pingora-cache/src/storage.rs`
- [Memory Cache](https://github.com/it-nilesh/pingora/blob/main/pingora-memory-cache/src/lib.rs): `pingora-memory-cache/src/lib.rs`
- [Request Limits](https://github.com/it-nilesh/pingora/blob/main/pingora-limits/src/rate.rs): `pingora-limits/src/rate.rs`

### Integrations

- [Telemetry](https://github.com/it-nilesh/pingora/blob/main/pingora-foundations/src/lib.rs): `pingora-foundations/src/lib.rs`
- [Prometheus](https://github.com/it-nilesh/pingora/blob/main/pingora-prometheus/src/lib.rs): `pingora-prometheus/src/lib.rs`

### Other components

- **Client**

## Connections

- Client → Listeners: opens connection
- Server Setup → Services: configures
- Services → Listeners: accepts traffic
- Listeners → HTTP Application: dispatches
- HTTP Application → HTTP Session: serves session
- HTTP Session → HTTP/1: dispatches (evidence: `pingora-core/src/protocols/http/server.rs`)
- HTTP Session → HTTP/2: dispatches (evidence: `pingora-core/src/protocols/http/server.rs`)
- HTTP Session → Proxy Engine: supports proxying
- Proxy Engine → Proxy Modes: delegates (evidence: `pingora-proxy/src/lib.rs`)
- Proxy Engine → Upstream Client: proxies upstream
- Proxy Engine → Load Balancer: selects backend
- Proxy Engine → Proxy Cache: uses cache logic (evidence: `pingora-proxy/src/lib.rs`)
- Proxy Engine → HTTP Session: reads and writes
- Upstream Client → Connection Pool: reuses connections
- Listeners → TLS: secures transport
- Proxy Cache → Cache Storage: reads and writes
- Memory Cache → Cache Storage: provides caching
- Proxy Engine → Request Limits: applies limits
- Services → Telemetry: integrates telemetry
- Telemetry → Prometheus: exports metrics
- Services → Async Runtime: runs asynchronously
