Introduction

You’ve got a service running. It works. But now you need more — TLS termination, load balancing, rate limiting, caching. You could add this to your application directly, but now your business logic is tangled with infrastructure. Every new feature requires touching both.

Or you could use a proxy. A layer in front of your service that handles the infrastructure: routing, encryption, caching, rate limiting. Your application stays focused. The proxy handles the rest.

Pingora is a Rust framework for building exactly these proxies. Not a config file you fight against — a library you build on. Cloudflare uses it to handle over 40 million requests per second. This tutorial teaches you how by building a real load-balancing proxy, piece by piece.

Eight parts, each building on the last:

1. Your First Proxy — the basic request flow, the ProxyHttp trait, minimal working code
2. Load Balancing — selecting backends, health checks, failover
3. Filters and Middleware — intercepting and modifying traffic
4. TLS — encrypting the client-facing connection
5. Running in Production — logging, metrics, graceful restarts
6. HTTP Caching — reducing backend load
7. Rate Limiting — protecting your services
8. The Complete Proxy — wiring everything together

Each piece is useful on its own. Together, they form a proxy that can handle real traffic. Each part is self-contained — read them in order or jump to the one you need. The complete code is in Part 8 if you want to see the full picture first.

Why Pingora?

If you’ve used Nginx or HAProxy, you know the drill: config files, directives, a mini-language for each feature. It works, but customization has limits. When you need logic that doesn’t fit the config DSL, you’re writing Lua plugins or patching C modules.

Pingora is different. Your proxy is a Rust program. You implement a trait. The framework handles everything else — HTTP parsing, connection pooling, keep-alive, TLS, async I/O. You decide where requests go and what happens along the way.

The tradeoff: more code than a config file. The upside: you can do anything.