docs: complete lab 4 report and add the application CI job
- fill the skeleton sections of REPORT.md: author and target grade,
launch from a clean clone, architecture and variable mapping, open
questions to the teacher, limitations, sources and AI use
- add evidence/tests/clean-clone-final.md: clean clone of de98d77
- add .github/workflows/application.yml (CONTRIBUTING.md, CI) and the
.github/ci/ override for the Gitea runner: configs instead of bind
mounts, no host ports; evidence/tests/ci-application.md
- remove PLAN.md now that all changes are archived; point AGENTS.md
and the rules at REPORT.md
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -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`.
|
||||
|
||||
@@ -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` или возьмёт чужой образ.
|
||||
|
||||
## Обновление кода на стенде
|
||||
|
||||
|
||||
@@ -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`, без
|
||||
|
||||
@@ -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), сервис процесса уборщика:
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
}
|
||||
@@ -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
|
||||
@@ -48,8 +48,10 @@ S3 нет срока чтения aiohttp (он переживал ответ и
|
||||
SHA-256) в разовом проходе, предел скорости `[reconciler]
|
||||
max_objects_per_second` (2000 объектов S3/с), отказ по пределу без
|
||||
лишних перепроверок, стоимость прохода в его итоге, профиль `reconcile`
|
||||
стенда `bench/`. План работ, решения и
|
||||
трек «5» — `PLAN.md`. Из лабы 2: PostgreSQL
|
||||
стенда `bench/`. Рабочий план лабы 4 (`PLAN.md`) удалён после закрытия
|
||||
всех changes: итоги — в `REPORT.md`, открытые вопросы преподавателю — в
|
||||
его разделе «Открытые вопросы преподавателю», последняя версия плана —
|
||||
`git show fd03b84:PLAN.md`. Из лабы 2: PostgreSQL
|
||||
как источник истины, вход по Basic → Bearer-сессия, Valkey — кэш
|
||||
карточек чатов. Из лабы 3: HAProxy перед ≥2 репликами API
|
||||
(`replicas-lb`), `X-Instance-Id` и обязательный `Idempotency-Key`
|
||||
@@ -83,7 +85,9 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
|
||||
(кроме своих `scripts/restart.sh` и `scripts/stop-one.sh` по образцам
|
||||
`restart.example.sh` и `stop-one.example.sh`),
|
||||
`lab.json`, `README.md`, `COURSE.md`, `CONTRIBUTING.md`,
|
||||
`MAINTAINERS.md`, `.github/`, `compose.example.yaml`,
|
||||
`MAINTAINERS.md`, `.github/` (кроме своего CI job по `CONTRIBUTING.md`,
|
||||
«CI»: `.github/workflows/application.yml` и `.github/ci/`),
|
||||
`compose.example.yaml`,
|
||||
`infra/README.md`, цели `check` / `validate` / `test` / `load` /
|
||||
`test-persistence` / `test-failover` в `Makefile`. Если публичный тест упал, чиним
|
||||
приложение, а не тест. Если в контракте противоречие — сказать
|
||||
@@ -184,7 +188,8 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
|
||||
только при живом bucket; больше `[reconciler] max_changes` (100)
|
||||
изменений — ни одного и код 3. Потерянный оригинал помечается
|
||||
(`attachments.lost_at`): скачивание — 404, метаданные — 200, ссылка —
|
||||
201 (вопрос преподавателю, `PLAN.md`). Уборщику разрешён список только
|
||||
201 (вопрос преподавателю, `REPORT.md`, «Открытые вопросы
|
||||
преподавателю»). Уборщику разрешён список только
|
||||
с префиксом `<база>/attachments/` (`S3_CLEANER_LIST_PREFIX` у
|
||||
bootstrap). На время восстановления базы уборщик останавливают
|
||||
(`docker.md`). С change `track2-reconcile-cost`: проход затрагивает в
|
||||
@@ -239,7 +244,6 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
|
||||
| Файл | Что в нём |
|
||||
|---|---|
|
||||
| `README.md` | задание лабы: рубрика 3/4/5, сценарий и вопросы защиты, что приложить к PR |
|
||||
| `PLAN.md` | наш план лабы 4 на «5»: рубрика → change, ключевые решения (S3-сервер, порядок записи, память), трек 2, порядок changes, риски; удаляется, когда все changes закрыты |
|
||||
| `COURSE.md` | карта семи лаб, три объявленных перехода API (1→2, 2→3, 4→5), правила честных измерений |
|
||||
| `contracts/openapi.json` | нормативный OpenAPI 3.1: пути, схемы, коды ответов |
|
||||
| `contracts/README.md` | нормативная семантика: формат ошибок, валидация, пагинация, Basic → Bearer-сессии, TTL и отзыв, с lab3 — `Idempotency-Key` и `X-Instance-Id`, с lab4 — вложения: сырые bytes PNG/JPEG ≤10 MiB и ≤40 млн пикселей, `201 Attachment` (`ready`), `attachment_ids` в сообщении, download только участникам; пустой текст (в том числе из пробелов) — только с вложением (согласование 2026-10-20); разделы lab5+ — на будущее; как это сделано — `api-contract.md`, «Вложения (лаба 4)» |
|
||||
@@ -257,7 +261,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
|
||||
| `REPORT.md` | отчёт: запуск из чистого clone, архитектура, доказательства по каждому критерию, эксперименты, ИИ и источники |
|
||||
| `evidence/` | сохранённые выводы проверок и измерений (что можно класть — `evidence/README.md`) |
|
||||
| `CONTRIBUTING.md` | fork/PR, имя ветки, что переносить в следующую лабу |
|
||||
| `.github/pull_request_template.md` | шаблон PR; CI `workflows/contracts.yml` проверяет только контракт, приложение не запускает |
|
||||
| `.github/pull_request_template.md` | шаблон PR; CI `workflows/contracts.yml` проверяет только контракт, приложение не запускает; сборку, стенд и `make test` — свой job `workflows/application.yml` (карта кода) |
|
||||
| `Dockerfile.example` | опорные шаги Dockerfile, не рабочий файл |
|
||||
| `.env.example` | шаблон `.env`; «логические» имена skeleton (lab2, lab3 `API_REPLICAS`, `IDEMPOTENCY_TTL_SECONDS` и новые lab4 `S3_*`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS`) перечислены в шапке, их соответствие — в `REPORT.md` (`settings.md`) |
|
||||
| `examples/requests.http` | ручные запросы для HTTP-клиента IDE |
|
||||
@@ -285,7 +289,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
|
||||
| `logging.md` | сервисы, API, инфраструктура, `src/main.py`: где и как логировать, чего в логах быть не должно |
|
||||
| `settings.md` | `src/config/**`, `.env.example`, `config_example.toml`: источники настроек, что куда класть |
|
||||
| `run-modes.md` | точки входа, `Makefile`, compose, шаблоны конфигов: console и docker, uvicorn, SIGTERM |
|
||||
| `docker.md` | `Dockerfile`, `docker-compose.yml`, `.dockerignore`, `scripts/restart.sh`, `infra/**`: мультистейдж, non-root, пины, healthcheck, стенд compose, S3 и bootstrap, секреты по сервисам, volumes, restart hook |
|
||||
| `docker.md` | `Dockerfile`, `docker-compose.yml`, `.dockerignore`, `scripts/restart.sh`, `infra/**`, `.github/ci/**`, `.github/workflows/application.yml`: мультистейдж, non-root, пины, healthcheck, стенд compose, S3 и bootstrap, секреты по сервисам, volumes, restart hook |
|
||||
| `balancer.md` | `docker-compose.yml`, `infra/haproxy/**`, `scripts/stop-one.sh`, `scripts/rolling-update.sh`: реплики за HAProxy, проверки и цепочка таймаутов, повторы LB, failover hook, поочерёдная замена, лимиты и пулы (с лабы 3) |
|
||||
| `student-tests.md` | `student-tests/**`: обязательные проверки уровня 4, black-box по HTTP, особый стенд |
|
||||
| `bench.md` | `bench/**`: нагрузочный стенд на Postgres (проект compose `mtusi-bench`), что не меняется между метками замеров, граница чёрного ящика и планы запроса, сравнение меток, коммиты измеренных состояний |
|
||||
@@ -549,6 +553,9 @@ evidence/plots/scaling/ # make bench_plots по сериям a и b: гра
|
||||
evidence/plots/scaling-db/ # make bench_plots по серии db: R* по лимитам PostgreSQL и раздел «Насыщение PostgreSQL»
|
||||
evidence/uploads/ # change upload-memory: <метка>/ — make bench_uploads (meta.json, runs.csv, summary.md, raw/), lb-timeouts.md — driver.py lb-upload-timeouts, rollout-upload.md — медленная загрузка во время make rolling_update
|
||||
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md
|
||||
.github/workflows/application.yml # свой CI job (CONTRIBUTING.md, «CI»; contracts.yml — skeleton): checkout commit прогона, сборка и стенд под проектом mtusi-lab4-safronov-ci-<run_id>, job подключается к сети стенда, готовность — обе реплики через LB, make check / test, аноним в S3 — 403, make student_test, test-persistence, test-failover stop и kill, уборка при любом исходе; без s3_check, test_isolated и failure_checks (порты хоста). Раннер Gitea (act_runner) запускает job в контейнере на том же Docker, что стенд
|
||||
.github/ci/compose.yml # override стенда в CI: конфиги — configs из переменных окружения вместо bind mount (файлов job нет на хосте раннера), без портов на хосте, образ API с тегом прогона
|
||||
.github/ci/stand-env.sh # «.» в шагах job: содержимое конфигов в CI_* для configs (с переводом строки в конце: без него HAProxy конфиг не принимает), wait_replicas — /health/ready 200 от API_REPLICAS разных реплик через LB за 60 с
|
||||
KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы
|
||||
```
|
||||
|
||||
@@ -630,7 +637,12 @@ KNOWN_ISSUES.md # найденные попутно дефекты,
|
||||
`scripts/rolling-update.sh` (без примеров и проверок skeleton в
|
||||
`scripts/`), `pyproject.toml`, `uv.lock`, `.python-version`,
|
||||
`config_example.toml`, `AGENTS.md`, `CLAUDE.md`, `.claude/`,
|
||||
`openspec/`, `.graphifyignore`, `bench/`, `KNOWN_ISSUES.md`.
|
||||
`openspec/`, `.graphifyignore`, `bench/`, `KNOWN_ISSUES.md`, свой CI
|
||||
job `.github/workflows/application.yml` и `.github/ci/` (остальное в
|
||||
`.github/` — из нового skeleton). В job поменять номер лабы в префиксе
|
||||
проекта `mtusi-lab4-safronov-ci-` (и в шаге уборки хвостов), в
|
||||
override — новые сервисы и конфиги нового стенда; Actions в новом fork
|
||||
включить в его настройках.
|
||||
- Сливать, а не копировать поверх: `Makefile`, `.env.example`,
|
||||
`.gitignore`, `.dockerignore`. Берём версию нового skeleton (в ней
|
||||
новые цели и проверки) и дописываем свои секции.
|
||||
|
||||
@@ -1,15 +1,233 @@
|
||||
# Отчёт — лабораторная 4
|
||||
|
||||
- Автор, группа: TODO
|
||||
- Целевая оценка; выбранный трек 5, если нужен: TODO
|
||||
- Commit/PR: TODO после публикации
|
||||
- Использованные источники, библиотеки и помощь ИИ: TODO
|
||||
- Автор, группа: Сафронов Роман Николаевич, БВТ2301
|
||||
- Целевая оценка 5; выбранный трек 5: трек 2 «Согласованность двух
|
||||
хранилищ» (сверка bucket и БД — change `track2-reconciler`, стоимость
|
||||
обхода — change `track2-reconcile-cost`)
|
||||
- Commit/PR: ветка `solution/bvt2301-safronov`, PR «ЛР 4 — БВТ2301 —
|
||||
Сафронов — на 5» (ссылка — после публикации). Из чистого clone
|
||||
проверен commit `de98d77` (2026-10-29, итоговый код всех changes
|
||||
лабы 4): `evidence/tests/clean-clone-final.md`. После него менялись
|
||||
только документы и добавлен CI job (`.github/workflows/application.yml`,
|
||||
раздел «CI»); код приложения и стенда прежний.
|
||||
- Использованные источники, библиотеки и помощь ИИ: раздел «Источники,
|
||||
библиотеки и использование ИИ» в конце отчёта.
|
||||
|
||||
Сделано по changes OpenSpec (`openspec/changes/archive/`) поверх кода
|
||||
лабы 3:
|
||||
- `s3-storage` (уровни «3» и «4»): SeaweedFS в стенде с закреплённым
|
||||
образом и volume, приватный bucket с первой секунды, одноразовый
|
||||
идемпотентный `s3-bootstrap`, у API свой пользователь S3 с правами
|
||||
только на объекты bucket, служебные серверы на loopback, проверка
|
||||
приватности вне API `make s3_check`;
|
||||
- `attachments` (уровни «3» и «4»): загрузка PNG/JPEG сырыми байтами со
|
||||
структурной проверкой до записи, метаданные в PostgreSQL, скачивание
|
||||
только участникам, `attachment_ids` в сообщениях, тесты рубрики;
|
||||
- `upload-consistency` (уровень «4»): строка `pending` до PUT,
|
||||
компенсация в загрузке, отдельный сервис-уборщик незавершённых
|
||||
загрузок с grace 900 с и своим пользователем S3;
|
||||
- `upload-memory` (уровень «4»): места загрузки на реплику (4 + очередь
|
||||
16, затем 429), срок тела, одна копия тела при PUT, буферы сокетов и
|
||||
сроки LB пути загрузки, замер памяти при 1–40 одновременных загрузках;
|
||||
- `track2-reconciler` (уровень «5», трек 2): сверка bucket и БД с
|
||||
dry-run, исправлением, повторным запуском и пределом изменений,
|
||||
пометка потерянного оригинала;
|
||||
- `fix-upload-put-flake` (исправление уровня «4»): причина редких 503 на
|
||||
загрузке — срок чтения aiohttp портил соединение в пуле клиента S3;
|
||||
- `track2-reconcile-cost` (уровень «5», трек 2): гипотезы до замера,
|
||||
профиль стоимости обхода, стратегия «HEAD на строку», глубокая сверка
|
||||
по SHA-256, предел скорости, ранний отказ по пределу.
|
||||
|
||||
## Запуск из чистого clone
|
||||
|
||||
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
|
||||
**Версии.** Образ API: `python:3.12.14-slim-trixie` и `uv 0.12.17`; LB:
|
||||
`haproxy:3.4.6-trixie`; PostgreSQL: `postgres:18.6-trixie`; Valkey:
|
||||
`valkey/valkey:9.1.2-trixie`; S3: `chrislusf/seaweedfs:4.48`. Все
|
||||
закреплены тегом и digest индекса в `Dockerfile` и `docker-compose.yml`
|
||||
(таблица «Сервисы стенда» ниже). Приложение: Python 3.12, FastAPI
|
||||
0.141.1, uvicorn 0.54.0, pydantic 2.13.5, pydantic-settings 2.15.0,
|
||||
SQLAlchemy 2.1.1 (async), asyncpg 0.31.0, alembic 1.20.0, argon2-cffi
|
||||
25.1.0, redis-py 8.1.0, structlog 24.4.0, aiobotocore 3.9.2 (botocore
|
||||
1.43.106, aiohttp 3.14.5), остальное строго по `uv.lock`. Тесты: pytest
|
||||
9.1.1, httpx 0.28.1, Pillow 13.0.0 (JPEG в тестах); нагрузка: k6 2.3.0
|
||||
в контейнере (`grafana/k6:2.3.0@sha256:…`, `bench/run.py`). Проверено на
|
||||
Docker Desktop 29.9.2 (ВМ linux/arm64, 12 CPU, 7,7 GiB), macOS на Apple
|
||||
M3 Pro.
|
||||
|
||||
### S3 (change `s3-storage`)
|
||||
**Нужно на машине:**
|
||||
- Docker Engine 25+ с BuildKit и Compose v2, `make`, `openssl` (секреты
|
||||
в `make env_setup`), `curl`;
|
||||
- `python3` 3.9+ для публичных `make check`, `make test`, `make
|
||||
test-persistence`, `make test-failover` и для драйвера скилла (`make
|
||||
instances`, `make s3_check`, `driver.py …`) — только stdlib;
|
||||
- uv — для `make validate`, `make student_test`, `make test_isolated`,
|
||||
`make failure_checks`, стенда замеров `make bench*` и `make run_dev`;
|
||||
- свободные порты `127.0.0.1:8080` (LB), `5433` (PostgreSQL), `6380`
|
||||
(Valkey), `8334` (API S3) и `18088` (`make test_isolated`). Стенды
|
||||
лаб 2 и 3 занимают те же порты: перед запуском их останавливают
|
||||
(`make stop` в их каталоге). Другой порт LB — строкой `APP_OUT_PORT`
|
||||
в `.env` или аргументом make (`make run_docker APP_OUT_PORT=8090`),
|
||||
затем `make test BASE_URL=http://localhost:8090`.
|
||||
|
||||
**Подготовка и секреты.** `make env_setup` создаёт `.env` из
|
||||
`.env.example` и `config.toml` из `config_example.toml`. В шаблоне
|
||||
пароли PostgreSQL и Valkey и шесть секретов S3 пустые, в новый `.env`
|
||||
подставляются случайные (`openssl rand`): общего секрета стенда в git
|
||||
нет. Печатаются только имена. Отдельно запускать `env_setup` не
|
||||
обязательно: его вызывают `make run_docker`, `make run_dev`, `make
|
||||
test_isolated` и `make failure_checks`. Пароль PostgreSQL и
|
||||
административная пара S3 задаются при создании volume: после их смены
|
||||
нужен `make wipe_data`.
|
||||
|
||||
Последовательность проверяющего — та, что прошла из настоящего `git
|
||||
clone` (`evidence/tests/clean-clone-final.md`):
|
||||
|
||||
```sh
|
||||
git clone <fork> && cd <каталог clone> && git checkout solution/bvt2301-safronov
|
||||
make env_setup # .env (случайные пароли и секреты S3) и config.toml из шаблонов
|
||||
make run_docker # build + up -d: postgres, valkey, s3 → migrate, s3-bootstrap → api × 2 и cleaner → haproxy
|
||||
make replicas # дождаться healthy реплик; готовность стенда — haproxy (healthy)
|
||||
make check # структура skeleton
|
||||
uv sync && make validate PYTHON=.venv/bin/python # полная валидация OpenAPI 3.1
|
||||
make test # публичный smoke через LB: загрузка fixture, сообщение с attachment_ids, SHA-256, 404 постороннему
|
||||
make instances # ≥2 X-Instance-Id одной сессии через LB
|
||||
make s3_check # приватность bucket вне API: права ключей API и уборщика, аноним, порты S3
|
||||
make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт LB, реплик, PostgreSQL, Valkey и S3: те же данные и оригинал
|
||||
STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановлена одна реплика
|
||||
make replicas # вернуть остановленную реплику (тот же контейнер и ID)
|
||||
curl -s -o /dev/null http://127.0.0.1:8080/health/live # сдвиг очереди round-robin: тест выберет другую реплику
|
||||
STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановлена вторая
|
||||
make replicas
|
||||
python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 attachment-failover --mode stop # принявшая реплика остановлена: файл отдаёт другая
|
||||
python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 attachment-storage # байты только в приватном bucket, не в БД и не на диске API
|
||||
make student_test # свой набор через LB, тесты реплик выполняются
|
||||
make reconcile # сверка bucket и БД, dry-run: код 0 — расхождений нет
|
||||
make test_isolated # образ на временной базе test_messenger, один контейнер API: smoke + свой набор
|
||||
make failure_checks # проверки отказов на отдельном проекте mtusi-lab4-failures (~15 мин); рабочий стенд не трогается
|
||||
```
|
||||
|
||||
Ожидаемо — так прошло на `de98d77` (2026-10-29, все шаги с кодом 0):
|
||||
- `make check`, `make validate`, `make test`, `make test-persistence` и
|
||||
оба `make test-failover` — `PASS`. У `test-failover` `failed_attempts`
|
||||
0, восстановление 1,08 и 1,2 с;
|
||||
- `make instances` — `instances: 2`, по 6 ответов каждой реплики;
|
||||
- `make s3_check` — `PASS: 70 checks, bucket messenger is private`;
|
||||
- `attachment-failover` — загрузку приняла одна реплика, после её
|
||||
остановки файл отдала другая с тем же SHA-256, постороннему — 404;
|
||||
`attachment-storage` — `PASS`, файлов оригинала в контейнерах API 0;
|
||||
- `make student_test` — `198 passed`, сверка покрытия «252 scenarios in
|
||||
13 specs, 235 tested (70 by make failure_checks), 17 excluded»;
|
||||
- `make reconcile` — `found {}`, код 0;
|
||||
- `make test_isolated` — `193 passed, 5 skipped`: тесты реплик против
|
||||
одного процесса пропускаются с причиной;
|
||||
- `make failure_checks` — `56 passed` за ~14 мин и строка сводки журнала
|
||||
PostgreSQL стенда отказов `[failure_checks] postgres log: … crash
|
||||
markers 0`.
|
||||
|
||||
Строка `STOP_ONE_LOG` называет `TARGET_INSTANCE_ID`, который выбрал
|
||||
тест, и полный ID остановленного контейнера; `docker compose ps -a`
|
||||
показывает его `Exited`. Порт 8080 хоста был занят посторонним
|
||||
контейнером, поэтому клон поднимался на `APP_OUT_PORT=8090` под своим
|
||||
проектом compose; это две строки `.env` до `make env_setup`
|
||||
(`evidence/tests/clean-clone-final.md`).
|
||||
|
||||
Вариант README без make — те же compose-команды, но после `make
|
||||
env_setup`: без `config.toml` compose падает с `bind source path does
|
||||
not exist` (он монтируется read-only, `create_host_path: false`), без
|
||||
секретов — на «… is empty».
|
||||
|
||||
```sh
|
||||
make env_setup
|
||||
docker compose --env-file .env config --quiet
|
||||
docker compose --env-file .env up -d --build # тот же стенд, что make run_docker
|
||||
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/health/ready # 200 — готов
|
||||
```
|
||||
|
||||
### CI
|
||||
|
||||
Workflow skeleton `.github/workflows/contracts.yml` проверяет только
|
||||
контракт и не менялся. Сборку, стенд и `make test` ведёт свой job
|
||||
`.github/workflows/application.yml` (`CONTRIBUTING.md`, «CI») на раннере
|
||||
Gitea при каждом push в fork. Actions включены в настройках fork; в
|
||||
репозитории преподавателя они выключены, поэтому статуса job на самом PR
|
||||
нет — ссылка на прогон в описании PR.
|
||||
|
||||
Шаги job:
|
||||
1. checkout ровно commit прогона;
|
||||
2. `make env_setup`, `make run_docker`, `make replicas` под своим
|
||||
проектом compose `mtusi-lab4-safronov-ci-<run_id>`;
|
||||
3. готовность: `/health/ready` 200 через LB от двух разных
|
||||
`X-Instance-Id`;
|
||||
4. `make check`, `make test`;
|
||||
5. анонимный GET в S3 (список bucket и объектов) — 403;
|
||||
6. `make student_test` через LB, тесты реплик выполняются;
|
||||
7. `make test-persistence`;
|
||||
8. `make test-failover` в режимах `stop` и `kill`, после каждого —
|
||||
`make replicas`;
|
||||
9. при любом исходе — уборка стенда, его volumes и образа прогона.
|
||||
|
||||
Раннер (`act_runner`, образ `gitea/runner-images:ubuntu-latest`)
|
||||
запускает job в контейнере на том же Docker, что и стенд. Поэтому
|
||||
отличия от локального запуска собраны в override `.github/ci/compose.yml`:
|
||||
- bind mount файлов рабочего каталога (их нет на хосте раннера) заменены
|
||||
`configs` из переменных окружения — побайтная копия файла
|
||||
(`.github/ci/stand-env.sh`; без последнего перевода строки HAProxy
|
||||
конфиг не принимает);
|
||||
- порты на хост не публикуются: job подключается к сети стенда и ходит
|
||||
на `http://haproxy:8080`;
|
||||
- образ API — с тегом прогона, а не общим `mtusi-messenger:lab4`.
|
||||
|
||||
Секретов CI не получает: пароли и ключи — случайные из `make env_setup`
|
||||
и живут только в прогоне. Права токена — `contents: read`,
|
||||
`pull_request_target` нет. Прогоны идут по очереди и без отмены: прерванный
|
||||
job оставил бы стенд на общем хосте раннера, а шаг уборки хвостов удаляет
|
||||
только проекты с префиксом этого job. Без `make s3_check`, `make
|
||||
test_isolated`, `make failure_checks` и замеров: им нужны порты хоста и
|
||||
отдельные проекты, их вывод — в `evidence/`.
|
||||
|
||||
Шаги workflow как есть прошли в той же схеме локально: контейнер образа
|
||||
раннера с сокетом Docker, файлы скопированы внутрь. Все шаги — код 0 за
|
||||
~2,5 мин со сборкой из кэша: `make test` — `PASS`, `make student_test` —
|
||||
198 passed, `make test-persistence` и оба `make test-failover` — `PASS`
|
||||
(`evidence/tests/ci-application.md`).
|
||||
|
||||
### Сценарий защиты
|
||||
|
||||
```sh
|
||||
make test # 1–2. fixture, сообщение с attachment_ids, второй участник — тот же SHA-256, третий — 404 на метаданные и байты
|
||||
D=.claude/skills/run-mtusi-messenger/driver.py
|
||||
python3 $D --port 8080 upload --token <токен> --chat <id> --file tests/fixtures/sample.png # то же по шагам
|
||||
python3 $D --port 8080 download --token <токен второго участника> --attachment <id> # SHA-256 оригинала
|
||||
make s3_check # 2. прямой анонимный GET в S3 — 403 (с хоста и из сети стенда)
|
||||
make test-persistence ACTION_SCRIPT=scripts/restart.sh # 3. рестарт всего стенда: прежний токен, тот же оригинал
|
||||
python3 $D --port 8080 attachment-failover --mode kill # 3. загрузившая реплика убита: скачивание через другую, тот же SHA-256
|
||||
python3 $D --port 8080 attachment-storage # 4. схема, ключ, объект в bucket, docker diff реплик — файла оригинала нет
|
||||
# уровень 4
|
||||
python3 $D --port 8080 upload-consistency # S3 заморожен и сбой фиксации ready: 503, компенсация, уборщик убирает остатки
|
||||
make failure_checks # отказы S3, PostgreSQL, места загрузок, срок тела, уборщик, сверка (~15 мин)
|
||||
# уровень 5, трек 2
|
||||
python3 $D --port 8080 reconcile-cycle # расхождения с обеих сторон: dry-run, --apply, повтор = 0 (~2 мин)
|
||||
make reconcile # разовая сверка, dry-run; APPLY=1 — исправить
|
||||
make stop && make bench_reconcile_quick # самопроверка профиля стоимости (~4 мин); полная метка — evidence/reconcile/baseline/
|
||||
```
|
||||
|
||||
Полные метки уже лежат в `evidence/uploads/baseline/` и
|
||||
`evidence/reconcile/baseline/` (разделы «Одновременные загрузки» и
|
||||
«Стоимость сверки»), на защите показываются они: прогоны идут по
|
||||
~50 мин.
|
||||
|
||||
### Остановка и удаление данных
|
||||
|
||||
- `make stop` — остановить контейнеры; S3 останавливается плавно, ~15 с.
|
||||
- `make down` — удалить контейнеры; volumes `postgres_data` и `s3_data`
|
||||
остаются, кэш Valkey теряется (он без volume, данные от этого не
|
||||
страдают).
|
||||
- `make wipe_data` — удалить контейнеры и volumes
|
||||
`mtusi-lab4_postgres_data` и `mtusi-lab4_s3_data`, только после ввода
|
||||
`yes`; оба тома запрос называет по имени. Следующий `make run_docker`
|
||||
поднимает пустую базу со схемой и пустой приватный bucket.
|
||||
|
||||
### Старый `.env` и консоль (changes `s3-storage`, `upload-consistency`)
|
||||
|
||||
`make env_setup` создаёт новый `.env` из `.env.example` со случайными
|
||||
паролями PostgreSQL и Valkey и шестью секретами S3 и печатает только их
|
||||
@@ -50,17 +268,13 @@ S3_CLEANER_ACCESS_KEY S3_CLEANER_SECRET_KEY». Без них compose
|
||||
`127.0.0.1:8080`. В консоли S3 доступен на `127.0.0.1:8334`. Уборщика
|
||||
в консоли нет: зависшие загрузки консольного API убирает уборщик
|
||||
стенда (та же база) или разовый `docker compose run --rm --no-deps
|
||||
cleaner --once`.
|
||||
- `make stop` останавливает S3 плавно, ~15 с. `make down` volumes не
|
||||
трогает.
|
||||
- `make wipe_data` удаляет volumes `mtusi-lab4_postgres_data` и
|
||||
`mtusi-lab4_s3_data` только после ввода `yes`, оба тома запрос
|
||||
называет по имени.
|
||||
cleaner --once`. Порт 8080 занят HAProxy работающего стенда, поэтому
|
||||
перед `make run_dev` — `make stop` (или `docker compose stop
|
||||
haproxy`); свой набор против консоли — `make student_test
|
||||
EXPECT_REPLICAS=1`.
|
||||
|
||||
## Архитектура и решения
|
||||
|
||||
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
|
||||
|
||||
```
|
||||
клиент → 127.0.0.1:8080 → haproxy → api × 2 → postgres (метаданные, сессии, ключи идемпотентности)
|
||||
→ valkey (кэш карточек чатов)
|
||||
@@ -70,6 +284,89 @@ TODO: схема процессов/хранилищ, источник исти
|
||||
cleaner (долгоживущий, без портов) ──→ postgres (строки pending), s3 (их объекты)
|
||||
```
|
||||
|
||||
Источник истины — PostgreSQL: пользователи, чаты, сообщения, сессии,
|
||||
ключи идемпотентности и метаданные вложений (строка `attachments` с
|
||||
ключом объекта, размером, SHA-256 и статусом). S3 хранит только байты
|
||||
оригинала по ключу, который назначает сервер. Valkey — общий кэш
|
||||
неизменяемых карточек чатов, его отказ — обход в PostgreSQL. Реплики
|
||||
`api` одинаковы и взаимозаменяемы, порта на хосте у них нет; в памяти
|
||||
процесса нет ничего, от чего зависит ответ. Единственная точка входа —
|
||||
HAProxy.
|
||||
|
||||
**Что перенесено из лабы 3** (репозиторий `mtusi2026lab3-safronov`,
|
||||
ветка `solution/bvt2301-safronov`, commit `ce89eba`; здесь — commit
|
||||
`5d5d8f9` «carry lab 3 over») без изменения поведения, кроме
|
||||
перечисленного ниже:
|
||||
- из лабы 2: PostgreSQL как источник истины, миграции alembic отдельным
|
||||
сервисом `migrate`, регистрация с паролем (Argon2id в потоке), вход по
|
||||
Basic только на `POST /auth/sessions`, остальное — Bearer-сессия в
|
||||
таблице `sessions`, кэш карточки чата в Valkey, keyset-пагинация,
|
||||
формат ошибок контракта;
|
||||
- из лабы 3: HAProxy перед двумя репликами без портов на хосте,
|
||||
`X-Instance-Id` в каждом ответе, обязательный `Idempotency-Key` с
|
||||
ключом и сообщением в одной транзакции, замеренная цепочка таймаутов,
|
||||
поочерёдная замена `make rolling_update`, ранний обработчик SIGTERM,
|
||||
строгие курсор и UUID на входе;
|
||||
- свои тесты (`make student_test`, `make test_isolated`, `make
|
||||
failure_checks`) и стенд замеров `bench/` с профилями лаб 2 и 3.
|
||||
|
||||
Что изменилось при переходе 3 → 4:
|
||||
- переход API — вложения (`contracts/README.md`, «Вложения (с lab4)»):
|
||||
ручки загрузки, метаданных и скачивания, `attachment_ids` в сообщении
|
||||
(по умолчанию `[]`, прежние текстовые POST валидны), пустой текст
|
||||
только с вложением;
|
||||
- миграции только расширяют схему: `ef25d50b01a8` (таблицы
|
||||
`attachments` и `message_attachments`, ослабленное `NOT VALID`
|
||||
ограничение текста), `739b8f04d5fb` (частичный индекс строк `pending`
|
||||
`CONCURRENTLY`), `5c3e1f0a9b7d` (`attachments.lost_at`);
|
||||
- новые сервисы стенда: `s3`, одноразовый `s3-bootstrap`, уборщик
|
||||
`cleaner` на образе API; проект compose `mtusi-lab4`, образ
|
||||
`mtusi-messenger:lab4` — чтобы не подключиться к данным лабы 3;
|
||||
- хэш идемпотентности учитывает `attachment_ids` только непустым: ключ,
|
||||
сохранённый версией лабы 3, повторяется без 409;
|
||||
- `/health/ready` S3 не проверяет: отказ S3 — 503 только на путях
|
||||
вложений;
|
||||
- у HAProxy — свой `timeout server` 30 с пути загрузки и буферы
|
||||
сокетов, у реплик — буфер приёма сокетов 512 KiB, `ROLLOUT_DRAIN_TIMEOUT`
|
||||
90 с вместо 12 с.
|
||||
|
||||
**Транзакционные границы лабы 4.** У ручек вложений сессия БД — на шаг,
|
||||
а не на запрос: соединение пула не держится на время передачи байтов.
|
||||
Остальные ручки — одна сессия на запрос, как в лабе 3. Commit делает
|
||||
сервис, изоляция `READ COMMITTED`:
|
||||
|
||||
| Операция | Шаги |
|
||||
| --- | --- |
|
||||
| загрузка | проверки 401 → 400 → 404 → 415 → 413 без тела → место загрузки (иначе 429) → тело со счётчиком и сроком → проверка изображения и SHA-256 → tx1: `INSERT attachments` (`pending`, ключ) → commit → PUT в S3 → tx2: `pending` → `ready` только у непомеченной строки → commit → 201. Сбой между PUT и отправкой COMMIT — DELETE объекта и 503; исход COMMIT неизвестен — объект остаётся уборщику |
|
||||
| отправка сообщения | членство → вложения: все `ready` и этого чата (иначе 404) → захват ключа идемпотентности → `INSERT messages` → `INSERT message_attachments` одной вставкой → один commit |
|
||||
| метаданные и скачивание | строка `ready` и членство в чате вложения (иначе 404); байты — GET из S3 потоком, сессия БД к этому времени закрыта |
|
||||
| уборщик | на строку `pending` старше grace: tx пометки (`FOR UPDATE SKIP LOCKED`, `updated_at`) → commit; tx уборки: та же блокировка → DELETE объекта в S3 → DELETE строки → commit |
|
||||
| сверка | чтения — короткие сеансы на страницу; каждое действие — после перепроверки в БД и HEAD; пометка и снятие пометки — условный `UPDATE` колонки `lost_at` |
|
||||
|
||||
Подробно — разделы «Вложения», «Согласованность БД и S3» и «Сверка
|
||||
хранилищ» ниже.
|
||||
|
||||
### Соответствие переменных `.env.example`
|
||||
|
||||
`.env.example` skeleton предлагает «логические» имена и просит
|
||||
сопоставить их с настоящими. Критерий — кто читает значение: то, что
|
||||
читают compose и контейнеры зависимостей, живёт в `.env`, то, что читает
|
||||
только приложение, — в секциях `config.toml` (согласование 2026-09-29).
|
||||
Имена S3 и лимиты вложений — в таблице «Соответствие имён skeleton
|
||||
`S3_*`» ниже.
|
||||
|
||||
| Имя skeleton | Где у нас | Почему так |
|
||||
| --- | --- | --- |
|
||||
| `APP_HOST` | режим `APP__RUN_MODE`: console — `127.0.0.1`, docker — `0.0.0.0` (литерал в `environment` compose и `ENV` в `Dockerfile`) | адрес следует из режима; в `.env` режим не хранится, чтобы консоль и docker работали из одного файла |
|
||||
| `APP_PORT` | `APP__PORT` в `.env` (8080) — порт каждой реплики, на нём же healthcheck и проверки HAProxy; `APP_OUT_PORT` (8080) — порт на `127.0.0.1` хоста, его публикует только HAProxy | параметр приложения в формате настроек; внешний порт приложение не читает, поэтому без секции |
|
||||
| `APP_ENV` | не используется | окружение одно — учебный стенд |
|
||||
| `SESSION_TTL_SECONDS` | `[auth] session_ttl_seconds` в `config.toml`, по умолчанию 3600; разовая подмена — `AUTH__SESSION_TTL_SECONDS` | читает только приложение; мост из `.env` с этим именем окружение бы не перекрыло (`.claude/rules/settings.md`) |
|
||||
| `DATABASE_URL_FILE` | не используется: URL собирает приложение из `[database]`, адрес и порт в docker — `POSTGRES_HOST` / `POSTGRES_PORT`, пароль — мостом из `POSTGRES_PASSWORD` в `.env` | пароль нужен ещё и контейнеру PostgreSQL, поэтому один источник — `.env` |
|
||||
| `SESSION_STORE` | `postgres`: таблица `sessions`, общая для всех реплик, без кэша — отзыв мгновенный | другого хранилища сессий нет; Valkey без persistence стёр бы сессии рестартом |
|
||||
| `CACHE_URL_FILE` | не используется: адрес и порт Valkey — `VALKEY_HOST`, `VALKEY_PORT` и `VALKEY_OUT_PORT` в `.env`, пароль — мостом из `VALKEY_PASSWORD` в `[cache] password`; срок, окно пропуска и пул — `[cache]` | как у PostgreSQL: пароль нужен и серверу Valkey |
|
||||
| `IDEMPOTENCY_TTL_SECONDS` | `[idempotency] ttl_seconds` в `config.toml`, по умолчанию 86400 (24 ч); разовая подмена — `IDEMPOTENCY__TTL_SECONDS` | читает только приложение; срок меньше 86400 нарушает контракт и применяется только в проверках |
|
||||
| `API_REPLICAS` | `API_REPLICAS` в `.env` (2), `deploy.replicas: ${API_REPLICAS:-2}` сервиса `api`; Makefile — `API_REPLICAS ?= 2` (`make replicas`, `EXPECT_REPLICAS` тестов) | приложение его не читает, поэтому имя без секции |
|
||||
|
||||
### Роль S3 и её граница
|
||||
|
||||
S3 хранит только байты вложений, метаданные лежат в PostgreSQL. Пишет и
|
||||
@@ -82,9 +379,15 @@ S3 хранит только байты вложений, метаданные
|
||||
загрузки, срок тела, одна копия тела и сроки LB пути загрузки (раздел
|
||||
«Память и сроки загрузки»).
|
||||
|
||||
Сервер — SeaweedFS 4.48. Выбор и проба — `PLAN.md` (решение 1) и
|
||||
design change `s3-storage`. Три места, где SeaweedFS по умолчанию не
|
||||
приватен, закрыты:
|
||||
Сервер — SeaweedFS 4.48 (выбор подтверждён автором 2026-10-20). MinIO
|
||||
отвергнут: на 2026-10-20 его образы `minio/minio` и `minio/mc` из
|
||||
чистого clone не скачивались («pull access denied», `quay.io/minio` —
|
||||
401 без авторизации), а стенд должен подниматься из репозитория.
|
||||
RustFS моложе, и его bootstrap требует `mc` или своего кода подписи
|
||||
admin API; у SeaweedFS bucket и пользователи создаются `weed shell` из
|
||||
того же закреплённого образа. Проба до выбора — design change
|
||||
`s3-storage`. Три места, где SeaweedFS по умолчанию не приватен,
|
||||
закрыты:
|
||||
- без учётных записей S3 открыт анониму — административная пара задана
|
||||
в окружении сервера с первого старта;
|
||||
- master, filer и volume слушают все интерфейсы — `-ip.bind=127.0.0.1`;
|
||||
@@ -469,7 +772,7 @@ rate_limited` с `Retry-After: 1`, срок вышел — 429 по сроку;
|
||||
(у него одного `Retry-After`), 503 — «зависимость недоступна», и клиент
|
||||
не отличил бы занятые места от отказа S3. Места ограничивают
|
||||
одновременность, а не частоту, поэтому трактовка — открытый вопрос
|
||||
преподавателю (`PLAN.md`, `### upload-memory`, «Вопросы», п. 1).
|
||||
преподавателю (раздел «Открытые вопросы преподавателю», п. 1).
|
||||
|
||||
**Срок тела** — `[uploads] body_timeout_seconds` (30 с) на всё тело с
|
||||
момента, как загрузка заняла место (`asyncio.timeout` вокруг чтения);
|
||||
@@ -647,8 +950,8 @@ dry-run. Плановая — в сервисе `cleaner` при старте и
|
||||
— 201; после снятия пометки — снова 200 с байтами. Статус `lost` /
|
||||
`failed` отвергнут: контракт лабы 4 знает только `ready`, и прежние
|
||||
реплики упали бы на неизвестном значении при `make rolling_update`.
|
||||
**Это вопрос преподавателю** (`PLAN.md`, `### track2-reconciler`,
|
||||
«Вопросы», п. 1): в контракте рядом «Отсутствующий вариант ready-объекта
|
||||
**Это вопрос преподавателю** (раздел «Открытые вопросы преподавателю»,
|
||||
п. 2): в контракте рядом «Отсутствующий вариант ready-объекта
|
||||
— 404», «404 — объекта нет» и «Неожиданное исключение — 500». Сделан
|
||||
вариант по умолчанию; ответ «иначе» меняет одну ветку `open_content`,
|
||||
сценарий и тесты, но не сверку.
|
||||
@@ -774,6 +1077,45 @@ reconcile`) получил три аргумента; плановая свер
|
||||
| 2026-09-29 | Конфиг через pydantic-settings: окружение → `.env` → `config.toml` → дефолты, `config.toml` монтируется read-only, не в образе | `.claude/rules/settings.md`, `docker.md` |
|
||||
| 2026-10-20 | «Пустой текст» сообщения — и `""`, и из одних пробелов: с хотя бы одним вложением — 201 (текст как прислан), без вложений — 400 | спек `messages`, «Пробелы с вложением»; `CreateMessage`; `test_blank_text_with_attachment` |
|
||||
|
||||
### Открытые вопросы преподавателю
|
||||
|
||||
Контракт допускает две трактовки, ответа пока нет. Сделан вариант по
|
||||
умолчанию, ниже — что поменяет другой ответ. Подход и остальной код от
|
||||
ответа не зависят.
|
||||
|
||||
1. **Все места загрузки реплики заняты: 429 `rate_limited` или 503
|
||||
`unavailable`?** `contracts/openapi.json` у `uploadAttachment`
|
||||
допускает оба: 429 — «Ограничение частоты запросов», и только у него
|
||||
есть `Retry-After`; 503 — «Зависимость недоступна».
|
||||
`contracts/README.md` называет 429 факультативным ограничением
|
||||
запросов, а места ограничивают одновременность, а не частоту.
|
||||
- Сделано: 429 с `Retry-After: 1`. Из двух описаний к ограничению
|
||||
подходит только 429. 503 клиент не отличил бы от отказа S3.
|
||||
- Ответ «503» меняет `DOMAIN_ERRORS` и `RETRY_AFTER` в
|
||||
`src/api/errors.py`, проверку `Retry-After` в
|
||||
`student-tests/contract.py`, ожидания `test_upload_slots_busy` и
|
||||
`test_rejections_before_queue`, сценарии спеков `attachments` и
|
||||
`api-conventions` и правило `api-contract.md`.
|
||||
2. **Что отвечает API на вложение, чей оригинал по сверке потерян**
|
||||
(объекта нет, он другого размера или с другим SHA-256)? У
|
||||
`Attachment.status` в лабе 4 одно значение — `ready`: `failed` и 409
|
||||
появляются с лабы 5. `contracts/README.md` пишет: «Отсутствующий
|
||||
вариант ready-объекта — 404», «404 — объекта нет», «Неожиданное
|
||||
исключение — 500».
|
||||
- Сделано, вариант (а): метаданные — 200 как раньше, байты — 404
|
||||
`not_found`, как у отсутствующего варианта, ссылка в новом
|
||||
сообщении — 201. До пометки сверкой байты — 500: расхождение
|
||||
непредвиденное.
|
||||
- Другие варианты: (б) вложение целиком как незавершённое —
|
||||
метаданные, байты и ссылка дают 404; (в) байты — 500 и после
|
||||
пометки, пометка только для отчёта. Каждый меняет ветку `lost_at` в
|
||||
`AttachmentService.open_content`, для (б) — ещё `get_attachment` и
|
||||
выборку вложений сообщения. Меняются и сценарий `attachments`
|
||||
«Потерянный оригинал», и ожидания `test_reconcile_finds_and_fixes`,
|
||||
`test_reconcile_keeps_fresh_used_and_unknown`,
|
||||
`test_reconcile_restored_original` и `driver.py reconcile-cycle`.
|
||||
Классы, правила безопасности и схема сверки остаются прежними.
|
||||
|
||||
### Ответы на вопросы защиты
|
||||
|
||||
- **Почему файл в Docker volume одной API-реплики не равен объектному
|
||||
@@ -870,8 +1212,8 @@ student_test` через LB (197 passed, сверка 215 / 200 / 36 / 15) и
|
||||
«узкого» API стенда отказов 3 с вместо 2 с, код приложения прежний)
|
||||
переснято `make failure_checks` (37 / 37). Строки сверки хранилищ (change
|
||||
`track2-reconciler`, трек 2) — с `c1648d9` на рабочем стенде после
|
||||
порядка обновления change (`evidence/reconcile/`, `evidence/s3/cleaner-
|
||||
list.md`, `evidence/migrations/lost-at.md`); с того же commit снят `make
|
||||
порядка обновления change (`evidence/reconcile/`,
|
||||
`evidence/s3/cleaner-list.md`, `evidence/migrations/lost-at.md`); с того же commit снят `make
|
||||
test_isolated` (`evidence/tests/`). После правок по verify (`84f8c35`:
|
||||
сверка и тесты отказов, код API прежний) переснято `make failure_checks`
|
||||
(48 / 48) и `make student_test` через LB. После change
|
||||
@@ -886,14 +1228,17 @@ student_test` через LB после замены реплик. После п
|
||||
|
||||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||||
| --- | --- | --- | --- |
|
||||
| Публичный smoke | `make test` (через LB и в `make test_isolated`) | `PASS: lab4 public API scenario` — загрузка fixture, сообщение с `attachment_ids`, SHA-256 скачанного оригинала, 404 постороннему | `evidence/attachments/smoke.md`, `evidence/tests/test-isolated-s3-cleanup.md` (раздел 0) |
|
||||
| Публичный smoke | `make test` (через LB и в `make test_isolated`), в том числе из чистого clone на `de98d77` | `PASS: lab4 public API scenario` — загрузка fixture, сообщение с `attachment_ids`, SHA-256 скачанного оригинала, 404 постороннему | `evidence/attachments/smoke.md`, `evidence/tests/clean-clone-final.md`, `evidence/tests/test-isolated-s3-cleanup.md` (раздел 0) |
|
||||
| Стенд собирается и проходит проверки из чистого clone | `git clone` во временный каталог, последовательность раздела «Запуск из чистого clone» (`de98d77`, 2026-10-29) | все шаги — код 0: `make check`, `make validate`, `make test`, `make instances` (2 реплики), `make s3_check` (70), `make test-persistence`, `make test-failover` × 2, `attachment-failover`, `attachment-storage`, `make student_test` (198), `make reconcile` (`found {}`), `make test_isolated` (193 + 5), `make failure_checks` (56, `crash markers 0`); секретов `.env` в журнале — 0 | `evidence/tests/clean-clone-final.md` |
|
||||
| CI: сборка, стенд и `make test` в отдельном job (`CONTRIBUTING.md`, «CI») | `.github/workflows/application.yml` на раннере Gitea; шаги workflow в контейнере образа раннера с сокетом Docker, файлы скопированы внутрь | стенд с конфигами из `configs` и без портов хоста, обе реплики в LB; `make check`, `make test` — `PASS`; аноним в S3 — 403; `make student_test` — 198 passed (тесты реплик выполнены); `make test-persistence`, `make test-failover` `stop` и `kill` — `PASS`, `failed_attempts` 0; после уборки ни контейнеров, ни volumes, ни образа прогона | `evidence/tests/ci-application.md` |
|
||||
| «3»: метаданные в PostgreSQL, байты в приватном bucket, не в БД и не на диске API | `driver.py --port 8080 attachment-storage` | из `bytea` только `sha256` (32 байта), `object_key` = `messenger/attachments/<id>/original` без `filename`, объект в bucket 111 817 байт, анонимный GET ключа — 403, `docker diff` реплик — только `config.toml`; открыли bucket анониму — код 1 «anonymous GET … got 200», bootstrap закрыл — код 0 | `evidence/attachments/storage.md` |
|
||||
| «3»: POST вложения → 201 `ready` после сохранения; оригинал побайтно; `attachment_ids` читают участники; посторонний — 404 | `make test`; `driver.py upload` Алисой, `download` Бобом и Евой | 201 `status=ready`, `variants=[]`, `sha256` 99ea7533…; Боб — 200 `image/png`, 111 817 байт, тот же SHA-256 (отдала другая реплика); Ева — 404 на метаданные и байты | `evidence/attachments/smoke.md` |
|
||||
| «3»: реальные PNG/JPEG ≤10 MiB и ≤40 млн пикселей, MIME по содержимому, опасные `filename`, лимиты до чтения и распаковки | `make student_test` через LB (`test_attachments.py`, 33 теста) | 10 485 760 байт — 201, +1 — 413; 30 MiB с `Content-Length` и частями — 413; 8000 × 5000 — 201, 40 000 001+ — 413; «бомба» — 415 (распаковано не больше ожидаемого объёма + 1 байт); текст, GIF, пустое тело, подмена MIME — 415; `filename` с `/`, `\`, NUL, `\n`, DEL, U+0085, пустой, 256 — 400; `a%FFb.png`, `a%C3.png`, `a%ED%A0%80b.png` — 400; U+202E, U+2066, U+2028 — 201 как есть | `evidence/tests/student-test-lb.md` |
|
||||
| «3»: остановка загрузившей реплики → download через другую | `driver.py --port 8080 attachment-failover --mode stop` и `--mode kill` | загрузку принял `5f5d4ac50d9a`, `stop-one.sh` его остановил (`stop` и `kill`), метаданные и байты — 200 от `847ad74efd7c`, SHA-256 совпал, посторонний — 404; после `make replicas` обе `UP` | `evidence/attachments/failover.md` |
|
||||
| «3»: restart с volumes сохраняет метаданные и оригинал | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` (`LAB=4`) | PASS: прежний токен читает данные, оригинал вложения тот же; `StartedAt` новый у всех шести контейнеров (API, LB, PostgreSQL, Valkey, S3) | `evidence/replicas/test-persistence.md` |
|
||||
| «3»: failover с записью | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` (каждая реплика, `stop` и `kill`, `STOP_ONE_LOG`) | 4 × PASS, `failed_attempts` 0, восстановление 0,76–1,2 с; `STOP_ONE_LOG` — оба контейнера | `evidence/failover/test-failover.md` |
|
||||
| «4»: тесты большого файла, повреждённого изображения, подмены MIME, чужого `attachment_id`, вложения другого чата; ошибка клиента не 500 | `make student_test` через LB (`test_rubric.py`: пять сценариев лабы 4), `make test_isolated` | 198 passed через LB (`b5983f0`, восемь прогонов подряд после замены реплик — без падений, «Object storage is unavailable» в журнале реплик 0 при 536 загрузках), 193 passed + 5 пропусков тестов реплик в одном процессе (`723b6c3`); каждая ошибка — 4xx в формате контракта; сверка покрытия: 244 сценария 13 спеков, 227 тестами (62 — проверками отказов), 17 исключений | `evidence/tests/student-test-lb.md`, `evidence/tests/test-isolated-s3-cleanup.md` (раздел 0, пересъёмка на `723b6c3`) |
|
||||
| «3»: failover с записью | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` (каждая реплика, `stop` и `kill`, `STOP_ONE_LOG`) | 4 × PASS, `failed_attempts` 0, восстановление 0,76–1,2 с; `STOP_ONE_LOG` — оба контейнера; из чистого clone — ещё 2 × PASS (`stop`, обе реплики по очереди, 1,08 и 1,2 с) | `evidence/failover/test-failover.md`, `evidence/tests/clean-clone-final.md` |
|
||||
| «3»: обязательные возможности лаб 2 и 3 сохранены | `make student_test` через LB (`test_identification.py`, `test_idempotency.py`, `test_load_balancing.py`, `test_race.py`, `test_chat_cache.py`), `make instances`, `driver.py auth-storage`, повтор отправки после `--force-recreate api` | Basic только на вход, Bearer на остальном, `X-User-Id` игнорируется; `X-Instance-Id` в каждом ответе, одна сессия на обеих репликах (`instances: 2`, 6 / 6); повтор с тем же `Idempotency-Key` через другую реплику и после пересоздания реплик — тот же `Message`, гонка 10 клиентов с одним ключом — одно сообщение; Argon2id в `users`, SHA-256 токена в `sessions`; кэш карточки — одно чтение `chats` на 50 | `evidence/tests/student-test-lb.md`, `evidence/tests/clean-clone-final.md`, `evidence/auth/passwords-and-tokens.md`, `evidence/idempotency/replay-after-restart.md`, `evidence/cache/hits.md` |
|
||||
| «4»: тесты большого файла, повреждённого изображения, подмены MIME, чужого `attachment_id`, вложения другого чата; ошибка клиента не 500 | `make student_test` через LB (`test_rubric.py`: пять сценариев лабы 4), `make test_isolated` | 198 passed через LB (`b5983f0`, восемь прогонов подряд после замены реплик — без падений, «Object storage is unavailable» в журнале реплик 0 при 536 загрузках), 193 passed + 5 пропусков тестов реплик в одном процессе (`723b6c3`); каждая ошибка — 4xx в формате контракта; из чистого clone на `de98d77` — 198 passed через LB и 193 + 5 в `make test_isolated`, сверка покрытия: 252 сценария 13 спеков, 235 тестами (70 — проверками отказов), 17 исключений | `evidence/tests/student-test-lb.md`, `evidence/tests/test-isolated-s3-cleanup.md` (раздел 0, пересъёмка на `723b6c3`), `evidence/tests/clean-clone-final.md` |
|
||||
| «4»: отказы S3 на путях вложений, отклонённая загрузка ничего не оставляет | `make failure_checks` | 49 / 49, код 0 (`723b6c3`, 552 с): S3 остановлен — загрузка 503, ровно одна новая строка `pending`, готовые те же, текст 201; скачивание 503, метаданные 200, история с `attachment_ids` 200, `/health/ready` 200; S3 заморожен — 503 не позже 5,6 с; отклонённые загрузки — ни новых строк, ни новых объектов (списки `id`); рабочий стенд не тронут | `evidence/tests/failure-checks.md` |
|
||||
| «4»: прерывание загрузки и отказ между S3 и БД не оставляют вечных неучтённых объектов | `make failure_checks` (стенд отказов: уборщик с grace 20 с, интервал 1 с) | сбой записи строки (SQLSTATE 08006) — 503, ни строки, ни объекта; обрыв клиента посреди тела — ни строки, ни объекта; сбой фиксации `ready` — 503, объекта нет сразу (компенсация), строка `pending` не видна по API, на G/2 ещё на месте, после G + I + 5 с убрана; S3 заморожен на время PUT — строка убрана после grace, объект не появился; kill реплики между PUT и фиксацией — 201 не дошёл, строка и объект есть до grace, после — ни того, ни другого; COMMIT `ready` упал (отложенный триггер) — 503, объект на месте (исход неизвестен), после grace убран; загрузка дольше grace (строка «старше» на час, уборщик убрал её, пока перевод в `ready` ждал) — 503, а не 201 и не 500, ни строки, ни объекта; уборщик удалил объект, а удаление строки упало в той же транзакции уборки — 503, а не 201, `ready` без объекта нет, следующий проход доводит уборку; во всех — объектов без строки 0 (`object-ids − attachment-ids`); красный прогон до кода — 4 из 11 упали; тесты по verify: W1 — 201 на коде `f2dc0b3`, W2 и W3 — красные на временных регрессиях (компенсация на любой сбой, `RuntimeError` → 500) | `evidence/tests/failure-checks.md` |
|
||||
| «4»: то же на рабочем стенде через LB | `driver.py --port 8080 upload-consistency` | S3 заморожен — 503 за 5,1 с, строка `pending` с ключом; сбой фиксации `ready` — 503, объекта нет; обе строки — 404 на метаданные, байты и ссылку; `cleaner --once` (grace 30 с) — `removed 2`, код 0; строк и объектов нет, «1200 objects, 1200 rows, 0 objects without a row»; готовое вложение — тот же SHA-256; в журнале API шаги `put` / `ready` и «Deleted attachment object», `filename` — 0 вхождений | `evidence/attachments/consistency.md` |
|
||||
@@ -929,11 +1274,33 @@ student_test` через LB после замены реплик. После п
|
||||
| «5», трек 2: влияние сверки на фоновую нагрузку | та же метка, этап D: 300 скачиваний + 50 записей + 50 чтений в секунду, 4 варианта CPU уборщика и предела | H4 **не проверена**: все r ≤ 1,08, a 0,96–1,06, 5xx нет, но контраст `fast-unlimited` (1 CPU, без предела) дал r скачиваний 1,08 при пороге > 1,5 — метод влияния не показал; предел 2000 держит CPU S3 за проход 0,27–0,32 ядра при любом CPU уборщика (без него — 0,42–0,73) ценой прохода в 2,2–4 раза дольше | `evidence/reconcile/baseline/summary.md`, `passes.csv`, `windows.csv` |
|
||||
| «5», трек 2: `head`, глубокая, возврат по SHA-256, предел скорости, ранний отказ | `make failure_checks` (5 проверок и 2 по замечаниям verify, `ca0c4b2`); красные прогоны на `7f4e626` и `16f2cde`; `driver.py reconcile-signal --pace [--apply]` (временный проект) | 56 из 56 за 877 с; на `7f4e626` — 5 из 5 упали по ожидаемым причинам (argparse, нет поля `deep`, пометку снял объект того же размера, `changes` 7 вместо 3); на `16f2cde` — 2 из 2 (`batch` не сравнил строку с чужим `<Z>/original`, помечен только что перезаписанный объект); `docker stop` во время паузы предела 1 объект/с — код 1, `interrupted_by: stop`, выход через 0,06 с, ключи страницы в итоге, а с `--apply` каждое удалённое — «Fixed» (4 из 4; на `16f2cde` — 3 из 4) | `evidence/tests/failure-checks.md`, `evidence/reconcile/service.md` |
|
||||
|
||||
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
|
||||
Какие процессы и хранилища перезапускает restart hook, подтверждено
|
||||
отдельно, а не только `PASS` теста: `StartedAt` у LB, обеих реплик,
|
||||
PostgreSQL, Valkey и S3 новый, ID контейнеров прежние
|
||||
(`evidence/replicas/test-persistence.md`, `evidence/s3/restart.md`); в
|
||||
проверке из чистого clone — время работы этих контейнеров после hook
|
||||
меньше его длительности, а у уборщика, которого hook не трогает, —
|
||||
прежнее (`evidence/tests/clean-clone-final.md`).
|
||||
|
||||
## Эксперименты и отказы
|
||||
|
||||
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
|
||||
Два замера с гипотезами, записанными и закоммиченными до прогонов. У
|
||||
каждого в своём разделе ниже — хост и лимиты контейнеров, версии,
|
||||
объём данных, профиль и интенсивность нагрузки, окна и прогрев,
|
||||
повторы, коды ответов, p50 / p95 / p99, CPU и память, выводы и
|
||||
ограничения. Сырые итоги без токенов лежат в каталогах меток:
|
||||
- **память при одновременных загрузках** (уровень «4»: «≥ 10
|
||||
одновременных загрузок с измерением пика памяти») — `make
|
||||
bench_uploads`, метка `evidence/uploads/baseline/`, разделы
|
||||
«Одновременные загрузки: гипотезы» и «… результаты»;
|
||||
- **стоимость сверки bucket и БД** (уровень «5», трек 2: «измерьте
|
||||
стоимость обхода») — `make bench_reconcile`, метка
|
||||
`evidence/reconcile/baseline/`, разделы «Стоимость сверки: гипотезы» и
|
||||
«… результаты».
|
||||
|
||||
Таблица ниже — отказы и пробы: внесённое воздействие, ожидание,
|
||||
наблюдение и потери. Команды и полные выводы — в файлах таблицы
|
||||
«Доказательства критериев».
|
||||
|
||||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -1419,7 +1786,63 @@ CPU S3 в ней нет). Естественная скорость `batch` на
|
||||
|
||||
## Ограничения и следующие шаги
|
||||
|
||||
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
|
||||
**Какие отказы стенд выдерживает** (подтверждено проверками, таблица
|
||||
«Доказательства критериев»):
|
||||
- остановка, `kill` и заморозка одной реплики API: LB уводит запросы,
|
||||
запись восстанавливается за 0,76–1,2 с без дублей, вложение отдаёт
|
||||
другая реплика с тем же SHA-256;
|
||||
- отказ S3 (остановлен, заморожен, нет bucket, отказ в доступе): 503
|
||||
только на загрузке и скачивании байтов, а текст, история, метаданные
|
||||
и `/health/ready` работают;
|
||||
- отказ PostgreSQL или процесса API посреди загрузки, обрыв клиента,
|
||||
медленный клиент: ответ 503 или 4xx, а не 201 и не 500; неучтённых
|
||||
объектов старше grace + интервал не остаётся (компенсация, уборщик,
|
||||
сверка);
|
||||
- отказ Valkey: обход кэша;
|
||||
- рестарт всего стенда с volumes: данные, прежние сессии и оригиналы
|
||||
вложений целы.
|
||||
|
||||
**Чего стенд не выдерживает:** отказ хоста или ВМ Docker, единственного
|
||||
HAProxy и единственного PostgreSQL (без него API отвечает 503, LB
|
||||
выводит реплики), потерю диска S3 (одна нода без репликации). Один
|
||||
Docker-host — не отказоустойчивость к потере этого host (`COURSE.md`).
|
||||
|
||||
**Что не реализовано:**
|
||||
- трек 1 «Прямой upload» — выбран один трек 5, трек 2;
|
||||
- в CI нет `make s3_check`, `make test_isolated`, `make failure_checks`
|
||||
и замеров `bench/`: им нужны порты хоста, отдельные проекты и десятки
|
||||
минут (раздел «CI» в «Запуск из чистого clone»). Их выводы — в
|
||||
`evidence/`;
|
||||
- Swarm: стенд — один проект Compose;
|
||||
- полное декодирование изображения, превью и асинхронная обработка —
|
||||
лаба 5; лимит одновременных скачиваний — вне лабы.
|
||||
|
||||
**Учебные упрощения:** один хост, генератор нагрузки на нём же; одна
|
||||
нода S3 без fsync; секреты в `.env` и видны в `docker inspect`; HTTP без
|
||||
TLS (лаба 7).
|
||||
|
||||
**Подтверждено и гипотеза.** Замер загрузок: H1–H4 подтверждены —
|
||||
с местами загрузки пик реплики при 40 × 10 MiB — 181,3 MiB (медиана),
|
||||
а без них реплику убивает OOM. Замер сверки: H1, H2, H3 и S4 подтверждены, H4
|
||||
**не проверена** — контраст без предела не насытил S3, поэтому предел
|
||||
скорости 2000 — страховка доли CPU шлюза, а не доказанная защита задержек
|
||||
фона.
|
||||
|
||||
**Известные дефекты** (`KNOWN_ISSUES.md`, четыре открытые записи, ни
|
||||
одна не затрагивает стенды проекта в штатной работе):
|
||||
- повторный bootstrap после удаления bucket на маленьком tmpfs падает на
|
||||
«api key wait (code 500)» — не хватает слотов томов SeaweedFS;
|
||||
- уборщик удаляет объект зависшей загрузки по ключу вне своего префикса
|
||||
(бывает только в базе, восстановленной под другим именем);
|
||||
- LB отвечает 408 на медленные заголовки страницей HAProxy, а не в
|
||||
формате контракта;
|
||||
- поля `float` настроек принимают `inf`.
|
||||
|
||||
**Следующие шаги:** ответы на открытые вопросы преподавателю; новая
|
||||
метка сверки с контрастом, который насыщает S3 (S3 0,5 CPU или фон в
|
||||
2–3 раза больше), — проверка H4; исправление записей `KNOWN_ISSUES.md`;
|
||||
лаба 5 — 202, worker и staging-prefix, где сверке прибавятся варианты
|
||||
под префиксом вложения.
|
||||
|
||||
S3 (change `s3-storage`):
|
||||
- **Одна нода S3 без репликации и fsync.** SIGKILL процесса
|
||||
@@ -1549,8 +1972,8 @@ S3 (change `s3-storage`):
|
||||
получить 429 при полной очереди; затем она берёт место, сразу
|
||||
заканчивается `interrupted` и отпускает его (проба verify). Места
|
||||
загрузки она не держит дольше обычной.
|
||||
- **429 или 503 — вопрос преподавателю открыт** (`PLAN.md`, «Вопросы»,
|
||||
п. 1). Ответ «503» поменяет строку таблицы ошибок, сценарии спеков и
|
||||
- **429 или 503 — вопрос преподавателю открыт** (раздел «Открытые
|
||||
вопросы преподавателю», п. 1). Ответ «503» поменяет строку таблицы ошибок, сценарии спеков и
|
||||
ожидания тестов, но не подход.
|
||||
- **Тело отклонённой загрузки реплика дочитывает и выбрасывает**
|
||||
(uvicorn держит соединение): памяти это не стоит (буферы ограничены),
|
||||
@@ -1628,7 +2051,7 @@ S3 (change `s3-storage`):
|
||||
(одни часы), точность `LastModified` — секунда; `updated_at` строк
|
||||
консольного API на macOS расходится на секунды — меньше grace.
|
||||
- **Ответ API на потерянный оригинал — трактовка контракта**, вопрос
|
||||
преподавателю открыт (раздел «Сверка хранилищ»).
|
||||
преподавателю открыт (раздел «Открытые вопросы преподавателю», п. 2).
|
||||
- **Старый образ уборщика после `make rolling_update`** — сверки нет, как
|
||||
до change; новый — `docker compose up -d --no-deps cleaner` (порядок
|
||||
обновления).
|
||||
@@ -1664,3 +2087,133 @@ S3 (change `s3-storage`):
|
||||
dry-run, он перепроверяет всех.
|
||||
- **`make failure_checks` — ещё ~4 мин** (56 проверок, ~15 мин): семь
|
||||
проверок сверки change ждут grace стенда.
|
||||
|
||||
## Источники, библиотеки и использование ИИ
|
||||
|
||||
**Документация и спецификации**, по которым приняты решения. Ссылки —
|
||||
на корень документации, нужный раздел назван словами. Поведение
|
||||
стенда при этом проверено пробами и тестами, их выводы — в
|
||||
`evidence/`:
|
||||
- Amazon S3 — <https://docs.aws.amazon.com/AmazonS3/latest/userguide/>
|
||||
(из `README.md` задания): загрузка объектов, presigned URL (почему не
|
||||
трек 1), политики bucket с условием `s3:prefix`; API Reference —
|
||||
`ListObjectsV2`, `HeadObject`, `DeleteObject`.
|
||||
- SeaweedFS 4.48 — <https://github.com/seaweedfs/seaweedfs> (wiki и
|
||||
исходники): шлюз S3, учётные записи и политики IAM, `weed shell`
|
||||
(`s3.bucket.create`, `s3.anonymous.set`, `fs.ls`, `fs.rm`), ключ
|
||||
подписи `WEED_JWT_FILER_SIGNING_KEY`, `-ip.bind`, метрики шлюза.
|
||||
- aiobotocore — <https://aiobotocore.aio-libs.org/>, botocore `Config`
|
||||
(`connect_timeout`, `read_timeout`, `retries`, `max_pool_connections`);
|
||||
исходники aiohttp 3.14.5 — `resume_reading()` и таймер `sock_read`
|
||||
(причина flake, `evidence/s3/idle-connection.md`).
|
||||
- PNG — <https://www.w3.org/TR/png/> (чанки, CRC, IHDR, фильтры строк,
|
||||
Adam7), zlib — RFC 1950 / 1951 и `zlib.decompressobj(max_length)`
|
||||
Python; JPEG — ITU-T T.81 (маркеры, SOF, длины сегментов).
|
||||
- PostgreSQL 18 — <https://www.postgresql.org/docs/18/>: частичные
|
||||
индексы, `CREATE INDEX CONCURRENTLY`, `SELECT … FOR UPDATE SKIP
|
||||
LOCKED`, `ALTER TABLE … ADD COLUMN` под `lock_timeout`, `NOT VALID`
|
||||
ограничения, `pg_stat_database`.
|
||||
- HAProxy 3.4 — <https://docs.haproxy.org/>: `http-request
|
||||
set-timeout`, `tune.sndbuf.server`, `tune.rcvbuf.client`,
|
||||
`http-error`, `timeout http-request`.
|
||||
- Linux — [cgroup v2](https://docs.kernel.org/admin-guide/cgroup-v2.html)
|
||||
(`memory.peak`, `memory.stat` `anon` / `sock`, `memory.events`
|
||||
`oom_kill`), [ip-sysctl](https://docs.kernel.org/networking/ip-sysctl.html)
|
||||
(`tcp_rmem`); glibc
|
||||
[mallopt](https://man7.org/linux/man-pages/man3/mallopt.3.html)
|
||||
(`M_MMAP_THRESHOLD`, переменная `MALLOC_MMAP_THRESHOLD_`).
|
||||
- Starlette — `Request.stream()`; k6 —
|
||||
<https://grafana.com/docs/k6/latest/> (`constant-vus`,
|
||||
`constant-arrival-rate`).
|
||||
- Из лаб 2 и 3 — FastAPI, uvicorn, SQLAlchemy, asyncpg, alembic,
|
||||
argon2-cffi, redis-py, Valkey, Docker Compose (источники перечислены в
|
||||
отчётах этих лаб).
|
||||
|
||||
**Библиотеки и образы:** FastAPI, pydantic, pydantic-settings,
|
||||
structlog, SQLAlchemy, asyncpg, alembic, argon2-cffi, redis-py,
|
||||
aiobotocore, uvicorn (версии — раздел «Запуск из чистого clone»); тесты
|
||||
— pytest, httpx, Pillow; стенд — HAProxy, PostgreSQL, Valkey,
|
||||
SeaweedFS, k6 в закреплённых образах. Проверка изображения — свой код на
|
||||
stdlib (`src/utils/image.py`), без библиотек декодирования. Сторонний
|
||||
код в репозиторий не копировался.
|
||||
|
||||
**Использование ИИ.** Инструмент — Claude Code, модель Claude Opus 5.5.
|
||||
Работа велась по changes OpenSpec (`openspec/changes/archive/`, семь
|
||||
changes лабы 4: `s3-storage`, `attachments`, `upload-consistency`,
|
||||
`upload-memory`, `track2-reconciler`, `fix-upload-put-flake`,
|
||||
`track2-reconcile-cost`). Все семь в архиве, спеки синхронизированы,
|
||||
активных changes нет. Каждый change проходил этапы propose → apply →
|
||||
verify → правки по verify → archive. Каждый этап выполнял отдельный
|
||||
субагент, основная сессия координировала: передавала этапы, проверяла
|
||||
итоги, коммитила на ветке `feat/<change>` и вливала её в основную,
|
||||
присылала автору прогресс. Все commit после переноса лабы 3
|
||||
(`5d5d8f9`) помечены `Co-Authored-By: Claude Opus 5.5`. Рабочий план
|
||||
лабы (`PLAN.md`: рубрика → changes, ключевые решения, трек 5, риски,
|
||||
вопросы по ходу changes) удалён после закрытия всех changes. Его итоги
|
||||
перенесены в этот отчёт и в design архивных changes, открытые вопросы —
|
||||
в раздел «Открытые вопросы преподавателю». Последняя версия плана —
|
||||
`git show fd03b84:PLAN.md`, на неё ссылаются архивные changes и ранние
|
||||
файлы `evidence/`.
|
||||
|
||||
Что делал ИИ:
|
||||
- код приложения и уборщика, миграции, `docker-compose.yml`,
|
||||
`haproxy.cfg`, `infra/s3/bootstrap.sh`, скрипты стенда;
|
||||
- собственные тесты `student-tests/`, стенд проверок отказов и его hook;
|
||||
- профили `uploads` и `reconcile` стенда замеров `bench/`, сэмплер
|
||||
памяти, сводки и графики;
|
||||
- драйвер проверок (`driver.py s3-check`, `attachment-failover`,
|
||||
`upload-consistency`, `reconcile-cycle` и другие), запуск замеров и
|
||||
проверок, evidence, этот отчёт, правила `.claude/rules/` и спеки
|
||||
OpenSpec;
|
||||
- CI job `application` и override стенда для раннера Gitea; схему
|
||||
раннера (job — контейнер рядом со стендом) ИИ установил по журналу
|
||||
публичного прогона на этом Gitea и повторил локально.
|
||||
|
||||
Что решал автор:
|
||||
- трек 2 «Согласованность двух хранилищ» и SeaweedFS вместо MinIO
|
||||
(2026-10-20); `/health/ready` без S3 и уборщик — отдельный сервис, а
|
||||
не фоновая задача реплик (2026-10-20);
|
||||
- проверка изображения структурная, без полного декодирования;
|
||||
`filename` отклоняется только по правилу контракта (`/`, `\`, NUL и
|
||||
категория Cc), символы направления текста принимаются (2026-10-20);
|
||||
- текст из пробелов с вложением — вопрос преподавателю (ответ —
|
||||
«Согласования с преподавателем», 2026-10-20);
|
||||
- метку `uploads` принять с предупреждением о swap хоста (2026-10-22)
|
||||
и после `fix-upload-put-flake` полную метку не переснимать
|
||||
(2026-10-23);
|
||||
- добавить CI job по `CONTRIBUTING.md`, «CI», и включить Actions в fork
|
||||
(2026-10-29);
|
||||
- все замечания каждого verify — в правки, без отдельного согласования;
|
||||
работа в автономном режиме. Решения, принятые основной сессией без
|
||||
автора, отмечены в design changes как принятые без пользователя
|
||||
(например, дописывание недостающих переменных в существующий `.env`,
|
||||
2026-10-21; варианты по умолчанию в открытых вопросах преподавателю).
|
||||
|
||||
Как проверялось:
|
||||
- verify каждого change отдельным субагентом: сверка с задачами,
|
||||
спеками и рубрикой. Найденное правилось, и evidence переснималось с
|
||||
закоммиченного кода. Примеры — гонка уборщика с `mark_ready`, которая
|
||||
давала `ready` без объекта (два раунда verify `upload-consistency`),
|
||||
строка с ключом вне префикса в сверке, неполные вердикты сводки метки
|
||||
сверки;
|
||||
- публичные проверки skeleton (`make test`, `make test-persistence`,
|
||||
`make test-failover`) и собственные (`make student_test`, `make
|
||||
failure_checks`, `make test_isolated`, `make s3_check`) — на итоговом
|
||||
коде каждого change и из чистого clone
|
||||
(`evidence/tests/clean-clone-final.md`); у новых проверок отказов —
|
||||
красный прогон до кода;
|
||||
- гипотезы обоих замеров закоммичены до прогонов, хост проверялся перед
|
||||
каждой меткой. Первая метка `uploads` (грязное дерево, swap хоста
|
||||
337 056 страниц) отброшена; принятая снята на чистом дереве, с
|
||||
пометкой о swap 7 464 страниц в одном прогоне (решение автора выше);
|
||||
- ошибки ИИ, найденные по ходу, описаны в отчёте как есть:
|
||||
- оценка «~1,2 тела на загрузку» до change `upload-memory` была
|
||||
неверна: на деле ~2,17 тела и OOM при 20 × 10 MiB;
|
||||
- первая метка `uploads` снята на грязном дереве со swap хоста;
|
||||
- две попытки метки сверки упали на собственной проверке полноты
|
||||
строк k6;
|
||||
- срок чтения aiohttp давал редкие 503 на исправном S3
|
||||
(`fix-upload-put-flake`).
|
||||
|
||||
Утверждения отчёта о поведении стенда подтверждены командами, их выводы
|
||||
лежат в `evidence/`. Решения, перечисленные выше, принимал автор.
|
||||
|
||||
@@ -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` удалены.
|
||||
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user