Files
mtusi2026lab4/openspec/specs/object-storage/spec.md
T
ricoromaandClaude Opus 5.5 5b42bd2891 feat: compensate failed uploads and clean stale pending attachments
- upload: delete the stored object when ready fails before COMMIT or the
  pending row is gone (503 instead of 500); unknown COMMIT outcome keeps it
- cleaner service (python -m src.cleaner): stale pending rows older than
  grace (900 s, must exceed 17 s live-upload bound) under FOR UPDATE SKIP
  LOCKED, object before row, own S3 user with read/delete only
- shared session_scope for API and cleaner; early_stop process name
- partial index on pending attachments, CREATE INDEX CONCURRENTLY
- s3-bootstrap: cleaner user, policy and checks; make env_setup appends
  missing template variables to an existing .env
- failure checks: cleaner on the failure stand, id-list hook actions,
  five new and three updated tests; driver upload-consistency
- sync upload-consistency deltas into main specs (storage-consistency)

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

378 lines
22 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.
# object-storage Specification
## Purpose
S3-хранилище байтов стенда с лабы 4. Здесь описано:
- сервер, его закрепление и служебные интерфейсы вне сети;
- идемпотентный bootstrap приватного bucket;
- запрет анонимного доступа и ограниченные учётные данные API;
- проверка приватности вне API и сохранность данных при рестарте;
- клиент приложения: сроки вызовов, ошибки и ключи объектов по имени
базы.
## Requirements
### Requirement: S3-хранилище в стенде
Рабочий стенд compose (`make run_docker`) SHALL включать один
S3-совместимый сервер. Его образ SHALL быть закреплён тегом с версией и
digest индекса. Данные сервера SHALL
храниться в именованном volume. Сервису SHALL быть заданы:
- healthcheck, который проверяет готовность обслуживать запросы S3, в
том числе запись объекта: `healthy` MUST NOT наступать раньше, чем
хранилище томов готово принять запись;
- лимиты CPU и памяти;
- перезапуск после сбоя;
- срок остановки, за который сервер завершается сам, без принудительного
завершения.
Сервер SHALL выдерживать одновременную запись 20 объектов по 10 MiB без
превышения лимита памяти. Сервер MUST NOT отправлять сведения о стенде
внешним сервисам, в том числе анонимную статистику.
#### Scenario: Сервис S3 запущен
- **WHEN** в свежем clone выполнен `make run_docker`
- **THEN** контейнер S3 в состоянии `healthy`, его образ указан тегом с
версией и digest, а данные лежат в именованном volume проекта
#### Scenario: Первая запись после healthy
- **WHEN** контейнер S3 перезапущен с сохранённым volume и стал
`healthy`, и сразу после этого ключом API записывается объект
- **THEN** первая запись проходит заметно быстрее срока вызова клиента
(`[s3] timeout_seconds`), а не ждёт регистрации хранилища томов
#### Scenario: Остановка сервера
- **WHEN** выполняется `docker compose stop s3`
- **THEN** контейнер S3 завершается с кодом 0 раньше срока остановки,
а не принудительно
#### Scenario: Одновременная запись
- **WHEN** 20 клиентов одновременно записывают ключом API по объекту
10 MiB, затем читают их
- **THEN** все записи подтверждены и прочитаны с тем же размером, а
контейнер S3 не перезапускался и не был завершён из-за памяти
#### Scenario: Без внешней статистики
- **WHEN** стенд работает
- **THEN** у процесса S3 нет соединений с адресами вне сети стенда,
а отправка статистики выключена в описании сервиса
### Requirement: Служебные интерфейсы вне сети
Из контейнера S3 в сеть compose SHALL быть открыты только порт API S3 и
служебный gRPC-порт шлюза S3, без которого шлюз не работает. Консоль
администратора, UI и внутренние серверы хранилища (координатор,
метаданные, тома) MUST NOT быть доступны ни из сети compose, ни с хоста.
Порт API S3 SHALL публиковаться только на `127.0.0.1` хоста, другие
порты сервера MUST NOT публиковаться.
Изменение учётных записей и политик через служебный gRPC-порт SHALL
требовать токен, подписанный секретным ключом стенда. Без токена вызов
MUST NOT менять учётные записи сервера.
#### Scenario: Порты из сети стенда
- **WHEN** из другого контейнера сети compose проверяются порты
контейнера S3
- **THEN** открыты только порт API S3 и gRPC-порт шлюза, а порты
консоли, UI, координатора, метаданных и томов закрыты
#### Scenario: Порты на хосте
- **WHEN** для запущенного контейнера S3 выполняется `docker port`
- **THEN** опубликован только порт API S3 и только на `127.0.0.1`
#### Scenario: Учётная запись через gRPC-порт без токена
- **WHEN** клиент из сети стенда без токена передаёт шлюзу S3 через
gRPC-порт новую учётную запись с правами администратора
- **THEN** вызов отклонён как неаутентифицированный, а запросы S3 с
ключами этой записи получают отказ
### Requirement: Приватный bucket создаёт bootstrap
Bucket приложения SHALL создавать одноразовый сервис bootstrap стенда.
Bootstrap SHALL:
- создать bucket, если его нет;
- запретить анонимный доступ к bucket;
- завести пользователя API с политикой доступа (требование
«Ограниченные учётные данные API») и ключами из `.env`;
- завести пользователя уборщика с его политикой (требование
«Ограниченные учётные данные уборщика») и ключами из `.env`.
На рабочем стенде реплики API и уборщик MUST NOT стартовать, пока
bootstrap не завершился успешно. Стенды проверок с S3 (`make
test_isolated`, `make failure_checks`) запускают bootstrap до своих
контейнеров API, а стенд отказов — и до своего уборщика.
Повторный запуск SHALL завершаться успешно и не менять уже правильное
состояние: bucket и его объекты сохраняются, пользователи не
пересоздаются. Если в `.env` изменился секрет API или уборщика,
повторный запуск SHALL привести к нему учётные данные этого
пользователя, а прежний секрет SHALL перестать действовать.
Вывод bootstrap MUST NOT содержать секретов. Ошибка любого шага SHALL
давать ненулевой код выхода и сообщение, которое называет шаг.
#### Scenario: Первый запуск
- **WHEN** стенд поднимается на пустом volume S3
- **THEN** bootstrap создаёт bucket, пользователей API и уборщика и
завершается с кодом 0, и только после этого стартуют реплики API и
уборщик
#### Scenario: Повторный запуск
- **WHEN** на работающем стенде bootstrap запускается ещё дважды подряд
- **THEN** оба запуска завершаются с кодом 0 и сообщают, что bucket и
оба пользователя уже есть, а записанные ранее объекты читаются
#### Scenario: Новый секрет API
- **WHEN** в `.env` изменён секрет API или секрет уборщика, и bootstrap
запущен снова
- **THEN** запросы S3 с новым секретом этого пользователя проходят, а с
прежним получают отказ
#### Scenario: Ошибка bootstrap
- **WHEN** bootstrap не может выполнить шаг, например имя bucket
недопустимо
- **THEN** он завершается с ненулевым кодом и сообщением о шаге, реплики
API не стартуют, а в выводе нет секретов
### Requirement: Запрет анонимного доступа
Bucket SHALL быть приватным с первого старта сервера. Анонимный запрос
SHALL получать 403 на:
- чтение объекта и его метаданных;
- список объектов bucket и список bucket-ов;
- запись объекта и создание bucket.
Для несуществующего ключа ответ SHALL быть тем же 403: он MUST NOT
показывать, есть ли объект. Сервер MUST NOT работать без учётных
записей ни в какой момент, в том числе до первого запуска bootstrap.
#### Scenario: Анонимное чтение
- **WHEN** аноним с хоста или из сети стенда запрашивает существующий
объект bucket и его метаданные
- **THEN** оба ответа 403, байтов объекта в ответе нет
#### Scenario: Анонимный список и запись
- **WHEN** аноним запрашивает список объектов bucket, список bucket-ов
или записывает объект
- **THEN** каждый ответ 403, и объект не создан
#### Scenario: Несуществующий ключ
- **WHEN** аноним запрашивает ключ, которого в bucket нет
- **THEN** ответ 403, как для существующего ключа
#### Scenario: До bootstrap
- **WHEN** сервер только что запущен на пустом volume, а bootstrap ещё
не выполнялся
- **THEN** анонимное создание bucket и запись объекта получают 403
### Requirement: Ограниченные учётные данные API
У API SHALL быть свои учётные данные S3, отдельные от административных.
Пользователю API SHALL быть разрешены только чтение, запись и удаление
объектов своего bucket. Ему MUST NOT быть разрешены:
- список объектов;
- операции с bucket: создание, удаление, политика, ACL;
- публичный ACL объекта;
- управление учётными записями;
- любой доступ к другим bucket.
Административные учётные данные S3 MUST NOT передаваться репликам API.
#### Scenario: Работа с объектами
- **WHEN** ключом API в своём bucket записывается объект, читаются он
и его метаданные, затем объект удаляется
- **THEN** все операции проходят, а прочитанные байты совпадают с
записанными по SHA-256
#### Scenario: Запрещённые операции
- **WHEN** ключом API запрашиваются список объектов, создание и
удаление bucket, политика и ACL bucket и публичный ACL объекта
- **THEN** каждый запрос получает 403, а bucket и его доступ не
меняются
#### Scenario: Чужой bucket
- **WHEN** на сервере есть другой bucket, и ключом API в нём читается
объект, записывается объект и запрашивается список
- **THEN** каждый запрос получает 403
#### Scenario: Ключи реплик API
- **WHEN** проверяющий смотрит окружение реплик API в `docker compose
config`
- **THEN** там есть ключи пользователя API и нет административных
ключей S3 и ключа подписи
### Requirement: Ограниченные учётные данные уборщика
У уборщика (capability `storage-consistency`) SHALL быть свои учётные
данные S3, отдельные от учётных данных API и административных.
Пользователю уборщика SHALL быть разрешены только чтение и удаление
объектов своего bucket. Ему MUST NOT быть разрешены:
- запись объектов;
- список объектов;
- операции с bucket: создание, удаление, политика, ACL;
- публичный ACL объекта;
- управление учётными записями;
- любой доступ к другим bucket.
Ключи уборщика MUST NOT передаваться репликам API. Уборщик MUST NOT
получать ключи API, административные ключи S3 и ключ подписи.
#### Scenario: Работа уборщика с объектами
- **WHEN** ключом API записан объект, а ключом уборщика он прочитан,
удалён и удалён ещё раз
- **THEN** чтение отдаёт те же байты, оба удаления успешны, а объекта
после них нет
#### Scenario: Запрещённые операции уборщика
- **WHEN** ключом уборщика запрашиваются запись объекта, список
объектов, создание и удаление bucket, политика и ACL bucket, публичный
ACL объекта и объект другого bucket
- **THEN** каждый запрос получает 403, а bucket и его доступ не
меняются
### Requirement: Проверка приватности вне API
Приватность bucket и права ключей API и уборщика SHALL проверяться без
участия приложения двумя способами.
1. Каждый запуск bootstrap:
- ключ API записывает и читает проверочный объект и получает отказ на
список и на создание bucket;
- ключ уборщика читает и удаляет этот объект и получает отказ на
запись и на список;
- аноним получает отказ на чтение существующего объекта и на список.
При нарушении bootstrap завершается с ненулевым кодом, и реплики API
не стартуют.
2. Отдельная команда `make s3_check` на запущенном стенде. Она
повторяет проверки bootstrap и добавляет:
- анонимные запросы с хоста и из сети стенда;
- запросы ключей API и уборщика к чужому bucket;
- административные запросы ключей API и уборщика;
- запись и список ключом уборщика.
Команда SHALL печатать по каждой проверке ожидаемый и полученный код
ответа без секретов. При любом нарушении код выхода SHALL быть
ненулевым. Свои проверочные объекты и bucket команда SHALL удалять.
#### Scenario: Проверка командой
- **WHEN** на запущенном стенде выполняется `make s3_check`
- **THEN** каждая проверка напечатана с полученным кодом ответа, в том
числе проверки ключа уборщика, код выхода 0, а проверочных объектов и
bucket после команды нет
#### Scenario: Bucket стал публичным
- **WHEN** на bucket открыт анонимный доступ на чтение, например
административной командой мимо bootstrap
- **THEN** `make s3_check` завершается с ненулевым кодом и называет
нарушенную проверку, а следующий запуск bootstrap снова закрывает
доступ
### Requirement: Данные хранилища переживают рестарт
Bucket, учётные записи и объекты SHALL переживать перезапуск сервера S3
и всего стенда с сохранённым volume. Объекты с подтверждённой записью
SHALL сохраняться и после принудительного завершения процесса S3.
#### Scenario: Рестарт стенда
- **WHEN** объект записан ключом API, затем выполнен
`scripts/restart.sh`
- **THEN** контейнер S3 перезапущен (новое время старта), объект
читается тем же ключом с тем же SHA-256, bucket и пользователь API на
месте
#### Scenario: Принудительное завершение
- **WHEN** сразу после подтверждённых записей контейнер S3 завершён
сигналом KILL и запущен снова
- **THEN** все подтверждённые объекты читаются с тем же SHA-256
### Requirement: Клиент хранилища в приложении
Процессы приложения SHALL обращаться к S3 с учётными данными своей роли
из секции `[s3]`: реплики API — ключами пользователя API, уборщик —
ключами пользователя уборщика. Клиент SHALL уметь записать объект,
прочитать его потоком, получить метаданные и удалить. Удаление
отсутствующего объекта — не ошибка. Каждый вызов SHALL быть ограничен
сроком из настроек. После отказа или истечения срока вызов MUST NOT
повторяться автоматически.
Ошибкой недоступности, которую API отдаёт как 503 `unavailable` в
формате контракта, SHALL заканчиваться вызов, если S3:
- недоступен;
- не ответил за срок;
- отклонил учётные данные;
- отказал ключу в доступе или не нашёл bucket.
Такой вызов MUST NOT давать 500 или зависать. Отсутствующий объект SHALL
отличаться от недоступности: отсутствующий bucket MUST NOT выдаваться за
отсутствующий объект у записи, чтения и удаления. После возврата S3 вызовы SHALL проходить
без перезапуска приложения. Соединения с S3 SHALL открываться при
первом вызове, а при остановке сервиса клиент SHALL закрываться.
Ключ объекта SHALL начинаться с имени базы PostgreSQL процесса и `/`.
Так объекты прогона на временной базе (`make test_isolated`) отделены
от объектов рабочей базы.
#### Scenario: S3 остановлен
- **WHEN** S3 остановлен, и приложение записывает объект
- **THEN** вызов за доли секунды завершается ошибкой недоступности, без
повторов
#### Scenario: S3 завис
- **WHEN** контейнер S3 заморожен (`docker pause`), и приложение
записывает объект
- **THEN** вызов завершается ошибкой недоступности не позже срока
вызова
#### Scenario: S3 вернулся
- **WHEN** S3 снова доступен, а приложение не перезапускалось
- **THEN** следующий вызов проходит
#### Scenario: Объекта нет
- **WHEN** приложение читает ключ, которого в bucket нет
- **THEN** клиент сообщает, что объекта нет, а не недоступность S3
#### Scenario: Bucket нет
- **WHEN** bucket приложения удалён мимо bootstrap, и приложение
записывает, читает или удаляет объект
- **THEN** каждый вызов завершается ошибкой недоступности, а не
сообщением «объекта нет», и в журнале есть запись уровня `error`
#### Scenario: Учётные данные отклонены
- **WHEN** секрет API у приложения не совпадает с секретом на сервере
S3
- **THEN** вызов завершается ошибкой недоступности, а в журнале есть
запись уровня `error` без секрета