Sync the delta specs into the main specs: zones are linked by the schema and the ports main.py assembles, the event bus and the network dependencies name S3 and Valkey, an outsider does not wait for chat locks, an empty cursor is rejected, a request cancelled at shutdown gets 503 in the contract format, the body limit counts received bytes per route, logout withdraws the revocation mark on a database failure, detection runs three times, failover-each records the stopped replica, lost answers are retried on the stand, posting checks its input in a fixed order and make up waits for every replica in the balancer. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27
18 KiB
lab1-service-operability Specification
Purpose
Определяет наблюдаемое поведение сервиса как эксплуатируемого процесса: пробы жизни и готовности, сквозной идентификатор запроса, единый формат ошибок, реакция на сигнал остановки и требования к контейнерной поставке.
Requirements
Requirement: Пробы жизни и готовности
Сервис SHALL отвечать на GET /health/live кодом 200 с телом {"status":"ok"}, проверяя только жизнь процесса. Сервис SHALL отвечать на GET /health/ready кодом 200 с тем же телом, только если в момент запроса выполнен запрос к PostgreSQL за ограниченное время, и кодом 503 с телом ошибки в общем формате в противном случае. Пробы SHALL NOT требовать аутентификации. Недоступность необязательных зависимостей SHALL NOT переводить готовность в 503.
Scenario: Проба жизни отвечает без идентификации
- WHEN приходит
GET /health/liveбез заголовкаAuthorization - THEN ответ
200с телом{"status":"ok"}
Scenario: Готовность подтверждена
- WHEN приходит
GET /health/ready, а PostgreSQL доступен - THEN ответ
200с телом{"status":"ok"}
Scenario: Готовность не зависит от внешних сервисов
- WHEN проверяется готовность, а недоступна только необязательная зависимость
- THEN ответ
200: из внешних сервисов готовность зависит лишь от PostgreSQL
Scenario: Готовность отражает PostgreSQL
- WHEN PostgreSQL остановлен
- THEN
GET /health/readyотвечает503с кодомunavailable, аGET /health/live—200
Scenario: Сервис остановлен
- WHEN процесс получил сигнал остановки и перестал принимать новую работу
- THEN
GET /health/readyотвечает503с кодомunavailableлибо соединение не устанавливается
Requirement: Сквозной идентификатор запроса
Каждый ответ сервиса, включая ответы проб, 204 выхода и ответы об ошибках (404/405 неизвестного маршрута, 413, 500 необработанного исключения), SHALL содержать непустые заголовки X-Request-Id и X-Instance-Id. Если запрос принёс собственный X-Request-Id, сервис SHALL использовать его значение, иначе SHALL сгенерировать новое. X-Instance-Id SHALL идентифицировать реплику (контейнер), а не отдельный процесс-воркер: значение SHALL быть одинаковым у всех процессов реплики, стабильным на всё время её жизни и SHALL совпадать с hostname контейнера, чтобы оператор мог сопоставить ответ с docker ps.
Scenario: Идентификатор присутствует в любом ответе
- WHEN выполняется любой запрос к сервису, успешный или ошибочный
- THEN ответ содержит непустые
X-Request-IdиX-Instance-Id
Scenario: Клиентский идентификатор сохраняется
- WHEN запрос содержит
X-Request-Idс непустым значением - THEN ответ содержит то же значение
Scenario: Один идентификатор на реплику
- WHEN реплика с несколькими процессами-воркерами обслуживает серию запросов
- THEN все её ответы несут одно и то же значение
X-Instance-Id, равное hostname контейнера
Scenario: Необработанное исключение несёт идентификаторы
- WHEN обработка запроса завершается непредвиденным исключением
- THEN ответ
500содержитX-Request-IdиX-Instance-Id
Requirement: Единый формат ошибки
Ответ с кодом 4xx или 5xx SHALL иметь Content-Type: application/json и тело {"error":{"code":...,"message":...,"request_id":...}} без каких-либо дополнительных полей. code SHALL принимать значение из перечисления контракта, request_id SHALL совпадать со значением заголовка X-Request-Id. message SHALL быть непустым и SHALL NOT содержать stack trace, SQL, учётных данных, внутренних путей и сведений о существовании чужих объектов.
Scenario: Тело ошибки соответствует схеме
- WHEN запрос завершается ошибкой любого класса
- THEN тело ответа соответствует схеме
Errorконтракта - AND
request_idв теле совпадает с заголовкомX-Request-Id
Scenario: Необработанное исключение
- WHEN обработка запроса завершается непредвиденным исключением
- THEN ответ
500с кодомinternal_errorи телом в общем формате - AND тело не раскрывает внутренних деталей
Scenario: Неподдерживаемый метод или несуществующий путь
- WHEN запрашивается несуществующий путь или неподдерживаемый метод существующего пути
- THEN ответ имеет тело в общем формате ошибки с непустым
X-Request-Id
Requirement: Корректное завершение по сигналу
По получении SIGTERM сервис SHALL сначала выйти из ротации: на время окна DRAIN_SECONDS (по умолчанию 2 с, больше максимального времени обнаружения балансировщиком) /health/ready SHALL отвечать 503 unavailable, а принятые и новые запросы SHALL обслуживаться как обычно. После окна сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс; весь срок, включая окно, SHALL укладываться в SHUTDOWN_TIMEOUT_SECONDS (по умолчанию 6 с), который меньше таймаута хука остановки, stop_grace_period контейнера и 10 секунд, чтобы контейнер не убивался по таймауту. Собственный срок ожидания принятых запросов SHALL заканчиваться раньше, чем мастер процесса или контейнер останавливает сервер принудительно, чтобы зависший запрос прерывал сам сервер ответом 503 unavailable в общем формате ошибки с заголовками X-Request-Id и X-Instance-Id, а не SIGKILL, и SHALL быть не меньше суммы таймаутов ожидания соединения с БД и оператора. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
Scenario: Остановка укладывается в срок
- WHEN запущенному контейнеру послан
SIGTERM - THEN процесс завершается не позднее чем через 10 секунд и раньше
stop_grace_period - AND код завершения соответствует штатной остановке, а не убийству по таймауту
Scenario: Сначала вывод из ротации
- WHEN процессу сервера послан
SIGTERM - THEN в течение окна
DRAIN_SECONDS/health/readyотвечает503в общем формате ошибки,/health/live—200, соединения ещё принимаются, а после окна порт закрыт и процесс завершается с кодом 0 не позднееSHUTDOWN_TIMEOUT_SECONDS
Scenario: Принятый запрос дорабатывается
- WHEN
SIGTERMприходит во время обработки принятого запроса - THEN этот запрос получает ответ до завершения процесса
Scenario: Зависший запрос не приводит к SIGKILL
- WHEN во время
SIGTERMпринятый запрос не завершается за собственный срок ожидания сервера (например, клиент так и не дослал тело) - THEN сервер прерывает его сам ответом
503с кодомunavailableв общем формате ошибки (Content-Type: application/json,request_idравенX-Request-Id) и с непустымиX-Request-IdиX-Instance-Id, а не ответом500без заголовков контракта - AND процесс завершается с кодом
0раньшеSHUTDOWN_TIMEOUT_SECONDS
Requirement: Логи без содержимого сообщений
Сервис SHALL писать в stdout/stderr структурированную запись на каждый запрос с методом, шаблоном маршрута, кодом ответа, длительностью и X-Request-Id. Логи SHALL NOT содержать текста сообщений, display_name, паролей, токенов сессий, значений заголовка Authorization, строк подключения к хранилищам и тел запросов.
Scenario: Запись о запросе присутствует
- WHEN обработан любой запрос к API
- THEN в stdout появляется запись с методом, шаблоном маршрута, кодом ответа и идентификатором запроса
Scenario: Текст сообщения не попадает в логи
- WHEN отправлено сообщение с известным текстом-маркером
- THEN этот текст отсутствует в stdout и stderr процесса
Scenario: Учётные данные не попадают в логи
- WHEN пользователь зарегистрировался, вошёл и выполнил запрос с токеном
- THEN ни пароль, ни токен, ни значение
Authorizationне встречаются в stdout и stderr процесса
Requirement: Контейнерная поставка
Сервис SHALL собираться из исходников в образ, слушать 0.0.0.0:8080 и читать конфигурацию из переменных окружения. Контейнер SHALL выполняться от непривилегированного пользователя, SHALL фиксировать версию базового образа и версии зависимостей и SHALL объявлять healthcheck, опирающийся на пробу жизни.
Scenario: Образ собирается из чистого clone
- WHEN выполняется сборка образа в свежей копии репозитория
- THEN сборка завершается успешно без обращения к артефактам вне репозитория
Scenario: API доступен на опубликованном порту
- WHEN стенд поднят командой
make up - THEN
GET /health/readyс хоста через опубликованный порт балансировщика отвечает200
Scenario: Процесс работает не от root
- WHEN в работающем контейнере проверяется эффективный пользователь процесса сервера
- THEN это не
root, и идентификатор пользователя не равен 0
Scenario: Healthcheck отражает состояние сервиса
- WHEN контейнер запущен и сервис готов
- THEN статус healthcheck контейнера становится
healthy
Requirement: Предел времени обработки запроса
Обработка запроса SHALL ограничиваться настраиваемым пределом времени. При его превышении сервис SHALL отвечать 503 с кодом unavailable, если ответ ещё не начал отправляться, и SHALL записывать факт превышения в журнал. Превышение предела одним запросом SHALL NOT влиять на последующие запросы и на готовность сервиса.
Scenario: Запрос превысил предел
- WHEN обработка запроса длится дольше установленного предела
- THEN ответ
503с кодомunavailableи телом в общем формате ошибки
Scenario: Сервис продолжает работать после превышения
- WHEN после превышения предела приходит обычный запрос
- THEN он обрабатывается штатно, а
GET /health/readyотвечает200
Scenario: Запись о превышении не раскрывает содержимого
- WHEN запрос с известным текстом-маркером превысил предел
- THEN в журнале появляется запись о превышении, и этот текст в ней отсутствует
Requirement: Единый журнал всех сообщений процесса
Сервис SHALL выводить в stdout единый поток структурированных записей. Сообщения сервера приложений и используемых библиотек SHALL проходить через тот же журнал и иметь тот же формат, что и сообщения приложения. Записи SHALL содержать только поля из объявленного перечня; поля вне перечня SHALL отбрасываться.
Scenario: Сообщения сервера приложений в общем формате
- WHEN процесс запускается и печатает сообщения о старте сервера
- THEN каждая строка stdout разбирается как структурированная запись того же формата, что и записи приложения
Scenario: Незаявленное поле не попадает в журнал
- WHEN запись журнала формируется с полем, отсутствующим в перечне разрешённых
- THEN это поле в выводе отсутствует
Requirement: Предел размера тела запроса
Сервис SHALL ограничивать размер тела запроса настраиваемым пределом маршрута (по умолчанию 1 MiB; у загрузки вложения — MAX_UPLOAD_BYTES, см. lab4-attachments) и SHALL отвечать 413 с кодом payload_too_large в общем формате ошибки, если тело больше предела. Предел SHALL применяться к фактически принятым байтам независимо от способа передачи: и к телу с заголовком Content-Length, и к телу Transfer-Encoding: chunked. Сервис SHALL NOT дочитывать тело сверх предела.
Scenario: Объявленная длина больше предела
- WHEN приходит запрос с
Content-Lengthбольше предела - THEN ответ
413с кодомpayload_too_largeдо чтения тела
Scenario: Chunked-тело больше предела
- WHEN тело передано
Transfer-Encoding: chunkedбезContent-Lengthи его размер превышает предел - THEN ответ
413с кодомpayload_too_large, а не400и не500
Scenario: Тело в пределах лимита
- WHEN
chunked-тело меньше предела - THEN запрос обрабатывается штатно