212 lines
17 KiB
Markdown
212 lines
17 KiB
Markdown
# 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](#rtwk-01fr-01-имя-состояния-и-управление-worker).
|
||
2. Runtime хранит lifecycle и health каждого запущенного worker отдельно по [RT.WK-01.FR-02](#rtwk-01fr-02-независимость-работы-и-состояния).
|
||
|
||
##### Альтернативы и ошибки
|
||
|
||
- Для worker задано `disabled: true` — supervisor пропускает его запуск.
|
||
- Worker не удалось запустить — runtime сообщает `WORKER_START_FAILED` по [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker), остальные workers сохраняют собственное состояние.
|
||
|
||
##### Результат
|
||
|
||
Каждый включённый worker выполняется независимо и имеет отдельные имя, lifecycle и health-состояние.
|
||
|
||
##### Коды завершения
|
||
|
||
| Код | Смысл | Связанные FR |
|
||
| --- | --- | --- |
|
||
| `WORKER_STARTED` | Включённый worker запущен при запуске приложения | [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker) |
|
||
| `WORKER_START_FAILED` | Worker не удалось запустить | [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker) |
|
||
|
||
#### Функциональные требования
|
||
|
||
##### 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](#rtwk-04fr-01-контракт-и-прикладные-условия-health).
|
||
|
||
### Requirement: Контролируемая остановка workers
|
||
|
||
**ID:** `RT.WK-02`
|
||
|
||
Supervisor SHALL запрашивать остановку всех запущенных workers приложения и сообщать, когда каждый из них завершил текущую работу.
|
||
|
||
#### Scenario: Остановка группы workers
|
||
|
||
##### Участники
|
||
|
||
- Runtime PLBA2, supervisor и зарегистрированные workers.
|
||
|
||
##### Предусловия
|
||
|
||
- Workers запущены и доступны supervisor.
|
||
|
||
##### Основной поток
|
||
|
||
1. Передаём всем запущенным workers приложения режим остановки по [RT.WK-02.FR-01](#rtwk-02fr-01-режимы-остановки-worker).
|
||
2. Сообщаем о результате группы по [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы); после завершения возвращаем `WORKERS_STOPPED`.
|
||
|
||
##### Альтернативы и ошибки
|
||
|
||
- Часть workers ещё выполняет работу — сообщаем `WORKERS_STOPPING` и их имена по [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы).
|
||
|
||
##### Результат
|
||
|
||
Для каждого запущенного worker известно, завершена ли его работа.
|
||
|
||
##### Коды завершения
|
||
|
||
| Код | Смысл | Связанные FR |
|
||
| --- | --- | --- |
|
||
| `WORKERS_STOPPED` | Все запущенные workers приложения остановлены | [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы) |
|
||
| `WORKERS_STOPPING` | Не все запущенные workers приложения завершили работу | [RT.WK-02.FR-02](#rtwk-02fr-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](#rtwk-03fr-02-валидация-расписания) и начинает цикл по [RT.WK-03.FR-01](#rtwk-03fr-01-режимы-и-настройки-расписания).
|
||
2. После завершения цикла планируем следующий запуск по текущей конфигурации и продолжаем последовательное исполнение по [RT.WK-03.FR-01](#rtwk-03fr-01-режимы-и-настройки-расписания).
|
||
|
||
##### Альтернативы и ошибки
|
||
|
||
- Настройки расписания отсутствуют, заданы вместе или имеют недопустимое значение — worker не запускается с `WORKER_CONFIG_INVALID` по [RT.WK-03.FR-02](#rtwk-03fr-02-валидация-расписания).
|
||
|
||
##### Результат
|
||
|
||
Worker выполняет прикладной процесс последовательно и повторяет его согласно выбранному режиму расписания.
|
||
|
||
##### Коды завершения
|
||
|
||
| Код | Смысл | Связанные FR |
|
||
| --- | --- | --- |
|
||
| `WORKER_SCHEDULE_STARTED` | Расписание принято, worker начал циклическое исполнение | [RT.WK-03.FR-02](#rtwk-03fr-02-валидация-расписания) |
|
||
| `WORKER_CONFIG_INVALID` | Расписание отсутствует или некорректно | [RT.WK-03.FR-02](#rtwk-03fr-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](#rtwk-04fr-01-контракт-и-прикладные-условия-health).
|
||
2. Передаём status и critical aggregator по [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления); обновление завершается с `WORKER_HEALTH_UPDATED`.
|
||
|
||
##### Альтернативы и ошибки
|
||
|
||
- Процесс цикла выбрасывает исключение — фиксируем `unhealthy`, возвращаем `WORKER_PROCESS_FAILED`, сохраняем worker запущенным и планируем следующий цикл по [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления).
|
||
|
||
##### Результат
|
||
|
||
Health-состояние worker доступно aggregator; исключение одного цикла не прекращает последующие циклы.
|
||
|
||
##### Коды завершения
|
||
|
||
| Код | Смысл | Связанные FR |
|
||
| --- | --- | --- |
|
||
| `WORKER_HEALTH_UPDATED` | Новое health-состояние worker передано aggregator | [RT.WK-04.FR-01](#rtwk-04fr-01-контракт-и-прикладные-условия-health), [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления) |
|
||
| `WORKER_PROCESS_FAILED` | Цикл завершился исключением, worker продолжит работу по расписанию | [RT.WK-04.FR-02](#rtwk-04fr-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 сохраняет работу и запускает следующий цикл по расписанию |
|