Files
mtusi2026lab6/openspec/specs/container-image/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e.
Contracts, public tests and evidence of lab 5 are not carried over.
The compose project, image and CI prefix are renamed to lab6; the first
broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the
OpenSpec changes of lab 6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 04:46:56 +03:00

8.4 KiB
Raw Blame History

container-image Specification

Purpose

Образ сервиса: как он собирается из исходников и что в нём есть. Сборка воспроизводима из чистого clone, версии закреплены, процесс работает без привилегий, конфиги и секреты в образ не попадают.

Requirements

Requirement: Сборка из чистого clone

docker build в корне свежего clone SHALL собирать образ без предварительных шагов: без make env_setup, без config.toml и .env. Зависимости SHALL устанавливаться строго по uv.lock. Если lock не соответствует pyproject.toml, сборка MUST завершаться ошибкой, а не пересчитывать версии.

Scenario: Свежий clone

  • WHEN в новом clone репозитория выполняется docker build -t mtusi-messenger:lab6 .
  • THEN образ собирается без ошибок

Scenario: Устаревший lock

  • WHEN в pyproject.toml добавлена зависимость, а uv.lock не обновлён
  • THEN сборка завершается ошибкой проверки lock

Requirement: Закреплённые версии

Базовые образы и инструменты сборки SHALL указываться явной версией и digest. Плавающие теги (latest, 3.12-slim и подобные) MUST NOT использоваться.

Scenario: Проверка Dockerfile

  • WHEN проверяющий читает строки FROM и COPY --from в Dockerfile
  • THEN каждая ссылка на образ содержит версию с патч-номером и @sha256:

Requirement: Непривилегированный пользователь

Процесс сервиса SHALL работать не от root. Код приложения и зависимости MUST NOT быть доступны этому пользователю на запись.

Scenario: UID процесса

  • WHEN в работающем контейнере выполняется id -u
  • THEN результат не равен 0

Scenario: Код только на чтение

  • WHEN пользователь контейнера пытается записать файл в каталог с кодом приложения
  • THEN запись отклоняется с ошибкой доступа

Requirement: Состав образа

Образ SHALL содержать только то, что нужно для работы сервиса и применения миграций: интерпретатор, зависимости времени выполнения, исходники src/, каталог миграций и конфигурацию инструмента миграций. В образе MUST NOT быть config.toml, .env, публичных и собственных тестов, контрактов, файлов .claude и openspec, а также инструментов сборки: uv и компиляторов.

Scenario: Нет конфигов и лишних каталогов

  • WHEN в образе просматривается рабочий каталог приложения
  • THEN в нём есть только исходники, миграции с их конфигурацией и окружение зависимостей, а config.toml и .env отсутствуют

Scenario: Нет uv в runtime

  • WHEN в контейнере запрашивается uv
  • THEN команда не найдена

Scenario: Миграции из образа

  • WHEN контейнер из этого образа запускается командой применения миграций с настройками подключения к Postgres
  • THEN миграции применяются без доступа к исходникам на хосте

Requirement: Сервер — основной процесс контейнера

Процессом с PID 1 SHALL быть сам сервер (python -m src), без оболочки и без uv run между Docker и сервером. Так сигналы остановки доходят до сервера напрямую.

Scenario: PID 1

  • WHEN в работающем контейнере читается командная строка процесса 1
  • THEN это python -m src

Requirement: Healthcheck образа

Образ SHALL объявлять healthcheck, который проверяет GET /health/ready на внутреннем порту сервиса. Healthcheck MUST работать и без compose, при запуске голым docker run.

Scenario: Контейнер становится healthy

  • WHEN контейнер запущен и сервис завершил старт
  • THEN docker inspect показывает состояние здоровья healthy до окончания start_period

Scenario: Healthcheck не шумит в логах

  • WHEN healthcheck отрабатывает несколько раз
  • THEN итоговых записей о запросах к health в журнале сервиса нет

Requirement: Worker на образе приложения

Worker SHALL запускаться из того же образа, что и API, своей командой. Процессом с PID 1 контейнера worker SHALL быть сам worker (python -m src.worker), без оболочки между Docker и им. Декодер изображений SHALL входить в образ зависимостью времени выполнения из uv.lock, без компиляторов в runtime. Healthcheck образа проверяет HTTP и worker не подходит: у контейнера worker он SHALL быть выключен, и живость видна по журналу.

Реплики API и сам процесс worker MUST NOT загружать декодер изображений в память: его загружает только дочерний процесс обработки (attachment-processing, «Лимиты обработки»).

Scenario: PID 1 worker

  • WHEN в работающем контейнере worker читается командная строка процесса 1
  • THEN это python -m src.worker, а docker inspect не показывает у контейнера проверки здоровья

Scenario: Декодер в образе

  • WHEN в образе, собранном из чистого clone, импортируется декодер изображений и запрашивается версия
  • THEN импорт проходит, версия совпадает с uv.lock, поддержка WebP есть, а uv и компиляторов в образе нет

Scenario: Декодера нет в процессе API

  • WHEN в работающей реплике API и в процессе 1 контейнера worker проверяются загруженные модули
  • THEN декодера изображений среди них нет

Requirement: Relay на образе приложения

Relay SHALL запускаться из того же образа, что и API, своей командой. Процессом с PID 1 контейнера relay SHALL быть сам relay (python -m src.relay), без оболочки между Docker и им. Healthcheck образа проверяет HTTP и relay не подходит: у контейнера он SHALL быть выключен, живость видна по журналу.

Scenario: PID 1 relay

  • WHEN в работающем контейнере relay читается командная строка процесса 1
  • THEN это python -m src.relay, а docker inspect не показывает у контейнера проверки здоровья