docs: complete lab 4 report and add the application CI job

- fill the skeleton sections of REPORT.md: author and target grade,
  launch from a clean clone, architecture and variable mapping, open
  questions to the teacher, limitations, sources and AI use
- add evidence/tests/clean-clone-final.md: clean clone of de98d77
- add .github/workflows/application.yml (CONTRIBUTING.md, CI) and the
  .github/ci/ override for the Gitea runner: configs instead of bind
  mounts, no host ports; evidence/tests/ci-application.md
- remove PLAN.md now that all changes are archived; point AGENTS.md
  and the rules at REPORT.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-29 18:12:55 +03:00
co-authored by Claude Opus 5.5
parent de98d77312
commit d947781591
13 changed files with 1376 additions and 1706 deletions
+3 -3
View File
@@ -88,7 +88,7 @@ FastAPI 0.141 из `uv.lock`:
`Retry-After` — положительное целое. У нас 429 — только у загрузки, когда
заняты места процесса (design change `upload-memory`, решение 2). Места
ограничивают одновременность, а не частоту: трактовка — вопрос 1
преподавателю (`PLAN.md`, `### upload-memory`). До ответа — 429, ответ
преподавателю (`REPORT.md`, «Открытые вопросы преподавателю»). До ответа — 429, ответ
«503» меняет строку `DOMAIN_ERRORS`, сценарии и тесты, но не подход.
`DELETE /auth/sessions/current` отвечает 204 без тела.
@@ -334,8 +334,8 @@ ACTION_SCRIPT=scripts/restart.sh` (`tests/README.md`), hook —
(`status=ready`, `error_code=null`: другого статуса контракт лабы 4 не
знает), ссылка в новом сообщении — 201. До пометки — 500, как выше.
Контракт неоднозначен («404 — объекта нет», «неожиданное исключение —
500», `status` только `ready`): это вопрос преподавателю (`PLAN.md`,
`### track2-reconciler`, «Вопросы», п. 1), сделан вариант по
500», `status` только `ready`): это вопрос преподавателю (`REPORT.md`,
«Открытые вопросы преподавателю», п. 2), сделан вариант по
умолчанию. Ответ «иначе» меняет ветку `open_content`, сценарий
`attachments` «Потерянный оригинал» и тест
`test_reconcile_finds_and_fixes`.
+12
View File
@@ -5,6 +5,8 @@ paths:
- ".dockerignore"
- "scripts/restart.sh"
- "infra/**"
- ".github/ci/**"
- ".github/workflows/application.yml"
---
# Dockerfile и compose
@@ -334,6 +336,16 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t
длинной записью с `create_host_path: false` (`infra/README.md`). В
`REPORT.md` — таблица роль → сервис → версия/digest → healthcheck →
volume → порт → способ передачи credentials.
- **Стенд в CI** — тот же `docker-compose.yml` плюс override
`.github/ci/compose.yml` (job `.github/workflows/application.yml`,
AGENTS.md, карта кода). Job раннера Gitea — контейнер на том же Docker,
что стенд: bind mount файла из рабочего каталога там не работает (пути
нет на хосте раннера), порты хоста job не видит. Override заменяет
каждый bind mount на `configs` из переменной окружения
(`.github/ci/stand-env.sh`), убирает `ports` (`!reset []`) и даёт образу
API тег прогона. Поэтому новый bind mount, новый порт или новый сервис
на образе API в `docker-compose.yml` — строка и в override, иначе job
упадёт на `bind source path does not exist` или возьмёт чужой образ.
## Обновление кода на стенде
+1 -1
View File
@@ -252,7 +252,7 @@ paths:
дефект;
- обхода и пропуска после отказа, как у Valkey, нет: без S3 путь
вложений всё равно 503. `/health/ready` S3 не проверяет (спек
`health`, решение 3 `PLAN.md`): текст работает без него.
`health`, design change `s3-storage`): текст работает без него.
- Клиенты внешних сервисов: адреса и секреты из `settings`
(`.claude/rules/settings.md`), таймаут на каждый вызов, ошибки
переводятся в доменные исключения. Логи — по `logging.md`, без
+1 -1
View File
@@ -148,7 +148,7 @@ paths:
lost» и `AttachmentNotFound` (404) до обращения к S3; метаданные и
`MessageService` эту колонку не смотрят (200 и 201, как у любого
`ready`). Ответ — вариант по умолчанию до ответа преподавателя
(`PLAN.md`, `### track2-reconciler`, «Вопросы», п. 1);
(`REPORT.md`, «Открытые вопросы преподавателю», п. 2);
- сверка bucket и БД — `AttachmentReconcileService(db_scope,
storage)` (`services/attachment_reconcile.py`, design change
`track2-reconciler`, решения 3, 4, 7, 8), сервис процесса уборщика:
+2 -2
View File
@@ -138,8 +138,8 @@ compose полю секции:
`POSTGRES_PASSWORD`, `VALKEY_PASSWORD` и шесть секретов S3 и печатает
только их имена. Существующий `.env` он не перезаписывает, а дописывает
в конец переменные шаблона, которых в нём нет (с change
`upload-consistency`, ответ основной сессии на вопрос 1 его
`PLAN.md`): секреты — случайными значениями той же подстановкой, что для
`upload-consistency`, design, «Уточнения apply», п. 1): секреты —
случайными значениями той же подстановкой, что для
нового `.env` (`ENV_FILLED`), остальные — значениями шаблона, под
комментарием `# added by make env_setup from .env.example`. Прежние
строки не меняются, в вывод — только имена («added to existing .env:
+72
View File
@@ -0,0 +1,72 @@
# Стенд в CI: docker-compose.yml + этот файл (COMPOSE_FILE job
# application, .github/workflows/application.yml). Раннер Gitea
# (act_runner) запускает job в контейнере рядом со стендом, на том же
# Docker. Файлы рабочего каталога есть только в контейнере job, а bind
# mount ищет их на хосте раннера; порты на 127.0.0.1 хоста из job не
# видны и на общем хосте заняли бы чужие. Поэтому отличия от рабочего
# стенда только такие:
# - конфиги — configs из переменных окружения (их выставляет
# .github/ci/stand-env.sh): compose копирует содержимое в контейнер при
# создании, пути на хосте не нужно;
# - портов на хосте нет: job подключается к сети стенда и ходит на
# haproxy по имени;
# - образ API — с тегом прогона: тег mtusi-messenger:lab4 на общем хосте
# раннера может собрать и чужой job.
# Остальное — сервисы, лимиты, volumes, секреты по сервисам — как в
# рабочем стенде. Нужен Compose ≥ 2.24 (!reset).
services:
postgres:
ports: !reset []
valkey:
ports: !reset []
volumes: !reset []
configs:
- source: valkey_conf
target: /usr/local/etc/valkey/valkey.conf
s3:
ports: !reset []
s3-bootstrap:
volumes: !reset []
configs:
- source: s3_bootstrap
target: /opt/s3/bootstrap.sh
migrate:
image: &ci-image mtusi-messenger:${CI_IMAGE_TAG:?CI_IMAGE_TAG is not set}
volumes: !reset []
configs: &config-toml
- source: config_toml
target: /app/config.toml
api:
image: *ci-image
volumes: !reset []
configs: *config-toml
cleaner:
image: *ci-image
volumes: !reset []
configs: *config-toml
haproxy:
ports: !reset []
volumes: !reset []
configs:
- source: haproxy_cfg
target: /usr/local/etc/haproxy/haproxy.cfg
# файлы по умолчанию 0444 и root: непривилегированные пользователи
# контейнеров читают, но не меняют — как read_only у bind mount
configs:
config_toml:
environment: CI_CONFIG_TOML
valkey_conf:
environment: CI_VALKEY_CONF
s3_bootstrap:
environment: CI_S3_BOOTSTRAP
haproxy_cfg:
environment: CI_HAPROXY_CFG
+38
View File
@@ -0,0 +1,38 @@
# Окружение шага job application (.github/workflows/application.yml),
# подключается через «.» из корня репозитория после make env_setup.
# Содержимое конфигов — в переменные для configs override
# .github/ci/compose.yml. $(cat …) срезает перевод строки в конце файла,
# поэтому он возвращается: копия побайтно равна файлу, а HAProxy без него
# конфиг не принимает («Missing LF on last line»). Значения не печатаются.
nl='
'
CI_CONFIG_TOML="$(cat config.toml)$nl"
CI_VALKEY_CONF="$(cat infra/valkey/valkey.conf)$nl"
CI_S3_BOOTSTRAP="$(cat infra/s3/bootstrap.sh)$nl"
CI_HAPROXY_CFG="$(cat infra/haproxy/haproxy.cfg)$nl"
export CI_CONFIG_TOML CI_VALKEY_CONF CI_S3_BOOTSTRAP CI_HAPROXY_CFG
# готовность стенда через LB: /health/ready отвечает 200 от API_REPLICAS
# (из .env, по умолчанию 2) разных реплик — X-Instance-Id. Срок 60 с:
# make replicas ждёт healthy контейнеров, а слот LB включается ещё через
# rise проверок
wait_replicas() {
want=$(sed -n 's/^API_REPLICAS=//p' .env)
want=${want:-2}
seen=""
deadline=$(($(date +%s) + 60))
while [ "$(date +%s)" -lt "$deadline" ]; do
reply=$(curl -s -o /dev/null -w '%{http_code} %header{x-instance-id}' \
"$BASE_URL/health/ready" || true)
case "$reply" in
"200 "?*) seen=$(printf '%s\n%s\n' "$seen" "${reply#200 }" | sort -u | grep .) ;;
esac
if [ "$(printf '%s\n' "$seen" | grep -c .)" -ge "$want" ]; then
echo "LB ready: $(printf '%s ' $seen)"
return 0
fi
sleep 0.5
done
echo "LB: $(printf '%s\n' "$seen" | grep -c .) of $want replicas ready in 60 s" >&2
return 1
}
+129
View File
@@ -0,0 +1,129 @@
# Job приложения (CONTRIBUTING.md, «CI»): сборка образа, стенд и его
# готовность через LB, make check и make test, затем проверки, которым
# хватает сети стенда: приватность bucket для анонима, собственные тесты,
# сохранность после рестарта и отказ реплики. Workflow skeleton
# contracts.yml проверяет только контракт и не меняется.
# Раннер Gitea (act_runner) запускает job в контейнере на том же Docker,
# что и стенд: конфиги и порты — override .github/ci/compose.yml, к LB job
# ходит по сети стенда. Секретов CI не получает: пароли и ключи — случайные
# из make env_setup и живут только в прогоне. pull_request_target не
# используется (CONTRIBUTING.md). Нет make s3_check, test_isolated и
# failure_checks: им нужны порты на хосте; их результат — evidence/.
name: Application
on: [push, pull_request, workflow_dispatch]
permissions:
contents: read
# прогоны репозитория по очереди и без отмены: отменённый посреди прогона
# job оставил бы стенд на общем хосте раннера, а уборка хвостов не должна
# задеть стенд соседнего прогона
concurrency:
group: application-${{ github.repository }}
cancel-in-progress: false
jobs:
application:
runs-on: ubuntu-latest
timeout-minutes: 40
env:
# свой проект, volumes и образ у каждого прогона
COMPOSE_PROJECT_NAME: mtusi-lab4-safronov-ci-${{ github.run_id }}
COMPOSE_FILE: docker-compose.yml:.github/ci/compose.yml
CI_IMAGE_TAG: safronov-ci-${{ github.run_id }}
# LB по имени сервиса в сети стенда, порт — APP__PORT из .env.example
BASE_URL: http://haproxy:8080
steps:
- name: Checkout
# ровно commit прогона; репозиторий публичный, токен не нужен
run: |
git init -q .
git remote add origin "${{ github.server_url }}/${{ github.repository }}.git"
git fetch -q --depth=1 origin "${{ github.sha }}"
git checkout -q --detach FETCH_HEAD
git log --oneline -1
- name: Runner
run: |
docker info --format 'docker {{.ServerVersion}}, {{.OSType}}/{{.Architecture}}, {{.NCPU}} CPU, {{.MemTotal}} B'
docker compose version
python3 -V
- name: Remove stands of interrupted runs
# только проекты этого workflow: прогон, прерванный без уборки
# (сбой раннера), оставил бы их на хосте
run: |
for p in $(docker ps -a --format '{{.Label "com.docker.compose.project"}}' | grep '^mtusi-lab4-safronov-ci-' | sort -u || true); do
echo "remove leftover stand $p"
docker ps -aq --filter "label=com.docker.compose.project=$p" | xargs -r docker rm -f >/dev/null
docker volume ls -q --filter "label=com.docker.compose.project=$p" | xargs -r docker volume rm >/dev/null
docker network ls -q --filter "label=com.docker.compose.project=$p" | xargs -r docker network rm >/dev/null || true
done
- name: Build and start the stand
run: |
make env_setup
. .github/ci/stand-env.sh
docker compose config --quiet
make run_docker
make replicas
docker network connect "${COMPOSE_PROJECT_NAME}_default" "$HOSTNAME"
wait_replicas
docker compose ps -a --format 'table {{.Service}}\t{{.Status}}'
- name: make check and make test
run: |
make check
make test
- name: Bucket is closed to anonymous requests
# без подписи: список bucket и объектов — 403. Полная проверка
# приватности — make s3_check (evidence/s3/privacy.md)
run: |
s3="http://s3:$(sed -n 's/^S3_PORT=//p' .env)"
bucket=$(sed -n 's/^S3__BUCKET=//p' .env)
for url in "$s3/" "$s3/$bucket" "$s3/$bucket?list-type=2"; do
code=$(curl -s -o /dev/null -w '%{http_code}' "$url")
echo "anonymous GET $url -> $code"
test "$code" = 403
done
- name: Install uv
# та же версия, что в Dockerfile
run: |
python3 -m venv "$RUNNER_TEMP/uv"
"$RUNNER_TEMP/uv/bin/pip" install -q uv==0.12.17
echo "$RUNNER_TEMP/uv/bin" >> "$GITHUB_PATH"
- name: make student_test
# через LB: тесты реплик выполняются, проверки отказов — нет
run: make student_test
- name: make test-persistence
run: |
. .github/ci/stand-env.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
wait_replicas
- name: make test-failover, stop and kill
# остановленную реплику возвращает make replicas (те же ID)
run: |
. .github/ci/stand-env.sh
log="$RUNNER_TEMP/stop-one.log"
STOP_ONE_LOG="$log" make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make replicas
wait_replicas
STOP_ONE_LOG="$log" STOP_MODE=kill make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make replicas
wait_replicas
cat "$log"
- name: Stand logs
if: failure()
run: |
if [ -f .env ]; then docker compose ps -a; docker compose logs --no-color --tail=200; fi
- name: Remove the stand
if: always()
run: |
docker network disconnect "${COMPOSE_PROJECT_NAME}_default" "$HOSTNAME" 2>/dev/null || true
if [ -f .env ]; then docker compose down -v --remove-orphans; fi
docker image rm "mtusi-messenger:$CI_IMAGE_TAG" >/dev/null 2>&1 || true
+20 -8
View File
@@ -48,8 +48,10 @@ S3 нет срока чтения aiohttp (он переживал ответ и
SHA-256) в разовом проходе, предел скорости `[reconciler]
max_objects_per_second` (2000 объектов S3/с), отказ по пределу без
лишних перепроверок, стоимость прохода в его итоге, профиль `reconcile`
стенда `bench/`. План работ, решения и
трек «5» — `PLAN.md`. Из лабы 2: PostgreSQL
стенда `bench/`. Рабочий план лабы 4 (`PLAN.md`) удалён после закрытия
всех changes: итоги — в `REPORT.md`, открытые вопросы преподавателю — в
его разделе «Открытые вопросы преподавателю», последняя версия плана —
`git show fd03b84:PLAN.md`. Из лабы 2: PostgreSQL
как источник истины, вход по Basic → Bearer-сессия, Valkey — кэш
карточек чатов. Из лабы 3: HAProxy перед ≥2 репликами API
(`replicas-lb`), `X-Instance-Id` и обязательный `Idempotency-Key`
@@ -83,7 +85,9 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
(кроме своих `scripts/restart.sh` и `scripts/stop-one.sh` по образцам
`restart.example.sh` и `stop-one.example.sh`),
`lab.json`, `README.md`, `COURSE.md`, `CONTRIBUTING.md`,
`MAINTAINERS.md`, `.github/`, `compose.example.yaml`,
`MAINTAINERS.md`, `.github/` (кроме своего CI job по `CONTRIBUTING.md`,
«CI»: `.github/workflows/application.yml` и `.github/ci/`),
`compose.example.yaml`,
`infra/README.md`, цели `check` / `validate` / `test` / `load` /
`test-persistence` / `test-failover` в `Makefile`. Если публичный тест упал, чиним
приложение, а не тест. Если в контракте противоречие — сказать
@@ -184,7 +188,8 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
только при живом bucket; больше `[reconciler] max_changes` (100)
изменений — ни одного и код 3. Потерянный оригинал помечается
(`attachments.lost_at`): скачивание — 404, метаданные — 200, ссылка —
201 (вопрос преподавателю, `PLAN.md`). Уборщику разрешён список только
201 (вопрос преподавателю, `REPORT.md`, «Открытые вопросы
преподавателю»). Уборщику разрешён список только
с префиксом `<база>/attachments/` (`S3_CLEANER_LIST_PREFIX` у
bootstrap). На время восстановления базы уборщик останавливают
(`docker.md`). С change `track2-reconcile-cost`: проход затрагивает в
@@ -239,7 +244,6 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
| Файл | Что в нём |
|---|---|
| `README.md` | задание лабы: рубрика 3/4/5, сценарий и вопросы защиты, что приложить к PR |
| `PLAN.md` | наш план лабы 4 на «5»: рубрика → change, ключевые решения (S3-сервер, порядок записи, память), трек 2, порядок changes, риски; удаляется, когда все changes закрыты |
| `COURSE.md` | карта семи лаб, три объявленных перехода API (1→2, 2→3, 4→5), правила честных измерений |
| `contracts/openapi.json` | нормативный OpenAPI 3.1: пути, схемы, коды ответов |
| `contracts/README.md` | нормативная семантика: формат ошибок, валидация, пагинация, Basic → Bearer-сессии, TTL и отзыв, с lab3 — `Idempotency-Key` и `X-Instance-Id`, с lab4 — вложения: сырые bytes PNG/JPEG ≤10 MiB и ≤40 млн пикселей, `201 Attachment` (`ready`), `attachment_ids` в сообщении, download только участникам; пустой текст (в том числе из пробелов) — только с вложением (согласование 2026-10-20); разделы lab5+ — на будущее; как это сделано — `api-contract.md`, «Вложения (лаба 4)» |
@@ -257,7 +261,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
| `REPORT.md` | отчёт: запуск из чистого clone, архитектура, доказательства по каждому критерию, эксперименты, ИИ и источники |
| `evidence/` | сохранённые выводы проверок и измерений (что можно класть — `evidence/README.md`) |
| `CONTRIBUTING.md` | fork/PR, имя ветки, что переносить в следующую лабу |
| `.github/pull_request_template.md` | шаблон PR; CI `workflows/contracts.yml` проверяет только контракт, приложение не запускает |
| `.github/pull_request_template.md` | шаблон PR; CI `workflows/contracts.yml` проверяет только контракт, приложение не запускает; сборку, стенд и `make test` — свой job `workflows/application.yml` (карта кода) |
| `Dockerfile.example` | опорные шаги Dockerfile, не рабочий файл |
| `.env.example` | шаблон `.env`; «логические» имена skeleton (lab2, lab3 `API_REPLICAS`, `IDEMPOTENCY_TTL_SECONDS` и новые lab4 `S3_*`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`) перечислены в шапке, их соответствие — в `REPORT.md` (`settings.md`) |
| `examples/requests.http` | ручные запросы для HTTP-клиента IDE |
@@ -285,7 +289,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
| `logging.md` | сервисы, API, инфраструктура, `src/main.py`: где и как логировать, чего в логах быть не должно |
| `settings.md` | `src/config/**`, `.env.example`, `config_example.toml`: источники настроек, что куда класть |
| `run-modes.md` | точки входа, `Makefile`, compose, шаблоны конфигов: console и docker, uvicorn, SIGTERM |
| `docker.md` | `Dockerfile`, `docker-compose.yml`, `.dockerignore`, `scripts/restart.sh`, `infra/**`: мультистейдж, non-root, пины, healthcheck, стенд compose, S3 и bootstrap, секреты по сервисам, volumes, restart hook |
| `docker.md` | `Dockerfile`, `docker-compose.yml`, `.dockerignore`, `scripts/restart.sh`, `infra/**`, `.github/ci/**`, `.github/workflows/application.yml`: мультистейдж, non-root, пины, healthcheck, стенд compose, S3 и bootstrap, секреты по сервисам, volumes, restart hook |
| `balancer.md` | `docker-compose.yml`, `infra/haproxy/**`, `scripts/stop-one.sh`, `scripts/rolling-update.sh`: реплики за HAProxy, проверки и цепочка таймаутов, повторы LB, failover hook, поочерёдная замена, лимиты и пулы (с лабы 3) |
| `student-tests.md` | `student-tests/**`: обязательные проверки уровня 4, black-box по HTTP, особый стенд |
| `bench.md` | `bench/**`: нагрузочный стенд на Postgres (проект compose `mtusi-bench`), что не меняется между метками замеров, граница чёрного ящика и планы запроса, сравнение меток, коммиты измеренных состояний |
@@ -549,6 +553,9 @@ evidence/plots/scaling/ # make bench_plots по сериям a и b: гра
evidence/plots/scaling-db/ # make bench_plots по серии db: R* по лимитам PostgreSQL и раздел «Насыщение PostgreSQL»
evidence/uploads/ # change upload-memory: <метка>/ — make bench_uploads (meta.json, runs.csv, summary.md, raw/), lb-timeouts.md — driver.py lb-upload-timeouts, rollout-upload.md — медленная загрузка во время make rolling_update
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md
.github/workflows/application.yml # свой CI job (CONTRIBUTING.md, «CI»; contracts.yml — skeleton): checkout commit прогона, сборка и стенд под проектом mtusi-lab4-safronov-ci-<run_id>, job подключается к сети стенда, готовность — обе реплики через LB, make check / test, аноним в S3 — 403, make student_test, test-persistence, test-failover stop и kill, уборка при любом исходе; без s3_check, test_isolated и failure_checks (порты хоста). Раннер Gitea (act_runner) запускает job в контейнере на том же Docker, что стенд
.github/ci/compose.yml # override стенда в CI: конфиги — configs из переменных окружения вместо bind mount (файлов job нет на хосте раннера), без портов на хосте, образ API с тегом прогона
.github/ci/stand-env.sh # «.» в шагах job: содержимое конфигов в CI_* для configs (с переводом строки в конце: без него HAProxy конфиг не принимает), wait_replicas — /health/ready 200 от API_REPLICAS разных реплик через LB за 60 с
KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы
```
@@ -630,7 +637,12 @@ KNOWN_ISSUES.md # найденные попутно дефекты,
`scripts/rolling-update.sh` (без примеров и проверок skeleton в
`scripts/`), `pyproject.toml`, `uv.lock`, `.python-version`,
`config_example.toml`, `AGENTS.md`, `CLAUDE.md`, `.claude/`,
`openspec/`, `.graphifyignore`, `bench/`, `KNOWN_ISSUES.md`.
`openspec/`, `.graphifyignore`, `bench/`, `KNOWN_ISSUES.md`, свой CI
job `.github/workflows/application.yml` и `.github/ci/` (остальное в
`.github/` — из нового skeleton). В job поменять номер лабы в префиксе
проекта `mtusi-lab4-safronov-ci-` (и в шаге уборки хвостов), в
override — новые сервисы и конфиги нового стенда; Actions в новом fork
включить в его настройках.
- Сливать, а не копировать поверх: `Makefile`, `.env.example`,
`.gitignore`, `.dockerignore`. Берём версию нового skeleton (в ней
новые цели и проверки) и дописываем свои секции.
-1660
View File
File diff suppressed because it is too large Load Diff
+584 -31
View File
@@ -1,15 +1,233 @@
# Отчёт — лабораторная 4
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Сафронов Роман Николаевич, БВТ2301
- Целевая оценка 5; выбранный трек 5: трек 2 «Согласованность двух
хранилищ» (сверка bucket и БД — change `track2-reconciler`, стоимость
обхода — change `track2-reconcile-cost`)
- Commit/PR: ветка `solution/bvt2301-safronov`, PR «ЛР 4 — БВТ2301 —
Сафронов — на 5» (ссылка — после публикации). Из чистого clone
проверен commit `de98d77` (2026-10-29, итоговый код всех changes
лабы 4): `evidence/tests/clean-clone-final.md`. После него менялись
только документы и добавлен CI job (`.github/workflows/application.yml`,
раздел «CI»); код приложения и стенда прежний.
- Использованные источники, библиотеки и помощь ИИ: раздел «Источники,
библиотеки и использование ИИ» в конце отчёта.
Сделано по changes OpenSpec (`openspec/changes/archive/`) поверх кода
лабы 3:
- `s3-storage` (уровни «3» и «4»): SeaweedFS в стенде с закреплённым
образом и volume, приватный bucket с первой секунды, одноразовый
идемпотентный `s3-bootstrap`, у API свой пользователь S3 с правами
только на объекты bucket, служебные серверы на loopback, проверка
приватности вне API `make s3_check`;
- `attachments` (уровни «3» и «4»): загрузка PNG/JPEG сырыми байтами со
структурной проверкой до записи, метаданные в PostgreSQL, скачивание
только участникам, `attachment_ids` в сообщениях, тесты рубрики;
- `upload-consistency` (уровень «4»): строка `pending` до PUT,
компенсация в загрузке, отдельный сервис-уборщик незавершённых
загрузок с grace 900 с и своим пользователем S3;
- `upload-memory` (уровень «4»): места загрузки на реплику (4 + очередь
16, затем 429), срок тела, одна копия тела при PUT, буферы сокетов и
сроки LB пути загрузки, замер памяти при 1–40 одновременных загрузках;
- `track2-reconciler` (уровень «5», трек 2): сверка bucket и БД с
dry-run, исправлением, повторным запуском и пределом изменений,
пометка потерянного оригинала;
- `fix-upload-put-flake` (исправление уровня «4»): причина редких 503 на
загрузке — срок чтения aiohttp портил соединение в пуле клиента S3;
- `track2-reconcile-cost` (уровень «5», трек 2): гипотезы до замера,
профиль стоимости обхода, стратегия «HEAD на строку», глубокая сверка
по SHA-256, предел скорости, ранний отказ по пределу.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
**Версии.** Образ API: `python:3.12.14-slim-trixie` и `uv 0.12.17`; LB:
`haproxy:3.4.6-trixie`; PostgreSQL: `postgres:18.6-trixie`; Valkey:
`valkey/valkey:9.1.2-trixie`; S3: `chrislusf/seaweedfs:4.48`. Все
закреплены тегом и digest индекса в `Dockerfile` и `docker-compose.yml`
(таблица «Сервисы стенда» ниже). Приложение: Python 3.12, FastAPI
0.141.1, uvicorn 0.54.0, pydantic 2.13.5, pydantic-settings 2.15.0,
SQLAlchemy 2.1.1 (async), asyncpg 0.31.0, alembic 1.20.0, argon2-cffi
25.1.0, redis-py 8.1.0, structlog 24.4.0, aiobotocore 3.9.2 (botocore
1.43.106, aiohttp 3.14.5), остальное строго по `uv.lock`. Тесты: pytest
9.1.1, httpx 0.28.1, Pillow 13.0.0 (JPEG в тестах); нагрузка: k6 2.3.0
в контейнере (`grafana/k6:2.3.0@sha256:…`, `bench/run.py`). Проверено на
Docker Desktop 29.9.2 (ВМ linux/arm64, 12 CPU, 7,7 GiB), macOS на Apple
M3 Pro.
### S3 (change `s3-storage`)
**Нужно на машине:**
- Docker Engine 25+ с BuildKit и Compose v2, `make`, `openssl` (секреты
в `make env_setup`), `curl`;
- `python3` 3.9+ для публичных `make check`, `make test`, `make
test-persistence`, `make test-failover` и для драйвера скилла (`make
instances`, `make s3_check`, `driver.py …`) — только stdlib;
- uv — для `make validate`, `make student_test`, `make test_isolated`,
`make failure_checks`, стенда замеров `make bench*` и `make run_dev`;
- свободные порты `127.0.0.1:8080` (LB), `5433` (PostgreSQL), `6380`
(Valkey), `8334` (API S3) и `18088` (`make test_isolated`). Стенды
лаб 2 и 3 занимают те же порты: перед запуском их останавливают
(`make stop` в их каталоге). Другой порт LB — строкой `APP_OUT_PORT`
в `.env` или аргументом make (`make run_docker APP_OUT_PORT=8090`),
затем `make test BASE_URL=http://localhost:8090`.
**Подготовка и секреты.** `make env_setup` создаёт `.env` из
`.env.example` и `config.toml` из `config_example.toml`. В шаблоне
пароли PostgreSQL и Valkey и шесть секретов S3 пустые, в новый `.env`
подставляются случайные (`openssl rand`): общего секрета стенда в git
нет. Печатаются только имена. Отдельно запускать `env_setup` не
обязательно: его вызывают `make run_docker`, `make run_dev`, `make
test_isolated` и `make failure_checks`. Пароль PostgreSQL и
административная пара S3 задаются при создании volume: после их смены
нужен `make wipe_data`.
Последовательность проверяющего — та, что прошла из настоящего `git
clone` (`evidence/tests/clean-clone-final.md`):
```sh
git clone <fork> && cd <каталог clone> && git checkout solution/bvt2301-safronov
make env_setup # .env (случайные пароли и секреты S3) и config.toml из шаблонов
make run_docker # build + up -d: postgres, valkey, s3 → migrate, s3-bootstrap → api × 2 и cleaner → haproxy
make replicas # дождаться healthy реплик; готовность стенда — haproxy (healthy)
make check # структура skeleton
uv sync && make validate PYTHON=.venv/bin/python # полная валидация OpenAPI 3.1
make test # публичный smoke через LB: загрузка fixture, сообщение с attachment_ids, SHA-256, 404 постороннему
make instances # ≥2 X-Instance-Id одной сессии через LB
make s3_check # приватность bucket вне API: права ключей API и уборщика, аноним, порты S3
make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт LB, реплик, PostgreSQL, Valkey и S3: те же данные и оригинал
STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановлена одна реплика
make replicas # вернуть остановленную реплику (тот же контейнер и ID)
curl -s -o /dev/null http://127.0.0.1:8080/health/live # сдвиг очереди round-robin: тест выберет другую реплику
STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановлена вторая
make replicas
python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 attachment-failover --mode stop # принявшая реплика остановлена: файл отдаёт другая
python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 attachment-storage # байты только в приватном bucket, не в БД и не на диске API
make student_test # свой набор через LB, тесты реплик выполняются
make reconcile # сверка bucket и БД, dry-run: код 0 — расхождений нет
make test_isolated # образ на временной базе test_messenger, один контейнер API: smoke + свой набор
make failure_checks # проверки отказов на отдельном проекте mtusi-lab4-failures (~15 мин); рабочий стенд не трогается
```
Ожидаемо — так прошло на `de98d77` (2026-10-29, все шаги с кодом 0):
- `make check`, `make validate`, `make test`, `make test-persistence` и
оба `make test-failover` — `PASS`. У `test-failover` `failed_attempts`
0, восстановление 1,08 и 1,2 с;
- `make instances` — `instances: 2`, по 6 ответов каждой реплики;
- `make s3_check` — `PASS: 70 checks, bucket messenger is private`;
- `attachment-failover` — загрузку приняла одна реплика, после её
остановки файл отдала другая с тем же SHA-256, постороннему — 404;
`attachment-storage` — `PASS`, файлов оригинала в контейнерах API 0;
- `make student_test` — `198 passed`, сверка покрытия «252 scenarios in
13 specs, 235 tested (70 by make failure_checks), 17 excluded»;
- `make reconcile` — `found {}`, код 0;
- `make test_isolated` — `193 passed, 5 skipped`: тесты реплик против
одного процесса пропускаются с причиной;
- `make failure_checks` — `56 passed` за ~14 мин и строка сводки журнала
PostgreSQL стенда отказов `[failure_checks] postgres log: … crash
markers 0`.
Строка `STOP_ONE_LOG` называет `TARGET_INSTANCE_ID`, который выбрал
тест, и полный ID остановленного контейнера; `docker compose ps -a`
показывает его `Exited`. Порт 8080 хоста был занят посторонним
контейнером, поэтому клон поднимался на `APP_OUT_PORT=8090` под своим
проектом compose; это две строки `.env` до `make env_setup`
(`evidence/tests/clean-clone-final.md`).
Вариант README без make — те же compose-команды, но после `make
env_setup`: без `config.toml` compose падает с `bind source path does
not exist` (он монтируется read-only, `create_host_path: false`), без
секретов — на «… is empty».
```sh
make env_setup
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build # тот же стенд, что make run_docker
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/health/ready # 200 — готов
```
### CI
Workflow skeleton `.github/workflows/contracts.yml` проверяет только
контракт и не менялся. Сборку, стенд и `make test` ведёт свой job
`.github/workflows/application.yml` (`CONTRIBUTING.md`, «CI») на раннере
Gitea при каждом push в fork. Actions включены в настройках fork; в
репозитории преподавателя они выключены, поэтому статуса job на самом PR
нет — ссылка на прогон в описании PR.
Шаги job:
1. checkout ровно commit прогона;
2. `make env_setup`, `make run_docker`, `make replicas` под своим
проектом compose `mtusi-lab4-safronov-ci-<run_id>`;
3. готовность: `/health/ready` 200 через LB от двух разных
`X-Instance-Id`;
4. `make check`, `make test`;
5. анонимный GET в S3 (список bucket и объектов) — 403;
6. `make student_test` через LB, тесты реплик выполняются;
7. `make test-persistence`;
8. `make test-failover` в режимах `stop` и `kill`, после каждого —
`make replicas`;
9. при любом исходе — уборка стенда, его volumes и образа прогона.
Раннер (`act_runner`, образ `gitea/runner-images:ubuntu-latest`)
запускает job в контейнере на том же Docker, что и стенд. Поэтому
отличия от локального запуска собраны в override `.github/ci/compose.yml`:
- bind mount файлов рабочего каталога (их нет на хосте раннера) заменены
`configs` из переменных окружения — побайтная копия файла
(`.github/ci/stand-env.sh`; без последнего перевода строки HAProxy
конфиг не принимает);
- порты на хост не публикуются: job подключается к сети стенда и ходит
на `http://haproxy:8080`;
- образ API — с тегом прогона, а не общим `mtusi-messenger:lab4`.
Секретов CI не получает: пароли и ключи — случайные из `make env_setup`
и живут только в прогоне. Права токена — `contents: read`,
`pull_request_target` нет. Прогоны идут по очереди и без отмены: прерванный
job оставил бы стенд на общем хосте раннера, а шаг уборки хвостов удаляет
только проекты с префиксом этого job. Без `make s3_check`, `make
test_isolated`, `make failure_checks` и замеров: им нужны порты хоста и
отдельные проекты, их вывод — в `evidence/`.
Шаги workflow как есть прошли в той же схеме локально: контейнер образа
раннера с сокетом Docker, файлы скопированы внутрь. Все шаги — код 0 за
~2,5 мин со сборкой из кэша: `make test` — `PASS`, `make student_test` —
198 passed, `make test-persistence` и оба `make test-failover` — `PASS`
(`evidence/tests/ci-application.md`).
### Сценарий защиты
```sh
make test # 1–2. fixture, сообщение с attachment_ids, второй участник — тот же SHA-256, третий — 404 на метаданные и байты
D=.claude/skills/run-mtusi-messenger/driver.py
python3 $D --port 8080 upload --token <токен> --chat <id> --file tests/fixtures/sample.png # то же по шагам
python3 $D --port 8080 download --token <токен второго участника> --attachment <id> # SHA-256 оригинала
make s3_check # 2. прямой анонимный GET в S3 — 403 (с хоста и из сети стенда)
make test-persistence ACTION_SCRIPT=scripts/restart.sh # 3. рестарт всего стенда: прежний токен, тот же оригинал
python3 $D --port 8080 attachment-failover --mode kill # 3. загрузившая реплика убита: скачивание через другую, тот же SHA-256
python3 $D --port 8080 attachment-storage # 4. схема, ключ, объект в bucket, docker diff реплик — файла оригинала нет
# уровень 4
python3 $D --port 8080 upload-consistency # S3 заморожен и сбой фиксации ready: 503, компенсация, уборщик убирает остатки
make failure_checks # отказы S3, PostgreSQL, места загрузок, срок тела, уборщик, сверка (~15 мин)
# уровень 5, трек 2
python3 $D --port 8080 reconcile-cycle # расхождения с обеих сторон: dry-run, --apply, повтор = 0 (~2 мин)
make reconcile # разовая сверка, dry-run; APPLY=1 — исправить
make stop && make bench_reconcile_quick # самопроверка профиля стоимости (~4 мин); полная метка — evidence/reconcile/baseline/
```
Полные метки уже лежат в `evidence/uploads/baseline/` и
`evidence/reconcile/baseline/` (разделы «Одновременные загрузки» и
«Стоимость сверки»), на защите показываются они: прогоны идут по
~50 мин.
### Остановка и удаление данных
- `make stop` — остановить контейнеры; S3 останавливается плавно, ~15 с.
- `make down` — удалить контейнеры; volumes `postgres_data` и `s3_data`
остаются, кэш Valkey теряется (он без volume, данные от этого не
страдают).
- `make wipe_data` — удалить контейнеры и volumes
`mtusi-lab4_postgres_data` и `mtusi-lab4_s3_data`, только после ввода
`yes`; оба тома запрос называет по имени. Следующий `make run_docker`
поднимает пустую базу со схемой и пустой приватный bucket.
### Старый `.env` и консоль (changes `s3-storage`, `upload-consistency`)
`make env_setup` создаёт новый `.env` из `.env.example` со случайными
паролями PostgreSQL и Valkey и шестью секретами S3 и печатает только их
@@ -50,17 +268,13 @@ S3_CLEANER_ACCESS_KEY S3_CLEANER_SECRET_KEY». Без них compose
`127.0.0.1:8080`. В консоли S3 доступен на `127.0.0.1:8334`. Уборщика
в консоли нет: зависшие загрузки консольного API убирает уборщик
стенда (та же база) или разовый `docker compose run --rm --no-deps
cleaner --once`.
- `make stop` останавливает S3 плавно, ~15 с. `make down` volumes не
трогает.
- `make wipe_data` удаляет volumes `mtusi-lab4_postgres_data` и
`mtusi-lab4_s3_data` только после ввода `yes`, оба тома запрос
называет по имени.
cleaner --once`. Порт 8080 занят HAProxy работающего стенда, поэтому
перед `make run_dev` — `make stop` (или `docker compose stop
haproxy`); свой набор против консоли — `make student_test
EXPECT_REPLICAS=1`.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```
клиент → 127.0.0.1:8080 → haproxy → api × 2 → postgres (метаданные, сессии, ключи идемпотентности)
→ valkey (кэш карточек чатов)
@@ -70,6 +284,89 @@ TODO: схема процессов/хранилищ, источник исти
cleaner (долгоживущий, без портов) ──→ postgres (строки pending), s3 (их объекты)
```
Источник истины — PostgreSQL: пользователи, чаты, сообщения, сессии,
ключи идемпотентности и метаданные вложений (строка `attachments` с
ключом объекта, размером, SHA-256 и статусом). S3 хранит только байты
оригинала по ключу, который назначает сервер. Valkey — общий кэш
неизменяемых карточек чатов, его отказ — обход в PostgreSQL. Реплики
`api` одинаковы и взаимозаменяемы, порта на хосте у них нет; в памяти
процесса нет ничего, от чего зависит ответ. Единственная точка входа —
HAProxy.
**Что перенесено из лабы 3** (репозиторий `mtusi2026lab3-safronov`,
ветка `solution/bvt2301-safronov`, commit `ce89eba`; здесь — commit
`5d5d8f9` «carry lab 3 over») без изменения поведения, кроме
перечисленного ниже:
- из лабы 2: PostgreSQL как источник истины, миграции alembic отдельным
сервисом `migrate`, регистрация с паролем (Argon2id в потоке), вход по
Basic только на `POST /auth/sessions`, остальное — Bearer-сессия в
таблице `sessions`, кэш карточки чата в Valkey, keyset-пагинация,
формат ошибок контракта;
- из лабы 3: HAProxy перед двумя репликами без портов на хосте,
`X-Instance-Id` в каждом ответе, обязательный `Idempotency-Key` с
ключом и сообщением в одной транзакции, замеренная цепочка таймаутов,
поочерёдная замена `make rolling_update`, ранний обработчик SIGTERM,
строгие курсор и UUID на входе;
- свои тесты (`make student_test`, `make test_isolated`, `make
failure_checks`) и стенд замеров `bench/` с профилями лаб 2 и 3.
Что изменилось при переходе 3 → 4:
- переход API — вложения (`contracts/README.md`, «Вложения (с lab4)»):
ручки загрузки, метаданных и скачивания, `attachment_ids` в сообщении
(по умолчанию `[]`, прежние текстовые POST валидны), пустой текст
только с вложением;
- миграции только расширяют схему: `ef25d50b01a8` (таблицы
`attachments` и `message_attachments`, ослабленное `NOT VALID`
ограничение текста), `739b8f04d5fb` (частичный индекс строк `pending`
`CONCURRENTLY`), `5c3e1f0a9b7d` (`attachments.lost_at`);
- новые сервисы стенда: `s3`, одноразовый `s3-bootstrap`, уборщик
`cleaner` на образе API; проект compose `mtusi-lab4`, образ
`mtusi-messenger:lab4` — чтобы не подключиться к данным лабы 3;
- хэш идемпотентности учитывает `attachment_ids` только непустым: ключ,
сохранённый версией лабы 3, повторяется без 409;
- `/health/ready` S3 не проверяет: отказ S3 — 503 только на путях
вложений;
- у HAProxy — свой `timeout server` 30 с пути загрузки и буферы
сокетов, у реплик — буфер приёма сокетов 512 KiB, `ROLLOUT_DRAIN_TIMEOUT`
90 с вместо 12 с.
**Транзакционные границы лабы 4.** У ручек вложений сессия БД — на шаг,
а не на запрос: соединение пула не держится на время передачи байтов.
Остальные ручки — одна сессия на запрос, как в лабе 3. Commit делает
сервис, изоляция `READ COMMITTED`:
| Операция | Шаги |
| --- | --- |
| загрузка | проверки 401 → 400 → 404 → 415 → 413 без тела → место загрузки (иначе 429) → тело со счётчиком и сроком → проверка изображения и SHA-256 → tx1: `INSERT attachments` (`pending`, ключ) → commit → PUT в S3 → tx2: `pending` → `ready` только у непомеченной строки → commit → 201. Сбой между PUT и отправкой COMMIT — DELETE объекта и 503; исход COMMIT неизвестен — объект остаётся уборщику |
| отправка сообщения | членство → вложения: все `ready` и этого чата (иначе 404) → захват ключа идемпотентности → `INSERT messages` → `INSERT message_attachments` одной вставкой → один commit |
| метаданные и скачивание | строка `ready` и членство в чате вложения (иначе 404); байты — GET из S3 потоком, сессия БД к этому времени закрыта |
| уборщик | на строку `pending` старше grace: tx пометки (`FOR UPDATE SKIP LOCKED`, `updated_at`) → commit; tx уборки: та же блокировка → DELETE объекта в S3 → DELETE строки → commit |
| сверка | чтения — короткие сеансы на страницу; каждое действие — после перепроверки в БД и HEAD; пометка и снятие пометки — условный `UPDATE` колонки `lost_at` |
Подробно — разделы «Вложения», «Согласованность БД и S3» и «Сверка
хранилищ» ниже.
### Соответствие переменных `.env.example`
`.env.example` skeleton предлагает «логические» имена и просит
сопоставить их с настоящими. Критерий — кто читает значение: то, что
читают compose и контейнеры зависимостей, живёт в `.env`, то, что читает
только приложение, — в секциях `config.toml` (согласование 2026-09-29).
Имена S3 и лимиты вложений — в таблице «Соответствие имён skeleton
`S3_*`» ниже.
| Имя skeleton | Где у нас | Почему так |
| --- | --- | --- |
| `APP_HOST` | режим `APP__RUN_MODE`: console — `127.0.0.1`, docker — `0.0.0.0` (литерал в `environment` compose и `ENV` в `Dockerfile`) | адрес следует из режима; в `.env` режим не хранится, чтобы консоль и docker работали из одного файла |
| `APP_PORT` | `APP__PORT` в `.env` (8080) — порт каждой реплики, на нём же healthcheck и проверки HAProxy; `APP_OUT_PORT` (8080) — порт на `127.0.0.1` хоста, его публикует только HAProxy | параметр приложения в формате настроек; внешний порт приложение не читает, поэтому без секции |
| `APP_ENV` | не используется | окружение одно — учебный стенд |
| `SESSION_TTL_SECONDS` | `[auth] session_ttl_seconds` в `config.toml`, по умолчанию 3600; разовая подмена — `AUTH__SESSION_TTL_SECONDS` | читает только приложение; мост из `.env` с этим именем окружение бы не перекрыло (`.claude/rules/settings.md`) |
| `DATABASE_URL_FILE` | не используется: URL собирает приложение из `[database]`, адрес и порт в docker — `POSTGRES_HOST` / `POSTGRES_PORT`, пароль — мостом из `POSTGRES_PASSWORD` в `.env` | пароль нужен ещё и контейнеру PostgreSQL, поэтому один источник — `.env` |
| `SESSION_STORE` | `postgres`: таблица `sessions`, общая для всех реплик, без кэша — отзыв мгновенный | другого хранилища сессий нет; Valkey без persistence стёр бы сессии рестартом |
| `CACHE_URL_FILE` | не используется: адрес и порт Valkey — `VALKEY_HOST`, `VALKEY_PORT` и `VALKEY_OUT_PORT` в `.env`, пароль — мостом из `VALKEY_PASSWORD` в `[cache] password`; срок, окно пропуска и пул — `[cache]` | как у PostgreSQL: пароль нужен и серверу Valkey |
| `IDEMPOTENCY_TTL_SECONDS` | `[idempotency] ttl_seconds` в `config.toml`, по умолчанию 86400 (24 ч); разовая подмена — `IDEMPOTENCY__TTL_SECONDS` | читает только приложение; срок меньше 86400 нарушает контракт и применяется только в проверках |
| `API_REPLICAS` | `API_REPLICAS` в `.env` (2), `deploy.replicas: ${API_REPLICAS:-2}` сервиса `api`; Makefile — `API_REPLICAS ?= 2` (`make replicas`, `EXPECT_REPLICAS` тестов) | приложение его не читает, поэтому имя без секции |
### Роль S3 и её граница
S3 хранит только байты вложений, метаданные лежат в PostgreSQL. Пишет и
@@ -82,9 +379,15 @@ S3 хранит только байты вложений, метаданные
загрузки, срок тела, одна копия тела и сроки LB пути загрузки (раздел
«Память и сроки загрузки»).
Сервер — SeaweedFS 4.48. Выбор и проба — `PLAN.md` (решение 1) и
design change `s3-storage`. Три места, где SeaweedFS по умолчанию не
приватен, закрыты:
Сервер — SeaweedFS 4.48 (выбор подтверждён автором 2026-10-20). MinIO
отвергнут: на 2026-10-20 его образы `minio/minio` и `minio/mc` из
чистого clone не скачивались («pull access denied», `quay.io/minio` —
401 без авторизации), а стенд должен подниматься из репозитория.
RustFS моложе, и его bootstrap требует `mc` или своего кода подписи
admin API; у SeaweedFS bucket и пользователи создаются `weed shell` из
того же закреплённого образа. Проба до выбора — design change
`s3-storage`. Три места, где SeaweedFS по умолчанию не приватен,
закрыты:
- без учётных записей S3 открыт анониму — административная пара задана
в окружении сервера с первого старта;
- master, filer и volume слушают все интерфейсы — `-ip.bind=127.0.0.1`;
@@ -469,7 +772,7 @@ rate_limited` с `Retry-After: 1`, срок вышел — 429 по сроку;
(у него одного `Retry-After`), 503 — «зависимость недоступна», и клиент
не отличил бы занятые места от отказа S3. Места ограничивают
одновременность, а не частоту, поэтому трактовка — открытый вопрос
преподавателю (`PLAN.md`, `### upload-memory`, «Вопросы», п. 1).
преподавателю (раздел «Открытые вопросы преподавателю», п. 1).
**Срок тела** — `[uploads] body_timeout_seconds` (30 с) на всё тело с
момента, как загрузка заняла место (`asyncio.timeout` вокруг чтения);
@@ -647,8 +950,8 @@ dry-run. Плановая — в сервисе `cleaner` при старте и
— 201; после снятия пометки — снова 200 с байтами. Статус `lost` /
`failed` отвергнут: контракт лабы 4 знает только `ready`, и прежние
реплики упали бы на неизвестном значении при `make rolling_update`.
**Это вопрос преподавателю** (`PLAN.md`, `### track2-reconciler`,
«Вопросы», п. 1): в контракте рядом «Отсутствующий вариант ready-объекта
**Это вопрос преподавателю** (раздел «Открытые вопросы преподавателю»,
п. 2): в контракте рядом «Отсутствующий вариант ready-объекта
— 404», «404 — объекта нет» и «Неожиданное исключение — 500». Сделан
вариант по умолчанию; ответ «иначе» меняет одну ветку `open_content`,
сценарий и тесты, но не сверку.
@@ -774,6 +1077,45 @@ reconcile`) получил три аргумента; плановая свер
| 2026-09-29 | Конфиг через pydantic-settings: окружение → `.env` → `config.toml` → дефолты, `config.toml` монтируется read-only, не в образе | `.claude/rules/settings.md`, `docker.md` |
| 2026-10-20 | «Пустой текст» сообщения — и `""`, и из одних пробелов: с хотя бы одним вложением — 201 (текст как прислан), без вложений — 400 | спек `messages`, «Пробелы с вложением»; `CreateMessage`; `test_blank_text_with_attachment` |
### Открытые вопросы преподавателю
Контракт допускает две трактовки, ответа пока нет. Сделан вариант по
умолчанию, ниже — что поменяет другой ответ. Подход и остальной код от
ответа не зависят.
1. **Все места загрузки реплики заняты: 429 `rate_limited` или 503
`unavailable`?** `contracts/openapi.json` у `uploadAttachment`
допускает оба: 429 — «Ограничение частоты запросов», и только у него
есть `Retry-After`; 503 — «Зависимость недоступна».
`contracts/README.md` называет 429 факультативным ограничением
запросов, а места ограничивают одновременность, а не частоту.
- Сделано: 429 с `Retry-After: 1`. Из двух описаний к ограничению
подходит только 429. 503 клиент не отличил бы от отказа S3.
- Ответ «503» меняет `DOMAIN_ERRORS` и `RETRY_AFTER` в
`src/api/errors.py`, проверку `Retry-After` в
`student-tests/contract.py`, ожидания `test_upload_slots_busy` и
`test_rejections_before_queue`, сценарии спеков `attachments` и
`api-conventions` и правило `api-contract.md`.
2. **Что отвечает API на вложение, чей оригинал по сверке потерян**
(объекта нет, он другого размера или с другим SHA-256)? У
`Attachment.status` в лабе 4 одно значение — `ready`: `failed` и 409
появляются с лабы 5. `contracts/README.md` пишет: «Отсутствующий
вариант ready-объекта — 404», «404 — объекта нет», «Неожиданное
исключение — 500».
- Сделано, вариант (а): метаданные — 200 как раньше, байты — 404
`not_found`, как у отсутствующего варианта, ссылка в новом
сообщении — 201. До пометки сверкой байты — 500: расхождение
непредвиденное.
- Другие варианты: (б) вложение целиком как незавершённое —
метаданные, байты и ссылка дают 404; (в) байты — 500 и после
пометки, пометка только для отчёта. Каждый меняет ветку `lost_at` в
`AttachmentService.open_content`, для (б) — ещё `get_attachment` и
выборку вложений сообщения. Меняются и сценарий `attachments`
«Потерянный оригинал», и ожидания `test_reconcile_finds_and_fixes`,
`test_reconcile_keeps_fresh_used_and_unknown`,
`test_reconcile_restored_original` и `driver.py reconcile-cycle`.
Классы, правила безопасности и схема сверки остаются прежними.
### Ответы на вопросы защиты
- **Почему файл в Docker volume одной API-реплики не равен объектному
@@ -870,8 +1212,8 @@ student_test` через LB (197 passed, сверка 215 / 200 / 36 / 15) и
«узкого» API стенда отказов 3 с вместо 2 с, код приложения прежний)
переснято `make failure_checks` (37 / 37). Строки сверки хранилищ (change
`track2-reconciler`, трек 2) — с `c1648d9` на рабочем стенде после
порядка обновления change (`evidence/reconcile/`, `evidence/s3/cleaner-
list.md`, `evidence/migrations/lost-at.md`); с того же commit снят `make
порядка обновления change (`evidence/reconcile/`,
`evidence/s3/cleaner-list.md`, `evidence/migrations/lost-at.md`); с того же commit снят `make
test_isolated` (`evidence/tests/`). После правок по verify (`84f8c35`:
сверка и тесты отказов, код API прежний) переснято `make failure_checks`
(48 / 48) и `make student_test` через LB. После change
@@ -886,14 +1228,17 @@ student_test` через LB после замены реплик. После п
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` (через LB и в `make test_isolated`) | `PASS: lab4 public API scenario` — загрузка fixture, сообщение с `attachment_ids`, SHA-256 скачанного оригинала, 404 постороннему | `evidence/attachments/smoke.md`, `evidence/tests/test-isolated-s3-cleanup.md` (раздел 0) |
| Публичный smoke | `make test` (через LB и в `make test_isolated`), в том числе из чистого clone на `de98d77` | `PASS: lab4 public API scenario` — загрузка fixture, сообщение с `attachment_ids`, SHA-256 скачанного оригинала, 404 постороннему | `evidence/attachments/smoke.md`, `evidence/tests/clean-clone-final.md`, `evidence/tests/test-isolated-s3-cleanup.md` (раздел 0) |
| Стенд собирается и проходит проверки из чистого clone | `git clone` во временный каталог, последовательность раздела «Запуск из чистого clone» (`de98d77`, 2026-10-29) | все шаги — код 0: `make check`, `make validate`, `make test`, `make instances` (2 реплики), `make s3_check` (70), `make test-persistence`, `make test-failover` × 2, `attachment-failover`, `attachment-storage`, `make student_test` (198), `make reconcile` (`found {}`), `make test_isolated` (193 + 5), `make failure_checks` (56, `crash markers 0`); секретов `.env` в журнале — 0 | `evidence/tests/clean-clone-final.md` |
| CI: сборка, стенд и `make test` в отдельном job (`CONTRIBUTING.md`, «CI») | `.github/workflows/application.yml` на раннере Gitea; шаги workflow в контейнере образа раннера с сокетом Docker, файлы скопированы внутрь | стенд с конфигами из `configs` и без портов хоста, обе реплики в LB; `make check`, `make test` — `PASS`; аноним в S3 — 403; `make student_test` — 198 passed (тесты реплик выполнены); `make test-persistence`, `make test-failover` `stop` и `kill` — `PASS`, `failed_attempts` 0; после уборки ни контейнеров, ни volumes, ни образа прогона | `evidence/tests/ci-application.md` |
| «3»: метаданные в PostgreSQL, байты в приватном bucket, не в БД и не на диске API | `driver.py --port 8080 attachment-storage` | из `bytea` только `sha256` (32 байта), `object_key` = `messenger/attachments/<id>/original` без `filename`, объект в bucket 111 817 байт, анонимный GET ключа — 403, `docker diff` реплик — только `config.toml`; открыли bucket анониму — код 1 «anonymous GET … got 200», bootstrap закрыл — код 0 | `evidence/attachments/storage.md` |
| «3»: POST вложения → 201 `ready` после сохранения; оригинал побайтно; `attachment_ids` читают участники; посторонний — 404 | `make test`; `driver.py upload` Алисой, `download` Бобом и Евой | 201 `status=ready`, `variants=[]`, `sha256` 99ea7533…; Боб — 200 `image/png`, 111 817 байт, тот же SHA-256 (отдала другая реплика); Ева — 404 на метаданные и байты | `evidence/attachments/smoke.md` |
| «3»: реальные PNG/JPEG ≤10 MiB и ≤40 млн пикселей, MIME по содержимому, опасные `filename`, лимиты до чтения и распаковки | `make student_test` через LB (`test_attachments.py`, 33 теста) | 10 485 760 байт — 201, +1 — 413; 30 MiB с `Content-Length` и частями — 413; 8000 × 5000 — 201, 40 000 001+ — 413; «бомба» — 415 (распаковано не больше ожидаемого объёма + 1 байт); текст, GIF, пустое тело, подмена MIME — 415; `filename` с `/`, `\`, NUL, `\n`, DEL, U+0085, пустой, 256 — 400; `a%FFb.png`, `a%C3.png`, `a%ED%A0%80b.png` — 400; U+202E, U+2066, U+2028 — 201 как есть | `evidence/tests/student-test-lb.md` |
| «3»: остановка загрузившей реплики → download через другую | `driver.py --port 8080 attachment-failover --mode stop` и `--mode kill` | загрузку принял `5f5d4ac50d9a`, `stop-one.sh` его остановил (`stop` и `kill`), метаданные и байты — 200 от `847ad74efd7c`, SHA-256 совпал, посторонний — 404; после `make replicas` обе `UP` | `evidence/attachments/failover.md` |
| «3»: restart с volumes сохраняет метаданные и оригинал | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` (`LAB=4`) | PASS: прежний токен читает данные, оригинал вложения тот же; `StartedAt` новый у всех шести контейнеров (API, LB, PostgreSQL, Valkey, S3) | `evidence/replicas/test-persistence.md` |
| «3»: failover с записью | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` (каждая реплика, `stop` и `kill`, `STOP_ONE_LOG`) | 4 × PASS, `failed_attempts` 0, восстановление 0,76–1,2 с; `STOP_ONE_LOG` — оба контейнера | `evidence/failover/test-failover.md` |
| «4»: тесты большого файла, повреждённого изображения, подмены MIME, чужого `attachment_id`, вложения другого чата; ошибка клиента не 500 | `make student_test` через LB (`test_rubric.py`: пять сценариев лабы 4), `make test_isolated` | 198 passed через LB (`b5983f0`, восемь прогонов подряд после замены реплик — без падений, «Object storage is unavailable» в журнале реплик 0 при 536 загрузках), 193 passed + 5 пропусков тестов реплик в одном процессе (`723b6c3`); каждая ошибка — 4xx в формате контракта; сверка покрытия: 244 сценария 13 спеков, 227 тестами (62 — проверками отказов), 17 исключений | `evidence/tests/student-test-lb.md`, `evidence/tests/test-isolated-s3-cleanup.md` (раздел 0, пересъёмка на `723b6c3`) |
| «3»: failover с записью | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` (каждая реплика, `stop` и `kill`, `STOP_ONE_LOG`) | 4 × PASS, `failed_attempts` 0, восстановление 0,76–1,2 с; `STOP_ONE_LOG` — оба контейнера; из чистого clone — ещё 2 × PASS (`stop`, обе реплики по очереди, 1,08 и 1,2 с) | `evidence/failover/test-failover.md`, `evidence/tests/clean-clone-final.md` |
| «3»: обязательные возможности лаб 2 и 3 сохранены | `make student_test` через LB (`test_identification.py`, `test_idempotency.py`, `test_load_balancing.py`, `test_race.py`, `test_chat_cache.py`), `make instances`, `driver.py auth-storage`, повтор отправки после `--force-recreate api` | Basic только на вход, Bearer на остальном, `X-User-Id` игнорируется; `X-Instance-Id` в каждом ответе, одна сессия на обеих репликах (`instances: 2`, 6 / 6); повтор с тем же `Idempotency-Key` через другую реплику и после пересоздания реплик — тот же `Message`, гонка 10 клиентов с одним ключом — одно сообщение; Argon2id в `users`, SHA-256 токена в `sessions`; кэш карточки — одно чтение `chats` на 50 | `evidence/tests/student-test-lb.md`, `evidence/tests/clean-clone-final.md`, `evidence/auth/passwords-and-tokens.md`, `evidence/idempotency/replay-after-restart.md`, `evidence/cache/hits.md` |
| «4»: тесты большого файла, повреждённого изображения, подмены MIME, чужого `attachment_id`, вложения другого чата; ошибка клиента не 500 | `make student_test` через LB (`test_rubric.py`: пять сценариев лабы 4), `make test_isolated` | 198 passed через LB (`b5983f0`, восемь прогонов подряд после замены реплик — без падений, «Object storage is unavailable» в журнале реплик 0 при 536 загрузках), 193 passed + 5 пропусков тестов реплик в одном процессе (`723b6c3`); каждая ошибка — 4xx в формате контракта; из чистого clone на `de98d77` — 198 passed через LB и 193 + 5 в `make test_isolated`, сверка покрытия: 252 сценария 13 спеков, 235 тестами (70 — проверками отказов), 17 исключений | `evidence/tests/student-test-lb.md`, `evidence/tests/test-isolated-s3-cleanup.md` (раздел 0, пересъёмка на `723b6c3`), `evidence/tests/clean-clone-final.md` |
| «4»: отказы S3 на путях вложений, отклонённая загрузка ничего не оставляет | `make failure_checks` | 49 / 49, код 0 (`723b6c3`, 552 с): S3 остановлен — загрузка 503, ровно одна новая строка `pending`, готовые те же, текст 201; скачивание 503, метаданные 200, история с `attachment_ids` 200, `/health/ready` 200; S3 заморожен — 503 не позже 5,6 с; отклонённые загрузки — ни новых строк, ни новых объектов (списки `id`); рабочий стенд не тронут | `evidence/tests/failure-checks.md` |
| «4»: прерывание загрузки и отказ между S3 и БД не оставляют вечных неучтённых объектов | `make failure_checks` (стенд отказов: уборщик с grace 20 с, интервал 1 с) | сбой записи строки (SQLSTATE 08006) — 503, ни строки, ни объекта; обрыв клиента посреди тела — ни строки, ни объекта; сбой фиксации `ready` — 503, объекта нет сразу (компенсация), строка `pending` не видна по API, на G/2 ещё на месте, после G + I + 5 с убрана; S3 заморожен на время PUT — строка убрана после grace, объект не появился; kill реплики между PUT и фиксацией — 201 не дошёл, строка и объект есть до grace, после — ни того, ни другого; COMMIT `ready` упал (отложенный триггер) — 503, объект на месте (исход неизвестен), после grace убран; загрузка дольше grace (строка «старше» на час, уборщик убрал её, пока перевод в `ready` ждал) — 503, а не 201 и не 500, ни строки, ни объекта; уборщик удалил объект, а удаление строки упало в той же транзакции уборки — 503, а не 201, `ready` без объекта нет, следующий проход доводит уборку; во всех — объектов без строки 0 (`object-ids − attachment-ids`); красный прогон до кода — 4 из 11 упали; тесты по verify: W1 — 201 на коде `f2dc0b3`, W2 и W3 — красные на временных регрессиях (компенсация на любой сбой, `RuntimeError` → 500) | `evidence/tests/failure-checks.md` |
| «4»: то же на рабочем стенде через LB | `driver.py --port 8080 upload-consistency` | S3 заморожен — 503 за 5,1 с, строка `pending` с ключом; сбой фиксации `ready` — 503, объекта нет; обе строки — 404 на метаданные, байты и ссылку; `cleaner --once` (grace 30 с) — `removed 2`, код 0; строк и объектов нет, «1200 objects, 1200 rows, 0 objects without a row»; готовое вложение — тот же SHA-256; в журнале API шаги `put` / `ready` и «Deleted attachment object», `filename` — 0 вхождений | `evidence/attachments/consistency.md` |
@@ -929,11 +1274,33 @@ student_test` через LB после замены реплик. После п
| «5», трек 2: влияние сверки на фоновую нагрузку | та же метка, этап D: 300 скачиваний + 50 записей + 50 чтений в секунду, 4 варианта CPU уборщика и предела | H4 **не проверена**: все r ≤ 1,08, a 0,96–1,06, 5xx нет, но контраст `fast-unlimited` (1 CPU, без предела) дал r скачиваний 1,08 при пороге > 1,5 — метод влияния не показал; предел 2000 держит CPU S3 за проход 0,27–0,32 ядра при любом CPU уборщика (без него — 0,42–0,73) ценой прохода в 2,2–4 раза дольше | `evidence/reconcile/baseline/summary.md`, `passes.csv`, `windows.csv` |
| «5», трек 2: `head`, глубокая, возврат по SHA-256, предел скорости, ранний отказ | `make failure_checks` (5 проверок и 2 по замечаниям verify, `ca0c4b2`); красные прогоны на `7f4e626` и `16f2cde`; `driver.py reconcile-signal --pace [--apply]` (временный проект) | 56 из 56 за 877 с; на `7f4e626` — 5 из 5 упали по ожидаемым причинам (argparse, нет поля `deep`, пометку снял объект того же размера, `changes` 7 вместо 3); на `16f2cde` — 2 из 2 (`batch` не сравнил строку с чужим `<Z>/original`, помечен только что перезаписанный объект); `docker stop` во время паузы предела 1 объект/с — код 1, `interrupted_by: stop`, выход через 0,06 с, ключи страницы в итоге, а с `--apply` каждое удалённое — «Fixed» (4 из 4; на `16f2cde` — 3 из 4) | `evidence/tests/failure-checks.md`, `evidence/reconcile/service.md` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
Какие процессы и хранилища перезапускает restart hook, подтверждено
отдельно, а не только `PASS` теста: `StartedAt` у LB, обеих реплик,
PostgreSQL, Valkey и S3 новый, ID контейнеров прежние
(`evidence/replicas/test-persistence.md`, `evidence/s3/restart.md`); в
проверке из чистого clone — время работы этих контейнеров после hook
меньше его длительности, а у уборщика, которого hook не трогает, —
прежнее (`evidence/tests/clean-clone-final.md`).
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Два замера с гипотезами, записанными и закоммиченными до прогонов. У
каждого в своём разделе ниже — хост и лимиты контейнеров, версии,
объём данных, профиль и интенсивность нагрузки, окна и прогрев,
повторы, коды ответов, p50 / p95 / p99, CPU и память, выводы и
ограничения. Сырые итоги без токенов лежат в каталогах меток:
- **память при одновременных загрузках** (уровень «4»: «≥ 10
одновременных загрузок с измерением пика памяти») — `make
bench_uploads`, метка `evidence/uploads/baseline/`, разделы
«Одновременные загрузки: гипотезы» и «… результаты»;
- **стоимость сверки bucket и БД** (уровень «5», трек 2: «измерьте
стоимость обхода») — `make bench_reconcile`, метка
`evidence/reconcile/baseline/`, разделы «Стоимость сверки: гипотезы» и
«… результаты».
Таблица ниже — отказы и пробы: внесённое воздействие, ожидание,
наблюдение и потери. Команды и полные выводы — в файлах таблицы
«Доказательства критериев».
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
@@ -1419,7 +1786,63 @@ CPU S3 в ней нет). Естественная скорость `batch` на
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
**Какие отказы стенд выдерживает** (подтверждено проверками, таблица
«Доказательства критериев»):
- остановка, `kill` и заморозка одной реплики API: LB уводит запросы,
запись восстанавливается за 0,76–1,2 с без дублей, вложение отдаёт
другая реплика с тем же SHA-256;
- отказ S3 (остановлен, заморожен, нет bucket, отказ в доступе): 503
только на загрузке и скачивании байтов, а текст, история, метаданные
и `/health/ready` работают;
- отказ PostgreSQL или процесса API посреди загрузки, обрыв клиента,
медленный клиент: ответ 503 или 4xx, а не 201 и не 500; неучтённых
объектов старше grace + интервал не остаётся (компенсация, уборщик,
сверка);
- отказ Valkey: обход кэша;
- рестарт всего стенда с volumes: данные, прежние сессии и оригиналы
вложений целы.
**Чего стенд не выдерживает:** отказ хоста или ВМ Docker, единственного
HAProxy и единственного PostgreSQL (без него API отвечает 503, LB
выводит реплики), потерю диска S3 (одна нода без репликации). Один
Docker-host — не отказоустойчивость к потере этого host (`COURSE.md`).
**Что не реализовано:**
- трек 1 «Прямой upload» — выбран один трек 5, трек 2;
- в CI нет `make s3_check`, `make test_isolated`, `make failure_checks`
и замеров `bench/`: им нужны порты хоста, отдельные проекты и десятки
минут (раздел «CI» в «Запуск из чистого clone»). Их выводы — в
`evidence/`;
- Swarm: стенд — один проект Compose;
- полное декодирование изображения, превью и асинхронная обработка —
лаба 5; лимит одновременных скачиваний — вне лабы.
**Учебные упрощения:** один хост, генератор нагрузки на нём же; одна
нода S3 без fsync; секреты в `.env` и видны в `docker inspect`; HTTP без
TLS (лаба 7).
**Подтверждено и гипотеза.** Замер загрузок: H1–H4 подтверждены —
с местами загрузки пик реплики при 40 × 10 MiB — 181,3 MiB (медиана),
а без них реплику убивает OOM. Замер сверки: H1, H2, H3 и S4 подтверждены, H4
**не проверена** — контраст без предела не насытил S3, поэтому предел
скорости 2000 — страховка доли CPU шлюза, а не доказанная защита задержек
фона.
**Известные дефекты** (`KNOWN_ISSUES.md`, четыре открытые записи, ни
одна не затрагивает стенды проекта в штатной работе):
- повторный bootstrap после удаления bucket на маленьком tmpfs падает на
«api key wait (code 500)» — не хватает слотов томов SeaweedFS;
- уборщик удаляет объект зависшей загрузки по ключу вне своего префикса
(бывает только в базе, восстановленной под другим именем);
- LB отвечает 408 на медленные заголовки страницей HAProxy, а не в
формате контракта;
- поля `float` настроек принимают `inf`.
**Следующие шаги:** ответы на открытые вопросы преподавателю; новая
метка сверки с контрастом, который насыщает S3 (S3 0,5 CPU или фон в
2–3 раза больше), — проверка H4; исправление записей `KNOWN_ISSUES.md`;
лаба 5 — 202, worker и staging-prefix, где сверке прибавятся варианты
под префиксом вложения.
S3 (change `s3-storage`):
- **Одна нода S3 без репликации и fsync.** SIGKILL процесса
@@ -1549,8 +1972,8 @@ S3 (change `s3-storage`):
получить 429 при полной очереди; затем она берёт место, сразу
заканчивается `interrupted` и отпускает его (проба verify). Места
загрузки она не держит дольше обычной.
- **429 или 503 — вопрос преподавателю открыт** (`PLAN.md`, «Вопросы»,
п. 1). Ответ «503» поменяет строку таблицы ошибок, сценарии спеков и
- **429 или 503 — вопрос преподавателю открыт** (раздел «Открытые
вопросы преподавателю», п. 1). Ответ «503» поменяет строку таблицы ошибок, сценарии спеков и
ожидания тестов, но не подход.
- **Тело отклонённой загрузки реплика дочитывает и выбрасывает**
(uvicorn держит соединение): памяти это не стоит (буферы ограничены),
@@ -1628,7 +2051,7 @@ S3 (change `s3-storage`):
(одни часы), точность `LastModified` — секунда; `updated_at` строк
консольного API на macOS расходится на секунды — меньше grace.
- **Ответ API на потерянный оригинал — трактовка контракта**, вопрос
преподавателю открыт (раздел «Сверка хранилищ»).
преподавателю открыт (раздел «Открытые вопросы преподавателю», п. 2).
- **Старый образ уборщика после `make rolling_update`** — сверки нет, как
до change; новый — `docker compose up -d --no-deps cleaner` (порядок
обновления).
@@ -1664,3 +2087,133 @@ S3 (change `s3-storage`):
dry-run, он перепроверяет всех.
- **`make failure_checks` — ещё ~4 мин** (56 проверок, ~15 мин): семь
проверок сверки change ждут grace стенда.
## Источники, библиотеки и использование ИИ
**Документация и спецификации**, по которым приняты решения. Ссылки —
на корень документации, нужный раздел назван словами. Поведение
стенда при этом проверено пробами и тестами, их выводы — в
`evidence/`:
- Amazon S3 — <https://docs.aws.amazon.com/AmazonS3/latest/userguide/>
(из `README.md` задания): загрузка объектов, presigned URL (почему не
трек 1), политики bucket с условием `s3:prefix`; API Reference —
`ListObjectsV2`, `HeadObject`, `DeleteObject`.
- SeaweedFS 4.48 — <https://github.com/seaweedfs/seaweedfs> (wiki и
исходники): шлюз S3, учётные записи и политики IAM, `weed shell`
(`s3.bucket.create`, `s3.anonymous.set`, `fs.ls`, `fs.rm`), ключ
подписи `WEED_JWT_FILER_SIGNING_KEY`, `-ip.bind`, метрики шлюза.
- aiobotocore — <https://aiobotocore.aio-libs.org/>, botocore `Config`
(`connect_timeout`, `read_timeout`, `retries`, `max_pool_connections`);
исходники aiohttp 3.14.5 — `resume_reading()` и таймер `sock_read`
(причина flake, `evidence/s3/idle-connection.md`).
- PNG — <https://www.w3.org/TR/png/> (чанки, CRC, IHDR, фильтры строк,
Adam7), zlib — RFC 1950 / 1951 и `zlib.decompressobj(max_length)`
Python; JPEG — ITU-T T.81 (маркеры, SOF, длины сегментов).
- PostgreSQL 18 — <https://www.postgresql.org/docs/18/>: частичные
индексы, `CREATE INDEX CONCURRENTLY`, `SELECT … FOR UPDATE SKIP
LOCKED`, `ALTER TABLE … ADD COLUMN` под `lock_timeout`, `NOT VALID`
ограничения, `pg_stat_database`.
- HAProxy 3.4 — <https://docs.haproxy.org/>: `http-request
set-timeout`, `tune.sndbuf.server`, `tune.rcvbuf.client`,
`http-error`, `timeout http-request`.
- Linux — [cgroup v2](https://docs.kernel.org/admin-guide/cgroup-v2.html)
(`memory.peak`, `memory.stat` `anon` / `sock`, `memory.events`
`oom_kill`), [ip-sysctl](https://docs.kernel.org/networking/ip-sysctl.html)
(`tcp_rmem`); glibc
[mallopt](https://man7.org/linux/man-pages/man3/mallopt.3.html)
(`M_MMAP_THRESHOLD`, переменная `MALLOC_MMAP_THRESHOLD_`).
- Starlette — `Request.stream()`; k6 —
<https://grafana.com/docs/k6/latest/> (`constant-vus`,
`constant-arrival-rate`).
- Из лаб 2 и 3 — FastAPI, uvicorn, SQLAlchemy, asyncpg, alembic,
argon2-cffi, redis-py, Valkey, Docker Compose (источники перечислены в
отчётах этих лаб).
**Библиотеки и образы:** FastAPI, pydantic, pydantic-settings,
structlog, SQLAlchemy, asyncpg, alembic, argon2-cffi, redis-py,
aiobotocore, uvicorn (версии — раздел «Запуск из чистого clone»); тесты
— pytest, httpx, Pillow; стенд — HAProxy, PostgreSQL, Valkey,
SeaweedFS, k6 в закреплённых образах. Проверка изображения — свой код на
stdlib (`src/utils/image.py`), без библиотек декодирования. Сторонний
код в репозиторий не копировался.
**Использование ИИ.** Инструмент — Claude Code, модель Claude Opus 5.5.
Работа велась по changes OpenSpec (`openspec/changes/archive/`, семь
changes лабы 4: `s3-storage`, `attachments`, `upload-consistency`,
`upload-memory`, `track2-reconciler`, `fix-upload-put-flake`,
`track2-reconcile-cost`). Все семь в архиве, спеки синхронизированы,
активных changes нет. Каждый change проходил этапы propose → apply →
verify → правки по verify → archive. Каждый этап выполнял отдельный
субагент, основная сессия координировала: передавала этапы, проверяла
итоги, коммитила на ветке `feat/<change>` и вливала её в основную,
присылала автору прогресс. Все commit после переноса лабы 3
(`5d5d8f9`) помечены `Co-Authored-By: Claude Opus 5.5`. Рабочий план
лабы (`PLAN.md`: рубрика → changes, ключевые решения, трек 5, риски,
вопросы по ходу changes) удалён после закрытия всех changes. Его итоги
перенесены в этот отчёт и в design архивных changes, открытые вопросы —
в раздел «Открытые вопросы преподавателю». Последняя версия плана —
`git show fd03b84:PLAN.md`, на неё ссылаются архивные changes и ранние
файлы `evidence/`.
Что делал ИИ:
- код приложения и уборщика, миграции, `docker-compose.yml`,
`haproxy.cfg`, `infra/s3/bootstrap.sh`, скрипты стенда;
- собственные тесты `student-tests/`, стенд проверок отказов и его hook;
- профили `uploads` и `reconcile` стенда замеров `bench/`, сэмплер
памяти, сводки и графики;
- драйвер проверок (`driver.py s3-check`, `attachment-failover`,
`upload-consistency`, `reconcile-cycle` и другие), запуск замеров и
проверок, evidence, этот отчёт, правила `.claude/rules/` и спеки
OpenSpec;
- CI job `application` и override стенда для раннера Gitea; схему
раннера (job — контейнер рядом со стендом) ИИ установил по журналу
публичного прогона на этом Gitea и повторил локально.
Что решал автор:
- трек 2 «Согласованность двух хранилищ» и SeaweedFS вместо MinIO
(2026-10-20); `/health/ready` без S3 и уборщик — отдельный сервис, а
не фоновая задача реплик (2026-10-20);
- проверка изображения структурная, без полного декодирования;
`filename` отклоняется только по правилу контракта (`/`, `\`, NUL и
категория Cc), символы направления текста принимаются (2026-10-20);
- текст из пробелов с вложением — вопрос преподавателю (ответ —
«Согласования с преподавателем», 2026-10-20);
- метку `uploads` принять с предупреждением о swap хоста (2026-10-22)
и после `fix-upload-put-flake` полную метку не переснимать
(2026-10-23);
- добавить CI job по `CONTRIBUTING.md`, «CI», и включить Actions в fork
(2026-10-29);
- все замечания каждого verify — в правки, без отдельного согласования;
работа в автономном режиме. Решения, принятые основной сессией без
автора, отмечены в design changes как принятые без пользователя
(например, дописывание недостающих переменных в существующий `.env`,
2026-10-21; варианты по умолчанию в открытых вопросах преподавателю).
Как проверялось:
- verify каждого change отдельным субагентом: сверка с задачами,
спеками и рубрикой. Найденное правилось, и evidence переснималось с
закоммиченного кода. Примеры — гонка уборщика с `mark_ready`, которая
давала `ready` без объекта (два раунда verify `upload-consistency`),
строка с ключом вне префикса в сверке, неполные вердикты сводки метки
сверки;
- публичные проверки skeleton (`make test`, `make test-persistence`,
`make test-failover`) и собственные (`make student_test`, `make
failure_checks`, `make test_isolated`, `make s3_check`) — на итоговом
коде каждого change и из чистого clone
(`evidence/tests/clean-clone-final.md`); у новых проверок отказов —
красный прогон до кода;
- гипотезы обоих замеров закоммичены до прогонов, хост проверялся перед
каждой меткой. Первая метка `uploads` (грязное дерево, swap хоста
337 056 страниц) отброшена; принятая снята на чистом дереве, с
пометкой о swap 7 464 страниц в одном прогоне (решение автора выше);
- ошибки ИИ, найденные по ходу, описаны в отчёте как есть:
- оценка «~1,2 тела на загрузку» до change `upload-memory` была
неверна: на деле ~2,17 тела и OOM при 20 × 10 MiB;
- первая метка `uploads` снята на грязном дереве со swap хоста;
- две попытки метки сверки упали на собственной проверке полноты
строк k6;
- срок чтения aiohttp давал редкие 503 на исправном S3
(`fix-upload-put-flake`).
Утверждения отчёта о поведении стенда подтверждены командами, их выводы
лежат в `evidence/`. Решения, перечисленные выше, принимал автор.
+178
View File
@@ -0,0 +1,178 @@
# CI job `application`: сборка, стенд и проверки в раннере Gitea
Свой job по `CONTRIBUTING.md`, «CI»: `.github/workflows/application.yml`
(workflow skeleton `contracts.yml` не менялся), override стенда
`.github/ci/compose.yml` и окружение шагов `.github/ci/stand-env.sh`.
Устройство — `REPORT.md`, раздел «CI» в «Запуск из чистого clone».
## Раннер
Раннеры Gitea fork — `runner-1` и `runner-2`, `act_runner` v0.2.13,
метки `ubuntu-latest`, `ubuntu-22.04`, `ubuntu-24.04` (настройки fork →
Actions → Раннеры, 2026-10-29). По журналу публичного прогона на этом же
Gitea: job — контейнер образа `gitea/runner-images:ubuntu-latest`
(linux/amd64) в своей сети, сокет Docker хоста раннера ему доступен,
стенд compose поднимается соседними контейнерами. Отсюда два ограничения,
которые снимает override:
- bind mount файла рабочего каталога (`./config.toml`,
`./infra/haproxy/haproxy.cfg` и др.) Docker ищет на хосте раннера, а
файлы есть только в контейнере job: `bind source path does not exist`;
- порт стенда на `127.0.0.1` хоста раннера из контейнера job не виден и
на общем хосте может быть занят.
Инструменты образа раннера (`docker run --rm
gitea/runner-images:ubuntu-latest …`, index
`sha256:2992a8a0448aba1c093255787390b2a090fefbfd76cc25db107f527e9bd65d3a`):
```text
PRETTY_NAME="Ubuntu 24.04.5 LTS"
Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1
Python 3.12.3
GNU Make 4.3
curl 8.5.0
OpenSSL 3.0.13 30 Jan 2024
git version 2.56.0
```
## Почему конфиги копируются с переводом строки в конце
`$(cat файл)` срезает последний перевод строки; `stand-env.sh` его
возвращает. Без него HAProxy закреплённого образа конфиг не принимает:
```text
$ haproxy -c -f /c.cfg # infra/haproxy/haproxy.cfg без последнего \n
[ALERT] (1) : config : parsing [/c.cfg:163]: Missing LF on last line, file might have been truncated at position 23.
[ALERT] (1) : config : Error(s) found in configuration file : /c.cfg
[ALERT] (1) : config : Fatal errors found in configuration.
```
С исходным файлом та же команда проходит без вывода.
## Локальный прогон шагов workflow в схеме раннера
2026-10-29, 18:06–18:09 MSK. Хост: Docker Desktop 29.9.2 (ВМ
linux/arm64, 12 CPU, 7,7 GiB), macOS, Apple M3 Pro. Код — рабочее
дерево поверх `de98d77`: файлы будущего commit с job (`git ls-files -co
--exclude-standard`; `.env` и `config.toml` в них не входят).
Схема та же, что у раннера: контейнер `gitea/runner-images:ubuntu-latest`
в своей сети, сокет Docker хоста смонтирован, файлы репозитория
скопированы внутрь архивом (не смонтированы). Шаги — блоки `run`
`application.yml` как есть, `bash --noprofile --norc -e -o pipefail`, в
порядке файла, с `if: failure()` и `if: always()`. `${{ github.run_id
}}` — `sim1`. Шаг Checkout пропущен: файлы уже скопированы, а commit на
Gitea ещё не опубликован. Сам checkout проверен отдельно в том же образе
на `main` fork: `git fetch --depth=1 origin
ec540a1a725862a8619fcb758daec4ad197f0dd5` по https без токена, `git
checkout --detach FETCH_HEAD`, исполняемые биты `scripts/*.sh`
сохранились.
| Шаг | Код | с | Итог |
|---|---|---|---|
| Runner | 0 | 0 | `docker 29.9.2, linux/aarch64, 12 CPU`, Compose v5.6.1, Python 3.12.3 |
| Remove stands of interrupted runs | 0 | 0 | хвостов нет |
| Build and start the stand | 0 | 14 | `new .env with random …` (только имена); образ `mtusi-messenger:safronov-ci-sim1`; проект `mtusi-lab4-safronov-ci-sim1`; `LB ready: 0d9ec34300c1 dd41a7e8f7f9` |
| make check and make test | 0 | 1 | оба `PASS` |
| Bucket is closed to anonymous requests | 0 | 0 | три анонимных GET — 403 |
| Install uv | 0 | 6 | uv 0.12.17 в venv `$RUNNER_TEMP/uv` |
| make student_test | 0 | 62 | `198 passed, 56 deselected in 52.62s` |
| make test-persistence | 0 | 32 | `PASS`, затем обе реплики в LB |
| make test-failover, stop and kill | 0 | 39 | 2 × `PASS`, `failed_attempts` 0 |
| Stand logs | — | — | пропущен (`failure()`) |
| Remove the stand | 0 | 16 | контейнеры, сеть, volumes `…_postgres_data` и `…_s3_data` удалены |
Сборка шла из кэша BuildKit хоста; на раннере первая сборка дольше
(зависимости по `uv.lock` скачиваются заново).
Стенд после старта (`docker compose ps -a`): сервисы рабочего стенда,
конфиги HAProxy, Valkey, bootstrap S3 и `config.toml` — из `configs`, не
из bind mount.
```text
SERVICE STATUS
api Up 3 seconds (healthy)
api Up 3 seconds (healthy)
cleaner Up 3 seconds
haproxy Up 3 seconds (healthy)
migrate Exited (0) 6 seconds ago
postgres Up 11 seconds (healthy)
s3 Up 11 seconds (healthy)
s3-bootstrap Exited (0) 3 seconds ago
valkey Up 11 seconds (healthy)
```
`make check`, `make test` (через `http://haproxy:8080` в сети стенда):
```text
python3 scripts/check_contract.py
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
python3 tests/smoke.py --base-url "http://haproxy:8080"
PASS: lab4 public API scenario; infrastructure and grading evidence remain separate.
```
Аноним без подписи:
```text
anonymous GET http://s3:8333/ -> 403
anonymous GET http://s3:8333/messenger -> 403
anonymous GET http://s3:8333/messenger?list-type=2 -> 403
```
`make student_test` (`BASE_URL=http://haproxy:8080 EXPECT_REPLICAS=2 uv
run pytest`, CPython 3.12.3 образа, 102 пакета по `uv.lock`): тесты реплик
выполнены, а не пропущены — `test_download_through_other_replica`,
`test_replay_on_other_replica`, `test_one_session_on_several_replicas`,
`test_write_visible_through_other_replica`,
`test_same_key_through_replicas` — `PASSED`.
```text
coverage: 252 scenarios in 13 specs, 235 tested (70 by make failure_checks), 17 excluded
===================== 198 passed, 56 deselected in 52.62s ======================
```
`make test-persistence ACTION_SCRIPT=scripts/restart.sh` — hook
перезапускает LB, реплики, PostgreSQL, Valkey и S3 этого проекта
(`COMPOSE_PROJECT_NAME`, `COMPOSE_FILE` из окружения job):
```text
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
LB ready: 0d9ec34300c1 dd41a7e8f7f9
```
`make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, затем `make
replicas`, затем то же со `STOP_MODE=kill`:
```text
{"observed_instances_before": 2, "successful_writes": 121, "failed_attempts": 0, "first_recovery_seconds": 1.804}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
{"observed_instances_before": 2, "successful_writes": 125, "failed_attempts": 0, "first_recovery_seconds": 0.858}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
2026-10-29T15:08:18Z TARGET_INSTANCE_ID=dd41a7e8f7f9 container=dd41a7e8f7f9957ba930c4a5d5d1a28eef38f90cdc63e1ff682443d4633c95d7 mode=stop
2026-10-29T15:08:37Z TARGET_INSTANCE_ID=dd41a7e8f7f9 container=dd41a7e8f7f9957ba930c4a5d5d1a28eef38f90cdc63e1ff682443d4633c95d7 mode=kill
```
Тест останавливает реплику, ответившую на его первую отправку: оба раза
это `dd41a7e8f7f9`, в режимах `stop` и `kill`. Отказ каждой реплики по
очереди — `evidence/failover/test-failover.md` и
`evidence/tests/clean-clone-final.md`.
После прогона на хосте нет ни контейнеров, ни volumes, ни сетей, ни
образа прогона (`docker ps -a`, `docker volume ls`, `docker network ls`,
`docker image ls` по `safronov-ci` — пусто).
## Шаг уборки хвостов трогает только свои проекты
Контейнер, volume и сеть с меткой проекта
`mtusi-lab4-safronov-ci-zz9` и контейнер проекта `mtusi-lab4-other`;
блок `run` шага «Remove stands of interrupted runs» в контейнере образа
раннера с сокетом Docker:
```text
remove leftover stand mtusi-lab4-safronov-ci-zz9
step exit=0
```
После него остался только контейнер `mtusi-lab4-other`; контейнер,
volume и сеть проекта `…-ci-zz9` удалены.
+336
View File
@@ -0,0 +1,336 @@
# Итоговая проверка из чистого clone: стенд с LB, S3 и уборщиком
| | |
|---|---|
| Что проверялось | раздел `REPORT.md` «Запуск из чистого clone»: шаг за шагом, как у проверяющего |
| Дата | 2026-10-29 12:46–13:04 UTC |
| Commit | `de98d77` — `git clone --branch solution/bvt2301-safronov` локального репозитория во временный каталог. Рабочее дерево клона чистое, `.env`, `config.toml` и `.venv` нет. Это итоговый код всех changes лабы 4: последний commit кода — `ca0c4b2` (правки по verify `track2-reconcile-cost`), после него — только документы |
| Стенд | временный проект compose `mtusi-lab4-cleancheck`, LB на `127.0.0.1:8090`, остальные порты по умолчанию: PostgreSQL 5433, Valkey 6380, S3 8334, `make test_isolated` 18088. Клон стартовал на пустых volumes PostgreSQL и S3 со своими секретами, как у проверяющего. Рабочий стенд `mtusi-lab4` остановлен и не тронут. После проверки стенд клона удалён (`docker compose down -v`), volumes `mtusi-lab4_postgres_data` и `mtusi-lab4_s3_data` на месте |
| Хост | Docker Desktop 29.9.2, Compose 5.6.1, macOS 26.7.1, Apple M3 Pro, 18 ГиБ; ВМ Docker — 12 CPU, 7,7 GiB, ядро 7.0.14-linuxkit, aarch64; `python3` на `PATH` — 3.11.9, uv 0.12.17 (виртуальное окружение — CPython 3.12.12). Порт 8080 хоста занят посторонним контейнером. Это проверка, а не замер |
**Отличие от последовательности проверяющего — две строки `.env`.**
Порт 8080 на хосте занят посторонним контейнером, а рабочий стенд с
тем же именем проекта трогать нельзя. Поэтому до `make env_setup` в клон
записан `.env` из двух строк: `COMPOSE_PROJECT_NAME=mtusi-lab4-cleancheck`
и `APP_OUT_PORT=8090`. Это штатный способ из раздела «Нужно на машине».
Остальные переменные, в том числе все секреты, дописал `make env_setup`
из `.env.example`: этот путь проходит проверяющий со старым `.env`.
Цели `Makefile`, `scripts/restart.sh`, `scripts/stop-one.sh`,
`run_failures.py`, `run_isolated.py` и драйвер берут проект и порт у
`docker compose` и из `.env`, поэтому шаги те же. Отличие одно:
`BASE_URL=http://localhost:8090` у `make test`, `make test-persistence`,
`make test-failover` и `make student_test`, а у драйвера — `--port
8090`.
Значения секретов не выводились. Поиск всех десяти значений из `.env`
клона по полному журналу проверки — 0 совпадений.
Все шаги ниже завершились с кодом 0. Длительности — из журнала, `exit` —
код команды.
## Подготовка и запуск
```text
$ git clone --branch solution/bvt2301-safronov <репозиторий> clean-clone && cd clean-clone
$ git log --oneline -1; git status --short | wc -l; ls .env config.toml .venv
de98d77 docs: archive track2-reconcile-cost and sync its specs
0
ls: .env: No such file or directory
ls: .venv: No such file or directory
ls: config.toml: No such file or directory
$ grep -v '^#' .env # записан до env_setup: комментарий и две строки, см. выше
COMPOSE_PROJECT_NAME=mtusi-lab4-cleancheck
APP_OUT_PORT=8090
$ make env_setup
added to existing .env: APP__PORT API_REPLICAS POSTGRES_USER POSTGRES_PASSWORD POSTGRES_DB POSTGRES_HOST POSTGRES_PORT POSTGRES_OUT_PORT DATABASE__HOST DATABASE__PORT DATABASE__USER DATABASE__PASSWORD DATABASE__NAME VALKEY_PASSWORD VALKEY_HOST VALKEY_PORT VALKEY_OUT_PORT CACHE__HOST CACHE__PORT CACHE__PASSWORD S3__BUCKET S3_ROOT_ACCESS_KEY S3_ROOT_SECRET_KEY S3_JWT_SIGNING_KEY S3_API_ACCESS_KEY S3_API_SECRET_KEY S3_CLEANER_ACCESS_KEY S3_CLEANER_SECRET_KEY S3_HOST S3_PORT S3_OUT_PORT S3__HOST S3__PORT S3__ACCESS_KEY_ID S3__SECRET_ACCESS_KEY TEST_APP_PORT
env ready: .env, config.toml
$ grep -c -E '^(POSTGRES|VALKEY)_PASSWORD=.{32}$' .env # случайные пароли
2
$ docker compose config | sed -n 's/^name: //p'
mtusi-lab4-cleancheck
$ make run_docker # exit 0, 11 с (слои — из кэша BuildKit)
Image mtusi-messenger:lab4 Built
Volume mtusi-lab4-cleancheck_postgres_data Created
Volume mtusi-lab4-cleancheck_s3_data Created
Container mtusi-lab4-cleancheck-migrate-1 Exited
Container mtusi-lab4-cleancheck-s3-bootstrap-1 Exited
$ make replicas # exit 0, 3 с: ожидание healthy
$ docker compose ps -a --format 'table {{.Name}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}'
NAME IMAGE STATUS PORTS
mtusi-lab4-cleancheck-api-1 mtusi-messenger:lab4 Up 2 seconds (healthy) 8080/tcp
mtusi-lab4-cleancheck-api-2 mtusi-messenger:lab4 Up 3 seconds (healthy) 8080/tcp
mtusi-lab4-cleancheck-cleaner-1 mtusi-messenger:lab4 Up 2 seconds 8080/tcp
mtusi-lab4-cleancheck-haproxy-1 haproxy:3.4.6-trixie@sha256:e273… Up 2 seconds (health: starting) 127.0.0.1:8090->8080/tcp
mtusi-lab4-cleancheck-migrate-1 mtusi-messenger:lab4 Exited (0) 7 seconds ago
mtusi-lab4-cleancheck-postgres-1 postgres:18.6-trixie@sha256:5a5a… Up 10 seconds (healthy) 127.0.0.1:5433->5432/tcp
mtusi-lab4-cleancheck-s3-1 chrislusf/seaweedfs:4.48@sha256:4e61… Up 11 seconds (healthy) 127.0.0.1:8334->8333/tcp
mtusi-lab4-cleancheck-s3-bootstrap-1 chrislusf/seaweedfs:4.48@sha256:4e61… Exited (0) 3 seconds ago
mtusi-lab4-cleancheck-valkey-1 valkey/valkey:9.1.2-trixie@sha256:4186… Up 10 seconds (healthy) 127.0.0.1:6380->6379/tcp
```
Digest в выводе сокращён, полностью он в `docker-compose.yml`. `8080/tcp`
у реплик и уборщика — `EXPOSE` образа: опубликованного порта у них нет,
API на хосте — только через HAProxy. Уборщик HTTP не слушает.
```text
$ docker compose logs migrate --no-log-prefix | <поле event>
Running upgrade -> 16c279725564, added messenger tables
Running upgrade 16c279725564 -> 42bc3b9be38f, added sessions and password hashes
Running upgrade 42bc3b9be38f -> 7652184b7016, added idempotency keys
Running upgrade 7652184b7016 -> e656d6bbe1a4, added message instance id
Running upgrade e656d6bbe1a4 -> ef25d50b01a8, added attachments tables
Running upgrade ef25d50b01a8 -> 739b8f04d5fb, added pending attachments index
Running upgrade 739b8f04d5fb -> 5c3e1f0a9b7d, added attachments lost_at
Finished alembic
$ docker compose logs s3-bootstrap --no-log-prefix
s3-bootstrap: bucket messenger created
s3-bootstrap: user api created
s3-bootstrap: user cleaner created
s3-bootstrap: checks passed (api key put/get; cleaner key get/delete and list messenger/attachments/; api key list and bucket create, cleaner key put and list of the bucket, anonymous get and list denied)
$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8090/health/ready
200
```
## Публичные проверки skeleton
```text
$ make check
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
$ uv sync && make validate PYTHON=.venv/bin/python # exit 0
Installed 102 packages in 169ms
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
$ make test BASE_URL=http://localhost:8090
python3 tests/smoke.py --base-url "http://localhost:8090"
PASS: lab4 public API scenario; infrastructure and grading evidence remain separate.
$ make instances
user lb_cdce70f9: one login, 12 requests with one token
91fbe934191d: 6
94a968393dd6: 6
instances: 2
$ make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8090 # 29 с
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
$ docker compose ps -a --format '{{.Name}} {{.Status}}' # сразу после hook
mtusi-lab4-cleancheck-api-1 Up 1 second (healthy)
mtusi-lab4-cleancheck-api-2 Up 1 second (healthy)
mtusi-lab4-cleancheck-cleaner-1 Up 38 seconds
mtusi-lab4-cleancheck-haproxy-1 Up 1 second (healthy)
mtusi-lab4-cleancheck-migrate-1 Exited (0) 2 seconds ago
mtusi-lab4-cleancheck-postgres-1 Up 27 seconds (healthy)
mtusi-lab4-cleancheck-s3-1 Up 12 seconds (healthy)
mtusi-lab4-cleancheck-s3-bootstrap-1 Exited (0) 1 second ago
mtusi-lab4-cleancheck-valkey-1 Up 27 seconds (healthy)
```
Hook перезапустил LB, обе реплики, PostgreSQL, Valkey и S3: у них время
работы меньше длительности hook. Уборщик hook не трогает (он переживает
рестарт хранилищ сам) — `Up 38 seconds` со старта стенда. `migrate` и
`s3-bootstrap` прошли повторно при старте реплик (no-op).
```text
$ STOP_ONE_LOG=<файл> make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://localhost:8090 # 16 с
{"observed_instances_before": 2, "successful_writes": 121, "failed_attempts": 0, "first_recovery_seconds": 1.08}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
$ cat <файл>; docker compose ps -a --format '{{.Name}} {{.Status}}' | grep api
2026-10-29T12:46:50Z TARGET_INSTANCE_ID=91fbe934191d container=91fbe934191d1d08cd0b04dc85f5e0fbe67da16bdbcfd9e96321e021e217c08b mode=stop
mtusi-lab4-cleancheck-api-1 Up 17 seconds (healthy)
mtusi-lab4-cleancheck-api-2 Exited (0) 14 seconds ago
$ make replicas; curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8090/health/live
200
$ STOP_ONE_LOG=<файл> make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://localhost:8090 # 16 с
{"observed_instances_before": 2, "successful_writes": 116, "failed_attempts": 0, "first_recovery_seconds": 1.201}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
$ cat <файл>; docker compose ps -a --format '{{.Name}} {{.Status}}' | grep api
2026-10-29T12:46:50Z TARGET_INSTANCE_ID=91fbe934191d container=91fbe934191d1d08cd0b04dc85f5e0fbe67da16bdbcfd9e96321e021e217c08b mode=stop
2026-10-29T12:47:08Z TARGET_INSTANCE_ID=94a968393dd6 container=94a968393dd656fe53a6700f0d43221ac8d8ea8c3252fd0a377dc2a81d111417 mode=stop
mtusi-lab4-cleancheck-api-1 Exited (0) 14 seconds ago
mtusi-lab4-cleancheck-api-2 Up 17 seconds (healthy)
$ make replicas
```
Остановлены обе реплики по очереди: ID контейнера в строке
`STOP_ONE_LOG` равен `TARGET_INSTANCE_ID`, выбранному тестом, и
остановлен именно он (`Exited (0)`).
## Приватность bucket и вложения
```text
$ make s3_check # 3 с
S3 s3:8333 (host 127.0.0.1:8334), bucket messenger, image chrislusf/seaweedfs:4.48
where check expected got verdict
server anonymous access setting none none ok
server api key put object 200 200 ok
server api key get object 200 200 ok
server api key head object 200 200 ok
server api key get missing object 404 404 ok
server api key list objects 403 403 ok
server api key create bucket 403 403 ok
server api key delete bucket 403 403 ok
server api key get bucket policy 403 403 ok
server api key put bucket policy 403 403 ok
server api key get bucket acl 403 403 ok
server api key put bucket acl public-read 403 403 ok
server api key put object acl public-read 403 403 ok
server api key put cleaner probe object 200 200 ok
server cleaner key get object 200 200 ok
server cleaner key head object 200 200 ok
server cleaner key delete object 204 204 ok
server cleaner key delete object again 204 204 ok
server api key get deleted object 404 404 ok
server cleaner key delete missing object 204 204 ok
server cleaner key put object 403 403 ok
server cleaner key list objects 403 403 ok
server cleaner key list attachments prefix 200 200 ok
server cleaner key list other prefix 403 403 ok
server cleaner key create bucket 403 403 ok
server cleaner key delete bucket 403 403 ok
server cleaner key get bucket policy 403 403 ok
server cleaner key put bucket policy 403 403 ok
server cleaner key get bucket acl 403 403 ok
server cleaner key put bucket acl public-read 403 403 ok
server cleaner key put object acl public-read 403 403 ok
server api key put object to other bucket 403 403 ok
server api key get object from other bucket 403 403 ok
server api key list other bucket 403 403 ok
server api key delete other bucket 403 403 ok
server cleaner key get object from other bucket 403 403 ok
server cleaner key delete object in other bucket 403 403 ok
server cleaner key list other bucket 403 403 ok
server cleaner key delete other bucket 403 403 ok
server anonymous get object 403 403 ok
server anonymous head object 403 403 ok
server anonymous get missing object 403 403 ok
server anonymous list objects 403 403 ok
server anonymous list buckets 403 403 ok
server anonymous put object 403 403 ok
server anonymous create bucket 403 403 ok
host anonymous get object 403 403 ok
host anonymous head object 403 403 ok
host anonymous get missing object 403 403 ok
host anonymous list objects 403 403 ok
host anonymous list buckets 403 403 ok
host anonymous put object 403 403 ok
server listening outside loopback 8333 18333 8333 18333 ok
network anonymous get object 403 403 ok
network anonymous head object 403 403 ok
network anonymous get missing object 403 403 ok
network anonymous list objects 403 403 ok
network anonymous list buckets 403 403 ok
network anonymous put object 403 403 ok
network port 8333 (S3 API / gRPC of gateway) open open ok
network port 18333 (S3 API / gRPC of gateway) open open ok
network port 8080 (loopback only) closed closed ok
network port 8888 (loopback only) closed closed ok
network port 9333 (loopback only) closed closed ok
network port 18080 (loopback only) closed closed ok
network port 18888 (loopback only) closed closed ok
network port 19333 (loopback only) closed closed ok
network port 39821 (loopback only) closed closed ok
server temporary buckets left 0 0 ok
server probe objects left 0 0 ok
PASS: 70 checks, bucket messenger is private
$ python3 .claude/skills/run-mtusi-messenger/driver.py --port 8090 attachment-failover --mode stop # 4 с
mode: stop; fixture sample.png: 111817 bytes
sha256 uploaded: 99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75
sha256 downloaded: 99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75
step expected got x-instance-id
alice uploads 201 201 94a968393dd6
alice sends message 201 201 91fbe934191d
stop-one.sh stop 0 0 94a968393dd6
bob downloads 200 200 91fbe934191d
bob reads metadata 200 200 91fbe934191d
eve reads metadata 404 404 91fbe934191d
eve downloads 404 404 91fbe934191d
make replicas 0 0
LB slots UP 2 2
PASS: accepted by 94a968393dd6, served by 91fbe934191d after stop, sha256 matches, outsider gets 404
$ python3 .claude/skills/run-mtusi-messenger/driver.py --port 8090 attachment-storage # 2 с
upload via 94a968393dd6: object_key messenger/attachments/bf97f566-2bc7-4fbd-bb65-9eee25af4404/original
upload via 91fbe934191d: object_key messenger/attachments/3b703856-69cc-40c1-9249-f4033820e321/original
docker diff 94a968393dd6: 2 changes
C /app
A /app/config.toml
docker diff 91fbe934191d: 2 changes
C /app
A /app/config.toml
bytea columns expected sha256 got sha256
octet_length(sha256) expected 32 got 32
filename not in key expected no got no
object in bucket, bytes expected 111817 got 111817
anonymous GET of the key expected 403 got 403
downloaded sha256 = uploaded expected yes got yes
original files in 94a968393dd6 expected 0 got 0
original files in 91fbe934191d expected 0 got 0
PASS: metadata in PostgreSQL, bytes only in the private bucket messenger, none in the API containers
```
У `attachment-storage` строки второй загрузки повторяют первую и здесь
опущены; полный вывод того же вида — `evidence/attachments/storage.md`.
## Свои тесты, сверка, отказы
```text
$ make student_test BASE_URL=http://localhost:8090 # 42 с
BASE_URL=http://localhost:8090 EXPECT_REPLICAS=2 uv run pytest
collecting ... collected 254 items / 56 deselected / 198 selected
coverage: 252 scenarios in 13 specs, 235 tested (70 by make failure_checks), 17 excluded
key race through replicas: {'94a968393dd6': 5, '91fbe934191d': 5}
===================== 198 passed, 56 deselected in 41.24s ======================
$ make reconcile # 5 с, dry-run, exit 0
{"event": "Finished reconcile pass", "module": "attachment_reconcile_service", "method": "reconcile", "apply": false, "strategy": "batch", "deep": false, "listed_objects": 74, "checked_rows": 74, "found": {}, "fixed": {}, "remaining": 0, "fresh_objects": 0, "fresh_rows": 0, "lost_known": 0, "refused": false, "unlogged": 0, "unchecked": 0, "interrupted_by": null, "duration_ms": 197, "max_objects_per_second": 2000.0, "storage_objects": 74, "s3_requests": {"list": 1, "head": 0, "get": 0, "delete": 0}, "read_bytes": 0, "db_sessions": 3, "phase_ms": {"list": 131, "rows": 64, "stale": 2, "recheck": 0, "act": 0}, "level": "info"}
$ make test_isolated # 88 с
[test_isolated] database=test_messenger objects=/buckets/messenger/test_messenger/ container=mtusi-lab4-cleancheck-test-api base_url=http://127.0.0.1:18088
[test_isolated] make test
PASS: lab4 public API scenario; infrastructure and grading evidence remain separate.
[test_isolated] make student_test
=========== 193 passed, 5 skipped, 56 deselected in 75.43s (0:01:15) ===========
[test_isolated] cleanup
[test_isolated] remove objects /buckets/messenger/test_messenger/
[test_isolated] results: {'test': 0, 'student_test': 0}
$ make failure_checks # 857 с
[failure_checks] project=mtusi-lab4-cleancheck-failures (working stand: mtusi-lab4-cleancheck)
[failure_checks] start cleaner: grace 20 s, interval 1 s, reconcile interval 0 s (0 — off)
[failure_checks] pytest -m fault
collecting ... collected 254 items / 198 deselected / 56 selected
================ 56 passed, 198 deselected in 834.00s (0:13:54) ================
[failure_checks] postgres log: 467 lines, crash markers 0; "too many clients" 30, "administrator command" 148
[failure_checks] cleanup
[failure_checks] results: {'fault': 0, 'postgres': 0}
```
Сверка нашла 74 объекта и 74 строки — вложения, загруженные шагами
выше, — и ни одного расхождения. Пять пропусков `make test_isolated` —
тесты реплик против одного процесса, с причиной «one API process
(EXPECT_REPLICAS=1): replica checks need the stand with the load
balancer». «too many clients» и «administrator command» в журнале
PostgreSQL стенда отказов — внесённые тестами отказы (заполнение
`max_connections`, остановка PostgreSQL), признаков аварийного
перезапуска нет. После `make failure_checks` контейнеров и volumes
проекта `mtusi-lab4-cleancheck-failures` не осталось, стенд клона
работал все 17 минут.
## Уборка
```text
$ docker compose down -v --remove-orphans # проект mtusi-lab4-cleancheck
Volume mtusi-lab4-cleancheck_postgres_data Removed
Volume mtusi-lab4-cleancheck_s3_data Removed
Network mtusi-lab4-cleancheck_default Removed
$ docker volume ls --format '{{.Name}}' | grep mtusi-lab4
mtusi-lab4_postgres_data
mtusi-lab4_s3_data
```