Files
mtusi2026lab2/openspec/specs/lab1-service-operability/spec.md
T
ArtyomandClaude Opus 5.5 8cd30488d2 Archive the carry over of the lab 3 fixes change
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
2026-10-30 06:25:44 +03:00

18 KiB
Raw Blame History

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 запрос обрабатывается штатно