17 KiB
Capability: Workers приложения
Purpose
Запускать именованные workers независимо друг от друга, выполнять их процессы по расписанию и формировать их health-состояния.
Границы
- В capability входят регистрация workers, независимые lifecycle и health, последовательное выполнение циклов по расписанию и контролируемая остановка.
Requirements
Requirement: Независимые workers
ID: RT.WK-01
Runtime SHALL выполнять каждый зарегистрированный worker независимо от остальных по его стабильному уникальному имени.
Scenario: Работа worker в составе приложения
Участники
- Приложение, runtime PLBA2, supervisor и зарегистрированный worker.
Предусловия
- Composition root зарегистрировал workers с уникальными именами.
- Приложение запускает workers через lifecycle приложения.
Основной поток
- При запуске приложения supervisor запускает worker, если
workers.<worker_name>.disabledотсутствует или равноfalse, с результатомWORKER_STARTEDпо RT.WK-01.FR-01. - Runtime хранит lifecycle и health каждого запущенного worker отдельно по RT.WK-01.FR-02.
Альтернативы и ошибки
- Для worker задано
disabled: true— supervisor пропускает его запуск. - Worker не удалось запустить — runtime сообщает
WORKER_START_FAILEDпо RT.WK-01.FR-01, остальные workers сохраняют собственное состояние.
Результат
Каждый включённый worker выполняется независимо и имеет отдельные имя, lifecycle и health-состояние.
Коды завершения
| Код | Смысл | Связанные FR |
|---|---|---|
WORKER_STARTED |
Включённый worker запущен при запуске приложения | RT.WK-01.FR-01 |
WORKER_START_FAILED |
Worker не удалось запустить | RT.WK-01.FR-01 |
Функциональные требования
RT.WK-01.FR-01: Имя, состояния и управление worker
Каждый worker регистрируется с уникальным стабильным именем. Runtime управляет его внутренним lifecycle через supervisor: запускает worker при запуске приложения, если workers.<worker_name>.disabled отсутствует или равно false, и останавливает его при остановке приложения. При disabled: true worker не запускается. Значение disabled применяется при запуске приложения; изменение этого значения во время работы не запускает и не останавливает worker до следующего запуска приложения. Отдельные операции API для запуска или остановки worker не предоставляются. Lifecycle и health запущенных workers доступны в общем health-отчёте. Неудачный внутренний запуск worker фиксируется с WORKER_START_FAILED; успешный — с WORKER_STARTED.
RT.WK-01.FR-02: Независимость работы и состояния
Runtime хранит lifecycle и health каждого worker отдельно. Исключение в процессе или состояние одного worker не меняет lifecycle и состояние остальных workers; операции управления приложением применяются ко всем включённым workers. Контракт health определён в RT.WK-04.FR-01.
Requirement: Контролируемая остановка workers
ID: RT.WK-02
Supervisor SHALL запрашивать остановку всех запущенных workers приложения и сообщать, когда каждый из них завершил текущую работу.
Scenario: Остановка группы workers
Участники
- Runtime PLBA2, supervisor и зарегистрированные workers.
Предусловия
- Workers запущены и доступны supervisor.
Основной поток
- Передаём всем запущенным workers приложения режим остановки по RT.WK-02.FR-01.
- Сообщаем о результате группы по RT.WK-02.FR-02; после завершения возвращаем
WORKERS_STOPPED.
Альтернативы и ошибки
- Часть workers ещё выполняет работу — сообщаем
WORKERS_STOPPINGи их имена по RT.WK-02.FR-02.
Результат
Для каждого запущенного worker известно, завершена ли его работа.
Коды завершения
| Код | Смысл | Связанные FR |
|---|---|---|
WORKERS_STOPPED |
Все запущенные workers приложения остановлены | RT.WK-02.FR-02 |
WORKERS_STOPPING |
Не все запущенные workers приложения завершили работу | RT.WK-02.FR-02 |
Функциональные требования
RT.WK-02.FR-01: Режимы остановки worker
При graceful stop worker завершает текущий цикл и не начинает следующий. При принудительной остановке runtime прерывает активную обработку worker. Supervisor отправляет запрос остановки всем запущенным workers приложения; остановка одного не задерживает отправку запросов остальным.
RT.WK-02.FR-02: Результат остановки группы
Supervisor возвращает WORKERS_STOPPED только после остановки всех запущенных workers приложения. Пока хотя бы один worker работает, результат — WORKERS_STOPPING со списком таких workers. Ожидание и таймаут ответа API определяет capability runtime/application-lifecycle.
| Код | Текст сообщения | Дальнейшее поведение |
|---|---|---|
WORKERS_STOPPED |
Сообщение отсутствует | Supervisor подтверждает завершение группы |
WORKERS_STOPPING |
Результат содержит имена ещё работающих workers | Supervisor продолжает остановку |
Requirement: Периодическое выполнение worker
ID: RT.WK-03
Runtime SHALL выполнять прикладной процесс worker циклами по расписанию, заданному для этого worker в config.yaml.
Scenario: Циклическое выполнение процесса
Участники
- Runtime PLBA2, зарегистрированный worker и конфигурация приложения.
Предусловия
- Приложение зарегистрировало worker с уникальным именем и предоставило его прикладной процесс.
- Для каждого включённого worker задан ровно один допустимый режим расписания.
Основной поток
- Запускаем процесс worker без начальной задержки — runtime принимает расписание с
WORKER_SCHEDULE_STARTEDпо RT.WK-03.FR-02 и начинает цикл по RT.WK-03.FR-01. - После завершения цикла планируем следующий запуск по текущей конфигурации и продолжаем последовательное исполнение по RT.WK-03.FR-01.
Альтернативы и ошибки
- Настройки расписания отсутствуют, заданы вместе или имеют недопустимое значение — worker не запускается с
WORKER_CONFIG_INVALIDпо RT.WK-03.FR-02.
Результат
Worker выполняет прикладной процесс последовательно и повторяет его согласно выбранному режиму расписания.
Коды завершения
| Код | Смысл | Связанные FR |
|---|---|---|
WORKER_SCHEDULE_STARTED |
Расписание принято, worker начал циклическое исполнение | RT.WK-03.FR-02 |
WORKER_CONFIG_INVALID |
Расписание отсутствует или некорректно | RT.WK-03.FR-02 |
Функциональные требования
RT.WK-03.FR-01: Режимы и настройки расписания
Настройки каждого worker находятся в корневом config.yaml по пути workers.<worker_name>. Для включённого worker нужно задать ровно одну положительную длительность в секундах: interval_seconds или pause_seconds. Worker с disabled: true не запускается и не требует настроек расписания. Первый цикл начинается сразу после старта worker; циклы одного worker не выполняются параллельно. При interval_seconds задан период между началами циклов: после обработки runtime ждёт остаток периода, а если обработка заняла дольше интервала — запускает следующий цикл сразу. При pause_seconds runtime ждёт указанную паузу после завершения каждого цикла. При планировании следующего цикла используются активные настройки; валидные изменения файла применяются без рестарта по capability configuration/application-config-file.
RT.WK-03.FR-02: Валидация расписания
Для включённого worker runtime принимает расписание только если задан ровно один ключ — interval_seconds или pause_seconds — со значением больше нуля. Если оба ключа отсутствуют, заданы вместе или значение некорректно, запуск приложения завершается ошибкой WORKER_CONFIG_INVALID; детали доступны приложению. Для worker с disabled: true проверка расписания не выполняется. Валидное расписание завершается с WORKER_SCHEDULE_STARTED.
Requirement: Health worker
ID: RT.WK-04
Runtime SHALL формировать health-состояние каждого worker, продолжая циклическую работу после исключения в прикладном процессе.
Scenario: Обновление health worker
Участники
- Runtime PLBA2, worker, прикладная health-логика и health aggregator.
Предусловия
- Worker запущен и зарегистрирован в health aggregator.
Основной поток
- Определяем состояние worker по результату цикла и прикладным условиям по RT.WK-04.FR-01.
- Передаём status и critical aggregator по RT.WK-04.FR-02; обновление завершается с
WORKER_HEALTH_UPDATED.
Альтернативы и ошибки
- Процесс цикла выбрасывает исключение — фиксируем
unhealthy, возвращаемWORKER_PROCESS_FAILED, сохраняем worker запущенным и планируем следующий цикл по RT.WK-04.FR-02.
Результат
Health-состояние worker доступно aggregator; исключение одного цикла не прекращает последующие циклы.
Коды завершения
| Код | Смысл | Связанные FR |
|---|---|---|
WORKER_HEALTH_UPDATED |
Новое health-состояние worker передано aggregator | RT.WK-04.FR-01, RT.WK-04.FR-02 |
WORKER_PROCESS_FAILED |
Цикл завершился исключением, worker продолжит работу по расписанию | RT.WK-04.FR-02 |
Функциональные требования
RT.WK-04.FR-01: Контракт и прикладные условия health
Health worker содержит status (ok, degraded или unhealthy), critical, detail и meta по контракту capability health/aggregation. Приложение задаёт critical при регистрации worker и может предоставить прикладную health-логику, возвращающую один из этих статусов по условиям своей задачи.
| Код | Текст сообщения | Дальнейшее поведение |
|---|---|---|
WORKER_HEALTH_UPDATED |
Сообщение отсутствует | Новое состояние worker передаётся health aggregator |
RT.WK-04.FR-02: Правила статуса и восстановления
Исключение прикладного процесса переводит автоматическое состояние worker в unhealthy, но runtime перехватывает исключение и планирует следующий цикл. В режиме interval_seconds превышение длительностью цикла заданного интервала переводит автоматическое состояние в degraded; в режиме pause_seconds этот статус не возникает из-за расписания. Успешный следующий цикл сбрасывает автоматическое состояние в ok. Итоговый status — худший по порядку ok < degraded < unhealthy из автоматического состояния и результата прикладной health-логики; прикладная логика не маскирует ошибку цикла.
| Код | Текст сообщения | Дальнейшее поведение |
|---|---|---|
WORKER_PROCESS_FAILED |
Сообщение отсутствует; исходное исключение доступно приложению | Worker сохраняет работу и запускает следующий цикл по расписанию |