Files
mtusi2026lab3/openspec/specs/graceful-shutdown/spec.md
T
ricoromaandClaude Opus 5.5 af4bca08c9 feat: carry lab 2 over and add X-Instance-Id and idempotency keys
- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec
  change instance-id-idempotency)
- rename the compose project to mtusi-lab3 and the image to :lab3
- add X-Instance-Id to every response and instance_id to every log
  record ([app] instance_id, hostname by default)
- require Idempotency-Key on POST messages: keys table in Postgres,
  key and message in one transaction, replay returns the same 201,
  another body gets 409, TTL from [idempotency] ttl_seconds
- send the key from student-tests, k6 scenarios and the skill driver;
  add idempotency, X-Instance-Id, key race and fault tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-08 19:42:36 +03:00

3.1 KiB
Raw Blame History

graceful-shutdown Specification

Purpose

Как сервис останавливается по SIGTERM: перестаёт принимать новые запросы, дорабатывает текущие и завершается за заявленный срок, до того как Docker применит SIGKILL.

Requirements

Requirement: Новые запросы после SIGTERM не принимаются

После получения SIGTERM сервис SHALL прекращать принимать новые соединения и MUST NOT начинать обработку новых запросов на уже открытых простаивающих соединениях.

Scenario: Нагрузка во время остановки

  • WHEN во время непрерывной отправки сообщений контейнеру отправлен SIGTERM
  • THEN запросы, начатые после сигнала, завершаются ошибкой соединения, а не ответом сервиса

Requirement: Текущие запросы дорабатывают

Запросы, начатые до SIGTERM, SHALL получать ответ, если укладываются в срок [app] graceful_shutdown_seconds. Запросы, которые не уложились, SHALL отменяться, чтобы процесс всё равно завершился.

Scenario: Запрос в полёте

  • WHEN SIGTERM приходит, пока сервис обрабатывает запрос
  • THEN клиент получает ответ на этот запрос, после чего процесс завершается

Requirement: Завершение за заявленный срок

Процесс SHALL завершаться после SIGTERM не дольше чем за [app] graceful_shutdown_seconds плюс время shutdown в lifespan. Это значение MUST быть не больше 9 с: Docker применяет SIGKILL через 10 с. Код выхода MUST NOT быть 137 (SIGKILL).

Scenario: docker stop

  • WHEN выполняется docker stop для работающего контейнера
  • THEN команда завершается быстрее 10 с, а код выхода контейнера не равен 137

Requirement: Остановка видна в журнале

Этапы остановки SHALL записываться в журнал сервиса JSON-записями с временем: начало остановки, завершение lifespan, завершение процесса. По меткам времени SHALL определяться длительность остановки.

Scenario: Журнал остановки

  • WHEN контейнер остановлен по SIGTERM
  • THEN в журнале по порядку есть «Shutting down», «Stopped API» и «Finished server process», и разница их timestamp меньше 10 с