Основы веб-разработки

Настройка веб-слоя

Веб-слой — это часть приложения, которая принимает HTTP-запросы и отдаёт ответы: сервер, маршрутизация, контроллеры. У него есть решения, которые не принадлежат ни одному контроллеру и ни одному маршруту, потому что касаются всего приложения сразу.

Класс WebConfigurerAdapterСервер configureServer()CORS configureCors()

Таких решений два вида:

  • Как устроен сам сервер — на каком адресе он слушает, сколько процессов держит, сколько памяти отводит на запрос, как долго ждёт медленный обработчик.
  • Кому браузер разрешит обращаться — политика кросс-доменных запросов, CORS.

Первое решается один раз при запуске, второе — на каждом запросе.

Проблема. Такие настройки легко расползаются по проекту: порт указан при запуске, число воркеров — в systemd-юните, ограничение памяти — в переменной окружения, CORS — где-то в коде инициализации. Через полгода на вопрос «откуда взялось это значение» уходит больше времени, чем на саму правку. Вдобавок ничто из этого не проверяется: опечатка в имени параметра остаётся опечаткой до самого запуска.

Решение. Winter собирает эти решения в один класс — конфигуратор веб-слоя. Он написан обычным кодом, поэтому его проверяют и типы, и подсказки редактора; лежит в проекте рядом с остальным кодом; и подключается сам — искать место для регистрации не нужно.

Класс-конфигуратор

Достаточно унаследовать WebConfigurerAdapter и переопределить нужные методы:

main/WebConfig.php
<?php

namespace Main;

use Flytachi\Winter\Kernel\App\ApplicationArguments;
use Flytachi\Winter\Kernel\App\Config\CorsRegistry;
use Flytachi\Winter\Kernel\App\Config\ServerSettings;
use Flytachi\Winter\Kernel\App\Config\WebConfigurerAdapter;

final class WebConfig extends WebConfigurerAdapter
{
  public function configureServer(ServerSettings $server, ApplicationArguments $args): void
  {
      $server->workers(4)
             ->requestTimeout(30);
  }

  public function configureCors(CorsRegistry $cors): void
  {
      $cors->allowedOrigins('https://app.example.com')
           ->allowedHeaders('Content-Type', 'Authorization')
           ->allowCredentials();
  }
}

Регистрировать класс нигде не нужно. Его находит тот же скан, что находит контроллеры, — значит, имя класса и его расположение произвольны, лишь бы файл лежал в сканируемом каталоге — из autoload в composer.json, но не в resources/, .winter/ или vendor/.

Что наследовать

Методы разнесены по двум интерфейсам: configureCors() объявлен в WebConfigurer, configureServer() — в ServerConfigurer. Отсюда три варианта:

Наследуете Что получаете Когда выбирать
WebConfigurerAdapter Реализует оба интерфейса, оба метода уже пустые — переопределяете только нужный Обычный случай: один класс на всё
WebConfigurer (интерфейс) Только configureCors() — PHP потребует его Дополнительный класс с CORS, класс CORS в пакете
ServerConfigurer (интерфейс) Только configureServer() — PHP потребует его Настройка сервера отдельно от CORS

WebConfigurerAdapter — это оба интерфейса с пустыми заглушками. Но учтите: любой его наследник считается ServerConfigurer, даже если configureServer() не переопределён, — поэтому такой класс в приложении может быть только один (см. ниже).

Классы, с которыми вы работаете

В сигнатурах обоих методов встречаются три класса. Знать их устройство необязательно — каждый решает ровно одну задачу:

Класс Откуда берётся Что это
ServerSettings Первый аргумент configureServer() Настройки сервера
ApplicationArguments Второй аргумент configureServer() Разобранная командная строка
CorsRegistry Аргумент configureCors() Политика CORS

ServerSettings — набор параметров запускаемого сервера: адрес, число процессов, лимиты памяти и времени. Устроен как текучий билдер: каждый метод возвращает сам объект, поэтому вызовы цепляются в одну строку. Объект приходит уже заполненным — значениями по умолчанию и тем, что нашлось в переменных окружения, — так что достаточно поправить нужное, а не описывать всё заново.

ApplicationArguments — то, с чем приложение запустили: php call run --http.port=9000 превращается в объект, у которого можно спросить значение по имени. Нужен, чтобы источник настройки выбирали вы: свой флаг, своя переменная в .env или число в коде — решение остаётся за вами, а не за фреймворком.

CorsRegistry — накопитель политики кросс-доменных запросов. Тоже текучий билдер, но, в отличие от ServerSettings, приходит пустым: пока не вызван ни один его метод, CORS-заголовки не отправляются вовсе.

Два метода

Методы отвечают за разные вещи и вызываются в разные моменты:

configureServer() configureCors()
Что настраивает Сам сервер: адрес, процессы, память, пределы Политику доступа для браузеров
Когда вызывается Один раз при запуске Один раз при запуске
Когда действует На всё время работы приложения На каждом запросе
Что принимает ServerSettings и ApplicationArguments CorsRegistry
Где описан Настройка сервера — ниже CORS — ниже

configureServer(ServerSettings $server, ApplicationArguments $args) — настраивает процесс, в котором приложение живёт. Выполняется в процессе приложения, до того как появятся воркеры, поэтому здесь задаётся то, что потом не изменить: порт, число процессов, лимит памяти на воркер, максимальный размер запроса, дедлайн обработки. Второй аргумент даёт доступ к разобранной командной строке php call run, так что источник значения выбираете вы: флаг, .env или константа в коде.

configureCors(CorsRegistry $cors) — описывает, каким сторонним источникам браузер разрешит читать ответы приложения. Сама политика собирается при запуске, но применяется на каждом ответе, включая 404 и ошибки.

Не переопределили метод — ничего не произойдёт: сервер поднимется с настройками по умолчанию, а CORS-заголовки просто не будут отправляться.

Несколько конфигураторов

Два контракта ведут себя по-разному, и различие — не в теме, а в арности.

WebConfigurer — сколько угодно классов, где угодно, включая пакеты. Все получают один и тот же CorsRegistry, вклады складываются: два класса, каждый со своим allowedOrigins(), дадут общий список источников. CORS — набор правил, и объединение двух наборов осмысленно.

ServerConfigurer — ровно один, и только в приложении. ServerSettings это один объект, изменяемый на месте: два вклада не складываются, второй затирает первый.

Каждый наследник WebConfigurerAdapter — это ServerConfigurer. Поэтому второй класс с CORS в приложении и любой класс CORS в пакете реализуют WebConfigurer напрямую, а не наследуют адаптер: два наследника адаптера в приложении остановят загрузку, а наследник адаптера в пакете будет отклонён.

Контракт Кто вправе Сколько
WebConfigurer → configureCors() приложение и пакеты сколько угодно, складываются
ServerConfigurer → configureServer() только приложение один

Сервер настраивает только приложение

ServerConfigurer, найденный внутри импортированного пакета, — ошибка загрузки с именем класса и пакета:

text
Only the application may configure the server; found Acme\Billing\Tuning in acme/billing.

Иначе пакет, тюнящий worker_num, тихо переопределял бы выбор приложения — а кто победит, решал бы порядок обхода файловой системы. Пакету остаётся WebConfigurer: он может дополнить политику CORS, но не двигать адрес сервера.

Больше одного ServerConfigurer в самом приложении — тоже ошибка загрузки: у сервера один хозяин.

text
More than one ServerConfigurer in the application: Main\WebConfig, Main\CorsConfig. The server is one, so its configuration has one owner.

Порядок: приложение последнее

Конфигураторы применяются в определённом порядке — сначала пакеты, в порядке объявления #[Import], затем приложение. Для складывающихся реестров это влияет только на порядок записей; там, где вклады перекрывают друг друга, приложение выигрывает всегда.

Настройка сервера

configureServer() вызывается один раз при запуске, в процессе приложения, до того как появятся воркеры. Всё, что здесь задано, действует до остановки приложения: поменять адрес или лимит памяти на лету нельзя.

main/WebConfig.php
public function configureServer(ServerSettings $server, ApplicationArguments $args): void
{
  $server->workers(4)
         ->profile(Profile::Balance)
         ->requestTimeout(30)
         ->memoryLimit('256M');
}

Вызовы цепляются — каждый метод возвращает сам объект настроек.

Что здесь вообще настраивается

Winter работает на Swoole, и это меняет смысл почти всех привычных цифр. Стоит разобрать модель, иначе непонятно, зачем нужен каждый параметр.

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

Отсюда два следствия, определяющих все настройки на этой странице:

  • Память общая. Все одновременные запросы воркера живут в одной куче. Запрос, который съест лишнее, убивает не себя, а весь процесс — вместе со всеми запросами, которые тот в этот момент держал.
  • Память не освобождается сама. Процесс не завершается после ответа, поэтому всё, что накопилось, остаётся до следующего запроса.

Поэтому настройки сервера — это по сути ответ на один вопрос: сколько запросов воркер может держать одновременно, не рискуя упасть. Дальше — по группам.

Адрес

Метод По умолчанию Назначение
host(string) 0.0.0.0 Сетевой интерфейс, который слушает сервер
port(int) 8000 Порт

0.0.0.0 означает «все интерфейсы» — сервер виден и снаружи. Если приложение стоит за nginx на той же машине, разумно сузить до 127.0.0.1, чтобы порт не торчал в сеть.

Адрес с двоеточием — IPv6: :: слушает все интерфейсы и принимает клиентов и IPv6, и IPv4, ::1 — только локальных. Адрес в квадратных скобках ([::1]) тоже принимается и понимается как ::1.

За nginx: что передать приложению

Приложение видит соединение от nginx, а не от клиента. Чтобы getClientIp(), getScheme() и getUrl() отвечали про клиента, nginx должен передать его данные заголовками:

proxy_http_version 1.1;
proxy_set_header Host              $host;
proxy_set_header X-Real-IP         $remote_addr;
proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

Без X-Forwarded-Proto схема под Swoole всегда http, даже если клиент пришёл по HTTPS. Версия HTTP (getProtocolVersion()) за nginx — это версия участка nginx → приложение, обычно 1.1. Поток запросов в логе включается переменной LOG_ACCESS.

Значения приходят уже заполненными: из #[EnableHttp(port:, host:)], а поверх — из флагов --http.port / --http.host. Трогать эти методы нужно, только если адрес берётся откуда-то ещё, — и тогда их слово последнее: вызов port() перекрывает и атрибут, и флаг запуска, а в лог уходит предупреждение. Поэтому не пишите port() с постоянным значением: он молча отменит #[EnableHttp(port:)]. Свой флаг --port тоже не подойдёт — голый --port без имени компонента call run отвергает при запуске.

Свою переменную окружения подключают так, чтобы без неё оставалось то, что пришло:

php
$server->port((int) env('ORDERS_PORT', $server->getPort()));

Процессы

Метод По умолчанию Назначение
workers(int) 1 Сколько процессов обрабатывают запросы
taskWorkers(int) нет Отдельные процессы под фоновые задачи Swoole

Один воркер — это по умолчанию, и этого почти всегда достаточно

Единица здесь не заглушка «на всякий случай». Swoole\Http\Server поднимается в режиме SWOOLE_BASE, а фреймворк worker_num не задаёт — стартует один процесс. Проверьте сами: ps -eo pid,command | grep winter-http на двенадцатиядерной машине покажет ровно одну строку winter-http: Worker 0.

И этого хватает, потому что параллелизм здесь берётся не из процессов. Один воркер держит сотни запросов одновременно за счёт корутин: каждая уступает управление на любом ожидании — база, сеть, файл. Добавление воркеров этот параллелизм не увеличивает.

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

Масштабируют сегодня не воркерами. Приложение живёт в контейнере, и когда нагрузка растёт, поднимают ещё один экземпляр — реплику в Kubernetes, второй сервис в docker compose, ещё одну машину за балансировщиком. Это даёт то, чего второй воркер внутри одного контейнера не даёт вовсе: отказоустойчивость, выкатку без простоя, раздельные лимиты и понятную арифметику ресурсов на под.

Поэтому нормальная картинка — один контейнер, один воркер, а масштаб набирается числом контейнеров.

Когда workers() трогать не надо. Обычное веб-приложение — обработка запроса, поход в базу, ответ — упирается в ожидание, а не в процессор. Второй воркер здесь не ускорит ничего: он добавит копию всего, что процесс держит в памяти, и ни одного запроса в секунду сверху.

Когда всё-таки поднимают. Это случаи специфические, и их видно по замеру: ядро занято вычислением, а не ожиданием — обработка изображений, разбор больших документов, шифрование, тяжёлая сериализация прямо в обработчике запроса. Такая работа не уступает управление, и корутины ей не помогают: пока она считает, остальные запросы в этом воркере ждут. Вот тогда несколько воркеров на одном контейнере оправданы — и тогда же стоит подумать, не вынести ли эту работу в процесс или демон вместо веб-воркера.

Что стоит поднятие воркеров. Цена платится за каждый:

Что умножается Следствие
Лимит памяти Он на воркер: четыре по 256M — это гигабайт, не считая opcache
Пулы соединений У каждого воркера свой пул: poolMaxConnections: 10 × 4 воркера = 40 сокетов к базе
Прогретые кеши и состояние Ничего не делится между процессами — каждый греет своё заново

Про соединения — самое частое место, где это выстреливает: база отвечает too many connections на приложении, которое «просто добавило воркеров». Подробности — Пул соединений и Redis.

Число задаётся руками. Формул вида «столько-то на ядро» здесь нет намеренно: сколько ядер у контейнера, знает не приложение, а тот, кто выписал ему лимиты, и вычисленное на старте число разъедется с ними при первом же изменении квоты. Ставьте конкретную цифру, которую вы обосновали замером:

php
$server->workers(2);   // обосновано замером: обработка изображений держит ядро

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

Замена воркеров

Метод По умолчанию Назначение
maxRequest(int) из профиля Сколько запросов отработает воркер, прежде чем его заменят свежим. 0 — никогда
maxRequestGrace(int) десятая часть maxRequest Разброс, чтобы воркеры не перезапускались разом

Долгоживущий процесс накапливает мусор, и от этого есть лекарство: периодически заменять воркер на новый. Но лекарство не бесплатное — замена убивает запросы, которые воркер в этот момент обслуживал, и клиент видит оборванное соединение, хотя в логах не появляется ничего.

Поэтому Winter меряет, а не перестраховывается. Течёт не всякий запрос: замеры на живом сервере дали ноль прироста кучи на 4,6 млн обычных запросов. Утечка в 180 байт возникает только там, где запрос взводит таймер — Coroutine::sleep() и всё, что на нём построено. Отсюда порог: воркер заменяется, когда накопленная утечка могла бы дойти до 20 % его лимита памяти.

maxRequestGrace решает отдельную беду: при ровном трафике воркеры досчитывают до одного и того же числа почти одновременно и перезапускаются вместе — а вместе с ними разом холодеют все пулы соединений. Swoole прибавляет к лимиту случайную величину до grace, и перезапуски расходятся во времени.

Если ваши обработчики никогда не спят, замену можно отключить (maxRequest(0)) — платить оборванными запросами будет не за что.

Одновременная нагрузка

Метод По умолчанию Назначение
maxConcurrency(int) из профиля Сколько запросов воркер обрабатывает одновременно
maxConnections(int) из профиля Потолок одновременных TCP-соединений
idleConnectionTimeout(int) выключено Через сколько секунд молчания закрыть соединение

maxConcurrency() — главный предохранитель. Каждый запрос в работе занимает память: около 78 КБ уходит на сам каркас — корутину, объекты запроса и ответа, — и сверх того столько, сколько выделит ваш код. Когда одновременных запросов слишком много, воркер упирается в лимит и умирает вместе со всеми ними. Ограничение превращает эту катастрофу в очередь: лишние запросы просто ждут.

Ожидание в очереди засчитывается в дедлайн запроса, так что подвисший клиент не получит свежие тридцать секунд сверх тех, что уже прождал.

maxConnections() — потолок сокетов. Здесь работает второе ограничение, никак не связанное с памятью: сокет — это файловый дескриптор, а их число задаёт ulimit -n. Выведенное из профиля значение Winter подрезает под этот предел, чтобы объявленное число совпадало с фактическим. Заданное вручную — оставляет как есть: предупреждение Swoole о превышении дойдёт до того, кто его запросил, и подскажет поднять ulimit.

idleConnectionTimeout() — про keep-alive. Открытое соединение занимает около 68 КБ, даже когда клиент ничего не просит, и эта память считается в лимит PHP. Воркер со стандартными 128 МБ умирает примерно на 1900 простаивающих соединениях. Если клиентов много и они держат соединения подолгу, поставьте таймаут молчания.

Пределы одного запроса

Метод По умолчанию Назначение
maxRequestSize(int $bytes) 8 МБ Наибольший запрос вместе с заголовками; сверх — 413
requestTimeout(float $sec) 30 Сколько запрос может идти, прежде чем сервер перестанет ждать. 0 — без предела

maxRequestSize(). Тело запроса лежит в куче воркера всё время обработки, а куча общая. Поэтому предел здесь не про диск и не про сеть, а про то, сколько одновременных загрузок переживёт процесс: 64 МБ при сотне параллельных загрузок — это 6,4 ГБ, и воркер умрёт раньше, чем закончится закачка. Значение по умолчанию совпадает с post_max_size в PHP, чтобы не удивлять привычных цифр.

requestTimeout(). Своего таймаута запроса у Swoole нет — дедлайн держит сторож, который отменяет корутину зависшего запроса. Отмена корректная: catch, finally и defer отрабатывают, соединения возвращаются в пул, клиент получает 504. Транзакции, закрытые в catch/finally или через transaction(), откатываются; ту, что осталась без закрытия, откатывает пул при возврате соединения.

Важно понимать границу: прерывается запрос, который чего-то ждёт — базу, внешний сервис, файл. Запрос, который жжёт процессор в цикле без ввода-вывода, не прервётся, потому что пока он не отпустит поток, в воркере не выполняется ничего, включая сам сторож.

Отдельным маршрутам дедлайн переопределяется атрибутом #[Timeout] — см. Маршрутизацию.

На остановке сервер ждёт начатые запросы столько, сколько запрос вообще может идти, — requestTimeout(), по умолчанию 30 секунд; при requestTimeout(0) — тоже 30. Новые запросы он уже не принимает. Без этого действовало бы умолчание Swoole в 3 секунды, и запрос длиннее получал бы оборванное соединение. Задать срок отдельно можно через $server->set('max_wait_time', 60). Маршрут с более длинным #[Timeout] на остановке всё равно обрывается по этому сроку.

Память

Метод По умолчанию Назначение
memoryLimit(string) ini PHP Потолок памяти каждого воркера
memoryTrimThreshold(string) из профиля Сколько простаивающей памяти воркер держит, прежде чем вернуть её системе. 0 — не возвращать

memoryLimit() — это memory_limit PHP, применяемый при старте каждого воркера. От него считается почти всё остальное: и допустимый параллелизм, и порог замены воркера, и порог возврата памяти.

Лимит памяти — на воркер, а не на приложение

memoryLimit('512M') при восьми воркерах означает 4 ГБ в худшем случае. Winter считает это произведение при старте и предупреждает, если машина столько не держит, но запуску не мешает: перезаклад бывает осознанным решением.

memoryTrimThreshold() — про возврат памяти операционной системе. После всплеска нагрузки воркер продолжает удерживать выделенное, хотя оно уже не нужно. Проверка после каждого ответа возвращает излишек, но операция не бесплатна: когда памяти много, она занимает около 80 мс и видна в хвосте задержек. Поэтому порог масштабируется от лимита, а не задан фиксированным числом.

Статика

php
$server->staticPath('resources/static');   // resources/static/app.css → /app.css

Отдача статики выключена по умолчанию — пока каталог не указан, ни один файл наружу не отдаётся.

Статика идёт мимо PHP

Такие файлы отдаёт сам Swoole, до того как управление попадёт в PHP. Значит, к ним не применяются ни middleware, ни CORS, ни логирование запросов — маршрутизация о них попросту не знает.

Заголовок Server

Каждый ответ сообщает в заголовке Server, кто его отдал. Swoole сам по себе пишет туда swoole-http-server — то есть называет среду выполнения любому, кто спросит. Winter отправляет Winter, без версии: по версии сканеры подбирают известные уязвимости.

php
$server->serverHeader('Orders API');   // своё имя
$server->serverHeader('');             // заголовок не отправляется вовсе

Пустая строка убирает заголовок полностью. Без кода то же задаёт переменная SERVER_HEADER: своё имя — SERVER_HEADER="Orders API", пустое значение или SERVER_HEADER=false — заголовка нет. Ответ может поставить свой Server — например, ResponseEntity::ok($data)->header('Server', '…'), — и он заменит общий. SERVER_HEADER действует и для WebSocket — кроме ответа 101, который Swoole собирает сам.

Сжатие

Сервер сжимает ответы сам: браузерам — brotli, остальным — gzip или deflate, в зависимости от того, что клиент назвал в Accept-Encoding. JSON и HTML сжимаются примерно втрое, и по реальной сети ответ доходит быстрее.

По умолчанию сжатие включено, уровень 1, ответы меньше 1 КБ не сжимаются:

php
$server->compression(false);          // выключить совсем
$server->compressionLevel(5);         // 1 — быстрее, 9 — меньше
$server->compressionMinLength('4K');  // меньше этого — без сжатия
Настройка По умолчанию Почему
compression() включено меньше трафика, быстрее ответ клиенту
compressionLevel() 1 уровень 5 даёт ответ всего на 8–10 % меньше, а воркер работает в 2–4 раза медленнее
compressionMinLength() 1K ответ меньше килобайта и так помещается в один TCP-пакет: сжатие тратит процессор, а клиенту ничего не даёт

Сжатие — работа процессора, и воркер делает её, не прерываясь на другие запросы. Ответ на несколько килобайт сжимается за микросекунды, ответ на 400 КБ — за 1–2 мс, и всё это время остальные запросы воркера ждут. Памяти сжатие почти не требует: воркер в каждый момент сжимает не больше одного ответа.

Выключать сжатие стоит, когда перед приложением стоит nginx или CDN, который сжимает сам, — иначе работа делается дважды.

Файлы не сжимаются

Ответы ResponseStreamFile уходят без сжатия: их Content-Length должен совпадать с размером файла. Статика из staticPath() отдаётся самим Swoole, без этих настроек.

HTTPS

Обычно HTTPS заканчивается на прокси перед приложением — nginx, Traefik, ingress в Kubernetes, балансировщик облака: там же обновляются сертификаты и редиректится HTTP. Приложение тогда работает по HTTP, а схему клиента узнаёт из X-Forwarded-Proto.

Когда прокси нет — внутренний сервис, простой сервер, — TLS включается в самом приложении:

php
$server->tls(cert: '/etc/ssl/app.crt', key: '/etc/ssl/app.key');

или переменными окружения — сертификаты обычно монтируются при развёртывании:

.env
SERVER_TLS_CERT=/etc/ssl/app.crt   # сертификат в PEM, цепочка следом
SERVER_TLS_KEY=/etc/ssl/app.key    # его закрытый ключ, без пароля

Относительный путь считается от корня проекта. Что получается:

  • порт говорит только по TLS: https:// работает, обычный http:// на тот же порт ответа не получает — редирект с HTTP на HTTPS остаётся задачей прокси;
  • принимаются TLS 1.2 и 1.3, старые версии — нет;
  • getScheme() и getUrl() отвечают https; заголовок X-Forwarded-Proto от прокси по-прежнему главнее — он видел сторону клиента;
  • оба файла проверяются при старте: нет файла, не читается, не сертификат, ключ от другого сертификата — приложение не стартует и говорит, что не так;
  • сертификат читается при старте: обновлённый подхватится после перезапуска.

HTTP/2

Включается отдельно, по умолчанию выключен:

php
$server->http2();   // или SERVER_HTTP2=true

Клиенты, которые просят HTTP/2, получат его, остальные — HTTP/1.1. Браузеры говорят по HTTP/2 только поверх TLS, так что для них он идёт вместе с tls(). Без TLS это открытый HTTP/2 (h2c) — так с бэкендом может говорить прокси или gRPC-клиент.

HEAD по HTTP/2

На HEAD по HTTP/2 Swoole отвечает с content-length: 0, а не с длиной, которую вернул бы GET, — передать её у Swoole нельзя (проверено). По HTTP/1.1 длина правильная.

Всё остальное

Любой параметр Swoole, для которого нет отдельного метода, задаётся напрямую:

php
$server->set('ssl_protocols', SWOOLE_SSL_TLSv1_3);   // только TLS 1.3

Профили

Задавать пределы поштучно приходится редко: почти все они выводятся из профиля.

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

php
$server->profile(Profile::Balance);

Все три рабочих профиля одинаково надёжны. Они не торгуют устойчивостью ради скорости — наоборот, каждый существует ровно затем, чтобы воркер не перенапрягал память и не падал, унося с собой обслуживаемые запросы. Различаются они только предположением о размере запроса:

Профиль Бюджет запроса Для каких приложений
Stable 512 КБ Тяжёлые запросы: отчёты, выгрузки, широкие выборки
Balance 128 КБ Обычный CRUD — значение по умолчанию
Performance 64 КБ Лёгкие запросы: тонкий API, прокси, интеграционный шлюз

Бюджет — это память на собственную работу запроса: загруженные сущности, собранная строка ответа. Каркас (около 78 КБ на запрос и 68 КБ на соединение) добавляется поверх и от профиля не зависит.

Меньший бюджет означает больший параллелизм: при одной и той же памяти Performance пропустит одновременно втрое больше запросов, чем Stable. Поэтому выбор профиля — не «насколько я осторожен», а «насколько крупные у меня запросы». Причём это измеряется, а не угадывается:

php
$before = memory_get_usage();
// ... обработчик ...
$after = memory_get_usage();   // меньше 64 КБ → Performance; больше 200 КБ → Stable

Ошибка в выборе не делает приложение безопаснее: если запросы тяжелее заявленного, Performance не спасёт — он лишь позволит набрать больше одновременных запросов, чем воркер выдержит.

`Stress` — только для замеров

Четвёртый профиль, Profile::Stress, единственный снимает ограничители: без предела параллелизма, без замены воркеров, без возврата памяти. Он существует не для того, чтобы «выжать ещё» — пропускная способность упирается в потолок задолго до памяти. Он убирает периодические помехи, искажающие замер: возврат памяти даёт паузы, видимые в p99, замена воркера опустошает пул соединений на середине прогона, сторож запросов крутит собственный таймер.

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

Всё, что решает профиль, — это значения по умолчанию. Явный вызов maxConcurrency(), maxRequest() или переменная окружения перекрывают его вне зависимости от порядка вызовов.

Настройка через .env

Те же параметры задаются переменными окружения — удобно, когда значения разные на стенде и в проде. Все SERVER_* относятся только к HTTP-серверу: процессы, демоны и WebSocket их не читают. Исключения — SERVER_HEADER, общий с WebSocket, и SERVER_TLS_CERT / SERVER_TLS_KEY: WebSocket с $tls берёт сертификат оттуда, если свой не задан (TLS у WebSocket).

Переменная Соответствует
SERVER_PROFILE profile()
SERVER_WORKERS workers()
SERVER_TASKS taskWorkers()
SERVER_MAX_REQUEST maxRequest()
SERVER_MAX_REQUEST_GRACE maxRequestGrace()
SERVER_MAX_REQUEST_SIZE maxRequestSize()
SERVER_MAX_CONNECTIONS maxConnections()
SERVER_MAX_CONCURRENCY maxConcurrency()
SERVER_IDLE_TIMEOUT idleConnectionTimeout()
SERVER_MEMORY_LIMIT memoryLimit()
SERVER_MEMORY_TRIM memoryTrimThreshold()
SERVER_REQUEST_TIMEOUT requestTimeout()
SERVER_HEADER serverHeader() — пустое значение или false убирает заголовок
SERVER_COMPRESSION compression() — true / false
SERVER_COMPRESSION_LEVEL compressionLevel()
SERVER_COMPRESSION_MIN compressionMinLength() — 512, 1K, 4K
SERVER_TLS_CERT, SERVER_TLS_KEY tls() — пути к сертификату и ключу
SERVER_HTTP2 http2() — true / false

Приоритет — от явного к выведенному: вызов в configureServer() перекрывает переменную окружения, переменная перекрывает значение из профиля. Порядок вызовов при этом не важен — профиль подставляет своё только там, где не сказано ничего.

CORS

CORS решает, каким сторонним источникам браузер разрешит обращаться к вашему API. Winter даёт два уровня: глобальную политику для всего приложения и пер-маршрутное переопределение атрибутом #[CrossOrigin].

Что такое CORS и зачем

CORS — Cross-Origin Resource Sharing, «совместное использование ресурсов между источниками». Это механизм, которым сервер разрешает браузеру отдавать ответ коду с другого источника.

Источник (origin) — это тройка «схема + хост + порт»: https://app.example.com и https://api.example.com — разные источники. По умолчанию браузеры действуют по правилу same-origin policy: JavaScript со страницы одного источника не может прочитать ответ от другого. Это защита от того, чтобы чужой сайт дёргал ваш API от имени пользователя.

Проблема. Типичная связка «SPA + API» живёт на разных источниках: фронтенд на app.example.com, API на api.example.com. Браузер по умолчанию заблокирует запрос фронтенда к API — в консоли появится знакомое CORS policy: No 'Access-Control-Allow-Origin' header.

Решение. Сервер должен явно сказать браузеру, каким источникам он доверяет — через заголовки ответа (Access-Control-Allow-Origin и родственные). Winter проставляет эти заголовки за вас: глобально для всего приложения и точечно на конкретном маршруте.

CORS — это про браузер

CORS проверяет браузер, а не сервер. Запросы из curl, Postman или бэкенд-к-бэкенду ограничение same-origin не касается — заголовки CORS на них не влияют.

Глобальная политика

Задаётся в configureCors(). CorsRegistry — текучий билдер: каждый метод принимает список значений через запятую (не массив) и возвращает сам себя, поэтому вызовы цепляются.

Метод По умолчанию Что делает
allowedOrigins(...$origins) пусто Разрешённые источники
allowedHeaders(...$headers) пусто Заголовки, которые браузеру можно прислать
exposeHeaders(...$headers) пусто Заголовки ответа, видимые из JavaScript
allowCredentials(bool) false Разрешает куки и Authorization
maxAge(int $seconds) 0 На сколько браузер закеширует preflight
vary(...$headers) пусто Дополнительные значения заголовка Vary

Не тронули ничего — CORS не отправляется вовсе. Пустой configureCors() равносилен отсутствию конфигуратора: все ответы остаются same-origin.

Как ведут себя настройки

Несколько деталей, которые видно только по итоговым заголовкам.

allowedOrigins работает в трёх режимах — в зависимости от количества:

Источников Что уходит в ответ
ни одного Access-Control-Allow-Origin: *
ровно один Этот источник, всегда и без Vary
несколько Совпавший Origin из запроса плюс Vary: Origin

Третий режим и нужен, чтобы промежуточные кеши не отдали ответ, выписанный одному источнику, другому.

allowedHeaders и maxAge уходят только в preflight. На обычных ответах их нет — они и не нужны там по спецификации. Если allowedHeaders не задан, фреймворк отражает то, что браузер запросил в Access-Control-Request-Headers.

allowCredentials() требует явных источников. Спецификация запрещает пару «* + credentials», и Winter такой заголовок просто не отправит: при пустом allowedOrigins() вызов allowCredentials() молча ничего не даст. Браузер при этом никакой ошибки не покажет — запрос с куками просто не пройдёт.

php
// ✗ заголовок Allow-Credentials не будет отправлен
$cors->allowCredentials();

// ✓ источники перечислены явно
$cors->allowedOrigins('https://app.example.com')
   ->allowCredentials();

vary() заменяет заголовок целиком. Если источников несколько, фреймворк уже поставил Vary: Origin, а ваш vary() перезапишет его. Указывайте Origin в списке сами:

php
$cors->allowedOrigins('https://app.example.com', 'https://admin.example.com')
   ->vary('Origin', 'Accept-Language');

Готовые конфигурации

Три случая, которые покрывают почти всё.

Публичный API только на чтение — доступен откуда угодно, без куки:

php
$cors->allowedHeaders('Content-Type')
   ->maxAge(86400);

SPA с авторизацией — один известный фронтенд, куки и токены разрешены:

php
$cors->allowedOrigins('https://app.example.com')
   ->allowedHeaders('Content-Type', 'Authorization')
   ->allowCredentials()
   ->maxAge(3600);

Несколько фронтендов — список источников, ответ подстраивается под запрос:

php
$cors->allowedOrigins(
       'https://app.example.com',
       'https://admin.example.com',
   )
   ->allowedHeaders('Content-Type', 'Authorization')
   ->allowCredentials()
   ->maxAge(3600);

Политика на отдельном маршруте

Когда одному эндпоинту нужна политика строже или мягче общей, на контроллер или метод вешается #[CrossOrigin]. Параметры те же шесть, только именованными аргументами:

php
use Flytachi\Winter\Kernel\Route\Annotation\CrossOrigin;

#[CrossOrigin(origins: ['https://admin.example.com'], credentials: true)]
#[RequestMapping('admin')]
class AdminController extends Controller
{
  #[GetMapping('stats')]
  public function stats(): ResponseEntity { /* admin.example.com */ }

  #[GetMapping('feed')]
  #[CrossOrigin(origins: ['https://partner.example.com'], maxAge: 3600)]
  public function feed(): ResponseEntity { /* partner.example.com */ }
}

Приоритет — от частного к общему: метод перекрывает класс, класс перекрывает глобальную политику.

Аргумент атрибута Метод билдера
origins allowedOrigins()
allowHeaders allowedHeaders()
exposeHeaders exposeHeaders()
credentials allowCredentials()
maxAge maxAge()
vary vary()

Заменяет, а не дополняет

#[CrossOrigin] полностью вытесняет глобальную политику для своего маршрута, а не сливается с ней. Если глобально разрешён заголовок Authorization, а в атрибуте указаны только origins, то на этом маршруте Authorization окажется запрещён.

Практическое правило: добавляя #[CrossOrigin], перенесите в него все нужные параметры из глобальной политики.

Preflight-запросы

Перед «непростым» запросом — с нестандартным методом, заголовком Authorization или JSON-телом — браузер сначала отправляет OPTIONS и спрашивает разрешение. Этот запрос фреймворк обрабатывает сам: отвечает 204 с нужными заголовками до middleware и контроллера. Писать метод под OPTIONS не нужно.

Чтобы ответить правильно, роутер сначала выясняет, какой маршрут собирается вызвать браузер — по заголовку Access-Control-Request-Method, — и берёт #[CrossOrigin] именно этого маршрута, если он задан.

Где заголовки появляются

Глобальные заголовки пишутся до поиска маршрута, поэтому они есть на любом ответе: успешном, 404, 405 и на ошибках 5xx.

Это сделано намеренно. Если бы на 404 заголовков не было, браузер спрятал бы от JavaScript настоящий статус и показал бы вместо него ошибку CORS — разработчик искал бы проблему в политике доступа вместо опечатки в адресе.

Дальше