Files
mtusi2026lab3/openspec/changes/archive/2026-09-29-container-runtime/design.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

23 KiB
Raw Blame History

Design

Context

Мотивация — proposal.md, раздел Why. Требования — specs/.

Приложение уже готово к контейнеру (change messenger-core-api):

  • режим APP__RUN_MODE=docker слушает 0.0.0.0 без reload;
  • uvicorn.run получает timeout_graceful_shutdown из [app] graceful_shutdown_seconds (8 с, валидатор не пускает больше 9 с);
  • /health/ready исключён из итоговой записи о запросе;
  • логи — JSON в stdout, включая строки uvicorn.

Форму Dockerfile и compose задают .claude/rules/docker.md и run-modes.md: мультистейдж с uv и compose в стиле bp_proxies. config.toml монтируется на старте, это согласовано с преподавателем (AGENTS.md). Цели Makefile оформляются так же, как в bp_proxies, без Apple Container.

Факты, проверенные при планировании:

  • Образы. Последний патч Python 3.12 — python:3.12.14-slim-trixie (Debian 13), uv — ghcr.io/astral-sh/uv:0.12.17, та же версия, что локально. Оба digest — индексы для нескольких архитектур (amd64 и arm64):
    • python:3.12.14-slim-trixie@sha256:f77ac9e44ae96ef2c90b8053ea08c31f8be030f824196b0ae4db6d462c84e51f
    • ghcr.io/astral-sh/uv:0.12.17@sha256:10787c682e4184e4f290de1171fd4703dc63de99221f10fe1c99002ce7fa9acc
  • uvicorn 0.54 на SIGTERM. Сначала закрывает слушающий сокет, затем закрывает простаивающие соединения, ждёт текущие запросы до timeout_graceful_shutdown и отменяет оставшиеся. После этого выполняет shutdown в lifespan и повторно шлёт себе пойманный сигнал через signal.raise_signal.

Goals / Non-Goals

Goals:

  • docker build и docker run из README работают из чистого clone без подготовительных шагов, make test проходит против контейнера.
  • Уровень «4» по контейнеру проверяется командами:
    • non-root;
    • пины версий и digest;
    • .dockerignore;
    • остановка по SIGTERM быстрее 10 с;
    • healthcheck;
    • журнал без содержимого сообщений.
  • Доказательства лежат в evidence/container/ и в строках REPORT.md, а не только в выводе терминала.

Non-Goals:

  • Лимиты CPU и памяти контейнера — их задаст методика трека 1 в отдельном change.
  • Сборка образа под чужую архитектуру и публикация в registry: собираем локально под платформу хоста, а пины через индекс работают на обеих архитектурах.
  • CI-сборка образа (CONTRIBUTING.md предлагает отдельный job в CI) — по желанию, позже.

Decisions

1. Dockerfile: два stage на одном базовом образе

FROM python:3.12.14-slim-trixie@sha256:… AS builder
COPY --from=ghcr.io/astral-sh/uv:0.12.17@sha256:… /uv /bin/uv
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_PYTHON_DOWNLOADS=never \
    UV_PROJECT_ENVIRONMENT=/app/.venv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-dev --no-install-project

FROM python:3.12.14-slim-trixie@sha256:… AS runtime
RUN groupadd --system --gid 10001 app \
 && useradd --system --uid 10001 --gid app --no-create-home \
      --home-dir /nonexistent --shell /usr/sbin/nologin app
ENV PATH=/app/.venv/bin:$PATH PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 APP__RUN_MODE=docker
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY src ./src
USER app
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=3s --start-period=10s \
    --start-interval=1s --retries=3 \
  CMD ["python", "-c", "import os, urllib.request; urllib.request.urlopen('http://127.0.0.1:%s/health/ready' % os.environ.get('APP__PORT', '8080'), timeout=2)"]
CMD ["python", "-m", "src"]
  • Один базовый образ в обоих stage. Интерпретатор в .venv — это ссылка на /usr/local/bin/python3.12 базового образа. Если builder взять на другом образе, в runtime .venv перестанет работать.
  • --no-install-project. Проект не ставится в .venv как пакет: hatchling собрал бы его из src/, которого в builder ещё нет. python -m src запускается из /app, и src находится через текущий каталог.
  • Код без права записи. Код и .venv копируются от root и принадлежат root. Пользователь app (UID 10001) может их только читать — это требование «код только на чтение». PYTHONDONTWRITEBYTECODE убирает попытки записать .pyc рядом с src/. Зависимости скомпилированы в builder (UV_COMPILE_BYTECODE).
  • Кеш сборки. Слой зависимостей пересобирается только при изменении pyproject.toml или uv.lock. Cache mount ускоряет повторный uv sync, но в образ не попадает.
  • Порт в healthcheck. Берётся из APP__PORT, как у сервиса, значение по умолчанию — 8080. Так healthcheck работает и в README-запуске, и в compose, где порт может быть другим.
  • --start-interval=1s. Во время start_period проверка идёт раз в секунду. Без этого первая проверка — только через interval (10 с), и контейнер не станет healthy до конца start_period, как требует спека. Флаг поддерживается с Docker Engine 25.
  • Отличия от bp_proxies:
    • uv не ставится pip install без версии и не нужен в runtime;
    • config.toml не копируется в образ;
    • сервер запускается как PID 1 без uv run.

Альтернативы:

  • python:3.12-slim без пина — запрещено рубрикой.
  • Bookworm вместо trixie — trixie актуальный stable Debian, а 3.12.14-slim-bookworm тоже есть и нужен, только если найдётся несовместимость.
  • Distroless: сложнее отлаживать на защите (docker exec без shell), и пришлось бы переносить интерпретатор. Выигрыш в размере для учебного стенда не нужен.

2. Пины: тег и digest индекса

В FROM и COPY --from пишется тег@sha256:<digest индекса>. Тег говорит, какая это версия, digest гарантирует повторяемость, даже если тег перепубликуют с обновлениями безопасности. Digest индекса, а не манифеста одной платформы, одинаково работает на arm64 (машина автора) и amd64 (стенд преподавателя). Обновление версии — осознанная правка: новый тег и digest из docker buildx imagetools inspect <тег>.

3. .dockerignore

Файл из skeleton дополняется, а не заменяется (docker.md): config.toml, .claude, openspec, tests, student-tests, contracts, scripts, examples, *.md, Makefile, .ruff_cache, .idea, .python-version, а также **/__pycache__, **/*.py[cod], **/.DS_Store: паттерн skeleton __pycache__ без **/ действует только в корне, и .pyc хоста из src/ попадали в образ (найдено при проверке состава). Dockerfile копирует только pyproject.toml, uv.lock и src, так что .dockerignore — вторая линия защиты и способ уменьшить контекст сборки.

4. compose

services:
  api:
    build: .
    image: mtusi-messenger:lab1
    restart: unless-stopped
    ports:
      - "127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"
    environment:
      - APP__RUN_MODE=docker
      - APP__PORT=${APP__PORT:-8080}
    volumes:
      - type: bind
        source: ./config.toml
        target: /app/config.toml
        read_only: true
        bind:
          create_host_path: false
    stop_grace_period: 10s
  • Healthcheck не дублируется: compose берёт его из образа.
  • Тег образа тот же, что в README (mtusi-messenger:lab1), поэтому docker run из README и compose используют один образ.
  • Длинная запись bind-mount и её поведение при отсутствии файла проверены при подготовке правил (docker.md).

5. .env.example: параметры приложения — в формате настроек

Переменная, которая касается самого приложения, пишется в .env в формате настроек (SECTION__FIELD), даже если её читает и compose. Имя без секции — только у того, что приложение не читает:

# порт сервиса ([app] port): на нём слушает приложение, его же
# публикуют compose и make run_no_compose, на нём же healthcheck
APP__PORT=8080
# порт на 127.0.0.1 хоста, куда публикуется сервис; приложение его
# не читает
APP_OUT_PORT=8080
  • Кто читает APP__PORT. Все три способа запуска:

    • run_dev — pydantic-settings из .env на хосте;
    • run_no_compose — из окружения контейнера (--env-file .env);
    • compose — через environment.

    Порт всегда задаётся в .env, поэтому port убирается из config_example.toml: по приоритету (окружение > .env > config.toml) значение в toml всё равно ни на что бы не влияло. Поле App.port с дефолтом 8080 остаётся. Пример в шапке config_example.toml меняется с APP__PORT на APP__LOG_LEVEL. В локальном config.toml строка port безвредна, но её лучше убрать руками.

  • Мосты не нужны. Мост SECTION__FIELD=${VAR} остаётся для значений, чьё имя навязано контейнером зависимости (с лабы 2 — DATABASE__PASSWORD=${POSTGRES_PASSWORD}). Порт приложения принадлежит приложению, и compose читает ${APP__PORT} напрямую.

  • Комментарии в .env — только отдельными строками. Makefile читает .env через include (решение 6), а make, в отличие от compose, оставляет пробел перед # комментарий в конце строки частью значения.

Переменные skeleton соотносятся так, и это записывается в REPORT.md:

  • APP_HOST не нужен: адрес следует из режима (0.0.0.0 в docker);
  • APP_PORT — это APP__PORT ([app] port), внешний порт отдельно — APP_OUT_PORT;
  • APP_ENV — это APP__RUN_MODE, его задают Dockerfile и compose.

Локальный .env, созданный из старого шаблона, содержит APP_PORT, который ни на что не влияет. Его нужно обновить руками: make env_setup существующий файл не перезаписывает.

6. Цели Makefile: два способа запуска

Новая секция Docker targets в стиле run-modes.md. Переменные — в начале секции, а не в начале файла: верх Makefile принадлежит skeleton, и свои секции при переходе в следующую лабу переносятся целиком.

# порты — из того же .env, что читает compose; без .env — 8080
-include .env
APP__PORT ?= 8080
APP_OUT_PORT ?= 8080
DC=docker compose
DOCKER_IMAGE=mtusi-messenger:lab1
DOCKER_CONTAINER=mtusi-messenger-lab1

Способов запуска два, и оба входят в REPORT.md (решение 9):

  • run_no_compose — команды README без compose, порты из .env:
    run_no_compose: env_setup
    	DOCKER_BUILDKIT=1 docker build -t $(DOCKER_IMAGE) .
    	docker run --rm --name $(DOCKER_CONTAINER) \
    		-p 127.0.0.1:$(APP_OUT_PORT):$(APP__PORT) \
    		--env-file .env $(DOCKER_IMAGE)
    
    • Порты работают так же, как в compose: APP_OUT_PORT снаружи, APP__PORT внутри. Приложение само читает APP__PORT из окружения контейнера, и healthcheck стучится туда же. С .env из шаблона команда совпадает с README буква в букву (-p 127.0.0.1:8080:8080).
    • Разовая подмена внешнего порта — аргументом make, для обеих целей: make run_no_compose APP_OUT_PORT=8090, make run_docker APP_OUT_PORT=8090. Внутренний порт меняется только в .env: make run_no_compose APP__PORT=9090 поменял бы маппинг -p, а приложение взяло бы APP__PORT из --env-file .env. Префикс окружения (APP_OUT_PORT=8090 make ...) не работает: присваивание из .env перекрывает переменную окружения, и make экспортирует в recipe уже значение из .env, в том числе для docker compose (проверено на GNU Make 3.81). Аргумент make перекрывает .env и экспортируется. Голый docker compose up без make работает по правилам compose: окружение важнее .env.
    • Контейнер работает на переднем плане, как в README («в другом терминале: make test»): журнал виден сразу. make печатает команды, поэтому в выводе видно, что именно выполняется.
    • Ctrl+C: docker CLI без -t передаёт SIGINT процессу 1 (--sig-proxy по умолчанию), uvicorn останавливается штатно, как на SIGTERM. --rm удаляет контейнер. Из другого терминала — docker stop mtusi-messenger-lab1. Отдельная цель остановки не нужна.
    • config.toml не монтируется: это сценарий README «без compose и без config.toml». Параметры приложения, кроме заданных в .env, берутся по умолчанию. Свой config.toml — через compose.
    • Нужен .env (--env-file): без него docker run падает. Поэтому цель зависит от env_setup, как и run_docker: недостающие файлы создаются из шаблонов, существующие не трогаются. -include .env читается при разборе Makefile, раньше env_setup. Поэтому при первом запуске без .env в -p идут значения по умолчанию, 8080 — те же, что в шаблоне.
  • run_docker: env_setup — compose: сначала env_setup создаёт недостающие .env и config.toml из шаблонов (существующие не трогает), затем DOCKER_BUILDKIT=1 $(DC) build и $(DC) up -d. Так make run_docker работает в свежем clone без подготовки, а голый docker compose up без config.toml по-прежнему падает с явной ошибкой вместо каталога config.toml/. Для него же stop, down, logs ($(DC) logs -f --no-log-prefix api: без префикса api-1 | каждая строка — JSON).

Оба способа собирают один образ mtusi-messenger:lab1 и публикуют 127.0.0.1:$(APP_OUT_PORT) из одного .env. Одновременно работает только один из них, иначе второй не получит порт.

Цели skeleton не меняются.

7. Как проверяем SIGTERM

  1. Поднять контейнер и запустить tests/load.py на 20 с в фоне.
  2. Через несколько секунд выполнить time docker stop <контейнер>.
  3. Зафиксировать:
    • время docker stop (должно быть меньше 10 с);
    • docker inspect -f '{{.State.ExitCode}}' (не 137);
    • строки журнала Shutting down → Stopped API → Finished server process с метками времени;
    • отчёт load.py: запросы после сигнала — ошибки соединения, а не ответы.

Ожидаемый код выхода — 0. uvicorn после остановки повторно шлёт себе SIGTERM, но ядро не доставляет процессу с PID 1 сигнал без установленного обработчика, и Python завершается обычным образом. Если окажется 143, это тоже корректная остановка, а не SIGKILL. Фиксируем фактическое значение.

8. Сборка «из чистого clone» без коммита

git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t mtusi-messenger:lab1 -

В контекст попадают ровно те файлы, которые попали бы в clone после коммита: отслеживаемые и новые, но не игнорируемые. config.toml, .env и .venv исключаются .gitignore. Так проверка не требует ни коммита, ни временного каталога. Финальная проверка настоящим git clone делается перед PR, когда изменения закоммичены.

9. Доказательства и REPORT.md

  • evidence/container/ — текстовые выводы команд без секретов и без текстов сообщений: сборка, docker run и make test, жизненный цикл с рестартом, id -u и запись в src/, docker inspect (healthcheck, пользователь), SIGTERM.

  • REPORT.md:

    • раздел «Запуск из чистого clone»: версии, prerequisites и оба способа из решения 6. Для каждого: подготовка (обе цели сами вызывают make env_setup), цель Makefile и команды, которые она выполняет, ожидание готовности (/health/ready или healthy в docker ps), make test, остановка. Первым идёт make run_no_compose: он повторяет README. Сразу за ним — make run_docker с портом и config.toml;
    • часть раздела «Архитектура и решения»: процессы и хранилище, соответствие .env.example, согласования с преподавателем;
    • строки таблицы критериев для этого change со ссылками на файлы evidence/.

    Остальные TODO остаются для student-tests и трека.

Risks / Trade-offs

  • [Базовый образ под тегом со временем получает исправления, а мы на старом digest] → Это осознанная цена воспроизводимости. Обновление — правка тега и digest с пересборкой, порядок описан в docker.md.
  • [На Linux хосте config.toml с правами 600 не прочитать пользователю UID 10001] → В docker.md уже сказано про режим 644. В REPORT.md добавить строку о правах.
  • [Docker Desktop на macOS: время остановки и сеть идут через VM] → Замер SIGTERM показывает поведение процесса, а не сети. Числа фиксируются вместе с окружением (версия Docker Desktop, архитектура).
  • [Healthcheck раз в 10 с запускает Python-процесс в контейнере] → Около 30 мс CPU на проверку. На замерах трека 1 это нужно учесть или отключить через --no-healthcheck, и записать это в методику.
  • [restart: unless-stopped поднимет контейнер после рестарта Docker] → Для учебного стенда это удобно. Остановка через make stop сохраняется.

Migration Plan

Не применимо: новые файлы инфраструктуры, данных нет. Откат — удалить Dockerfile и docker-compose.yml, вернуть .dockerignore, .env.example, config_example.toml, Makefile и REPORT.md из git.