Files
mtusi2026lab5/openspec/specs/container-image/spec.md
T
ricoromaandClaude Opus 5.5 e2a6427c24 feat: add job outbox, relay, leases and image variants to the pipeline
Move publishing out of the upload path: a relay process publishes queued
jobs with confirms. Add lease and attempt fencing, backoff with jitter, a
per-job render process with CPU and memory limits, crop and optimized
variants, the failed registry with audited replay, and staging cleanup.

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

157 lines
8.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 и сам процесс 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` не показывает у контейнера проверки
здоровья