adqproxy — мой обратный прокси на Rust, построенный на Cloudflare Pingora. Команда для работы с ним — adqp. Мне хотелось совместить программируемую обработку запросов с привычным устройством сервера: конфигурацией сайтов, проверкой настроек и службой systemd.

Когда я вернулся к проекту, обнаружилась неприятная граница между этими частями: пакет устанавливался, проверка конфигурации проходила, а процесс завершался ещё до первого HTTP-запроса. Пока исправлял установку и маршрутизацию, отдельно проверил весь путь от установки пакета до работающего сервиса.

Чтобы объяснить устройство adqproxy, сначала разберу его основу: что такое Pingora, где она работает у Cloudflare и почему её сравнивают с NGINX.

Что такое reverse proxy и где здесь Pingora

Обратный прокси принимает запрос от клиента и обращается к приложению от его имени. Приложение может работать на другом порту, сервере или в контейнере. Прокси выбирает, куда направить запрос, и возвращает ответ клиенту.

Клиент → reverse proxy → приложение или группа бэкендов

Например, один домен может отправлять /api/ в API-сервис, а остальные запросы — во фронтенд. На этом же уровне можно завершать TLS и распределять запросы между экземплярами приложения.

Pingora — асинхронный многопоточный Rust-фреймворк для построения сетевых сервисов, включая HTTP-прокси. Cloudflare открыла его исходный код в феврале 2024 года. Разработчик подключает библиотеки и пишет приложение со своей логикой обработки трафика. Анонс открытия Pingora

В проекте есть поддержка HTTP/1.1, HTTP/2, TLS, переиспользования соединений, балансировки и проверок доступности бэкендов. Какие возможности попадут в конкретный сервис и как ими управлять, определяет приложение поверх фреймворка. Репозиторий Pingora

Для чего Cloudflare использует Pingora

В описанной Cloudflare архитектуре Pingora обслуживает обращения из сети Cloudflare к origin-серверам — серверам, на которых работает сайт или приложение клиента.

В статье 2022 года компания объясняла ограничения своей прежней системы на NGINX: пулы соединений были привязаны к отдельным worker-процессам. Запрос не всегда мог использовать соединение, уже открытое другим процессом. Архитектура Pingora позволила разделять соединения между потоками и реже выполнять TCP/TLS-рукопожатия. Как Cloudflare построила Pingora

Почему Pingora сравнивают с NGINX

Они пересекаются в задачах reverse proxy: принять HTTP-запрос, выбрать бэкенд, установить соединение и вернуть ответ. На этом участке приложение на Pingora может конкурировать с NGINX.

При этом NGINX предоставляет готовый веб-сервер с конфигурацией, модулями, отдачей статических файлов, проксированием и балансировкой. Pingora предоставляет основу для разработки собственного сетевого сервиса. Поэтому при выборе стоит сравнивать возможности и эксплуатацию конкретных приложений. Возможности NGINX · Назначение Pingora

ВопросNGINXPingora и приложение поверх неё
С чего начинается работаЗапуск готового сервера и настройка конфигурацииРазработка или выбор готового приложения на фреймворке
Где задаётся поведениеКонфигурация, модули, расширенияRust-код и интерфейс настроек конкретного приложения
Кто определяет формат сайтовNGINXАвтор приложения
Что нужно проверить при внедренииКонфигурацию и необходимые модулиВозможности приложения, конфигурацию, установку и обновления

Возможность перенести собственную логику в Rust-код — одна из причин моего интереса к Pingora. Если прокси должен принимать решения по данным приложения, выбирать особую стратегию маршрутизации или интегрироваться с внутренними сервисами, полезно иметь явные точки расширения.

Для обычного проксирования нескольких сайтов NGINX остаётся практичным вариантом. В своём проекте я оцениваю Pingora прежде всего как основу для программируемого прокси. Отдельного сравнения производительности adqproxy и NGINX на одинаковой нагрузке в этой работе не было.

Как в Pingora обрабатывается запрос

Интерфейс ProxyHttp позволяет включаться в отдельные этапы запроса:

  1. request_filter — проверить запрос или сформировать ответ до обращения к бэкенду.
  2. upstream_peer — выбрать сервер и параметры соединения с ним.
  3. upstream_request_filter — изменить запрос перед отправкой бэкенду.
  4. response_filter и logging — обработать ответ и записать результат.

Это удобно, когда логика выбора бэкенда сложнее фиксированного соответствия пути и адреса. Например, решение может зависеть от контекста запроса. Последовательность этапов и условия повторных попыток описаны в руководстве по жизненному циклу запроса.

Как устроен adqproxy

В adqproxy я добавляю поверх Pingora формат конфигурации сайтов и рабочий процесс управления ими: sites-available, sites-enabled, проверку конфигурации и запуск через systemd. Это та часть, с которой взаимодействует администратор сервера.

В рамках этой доработки я обновил Pingora с 0.6.0 до 0.9.1, адаптировал код кэша и метрик и зафиксировал зависимости в Cargo.lock. Дальше проверял конкретное поведение adqproxy: запуск без upstream, выбор бэкенда, TLS и обновление поверх изменённых настроек. Релиз Pingora 0.9.1

Почему чистая установка падала

Установщик включал сайт default с простым правилом return 200 "OK\n"; для /health. Такой ответ можно отдать прямо из прокси. Но бинарник при запуске безусловно брал первый балансировщик из списка upstream, а у штатного сайта список был пуст. Обе части по отдельности казались разумными, пока их не запускали вместе.

Теперь прокси может стартовать без upstream. После установки на Linux с systemd он включает штатный сайт и отвечает на http://127.0.0.1:8080/health. При обновлении установщик сохраняет proxy.yaml, файлы сайтов и их симлинки. Если администратор отключил сайт по умолчанию, обновление его обратно не включает. Изменения установщика

Что я взял из рабочего процесса NGINX

Сайт хранится в /etc/adq-pingora/sites-available/, а adq-ensite создаёт ссылку в sites-enabled/. Например, в файле /etc/adq-pingora/sites-available/demo путь можно связать с конкретной группой бэкендов.

server {
    listen 8080;
    server_name demo.example;

    location /api/ {
        proxy_pass demo_api;
    }
}

upstream demo_api {
    server 127.0.0.1:3000;
}

С этим конфигом запрос на /api/ с заголовком Host: demo.example уходит в demo_api. До правки два маршрута с разными proxy_pass могли попадать в один бэкенд. Я поднял два локальных HTTP-сервера и проверил по телам ответов, какой из них действительно обработал каждый запрос. Для HTTPS директива listen … ssl теперь создаёт TLS-слушатель на указанном порту и использует сертификат из конфига.

Проверку имеет смысл запускать от пользователя службы. Так сразу видно, может ли процесс прочитать файлы конфига и TLS-ключ. Применение изменений пока требует перезапуска systemd, поэтому возможен перерыв в обслуживании.

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

Похожий подход к проверке конфигурации и работающего сервиса я описал в статье о проверке и обновлении NGINX после шести CVE: сначала сверил настройки и установленный пакет, затем проверил обработку запросов после обновления.

Проверка NGINX на vm-voly в Kaku: версия пакета, успешный nginx -t, активная служба и ответ HTTP/2 200.
Проверка NGINX на vm-voly в Kaku: версия пакета, успешный nginx -t, активная служба и ответ HTTP/2 200.

Что я теперь проверяю перед релизом

CI собирает бинарник из зафиксированных зависимостей, ставит его на Ubuntu, запускает установленную службу через systemd и ждёт OK от штатного /health. Отдельные тесты проверяют обновление поверх изменённого конфига, неправильный синтаксис, отсутствующий upstream, два независимых бэкенда, HTTPS и счётчик запросов на /metrics. Так я проверяю установку, которую получит пользователь, вместе с поведением самого прокси. Прогон GitHub Actions

Успешный прогон CI adqproxy: сборка, unit-тесты, smoke-тесты и запуск установленной службы systemd.
Успешный прогон CI adqproxy: сборка, unit-тесты, smoke-тесты и запуск установленной службы systemd.
Фрагмент журнала того же CI: тесты проксирования, метрик, установки, сохранения настроек и HTTPS. Команды выполняются в GitHub Actions; в Kaku открыт их журнал.
Фрагмент журнала того же CI: тесты проксирования, метрик, установки, сохранения настроек и HTTPS. Команды выполняются в GitHub Actions; в Kaku открыт их журнал.

Код и инструкция по сборке уже в основной ветке. Публикация пакета adqproxy в npm пока впереди. Репозиторий проекта