adqproxy: a Rust reverse proxy built on Cloudflare Pingora

adqproxy:-a-rust-reverse-proxy-built-on-cloudflare-pingora

How Cloudflare uses Pingora, how it differs from NGINX, and how adqproxy adds site configuration, routing, and systemd installation to a Rust proxy.

adqproxy is my Rust reverse proxy built on Cloudflare Pingora. Its command-line tool is adqp. I wanted to combine programmable request handling with a familiar server workflow: site configuration, configuration checks, and a systemd service.

When I returned to the project, I found a problem at the boundary between those parts. The package installed and its configuration check passed, but the process exited before serving its first HTTP request. While fixing installation and routing, I tested the path from installing the package to running the service.

To explain adqproxy’s design, I’ll start with its foundation: what Pingora is, where Cloudflare uses it, and why people compare it with NGINX.

What a reverse proxy does, and where Pingora fits

A reverse proxy accepts a client request and contacts an application on the client’s behalf. The application can run on another port, another server, or in a container. The proxy selects a destination and returns the application’s response to the client.

Client → reverse proxy → application or backend group

For example, one domain can route /api/ to an API service and other requests to a frontend. This layer can also terminate TLS and distribute requests across application instances.

Pingora is an asynchronous, multithreaded Rust framework for building network services, including HTTP proxies. Cloudflare open-sourced it in February 2024. Developers use its libraries to build applications with their own traffic-handling logic. Pingora open-source announcement

The project supports HTTP/1.1, HTTP/2, TLS, connection reuse, load balancing, and backend health checks. The application built on the framework determines which features it exposes and how operators configure them. Pingora repository

How Cloudflare uses Pingora

In the architecture Cloudflare described, Pingora handles requests from Cloudflare’s network to origin servers: the servers hosting a customer’s site or application.

In its 2022 engineering article, Cloudflare explained a limitation of its previous NGINX-based system. Connection pools belonged to individual worker processes, so a request could not always reuse a connection opened by another process. Pingora’s architecture allowed connections to be shared across threads, reducing the need for TCP/TLS handshakes. How Cloudflare built Pingora

Why Pingora is compared with NGINX

Their responsibilities overlap in reverse proxying: accepting an HTTP request, selecting a backend, establishing a connection, and returning a response. An application built on Pingora can compete with NGINX on that part of the request path.

NGINX provides a ready-to-run web server with configuration, modules, static file serving, proxying, and load balancing. Pingora provides a foundation for developing a network service. A useful comparison therefore considers the features and operation of specific applications. NGINX capabilities · Pingora’s purpose

Question NGINX Pingora and an application built on it
How do you get started? Run and configure an existing server Develop or choose an application built on the framework
Where is behavior defined? Configuration, modules, and extensions Rust code and the application’s configuration interface
Who defines the site configuration format? NGINX The application author
What needs checking before adoption? Configuration and required modules Application features, configuration, installation, and upgrades

The ability to express custom logic in Rust is one reason Pingora interests me. If a proxy needs application data to make routing decisions or must integrate with internal services, explicit extension points are useful.

For straightforward proxying of a few sites, NGINX remains a practical choice. In my project, I evaluate Pingora primarily as a foundation for a programmable proxy. This work did not include an adqproxy-versus-NGINX benchmark under an identical workload.

How Pingora processes a request

The ProxyHttp interface exposes stages of request processing:

  1. request_filter: validate the request or produce a response before contacting a backend.
  2. upstream_peer: select a server and its connection parameters.
  3. upstream_request_filter: modify the request before forwarding it.
  4. response_filter and logging: process the response and record the result.

This is useful when backend selection requires more than a fixed path-to-address mapping. For example, the decision might depend on request context. The stages and retry behavior are described in the request lifecycle guide.

How adqproxy is put together

In adqproxy, I add site configuration and its management workflow on top of Pingora: sites-available, sites-enabled, configuration validation, and a systemd service. This is the interface a server administrator works with.

For this update, I upgraded Pingora from 0.6.0 to 0.9.1, adapted the cache and metrics integrations, and committed Cargo.lock. I then tested specific adqproxy behavior: startup without upstreams, backend selection, TLS, and upgrades over edited configuration files. Pingora 0.9.1 release

Why the default install failed

The installer enabled a default site with a simple return 200 "OKn"; rule for /health. The proxy can serve that response directly. During startup, however, the binary always tried to take the first load balancer from its list of upstreams. The default site had none. The two pieces only failed when I ran them together.

The proxy can now start with zero upstreams. On a fresh Linux install with systemd, the installer enables the default site and the service responds at http://127.0.0.1:8080/health. Upgrades preserve proxy.yaml, site files, and their symlinks. If an administrator disables the default site, it stays disabled after the upgrade. Installer changes

The parts I kept from the NGINX workflow

Site files live in /etc/adq-pingora/sites-available/. Running adq-ensite creates a symlink in sites-enabled/. For example, /etc/adq-pingora/sites-available/demo can map a path to a named backend group.

server {
    listen 8080;
    server_name demo.example;

    location /api/ {
        proxy_pass demo_api;
    }
}

upstream demo_api {
    server 127.0.0.1:3000;
}

A request to /api/ with Host: demo.example goes to demo_api. Before the fix, two routes with different proxy_pass targets could end up at the same backend. I ran two local HTTP servers and checked the response bodies to see which one actually handled each request. For HTTPS, listen … ssl now creates a TLS listener on the configured port and loads the certificate specified in the site file.

Running the config check as the service user also checks that the process can read its configuration and TLS keys. Applying a change currently requires a systemd restart, so there can be an interruption.

sudo adq-ensite demo
sudo -u adq-pingora adqp -t && sudo systemctl restart adq-pingora

I used a similar approach to configuration and runtime checks when checking and updating NGINX after six CVEs: I verified the configuration and installed package, then checked request handling after the update.

Kaku terminal showing the installed NGINX package version, a successful configuration check, an active service and an HTTP/2 200 response

NGINX verification on vm-voly in Kaku: package version, a successful nginx -t, an active service and an HTTP/2 200 response.

What CI checks before release

CI builds the binary from the locked dependency set, installs it on Ubuntu, starts the installed systemd service, and checks that the default /health route returns OK. Separate tests cover an upgrade over an edited configuration, malformed syntax, a missing upstream, routing to two distinct backends, HTTPS, and the request counter at /metrics. That exercises the installation a user gets as well as the proxy itself. GitHub Actions run

Kaku terminal showing the successful adqproxy CI job with build, unit tests, smoke tests and systemd service startup

A successful adqproxy CI run: build, unit tests, smoke tests and startup of the installed systemd service.

Kaku terminal displaying GitHub Actions test results for proxying, metrics, installation, configuration preservation and HTTPS

An excerpt from the same CI log: proxying, metrics, installation, configuration preservation and HTTPS checks. Tests run in GitHub Actions; Kaku displays their log.

The source and build instructions are already on the main branch. Publication of the adqproxy npm package is still pending. Project repository

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
meta’s-new-muse-charm-device-may-cost-$300

Meta’s new Muse Charm device may cost $300

Next Post
thermo-fisher-scientific-arl-spark-companion-oes-metal-analyzer

Thermo Fisher Scientific ARL Spark Companion OES Metal Analyzer

Related Posts