Bring the Claude Code settings, the lint hook, the opsx commands and skills, the architecture notes, the lab 1 to lab 4 specs and the archived lab 1 to lab 4 changes into the lab 5 skeleton, so lab 5 continues the same spec history instead of starting from scratch. The files come from the lab 4 solution commit d2744bc. Rewrite AGENTS.md and the openspec context and rules for lab 5: upload answers 202 queued after the original is in a private staging prefix and the attachment, the job and the outbox row are committed in one transaction, a separate relay publishes the outbox to RabbitMQ with publisher confirms, a separate worker built from the same image consumes the queue through FastStream with a manual ack after the result commit, PostgreSQL stays the source of truth for job states, Out of scope moves to labs 6-7, track 1 and broker HA, and the rules add the failure windows between PostgreSQL and the broker, the effect key and the lease to specs and designs. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
15 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 (по умолчанию 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 это поле в выводе отсутствует