Фоновые компоненты

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

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

Манифест атрибуты #[Enable*]Запуск php call runБез веба да

Что такое компоненты и зачем

Компонент — самостоятельная часть приложения со своим способом работы: веб отвечает на запросы, процесс крутится в цикле, демон держит флот воркеров, планировщик запускает задачи по времени.

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

Решение. Winter описывает состав приложения в самом приложении. Класс-точка входа перечисляет атрибутами, из чего оно состоит, — и php call run поднимает всё это вместе, под одним конфигом, с общим контейнером зависимостей и общими логами. Понадобился воркер — это строка в манифесте, а не новое развёртывание.

Манифест

Всё объявляется атрибутами на классе приложения:

bootstrap.php
<?php

use Flytachi\Winter\Kernel\App\Attribute\EnableDaemon;
use Flytachi\Winter\Kernel\App\Attribute\EnableProcess;
use Flytachi\Winter\Kernel\App\Attribute\EnableScheduler;
use Flytachi\Winter\Kernel\App\Attribute\EnableHttp;
use Flytachi\Winter\Kernel\App\Attribute\EnableWebSocket;
use Flytachi\Winter\Kernel\WinterApplication;

require __DIR__ . '/vendor/autoload.php';

#[EnableHttp]                                  // HTTP-сервер
#[EnableScheduler]                            // задачи по расписанию
#[EnableProcess(\Main\Process\SnmpPoller::class)]   // один воркер
#[EnableDaemon(\Main\Process\Emails::class)]        // флот воркеров
#[EnableWebSocket(\Main\ChatSocket::class, port: 8001)]  // WebSocket-сервер
final class Application extends WinterApplication
{
  public static function main(array $argv): never
  {
      parent::run($argv);
  }
}

Это весь файл запуска. Настройки живут в обычных классах, которые находит сканер, — см. Внедрение зависимостей и Настройку веб-слоя. А то, что атрибутам недоступно, — условия, значения из окружения, внешние программы — объявляется кодом в хуке components().

Пять компонентов

Атрибут Что поднимает Повторяемый
#[EnableHttp(port: …)] HTTP-сервер; по умолчанию 0.0.0.0:8000 нет
#[EnableProcess(Класс)] Один долгоживущий процесс да
#[EnableDaemon(Класс)] Флот воркеров под супервизией да
#[EnableWebSocket(Класс, port: …)] WebSocket-сервер на своём порту да
#[EnableScheduler] Планировщик задач #[Scheduled] нет

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

У всех атрибутов есть параметры супервизии: что делать, если компонент не запускается или падает, — см. Супервизия.

php
#[EnableProcess(\Main\Process\SnmpPoller::class)]
#[EnableProcess(\Main\Process\Heartbeat::class)]
#[EnableDaemon(\Main\Process\Emails::class)]
#[EnableDaemon(\Main\Process\Webhooks::class)]

Адрес HTTP-сервера объявляется так же, как у WebSocket, — рядом с ним: #[EnableHttp(port: 8080, host: '127.0.0.1')]. При запуске его переопределяют флаги --http.port / --http.host, а последнее слово — за конфигуратором веб-слоя. Прежнее имя атрибута — #[EnableWeb]: оно устарело и работает как #[EnableHttp] без параметров.

Что компонентом не является

Три атрибута выглядят похоже, но ничего не поднимают:

Атрибут Что делает
#[EnableAsync] Включает проксирование методов с #[Async] — см. Асинхронные вызовы
#[EnableCaching] Включает кеширование методов с #[Cacheable] и соседними атрибутами — см. Кеширование методов
#[EnableActuator] Добавляет вебу диагностические эндпоинты — см. Actuator / Health

Запуск

Одна команда поднимает всё, что перечислено в манифесте:

bash
php call run       # рабочий режим
php call run dev   # разработка: перезапуск при изменении .php

Главный процесс — php call run, в контейнере это PID 1 — и есть приложение: он запускает компоненты и следит за ними. Каждый компонент, HTTP-сервер в том числе, работает в своём процессе: упавший поднимается по правилам из раздела Супервизия, остановили приложение — остановятся все.

text
php call run                       ← приложение (PID 1)
├── winter-http: manager → Worker 0..N
├── winter-process: Heartbeat
├── winter-daemon: Emails master → worker#1, worker#2
└── …

Одно приложение — один запуск

Второй php call run того же приложения из того же проекта не стартует:

Application is already running [PID 812] (since 2026-10-29 10:14:03 +05:00). Stop it before starting it again — one application runs once per project (.winter/).

В начале сообщения — полное имя класса вашего приложения. Два запуска делили бы между собой одни и те же процессы-синглтоны. Аварийно убитый запуск (kill -9, docker kill) повторному не мешает — см. Если приложение убито.

Приложение без веба

Убираете #[EnableHttp] — и приложение поднимается безголовым: только процессы, демоны и планировщик.

bootstrap.php
#[EnableScheduler]
#[EnableDaemon(\Main\Process\Emails::class)]
final class Application extends WinterApplication { /* ... */ }

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

Пустой манифест — ошибка

Хотя бы один компонент объявить нужно. Приложение без единого #[Enable*] не запустится и скажет об этом прямо: No components declared со списком доступных атрибутов.

Остановка

SIGTERM (docker stop, kill <pid>) или Ctrl+C в терминале останавливают приложение целиком. Каждый компонент фреймворка при этом получает SIGTERM, что бы ни получило само приложение: Ctrl+C посылает приложению SIGINT, но его компоненты всё равно останавливаются по SIGTERM — это единственный сигнал остановки, который корректно обрабатывает каждый из них. Поэтому у процесса под приложением срабатывает onTerminate(), а не onInterrupt(). Внешняя программа получает свой stopSignal — по умолчанию тоже SIGTERM.

Начало и конец остановки видны в логе:

text
Application up: http://0.0.0.0:8000 + [Heartbeat, Emails]
Application stopping (SIGTERM): 3 component(s)
Application stopped in 125 ms

В скобках — причина: SIGTERM, SIGINT или critical failure, если приложение останавливает критичный компонент; тогда и последняя строка читается как Application stopped (critical failure) in 2.7s. Длительность пишется в миллисекундах до секунды и в секундах дальше. Ещё две строки на месте этих:

  • Application reloading. — php call run dev перезапускается после изменения кода;
  • Application finished: every component has done its work. — у приложения без веба все компоненты закончили работу сами, и оно вышло.

Каждому компоненту остановка даёт его собственный срок: процессу — его $grace (по умолчанию 30 секунд), внешней программе — grace, HTTP-серверу — время на начатые запросы (ожидание при остановке). Само приложение ждёт свои компоненты не дольше 35 секунд — или на 5 секунд дольше самого длинного из этих сроков, если он больше 30. Кто не остановился к этому времени, получает SIGKILL, и лог говорит, чья работа оборвана:

text
Application stopping (SIGTERM): 3 component(s)
Application stop: not stopped within 35s — killing Emails.
Application stopped (forced) in 35.0s

Если хоть у одного компонента $grace = 0 — ждать сколько угодно, — приложение уважает этот выбор и своего срока не ставит.

С приоритетами уровни останавливаются друг за другом, и сроки складываются: самый долгий срок в Low, плюс в Normal, плюс в High, плюс 5 секунд. HTTP на Low (30), процессы на Normal (30) и база на High с grace: 60.0 дают 125 секунд — и столько же должно быть у stop_grace_period контейнера.

Повторный сигнал остановки — второй Ctrl+C, второй kill — не ждёт: оставшиеся компоненты сразу получают SIGKILL, в логе Application stop: a second stop signal — killing Emails.

Сроки вложены друг в друга: компонент — 30 секунд, приложение — 35, контейнер — 40. Последнее нужно задать самому. docker stop по умолчанию ждёт всего 10 секунд и затем убивает контейнер целиком, так что 30 секунд компонентов не наступили бы никогда, — в сгенерированном docker-compose.yml поэтому стоит stop_grace_period: 40s. В Kubernetes задайте terminationGracePeriodSeconds: 40: умолчание 30 оборвёт 35-секундный срок приложения.

Сигналы приложению

SIGHUP перезагружает всё приложение и ничего не останавливает. Его посылают главному процессу — kill -HUP <pid>, в контейнере docker kill -s HUP <контейнер>, — и каждый компонент перезагружается по-своему:

Компонент Что получает
HTTP-сервер SIGUSR1 — плавный перезапуск воркеров: начатые запросы доделываются
Процесс onReload()
Планировщик заново читает расписание
Демон свой onReload() и SIGHUP каждому воркеру — их onReload()
WebSocket onReload() — по умолчанию ничего не делает
Внешняя программа (script(), command()) ничего: SIGHUP по умолчанию завершил бы её

В логе — Application reloading (SIGHUP): 4 component(s).

SIGUSR1 и SIGUSR2, посланные приложению, уходят только HTTP-серверу. Чтобы вызвать onUser1() / onUser2() процесса, сигнал посылают на PID самого процесса — его показывает php call process <Класс> status.

Если приложение убито

Компоненты работают в своих группах процессов и сами с приложением не умирают. Если приложение убить так, что оно не успеет их остановить (kill -9, OOM killer), они остались бы работать без присмотра: HTTP-сервер держал бы порт, и следующий php call run не смог бы стартовать.

Поэтому приложение первым делом запускает маленький процесс-страж — в ps он виден как winter-sentinel. Страж знает группы всех компонентов. Если приложение исчезло, не остановив их, страж пишет в stderr строку winter: the application (PID 812) is gone — stopping its components, посылает компонентам SIGTERM, через 30 секунд оставшимся — SIGKILL и выходит. Блокировка приложения к этому времени свободна, и следующий php call run стартует. Сигналы остановки страж игнорирует, так что Ctrl+C в терминале его не задевает.

В контейнере такого не бывает: вместе с PID 1 уходит весь контейнер. Если первым погибнет сам страж, приложение работает дальше и пишет об этом предупреждение — с этого момента после kill -9 компоненты останавливать некому.

Супервизия

Что это. Супервизор — часть приложения, которая запускает его компоненты и следит за ними: решает, перезапустить ли упавший компонент, сдаться или остановить всё приложение.

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

Решение. У каждого компонента два этапа жизни, и правила для них разные.

text
запуск ──► старт ──(готов)──► работа (часы, дни…)
          │                   │
          упал или не успел   упал
          за startTimeout     │
          │                   ▼
          ▼                   перезапуск через 1 → 2 → 4 с,
          без повторов        не больше retries за 30 минут

Старт длится, пока компонент не станет готов. Упал на старте — значит, сломан, а не невезуч: повтор ничего не даст, только спрячет ошибку. Поэтому на старте повторов нет.

Работа начинается с готовности. Падение здесь — разовый сбой (оборвалось соединение, кончилась память), и компонент перезапускается: через 1 секунду, потом через 2, через 4 — не больше retries раз за 30 минут. Продержался 30 минут — счётчик снова с нуля. Повтор, упавший уже на старте, считается одной из этих попыток.

Готовность фреймворк определяет сам:

Компонент Готов, когда
HTTP-сервер Занял порт и запустился
Процесс Начал выполнять run() — зависимости построены
Планировщик Запустил цикл задач
WebSocket Занял порт и принимает подключения
Демон Все воркеры дошли до работы
Внешняя программа Сразу после запуска — или когда проходит её проверка ready

Параметры

Параметр По умолчанию Что задаёт
critical true Что делать, когда компонент больше не может работать: true — остановить приложение, false — оставить компонент лежать, а остальное пусть работает
retries 3 Сколько перезапусков после падения в работе за 30 минут
startTimeout 60 Сколько секунд на старт; не успел — это падение на старте. 0 — ждать сколько нужно
priority Priority::Normal Когда компонент стартует и останавливается относительно остальных — см. Priority
php
#[EnableHttp(retries: 5)]
#[EnableProcess(PriceImport::class, critical: false, startTimeout: 180)]
#[EnableScheduler(retries: 5)]
#[EnableWebSocket(ChatSocket::class, port: 8001, critical: false)]
#[EnableDaemon(Documents::class, startTimeout: 300)]   // у демона нет retries

Демон не перезапускается никогда. Он сам супервизор своих воркеров и перезапускает их по своей политике. Если упал сам демон или он сдался — ему доступен только critical.

Критичный компонент, который больше не может работать, останавливает приложение: остальные компоненты корректно завершаются, а php call run выходит с кодом 1. В контейнере это видно сразу — docker ps покажет перезапуск, Kubernetes — CrashLoopBackOff. Некритичный остаётся лежать в состоянии FAILED, а остальное приложение работает дальше.

Что сбоем не считается

  • Остановка по просьбе — stop() из кода или консоли. Компонент остаётся остановленным, см. Управление работающим компонентом. Это так и тогда, когда тело процесса не уложилось в свой grace и его завершили принудительно: остановка по просьбе — не падение, и компонент не перезапускается.
  • Остановка всего приложения.
  • Процесс доделал работу: run() вернул управление. Процесс не перезапускается и не оставляет записи о себе: в call application status он виден как выполненный (COMPLETED), а запустить его снова можно как любой процесс.

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

Планировщик, WebSocket и демон работают в бесконечном цикле, который заканчивается только по остановке. Если цикл кончился сам — это падение.

Как это выглядит в логе

text
TickProcess is up.
TickProcess crashed: killed by signal 9; restart 1 of 3 in 1s.
TickProcess is up.
Reports failed: did not start: exit code 1. It is not critical: the application runs on without it.
Importer failed: did not start: was not ready within 60s. It is critical: the application stops.

Причина падения на старте — исключение — пишется отдельной строкой рядом.

Порядок запуска и остановки

Что это. По умолчанию приложение запускает все компоненты разом и разом же их останавливает. Порядок задаётся, когда одни компоненты держатся на других.

Проблема. Допустим, база данных работает внутри приложения, как внешняя программа. Если всё стартует одновременно, HTTP-сервер начнёт принимать запросы, пока база ещё поднимается, и первые запросы получат ошибку. Миграциям некуда встать: они нужны после базы, но до сервера. А при остановке база получит сигнал вместе со всеми и может погаснуть раньше, чем закончатся запросы, которые к ней обращаются.

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

Priority

Приоритетов три. Чем выше приоритет, тем дольше компонент живёт: раньше стартует и позже останавливается.

Приоритет Стартует Останавливается Для чего
Priority::High первым последним то, на чём держатся остальные: база, Redis, свой nginx
Priority::Normal после High между работа приложения: процессы, демоны, планировщик. Значение по умолчанию
Priority::Low когда всё готово первым то, что принимает трафик извне: HTTP, WebSocket

Приоритет принимают все #[Enable*] и все методы components():

bootstrap.php
use Flytachi\Winter\Kernel\App\Priority;

#[EnableHttp(port: 8000, priority: Priority::Low)]       // трафик — когда всё готово
#[EnableScheduler]                                       // Normal
final class Application extends WinterApplication
{
  protected static function components(Components $components): void
  {
      $components->command(['bin/postgres.sh'], name: 'postgres',
          priority: Priority::High,
          ready: ['pg_isready', '-q', '-h', '/run/postgresql'],
          stopSignal: SIGINT,
          retries: 3);
  }

  protected static function onStarting(): void
  {
      Migrations::apply();   // postgres здесь уже готов
  }
}

Migrations — класс вашего проекта. Как задаются ready, stopSignal и retries у программы — в разделе Готовность, сигнал остановки, перезапуск.

Старт идёт по уровням: High → onStarting() → Normal → Low. Следующий уровень стартует, когда все компоненты предыдущего готовы — или в состоянии, в котором ждать больше нечего: некритичный упал, компонент работает снаружи, программа закончила работу. Внутри уровня компоненты стартуют одновременно. Критичный компонент, не готовый к своему startTimeout, останавливает приложение, как и без приоритетов, — до следующих уровней дело не доходит.

Остановка идёт обратно: Low → Normal → High. Уровень получает сигнал, когда предыдущий остановился полностью: сначала закрыли вход для трафика, потом погасили работу, потом базу. Второй Ctrl+C по-прежнему убивает всё оставшееся сразу.

Лог называет каждый уровень:

text
Application starting High: postgres
postgres is up.
onStarting done in 812 ms.
Application starting Normal: Scheduler
Application starting Low: Http
…
Application stopping (SIGTERM): 3 component(s)
Application stopping Normal: Scheduler
Application stopping High: postgres
Application stopped in 1.4s

В call application status появляется колонка PRIORITY, а у компонента, который ждёт свой уровень, — причина: waits for High to be ready или waits for onStarting.

Без приоритетов ничего не меняется

Все компоненты — Normal, если не сказано иное, HTTP-сервер тоже. Приложение, в котором приоритет не задан и onStarting() не объявлен, стартует и останавливается разом, как раньше, и лишних строк в логе нет.

onStarting()

Метод класса приложения, который выполняется один раз при старте: когда компоненты High готовы, но остальные ещё не запущены. Место для разовой подготовки — прежде всего миграций. Контейнер, слой базы данных и логгер в нём уже есть.

bootstrap.php
protected static function onStarting(): void
{
  Migrations::apply();
}
  • Ошибка останавливает запуск. Исключение пишется в лог, следующие уровни не стартуют, приложение выходит с кодом 1: onStarting failed (exit code 1): the application stops.
  • Выполняется в отдельном процессе. Открытое в нём — соединения, таймеры — не достаётся компонентам по наследству. Но и то, что метод запишет в статическое свойство или синглтон, до компонентов не дойдёт: результаты передают через базу, файл или кеш.
  • Сигнал остановки во время onStarting() прерывает его, и больше ничего не стартует.
  • Когда не выполняется: при перезагрузке (SIGHUP) и в консольных командах. В php call run dev он выполняется на каждом перезапуске после правки кода — то, что в нём делается, должно быть безопасно повторять. Миграции такими и бывают.

Если компонентов High нет — например, база во внешнем контейнере, — onStarting() выполняется сразу после загрузки, до всех компонентов.

initdb — в скрипте запуска базы

pg_isready говорит только, что сервер принимает соединения, а не что база и роль уже созданы. Подготовку каталога данных кладут в скрипт запуска, как в официальном образе postgres, а создание базы и роли — в начало onStarting():

bin/postgres.sh
#!/bin/sh
[ -s "$PGDATA/PG_VERSION" ] || initdb -D "$PGDATA"
exec postgres -D "$PGDATA"

Базу оставляйте критичной (так по умолчанию): если она не поднимется, миграции всё равно не пройдут.

onStopped()

Метод класса приложения, который выполняется, когда остановлено всё — компоненты, а последними и High. Выполняется в процессе самого приложения и не дольше 5 секунд: он для короткого — уведомить, убрать временные файлы.

bootstrap.php
protected static function onStopped(): void
{
  Notifier::send('service stopped');
}

Исключение пишется в лог (onStopped failed), но остановку не отменяет: код выхода остаётся тем, каким был бы без него. Иначе Docker с restart: on-failure поднимал бы контейнер после обычной остановки.

Объявление кодом

Атрибуты статичны: в них можно писать только константы. Для всего остального есть хук components() на классе приложения.

components()

bootstrap.php
use Flytachi\Winter\Kernel\App\Components;

#[EnableHttp]
#[EnableDaemon(\Main\Process\Emails::class)]
final class Application extends WinterApplication
{
  protected static function components(Components $components): void
  {
      // Планировщик — только на репликах-обработчиках.
      if (env('APP_ROLE') !== 'web') {
          $components->scheduler();
      }
      // Порт — из окружения.
      $components->websocket(\Main\ChatSocket::class, port: (int) env('CHAT_WS_PORT', 8001));

      $components
          ->script('scripts/legacy-sync.php', critical: false)
          ->command(['node', 'tools/bridge.js'], name: 'bridge');
  }
}

Хук вызывается при старте, после сканирования — контейнер уже готов. Объявленное в нём складывается с атрибутами. Методы process(), scheduler(), websocket() и daemon() принимают то же, что и одноимённые атрибуты, включая параметры супервизии. service() добавляет сервис — базу, кеш, — который сам знает, как ему стартовать, проверяться и останавливаться и что ему нужно в образе.

Ошибка в хуке — неверное значение, один класс дважды — остановит запуск с указанием места: Application::components(): retries and startTimeout cannot be negative.

Внешние программы

Иногда рядом с приложением должна работать программа, к фреймворку не относящаяся: старый PHP-скрипт, утилита на другом языке, мост к стороннему сервису. Её можно отдать тому же супервизору.

script()

PHP-скрипт, который запускается отдельной программой тем же PHP, что и приложение. Это обычный PHP: фреймворк в нём не участвует.

php
$components->script('scripts/legacy-sync.php', args: ['--batch=500'], critical: false);

Путь — от корня проекта или абсолютный. Если файла нет, приложение не стартует с понятной ошибкой. Имя для логов по умолчанию — имя файла без .php, задать своё можно параметром name.

command()

Любая программа, которую можно найти в PATH, с аргументами:

php
$components->command(['node', 'tools/bridge.js'], name: 'bridge', grace: 20.0);

Скрипт и программа работают одинаково:

  • запускаются в корне проекта с окружением приложения, включая переменные из .env;
  • по умолчанию готовы сразу после запуска;
  • по умолчанию не перезапускаются: выход с кодом 0 — работа сделана, любой другой — сбой, и дальше решает critical;
  • при остановке получают SIGTERM, а через grace секунд (по умолчанию 30) — SIGKILL;
  • их вывод идёт в вывод приложения как есть, а с output — в лог приложения.

Готовность, сигнал остановки, перезапуск

Программа, на которой держатся остальные — база, Redis, — нуждается в большем, чем «запущена»: остальным надо знать, когда она готова, гасить её надо её собственным сигналом, а упавшую — поднимать. Для этого у command() и script() есть параметры:

Параметр По умолчанию Что задаёт
priority Priority::Normal Уровень запуска и остановки
ready null — готова сразу Как узнать, что программа готова: команда, которая завершается с 0, когда та готова (['pg_isready', '-q']), или 'tcp://хост:порт', который принимает подключение
alive null — не проверяется Проверка, что программа после старта ещё жива, — см. alive
stopSignal SIGTERM Каким сигналом просить остановиться: SIGINT — быстрая остановка PostgreSQL
retries 0 Сколько перезапусков после падения за 30 минут — как у процессов, с паузами 1, 2, 4 с
startTimeout 60 Сколько секунд у проверки ready; без ready не действует
output null — вывод как есть Как превращать вывод программы в лог приложения — см. output
php
$components->command(['redis-server', 'config/redis.conf'], name: 'redis',
  priority: Priority::High,
  ready: 'tcp://127.0.0.1:6379',
  retries: 3);

Проверку ready приложение спрашивает раз в полсекунды. Вывод проверочной команды отбрасывается; команда, которая висит дольше 5 секунд, считается ответом «нет». Не готова за startTimeout — это падение на старте: критичная программа останавливает приложение (postgres failed: did not start: was not ready within 60s), некритичная остаётся лежать, а следующий уровень стартует без неё.

alive

Что это. Проверка, что программа после старта всё ещё жива и отвечает. ready спрашивают только до готовности; alive — всё время, пока программа работает.

Проблема. Процесс может зависнуть, не умирая: база перестала принимать соединения, сервис упёрся в блокировку. Для приложения такой процесс жив — PID на месте, — и оно его не трогает. Запросы тем временем ждут и падают по таймауту, а call application status показывает RUNNING.

Решение. Приложение регулярно задаёт программе простой вопрос — команду или подключение к порту. Если программа много раз подряд не ответила, её считают зависшей, останавливают по ступеням и перезапускают, как упавшую.

php
use Flytachi\Winter\Kernel\App\Probe;

$components->command(['bin/postgres.sh'], name: 'postgres',
  priority: Priority::High,
  ready: ['pg_isready', '-q', '-h', '/run/postgresql', '-d', 'postgres'],
  alive: Probe::command(['pg_isready', '-q', '-h', '/run/postgresql', '-d', 'postgres']),
  stopSignal: SIGINT,
  retries: 3);

Что передать в alive

Значение Что проверяет
null (по умолчанию) ничего — проверки нет
['pg_isready', '-q'] команду: код 0 — жива; с настройками по умолчанию
'tcp://127.0.0.1:6379' порт: принимает подключение — жива; с настройками по умолчанию
Probe::command([...], every:, timeout:, failures:) команду, со своими настройками
Probe::tcp('127.0.0.1:6379', every:, timeout:, failures:) порт, со своими настройками (tcp:// можно не писать)

Параметры Probe

Параметр По умолчанию За что отвечает
every 10 Раз в сколько секунд проверять. Проверки не накладываются: следующая начинается, только когда закончилась предыдущая
timeout 5 Сколько секунд ждать ответа одной проверки. Не ответила за это время — её прерывают, и это неудача
failures 6 Сколько неудач подряд значат «зависла». Одна удачная проверка обнуляет счётчик

С этими значениями программу признают зависшей примерно через минуту без единого ответа (failures × every = 6 × 10 с; если timeout больше every, вместо every считается timeout).

Как это работает

  1. Проверки начинаются после готовности — через every секунд после того, как прошла ready (или после запуска, если ready нет). На старте работает только ready.
  2. Каждая проверка — отдельный процесс, её вывод отбрасывается; ответ — только код выхода. Проверка порта тоже идёт в своём процессе, чтобы приложение не ждало её.
  3. Неудача пишется в лог сразу, с номером: postgres alive check failed (2/6): no answer in 5s. — и видна в call application status под строкой программы: alive check failed 2/6.
  4. Удачная проверка после неудач сбрасывает счётчик: postgres answers its alive check again.
  5. failures неудач подряд — программа зависла: postgres is not answering (6 checks in a row): stopping it with SIGINT.

Как останавливают зависшую программу

Сначала мягко, потом строже — в пределах её grace:

Когда Что получает программа
сразу свой stopSignal — например, SIGINT, быструю остановку PostgreSQL
через grace / 2 SIGTERM — если ещё работает (в логе postgres still running: SIGTERM.)
через grace SIGKILL (postgres still running: SIGKILL.)

Если stopSignal и так SIGTERM, средняя ступень пропускается: SIGTERM, через grace — SIGKILL. Чем бы программа ни закончилась — даже чистым выходом с кодом 0 на свой сигнал, — это падение: postgres crashed: was not answering; restart 1 of 3 in 1s. Дальше — как при любом падении: перезапуск по retries с паузами 1, 2, 4 с, а когда попытки кончились, решает critical. Для базы, убитой SIGKILL, это значит восстановление после аварии при следующем старте — так же, как после kill -9.

Защита от ложных срабатываний

Убить работающую программу из-за медленного ответа хуже, чем подождать. Поэтому:

  • Считаются только неудачи подряд. Пик нагрузки, контрольная точка, сборка мусора дают одну-две неудачи, и первая же удачная проверка обнуляет счётчик.
  • Лёгкая проверка. pg_isready только устанавливает соединение и запросов не выполняет: долгая выгрузка, тяжёлый COPY, блокировки таблиц ей не мешают — занятая база на подключение отвечает.
  • Щедрый timeout: 5 секунд на ответ — медленный, но живой сервер успевает.
  • Не проверяют, когда незачем: до готовности, во время остановки приложения, пока программа перезапускается.
  • Видно заранее. Каждая неудача — строка в логе. Если проверки начали «моргать» под нагрузкой, это видно задолго до перезапуска — поднимите failures или timeout.
  • По умолчанию выключено. Без alive программу не проверяют вовсе.

Для тяжёлой базы с долгими выгрузками можно быть ещё осторожнее:

php
alive: Probe::command(['pg_isready', '-q', '-h', '/run/postgresql', '-d', 'postgres'],
  every: 15, timeout: 10, failures: 8),   // about two minutes without an answer

Проверка не видит, чего не спрашивает

pg_isready скажет «жива» и базе, которая принимает соединения, но не выполняет запросы к одной повисшей таблице. Это правильно: перезапускать базу из-за одной долгой блокировки хуже, чем ждать. Своя, более глубокая проверка (psql -c 'select 1') возможна, но тогда и её ложные срабатывания — на вас.

output

Что это. Разбор вывода программы в лог приложения: строка за строкой, каждая — со своим уровнем.

Проблема. Без разбора программа пишет в вывод приложения как есть. Её строки выглядят иначе, чем строки приложения, на них не действует LOG_LEVEL, они не попадают в JSON и в файл логов. Ошибку базы среди них не отличить от обычного сообщения.

Решение. Дать программе output — класс, который читает одну её строку и говорит, что она значит. Дальше строка идёт через логгер приложения: каналом служит имя программы (синим), в скобках — PID процесса, который её написал.

main/Services/RedisOutput.php
use FlytachiWinterKernelAppOutputLine;
use FlytachiWinterKernelAppProgramOutput;

final class RedisOutput implements ProgramOutput
{
  public function line(string $line): OutputLine
  {
      // 12:M 15 Nov 2026 02:10:00.412 # Server initialized
      if (preg_match('/^(\d+):\w \S+ \S+ \S+ \S+ ([.*#-]) (.*)$/', $line, $m) !== 1) {
          return OutputLine::more($line);
      }
      $level = match ($m[2]) {
          '.' => 'debug',
          '-', '*' => 'info',
          default => 'warning',
      };
      return OutputLine::entry($level, $m[3], pid: (int) $m[1]);
  }
}
php
$components->command(['redis-server', '--port', '6379'], name: 'redis', output: new RedisOutput());
text
[2026-11-15 02:10:00] [INFO ] -redis- [12]: Server initialized
[2026-11-15 02:10:00] [WARN ] -redis- [12]: Memory overcommit must be enabled!

Что может вернуть line():

Вызов Что значит
OutputLine::entry($level, $message, $context, $pid) Строка начинает запись. Уровень — PSR-3 ('info', 'error'…); $pid — кто её написал, по умолчанию сама программа
OutputLine::more($text, $key) Строка продолжает предыдущую запись: с $key — в её контекст под этим ключом, без — туда же, куда ушла строка перед ней
OutputLine::skip() Строку не писать
  • Запись уходит в лог, когда начинается следующая или программа замолкает на мгновение. Поэтому продолжения успевают к ней присоединиться: ошибка и её STATEMENT становятся одной записью.
  • Разбор не теряет вывод. Строку, на которой line() бросил исключение, приложение пишет как есть, с уровнем INFO.
  • line() вызывается в процессе приложения, на каждую строку. Он должен быть быстрым и не хранить состояние между вызовами.
  • Программа, которая пишет без остановки, супервизор не держит: за один проход он читает ограниченную порцию.
  • Размер ограничен. Строка — до 128 КБ, запись вместе с продолжениями — до 3 МБ; лишнее отрезается, а в конце записи сказано, сколько: … (cut: 9.2 MB more). Под call run dev — 1 МБ и 16 МБ.

Готовый разбор есть у PostgreSQL.

Только из кода

Внешние программы не управляются консолью call process: у них нет класса, а значит, и записи состояния. Они живут ровно столько, сколько приложение.

Управление работающим компонентом

Пока приложение работает, запуском процессов распоряжается оно — из кода в любом процессе так же, как из консоли (call process … start, call daemon … start, call schedule start, с -d и без).

Вызов Что происходит
Класс::stop() Компонент останавливается и остаётся остановленным: приложение его не перезапускает
Класс::dispatch() Приложение запускает компонент — остановленный, упавший (FAILED) или выполнивший работу — с чистого листа, счётчик перезапусков обнуляется. Возвращает PID нового процесса
Класс::relaunch() Перезапуск: остановить и сразу запустить. Сбоем не считается
Класс::start() Для объявленного компонента — отказ ProcessManagedException: он работает в процессах приложения, а не в текущем
php
InboxWatcher::stop();                 // остановлен, приложение его не поднимет
$pid = InboxWatcher::dispatch();      // снова работает внутри приложения
InboxWatcher::relaunch();             // перезапуск, например после смены настроек

Остановка действует только на текущий запуск приложения: после перезапуска приложения снова поднимается всё, что объявлено.

Запуск необъявленного процесса

Процесс, которого нет в составе приложения, тоже запускается через приложение — оно его подхватывает на один запуск:

  • повторов нет: упал — значит упал;
  • он не критичный: ни падение, ни что-то ещё не остановит приложение;
  • закончил работу или остановлен — приложение о нём забывает;
  • упал — виден в call application status как FAILED с причиной, пока его не запустят снова;
  • остановка или перезапуск приложения его не возвращает: он временный.

Объявленный компонент запускается со своими параметрами (retries, critical, startTimeout) — как при старте приложения.

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

bash
php call schedule start   # приложение подхватывает планировщик
php call app status         # он в списке «Adopted»
php call schedule stop      # и приложение о нём забывает

Из кода так же: ReportExport::dispatch() в контроллере запускает выгрузку внутри приложения — её видно в call application status, и она остановится вместе с приложением.

Класс::start() необъявленного процесса по-прежнему запускает его в текущем процессе: это просьба «выполни здесь», а не «запусти в фоне».

Ещё два случая, о которых заботиться не нужно:

  • Компонент уже запущен вне приложения — например, его подняли командой call process … start -d до call run. Приложение не падает и не воюет с ним, а ждёт, пока тот завершится, и тогда запускает свой.
  • Компонент или всё приложение работает в другом окружении — запись видна через общую папку .winter/ смонтированного проекта, но процесс в другом контейнере. Такую запись не трогают: stop() и relaunch() вернут false, start() и dispatch() откажут с подсказкой выполнить команду там. Иначе рядом с приложением заработал бы второй экземпляр — например, второй планировщик, и задачи выполнялись бы дважды. Запись контейнера, убитого без остановки (docker kill, нехватка памяти) и пересозданного на том же дереве, не мешает: её блокировку никто не держит, и компонент стартует. Это видно между контейнерами одной машины; хост macOS и контейнер блокировок друг друга не видят.

Что выбрать

Пять инструментов легко перепутать, потому что все они «делают что-то в фоне». Разводятся они по вопросу «когда это должно работать».

Нужно Инструмент
Выполнить кусок работы, не задерживая ответ клиенту #[Async]
Крутить один бесконечный цикл: слушать очередь, опрашивать устройство Процесс
То же самое, но в несколько рук, с перезапуском упавших Демон
Запускать по расписанию: каждые 5 минут, каждую ночь в 3:00 Планировщик
Держать открытые соединения с браузерами и отправлять им сообщения сразу WebSocket

Разберём границы, потому что именно на них ошибаются:

#[Async] — не фоновая задача. Метод уходит в отдельную корутину и чередуется с вызывающим кодом на ожиданиях ввода-вывода, но работа остаётся внутри того же воркера и живёт ровно столько, сколько он: перезапуск её потеряет, на другую машину она не уедет, очереди у неё нет. Годится, чтобы не заставлять клиента ждать; не годится, чтобы гарантированно доставить письмо — для этого нужен процесс или демон с очередью.

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

Планировщик против процесса с sleep(). Цикл с sleep(300) внутри процесса кажется простым решением, но с ним вы сами отвечаете за то, чтобы задача не наложилась сама на себя, за пропуски после перезапуска и за расписание в терминах времени суток. Планировщик всё это уже умеет.

Дальше