nginx 1.31.5 — Control API, предикатные location и нативный разбор JSON

2 сентября 2026 года вышел nginx 1.31.5 — новая mainline-версия с Control API, предикатными location, модулем ngx_http_json_module и директивой client_body_early_read. Релиз заметно расширяет возможности маршрутизации API-трафика и одновременно исправляет use-after-free при буферизованном проксировании ответов HTTP/2-клиентам, поэтому обновление представляет интерес не только из-за новых функций.

nginx 1.31.5 меняет модель маршрутизации запросов

nginx 1.31.5 вышел 2 сентября 2026 года и на момент релиза является основной, или mainline, веткой проекта. В официальном журнале изменений для версии перечислены четыре крупных добавления: Control API, предикатные location, новый ngx_http_json_module и директива client_body_early_read.

Вместе эти механизмы позволяют принимать решение о маршрутизации не только по URI и заголовкам, но и по значениям переменных, включая данные, извлечённые из JSON-тела запроса. Для API-шлюзов, микросервисов и сервисов, работающих с JSON-RPC, GraphQL или Model Context Protocol, это означает возможность перенести часть логики на уровень nginx без обязательного подключения Lua или njs.

Основные изменения выглядят так:

Изменение	Что появилось в nginx 1.31.5	Практический эффект
Predicate locations	`location` может использовать вычисляемую переменную как предикат	Маршрутизация по заголовкам, сертификатам, сети, JSON-полям и другой логике
`client_body_early_read`	Тело запроса можно прочитать до выбора location	nginx получает доступ к содержимому POST/PUT-запроса раньше обычного
`ngx_http_json_module`	Нативный разбор JSON и извлечение значений в переменные	Меньше необходимости в Lua/njs для простого анализа JSON
Control API	REST-интерфейс управления и инспекции nginx	Reload и получение состояния можно автоматизировать с синхронным JSON-ответом

По сравнению с nginx 1.31.4, где основными изменениями были PROXY Protocol v2 и корректировки работы HTTP/2, gRPC и проверки входных данных, версия 1.31.5 гораздо сильнее затрагивает сам механизм обработки запросов.

Predicate locations — выбор location больше не ограничен URI

До nginx 1.31.5 директива location прежде всего определяла обработчик по URI. Новая версия позволяет использовать переменную как предикат, благодаря чему решение можно основывать на значении, которое nginx вычислил из других параметров запроса.

Упрощённый пример из описания релиза выглядит так:

location $is_ai_scraper {
    # отдельная обработка запросов,
    # для которых переменная получила истинное значение
}

Переменная может быть сформирована через map или другие встроенные механизмы. Источником для неё могут служить HTTP-заголовки, адрес клиента, параметры TLS, сертификат или данные, предварительно извлечённые из тела запроса.

Это особенно полезно там, где один и тот же URI обслуживает разные типы операций. Например, endpoint /mcp, /graphql или /api/v1 сам по себе мало говорит о том, что именно хочет выполнить клиент. С предикатными location nginx может сначала определить тип запроса, а затем выбрать отдельную ветку обработки.

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

client_body_early_read позволяет анализировать тело запроса до маршрутизации

По стандартной схеме nginx сначала получает заголовки, выбирает подходящий location, а уже затем обрабатывает или буферизует тело запроса. Директива client_body_early_read, появившаяся в 1.31.5, позволяет изменить последовательность и прочитать тело сразу после заголовков.

Синтаксис директивы:

client_body_early_read string ...;

Она доступна в контекстах http и server. Если хотя бы одно переданное значение не пустое и не равно 0, nginx выполняет раннее чтение тела.

Например, раннее чтение можно включать только для JSON-запросов:

map $http_content_type $is_json {
    application/json  1;
}

server {
    listen 8000;

    client_body_early_read $is_json;

    client_max_body_size    256k;
    client_body_buffer_size 256k;
}

Практический эффект появляется в связке с новым JSON-модулем и предикатными location: nginx может получить тело, извлечь нужное поле, преобразовать его в переменную и учесть эту переменную ещё до окончательного выбора обработчика.

Но у механизма есть ограничения. Согласно актуальной документации nginx, client_body_early_read несовместим с модулями, использующими небуферизованную обработку тела запроса, в частности ngx_http_grpc_module. Директива также несовместима с модулями, записывающими тело запроса в файл, например ngx_http_dav_module; при раннем чтении игнорируется client_body_in_file_only.

Поэтому включать раннее чтение глобально без проверки существующей конфигурации не стоит. Для обычного reverse proxy, которому содержимое тела не требуется для выбора маршрута, новая директива сама по себе преимуществ не даёт.

ngx_http_json_module переносит простой JSON-разбор в nginx

Новый ngx_http_json_module позволяет разбирать JSON непосредственно средствами nginx и записывать найденные значения в стандартные переменные. Раньше подобные сценарии часто требовали njs, Lua или дополнительного приложения перед upstream.

В официальном анонсе показан пример извлечения поля method:

json_set $request_body $json_method "method";

После этого $json_method можно использовать в map, логировании или предикатной маршрутизации.

В связке с client_body_early_read схема обработки может выглядеть так:

nginx получает заголовки запроса.
Для нужного типа трафика заранее читает тело.
ngx_http_json_module извлекает одно или несколько JSON-полей.
Значения преобразуются в переменные.
Предикатный location выбирает дальнейший обработчик или upstream.

Для API-шлюзов это позволяет реализовать простую классификацию запросов на уровне nginx без отдельного скриптового runtime. Например, разные JSON-RPC методы или MCP tool calls можно направлять в разные сервисы, несмотря на общий URI.

При самостоятельной сборке nginx есть важная деталь: модуль JSON не включён в стандартную конфигурацию исходников автоматически. В configure nginx 1.31.5 для него предусмотрен параметр:

./configure --with-http_json_module

Параметры конкретного установленного бинарного пакета можно проверить командой:

nginx -V

Если nginx установлен из репозитория дистрибутива или стороннего пакета, наличие нового модуля зависит от того, с какими опциями был собран этот бинарный файл.

Control API пришёл в открытый nginx

Ещё одно крупное изменение nginx 1.31.5 — Control API, ранее представленный в коммерческой ветке NGINX Plus R37.0. API работает в master-процессе и предоставляет программный интерфейс для инспекции процессов, чтения загруженной конфигурации и выполнения reload.

В анонсе релиза перечислены, в частности, следующие endpoints:

/1/control/processes — сведения о worker-процессах;
/1/control/config — работа с загруженной конфигурацией и запуск reload через PATCH;
/1/nginx — информация о версии и сборке.

Запустить nginx с Control API можно через отдельный listener. Разработчики рекомендуют UNIX-domain socket:

sudo nginx -l unix:/tmp/nginx.sock

После этого reload можно инициировать HTTP-запросом:

curl --unix-socket /tmp/nginx.sock \
  -X PATCH http://localhost/1/control/config

Главное отличие от классического nginx -s reload — API возвращает структурированный результат операции. Это удобнее для CI/CD, систем конфигурационного управления и собственных панелей администрирования: автоматизации не нужно запускать отдельную команду и затем анализировать error.log, чтобы понять, успешно ли применена конфигурация.

У Control API есть существенное ограничение безопасности: интерфейс не имеет встроенной аутентификации. Разработчики nginx прямо рекомендуют не публиковать его на сетевом порту и использовать UNIX-сокет с ограниченными правами доступа.

При сборке из исходников Control API также является отдельной опцией:

./configure --with-control-api

Проверять наличие поддержки в уже установленном nginx снова удобно через nginx -V.

Исправление use-after-free делает релиз важным и без новых функций

Помимо функциональных изменений nginx 1.31.5 исправляет use-after-free в worker-процессе при определённом сценарии буферизованного проксирования ответа HTTP/2-клиенту. В официальном CHANGES проблема описана как bugfix, а не как отдельная CVE, однако технический разбор в NGINX Community Blog называет это исправление основной причиной для обновления.

Проблема возникала в цепочке буферов при proxy_buffering on. Если при передаче ответа происходила ошибка, часть буферов могла вернуться в список свободных, хотя HTTP/2 output filters всё ещё держали на них ссылки. В результате worker мог продолжить отправку DATA frames с указателями на уже освобождённую память.

Последствия зависели от состояния памяти: возможен был сбой worker-процесса или передача клиенту содержимого освобождённой heap-памяти. По описанию разработчиков, для возникновения ситуации не требовался специально сформированный вредоносный запрос — достаточно было ошибки body filter при накопившихся данных у медленного HTTP/2-клиента.

Для конфигураций, где nginx активно используется как reverse proxy с HTTP/2 на клиентской стороне и буферизацией ответов, это наиболее весомый аргумент в пользу перехода на 1.31.5.

Другие исправления — FastCGI, uWSGI, QUIC и исчерпание файловых дескрипторов

nginx 1.31.5 также закрывает несколько менее заметных, но практически полезных ошибок.

Длинные параметры FastCGI и uWSGI

Исправлено кодирование слишком длинных имён параметров. В FastCGI проблема проявлялась при длине имени от 128 байт, в uWSGI — от 256 байт. Ранее длина могла кодироваться некорректно, из-за чего backend получал повреждённый запрос и соединение завершалось ошибкой, а nginx отвечал 502 Bad Gateway.

Корректное завершение worker при нехватке файловых дескрипторов

Если worker исчерпывал доступные файловые дескрипторы непосредственно перед graceful shutdown, он мог не завершиться корректно. В логах также мог появляться accept4() failed (9: Bad file descriptor). В 1.31.5 эти сценарии исправлены.

Проверки граничных значений

Дополнительные исправления внесены в:

ngx_http_memcached_module — проверку экстремально больших размеров ответа;
ngx_http_slice_module — обработку диапазонов возле максимального значения off_t;
HTTP/3/QUIC — отклонение CRYPTO frames в 1-RTT пакетах после завершения handshake;
внутренний JSON-код — корректную проверку переполнения при расчёте длины JSON-объекта.

Для большинства администраторов эти изменения останутся незаметными, но они делают обработку некорректных и пограничных состояний более предсказуемой.

Резюме

nginx 1.31.5 — это не просто очередной mainline-релиз. Он значительно улучшает маршрутизацию и устраняет проблему управления памятью в популярной конфигурации reverse proxy + HTTP/2 + buffering.

В первую очередь обновление имеет смысл рассмотреть:

Администраторам reverse proxy с HTTP/2. Исправление use-after-free напрямую относится к буферизованной передаче ответов клиентам HTTP/2.
Командам, строящим API gateway на nginx. Predicate locations, JSON-разбор и раннее чтение тела позволяют сократить количество внешней логики для маршрутизации JSON-запросов.
Платформенным и DevOps-командам. Control API упрощает программный reload и получение результата применения конфигурации.
Пользователям FastCGI и uWSGI с нестандартно длинными параметрами. В этой версии исправлено формирование запросов, которое раньше могло приводить к постоянным 502.

При переходе на новые функции стоит учитывать две вещи. Во-первых, раннее чтение тела запроса меняет обычный порядок обработки и имеет ограничения совместимости, в частности с gRPC и DAV. Во-вторых, ngx_http_json_module и Control API при самостоятельной сборке требуют соответствующих configure-флагов.

Исходный код и официальные пакеты nginx 1.31.5 уже доступны на странице загрузки nginx.org. Для существующих production-конфигураций, особенно использующих HTTP/2 и proxy_buffering, релиз стоит оценивать прежде всего как обновление надёжности, а новые механизмы маршрутизации — внедрять отдельно после проверки совместимости и параметров сборки.