Files
alex d517820088
PLBA package CI / Python tests (push) Failing after 2s
PLBA package CI / Package version increment (push) Skipped
PLBA2-2. Архивация спек
2026-10-10 20:55:13 +03:00

17 KiB
Raw Permalink Blame History

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 приложения.
Основной поток
  1. При запуске приложения supervisor запускает worker, если workers.<worker_name>.disabled отсутствует или равно false, с результатом WORKER_STARTED по RT.WK-01.FR-01.
  2. 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.
Основной поток
  1. Передаём всем запущенным workers приложения режим остановки по RT.WK-02.FR-01.
  2. Сообщаем о результате группы по 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 задан ровно один допустимый режим расписания.
Основной поток
  1. Запускаем процесс worker без начальной задержки — runtime принимает расписание с WORKER_SCHEDULE_STARTED по RT.WK-03.FR-02 и начинает цикл по RT.WK-03.FR-01.
  2. После завершения цикла планируем следующий запуск по текущей конфигурации и продолжаем последовательное исполнение по 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.
Основной поток
  1. Определяем состояние worker по результату цикла и прикладным условиям по RT.WK-04.FR-01.
  2. Передаём 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 сохраняет работу и запускает следующий цикл по расписанию