diff --git a/.claude/rules/api-contract.md b/.claude/rules/api-contract.md index 38c85e15..f48f60da 100644 --- a/.claude/rules/api-contract.md +++ b/.claude/rules/api-contract.md @@ -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`. diff --git a/.claude/rules/docker.md b/.claude/rules/docker.md index 05c267fa..23c95ab5 100644 --- a/.claude/rules/docker.md +++ b/.claude/rules/docker.md @@ -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` или возьмёт чужой образ. ## Обновление кода на стенде diff --git a/.claude/rules/infra.md b/.claude/rules/infra.md index 9bab9f34..0d59e429 100644 --- a/.claude/rules/infra.md +++ b/.claude/rules/infra.md @@ -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`, без diff --git a/.claude/rules/service-layer.md b/.claude/rules/service-layer.md index 20987702..80d75f39 100644 --- a/.claude/rules/service-layer.md +++ b/.claude/rules/service-layer.md @@ -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), сервис процесса уборщика: diff --git a/.claude/rules/settings.md b/.claude/rules/settings.md index 55a768e3..b246d25c 100644 --- a/.claude/rules/settings.md +++ b/.claude/rules/settings.md @@ -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: diff --git a/.github/ci/compose.yml b/.github/ci/compose.yml new file mode 100644 index 00000000..7cabd51a --- /dev/null +++ b/.github/ci/compose.yml @@ -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 diff --git a/.github/ci/stand-env.sh b/.github/ci/stand-env.sh new file mode 100644 index 00000000..9845577f --- /dev/null +++ b/.github/ci/stand-env.sh @@ -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 +} diff --git a/.github/workflows/application.yml b/.github/workflows/application.yml new file mode 100644 index 00000000..251cc2d8 --- /dev/null +++ b/.github/workflows/application.yml @@ -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 diff --git a/AGENTS.md b/AGENTS.md index 65dbb4d1..82f94754 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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-, 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 (в ней новые цели и проверки) и дописываем свои секции. diff --git a/PLAN.md b/PLAN.md deleted file mode 100644 index cc96b4a6..00000000 --- a/PLAN.md +++ /dev/null @@ -1,1660 +0,0 @@ -# План лабы 4 на «5» - -Рабочий документ на время лабы (составлен 2026-10-20). Пункты -закрываются changes OpenSpec по порядку из раздела «Последовательность -работ»; решение, принятое в design change, важнее этого плана. Когда -change заархивирован, его строку здесь отметить; когда закрыты все — -итоги перенести в `REPORT.md`, а файл удалить. - -Задание — `README.md`, переходы API — `COURSE.md`, семантика — -`contracts/README.md`, раздел «Вложения (с lab4)». Код пока в состоянии -лабы 3 (commit `5d5d8f9`, «carry lab 3 over»): S3 и вложений нет. Поэтому -по коду, без запуска: -- публичный smoke (`LAB=4`) упадёт на загрузке вложения; -- `make student_test` красный на `test_exclusion_evidence_exists`: - файлов evidence исключений сверки ещё нет (AGENTS.md, «Переход в - следующую лабу»). - -Оба пункта закрывает change `attachments`. - -## Что требует рубрика и чем закрываем - -| Уровень | Пункт рубрики | Как закрываем | Change | -|---|---|---|---| -| 3 | S3 в общем стенде, persistent volume, закреплённая версия, создание приватного bucket описано | сервис S3 в `docker-compose.yml`, одноразовый bootstrap как `migrate` | `s3-storage` | -| 3 | метаданные в PostgreSQL, байты в приватном bucket, не в БД и не в локальном каталоге API | таблица вложений, ключ объекта назначает сервер | `attachments` | -| 3 | `POST` вложения → `201 ready` после сохранения, побайтный download, `attachment_ids` в сообщении, smoke с checksum и 404 постороннему | ручки upload / метаданные / content, поле сообщения, история | `attachments` | -| 3 | реальные PNG/JPEG ≤ 10 MiB и ≤ 40 млн пикселей, MIME по содержимому, опасный `filename` отклонён, лимиты до неограниченного чтения и декодирования | `Content-Length` до чтения, потоковое чтение со счётчиком, сигнатура по байтам, размеры из заголовка до декодирования | `attachments` | -| 3 | upload → остановка обслужившей реплики → download через другую тот же файл; restart с volumes сохраняет метаданные и оригинал | `make test-persistence`, `make test-failover` и свой сценарий: остановить реплику по `X-Instance-Id` **загрузки** | `attachments` | -| 3 (п. 5 «Что сделать») | недоступность S3, чужой чат, restart всего стенда | 503 вместо 500 при отказе S3, текстовые сообщения работают; тесты отказов | `attachments`, `upload-consistency` | -| 4 | тесты: большой файл, повреждённое изображение, подмена MIME, чужое `attachment_id`, вложение другого чата; пользовательская ошибка не 500 | `student-tests/test_attachments.py` | `attachments` | -| 4 | прерванная загрузка и отказ между S3 и БД не оставляют вечных неучтённых объектов; механизм компенсации / очистки с grace period описан | строка-намерение до PUT, компенсация, уборщик зависших намерений | `upload-consistency` | -| 4 | лимиты, таймауты и потоковая обработка ограничивают RAM; ≥ 10 одновременных загрузок с замером пика памяти | лимит одновременных загрузок на реплику, профиль `uploads` стенда `bench/` | `upload-memory` | -| 4 | bootstrap идемпотентен; у API отдельные S3 credentials с ограниченными правами; консоль не в общей сети; проверка приватности bucket вне API | bootstrap дважды, пользователь API только на объекты bucket, анонимный GET / LIST → 403 | `s3-storage` | -| 5 | трек 2 «Согласованность двух хранилищ» | раздел «Трек 5» ниже | `track2-reconciler`, `track2-reconcile-cost` | - -Сценарий защиты (README): п. 1 — smoke и команда драйвера; п. 2 — 404 -постороннему и анонимный GET в S3 (`s3-storage`); п. 3 — -`test-persistence` и `test-failover`; п. 4 — нет локального файла -оригинала на API, отказы и эксперименты. - -## Ключевые решения - -Ниже предложения. Окончательное решение принимается в design -соответствующего change. - -### 1. S3-сервер: SeaweedFS, не MinIO — подтверждено 2026-10-20 - -README разрешает любой из трёх: MinIO, SeaweedFS, RustFS. MinIO — -самый известный вариант, но закрепить его образ из чистого clone -сейчас нельзя. Проверено 2026-10-20: - -- `docker buildx imagetools inspect minio/minio:latest` и - `minio/mc:latest` — «pull access denied, repository does not exist»; - API Docker Hub на `minio/minio` отвечает 404; -- `quay.io/minio/minio` — 401 без авторизации; -- для сравнения `chrislusf/seaweedfs` и `rustfs/rustfs:1.0.3` - разрешаются, у обоих свежие теги (2026-10-17…20). - -По публичным источникам (блоги, не объявления MinIO): сборки образов -community edition прекращены в октябре 2025, с декабря 2025 — -maintenance mode, в 2026 репозиторий архивирован; исправление -CVE-2025-62506 в образ не попало. Варианты оставить MinIO и их цена: - -| Вариант | Чем плох | -|---|---| -| старый закреплённый образ | из чистого clone не скачивается — рубрика «3» (стенд из репозитория) не выполняется | -| сборка из исходников архивного репозитория | свой Dockerfile с Go-сборкой, исправлений дальше не будет | -| форк `pgsty/minio` | сторонний проект, доверие и сопровождение надо проверять | - -Сравнение оставшихся: - -| | SeaweedFS | RustFS | -|---|---|---| -| Зрелость | с 2015 года, образы публикуются ежедневно | проект моложе, открыт в 2025 | -| Bootstrap bucket и пользователя | `weed shell` (`s3.bucket.create`, `s3.configure`) из того же закреплённого образа | admin API в стиле MinIO: нужен `mc` (образ недоступен, см. выше) или свой код подписи | -| Права пользователя API | действия `Read` / `Write` / `List` / `Admin` на bucket | IAM-политики в формате AWS, тоньше (`s3:PutObject` без `s3:DeleteObject`) | -| Консоль / UI | master, filer, volume, admin UI — не публикуются | консоль на отдельном порту — не публикуется или выключается | - -Предложение — **SeaweedFS**: один процесс `weed server -s3` с volume, -bootstrap одноразовым сервисом на том же образе. В design -`s3-storage` — короткая проверка на стенде до выбора: идемпотентность -создания bucket, запрет анонимного доступа, права пользователя API, -healthcheck, переживание рестарта. Если SeaweedFS провалит проверку — -RustFS. В `.claude/rules/settings.md` MinIO упомянут только примером -секрета, правило обновляется в том же change. - -### 2. Запись вложения: намерение → объект → готово - -- Порядок upload: проверки до чтения → потоковое чтение и проверка - содержимого → строка-намерение `pending` с ключом объекта (commit) → - `PUT` в S3 → строка `ready` (commit) → `201`. -- Ключ объекта — серверный (`uuid`), `filename` только для показа: - ни путь, ни ключ из него не строятся. -- Любой объект в bucket, загруженный API, известен БД **до** PUT. - Сбой после PUT и до второго commit оставляет `pending`, а не - неучтённый объект: его убирает уборщик после grace period - (`upload-consistency`). Объект без строки возможен только мимо API — - это класс расхождений трека 2. -- Ответ на вопрос защиты «PUT прошёл, COMMIT нет» — отсюда. -- `pending` во внешний API не попадает: контракт лабы 4 знает только - `ready`; `GET` такого вложения — 404. - -### 3. `/health/ready` без S3 — подтверждено 2026-10-20 - -Отказ S3 не выводит реплики из LB: вложения отвечают 503 `unavailable`, -текстовые сообщения и история работают. Если включить S3 в готовность, -его заминка разом выключит все реплики, включая текстовый путь -(та же логика, что у таймаута готовности PostgreSQL, `balancer.md`). -Решение и список критичных зависимостей — в `REPORT.md` (контракт: -«Какие зависимости критичны, зафиксируйте в отчёте»). - -### 4. Память загрузки - -- Тело ≤ 10 MiB: `Content-Length` больше лимита — 413 до чтения; без - `Content-Length` — счётчик при чтении, обрыв на 10 MiB + 1. -- Сигнатура PNG / JPEG по первым байтам; размеры из заголовка до - декодирования, больше 40 млн пикселей — 413. -- Главный риск — не байты, а декодирование: 40 млн пикселей RGB — - около 120 МБ на одну загрузку при лимите реплики 512 МБ. Варианты - для design `attachments`: проверка целостности без полного - декодирования (PNG — CRC чанков и потоковая распаковка IDAT со - счётчиком строк; JPEG — структура маркеров), полное декодирование - под семафором, `draft` для JPEG. Цена каждого — в `upload-memory`. -- Лимит одновременных загрузок на реплику и сроки чтения тела (HAProxy - и API). `timeout server` LB 10 с рассчитан на запрос к БД, а не на - медленную передачу 10 MiB — цепочку таймаутов пересмотреть для пути - upload. - -### 5. Учётные данные S3 - -- root — только bootstrap; API и уборщик его не получают. -- Пользователь API — объекты своего bucket: чтение, запись, удаление - (компенсация). Без List и Admin. -- Уборщик / reconciler — свой пользователь: List, чтение, удаление. -- Пароли — `.env` (`make env_setup` генерирует, как Postgres и - Valkey), в приложение — мостами `S3__*`. Соответствие имён skeleton - (`S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID_FILE`, - `S3_SECRET_ACCESS_KEY_FILE`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`) — - в `REPORT.md`, как в лабе 3. -- API-порт S3 — только `127.0.0.1` (console-режим `make run_dev`), как - Postgres и Valkey; UI и консоль не публикуются вообще. - -### 6. Идемпотентность с `attachment_ids` - -`message_request_hash` начинает учитывать `attachment_ids`. Пустой -список не должен менять хэш: иначе ключ, сохранённый версией без -вложений, после `make rolling_update` давал бы 409 на повтор того же -тела. Порядок элементов массива значим (это JSON-массив), порядок -ключей объекта — нет (контракт). - -### 7. Уборщик — отдельный сервис (подтверждено 2026-10-20) - -Фоновая работа в API-репликах запрещена до worker лабы 5 (AGENTS.md, -«Архитектура в двух словах»). Уборщик зависших `pending` — отдельный -сервис compose на образе API со своей командой и своими S3-правами, -интервал и grace period в настройках. Отвергнута цель Makefile без -расписания: с ней «вечных» объектов нет только при регулярном ручном -запуске. В треке 2 уборщик вырастает в reconciler. - -## Трек 5: трек 2 «Согласованность двух хранилищ» (подтверждено 2026-10-20) - -**Почему трек 2.** -- Продолжает обязательный пункт «4» (компенсация и очистка): общий - код, общие тесты отказов. -- Контракт не расширяется, S3 остаётся во внутренней сети. -- Замеры ложатся на готовый `bench/` (наполнение, паспорт, сэмплер, - `summary.md`), как трек 2 лабы 2. -- Пригодится в лабе 5: staging-prefix, хвосты worker при доставке at - least once. - -**Почему не трек 1 (presigned upload).** -- S3 должен быть доступен клиенту: подпись под внешний адрес, шире - поверхность атаки. -- Новые ручки init / complete в `contracts/extensions.openapi.json`. -- Лимит размера (POST policy `content-length-range`) и checksum при - complete на SeaweedFS / RustFS не проверены; без них complete читает - объект обратно, и выигрыш по трафику API тает. -- В лабе 5 загрузка становится асинхронной (202) — flow переделывать. - -### Гипотезы (до прогонов коммитятся отдельно) - -1. **Линейность.** Время обхода растёт линейно по числу объектов, цена - на объект от N почти не зависит. -2. **Батч против точечной сверки.** Сверка страницы LIST (до 1000 - ключей) одним запросом к БД (`object_key = ANY(...)`) дешевле - `HEAD` на каждую строку: запросов N/1000 против N. -3. **Поверхностная против глубокой.** Размер из LIST почти бесплатен; - SHA-256 требует прочитать каждый объект и упирается в чтение S3 — - глубокая сверка выборочная или по требованию. -4. **Влияние на рабочий трафик.** Обход с ограниченной скоростью - ухудшает p95 фоновой нагрузки API не больше порога, заданного до - прогона. -5. **Безопасность.** Ни одно подтверждённое и ни одно используемое в - сообщениях вложение не удаляется при любой гонке с загрузками. - -### Методика (предварительно) - -- Стенд `mtusi-bench` с S3 и лимитами из паспорта. N = 10k и 100k - объектов; наполнение мимо API (SQL и прямой PUT), граница описана. -- Внесённые расхождения, по доле каждого класса: объект без строки, - зависший `pending`, строка `ready` без объекта, другой размер. -- Метрики: время по фазам, запросы S3 и PostgreSQL, CPU / RAM - reconciler, S3 и PostgreSQL (сэмплер), p95 фоновой нагрузки k6. -- 3 повтора, A/A для отделения эффекта от шума (`make bench_compare` - или его аналог для профиля). - -### Ограничения, которые заранее назвать - -- Генератор, API, S3 и БД на одном хосте, Docker Desktop — VM. -- Одна нода S3, без репликации: отказ диска или хоста не переживается. -- Строку без объекта не восстановить: байтов нет нигде. Reconciler её - находит и помечает, но не «чинит». - -## Последовательность работ - -Этапы 1–6 — changes OpenSpec, каждый проходит `/opsx:propose` → -`/opsx:apply` → `/opsx:verify` → `/opsx:archive`. Этап 7 — сборка -отчёта, не change. Замеры для отчёта снимаются с закоммиченного кода -(`bench.md`, «Измеренное состояние — commit»). Отчёт пополняется в -каждом change: evidence и строка в таблице доказательств `REPORT.md` — -часть «готово». Возможности лаб 2 и 3 (`bench_restore`, профили -`failover` и `rollout`, серии трека 1, проверки отказов) работают после -каждого change. - -### Сводная таблица - -| № | Change | Уровень | Что происходит | Готово, когда | -|---|---|---|---|---| -| 0 | — (подготовка) | — | этот план; выбор трека и S3-сервера | план сохранён 2026-10-20; трек 2, SeaweedFS, решения 3 и 7 подтверждены 2026-10-20 | -| 1 | `s3-storage` | 3 (+4: bootstrap, права, консоль, приватность) | S3 в стенде, bootstrap, клиент в `src/infra/s3/`, настройки, все стенды знают о S3 | bootstrap дважды без ошибок, анонимный GET / LIST → 403, ключ API не может admin-операций, `make test-persistence` перезапускает и S3; **заархивирован 2026-10-20** — `openspec/changes/archive/2026-10-20-s3-storage/` | -| 2 | `attachments` | 3 (+4: тесты) | миграция, домен `attachment`, ручки, `attachment_ids` в сообщениях, тесты | зелёные `make test`, `test-persistence`, `test-failover`, свой сценарий отказа загрузившей реплики; негативные тесты; evidence исключений переснят; **код — `116d8d3`, гонка `bench_restore` — `d56b892`; evidence 2026-10-20 с `d56b892`: `evidence/attachments/`, исключения, `evidence/tests/` (196 / 191 + 5 пропусков / 23 из 23), `test-failover` для обеих реплик; правки verify — `dba40bc`, после них `student_test` 197 и `failure_checks` 24 из 24, `bench_rollout` `attachments` переснят с `e1f8531` на чистом дереве (8,67 с, ошибок 0, 12 001 = 12 001); заархивирован 2026-10-21** — `openspec/changes/archive/2026-10-21-attachments/` | -| 3 | `upload-consistency` | 4 | намерение до PUT, компенсация, уборщик с grace period, тесты отказов | `make failure_checks` с отказами S3 и БД посреди загрузки: нет 500, нет неучтённых объектов старше grace period; **код — `5b42bd2`; evidence 2026-10-21 с него: `evidence/attachments/consistency.md` и `cleaner-process.md`, `evidence/s3/cleaner-key.md`, `evidence/migrations/pending-index.md`, `evidence/tests/`; `REPORT.md` — раздел «Согласованность БД и S3», ответ на вопрос «PUT прошёл, COMMIT нет», строки уровня «4». Правки по verify (W1–W4, S1) — код `87c48b9`: пометка строки уборщиком до удаления объекта, тесты неизвестного COMMIT, загрузки дольше grace и сбоя уборки после удаления объекта; evidence 2026-10-21 с него: `evidence/tests/` (`failure_checks` 32 из 32, `student_test` 197, сверка 215 / 36, `test_isolated` 192 + 5 пропусков), `cleaner-process.md` раздел 7 (отказ S3 во время прохода); `REPORT.md` — пометка, остаточный риск и окно `rolling_update`. Правки по повторному verify (W1, S1, S2) — код `5889ca2`: уборщик в два шага, объект и строка одной транзакцией под блокировкой, смеси версий не хуже, чем до правки, порядок обновления; evidence 2026-10-21 с него: `evidence/tests/failure-checks.md` (32 из 32 за 228 с), `cleaner-process.md` раздел 7, S2 в `student-test-lb.md` (8 сценариев `storage-consistency`); `REPORT.md` — два шага, «Зачем DELETE объекта под блокировкой», смесь версий; заархивирован 2026-10-21** — `openspec/changes/archive/2026-10-21-upload-consistency/` | -| 4 | `upload-memory` | 4 | лимит загрузок на реплику, сроки тела, профиль `uploads` | замер ≥ 10 одновременных загрузок: пик памяти ограничен, механизм объяснён; **код — `6cab9d3` (места загрузки, срок тела, одна копия тела при PUT, буферы и сроки LB) и `97a4be4` (буфер приёма LB от клиента 128 KiB); метка `evidence/uploads/baseline/` с `97a4be4` (commit `ce1ae2c`, принята с пометкой о swap хоста); evidence 2026-10-22: `evidence/uploads/lb-timeouts.md` и `rollout-upload.md`, `evidence/tests/` (`student_test` 198, `test_isolated` 193 + 5 пропусков); `REPORT.md` — «Память и сроки загрузки», гипотезы H1–H4 и выводы по метке. Правки по verify — код `9d2ee30`: разбор сводки профиля, спеки буфера LB и одной копии тела, срок тела «узкого» API 3 с; evidence с него: `evidence/tests/failure-checks.md` (37 из 37 за 263 с, commit `569a164`); заархивирован 2026-10-22** — `openspec/changes/archive/2026-10-22-upload-memory/` | -| 5 | `track2-reconciler` | 5 | reconciler: dry-run / apply, классы расхождений, внедрение ошибок, доказательство безопасности | ошибки внесены с обеих сторон, обнаружены, исправлены; повторный запуск находит 0; под загрузками ничего подтверждённого не удалено; **код — `c1648d9` (сверка в процессе уборщика, `make reconcile`, плановая сверка, `lost_at` и 404 потерянного оригинала, список по префиксу у ключа уборщика); evidence 2026-10-22 с него: `evidence/reconcile/cycle.md` (6 классов с обеих сторон, повтор 0, возврат оригинала), `stress.md` (640 / 640 с тем же SHA-256 под `--apply`), `service.md`, `evidence/s3/cleaner-list.md` (70 проверок), `evidence/migrations/lost-at.md`, `evidence/tests/` (`failure_checks` 45 из 45 за 462 с и красный прогон 8 из 8 на `c13df14`, `student_test` 198, `test_isolated` 193 + 5 пропусков); `REPORT.md` — «Сверка хранилищ», строки уровня «5», ограничения, ответ «PUT прошёл, COMMIT нет». Правки по verify — код `84f8c35`: строка с ключом вне префикса вложений — чужой объект, сигнал перед каждым вызовом хранилища, hook `set-key`, три новые проверки отказов; evidence 2026-10-22 с него (commit `96d2ecc`): `evidence/tests/failure-checks.md` (48 из 48 за 524 с и красные прогоны группы 13), `student-test-lb.md` (198), `evidence/reconcile/service.md` (`reconcile-signal`); вопрос 1 преподавателю (ответ API на потерянный оригинал) открыт; заархивирован 2026-10-22** — `openspec/changes/archive/2026-10-22-track2-reconciler/` | -| 5а | `fix-upload-put-flake` | 4 (исправление) | причина редких 503 на загрузке (срок чтения aiohttp портил соединение пула S3), правка клиента, тест на стенде отказов, `driver.py s3-idle` | тест красный до правки и зелёный после, `s3-idle` у образа без порчи, восемь `student_test` подряд без 503; **тест — `4cfaab0`, правка — `b5983f0`; evidence 2026-10-22 с `b5983f0`: `evidence/s3/idle-connection.md` (`s3-idle` до и после замены реплик, механизм, проба памяти PUT 1,17 тела, `bench_uploads_quick`), `evidence/tests/failure-checks.md` (49 из 49 за 570 с, красный 3 из 3 на `4cfaab0`), `student-test-lb.md` (8 × 198); запись `KNOWN_ISSUES.md` удалена; полную метку `uploads` не переснимать (пользователь, 2026-10-23)** | -| 6 | `track2-reconcile-cost` | 5 | гипотезы, профиль стоимости обхода, стратегии, графики | метки в `evidence/`, выводы по гипотезам и ограничения в `REPORT.md`; **код — `8d4cf7e` (`--strategy head`, `--deep` и класс «другой SHA-256», снятие пометки по SHA-256, предел скорости `[reconciler] max_objects_per_second` 2000, ранний отказ по пределу, стоимость в итоге, профиль `reconcile` стенда `bench/`); гипотезы H1–H4 и ожидание S4 — `aaf3fa3`, до метки; правки проверки строк k6 — `a42dd27`, `d8b8ae3`; метка `evidence/reconcile/baseline/` — `0072dbe` (с `d8b8ae3`, 51 проход, `dirty: false`, хост чистый): H1, H2, H3 и S4 подтверждены, H4 не проверена (контраст r 1,08 при пороге > 1,5); evidence 2026-10-23 с `0072dbe`: `evidence/tests/failure-checks.md` (54 из 54 за 712 с и красный прогон 5 из 5 на `7f4e626`), `evidence/reconcile/service.md` (`reconcile-signal --pace`: код 1 за 0,2 с), `make test_isolated`, `make student_test` 198; `REPORT.md` — «Стоимость сверки: результаты метки `baseline`», «Сверка хранилищ», строки уровня «5», ограничения** | -| 7 | — (отчёт и PR) | 3–5 | сводка `REPORT.md`, чистый clone, шаблон PR, уборка этого файла | PR `ЛР 4 — БВТ2301 — Сафронов — на 5` | - -### 1. `s3-storage` — уровень 3, +4 - -**Пункты рубрики.** -- «3»: S3 в общем стенде, persistent volume, закреплённая версия, - создание приватного bucket описано. -- «4»: bootstrap идемпотентен; отдельные credentials API с - ограниченными правами; консоль не в общей сети; проверка приватности - вне API. - -**Стенд.** -- Сервис S3: тег с версией и digest индекса (`docker.md`), named - volume, healthcheck, лимиты CPU / RAM, `restart: unless-stopped`. -- Одноразовый bootstrap (как `migrate`): bucket, запрет анонимного - доступа, пользователи API и уборщика. Реплики ждут его - `service_completed_successfully`. -- Окружение по сервисам: root — только bootstrap; ключи API — только - `api`; LB и `migrate` S3-секретов не получают. -- `.env.example`, `make env_setup` (генерация паролей S3), строки в - `config_example.toml`. -- `scripts/restart.sh` перезапускает и S3; стенды `bench/` - (`bench.compose.yml`), `make test_isolated` (свой bucket или prefix - по имени базы, как ключи Valkey) и `make failure_checks` (свой S3) - знают о новом сервисе. - -**Код.** -- `src/infra/s3/`: фабрика клиента и глобал по образцу - `cache/instance.py`, срок на каждый вызов, ошибки → доменные - исключения (отказ → 503). Библиотека — решение design: aiobotocore - (асинхронный, тянет закреплённый botocore) или boto3 в потоке. -- Секция `[s3]` в `Settings`, мосты `S3__*`. -- `/health/ready` — по решению 3. - -**Спеки (дельты).** Новая `object-storage` (bucket, приватность, -права, bootstrap); `container-run` (S3 в стенде, restart hook); -`service-configuration` (`[s3]`); `health` (S3 не критичен для -готовности); `service-logging` (ключи и подписи не логируются). - -**Правила.** S3 — в `infra.md`, `docker.md`, `settings.md`; AGENTS.md -(карта кода, таблица команд). - -**Evidence:** `evidence/s3/` — bootstrap дважды, анонимные GET и LIST -→ 403, ключ API против admin-операций и чужого bucket, `docker compose -ps` без опубликованных UI-портов, `test-persistence` с рестартом S3. - -### 2. `attachments` — уровень 3, +4 (тесты) - -**Пункты рубрики.** Все пункты «3» о вложениях; «4» — негативные -тесты. - -**Код.** -- Миграция: таблица вложений (чат, владелец, `filename`, - `content_type`, размер, SHA-256, ключ объекта, статус, время) и связь - сообщения с вложениями с порядком. Только расширение схемы - (`migrations.md`). -- Ручки: `POST /chats/{chat_id}/attachments?filename=…`, - `GET /attachments/{id}`, `GET /attachments/{id}/content` (поток из - S3, истинный `Content-Type`, без redirect, `variant` только - `original`). -- Проверки upload по решению 4; ошибки: 400 (`filename`, UUID), 413 - (байты, пиксели), 415 (формат, повреждение, подмена MIME), 404 - (чужой чат), 503 (S3). -- Сообщения: `attachment_ids` 0–10 уникальных `UuidIn`, пустой текст с - вложением, чужое / неизвестное / другого чата → 404; история и - повтор отдают `attachment_ids`; хэш — решение 6. -- Драйвер скилла `run-mtusi-messenger`: upload / download / SHA-256 и - сценарий «остановить реплику, принявшую файл». - -**Тесты** (`student-tests/test_attachments.py`, маркеры `spec`): -PNG и JPEG; 413 по байтам и по пикселям (маленький файл с огромными -размерами в заголовке); 415 на обрезанный файл, на текст с -`image/png`, на JPEG с `image/png`; `filename` с `/`, `\`, NUL, -управляющими символами — 400; чужое и неизвестное `attachment_id`, -вложение другого чата — 404; посторонний — 404 на метаданные и -content; ни одна ошибка не 500; идемпотентность с `attachment_ids`. -Большие и «бомбы» генерируются в тесте, в git не кладутся (README -fixtures). - -**Свой сценарий отказа.** Публичный `make test-failover` останавливает -реплику, ответившую на первое *сообщение*, а не на upload. Рубрика -требует остановить именно принявшую файл: upload через LB → -`stop-one.sh` по её `X-Instance-Id` → download через другую → тот же -SHA-256. - -**Переход в лабу 4.** Переснять четыре файла исключений сверки на -стенде лабы 4: `evidence/cache/hits.md`, -`evidence/auth/passwords-and-tokens.md`, -`evidence/replicas/test-persistence.md`, -`evidence/idempotency/replay-after-restart.md`. - -**Спеки (дельты).** Новая `attachments`; `messages` (`attachment_ids`, -пустой текст); `idempotency` (хэш); `data-storage` (байты в S3); -`student-tests`. - -**Evidence:** `evidence/attachments/` (smoke, download другим -участником, 404 постороннему, отказ загрузившей реплики), -`evidence/tests/`. - -### 3. `upload-consistency` — уровень 4 - -**Пункт рубрики.** Прерывание загрузки и отказ между S3 и БД не -оставляют вечных неучтённых объектов; механизм с grace period описан. - -**Код.** -- Намерение до PUT (решение 2), компенсация при ошибке после PUT - (удаление объекта, без гарантии — её даёт уборщик). -- Уборщик (решение 7): `pending` старше grace period → `DELETE` - объекта (идемпотентно, отсутствие — не ошибка) → удаление строки. - Grace period больше максимального времени загрузки с запасом на - часы; значения — настройки. - -**Тесты отказов** (`make failure_checks`, новые действия -`fault_hook.py`): S3 остановлен и заморожен до и во время PUT; отказ -вставки строки после PUT (триггер, как `fail-messages`); kill реплики -посреди загрузки; обрыв клиента посреди тела. Итог каждого: нет 500, -`pending` убран уборщиком после grace period, объектов без строки нет. -Ещё — невидимость `pending` через API (замечание verify `attachments`, -S6; спек `attachments`, «Порядок записи»): действие hook с id последней -строки `pending` (после «Запись в S3 не удалась»), по нему метаданные, -байты и сообщение со ссылкой — 404 до уборки. - -**Спеки (дельты).** `attachments` (сбои загрузки), новая или в -`object-storage` — уборка. - -**Evidence:** `evidence/attachments/consistency.md`, вывод -`make failure_checks`; раздел `REPORT.md` с порядком записи. - -### 4. `upload-memory` — уровень 4 - -**Пункт рубрики.** Лимиты, таймауты и потоковая обработка не дают -одной загрузке занять неограниченную RAM; эксперимент ≥ 10 -одновременных загрузок с замером пика памяти. - -**Код и стенд.** -- Лимит одновременных загрузок / декодирований на реплику; что видит - клиент при превышении — решение design (ожидание с таймаутом или - ответ с `Retry-After`). -- Сроки чтения тела в API и HAProxy, цепочка таймаутов для upload - (решение 4). -- Профиль `uploads` стенда `bench/`: 1 / 10 / 20 / 40 одновременных - загрузок по 1 и 10 MiB, `memory.peak` cgroup реплики и сэмплер, - p95, ошибки по кодам. Варианты «без лимита» и «с лимитом». - -**Гипотеза.** Пик памяти реплики ≈ база + K × (буфер тела + -декодирование), где K — лимит одновременных загрузок; без лимита пик -растёт с конкуренцией до OOM-kill. - -**Evidence:** `evidence/uploads/<метка>/`, выводы и ограничения в -`REPORT.md`. - -### 5. `track2-reconciler` — уровень 5, трек 2 - -**Пункт рубрики.** Повторяемый reconciler для orphan / missing -объектов и метаданных; ошибки на обеих сторонах; обнаружение и -безопасное исправление с dry-run и повторным запуском; свежие и -используемые вложения не удаляются. - -**Код.** -- Обход LIST bucket и БД (keyset), классы: объект без строки, - зависший `pending`, строка `ready` без объекта, другой размер. -- Режимы `--dry-run` (отчёт: класс, ключ, возраст) и `--apply`; - повторный запуск после прерванного `apply` доводит работу, - следующий находит 0. -- Безопасность: grace period по времени объекта и строки; перепроверка - строки в БД непосредственно перед удалением объекта; объекты, - на которые ссылаются сообщения, не удаляются никогда. -- Строка без объекта — что видит API (решение design: метка в БД, - ответ content), байты не восстановить. - -**Внедрение ошибок** (`fault_hook.py`): объект в bucket мимо API, -удалённый объект, удалённая или изменённая строка, обрыв загрузки -посередине. - -**Доказательство безопасности.** Reconciler `--apply` под -одновременными загрузками и отправками; затем каждое подтверждённое -вложение скачивается с тем же SHA-256. - -**Evidence:** `evidence/reconcile/` — dry-run, apply, повтор = 0, -стресс. - -### 6. `track2-reconcile-cost` — уровень 5, трек 2 - -**Пункт рубрики.** Гипотеза, повторяемая методика, результаты и -ограничения; измерить стоимость обхода. - -**Стенд `bench/`.** Профиль `reconcile` по методике раздела «Трек 5»: -наполнение N объектов с долей расхождений, стратегии (батч против -`HEAD`, поверхностная против глубокой), фоновая нагрузка k6, сэмплер, -3 повтора и A/A. - -**Evidence:** `evidence/reconcile/<метка>/`, графики (`make -bench_plots` или его аналог), выводы по гипотезам 1–5 и ограничения в -`REPORT.md`. - -**Передано из verify `track2-reconciler` (замечание S4).** При массовом -расхождении (N ≫ `max_changes`) `--apply` перепроверяет каждого -кандидата (SELECT + HEAD) и только потом отказывает по пределу; плановый -проход всё это время держит уборку зависших. Ранний отказ ломал бы -инварианты отчёта (каждое расхождение названо, ошибка называет число -изменений), поэтому там не сделан (design `track2-reconciler`, -«Уточнения apply», п. 21). Здесь — замер цены отказа при N = 1k / 10k -расхождений и выбор: перепроверка после решения о пределе с отчётом о -неперепроверенных кандидатах, отдельный счётчик в итоге или ранний отказ -только у плановой сверки. - -### 7. Отчёт и PR - -- `REPORT.md`: запуск из чистого clone, архитектура и транзакционные - границы, соответствие переменных skeleton, таблица доказательств, - эксперименты, ответы на вопросы защиты, согласования с - преподавателем, ИИ и источники. -- Проверка из чистого clone, `make check`, `make test` на собранном - образе, шаблон PR. Этот файл удаляется. - -## Риски - -- Декодирование больших изображений в лимите памяти реплики - (решение 4) — главный технический риск лабы. -- Совместимость выбранного S3-сервера: идемпотентный bootstrap, права, - поведение при рестарте. Проверяется до выбора в design `s3-storage`. -- Медленная загрузка 10 MiB против цепочки таймаутов лабы 3 - (`timeout server`, `timeout client`, срок запроса к БД). -- Доказательство «ничего свежего не удалено» требует настоящих гонок, - а не последовательного сценария. -- Объём `bench/`: новые профили `uploads` и `reconcile` не должны - ломать прежние (`bench_restore`, `failover`, `rollout`, серии). - -## Вопросы и решения по ходу changes - -Файл вопросов цикла OpenSpec: на каждый change — раздел `### ` -с подразделами «Решения» (принятые без пользователя, со ссылкой на -design) и «Вопросы» (ждут ответа; ответ дописывается рядом с датой). -При удалении плана открытые вопросы переносятся в `REPORT.md`. - -### s3-storage - -#### Решения - -Приняты 2026-10-20 в `/opsx:propose`, подробности — design change -`s3-storage`. - -1. **SeaweedFS прошёл пробу** на стенде вне репозитория (design, - Context), RustFS не понадобился. Проверены: идемпотентность bucket и - пользователя, анонимные запросы, права ключа API, healthcheck, - рестарт с volume, `kill -9`, память, клиент. Образ — - `chrislusf/seaweedfs:4.48@sha256:4e61d15f…`. Команды `s3.configure` - из решения 1 выше в 4.48 нет, вместо неё IAM-команды `s3.user.*` и - `s3.policy*` (решение 4). -2. **Три места, где SeaweedFS по умолчанию не приватен** (решения 1, 3): - - без учётных записей S3 открыт анониму → административная пара в - окружении сервера с первого старта; - - master, filer и volume слушают все интерфейсы → - `-ip.bind=127.0.0.1`, в сеть выходит только шлюз S3; - - gRPC-порт шлюза без ключа подписи принимает от любого контейнера - учётную запись администратора (воспроизведено) → обязательный - `S3_JWT_SIGNING_KEY`. - - Выключены ещё телеметрия, Iceberg, Lance и встроенный IAM API. -3. **Root по решению 5 выше** (решение 3). Административную пару - хранит только сервер `s3`: без неё S3 открыт. Bootstrap работает не - ею, а `weed shell` на loopback сервера с ключом подписи. У API и - будущего уборщика административной пары нет. -4. **Права API** — политика `s3:GetObject`, `s3:PutObject`, - `s3:DeleteObject` на `/*`, у bucket нет владельца (решение - 3). Пользователь уборщика появится в `upload-consistency`. -5. **Bootstrap** — сервис `s3-bootstrap` с `network_mode: service:s3` - (решение 4): - - сводит состояние к `.env`, в том числе новый секрет API; - - сам проверяет приватность при каждом запуске; - - `make s3_check` — те же проверки с хоста и из сети (решение 8). -6. **Отдельной сети для S3 нет**: служебные порты закрыты loopback и - ключом подписи (решение 1). -7. **Клиент** — aiobotocore 3.9.2 (решения 6, 7): - - без повторов, срок на каждый вызов; - - отказ, таймаут и отказ в учётных данных — 503; - - ключи объектов с префиксом имени базы. - - Отвергнуты boto3 в потоке, aioboto3, своя подпись, obstore и - minio-py. -8. **Память S3** (решение 2): лимит 512 МБ, `GOMEMLIMIT=400MiB` и - `-s3.concurrentUploadLimitMB=64`. Без них 20 одновременных загрузок - по 10 MiB дают OOM-kill. Числа уточняет `upload-memory`. -9. **Остановка и перезапуск** (решения 1, 2): - - `stop_grace_period: 20s` — плавная остановка SeaweedFS занимает - ~15 с, срок зашит в filer; на стенде отказов — 2 с; - - `-master.electionTimeout=1s` — перезапуск ~7 с вместо ~24 с. -10. **Стенды** (решение 9): - - `test_isolated` — S3 рабочего стенда, префикс `test_/`, - уборка через `fs.rm`; - - `failure_checks` — свой S3 и проверка готовности без него; - - `bench/` — секреты на прогон и фильтр секретов в паспорте; - профили лаб 2–3 S3 не запускают, методика прежняя; - - `rolling-update.sh` bootstrap не запускает: bootstrap, как - миграции, только расширяет права. -11. **Проверка рестарта без публичного теста** (design, Context; - решение 9). Публичные `make test`, `test-persistence` и - `test-failover` с `LAB=4` загружают вложение и до `attachments` - красные. Поэтому рестарт hook-ом проверяется напрямую: `StartedAt`, - «exists» bootstrap, объект с тем же SHA-256. - -Приняты 2026-10-20 в `/opsx:apply`, подробности — design change -`s3-storage`, «Уточнения apply». - -12. **`make start_s3` — два шага**: `up -d --wait s3`, затем `up - --no-deps --exit-code-from s3-bootstrap s3-bootstrap`. `--wait` не - ждёт завершения одноразового сервиса (compose v5.5.1), вопреки - пробе propose. Так же — `run_failures.py`. -13. **Bootstrap — режимы `apply`, `check`, `cleanup`**: проверки с хоста и - из сети идут между записью проверочного объекта и его удалением. - Новый секрет API распознаётся по `SignatureDoesNotMatch`. -14. **Клиент**: `open()` читает тело блоками, срок — на каждый блок; - ключи в botocore передаются всегда, даже пустые. -15. **Ожидаемо красные шире списка tasks**: контракт лабы 4 требует - `attachment_ids` в `Message`, код лабы 3 его не отдаёт — до - `attachments` красные 32 теста (и 2 ошибки) `make student_test` - через LB (в `make test_isolated` — 29 и 2) и 5 проверок `make - failure_checks`. От S3 не зависит. -16. **Дельта `health` синхронизирована в основной спек в apply**, как в - `scaling-bench`: иначе маркер нового сценария — ссылка на - неизвестный сценарий в сверке покрытия. -17. **`rollout_from c50b721` — дефект переноса** (`KNOWN_ISSUES.md`): - профиль `rollout` проверен с `--from 5d5d8f9`. - -Приняты 2026-10-20 в правках по `/opsx:verify` (tasks.md, группа 7), -подробности — design change `s3-storage`, «Уточнения apply», п. 8–13. - -18. **Healthcheck S3 ждёт регистрации тома** (`/dir/status`, непустой - `DataNodes`): первая запись после рестарта — 10–40 мс вместо до - 4,8 с при сроке 5 с. Та же проба — в `fault_hook.py`. -19. **`tmpfs: [/tmp, /data]` у `s3-bootstrap`**: без анонимного volume на - каждый контейнер. -20. **Клиент S3**: удалённый bucket и отказ в доступе — 503 с `error` - («bucket is missing», «denied access»), а не «объекта нет» и не - «rejected credentials»; `delete` глушит только отсутствующий ключ. - Ограничение: HEAD без тела, удалённый bucket у `head` — `None`. -21. **`make test_isolated` проверяет уборку префикса** (`fs.ls` после - `fs.rm`): код 0 `weed shell` успеха не значит. -22. **`make s3_check` берёт порты из `netstat` контейнера S3**, а не из - фиксированного списка; проверка готовности без S3 — и для `pause`. - -#### Вопросы - -1. Как в apply добавить строки S3 в рабочий `.env`? Агент `.env` не - читает, а `make env_setup` существующий файл не меняет (правило - `settings.md`). Варианты: - - (а) пользователь сам переносит блок из `.env.example` и - генерирует секреты, как было с Valkey; design исходит из этого; - - (б) агент с согласия пользователя: значения `openssl rand` попадут - в журнал сессии; - - (в) научить `make env_setup` дописывать недостающие переменные - шаблона со сгенерированными секретами в существующий `.env`. Это - меняет правило `settings.md` и спек `container-run` не нарушает: - существующие значения не перезаписываются. - - **Ответ 2026-10-20 (основная сессия, по факту):** в рабочей копии - лабы 4 `.env` ещё нет. Его создаст `make env_setup` из обновлённого - `.env.example` вместе с секретами S3, переносить нечего. Для уже - существующего `.env` остаётся (а), как в design; (в) — только по - просьбе пользователя. -2. `attachment_ids` отсутствует в ответах Message (код лабы 3), и - поэтому до change `attachments` красные 32 теста `make student_test` - и 5 тестов `make failure_checks` (решение 15). Добавлять ли пустой - список раньше? - - **Ответ пользователя 2026-10-20:** нет, красное до `attachments`. - Поле приходит целиком в `attachments` (запрос, ответ, хэш - идемпотентности), там же evidence тестов переснимается зелёным. -3. Когда чинить `rollout_from c50b721` (решение 17, `KNOWN_ISSUES.md`)? - - **Ответ пользователя 2026-10-20:** в change `attachments`: он - добавляет миграцию, и rollout со старого образа на новую схему — нужное - evidence. До тех пор запись остаётся в `KNOWN_ISSUES.md`. -4. HEAD при удалённом bucket даёт `None`, как отсутствующий ключ: - SeaweedFS отвечает на HEAD одним и тем же 404 без тела (решение 21, - design «Уточнения apply» п. 10). Нужен ли лишний GET `Range: - bytes=0-0` на каждый промах, чтобы их различить? - - **Ответ основной сессии 2026-10-20:** нет, ограничение принято. - Удалённый bucket видят `put`, `open` и `delete` (503), а также - bootstrap и `make s3_check`. Лишний запрос на каждый промах не нужен. - Правило для следующих changes: промах `head` не основание для - разрушающего решения (удалить строку, пометить вложение потерянным) - без проверки, что bucket на месте. Это учитывают `upload-consistency` - и reconciler трека 2. - -### attachments - -#### Решения - -Приняты 2026-10-20 в `/opsx:propose`, подробности — design change -`attachments`. - -1. **Строка `pending` до PUT — уже здесь** (решение 1). Порядок: - проверки → `pending` с ключом объекта (commit) → PUT → `ready` - (commit) → 201. При отказе S3 или БД после шага `pending` — 503, - строка остаётся. `upload-consistency` добавит компенсацию, уборщик и - тесты отказов посреди загрузки, порядок шагов не меняя. -2. **Проверка изображения — структура без декодирования** (решение 2), - своя функция на stdlib: - - PNG: CRC чанков, поток IDAT распаковывается ровно в объём по - размерам, типы фильтров строк; - - JPEG: маркеры, один кадр, скан, EOI; - - пиксели — из заголовка до распаковки. - - Проба: 12 000 настоящих файлов без ложных отказов, память проверки - до 3,5 MiB, «бомба» отсекается за доли миллисекунды. Pillow — только - dev-группа, для JPEG в тестах. Поведение для клиента подтвердил - пользователь («Вопросы», п. 1). -3. **Схема** (решение 3): - - таблицы `attachments` и `message_attachments` — порядок - `position`, FK без каскада: вложение со ссылкой из сообщения БД - удалить не даст; - - ограничение текста сообщения ослаблено до 0–4000 с `NOT VALID`, - без скана `messages` под эксклюзивной блокировкой (дельта - `db-migrations`); - - чат вложения = чат сообщения проверяет сервис в той же транзакции. - - Отвергнуты массив id в `messages`, составной FK с третьим индексом - на `messages` и тип `ENUM`. -4. **Ключ объекта** — `<база>/attachments//original`, хранится в - `object_key` (уникальный) (решение 4). -5. **Загрузка и скачивание не держат сессию БД** (решение 5). Найдено: - `get_db_session` держит соединение пула и срок 6 с до конца отправки - ответа, и передача 10 MiB медленному клиенту оборвалась бы на 6-й - секунде. Поэтому: - - `db_session_scope()` на каждый шаг с БД; - - вход `CurrentUserBrief` с короткой сессией; - - `AttachmentService(db_scope, cache, storage)`. -6. **Ответы до чтения тела** (решение 6, проба). Ранние 404, 413 и 415 - получают httpx, curl и любой клиент через LB. `urllib` напрямую к - одной реплике ответ теряет — ограничение в `REPORT.md`. Медленные - 10 MiB через LB проходят: таймауты HAProxy — простой, а не длительность. -7. **Порядок проверок загрузки**: 401 → 400 → 404 → 415 (`Content-Type`) - → 413 (`Content-Length`) → тело (спек «Порядок проверок загрузки»). -8. **Скачивание** (решение 7): - - поток из S3, отказ S3 — 503 до заголовков; - - заголовок `X-Content-Type-Options: nosniff`; - - `variant` кроме `original` — 400 по перечислению контракта лабы 4; - - строка `ready` без объекта или с другим размером — 500 и `error` - в журнале, строка не меняется. -9. **Хэш идемпотентности** (решение 9): пустой `attachment_ids` хэш не - меняет, id в нижнем регистре, порядок значим. -10. **Лимиты 10 MiB и 40 млн пикселей — константы, не настройки** - (дельта `service-configuration`), соответствие `MAX_UPLOAD_BYTES` и - `MAX_IMAGE_PIXELS` — в `REPORT.md`. -11. **`rollout_from = e1161f7`** — последний commit лабы 4 до этого - change (решение 14). Проверка commit до стенда, правило — в - `bench.md`, запись в `KNOWN_ISSUES.md` удаляется в apply. -12. **Дельты синхронизируются в основные спеки в apply**, как `health` - в `s3-storage`: сверка покрытия читает только `openspec/specs/`. -13. **Проверки отказов вложений** — через hook стенда отказов: счётчики - вложений по статусам и объектов в bucket (решение 12). - -Уточнения apply (2026-10-20/21, design change `attachments`, «Уточнения -apply»): - -14. **Текст из пробелов с вложением — 201** по ответу преподавателя - («Вопросы», п. 2); без вложений — 400. Текст не нормализуется. -15. **Проверка изображения на готовом модуле** повторила пробу: 17 - вариантов, корпус 12 000 файлов без ложных отказов, «бомба» за 1 мс, - пик памяти ≤ 3,2 MiB. Вход IDAT — кусками по 64 KiB. -16. **План истории**: на пустой `message_attachments` стенда `bench/` - `SubPlan` — `Seq Scan` пустой таблицы; с данными — - `pk_message_attachments`, индекс истории прежний. -17. **`variant` в `/openapi.json`** — `enum ["original"]` через - `json_schema_extra`: Literal pydantic пишет `const`. -18. **`bench_restore_quick` падал** из-за гонки стенда (реплика - пересоздаётся с тем же IP, LB держит устаревший `UP`), не из-за - вложений. **Решение основной сессии 2026-10-21: чинить в этом - change** — возможности лаб 2–3 (`bench_restore`) должны работать - после каждого change, а 7.2 — задача `attachments`. `switch_api` ждёт - готовности процесса новой реплики изнутри контейнера, затем `UP` в - LB (design, «Уточнения apply», п. 9); запись `KNOWN_ISSUES.md` - удалена. - -Замечания `/opsx:verify` 2026-10-21 (все приняты, tasks группа 10; -design, «Уточнения apply», пп. 10–15): - -19. **Память загрузки — одно тело, а не два.** Тело копится в - `io.BytesIO`, `getvalue()` отдаёт `bytes` без копии (`bytearray` - botocore копирует). В образе — `MALLOC_MMAP_THRESHOLD_=131072`: с - динамическим порогом glibc вторая загрузка росла в куче, и `realloc` - на миг держал два тела. Замер в образе: RSS 1,99 → 1,19–1,20 тела на - каждой из трёх загрузок подряд. Буфер под `Content-Length` заранее - не выделяется: заявивший 10 MiB клиент держал бы их без передачи. -20. **«Бомба» распаковывается до ожидаемого объёма + 1 байт**, а не до - 1 MiB: предел блока zlib — остаток ожидаемого плюс байт. Корпус - 11 993 файлов — вердикты те же. -21. **«Старый образ на новой схеме»** переформулирован: проверки, которые - прежний образ проходил на прежней схеме, проходят и на новой; - доказательство — замер `rollout` (переснять с чистого дерева после - commit правок). -22. **`filename` не в UTF-8 — 400** (`a%FFb.png` давал 201 с U+FFFD): - ручка строго разбирает строку запроса, новый сценарий «Имя не в - UTF-8». -23. **«Окружение не меняет лимит»** проверяет тест `fault`: обычный API - стенда отказов — с `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1`. -24. **Мёртвые константы** `MESSAGE_TEXT_MIN_LENGTH` и - `ATTACHMENT_READ_CHUNK_BYTES` удалены: блок чтения задаёт uvicorn. -25. **Невидимость `pending` через API** (S6) — не здесь: задача - `upload-consistency` (раздел «Последовательность работ», п. 3). - -#### Вопросы - -1. Что считать «повреждённым изображением» (решение 2, спек - `attachments`, «Повреждённое изображение»)? По умолчанию — - структурная проверка без декодирования пикселей: - - 415 — обрезанный файл, битая CRC, сломанные маркеры, поток zlib не - того объёма, «бомба»; - - байты после IEND или EOI принимаются как часть оригинала; - - изменённый байт внутри данных скана JPEG не ловится. У формата нет - контрольной суммы, Pillow его тоже не ловит. - - Альтернатива — полное декодирование Pillow. Оно стоит до 160 МБ на - загрузку при лимите реплики 512 МБ, требует семафора уже в этом - change и ловит не больше. - - **Ответ пользователя 2026-10-20:** структурная проверка, как по - умолчанию. Менять ничего не нужно. -2. Текст из одних пробелов вместе с вложением. По умолчанию — 400: общее - правило контракта «обязательные строки не состоят только из - пробельных символов», а исключение названо только для `text=""`. - Фраза «нельзя пустой/пробельный текст без вложений» допускает и - прочтение «с вложением можно». Это две трактовки контракта, то есть - вопрос преподавателю (AGENTS.md). - - **Ответ пользователя 2026-10-20:** пока 400, как по умолчанию. Это - неоднозначность контракта: `contracts/README.md`, строка 18 («нельзя - … пробельный текст без вложений») против строк 9 (обязательные строки - не из одних пробелов) и 50 (исключение — только `text=""` с - вложением). Пользователь спросит преподавателя. - - **Ответ преподавателя 2026-10-20 — вопрос закрыт.** «Пустой текст» — - это и `""`, и текст только из пробельных символов. Допустимы: - вложение + непустой текст, без вложения + непустой текст, вложение + - пустой текст. Итог: текст из одних пробелов с хотя бы одним - вложением — 201 (текст сохраняется и возвращается как прислан), без - вложений — 400. Записано в AGENTS.md, «Согласования с - преподавателем»; в apply поправлены валидатор `CreateMessage`, - сценарий `messages` «Пробелы с вложением» и его тест (design change - `attachments`, решение 8), в `REPORT.md` — как согласование. -3. Опасный `filename`. Контракт называет `/`, `\`, NUL и управляющие - символы. По умолчанию 400 и на символы управления направлением - текста (U+202A–U+202E, U+2066–U+2069) и разделители строк (U+2028, - U+2029): ими подменяют видимое имя (например, U+202E перед - `gnp.exe`). ZWJ и остальные форматирующие разрешены: на них держатся - emoji и письменности. Оставить так? - - **Ответ пользователя 2026-10-20:** нет, только то, что в контракте: - 400 на `/`, `\`, NUL и управляющие символы — категория Unicode Cc - (U+0000–U+001F, U+007F–U+009F). Символы направления текста, - разделители строк U+2028 и U+2029 и прочие символы категорий Cf, Zl и - Zp принимаются и возвращаются без изменений. Спеки `attachments`, - design (решения 3 и 10) и tasks приведены к этому, отвергнутый вариант - с причиной — в design, решение 10. - -### upload-consistency - -#### Решения - -Приняты 2026-10-21 в `/opsx:propose`, подробности — design change -`upload-consistency`. Пробы — design, Context. - -1. **Компенсация — только удаление объекта и только при известном - исходе** (решение 1): - - PUT подтверждён, а `ready` не зафиксирован до отправки COMMIT, или - строку уже убрал уборщик — объект удаляется до ответа 503; - - исход COMMIT неизвестен — объект не трогается; - - после неудачного PUT компенсации нет: при замороженном S3 ответ - стал бы 10 с, а позднего объекта по пробе нет (тело не уходит без - ответа сервера); - - строку компенсация не удаляет, её убирает уборщик. - - `mark_ready` → `None` — 503 вместо 500. -2. **Уборщик — сервис `cleaner`, `python -m src.cleaner`** (решение 2): - - свой engine (пул 1) и клиент S3, цикл с интервалом, `--once`; - - SIGTERM — довести текущий шаг строки и выйти с кодом 0; - - healthcheck образа выключен; - - в консоли (`make run_dev`) уборщика нет. -3. **Проход** (решение 3): строка под `FOR UPDATE SKIP LOCKED` → DELETE - объекта → DELETE строки → commit. Блокировка упорядочивает уборщика и - `mark_ready` загрузки, пережившей grace. Остаток риска: API заморожен - дольше grace посреди PUT — объект без строки, его находит сверка - трека 2. После verify — пометка строки отдельной транзакцией до - DELETE объекта (решение 18 ниже), после повторного — объект и строка - одной транзакцией под блокировкой (решение 23). -4. **Grace 900 с, интервал 60 с, выборка 100** (решение 4): - - граница живой загрузки от строки до `ready`: B = 2 × 6 + 5 = 17 с, - запас ×50; - - при grace ≤ B уборщик не стартует; - - стенд отказов — 20 с и 1 с. -5. **Права уборщика в S3** (решение 8) — `s3:GetObject` и - `s3:DeleteObject` на объекты своего bucket, как задано пользователем - («чтение/удаление»). Чтение пока не используется: HEAD не нужен, это - задел глубокой сверки трека 2. List — в `track2-reconciler`, если - понадобится. Проба: одного Delete хватает, DELETE отсутствующего — - 204, удалённого bucket — `NoSuchBucket` (503). -6. **Частичный индекс строк `pending` по `(created_at, id)`** — - `CONCURRENTLY` в `autocommit_block` (решение 6). Проба с асинхронным - `env.py` прошла: с нуля, повтор, откат. -7. **Общий `session_scope` в `src/infra/db/`** для API и уборщика - (решение 7). -8. **Hook — списки `id` вместо счётчиков** (решение 10): - - SeaweedFS убирает пустой каталог `/` лишь через ~2 мин после - DELETE, а уборщик меняет счётчики параллельно с тестами. Объекты - считаются по файлам `original`; - - новые действия: `attachment-ids`, `last-pending` (замечание S6), - `object-ids`, `fail-attachments insert|ready|stall`, `kill-api` и - `start-api`. Отказ триггера — SQLSTATE `08006`, для API это 503 - (проба). -9. **Тесты отказов** (решение 10): - - пять новых тестов и три изменённых, `make failure_checks` дольше - ~2 мин; - - «реплика убита» — между PUT и фиксацией (задержка в триггере), а - не во время PUT: так проверяется ровно «PUT прошёл, COMMIT нет». -10. **`restart.sh` и `rolling-update.sh` не меняются** (решение 9): - рестарт хранилищ уборщик переживает сам, новый код уборщика — - `docker compose up -d --no-deps cleaner`. -11. **Для `upload-memory`.** Ожидание между `pending` и `ready` (очередь - загрузок) расширяет границу B. Проверку grace и решение 4 design - `upload-consistency` обновить в том же change. - -Приняты 2026-10-21 в `/opsx:apply` (подробности — design, «Уточнения -apply»): - -12. **`make env_setup` дописывает в существующий `.env` недостающие - переменные шаблона** (ответ на вопрос 1): секреты — случайными, - остальные — значениями шаблона, прежние строки не меняются, в вывод - — только имена. Правило `settings.md` и дельты - `service-configuration` / `container-run` обновлены (новый сценарий - «Недостающие переменные в существующем `.env`»). -13. **Статус в запросах уборщика — константа** (`literal_execute`): - общий план asyncpg иначе не взял бы частичный индекс. План — `Index - Scan` по `ix_attachments_pending_created_at`. -14. **SIGTERM посреди прохода** — `stop_requested` у - `clean_stale_pending`: текущий шаг строки доводится до commit или - отката, новые не начинаются (после решения 19). -15. **Неверные настройки уборщика** — запись без значений полей и код 2, - а не traceback. -16. **`entrypoint` у сервиса `cleaner`**, чтобы `docker compose run - --rm --no-deps cleaner --once` передавал флаг уборщику. -17. **Красный прогон** новых тестов отказов против прежнего кода: 4 из - 11 упали (компенсация и уборка), остальные закрепляют уже - выполнявшееся поведение. Полный `make failure_checks` — 29 passed, - ~3,5 мин. - -Приняты 2026-10-21 в правках по verify (решения основной сессии; -design, «Уточнения apply», п. 16–20; tasks, группа 11): - -18. **W1 — пометка строки до удаления объекта** вместо одной транзакции - уборщика: блокировка → `updated_at = utcnow()` → commit; DELETE - объекта; блокировка → DELETE строки → commit. `mark_ready` — только - при `updated_at = created_at`. Без миграции. Откат транзакции - уборщика после удачного DELETE в S3 больше не даёт `ready` без - объекта. Остаток — окно `make rolling_update` (прежние реплики и - уборщик) и объект без строки, если зомби дописал объект после - уборки, а компенсация не удалась. -19. **SIGTERM уборщика — между шагами строки**: три шага удлинили бы - худшую остановку до 17 с (после решения 23 шагов два — до 12 с); - доводится только текущий шаг (≤ 6 с). - Требование `graceful-shutdown` «Остановка уборщика» уточнено. -20. **W2, W3 — режимы hook `commit` и `outlive`** и тесты веток «исход - COMMIT неизвестен» и «строку убрал уборщик до `ready`»; W1 — режим - `undeletable`. Ожидание перевода в `ready` — триггер `BEFORE UPDATE - OF status` уровня оператора: пометку уборщика он не задерживает. -21. **Новые сценарии** — «Исход фиксации неизвестен» (`attachments`), - «Загрузка дольше grace» и «Сбой уборки после удаления объекта» - (`storage-consistency`), в дельтах и основных спеках. -22. **W4 и S1** — evidence «Отказ S3 во время прохода» с закоммиченного - кода; `docker.md` — `entrypoint` уборщика. - -Приняты 2026-10-21 в правках по повторному verify (решения основной -сессии; design, «Уточнения apply», п. 21; tasks, группа 12): - -23. **W1 повторной проверки — два шага вместо трёх**: транзакция - пометки, затем объект и строка одной транзакцией под блокировкой - (как в `f2dc0b3`, но на помеченной строке). В решении 18 объект - удалялся без блокировки, и реплика до `87c48b9` успевала сделать - строку `ready` прямо перед удалением объекта — смесь «новый уборщик + - прежние реплики» была хуже, чем до правки. Теперь обе смеси не хуже, - чем до правки (проба блокировок — design, п. 21), остаётся только - откат транзакции уборки после удачного DELETE. Цена — вызов S3 внутри - транзакции (≤ 5 с < `idle_in_transaction_session_timeout` 10 с). - Решения 18 и 19 в части «три шага» заменены этим. -24. **Порядок обновления**: вперёд — сначала реплики (`make - rolling_update`), потом `docker compose up -d --no-deps cleaner`; - откат реплик на версию раньше `87c48b9` — сначала уборщик - (`balancer.md`, `REPORT.md`). -25. **Тесты 11.x не менялись**: `undeletable` на двухшаговой схеме роняет - DELETE строки в той же транзакции, что DELETE объекта, — это тот же - откат после удачного DELETE в S3; красный прогон на `f2dc0b3` в силе. - Требования `graceful-shutdown` и `storage-consistency` не менялись. - -#### Вопросы - -1. Как перенести секреты уборщика `S3_CLEANER_ACCESS_KEY` и - `S3_CLEANER_SECRET_KEY` в рабочий `.env`? Без них compose не - разбирает файл (`:?`). Тогда apply не проверит изменения ни на рабочем - стенде, ни в `make failure_checks` и `make test_isolated` (tasks, - шапка). - - По умолчанию — как в ответе на вопрос 1 `s3-storage`: пользователь - переносит из `.env.example` строки и комментарий, - значения — `openssl rand -hex 10` (ключ) и `openssl rand -hex 20` - (секрет). - - Альтернатива — научить `make env_setup` дописывать недостающие - секреты в существующий `.env`; только по просьбе пользователя. - - Спеки и design от выбора не меняются. - - **Ответ основной сессии 2026-10-21** (пользователь недоступен и - поручил работать самостоятельно): альтернатива. `make env_setup` - дописывает в существующий `.env` переменные шаблона, которых в нём - нет: секреты — случайными значениями, остальные — значениями - шаблона; существующие строки не меняет, печатает только имена. - Причины: значения не попадают ни в журнал сессии, ни в вывод; - тот же путь нужен и проверяющему со старым `.env` при переходе между - changes; ручной перенос блокирует автономную проверку на стенде. - Правило `settings.md` и сценарии `make env_setup` обновляет apply. - **Сделано в apply** (решение 12 выше): рабочий `.env` получил две - строки `S3_CLEANER_*` этой командой. - -### upload-memory - -#### Решения - -Приняты 2026-10-21 в `/opsx:propose`, подробности — design change -`upload-memory`. Пробы — design, Context: проект compose `umprobe`, -реплика 1 CPU / 512 МБ, прототип в копии дерева в scratchpad. - -1. **Проба опровергла «~1,2 тела» из `REPORT.md`** (Context, п. 1–5): - - при PUT aiohttp копирует тело (`getbuffer()` у `BytesIO`, общего с - `bytes`). Пик загрузки — около двух тел, и спек `attachments` - («Лимит размера до чтения тела») сейчас нарушен; - - код `f894040` без swap при 20 одновременных загрузках по 10 MiB — - OOM-kill. Со swap рабочего стенда при 30 — 512 MiB и ещё 267 MiB в - swap; - - ожидание до чтения тела само память не бережёт: ядро копит - недочитанное тело в буфере сокета, до 32 MiB на соединение; - - LB даёт 502/504, если реплика молчит дольше 10 с до тела или после - него, а клиенту, замолчавшему посреди тела, отвечает 400 в HTML. -2. **Места загрузки — на процесс API** (решение 1): 4 места, очередь до - 16, ожидание до 5 с по порядку прихода. Отвергнуты очередь в LB - (второй набор слотов ломал бы замену реплик и профили лабы 3), - `--limit-concurrency` uvicorn, места по байтам и общий счётчик в - Valkey или PostgreSQL. -3. **Ответ при занятых местах — 429 `rate_limited`, `Retry-After: 1`** - (решение 2) — до ответа на вопрос 1 ниже. Очередь, а не сразу 429: - сообщение несёт до 10 вложений, и 10–20 одновременных загрузок по - 10 MiB на пробе проходят все. -4. **Место — после проверок 401/400/404/415/413 и до тела, держится до - ответа** (решение 3). Граница уборщика B = 17 с не меняется: - ожидание, тело и проверка — до `created_at`, сроки tx1, PUT и tx2 - прежние. Проверка grace и стенд отказов (20 с) остаются. Свойство - закреплено сценарием `storage-consistency` и тестом: `created_at` - ожидавшей позже `updated_at` той, что держала место. -5. **Срок тела — 30 с с момента, как загрузка заняла место, иначе 400 - `invalid_request`** (решение 4), по образцу обрыва тела. 408 в - контракте ручки нет. Срок простоя между блоками отвергнут: клиент по - байту раз в 29 с держал бы место вечно. -6. **В PUT уходит тот же `BytesIO`** (решение 5): после проверки ссылка - на `bytes` удаляется, буфер снова не общий. Проба — 1,19 тела вместо - 2,0–2,3, SHA-256 объекта совпал. -7. **Буферы ядра** (решение 6): у `api` — `net.ipv4.tcp_rmem` до 512 KiB - (`sysctls` в compose), у LB — `tune.sndbuf.server 262144`. При 40 - загрузках `sock` реплики — 17 MiB вместо 134, пик LB — 51 MiB вместо - 109. Скорость загрузки одного клиента та же. -8. **Цепочка таймаутов пути загрузки** (решение 7): - - `timeout server` LB для `POST …/attachments` — 30 с: молчание до - тела ≤ 17 с, после ≈ 26 с; остальные пути — прежние 10 с; - - ответ LB 400 — в формате контракта; - - `ROLLOUT_DRAIN_TIMEOUT` — 90 с, больше наибольшей длительности - загрузки ~73 с; - - 408 на медленные заголовки остаётся HTML: `http-error` его не - меняет, запись в `KNOWN_ISSUES.md`. -9. **S3 без изменений** (решение 8): лимит загрузок шлюза 64 МБ, - `GOMEMLIMIT`, 512 МБ и общий срок вызова 5 с. При 12 одновременных - PUT (три реплики × 4 места) p95 — 1,6–1,9 с. Отдельный срок PUT не - нужен — это закрывает открытый вопрос design `attachments`. -10. **Профиль `uploads`** (решение 10): одна реплика без swap, S3 рабочего - стенда. Варианты: «до» (образ `f894040`), «без лимита» и «с - лимитом». Тела 1 и 10 MiB, 1 / 10 / 20 / 40 клиентов, 3 повтора, - новые S3 и реплика на прогон. Пик окна — `memory.peak` со сбросом - через свой дескриптор: пик старта (фиктивный хэш, 152 MiB) его иначе - перекрывает. Гипотезы H1–H4 — в design, в `REPORT.md` — отдельным - commit до прогонов. -11. **Тесты** (решение 11): в `make student_test` — 10 одновременных - загрузок. В `make failure_checks` — третий API с 1 местом, 1 в - очереди, ожиданием 1 с и сроком тела 2 с, пять тестов. Сценарии - памяти — исключения сверки со ссылкой на метку профиля. -12. **Драйвер `lb-upload-timeouts`** (решение 7): сроки LB на заглушке за - `haproxy.cfg` проекта. Evidence — `evidence/uploads/lb-timeouts.md`. - -Приняты 2026-10-21 в `/opsx:apply` (подробности — design, «Уточнения -apply»; вопрос 1 открыт — сделано 429, как по умолчанию): - -13. **Красный прогон — 5 из 5** новых тестов отказов на `f894040` - (п. 2): `test_rejections_before_queue` проверяет и полноту очереди - (429 ожидавшей), `test_slot_released_after_failures` включает шаг - «400 по сроку тела» — оба поэтому красные на прежнем коде, а не - зелёные, как ждали tasks. На дереве — все пять зелёные. -14. **Тесты мест под срок тела стенда 2 с** (п. 1, 3): держатель места - отпускается сразу после 429 ожидавшей, сверка — «новые `id` — только - держателя»; ранние отказы быстрее срока ожидания (1 с), а не 0,5 с. -15. **Одна копия тела подтверждена до профиля**: PUT 10 MiB в образе API - против S3 стенда — 1,19 тела над базой против 2,31 у прежнего пути, - SHA-256 совпал. -16. **Тип мест в сервисе — под `TYPE_CHECKING`, `Retry-After` — таблица - `RETRY_AFTER` в `errors.py`, `UploadsBusy` журналирует сервис** (п. - 4–6). -17. **Драйвер `lb-upload-timeouts`** (п. 8): пять случаев параллельно, - ~33 с; код 0 на текущем `haproxy.cfg`, код 1 на `f894040` (502 и 504 - через 10 с, 400 HTML). -18. **Профиль `uploads`** (п. 10): разбор — `bench/uploads.py`; окно - памяти — весь прогон k6 со сбросом пика после разогрева; окружение - варианта — свой override, чтобы `stand.app_env` прежних профилей не - менялся; S3 перед прогоном — `kill` и новый volume. `uploads_quick` - на дереве: «с лимитом» при 40 × 10 MiB — пик 180 MiB, 429 вместо - 5xx; «без лимита» — OOM. Попутно исправлен сэмплер: каждый запуск - оставлял анонимный volume (удаление без `-v`). -19. **Буфер приёма LB от клиента — `tune.rcvbuf.client 131072`** - (`97a4be4`; design, «Уточнения apply», п. 11). Первая метка - `baseline` (на `511e285`) отброшена: swap хоста 337 056 страниц и - `dirty`. Из неё взят только рост пика LB «с лимитом» ~2,6 MiB на - клиента — сценарий `load-balancing` «Буферы соединений ограничены» не - выполнялся из-за буфера приёма LB от клиента (до 9 MiB на сокет). - После правки — 0,56 MiB на клиента. -20. **Метка `baseline` на `97a4be4` принята с пометкой (решение - пользователя 2026-10-22, commit `ce1ae2c`).** В паспорте — - предупреждение «host swapped out 7464 pages»: вся выгрузка пришлась - на прогон `limited-10MiB-c40-r2` (`host_swap`). Пик памяти в нём как у - повторов, искажено только время (9,95 загрузки/с против ~11,0, p95 - 2 815 мс против ~2 050); медиана ячейки и выводы H1–H4 от него не - зависят. Предупреждение названо в `REPORT.md`. -21. **Правки по verify (2026-10-22, tasks, группа 11; design, «Уточнения - apply», пп. 12–16).** Метка `baseline` не переснимается; числа, - которых нет в её сводке, `REPORT.md` даёт формулой из её ячеек. - - Разбор сводки: H1 считает 429, OOM и 5xx только по ячейкам - гипотезы (10 MiB, C = 10, 20, 40: у `baseline` 429 — 1 351, а не - 2 731 обоих тел) и печатает рост сверх C = 10 на клиента; - «Буферы соединений ограничены» — своя строка с вердиктом по сумме - роста LB и `sock` реплики от C = 1 до 40 (у `baseline` 0,56 + 0,39 = - 0,95 MiB при пороге 1). - - Спеки: в требовании срока пути загрузки — буфер приёма LB от - клиента 128 KiB; «Лимит размера до чтения тела» — одна копия тела и - блоки чтения, рост пика ≤ 1,5 тела (как в сценарии). - - Проверки соотношения `wait_timeout_seconds` и `timeout server` LB - при старте нет: LB-значение API не знает; соотношение — в - `settings.md` и `config_example.toml`. - - Срок тела «узкого» API стенда отказов — 3 с вместо 2 с: запас - держателя места в `test_upload_slots_busy` был ~0,5 с. Evidence - `failure-checks.md` — переснять после commit. - - `REPORT.md`: таблица 1 MiB, числа и commit строк тестов - (`ce1ae2c`), ограничение «оборванный клиент в очереди держит место - очереди до срока ожидания». - -#### Вопросы - -1. Какой код отдавать, когда все места загрузки реплики заняты и - очередь полна или ожидание истекло: 429 `rate_limited` или 503 - `unavailable`? Контракт (`contracts/openapi.json`, ручка - `uploadAttachment`) допускает оба: - - 429 описан как «Ограничение частоты запросов», у него одного есть - заголовок `Retry-After`; - - 503 описан как «Зависимость недоступна». - - `contracts/README.md` разрешает факультативное ограничение запросов - кодом `429 rate_limited`. Места загрузки ограничивают одновременность, - а не частоту, и это расхождение формулировки. Поэтому трактовку - выбирает преподаватель. - - По умолчанию до ответа — 429 с `Retry-After: 1`. Причины: из двух - описаний контракта к ограничению подходит только 429, а «зависимость - недоступна» неверно. Кроме того, клиент и профиль `uploads` отличат - занятые места от отказа S3, который тоже 503. - - Ответ «503» меняет строку таблицы `src/api/errors.py` (заголовок - `Retry-After` остаётся), сценарии `attachments` и - `api-conventions`, ожидания тестов и `REPORT.md`. Остальной design - и задачи не меняются (design, решение 2). - - **Состояние на apply 2026-10-21:** ответа нет, сделано 429 - `rate_limited` с `Retry-After: 1` (поручение основной сессии). Строки, - которые поменяет ответ «503»: `DOMAIN_ERRORS` и `RETRY_AFTER` в - `src/api/errors.py`, `ERROR_CODES` и проверка `Retry-After` в - `student-tests/contract.py`, ожидания `test_upload_slots_busy` и - `test_rejections_before_queue`, сценарии спеков `attachments` и - `api-conventions`, правило `api-contract.md`. - -### track2-reconciler - -#### Решения - -Приняты 2026-10-22 в `/opsx:propose`, подробности — design change -`track2-reconciler`. Пробы — design, Context: проект compose `rcprobe`, -SeaweedFS и PostgreSQL на tmpfs, bootstrap проекта. - -1. **Сверка — часть уборщика** (решение 1): - - команда `python -m src.cleaner reconcile [--apply] [--max-changes - N]`, по умолчанию dry-run; цель `make reconcile [APPLY=1]`; - - плановая сверка в сервисе `cleaner` — при старте и раз в - `[reconciler] interval_seconds` (3600 с), с исправлением; - - `--once` — как было. - - Отвергнуты: - - отдельный сервис и пользователь S3 `reconciler`: второй процесс и - два секрета ради почти пустого разделения прав; - - сверка только вручную: PUT-зомби жил бы до запуска. - - С уборщиком на строках `pending` сверка не спорит: убирает их его - процедурой (`FOR UPDATE SKIP LOCKED` и пометка), а объект строки любого - статуса не удаляет никогда. -2. **Права S3** (решение 2). `cleaner-objects` получает `s3:ListBucket` - с условием `s3:prefix` `<база>/attachments/*`, префикс bootstrap берёт - из `POSTGRES_DB` (`S3_CLEANER_LIST_PREFIX`). Проба: SeaweedFS 4.48 - условие соблюдает — весь bucket, `test_/` и чужой bucket дают 403. - Нового пользователя и секретов нет. `make s3_check` получает строки - списка ключом уборщика. -3. **Проход** (решение 3): - - страницы LIST по 1000; - - на страницу — одно выражение к БД по `id` (по тексту ключа — только - для нестандартных ключей: по пробе в 15 раз дороже); - - множество увиденных ключей, затем keyset строк `ready` по `id`. - - Слияние отсортированных потоков отвергнуто: порядок списка SeaweedFS — - обход каталогов, а не порядок байтов (проба). Действия — только после - классификации, каждое с перепроверкой в БД и HEAD. -4. **Безопасность** (решение 4): - - grace уборщика по `LastModified` объекта и времени строки; - - удаляются только объекты без строки и зависшие загрузки; - - чужие ключи — только отчёт и код 3; - - отсутствие объекта не подтверждается без проверки bucket; - - предел `[reconciler] max_changes` (100): больше — ни одного - изменения, код 3. -5. **Потерянный оригинал** (решение 5) — колонка `attachments.lost_at`. - `status` и `updated_at` не меняются. Ответы API: - - скачивание помеченного — 404 без обращения к S3, до пометки — 500, - как было; - - метаданные — 200; - - ссылка в сообщении — 201. - - Это вариант по умолчанию до ответа на вопрос 1 ниже. Статус - `lost`/`failed` отвергнут: контракт лабы 4 знает только `ready`. -6. **Миграция** (решение 6) — `ADD COLUMN lost_at` с `SET LOCAL - lock_timeout`. По пробе это только каталог: 0,36 мс. Смеси версий не - хуже, чем до change. Порядок обновления: - - вперёд — `s3-bootstrap`, `make rolling_update`, затем уборщик; - - откат — сначала уборщик. -7. **Коды разового прохода** (решение 8): 0 — расхождений нет, 3 — - остались (в том числе чужой объект или отказ по пределу), 1 — - прерван, 2 — конфигурация. -8. **Стенд отказов** (решения 9, 11): - - плановая сверка выключена (`RECONCILER__INTERVAL_SECONDS=0`); - - сверку запускает hook; - - новые действия hook: объект мимо API, удаление объекта, строки и - размера, сдвиг времени строки, `lost-ids`, `fail-attachments mark`, - `reconcile`, `stop|start cleaner`, `run-cleaner`; - - восемь тестов отказов, ~+3 мин; объекты без строки ждут grace, а - строки состаривает hook. -9. **Evidence** (решение 12), `evidence/reconcile/`: - - `cycle.md` — драйвер `reconcile-cycle`: dry-run, apply, повтор = 0, - возврат оригинала; - - `stress.md` — `reconcile-stress`; - - `service.md`. - - Плюс `evidence/s3/cleaner-list.md` и `evidence/migrations/lost-at.md`. -10. **Граница с `track2-reconcile-cost`** (решение 13). Здесь — одна - стратегия «батч» и поверхностная сверка (наличие и размер). Там: - - HEAD на строку; - - глубокая сверка SHA-256; - - ограничение скорости; - - профиль `reconcile` стенда `bench/`; - - гипотезы 1–4. - - Гипотезу 5 проверяет стресс этого change. -11. **Запись `KNOWN_ISSUES.md` о bootstrap после удаления bucket — - воспроизведена и объяснена** (design, Context; решение 14). Причина — - не имя bucket, а слоты томов: - - `-volume.max=0` даёт на tmpfs 4 ГБ три слота; - - после удаления коллекции их занимают тома коллекции по умолчанию; - - PUT получает «no free volumes left», 500. - - На 16 ГБ повтор bootstrap прошёл за 2 с. У рабочего стенда 403 - свободных слота. Reconciler bucket не создаёт, поэтому запись не - чинится. В apply её текст переписывается, запись остаётся открытой. -12. **Решения apply (2026-10-22)** — подробно design, «Уточнения apply»: - - потерянный оригинал — вариант (а) до ответа на вопрос 1; - - `ReconcileAction` (названия действий), в итоге — `remaining` и - `unlogged`, `found` / `fixed` — `MappingProxyType`; - - шаг уборщика публичный (`remove_stale_pending`): сверка убирает - зависшие по одной, с записью «Fixed» на каждую; - - у `--apply` исправленное — `info` «Fixed», оставшееся — `warning` - «Found»; - - перед каждым действием — ещё одна проверка его условия (HEAD, - условный `UPDATE`, ссылки на ключ), перед пометками — снова bucket; - - свежие чужие объекты и объекты без `LastModified` — свежие; - - отказ после сигнала — `interrupted_by: stop`; - - 404 у списка — отсутствующий bucket; - - ревизия `5c3e1f0a9b7d`; планы: страница по `id` — BitmapOr, 1,5 мс, - keyset `ready` — Index Scan `pk_attachments`, 0,57 мс; - - hook `start cleaner` — `docker start` контейнера (`compose start` - требует контейнер `migrate`); - - драйвер на рабочем стенде — только после перестройки 12.1; в apply - он проверен на временном полном стенде. -13. **Правки по verify (2026-10-22, группа 13 tasks)** — design, - «Уточнения apply», пп. 19–23: - - W1: hook `set-key`, сценарии «Объект, на который ссылается строка, - не удаляется» и «Предел не останавливает уборку зависших», тесты - `…_keeps_referenced_objects` и `…_limit_keeps_cleanup` (зелёные на - `a6071da`, красные на временных регрессиях); - - W2: строка с ключом вне `<база>/attachments/` — «чужой объект» без - HEAD, пометки и уборки; сценарий «Ключ вне префикса вложений не - трогается», тест `…_foreign_key_untouched` (красный на `a6071da`); - сервис уборки такую зависшую загрузку по-прежнему убирает — - `KNOWN_ISSUES.md`; - - S1: сигнал — перед каждым вызовом хранилища, остановка ≤ 5 с (S3) / - ≤ 6 с (БД); - - S4: ранний отказ по пределу не сделан — передан в - `track2-reconcile-cost` (раздел 6 выше); - - S5: `driver.py reconcile-signal` — код 1 разового прохода по - SIGTERM; снимок — после commit, на временном стенде. - -#### Вопросы - -1. **Вопрос преподавателю.** Что отвечает API лабы 4 на вложение, - оригинал которого потерян, после того как сверка это подтвердила? - Объекта в bucket нет или он другого размера, байтов не восстановить. - - Контракт неоднозначен: - - `contracts/openapi.json`: у `Attachment.status` в лабе 4 одно - значение — `ready`, `failed` и 409 появляются с лабы 5; - - `contracts/README.md`: «Отсутствующий вариант ready-объекта — 404», - «404 — объекта нет или он чужой» и «Неожиданное исключение — 500». - - Варианты: - - (а) **по умолчанию:** метаданные — 200 как раньше (`ready`, - `error_code=null`), байты — 404 `not_found`, как отсутствующий - вариант, ссылка в новом сообщении — 201. До пометки байты — 500: - непредвиденное расхождение; - - (б) вложение целиком как незавершённое: метаданные, байты и ссылка - — 404; - - (в) байты — 500 и после пометки: пометка только для отчёта. - - Ответ (б) или (в) меняет только ветку `open_content` и выборку - вложений сообщения, сценарий `attachments` «Потерянный оригинал», тест - `test_reconcile_finds_and_fixes` и `REPORT.md`. Классы, правила - безопасности, схема и задачи сверки не меняются (design, Open - Questions). - - **Состояние на apply 2026-10-22:** ответа нет, сделан вариант (а) - (поручение основной сессии). Строки, которые поменяет ответ «иначе»: - ветка `lost_at` в `AttachmentService.open_content` - (`src/core/services/attachment.py`), для (б) — ещё проверка `lost_at` - в `get_attachment` и `MessageService` (выборка вложений сообщения); - сценарий `attachments` «Потерянный оригинал», `assert_lost_content` и - ожидания `test_reconcile_finds_and_fixes`, - `test_reconcile_keeps_fresh_used_and_unknown`, - `test_reconcile_restored_original`, шаги 5–6 и 8 `driver.py - reconcile-cycle`, правило `api-contract.md`. - -### fix-upload-put-flake - -Change вне сводной таблицы, до `track2-reconcile-cost`: исправление -записи `KNOWN_ISSUES.md` «Изредка 503 на загрузке: PUT в S3 обрывается -без тела» (решение пользователя 2026-10-22). - -#### Решения - -Приняты 2026-10-22 в `/opsx:propose`, подробности — design change -`fix-upload-put-flake`. Пробы — design, Context: временный проект compose -`upfprobe` (тот же `docker-compose.yml`, синтетические секреты, данные S3 -— volume `upfprobe_s3_data`, удалён после пробы), образы текущего дерева, -`f894040` и прототипа правки. - -1. **Причина найдена и воспроизведена** (design, Context): - - клиент S3 задаёт aiohttp срок чтения (`read_timeout` = `[s3] - timeout_seconds`, 5 с, с `s3-storage`); - - после скачивания большого оригинала с паузой чтения (буфер ответа - больше 512 KiB: `read_bufsize` 256 KiB, порог паузы вдвое больше) - aiohttp 3.14.5 (версия `uv.lock`, другие пробой не проверялись) - перевзводит этот срок в `resume_reading()` уже после конца ответа, - когда соединение вернулось в пул; - - через 5 с простоя срок срабатывает и портит соединение: исключение - сохранено, транспорт открыт; - - пул отдаёт его следующему вызову в окне 5–15 с (keep-alive), и вызов - падает за 1 мс — `ReadTimeoutError` → 503. S3 видит заголовки без - тела: botocore ставит `Expect: 100-continue` любому телу PutObject. - - Подтверждено: - - журнал рабочего стенда: три 503 через 5,9–6,8 с после скачиваний - `test_concurrent_uploads` на той же реплике; - - локальная проба aiohttp и проба клиента в образе API; - - HTTP через LB: до 13 × 503 за 4 раунда; - - захват пакетов: FIN клиента через 0,1 мс после заголовков PUT, 0 байт - тела. - - Полный `make student_test` на пробном стенде — 10 прогонов из 10 - зелёные: вероятность отказа на прогон зависит от таймингов. Поэтому - доказательство — целевое воспроизведение. -2. **Не регрессия `upload-memory`**: образ `f894040` (тело `bytes`) — 8 × - 503 в 4 раундах из 5 с той же подписью. В набор триггер пришёл с - `test_concurrent_uploads` (10 скачиваний по 1 MiB, затем ≥ 5 с без - вызовов S3). -3. **Правка — `read_timeout=None`** (решение 1). Срок вызова и блока - чтения — `asyncio.timeout` приложения, как было. Прототип в раундах - теста: 0 отказов из 120 загрузок после простоя, а на текущем образе в - тех же раундах — 17 × 503 (испорчено 17 соединений из 60). 503 при - `docker pause` S3 — за 5,02 с; обрыв ответа посреди тела — через 5,9 с. - - Отвергнуты: - - `force_close`; - - связка сроков keep-alive и `sock_read`; - - свой коннектор и патч aiohttp; - - другая версия aiohttp: новее 3.14.5 нет, дефект в ней воспроизведён, - а aiobotocore 3.9.2 требует ≥ 3.14.0; - - снятие `Expect`; - - больший буфер ответа; - - повтор. -4. **Правило «S3 без повторов» не меняется** (решение 2): повтор лечил бы - симптом, а `ReadTimeoutError` порчи не отличить от таймаута зависшего S3 - без закрытых полей aiohttp. -5. **Тест — стенд отказов, четвёртый API с `S3__TIMEOUT_SECONDS=1`** - (решение 3): до 8 раундов «10 одновременных медленных скачиваний ~4 MiB - → простой 1,5 с → 12 загрузок». Вероятность промаха на прежнем коде ≈ - 4e-12, `make failure_checks` дольше на ~20 с. В `make student_test` не - кладётся: раунд там — 6+ с простоя, нужно ~5 раундов (+35 с), и тест - всё равно вероятностный. Hook с пробой клиента в контейнере отвергнут: - это импорт `src` в обход HTTP. -6. **Evidence механизма — `driver.py s3-idle`** (решение 4): проба - клиента в реплике стенда, вариант образа против эталона с прежним - сроком. Файл — `evidence/s3/idle-connection.md`. -7. **Путь PUT не меняется** (решение 5): то же тело, заголовки, соединение - и срок. Проба памяти PUT 10 MiB на прототипе — 1,18 тела против 1,19. - -Приняты в `/opsx:apply` 2026-10-23 (design, «Уточнения apply»): - -8. Медленное скачивание теста — `Api.attachment_content_slowly`, ответ - проверяет обычный `assert_content`. Оригинал — `png_noise(1024, 1365)` - (~4 MiB), пользователи — фикстуры обычного API: база у API стенда общая. -9. Красный прогон на `4cfaab0`: три из трёх упали уже в раунде 1. -10. `driver.py s3-idle` считает объекты по списку записанных ключей: - списка у ключа API нет. Удаляет их отдельный клиент без скачиваний, - остаток проверяет `weed shell fs.tree` по файлам. Эталон — клиент - проекта с подменённым на время `start()` `AioConfig` - (`read_timeout=[s3] timeout_seconds`). По умолчанию 3 раунда и PUT - по 128 KiB. -11. Evidence — с `b5983f0`. `make test_isolated` на нём записан в - `evidence/s3/idle-connection.md` (раздел 7), а - `evidence/tests/test-isolated-s3-cleanup.md` не переснимался: его - предмет — уборка префикса `test_/`, а она не менялась. Полный - `make failure_checks` снят с фильтром вывода, без построчного списка - тестов: итог 49 passed и `results` — в файле. - -Правки по `/opsx:verify` 2026-10-23 (tasks, группа 6; design, -«Уточнения apply», п. 8): - -12. Буфер ответа aiohttp 3.14.5 — 256 KiB (`DEFAULT_CHUNK_SIZE`), пауза - чтения выше 512 KiB; прежние 64 / 128 KiB — значения 3.12–3.13. - Сходится с замером propose: до 200 KiB соединения не взводятся. -13. Версии aiohttp — «в каких проверено»: дефект воспроизведён только в - 3.14.5. По исходникам (кэш uv и sdist PyPI) перевзвод срока в - `resume_reading()` есть в 3.12.15, 3.13.2, 3.13.3, 3.13.5 и - 3.14.0–3.14.5 (с 3.14.2 — только после паузы); нижняя граница не - установлена. -14. Ссылка `botocore/handlers.py:380–397` оставлена: по `.venv` и по - образу `add_expect_header` — строки 380–397 (`def` — 380, `Expect` — - 397), а не 378–395, как в замечании S2. `client_proto.py:196–201` - исправлена на `196–202`, `httpsession.py:97–98` — на `97–99`. -15. Спек `object-storage`: срок из настроек — единственный срок вызова, - «кроме срока установки соединения» (`connect_timeout_seconds`), в - дельте и основном спеке одинаково. -16. `make test_isolated` и полный `make failure_checks` пересняты на - `723b6c3` (код — `b5983f0` плюс комментарий) с полным выводом: - 193 + 5 пропусков и 49 из 49 за 552 с (`evidence/tests/`). - -#### Вопросы - -1. Нужна ли пересъёмка полной метки `make bench_uploads` - (`evidence/uploads/baseline/`)? - - Правка путь PUT не меняет: то же тело, те же заголовки, то же - соединение из пула, тот же срок вызова. Исчезает только взвод таймера - `sock_read` после записи тела. - - Профиль `uploads` только загружает и не скачивает, порча соединений в - метке не возникала (design, решение 5). - - По мнению агента пересъёмка не нужна: хватит точечной пробы памяти и - `make bench_uploads_quick` в apply (tasks 4.4). - - Полный прогон (~50 мин) требует тихого хоста, а на нём сейчас - работают контейнеры другого проекта. Решение — за пользователем. - - По умолчанию до ответа — не переснимать, метка `baseline` остаётся. - - **Ответ пользователя 2026-10-23:** полную метку не переснимать, - `evidence/uploads/baseline/` остаётся. В apply — точечная проба памяти - PUT и `make bench_uploads_quick` (tasks 4.4). - -### track2-reconcile-cost - -#### Решения - -Приняты 2026-10-23 в `/opsx:propose`, подробности — design change -`track2-reconcile-cost`. Пробы — design, Context: временный проект -compose `rccost`, тот же `docker-compose.yml`, образ рабочего стенда -(`7f4e626`), PostgreSQL и S3 на volumes `rccost_*` — удалены по имени. -После пробы volumes, сети и образы — как до неё (155 / 17 / 24). Во время -пробы работали `domains-*`, поэтому задержки шумные, а счётчики точные. - -1. **Профиль `reconcile`** (решение 1): - - `make bench_reconcile` — **~50 мин**, `make bench_reconcile_quick` — - **~6 мин**; - - результаты — `evidence/reconcile/<метка>/`; - - этапы: A — 1k × 1 MiB, свежий стенд; B — 10k × 4 KiB, свежий; - C — 30k и D — 100k, тот же набор растёт; S4 — свежий стенд; - - три повтора кругами. - - Полная метка — отдельная точка commit после commit гипотез, на тихом - хосте: основная сессия останавливает `domains-*` на ~50 мин. -2. **Набор** (решение 2): - - N = 10k / 30k / 100k объектов по 4 KiB и 1k по 1 MiB; - - расхождения — по 0,25 % на класс (без метаданных, без объекта, - другой размер, зависшая загрузка), класс по номеру объекта; - - grace проходов — 30 с. - - Отвергнуты: 10k и 100k без средней точки, 1M, доли 0 % и 10 %, - случайные позиции. -3. **Наполнение мимо API** (решение 3): - - строки — `\copy` через stdin psql стенда; - - объекты — загрузчик `bench/fill_objects.py` в контейнере на образе - стенда, botocore и ключи API, ~1 750 PUT/с, упор в S3. - - Проход сверки — разовый уборщик, его результат — его журнал. Это новое - исключение границы чёрного ящика — только у профиля сверки. -4. **Стратегия `--strategy head`** (решение 4): выборка строки на объект - и HEAD на строку, без множества ключей. Только разовый проход; - плановая — `batch`. Проба: ~5,15 мс на объект против 0,30 у `batch` - (~17×). -5. **Глубокая сверка `--deep` — по требованию** (решение 5): - - SHA-256 потоком; - - новый класс `checksum_mismatch`, с `--apply` — пометка потерянного - оригинала; - - «оригинал вернулся» теперь требует того же SHA-256 во всех режимах. - - Выборочная глубокая в плановой отвергнута. Проба: предел глубокой на - лимите стенда — CPU уборщика, а не S3 (уточнение гипотезы 3). -6. **Предел скорости `[reconciler] max_objects_per_second`, по умолчанию - 2000** (решение 6): - - считаются объекты S3: ключи списка, HEAD, GET, DELETE; - - пауза прерывается сигналом; - - разовый проход принимает `--max-objects-per-second`, `make - reconcile` — `RATE`. - - 2000/с — ~0,2 ядра S3 на списке. Плановый проход 100k — ~65 с вместо - ~30. -7. **S4 — ранний отказ по пределу** (решение 7). Выбран порог - «подтверждено больше предела» с отдельным счётчиком `unchecked` в - итоге. Он действует у любого `--apply`, dry-run перепроверяет всех. - Проба на текущем коде: +5,3 мс на кандидата, +53 с при 10 000 - кандидатов. Отвергнуты отказ по числу неподтверждённых кандидатов и - ранний отказ только у плановой сверки. Замер — ячейки S4 на образе - `7f4e626` и на checkout. -8. **Счёт запросов** (решение 8): - - внутренний: счётчики клиента S3 по операциям и байтам, сеансы БД - обёрткой `db_scope` — в итоге прохода; - - внешний — только в метке: метрики шлюза `-metricsPort` на loopback, - только у S3 профиля сверки (override генерирует `run.py`) — и - `pg_stat_database`. Проба: шлюз считает HEAD типом GET, совпало до - запроса. - - Отвергнуты `pg_stat_statements` и порт метрик у рабочего стенда. -9. **Фоновая нагрузка и порог H4** (решение 10): - - 300 скачиваний, 50 записей и 50 чтений истории в секунду; - - тихие окна по 30 с до и после прохода; - - порог — медиана `p95(проход) / p95(окна)` ≤ 1,5 у `stand`, - `stand-unlimited`, `fast-limited`; - - контраст: `fast-unlimited` (1 CPU без предела) > 1,5 (проба: ×2,2); - - A/A окон вне [1/1,5; 1,5] — «не различимо». -10. **A/A и сравнение меток** (решение 11): A/A — внутри метки (разброс - повторов, окна до и после). Второй метки и `make bench_compare` нет. -11. **Гипотезы H1–H4 и ожидание S4** (решение 12) уточнены по пробе. Они - идут в `REPORT.md` отдельным commit до метки. -12. **Пять тестов отказов** и аргументы hook (решение 14). Красный прогон - — на `7f4e626`. Остановку во время паузы предела проверяет `driver.py - reconcile-signal --pace` → `evidence/reconcile/service.md`. - -Решения apply (2026-10-23, `/opsx:apply` без пользователя; подробно — -design, «Уточнения apply», пп. 1–13): - -13. Пауза предела скорости — после каждого вызова S3: иначе последний - вызов прохода предел не ограничивал бы (п. 1). -14. GET отдаёт `last_modified`, находка несёт SHA-256 строки; глубокая и - свежесть, вернувшийся объект с другим SHA-256 — `lost_known` (пп. 2–5). -15. Hook и тесты: позиционный предел и флаги по одному разу; тест предела - скорости — своя потеря и остановленный уборщик (пп. 6–7). -16. Быстрый профиль — два свежих стенда (S4 — свой), k6 блока H4 - останавливается `pkill -INT`, длительности — 0,01 мс (пп. 8–9). -17. Память в H1 и H2 — наклон и рост пика от N, а не прирост прохода: - постоянная часть прохода ~14 МиБ (п. 10). -18. Модель сверяется в каждом проходе (`found`, `listed_objects`, - `checked_rows`), окно шага списка — справочно (пп. 11–12). -19. `reconcile-signal --pace` — объекты пробы, иначе на пустом bucket - паузы нет; остановка — от события `kill` до `FinishedAt` (п. 13). - Проверка на временном проекте `rcpace` (tmpfs, без портов): до правки - п. 14 — 1,16 с (FAIL), после — 0,22 с, код драйвера 0; режим без - `--pace` — PASS (4,6 с при замороженном S3). Проект убран: volumes - 155, сети 17. -20. Уборщик выходит `os._exit` после `main()`: финализация - интерпретатора при 0,25 CPU — 0,8–1,5 с, остановка по сигналу иначе - больше секунды (п. 14). -21. Красный прогон 1.3 (`make failure_checks FAULT_ARGS='-k "head_strategy - or deep_checksum or restore_needs or rate_limit or limit_stops"'`, - код `7f4e626`, тесты из дерева): 5 failed за 117 с — `head` и предел - скорости — argparse (пустой отчёт, нет итога), глубокая — нет поля - `deep`, восстановление — пометку снял другой объект того же размера, - предел — `changes` 7 вместо 3. Затем все 16 тестов сверки на дереве — - 16 passed за 500 с. -22. `make bench_reconcile_quick` на дереве (хост тихий: все контейнеры, - включая рабочий стенд и `domains-*`, остановлены пользователем; дерево - грязное): первый — код 0 за 3 мин 39 с, после правок пп. 16–17 — - код 0 за 3 мин 30 с (быстрее оценки design ~6 мин). 9 проходов, - найденное = внесённому, `count_mismatch` нет, 5xx фона нет, строки k6 - = итерациям; volumes 155, сети 17, тег `bench-from` снят. Во втором у - проходов 1 CPU (0,3 и 1,1 с) CPU уборщика не посчитан — окно короче - отсчёта сэмплера в конце жизни контейнера; исправлено - (`reconcile.window_cpu` — по охватывающим отсчётам). -23. Регресс `bench/`: `make bench_quick` — complete 18/18 за 3 мин 26 с, - `make bench_uploads_quick` — complete 6/6 за 4 мин 9 с (у «без лимита» - при 40 × 10 MiB — OOM, как у метки `baseline`); `--selftest` - `uploads`, `resources`, `scaling`, `failover`, `rollout`, - `reconcile` — код 0. -24. Commit кода — `8d4cf7e`. Рабочий стенд переведён на него: `make - rolling_update APP_OUT_PORT=8090` (2 реплики UP за 9 с), уборщик - пересоздан на том же образе, `make student_test - BASE_URL=http://localhost:8090` — 198 passed. Гипотезы H1–H4 и - ожидание S4 — `REPORT.md`, «Стоимость сверки: гипотезы», отдельным - commit до метки; H1 и H2 по памяти — в форме п. 17. -25. Гипотезы — `aaf3fa3`. Первая метка `baseline` на нём упала на 39/51 - (37 мин): «D: 264071 k6 lines of download, 264070 iterations» — - итерация, прерванная остановкой k6 SIGINT уже после строки, в - `iterations` не входит. Правка `a42dd27` — счётчик - `bg_lines_<сценарий>` k6 и точное «строк = счётчику»; вторая метка - на ней упала там же (39/51): «D: write: 43997 k6 lines, 43996 counted - by bg_lines (lines lost)» — у прерванной итерации k6 теряет и отсчёт - счётчика. Полнота строк теперь — снизу по итерациям и по счётчику - (меньше — «lines lost»), сверху — лишних против каждого не больше VU - сценария (design, «Уточнения apply», п. 15). Офлайн на итогах k6 обеих - упавших меток проверка проходит (download 1 и write 1 прерванная). - Хост в обеих — `swapouts_delta` 0, `host_warnings` пусты. Каталоги - неполных меток — в scratchpad (`baseline-failed-aaf3fa3/`, - `baseline-failed-a42dd27/`), метка переснимается целиком после - commit правки. -26. Правка — `d8b8ae3`. Метка `baseline` с него — complete 51/51 за 45 - мин (15:06–15:52 UTC), `dirty: false`, `swapouts_delta` 0, - `slept_seconds` 0, `host_warnings` пусты, прерванных итераций фона — - 0; commit метки — `0072dbe` (10.1). Вердикты `summary.md`: H1, H2, - H3, S4 подтверждены, H4 — «не проверена». Контраст `fast-unlimited` - дал r скачиваний 1,08 при пороге > 1,5. Проход шёл со скоростью - пробы (100k за 12,9 с), уборщик 0,50 ядра, S3 0,70–0,73 из 1 вместе - с фоном: шлюз не насыщен. Проба design (×2,2) была одной, на шумном - хосте. Дефекта стенда нет, гипотеза не правилась, перемер не делался. - Вывод для предела: защита задержек фона на этих лимитах не показана. - Измерено, что предел держит CPU S3 за проход на 0,27–0,32 ядра при - любом CPU уборщика. 2000 оставлен как граница доли шлюза - (`REPORT.md`, «Стоимость сверки: результаты метки `baseline`»). - Рекомендации для `head` и глубокой — по CPU S3 на объект: ~1000 и - ~800 / ~250 объектов/с для быстрого уборщика. -27. Evidence 11.1–11.2 с `0072dbe`: - - `make failure_checks` — 54 из 54 за 712 с; - - красный прогон 1.3 (`7f4e626`, 5 из 5) перенесён из scratchpad в - `evidence/tests/failure-checks.md`; - - `driver.py reconcile-signal --pace` на временном проекте `rcpace` - — код 1, выход через 0,2 с после `docker stop` - (`evidence/reconcile/service.md`); - - `make test_isolated` — 193 passed, 5 skipped, 54 deselected, - сверка покрытия 250 / 233 / 68 / 17, префикс `test_messenger/` и - база убраны (`evidence/tests/test-isolated-s3-cleanup.md`). - - Рабочий стенд — `make run_docker APP_OUT_PORT=8090` (реплики - `api-27`, `api-28`), `make student_test BASE_URL=http://localhost:8090` - — 198 passed. - -#### Правки по verify - -Verify на `16f2cde`: CRITICAL нет; W1–W3 и S1–S10 — группа 12 -`tasks.md`, решения — design, «Правки по verify», пп. 1–8. Коротко: - -1. W1: `_pace` по сигналу возвращается, проход останавливает следующий - `check_stop()`. Красный прогон на `16f2cde` — `driver.py - reconcile-signal --pace`: `listed_objects` 0 при 8 ключах; новый - режим `--pace --apply`: удалено 4 объекта, «Fixed» и `fixed` — 3. -2. W2: правильно поведение `head` — строка сравнивается с объектом по - своему ключу, чей бы `id` в нём ни стоял; `batch` выровнен (HEAD - такой строки в шаге строк). Тест `test_reconcile_row_with_other_id_key` - красный на `16f2cde` (`batch` не назвал ни `size_mismatch`, ни - `checksum_mismatch` у Y1, Y2). Метка `baseline` действительна: у - строк её набора свои ключи. -3. S1: свежесть объекта другого размера — в классификации, перепроверке - и перед пометкой; «другой SHA-256» перечитывается с `fresh_before`. - Тест `test_reconcile_fresh_overwrite_untouched` красный на `16f2cde` - (объект другого размера, перезаписанный только что, помечен). -4. S2: `allow_inf_nan=False` у `max_objects_per_second`; на образе - `16f2cde` `inf` проходил — «Started cleaner» с `Infinity`. Прочие - поля `float` — `KNOWN_ISSUES.md`. -5. S4, S6, S9 — `bench/reconcile.py`, `run.py`: допуск строк по - `vus_max`, критерии вердиктов, пометки `bg_failed` / `bg_dropped`. - Офлайн-пересборки `summary.md` нет; новые критерии на данных метки - пересчитаны скриптом scratchpad — все выполняются, вердикты те же. -6. S8: спек `load-benchmark` называет исключение для группы из одной - ячейки; S5, S7, S10, W3 — тексты `REPORT.md` и design. -7. Код правок — `ca0c4b2`. С него: `make rolling_update APP_OUT_PORT=8090` - (реплики `api-29`, `api-30`), уборщик пересоздан (плановая сверка при - старте — без расхождений), `make student_test - BASE_URL=http://localhost:8090` — 198 passed, покрытие 252 / 235 / 70 - / 17; `make failure_checks` — 56 из 56, pytest 877 с, команда 898 с; - `driver.py reconcile-signal --pace` и `--pace --apply` на временном - `rcpace` — PASS (`evidence/reconcile/service.md`). Красный прогон - тестов verify переснят с окончательной версией - `…_fresh_overwrite_untouched` против `src` `16f2cde` (`git archive`), - 2 из 2 упали по ожидаемым причинам (`evidence/tests/failure-checks.md`); - образ `mtusi-messenger:lab4` затем пересобран из `ca0c4b2`. - `make bench_reconcile_quick` (на дереве точки 1) — код 0 за 3,7 мин; - на шумном хосте новая пометка `bg_dropped` (45 недосланных итераций). - -#### Вопросы - -Нет. Вопрос 1 раздела `### track2-reconciler` (ответ API на потерянный -оригинал) открыт и касается и класса «другой SHA-256». Ответ меняет ту -же ветку `open_content`, а не решения этого change. diff --git a/REPORT.md b/REPORT.md index 63577337..cfa3e527 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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 && 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-`; +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 --file tests/fixtures/sample.png # то же по шагам +python3 $D --port 8080 download --token <токен второго участника> --attachment # 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//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` не сравнил строку с чужим `/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 — + (из `README.md` задания): загрузка объектов, presigned URL (почему не + трек 1), политики bucket с условием `s3:prefix`; API Reference — + `ListObjectsV2`, `HeadObject`, `DeleteObject`. +- SeaweedFS 4.48 — (wiki и + исходники): шлюз S3, учётные записи и политики IAM, `weed shell` + (`s3.bucket.create`, `s3.anonymous.set`, `fs.ls`, `fs.rm`), ключ + подписи `WEED_JWT_FILER_SIGNING_KEY`, `-ip.bind`, метрики шлюза. +- aiobotocore — , 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 — (чанки, CRC, IHDR, фильтры строк, + Adam7), zlib — RFC 1950 / 1951 и `zlib.decompressobj(max_length)` + Python; JPEG — ITU-T T.81 (маркеры, SOF, длины сегментов). +- PostgreSQL 18 — : частичные + индексы, `CREATE INDEX CONCURRENTLY`, `SELECT … FOR UPDATE SKIP + LOCKED`, `ALTER TABLE … ADD COLUMN` под `lock_timeout`, `NOT VALID` + ограничения, `pg_stat_database`. +- HAProxy 3.4 — : `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 — + (`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/` и вливала её в основную, +присылала автору прогресс. Все 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/`. Решения, перечисленные выше, принимал автор. diff --git a/evidence/tests/ci-application.md b/evidence/tests/ci-application.md new file mode 100644 index 00000000..09d62562 --- /dev/null +++ b/evidence/tests/ci-application.md @@ -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` удалены. diff --git a/evidence/tests/clean-clone-final.md b/evidence/tests/clean-clone-final.md new file mode 100644 index 00000000..6432191c --- /dev/null +++ b/evidence/tests/clean-clone-final.md @@ -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 +```