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>
157 lines
8.4 KiB
Markdown
157 lines
8.4 KiB
Markdown
# 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` не показывает у контейнера проверки
|
||
здоровья
|