Files
mtusi2026lab2/openspec/specs/lab1-service-operability/spec.md
T
ArtyomandClaude Opus 5.5 61c0c28a43 Archive the failover operations change
Grade 4 of lab 3 is closed. A replica on SIGTERM first answers 503 on
readiness for a two second window, longer than the 1.5 s worst
detection, and only then closes its listener and finishes accepted
requests within five seconds; the balancer lets a replica back only
after two passed checks. A test pins the timeout chain to compose,
HAProxy and the stop hook. make detection measured 0.71 s for SIGTERM
(before the process exited at 2.49 s), 0.67 s for a killed process,
2.76 s for a hung one and 1.23 s until no replica was left with
PostgreSQL down. make failover-each stopped and restored each replica
under k6 at 100 rps with no errors and no balancer retries, make
lb-check ran 20 same-key races of 8, make limits checks limits and
isolation against a policy, and make rolling-update replaced the
level 3 image with the current one under load with capacity kept at
two and no errors, migrate running once. The new
lab3-failover-operations spec is synced, and the lab 1 operability
and lab 2 dependency failure specs carry their deltas.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-28 20:08:15 +03:00

15 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 (по умолчанию 5 с), который меньше таймаута хука остановки, stop_grace_period контейнера и 10 секунд, чтобы контейнер не убивался по таймауту. Процесс сервера 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 этот запрос получает ответ до завершения процесса

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 это поле в выводе отсутствует