Files
plba_v2/openspec/specs/runtime/application-lifecycle/spec.md
T
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

111 lines
7.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Capability: Жизненный цикл приложения
## Purpose
Управлять lifecycle всего приложения через runtime-контракт, сохраняя entrypoint и HTTP host в приложении.
## Границы
- В capability входят запуск и остановка приложения, переходы lifecycle status и результаты graceful или принудительной остановки workers. Завершение OS-процесса и принадлежащего приложению HTTP host остаётся ответственностью приложения.
## Requirements
### Requirement: Запуск приложения
**ID:** `RT.AL-01`
Runtime SHALL запускать все зарегистрированные и не отключённые workers и предоставлять состояние запуска приложения.
#### Scenario: Запуск приложения
##### Участники
- Приложение, runtime PLBA2 и зарегистрированные workers.
##### Предусловия
- Workers зарегистрированы с уникальными именами.
- Приложение подключило runtime control API.
##### Основной поток
1. Запрашиваем запуск приложения — runtime запускает workers, не отключённых в конфигурации, по [RT.WK-01.FR-01](../worker/spec.md#rtwk-01fr-01-имя-состояния-и-управление-worker).
2. После запуска workers возвращаем `APPLICATION_STARTED` по [RT.AL-01.FR-01](#rtal-01fr-01-запуск-и-состояния-приложения).
##### Альтернативы и ошибки
- Запуск одного или нескольких workers завершился ошибкой — возвращаем `APPLICATION_START_FAILED`; состояние приложения становится `failed`.
##### Результат
Lifecycle приложения и результат запуска workers доступны приложению.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_STARTED` | Все зарегистрированные и включённые workers запущены | [RT.AL-01.FR-01](#rtal-01fr-01-запуск-и-состояния-приложения) |
| `APPLICATION_START_FAILED` | Не удалось запустить один или несколько workers | [RT.AL-01.FR-01](#rtal-01fr-01-запуск-и-состояния-приложения) |
#### Функциональные требования
##### RT.AL-01.FR-01: Запуск и состояния приложения
При запуске runtime переводит приложение в `starting`, запускает зарегистрированные workers, у которых `workers.<worker_name>.disabled` отсутствует или равно `false`, по их контракту и переводит приложение в `running` после их успешного старта. Ошибка запуска переводит lifecycle в `failed`. Состояния приложения: `new`, `starting`, `running`, `stopping`, `stopped` и `failed`.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `APPLICATION_STARTED` | Сообщение отсутствует | Приложение доступно для control operations |
| `APPLICATION_START_FAILED` | Сообщение отсутствует; исходная ошибка доступна приложению | Lifecycle приложения остаётся `failed` |
### Requirement: Остановка приложения
**ID:** `RT.AL-02`
Runtime SHALL останавливать все workers приложения в graceful или принудительном режиме и предоставлять актуальный lifecycle status.
#### Scenario: Остановка приложения
##### Участники
- Клиент control API, runtime PLBA2, supervisor и зарегистрированные workers.
##### Предусловия
- Приложение запущено и его workers зарегистрированы.
##### Основной поток
1. Запрашиваем остановку приложения с выбранным режимом — runtime останавливает workers по [RT.AL-02.FR-01](#rtal-02fr-01-режимы-остановки-приложения).
2. Дожидаемся завершения workers и возвращаем `APPLICATION_STOPPED` по [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки).
##### Альтернативы и ошибки
- Истёк заданный timeout ожидания — возвращаем status `stopping` и `APPLICATION_STOPPING`; runtime продолжает остановку по [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки).
##### Результат
Lifecycle становится `stopped` только после остановки всех workers.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_STOPPED` | Все workers приложения остановлены | [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки) |
| `APPLICATION_STOPPING` | Остановка продолжается после завершения ожидания API | [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки) |
#### Функциональные требования
##### RT.AL-02.FR-01: Режимы остановки приложения
По умолчанию runtime запрашивает graceful stop у всех workers: каждый worker завершает активный цикл и не начинает следующий. При `force=true` runtime принудительно прерывает активную обработку workers. После любого режима новые циклы не запускаются.
##### RT.AL-02.FR-02: Ожидание и статус остановки
Положительный необязательный `timeout_seconds` ограничивает только ожидание ответа на запрос остановки. Если timeout отсутствует, runtime ждёт завершения всех workers без ограничения по времени. По истечении timeout runtime возвращает status `stopping`, продолжая остановку в фоне; timeout не включает принудительный режим. Lifecycle становится `stopped`, когда supervisor подтвердил остановку всех workers по [RT.WK-02.FR-02](../worker/spec.md#rtwk-02fr-02-результат-остановки-группы). Health aggregator возвращает `stopped` по [HL.AG-01.FR-01](../../health/aggregation/spec.md#hlag-01fr-01-состав-и-приоритет-статусов). Runtime не завершает принадлежащий приложению OS process или HTTP host; их остановка остаётся решением приложения.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `APPLICATION_STOPPED` | Сообщение отсутствует | Runtime фиксирует lifecycle `stopped` |
| `APPLICATION_STOPPING` | Сообщение отсутствует; lifecycle доступен в status | Runtime продолжает остановку workers |