Files
mtusi2026lab5/openspec/specs/container-image/spec.md
T
ricoromaandClaude Opus 5.5 ff1a83b6ff feat: process attachments asynchronously with RabbitMQ and a worker
Upload answers 202 after staging, a queued job in PostgreSQL and a broker
confirm; a separate worker publishes the original and a thumbnail with
bounded retries. Adds the job and variant tables, the broker service, the
worker S3 user, cleanup and reconcile support for staging and variants,
the failure stand with broker and worker, bench and driver updates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 06:48:20 +03:00

7.3 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:lab5 .
  • 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 MUST NOT загружать декодер изображений в память процесса.

Scenario: PID 1 worker

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

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

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

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

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