diff --git a/.claude/rules/balancer.md b/.claude/rules/balancer.md index f82ec761..acf139e9 100644 --- a/.claude/rules/balancer.md +++ b/.claude/rules/balancer.md @@ -19,9 +19,13 @@ paths: ``` клиент → 127.0.0.1:APP_OUT_PORT → haproxy → api × API_REPLICAS → postgres (данные, сессии, ключи) → valkey (кэш карточек) + → s3 (байты вложений, с лабы 4) migrate (один раз на up) ──────→ postgres + s3-bootstrap (один раз на up) ─→ s3 (bucket, пользователь API) ``` +Реплики ждут обоих одноразовых сервисов (`service_completed_successfully`). + ## Сервисы compose - **`haproxy`** — единственный сервис с портом наружу: @@ -41,6 +45,8 @@ paths: `restart: unless-stopped`. - **`migrate`** — как в лабе 2: один раз до реплик, реплики ждут `service_completed_successfully` (`migrations.md`). +- **`s3`, `s3-bootstrap`** (с лабы 4) — сервер S3 и его bootstrap + (`docker.md`, раздел S3). Реплики ждут bootstrap, как миграций. - Лимиты CPU/RAM у **всех** сервисов, включая postgres, valkey и migrate (`deploy.resources.limits`). Сумма — в `REPORT.md`, рядом с расчётом соединений Postgres (`infra.md`). @@ -299,6 +305,13 @@ rolling_update COMMIT=<прежний> MIGRATE=0`. снова `make rolling_update` или `make run_docker` (сборка рабочего дерева, все реплики разом). +**Bootstrap S3 скрипт не запускает** (design change `s3-storage`, +решение 9): новая реплика поднимается с `--no-deps`. Bootstrap, как +миграции, только расширяет: новые пользователи и политики не отбирают +прав у старых реплик. Его изменения (новая строка `infra/s3/bootstrap.sh`, +новый секрет API в `.env`) применяет `docker compose up -d s3-bootstrap` +или `make run_docker` — до замены, если новый код на них опирается. + Прогон — под нагрузкой с постоянной интенсивностью: профиль `rollout` стенда `bench/` (`make bench_rollout`, `bench.md`) вызывает этот же скрипт со своим проектом (`COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`, @@ -308,8 +321,11 @@ rolling_update COMMIT=<прежний> MIGRATE=0`. ## Что стенд не переживает -Один Docker-host, один HAProxy, одна Postgres, один Valkey. Выдерживается -отказ процесса API (любой одной реплики, при ≥2 живых). Не выдерживается -отказ хоста, LB и Postgres. Отказ Valkey — деградация до Postgres, не -отказ. Это пишется в `REPORT.md` прямо (`COURSE.md`, «Воспроизводимость -и честные измерения»). +Один Docker-host, один HAProxy, одна Postgres, один Valkey, одна нода S3 +без репликации. Выдерживается отказ процесса API (любой одной реплики, +при ≥2 живых). Не выдерживается отказ хоста, LB и Postgres. Отказ +Valkey — деградация до Postgres, не отказ. Отказ S3 — 503 на путях +вложений, текст работает, `/health/ready` 200. SIGKILL процесса S3 +подтверждённых объектов не теряет, отказ диска или ВМ — теряет (нет +реплик и fsync). Это пишется в `REPORT.md` прямо (`COURSE.md`, +«Воспроизводимость и честные измерения»). diff --git a/.claude/rules/bench.md b/.claude/rules/bench.md index 0135cfbc..fa2d958f 100644 --- a/.claude/rules/bench.md +++ b/.claude/rules/bench.md @@ -73,6 +73,23 @@ paths: хранилищ `run.py` генерирует на прогон и никуда не пишет. Каждый размер — свежий стенд: `down -v`, Postgres и Valkey, миграции, API. +**S3 (лаба 4) описан, но профили лаб 2–3 его не запускают** (design +change `s3-storage`, решение 9): старт стенда перечисляет сервисы, а +реплики поднимает с `--no-deps`, поэтому ни `s3`, ни `s3-bootstrap` не +стартуют, и методика прежних профилей не меняется. Compose всё равно +требует секреты S3 при разборе файла (`:?`), их `compose_env` тоже +генерирует на прогон (пять значений). Override `s3` — +`container_name: mtusi-bench-s3`, `restart: "no"`, порты сброшены; +`bench.env` — `S3_HOST`, `S3_PORT`, `S3__BUCKET=bench`. Реплики получают +`S3__*` в окружении, и `S3__HOST`, `S3__PORT`, `S3__BUCKET` попадают в +паспорт (`stand.app_env`); меток лабы 3 в этом репозитории нет, поэтому +сравнивать их не с чем. Лимиты `BENCH_S3_*` и S3 в паспорте появятся с +профилем, который его запускает (`upload-memory`, трек 2). + +Фильтр окружения паспорта (`SECRET_ENV_MARKS` в `run.py`) убирает имена с +`PASSWORD`, `SECRET` и `ACCESS_KEY`: иначе секрет и ключ доступа S3 +попали бы в `meta.json`. + Инструменты `bench/`: | Файл | Команда | Что делает | @@ -234,7 +251,9 @@ paths: `failover_*` профиля). Окна — `rollout_before_s` до запуска скрипта, бюджет замены `rollout_budget_s`, ещё `rollout_after_s`. - Реплики стартуют на образе `Profile.rollout_from` (сейчас `c50b721`, - последний commit до change): `git archive | docker build` + последний commit до change в репозитории лабы 3; в лабе 4 его нет — + `KNOWN_ISSUES.md`, до правки — `--from `): `git archive + | docker build` под тегом `mtusi-messenger:bench-from`, затем `docker tag` на `mtusi-messenger:bench`. Рабочее дерево не трогается; тег снимается при уборке. `--from ` — отладка (`overrides`). diff --git a/.claude/rules/docker.md b/.claude/rules/docker.md index 8d4da56c..0f80a31b 100644 --- a/.claude/rules/docker.md +++ b/.claude/rules/docker.md @@ -119,11 +119,13 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t `"127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"`; теперь эта строка — у сервиса `haproxy`. `environment` собирается из якорей: `x-db-env` (`APP__RUN_MODE: docker`, `DATABASE__*` из переменных - `POSTGRES_*`) и `x-cache-env` (`CACHE__*` из `VALKEY_*`), у `api` - — оба через `<<: [*db-env, *cache-env]` плюс `APP__PORT` - (`settings.md`, «Консоль и docker»). У `migrate` — только - `x-db-env`: пароль Valkey ему не нужен; `haproxy` получает только - `API_PORT` (секреты только там, где нужны, рубрика «4»). + `POSTGRES_*`), `x-cache-env` (`CACHE__*` из `VALKEY_*`) и с лабы 4 + `x-s3-env` (`S3__HOST`, `S3__PORT`, `S3__BUCKET`, ключи API мостами + из `S3_API_*`), у `api` — все три через `<<: [*db-env, *cache-env, + *s3-env]` плюс `APP__PORT` (`settings.md`, «Консоль и docker»). У + `migrate` — только `x-db-env`: пароль Valkey и секреты S3 ему не + нужны; `haproxy` получает только `API_PORT` (секреты только там, где + нужны, рубрика «4»). Секреты S3 по сервисам — раздел S3 ниже. Healthcheck образа проверяет `APP__PORT`; `stop_grace_period: 10s`; `restart: unless-stopped`; лимиты CPU/RAM (`deploy.resources.limits`) у всех сервисов — override стендов @@ -165,9 +167,10 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t - С лабы 2 compose — основной запуск стенда: API без Postgres запросы не обслуживает. Проверка и запуск — по README: `docker compose --env-file .env config --quiet`, затем - `up -d --build`, ожидание `/health/ready`. Роли лабы 3 — load_balancer - (HAProxy), api × ≥2, postgres и valkey (`contracts/infrastructure.json`: - Redis/Valkey необязателен, у нас остаётся кэшем). + `up -d --build`, ожидание `/health/ready`. Роли лабы 4 — load_balancer + (HAProxy), api × ≥2, postgres, s3 (SeaweedFS) и valkey + (`contracts/infrastructure.json`: Redis/Valkey необязателен, у нас + остаётся кэшем). `compose.example.yaml` — лишь список ролей, стенд — свой `docker-compose.yml` (compose находит его сам, как и `compose.yaml`). - Образы зависимостей закреплены так же, как базовый: тег с патч-версией @@ -207,8 +210,45 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t - порт сервера — `VALKEY_PORT` (`--port`), алиас в сети — `VALKEY_HOST`, публикация — `127.0.0.1:${VALKEY_OUT_PORT}`, как у Postgres. +- S3 (с лабы 4, design change `s3-storage`, решения 1–4) — сервис `s3` + на SeaweedFS (`chrislusf/seaweedfs:4.48@sha256:…`, якорь + `x-s3-image`) и одноразовый `s3-bootstrap` на том же образе: + - `s3` — `weed server` одним процессом: master, volume и filer только + на `127.0.0.1` контейнера (`-ip`, `-ip.bind`), в сеть выходят порт + API S3 (`S3_PORT`) и gRPC шлюза (`S3_PORT` + 10000); телеметрия, + Iceberg, Lance и IAM API выключены. Volume `s3_data:/data` + (`Config.Volumes`), алиас `${S3_HOST}`, публикация только + `127.0.0.1:${S3_OUT_PORT}:${S3_PORT}`. Healthcheck — `wget` на + `/cluster/healthz` master, `/healthz` filer и шлюза, всё на loopback. + Лимиты 1 CPU / 512 МБ, `GOMEMLIMIT=400MiB` и + `-s3.concurrentUploadLimitMB=64` (решение 2); + - **`stop_grace_period: 20s`**, а не 10: плавная остановка SeaweedFS + ~15 с (срок ожидания подписок filer зашит в код), при 10 с — + SIGKILL и код 137. Цена — `make stop` и `restart.sh` дольше на + ~15 с. На стенде отказов — 2 с (`student-tests.md`); + - секреты по сервисам: административная пара `S3_ROOT_*` — только + `s3` (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`: без учётной + записи сервер открыт анониму); ключ подписи `S3_JWT_SIGNING_KEY` + (`WEED_JWT_FILER_SIGNING_KEY`) — `s3` и `s3-bootstrap`: без него + gRPC шлюза принимает администратора от любого контейнера сети; ключи + API `S3_API_*` — `s3-bootstrap` и `api`. Все с `:?` «copy S3 lines + from .env.example»; + - `s3-bootstrap` — `network_mode: service:s3` (master и filer сервера + на его `127.0.0.1`), `user: seaweed`, `restart: "no"`, `tmpfs: + /tmp` и `HOME=/tmp`, скрипт `infra/s3/bootstrap.sh` read-only + длинной записью, `depends_on: s3: service_healthy`, лимиты 0,5 CPU / + 128 МБ. Режим `apply` (по умолчанию) идемпотентно сводит состояние + к `.env` (bucket, анонимный доступ `none`, политика `api-objects`, + пользователь `api` и его ключ) и проверяет приватность; `check` и + `cleanup` — для `make s3_check`. `api` ждёт его + `service_completed_successfully`, как `migrate`. Секреты — в + `weed shell` через stdin, в `curl` файлом `-K` на tmpfs, не в argv; + - `up -d --wait` одноразовый сервис без healthcheck считает готовым + уже запущенным: код bootstrap отдельно — `up --no-deps + --exit-code-from s3-bootstrap s3-bootstrap` (`make start_s3`). - Конфигурации сервисов (`valkey.conf`, при необходимости - `postgresql.conf`) — в `infra/<сервис>/`, монтируются read-only + `postgresql.conf`, скрипт `infra/s3/bootstrap.sh`) — в + `infra/<сервис>/`, монтируются read-only длинной записью с `create_host_path: false` (`infra/README.md`). В `REPORT.md` — таблица роль → сервис → версия/digest → healthcheck → volume → порт → способ передачи credentials. @@ -240,18 +280,20 @@ Hook для `make test-persistence ACTION_SCRIPT=scripts/restart.sh` (`tests/README.md`), по образцу `scripts/restart.example.sh`. - Перезапускает **все** реплики API, LB и **все** используемые - хранилища: Postgres и Valkey. Volumes, схему и данные сохраняет: без - `down -v`, `FLUSHALL`, повторного seed и изменения тестовых данных. - Кэш Valkey после рестарта пуст сам: persistence у него выключен. -- Порядок: `stop haproxy api` → `restart postgres valkey` → `up -d - --wait postgres valkey` (те же контейнеры, ожидание healthcheck) → - `start api haproxy`. `start api` запускает и зависимость `migrate`: - повторный прогон миграций — no-op. Число реплик не меняется: `start` - поднимает те же контейнеры, а не масштабирует (реплику, остановленную - `stop-one.sh`, тоже). + хранилища: Postgres, Valkey и с лабы 4 S3. Volumes, схему и данные + сохраняет: без `down -v`, `FLUSHALL`, повторного seed и изменения + тестовых данных. Кэш Valkey после рестарта пуст сам: persistence у + него выключен. Bucket, учётные записи и объекты S3 — в его volume. +- Порядок: `stop haproxy api` → `restart postgres valkey s3` → `up -d + --wait postgres valkey s3` (те же контейнеры, ожидание healthcheck) → + `start api haproxy`. `start api` запускает и зависимости `migrate` и + `s3-bootstrap`: повторные миграции и bootstrap — no-op («exists»). + Число реплик не меняется: `start` поднимает те же контейнеры, а не + масштабирует (реплику, остановленную `stop-one.sh`, тоже). - `#!/bin/sh`, `set -eu`, исполняемый бит в git (`chmod +x`, `git update-index --chmod=+x`). Возвращает 0 только после действия, - укладывается в 90 с. Готовность ждёт сам тест. Секреты не печатает. + укладывается в 90 с (с S3 — ~25 с, из них ~15 с — остановка S3). + Готовность ждёт сам тест. Секреты не печатает. - Успех теста не доказывает, что БД действительно перезапускалась. В `evidence/` — состояние контейнеров до и после (`docker compose ps`, `StartedAt` из `docker inspect`). diff --git a/.claude/rules/infra.md b/.claude/rules/infra.md index 3e6aa94c..c3df6a93 100644 --- a/.claude/rules/infra.md +++ b/.claude/rules/infra.md @@ -6,17 +6,19 @@ paths: # Инфраструктура (`src/infra/`) Всё, что не содержит бизнес-логики и может смениться от лабы к лабе: -логгер, PostgreSQL (`db/`), кэш Valkey (`cache/`), дальше — S3, брокер, -телеметрия. Бизнес-правил (уникальность, доступ, валидация) здесь нет: +логгер, PostgreSQL (`db/`), кэш Valkey (`cache/`), S3 (`s3/`), дальше — +брокер, телеметрия. Бизнес-правил (уникальность, доступ, валидация) здесь нет: они в сервисах, атомарные операции — в repo. -- Клиент хранилища (engine Postgres, кэш Valkey) — глобал своего модуля - (`db/session.py`, `cache/instance.py`): создаётся при импорте по +- Клиент хранилища (engine Postgres, кэш Valkey, S3) — глобал своего + модуля (`db/session.py`, `cache/instance.py`, `s3/instance.py`): + создаётся при импорте по `settings` (настройки читаются один раз на процесс), соединения открывает лениво, при первом запросе. Пакет `src/infra/<клиент>/` этот модуль не импортирует, модели тоже, поэтому alembic и скрипты клиента не создают. Закрытие (`engine.dispose()`, `cache.aclose()`) — в - lifespan `src/main.py`. Почему не `app.state` — design change + lifespan `src/main.py` (S3 — ещё и `start()` там же). Почему не + `app.state` — design change `postgres-storage`, решение 5. - Глобал импортируют только `src/main.py` (закрытие) и `src/api/dependencies.py`; сервисы получают сессию или клиент через @@ -29,6 +31,15 @@ paths: - `cache/`: `client.py` — фабрика `create_cache` и обёртка `Cache`; `instance.py` — глобал `cache`. Ключи и формат значений — в repo (`src/core/repos/chat_cache.py`), не здесь. +- `s3/` (с лабы 4, design change `s3-storage`, решения 6–7): `client.py` + — фабрика `create_object_storage`, обёртка `ObjectStorage` и типы + `StoredObjectInfo`, `StoredObject`; `instance.py` — глобал + `object_storage` с `namespace` = имя базы. Ключ объекта строит repo + (`attachments`): `f"{namespace}{S3_KEY_SEPARATOR}…"`, как ключи кэша, — + объекты `make test_isolated` лежат под `test_/`. Клиент + aiobotocore создаёт `start()` в lifespan (модели botocore — при + старте, сети нет), закрывает `aclose()` рядом с `cache.aclose()`. + Ниже — правила клиента. - `early_stop.py` — ранний обработчик SIGTERM и SIGINT процесса (`install()`, `disarm()`): только stdlib, ни настроек, ни логгера, ни других модулей `src`; клиентом хранилища не является, глобала клиента @@ -129,6 +140,31 @@ paths: `warning` «Cache is unavailable» на отказ и `info` «Cache is available again» при первом успехе. Пароль в журнал не попадает: он есть только в настройках пула. +- S3 (SeaweedFS) — байты вложений; источник истины метаданных — + PostgreSQL. Клиент — aiobotocore (botocore закреплён им узко, + обновлять вместе через `uv lock`): + - **повторов нет** (`retries={"total_max_attempts": 1}`): рестарт S3 + повтора не требует (старый клиент проходит первым же вызовом), таймаут + не повторяется, загрузку повторяет клиент контракта; + - **срок на вызов** — `asyncio.timeout([s3] timeout_seconds)` (5 с, + меньше `timeout server` HAProxy), у `open` — ещё и на каждый блок + чтения тела; `connect_timeout_seconds` и `read_timeout` botocore — + из `[s3]`; пул aiohttp — `[s3] max_connections`; + - адресация `path`: `bucket.s3` Docker DNS не разрешает; + простаивающее соединение aiohttp закрывает через + `S3_KEEPALIVE_TIMEOUT_SECONDS` (15 с), раньше шлюза (120 с); + - ключи передаются в botocore всегда, даже пустые: с `None` он искал + бы учётные данные в окружении и `~/.aws` хоста. Пустые ключи — + `warning` при старте; + - ошибки: отказ соединения, обрыв, таймаут, 5xx и отказ в учётных + данных (`AccessDenied`, `InvalidAccessKeyId`, + `SignatureDoesNotMatch`) — `ObjectStorageUnavailable` (наследник + `ServiceUnavailable`, 503 `unavailable`); отсутствующий ключ — + `StoredObjectMissing` (`head` — `None`, `delete` — не ошибка); + прочие ошибки S3 и botocore не перехватываются — 500, дефект; + - обхода и пропуска после отказа, как у Valkey, нет: без S3 путь + вложений всё равно 503. `/health/ready` S3 не проверяет (спек + `health`, решение 3 `PLAN.md`): текст работает без него. - Клиенты внешних сервисов: адреса и секреты из `settings` (`.claude/rules/settings.md`), таймаут на каждый вызов, ошибки переводятся в доменные исключения. Логи — по `logging.md`, без diff --git a/.claude/rules/logging.md b/.claude/rules/logging.md index 7dddd4be..988d9998 100644 --- a/.claude/rules/logging.md +++ b/.claude/rules/logging.md @@ -67,7 +67,10 @@ paths: `uvicorn.error` — `INFO` без своего handler, пишет через `uvicorn` (свой handler дал бы дубли); `uvicorn.access` — выключен; - шумные библиотеки (`sqlalchemy.engine`, драйвер Postgres, `httpx`, - `httpcore`) — `WARNING`: SQL с параметрами в лог не попадает. + `httpcore`) — `WARNING`: SQL с параметрами в лог не попадает; + - клиент S3 (с лабы 4): `botocore`, `aiobotocore`, `aiohttp` — явно + `WARNING`, даже если кто-то опустит уровень root: на `DEBUG` + botocore пишет заголовки запроса с подписью (`Authorization`). ### Отличия от bp_proxies @@ -119,8 +122,16 @@ paths: - Пароли, токены сессий и их хэши, заголовок `Authorization` (`auth.md`); с лабы 3 — `Idempotency-Key` (ни целиком, ни частью: ключ выбирает клиент, в нём может оказаться что угодно; повтор виден по - `replayed=true` и `message_id`); с лабы 4 — подписанные URL и - ключи бакета. + `replayed=true` и `message_id`); с лабы 4 — ключи доступа и секреты + S3, ключ подписи служебных вызовов, подписи запросов к S3 (заголовок + `Authorization`, параметры подписанного URL) и байты объектов. Для + обращений к S3 допустимы адрес S3, bucket, ключ объекта, размер, + длительность и класс ошибки (спек `service-logging`). Клиент + (`src/infra/s3/client.py`, модуль `object_storage`) пишет `warning` + «Object storage is unavailable» на отказ и таймаут, `error` «Object + storage rejected credentials» с кодом ошибки S3, `debug` на успешный + вызов; текста исключения botocore в записи нет. Запись «Started API» — + с `s3_host`, `s3_port`, `s3_bucket`; пустые ключи — `warning`. - Stack trace — только в лог, никогда в ответ. ## Где логировать @@ -132,7 +143,7 @@ paths: | `api/routers/v1/.py` | только заметные шаги, которых не видно из сервиса | `module="api__router"` | | `api/middlewares` | access-лог: одна строка на запрос; health не логировать | `middleware="http"` | | `api/errors.py` | не логирует: 4xx — штатные ответы, а traceback непредвиденной ошибки пишет uvicorn (`uvicorn.error`, с `request_id` из contextvar) после повторного броска исключения Starlette | нет | -| `infra/.py` | подключение, закрытие, ошибки; запросы к внешним API (`debug`) | `module=""` | +| `infra/.py` | подключение, закрытие, ошибки; запросы к внешним API (`debug`) | `module=""` (S3 — `object_storage`) | | `main.py` | старт (host, port, режим), начало и конец shutdown | `module="startup"` | | `infra/early_stop.py` | только остановка до старта сервера, одна запись без structlog (раздел выше) | нет, поле `module` — `startup` | | чистые функции | не логируют, бросают доменные исключения | нет | diff --git a/.claude/rules/run-modes.md b/.claude/rules/run-modes.md index 8ab07ae1..b0f7e366 100644 --- a/.claude/rules/run-modes.md +++ b/.claude/rules/run-modes.md @@ -22,8 +22,8 @@ README слушал `0.0.0.0`) и литерал в `environment` compose; дл | Процесс | `uv run python -m src` на хосте | `python -m src` — PID 1 контейнера | | uvicorn | `127.0.0.1`, `reload=True` по `src/` | `0.0.0.0`, без reload | | Порт | `settings.app.port`: `APP__PORT` из `.env`, без него — 8080 | `APP__PORT` из `.env` внутри каждой реплики (на нём же healthcheck и проверки HAProxy); с лабы 3 `APP_OUT_PORT` публикует только HAProxy | -| Хранилища | Postgres и Valkey — контейнеры compose, приложение ходит на `127.0.0.1:<*_OUT_PORT>` (`settings.md`, «Консоль и docker»); `make run_dev` сам поднимает Postgres, накатывает миграции и поднимает Valkey | всё в compose, зависимости по имени сервиса; миграции — отдельный сервис до старта API (`migrations.md`) | -| Рестарт | reload процесса данные и сессии не теряет | рестарт API и хранилищ с volumes данные и сессии не теряет (`make test-persistence`); кэш Valkey после рестарта пуст | +| Хранилища | Postgres, Valkey и S3 — контейнеры compose, приложение ходит на `127.0.0.1:<*_OUT_PORT>` (`settings.md`, «Консоль и docker»); `make run_dev` сам поднимает Postgres, накатывает миграции, поднимает Valkey и S3 с bootstrap | всё в compose, зависимости по имени сервиса; миграции и bootstrap S3 — отдельные сервисы до старта API (`migrations.md`, `docker.md`) | +| Рестарт | reload процесса данные и сессии не теряет | рестарт API и хранилищ с volumes данные, сессии и объекты S3 не теряет (`make test-persistence`); кэш Valkey после рестарта пуст | ## Точка входа @@ -45,7 +45,8 @@ access_log=False)`. Импорты в `src/__main__.py` — внутри `if __n `[app] graceful_shutdown_seconds`, не больше 8 с). Docker шлёт SIGKILL через 10 с, в compose — `stop_grace_period`. Shutdown в lifespan только логирует и закрывает клиенты (`engine.dispose()`, - `cache.aclose()`), долгих операций в нём нет. + `cache.aclose()`, `object_storage.aclose()`), долгих операций в нём + нет. Рубрика уровня 4 требует завершения не дольше 10 с. Сигнал на старте (спек `graceful-shutdown`, «Остановка во время старта»; design change `fix-known-issues`, решения 3–6): @@ -103,19 +104,21 @@ access_log=False)`. Импорты в `src/__main__.py` — внутри `if __n `# -------------------------`, свой `.PHONY` у каждой цели, имена в snake_case. Apple Container не делать. - Запуск и общие цели: - - `run_dev: upgrade start_cache` — Postgres из compose и миграции, - Valkey из compose, затем `APP__RUN_MODE=console uv run python -m - src`; + - `run_dev: upgrade start_cache start_s3` — Postgres из compose и + миграции, Valkey и S3 с bootstrap из compose, затем + `APP__RUN_MODE=console uv run python -m src`; - `run_docker: env_setup` (недостающие `.env` и `config.toml` из шаблонов, затем `DOCKER_BUILDKIT=1 $(DC) build` и `$(DC) up -d`: - хранилища → migrate → `api` × `API_REPLICAS` → haproxy), + хранилища → migrate и s3-bootstrap → `api` × `API_REPLICAS` → + haproxy), к нему `stop`, `down` (volume остаётся), `logs` (`$(DC) logs -f --no-log-prefix api`: без префикса `api-1 |` каждая строка — JSON, реплику называет поле `instance_id`); - `lint` (`ruff format .` + `ruff check --fix .`, дважды), `env_setup` (шаблоны `.env` и `config.toml`, в новый `.env` — - случайные `POSTGRES_PASSWORD` и `VALKEY_PASSWORD`; существующий - `.env` не меняется, новые строки переносятся руками), + случайные `POSTGRES_PASSWORD`, `VALKEY_PASSWORD` и пять секретов S3, + печатаются только имена; существующий `.env` не меняется, новые + строки переносятся руками), `student_test`. Оба способа запуска — `run_docker` и `run_dev` — описываются в @@ -125,9 +128,20 @@ access_log=False)`. Импорты в `src/__main__.py` — внутри `if __n `stop_db`, `upgrade: start_db` (`uv run alembic upgrade head`), `revision: upgrade` (autogenerate, сообщение — `read -p`), `wipe_data` (`$(DC) down -v --remove-orphans` только после ввода - `yes`). Volume — именованный `postgres_data` в compose; `wipe_data` - пересоздаёт и Valkey, то есть чистит кэш. + `yes`; запрос называет удаляемые volumes Postgres и S3 — + `<проект>_postgres_data`, `<проект>_s3_data`). Volumes — именованные + `postgres_data` и `s3_data` в compose; `wipe_data` пересоздаёт и + Valkey, то есть чистит кэш. - Valkey: `start_cache` (`$(DC) up -d --wait valkey`), `stop_cache`. +- S3 (с лабы 4): `start_s3` — `$(DC) up -d --wait s3`, затем `$(DC) up + --no-deps --exit-code-from s3-bootstrap s3-bootstrap`: `--wait` + одноразовый сервис считает готовым уже запущенным, а код bootstrap + нужен цели (design change `s3-storage`, «Уточнения apply», п. 1); + `stop_s3` (плавно ~15 с); `s3_check` — `driver.py s3-check`: + проверка приватности bucket вне API на запущенном стенде (права ключа + API, чужой bucket, административные запросы, аноним с хоста и из + сети, порты контейнера S3), таблица «проверка → ожидаемо → получено», + код 1 при нарушении. - Реплики за HAProxy (с лабы 3, `balancer.md`): `replicas` (вернуть остановленные и выставить число, `API_REPLICAS ?= 2` после `-include .env`), `instances` (распределение одной сессии по `X-Instance-Id`), @@ -136,14 +150,16 @@ access_log=False)`. Импорты в `src/__main__.py` — внутри `if __n - `student_test` передаёт pytest `EXPECT_REPLICAS` (по умолчанию `API_REPLICAS`): сколько реплик за `BASE_URL` ждут тесты реплик. Против одного процесса — `EXPECT_REPLICAS=1` (`student-tests.md`). -- `test_isolated: env_setup start_db start_cache` — образ на временной - базе (`student-tests.md`); Valkey общий с рабочим стендом, ключи кэша - разделены именем базы. Один контейнер API без LB: скрипт зовёт `make +- `test_isolated: env_setup start_db start_cache start_s3` — образ на + временной базе (`student-tests.md`); Valkey и S3 общие с рабочим + стендом, ключи кэша и объектов разделены именем базы, префикс + `test_/` bucket удаляется при уборке. Один контейнер API без LB: скрипт зовёт `make student_test EXPECT_REPLICAS=1`. Скрипт запускается `$(PYTHON)`, а не `uv run`: uv повторно пересылает SIGINT, и Ctrl+C обрывал уборку. - `failure_checks: env_setup` — проверки отказов на отдельном стенде, проект compose `<рабочий>-failures` (`student-tests.md`). От - `start_db` не зависит: стенд свой и удаляется вместе с volume. + `start_db` не зависит: стенд свой (Postgres, Valkey, S3) и удаляется + вместе с volumes. `FAULT_ARGS` — аргументы pytest (`make failure_checks FAULT_ARGS='-k valkey'`). Скрипт тоже запускается `$(PYTHON)`. Все команды docker проекта отказов — только с `-p <рабочий>-failures`: `down -v` без diff --git a/.claude/rules/settings.md b/.claude/rules/settings.md index 1bba264d..ceeec431 100644 --- a/.claude/rules/settings.md +++ b/.claude/rules/settings.md @@ -14,7 +14,8 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда ## Источники `Settings` - `src/config/settings.py`: `Settings(BaseSettings)` из секций-`BaseModel` - (`App`, `Database`, `Auth`, `Cache` — Valkey). Экземпляр один — + (`App`, `Database`, `Auth`, `Cache` — Valkey, `S3`, `Idempotency`). + Экземпляр один — `settings` на уровне модуля. Импорт везде `from src.config import settings`. Второй `Settings()` не создавать, поля в рантайме не менять. - Приоритет (`settings_customise_sources`): окружение процесса → `.env` @@ -47,8 +48,8 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда | Где | Что | В git | |---|---|---| -| `config.toml` | всё, что читает **только приложение**, по секциям: `log_level`, пул и таймауты `[database]`, TTL сессии, таймауты, пул и срок записей `[cache]`, секреты, которые нужны одному приложению | нет; шаблон `config_example.toml` | -| `.env` | всё, что читает **compose** (и Makefile) и контейнеры зависимостей: порты `APP__PORT` / `APP_OUT_PORT`, `POSTGRES_*` и `VALKEY_*` (адрес, порты, учётные данные), пароли MinIO / брокера с лаб 4–5; мосты `SECTION__FIELD=${...}` для приложения, в том числе консольные адреса Postgres и Valkey | нет; шаблон `.env.example` | +| `config.toml` | всё, что читает **только приложение**, по секциям: `log_level`, пул и таймауты `[database]`, TTL сессии, таймауты, пул и срок записей `[cache]`, регион, сроки и пул `[s3]`, секреты, которые нужны одному приложению | нет; шаблон `config_example.toml` | +| `.env` | всё, что читает **compose** (и Makefile) и контейнеры зависимостей: порты `APP__PORT` / `APP_OUT_PORT`, `POSTGRES_*`, `VALKEY_*` и `S3_*` (адрес, порты, учётные данные, секреты S3 с лабы 4), пароль брокера с лабы 5; мосты `SECTION__FIELD=${...}` для приложения, в том числе консольные адреса Postgres, Valkey и S3 | нет; шаблон `.env.example` | | окружение процесса | режим `APP__RUN_MODE` и разовые подмены | — | | `src/utils/constants.py` | лимиты контракта (3–32, 100, 4000, `limit` 1–100 / 50), пути: одинаковы на всех установках | да | @@ -57,7 +58,7 @@ console и docker — `.claude/rules/run-modes.md`. Здесь — откуда `Dockerfile.example` касается запекания в образ (`COPY`), а `config.toml` в образ не копируется, его монтируют на старте (`docker.md`). Но почти все секреты курса — пароли -Postgres, Valkey, MinIO, брокера — нужны ещё и контейнеру зависимости, +Postgres, Valkey, брокера, ключи S3 — нужны ещё и контейнеру зависимости, а его настраивает только compose из `.env`. Поэтому такой секрет живёт в `.env` и попадает в приложение мостом. Если продублировать его в `config.toml`, как `postgres_password` в bp_proxies, получатся два @@ -118,19 +119,49 @@ compose полю секции: `DATABASE__HOST=127.0.0.1`, `DATABASE__PORT=${POSTGRES_OUT_PORT}` и учётные данные из `POSTGRES_*`; для Valkey — `CACHE__HOST=127.0.0.1`, `CACHE__PORT=${VALKEY_OUT_PORT}`, - `CACHE__PASSWORD=${VALKEY_PASSWORD}`; + `CACHE__PASSWORD=${VALKEY_PASSWORD}`; для S3 — + `S3__HOST=127.0.0.1`, `S3__PORT=${S3_OUT_PORT}`, + `S3__ACCESS_KEY_ID=${S3_API_ACCESS_KEY}`, + `S3__SECRET_ACCESS_KEY=${S3_API_SECRET_KEY}`; - docker: `.env` в контейнер не попадает, адрес и порт приходят из `environment` compose — `DATABASE__HOST: ${POSTGRES_HOST}`, - `DATABASE__PORT: ${POSTGRES_PORT}`, `CACHE__HOST: ${VALKEY_HOST}`, - `CACHE__PORT: ${VALKEY_PORT}` в общем якоре `x-app-env`. + `DATABASE__PORT: ${POSTGRES_PORT}` (якорь `x-db-env`), + `CACHE__HOST: ${VALKEY_HOST}`, `CACHE__PORT: ${VALKEY_PORT}` + (`x-cache-env`), `S3__HOST: ${S3_HOST}`, `S3__PORT: ${S3_PORT}` + (`x-s3-env`). -Адреса и порты Postgres и Valkey в compose — только переменные `.env`, -литерал — лишь адрес публикации `127.0.0.1` (`docker.md`). +Адреса и порты Postgres, Valkey и S3 в compose — только переменные +`.env`, литерал — лишь адрес публикации `127.0.0.1` (`docker.md`). Существующий `.env` `make env_setup` не меняет. Новая переменная из -`.env.example` (с `membership-cache` — строки `VALKEY_*` и `CACHE__*`) -переносится в рабочий `.env` руками; без `VALKEY_PASSWORD` compose -останавливается с сообщением об этом. +`.env.example` (с `membership-cache` — строки `VALKEY_*` и `CACHE__*`, +с `s3-storage` — блок S3) переносится в рабочий `.env` руками, +пустые секреты — `openssl rand -hex 32`; без `VALKEY_PASSWORD` или +секретов S3 compose останавливается с сообщением «copy … lines from +.env.example». В новый `.env` `make env_setup` подставляет случайные +`POSTGRES_PASSWORD`, `VALKEY_PASSWORD` и пять секретов S3 и печатает +только их имена. + +### S3 (с лабы 4) + +- `[s3]`: `host`, `port` (8333), `bucket` (`messenger`, валидатор по + `S3_BUCKET_NAME_PATTERN`: иначе сервис не стартует, в ошибке — + `bucket`), `access_key_id` и `secret_access_key` (`SecretStr`, пусто + — `warning` при старте), `region` (`us-east-1`), сроки + `connect_timeout_seconds` (1) и `timeout_seconds` (5, `gt=0`), пул + `max_connections` (10, `ge=1`). URL — свойство `endpoint_url`. +- Имя bucket читают и приложение, и bootstrap, поэтому в `.env` оно в + формате настроек — `S3__BUCKET`; bootstrap получает его как + `S3_BUCKET: ${S3__BUCKET:-messenger}`. Регион, сроки и пул — в + `config.toml`, адреса и ключей там нет. +- Секреты S3 в `.env` (кто какой получает — `docker.md`): + `S3_ROOT_ACCESS_KEY` / `S3_ROOT_SECRET_KEY` — административная пара, + только сервер; `S3_JWT_SIGNING_KEY` — ключ подписи служебных вызовов; + `S3_API_ACCESS_KEY` / `S3_API_SECRET_KEY` — пользователь API: один + источник для bootstrap и приложения (мост). Новый секрет API действует + после следующего bootstrap (`make run_docker`), прежний перестаёт. +- Порт API S3 в сети — `S3_PORT`, на `127.0.0.1` хоста — `S3_OUT_PORT` + (8334, как 5433 и 6380). `.env.example` skeleton lab2 предлагает «логические» имена: `APP_HOST`, `APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, @@ -160,6 +191,17 @@ Skeleton lab3 добавил ещё два имени: 24 ч по контракту), соответствие — в `REPORT.md`, как `SESSION_TTL_SECONDS`. +Skeleton lab4 добавил имена `S3_*` (буквально не заводятся, +соответствие — в `REPORT.md`, design change `s3-storage`, решение 5): + +- `S3_ENDPOINT` → `S3__HOST` и `S3__PORT` (мосты в консоли, + `x-s3-env` в docker); +- `S3_REGION` → `[s3] region`; +- `S3_BUCKET` → `S3__BUCKET`; +- `S3_ACCESS_KEY_ID_FILE`, `S3_SECRET_ACCESS_KEY_FILE` → мосты из + `S3_API_*`: значения, а не файлы, как с `DATABASE_URL_FILE`; +- `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` — change `attachments`. + `X-Instance-Id` берётся из `[app] instance_id`: по умолчанию пусто, и тогда валидатор поля подставляет hostname процесса (один раз, при загрузке `settings`); значение проверяется по `INSTANCE_ID_PATTERN`. diff --git a/.claude/rules/student-tests.md b/.claude/rules/student-tests.md index 37e255f1..c8c76a37 100644 --- a/.claude/rules/student-tests.md +++ b/.claude/rules/student-tests.md @@ -94,9 +94,16 @@ paths: не доказана. Проверяются количество и уникальность `id`, а также отсутствие потерь при обходе всех страниц. - Обычный прогон — `make test_isolated` (`student-tests/run_isolated.py`): - образ из рабочего дерева на временной базе `test_` с Valkey - стенда (ключи кэша разделены именем базы), публичный smoke и весь - набор против отдельного контейнера, затем уборка при любом исходе. + образ из рабочего дерева на временной базе `test_` с Valkey и S3 + стенда (ключи кэша и объектов разделены именем базы), публичный smoke + и весь набор против отдельного контейнера, затем уборка при любом + исходе. С лабы 4 уборка удаляет и объекты под префиксом `test_/` + bucket — в начале (хвост прошлого прогона) и в конце: `docker compose + exec -T s3` + `weed shell` `fs.rm -r /buckets//test_` + (отсутствие префикса — не ошибка). Префикс собирается только из + имени, прошедшего `^test_[a-z0-9_]+$`, и проверенного имени bucket, + иначе код 2 до любых действий: ошибка не может удалить рабочий + префикс. `KEEP_TEST_DB=1` оставляет базу и префикс и печатает оба. Его вывод — evidence набора против контейнера. Это один контейнер API без LB (`EXPECT_REPLICAS=1`): тесты, которым нужны ≥2 реплики, здесь пропускаются. `make student_test` — против любого запущенного @@ -112,8 +119,12 @@ paths: БД: такие сценарии `chat-cache` — исключения с evidence. - Как устроен `make failure_checks` (`student-tests/run_failures.py`): - тот же `docker-compose.yml` под проектом `<рабочий>-failures` с - override `failures.compose.yml`: свои Postgres и Valkey со своим - volume, их порты не публикуются, healthcheck PostgreSQL проверяет + override `failures.compose.yml`: свои Postgres, Valkey и с лабы 4 + S3 со своими volumes, их порты не публикуются; bootstrap S3 — + отдельным `up --no-deps --exit-code-from s3-bootstrap` после + миграций; у `s3` `stop_grace_period: 2s` — здесь проверяется отказ, + а не плавная остановка (~15 с), и `stop` не тянет время набора; + healthcheck PostgreSQL проверяет служебную базу `postgres` (иначе каждая проверка — сессия в базе приложения и шум счётчика `db-sessions`); - два API на свободных портах `127.0.0.1`: обычный (`BASE_URL`) и @@ -142,7 +153,10 @@ paths: `make test-persistence` вызывает `ACTION_SCRIPT`. Маркер `fault` выбирает тесты, фикстура `stand` действует на стенд: имена разные намеренно. Действия: `stop` / `start` / - `pause` / `unpause`, `flush-cache`, `cache-hits`, `cache-has-chat`, + `pause` / `unpause` сервиса `postgres`, `valkey` или `s3` (у `s3` + проба после `unpause` — та же команда, что healthcheck: master, + filer и шлюз; `test_readiness_without_object_storage` — спек `health`, + «Хранилище объектов недоступно»), `flush-cache`, `cache-hits`, `cache-has-chat`, `fail-members` (триггер, который роняет вставку участников), `fail-messages` (триггер, который роняет вставку сообщения с данным текстом — уже после вставки ключа идемпотентности) и diff --git a/.claude/skills/run-mtusi-messenger/SKILL.md b/.claude/skills/run-mtusi-messenger/SKILL.md index 4c6b68d3..90d4b5dc 100644 --- a/.claude/skills/run-mtusi-messenger/SKILL.md +++ b/.claude/skills/run-mtusi-messenger/SKILL.md @@ -1,13 +1,15 @@ --- name: run-mtusi-messenger -description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, PostgreSQL, Valkey; лаба 3 — HAProxy перед репликами API) — на хосте или в Docker. Use when asked to run / start / stop the server or the stand, run the smoke test, `make test`, `make student_test`, `make test_isolated`, `make test-persistence` or `make test-failover`, stop or restore an API replica, show X-Instance-Id distribution, check that an API change works on a live server, send a request to an endpoint, reproduce a bug over HTTP, check the containers, or call services directly without HTTP. +description: Запустить, остановить, прогнать и подёргать API мессенджера MTUSI (FastAPI, PostgreSQL, Valkey; лаба 3 — HAProxy перед репликами API; лаба 4 — S3 на SeaweedFS) — на хосте или в Docker. Use when asked to run / start / stop the server or the stand, run the smoke test, `make test`, `make student_test`, `make test_isolated`, `make test-persistence` or `make test-failover`, `make s3_check`, check that the S3 bucket is private, stop or restore an API replica, show X-Instance-Id distribution, check that an API change works on a live server, send a request to an endpoint, reproduce a bug over HTTP, check the containers, or call services directly without HTTP. --- REST API мессенджера (пользователи, чаты, сообщения) — сервер на FastAPI/uvicorn, данные в PostgreSQL из compose, карточки чатов -кэшируются в Valkey из compose. Агент управляет им через +кэшируются в Valkey из compose, с лабы 4 есть S3 (SeaweedFS) для байтов +вложений. Агент управляет им через `.claude/skills/run-mtusi-messenger/driver.py`: он поднимает Postgres, -накатывает миграции и поднимает Valkey (`make upgrade start_cache`), +накатывает миграции, поднимает Valkey и S3 с bootstrap (`make upgrade +start_cache start_s3`), запускает свой экземпляр сервера в фоне, гоняет сценарий по HTTP, публичный smoke и собственные тесты, шлёт одиночные запросы и останавливает сервер. Против стенда compose (`make run_docker`: @@ -17,7 +19,8 @@ HAProxy на `APP_OUT_PORT` перед репликами API) работают полёте, `idle-conns` — кто закрывает простаивающие соединения LB → реплика, `hang-key` — повтор ключа после зависшей реплики, `cache-check` и `auth-storage` — доказательства исключений сверки -покрытия (кэш, хранение паролей и токенов). `stop-at-start` — остановка +покрытия (кэш, хранение паролей и токенов), `s3-check` (`make +s3_check`) — приватность bucket вне API. `stop-at-start` — остановка контейнеров образа во время старта, без стенда. Только стандартная библиотека Python 3.9+: `make instances` запускает драйвер системным `python3` (на macOS — 3.9), поэтому без `datetime.UTC`, @@ -46,16 +49,17 @@ Argon2id, около 30 мс на регистрацию и вход в конс ```bash uv sync --all-extras # venv с ruff и dev-группой (pytest, httpx, валидатор) -make env_setup # .env (случайные POSTGRES_PASSWORD и VALKEY_PASSWORD) и config.toml, существующие не трогает +make env_setup # .env (случайные POSTGRES_PASSWORD, VALKEY_PASSWORD и 5 секретов S3, печатает только имена) и config.toml, существующие не трогает ``` -Нужен запущенный Docker: Postgres и Valkey живут в compose. Без +Нужен запущенный Docker: Postgres, Valkey и S3 живут в compose. Без Postgres сервер стартует, но `/health/ready` отвечает 503; без Valkey -всё работает, но мимо кэша (`warning` «Cache is unavailable» в логе). -`driver.py start` сам делает `make upgrade start_cache`. В `.env`, -созданном до `membership-cache`, нет строк Valkey: их переносят из -`.env.example` руками, иначе compose падает с `VALKEY_PASSWORD is -empty`. +всё работает, но мимо кэша (`warning` «Cache is unavailable» в логе); +без S3 `/health/ready` — 200, а пути вложений (с change `attachments`) +— 503. `driver.py start` сам делает `make upgrade start_cache +start_s3`. В `.env`, созданном до `membership-cache` или `s3-storage`, +нет строк Valkey или S3: их переносят из `.env.example` руками, иначе +compose падает с `… is empty, copy … lines from .env.example`. ## Run (agent path) @@ -68,7 +72,7 @@ python3 $D all # start → flow → tests/smoke.py → student-tests → st посмотреть лог, послать свой запрос): ```bash -python3 $D start # make upgrade start_cache, затем фон; ждёт /health/ready до 30 с +python3 $D start # make upgrade start_cache start_s3, затем фон; ждёт /health/ready до 30 с python3 $D status # listeners: [pid reloader, pid worker], ready: True python3 $D flow # ~60 проверок: регистрация с паролем, вход, 409, неверный пароль, # 401 с WWW-Authenticate, X-User-Id игнорируется, чат, 5 сообщений, @@ -87,7 +91,7 @@ python3 $D stop | команда | что делает | |---|---| -| `start` | `make upgrade start_cache`, затем `APP__RUN_MODE=console APP__PORT= uv run python -m src` в своей группе процессов | +| `start` | `make upgrade start_cache start_s3`, затем `APP__RUN_MODE=console APP__PORT= uv run python -m src` в своей группе процессов | | `status` | кто слушает порт, отвечает ли `/health/ready`; код 1, если никого | | `flow` | сквозной сценарий; `[FAIL]` в строке и код 1 при провале; в конце печатает id alice/bob/eve/chat и синтетический токен alice | | `req METHOD PATH [--token T \| --basic USER:PASS] [--data JSON] [--key K \| --no-key]` | один запрос: статус, `x-request-id`, `x-instance-id`, `www-authenticate` у 401, тело; код 2 при статусе ≥ 400. `POST …/messages` без `--key` получает новый `Idempotency-Key` (он печатается), `--no-key` — без заголовка | @@ -99,6 +103,7 @@ python3 $D stop | `hang-key` | только стенд с LB: временный триггер `hang_probe_<метка>` задерживает вставку пробного сообщения на 2 с, реплика с этой транзакцией замораживается `docker pause`, повторы того же `Idempotency-Key` через LB до 201 (сначала 504 от LB или 503 по ожиданию блокировки), разморозка; печатает `idle_in_transaction_session_timeout` соединения приложения и строку журнала PostgreSQL о прерывании. Код 0 — повтор получил 201, в чате одно сообщение, обе реплики снова `UP`. Триггер удаляется и реплика размораживается при любом исходе, в том числе по Ctrl+C, SIGTERM и SIGHUP; если удалить не удалось — печатается SQL удаления и код 1 (от SIGKILL уборки нет) | | `cache-check [--require-test-keys]` | только стенд с LB (`--port 8080`): сценарии `chat-cache` «Чтение из кэша», «Срок записи», «Временная база». Два синтетических пользователя и чат; ключ `messenger:v1:<база>:chat:` сразу после 201 (`EXISTS`, TTL ≤ `[cache] chat_ttl_seconds` из реплики, поля значения), `DEL`, через 11 с снимок `seq_scan + idx_scan` таблицы `chats` и `keyspace_hits` / `keyspace_misses`, 50 чтений через LB, через 11 с второй снимок; TTL до и после ещё 10 чтений; число ключей рабочей и тестовой (`test_`) базы. Код 0 — чтений `chats` ≤ 1, hits ≥ +49, промахов ≤ 1, ответы равны ответу на создание, TTL не продлевается, ≥ 2 `X-Instance-Id`. Для «Временной базы» перед ней — `make test_isolated`: без ключей тестовой базы строка `PASS` заканчивается «temporary database: not checked», с `--require-test-keys` — код 1 (доказательство сценария снимается с флагом). На стенде в это время ничего другого не должно идти. Вывод — `evidence/cache/hits.md` | | `auth-storage` | только стенд с LB: сценарии `users` «Хэш в БД» и `sessions` «Токена нет в хранилище». Пароль P (с `:` и кириллицей) и токен T — только в памяти; через psql — префикс `$argon2id$…` до соли и длина у двух пользователей с одним P, неравенство хэшей, строка `sessions` с `token_hash` = SHA-256(T) (32 байта); `pg_dump --data-only` в память — нет ли T (текстом и в hex) и P. Код 0 — всё так. Вывод — `evidence/auth/passwords-and-tokens.md` | +| `s3-check` | стенд compose (`make s3_check`), без приложения: спек `object-storage` «Проверка приватности вне API». `docker compose run --rm --no-deps s3-bootstrap check` — права ключа API (PUT/GET/HEAD объекта, 404 отсутствующего; 403 на список, создание и удаление bucket, политику и ACL bucket, публичный ACL объекта), временный чужой bucket (403 на всё), аноним изнутри сервера (403); анонимные запросы с хоста (`127.0.0.1:S3_OUT_PORT`) и из сети стенда (одноразовый контейнер образа S3), порты контейнера S3 из сети (`nc -z`: открыты только API S3 и gRPC шлюза); затем `s3-bootstrap cleanup` и `weed shell` — проверочных объектов и bucket не осталось. Таблица «где → проверка → ожидаемо → получено» без секретов, код 1 при расхождении (печатает нарушенные). Вывод — `evidence/s3/privacy.md` | | `stop-at-start [--image ТЕГ] [--delays 0.2,0.3,0.4,1.5,5] [--server-start 3]` | спек `graceful-shutdown` «Остановка во время старта»: контейнеры образа (по умолчанию `mtusi-messenger:lab4`) с лимитами реплики (1 CPU / 512 МиБ без swap), без сети и `config.toml`; `docker stop --timeout 10` через паузу после `docker run` и сразу по строке «Started server process». По потоку `docker events` и журналу: «сигнал через», время `docker stop`, «выход после сигнала», код выхода, этап (`import` / `server-start` / `running`), кто остановил (`early` / `uvicorn`). Код 0 — каждая попытка с кодом 0 и `docker stop` ≤ 1 с, есть `import`, остановленный ранним обработчиком, и `running`. Проекты compose не трогает, свои контейнеры удаляет по метке `mtusi.stop-at-start`. Вывод — `evidence/failover/stop-at-start.md` | | `stop` | SIGTERM всей группе; ждёт, пока порт освободится. Чужой сервер и контейнер не трогает | | `all` | всё подряд (`student` — если есть `student-tests/`), `stop` в `finally` | @@ -113,13 +118,18 @@ python3 $D stop ## Run: стенд compose (HAProxy + реплики) Проект `mtusi-lab4`, образ `mtusi-messenger:lab4`, compose-сервисы -`postgres`, `valkey`, `migrate` (одноразовые миграции), `api` × -`API_REPLICAS` (по умолчанию 2, без портов на хосте) и `haproxy` — -единственный порт API на хосте, `127.0.0.1:APP_OUT_PORT` (8080). -Конфиг LB — `infra/haproxy/haproxy.cfg`, правила — `balancer.md`. +`postgres`, `valkey`, `s3` (SeaweedFS, API S3 на `127.0.0.1:S3_OUT_PORT` +— 8334), `migrate` (одноразовые миграции), `s3-bootstrap` (одноразовый: +приватный bucket и пользователь API), `api` × `API_REPLICAS` (по +умолчанию 2, без портов на хосте) и `haproxy` — единственный порт API +на хосте, `127.0.0.1:APP_OUT_PORT` (8080). Конфиг LB — +`infra/haproxy/haproxy.cfg`, правила — `balancer.md` и `docker.md`. ```bash -make run_docker # build + up -d: postgres, valkey → migrate → api × 2 → haproxy +make run_docker # build + up -d: postgres, valkey, s3 → migrate, s3-bootstrap → api × 2 → haproxy +make s3_check # приватность bucket вне API: таблица проверок, код 0 +docker compose logs s3-bootstrap # bucket/user exists|created, checks passed +docker compose run --rm s3-bootstrap # повтор bootstrap: «exists», код 0 docker compose ps -a --format '{{.Name}} {{.ID}} {{.Ports}} {{.Status}}' make instances # ≥2 X-Instance-Id одной сессии через LB (шаг 1 защиты) make lb_stats # слоты HAProxy: адрес, UP/DOWN, запросы, повторы, перенаправления @@ -129,7 +139,7 @@ docker compose logs --no-log-prefix api | tail -5 # JSON всех реплик docker compose logs --no-log-prefix haproxy | tail # LB: ошибки, повторы (+N), смена состояния реплик docker compose exec valkey sh -c 'valkey-cli -p "$VALKEY_PORT" --scan --pattern "messenger:*" | head' # ключи кэша; пароль — из VALKEYCLI_AUTH контейнера -scripts/restart.sh # рестарт LB, всех реплик, Postgres и Valkey: данные и токены остаются, кэш пуст +scripts/restart.sh # рестарт LB, всех реплик, Postgres, Valkey и S3 (~25 с): данные, токены и объекты остаются, кэш пуст make test-persistence ACTION_SCRIPT=scripts/restart.sh # то же публичной проверкой make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановка реплики, обслужившей тест; ~20 с STOP_MODE=kill STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh @@ -220,7 +230,7 @@ HTTP-коды: `authenticate(token="x")` бросает `Unauthenticated`, не ## Run (human path) ```bash -make run_dev # Postgres + миграции, Valkey, затем 127.0.0.1:8080, reload по src/; Ctrl-C +make run_dev # Postgres + миграции, Valkey, S3 + bootstrap, затем 127.0.0.1:8080, reload по src/; Ctrl-C ``` Блокирует терминал — агенту не подходит, используй `driver.py start`. @@ -239,10 +249,13 @@ make lint # ruff; затрагивает и dr Ожидаемо: `PASS: offline skeleton structure...`, `FAILED: none` у `flow`, smoke — `PASS: lab4 public API scenario...`, student — все прошли (тесты `fault` — `deselected`), `All checks passed!`; `all`, -`test_isolated` и `failure_checks` — код 0. +`test_isolated` и `failure_checks` — код 0. **До change `attachments`** +smoke (загрузка вложения) и тесты со схемой `Message` (контракт лабы 4 +требует `attachment_ids`) красные — список в `tasks.md` change +`s3-storage`. Проверки отказов (`student-tests/test_failures.py`, маркер `fault`) -останавливают и замораживают Postgres и Valkey, поэтому идут только на +останавливают и замораживают Postgres, Valkey и S3, поэтому идут только на своём стенде: `make failure_checks` поднимает проект compose `<рабочий>-failures` со своими хранилищами и volume и удаляет его после прогона. Рабочий стенд на 8080 при этом не трогается. `pytest -m fault` @@ -348,3 +361,14 @@ make lint # ruff; затрагивает и dr любой команды compose — `.env` создан до `membership-cache`: перенести строки `VALKEY_*` и `CACHE__*` из `.env.example`, пароль — `openssl rand -hex 16`. +- **`S3_… is empty, copy S3 lines from .env.example`** — `.env` создан + до `s3-storage`: перенести блок S3 из `.env.example`, пять пустых + секретов — `openssl rand -hex 32` каждый; затем `make run_docker`. +- **`s3-bootstrap: FAILED: <шаг>`, реплики не стартуют** — bootstrap + назвал шаг: `docker compose logs s3-bootstrap`. Недопустимое имя + `S3__BUCKET` — «bucket create»; анонимный доступ или права не те — + `FAILED: … is not denied`. Повтор — `docker compose up -d + s3-bootstrap` (или `make run_docker`). +- **`make stop` и `restart.sh` дольше на ~15 с** — SeaweedFS + останавливается плавно ~15 с (`stop_grace_period: 20s`), это не + зависание. diff --git a/.claude/skills/run-mtusi-messenger/driver.py b/.claude/skills/run-mtusi-messenger/driver.py index 30697ad8..c90b0403 100644 --- a/.claude/skills/run-mtusi-messenger/driver.py +++ b/.claude/skills/run-mtusi-messenger/driver.py @@ -6,10 +6,10 @@ python3 .claude/skills/run-mtusi-messenger/driver.py [--port N] Команды: - start `make upgrade start_cache` (Postgres из compose и миграции, - Valkey), затем поднять `python -m src` в фоне (console, - reload) и дождаться /health/ready; лог и pid — - /tmp/mtusi-api-.{log,pid} + start `make upgrade start_cache start_s3` (Postgres из compose и + миграции, Valkey, S3 с bootstrap), затем поднять + `python -m src` в фоне (console, reload) и дождаться + /health/ready; лог и pid — /tmp/mtusi-api-.{log,pid} status кто слушает порт и что отвечает /health/ready flow сквозной сценарий по HTTP с проверками; код выхода 1 при провале req один запрос: req METHOD PATH [--token T | --basic USER:PASS] @@ -53,6 +53,14 @@ хранилище» и users «Хэш в БД» — префиксы Argon2id и разные хэши одного пароля, token_hash = SHA-256 токена, ни токена, ни пароля в pg_dump; секреты не печатаются + s3-check стенд compose (make s3_check), без приложения: спек + object-storage «Проверка приватности вне API» — bootstrap S3 + в режиме check (права ключа API, чужой bucket, + административные запросы, аноним изнутри сервера), анонимные + запросы с хоста и из сети стенда, порты контейнера S3 из + сети, затем режим cleanup и проверка, что проверочных + объектов и bucket не осталось; таблица «где → проверка → + ожидаемо → получено», код 1 при расхождении stop-at-start [--image ТЕГ] [--delays 0.2,0.3,0.4,1.5,5] [--server-start 3] docker stop контейнеров образа (лимиты реплики, без сети) во время старта: через паузу после @@ -206,16 +214,16 @@ def cmd_start(port: int) -> int: print(f"port {port} is busy:", listener_pids(port)) return 1 # без Postgres сервис стартует, но /health/ready отвечает 503; без - # Valkey работает, но мимо кэша + # Valkey работает, но мимо кэша; без S3 — 503 на путях вложений upgrade = subprocess.run( - ["make", "upgrade", "start_cache"], + ["make", "upgrade", "start_cache", "start_s3"], cwd=ROOT, capture_output=True, text=True, check=False, ) if upgrade.returncode != 0: - print("make upgrade start_cache failed:") + print("make upgrade start_cache start_s3 failed:") print((upgrade.stdout + upgrade.stderr)[-2000:]) return 1 env = os.environ | {"APP__RUN_MODE": "console", "APP__PORT": str(port)} @@ -1559,6 +1567,270 @@ def cmd_auth_storage(port: int) -> int: return 0 +# s3-check: проверочный объект режима check bootstrap S3 +S3_CHECK_KEY = ".s3-check/probe" +# строки проверок bootstrap: «s3-bootstrap: checkимяожидаемо…» +S3_CHECK_ROW = "s3-bootstrap: check\t" +# порты weed server, которые не должны быть доступны из сети стенда: +# master, filer, volume (HTTP и gRPC), admin UI, Iceberg, Lance, webdav, +# SFTP, pprof +S3_CLOSED_PORTS = ( + 9333, + 19333, + 8888, + 18888, + 8080, + 18080, + 23646, + 8181, + 9101, + 7333, + 8111, + 6060, +) +# анонимные запросы из сети стенда и порты контейнера S3: одноразовый +# контейнер на образе сервера (curl и nc в нём есть). Строки — как у +# bootstrap: имя, ожидаемо, получено +S3_NETWORK_SCRIPT = r""" +set -u +code() { curl -s -o /dev/null -w '%{http_code}' --max-time 5 "$@" || echo 000; } +row() { printf 'row\t%s\t%s\t%s\n' "$1" "$2" "$3"; } +base="http://$S3_HOST:$S3_PORT" +row "anonymous get object" 403 "$(code "$base/$S3_BUCKET/$S3_KEY")" +row "anonymous head object" 403 "$(code -I "$base/$S3_BUCKET/$S3_KEY")" +row "anonymous get missing object" 403 "$(code "$base/$S3_BUCKET/.s3-check/missing")" +row "anonymous list objects" 403 "$(code "$base/$S3_BUCKET?list-type=2")" +row "anonymous list buckets" 403 "$(code "$base/")" +row "anonymous put object" 403 "$(code -X PUT --data-binary x "$base/$S3_BUCKET/.s3-check/anonymous")" +for p in $S3_PORT $S3_GRPC_PORT; do + if nc -z -w 2 "$S3_HOST" "$p"; then got=open; else got=closed; fi + row "port $p (S3 API / gRPC of gateway)" open "$got" +done +for p in $S3_CLOSED; do + if nc -z -w 2 "$S3_HOST" "$p"; then got=open; else got=closed; fi + row "port $p" closed "$got" +done +""" + + +def s3_stand() -> dict[str, str]: + """Параметры S3 стенда из `docker compose config` без секретов: + проект, образ, адрес и порт в сети, порт на хосте, bucket.""" + config = json.loads(compose("config", "--format", "json")) + services = config["services"] + s3 = services["s3"] + published = next( + p for p in s3.get("ports", []) if p.get("host_ip") == "127.0.0.1" + ) + api_env = services["api"]["environment"] + return { + "project": config["name"], + "image": s3["image"], + "host": str(api_env["S3__HOST"]), + "port": str(published["target"]), + "out_port": str(published["published"]), + "bucket": str(services["s3-bootstrap"]["environment"]["S3_BUCKET"]), + } + + +def anonymous_code( + url: str, + method: str = "GET", + data: bytes | None = None, +) -> str: + request = urllib.request.Request(url, method=method, data=data) + try: + with urllib.request.urlopen(request, timeout=5) as response: + return str(response.status) + except urllib.error.HTTPError as error: + return str(error.code) + except OSError: + return "000" + + +def weed_shell(command: str) -> str: + """Одна команда `weed shell` в контейнере `s3` стенда: master и filer + на его loopback, ключ подписи — в его окружении.""" + return compose( + "exec", + "-T", + "s3", + "sh", + "-c", + "exec weed shell -master=127.0.0.1:9333 2>&1", + stdin=f"{command}\n", + ) + + +def s3_bootstrap(mode: str) -> tuple[int, str]: + """Bootstrap S3 стенда в режиме `check` или `cleanup`: код и вывод.""" + proc = subprocess.run( + [ + "docker", + "compose", + "run", + "--rm", + "--no-deps", + "s3-bootstrap", + mode, + ], + cwd=ROOT, + capture_output=True, + text=True, + check=False, + ) + return proc.returncode, proc.stdout + proc.stderr + + +def cmd_s3_check() -> int: + """Спек `object-storage`, «Проверка приватности вне API»: права ключа + API и приватность bucket без приложения (design change `s3-storage`, + решение 8). + + 1. Bootstrap в режиме `check`: ключ API пишет проверочный объект и + проверяет свои права, чужой bucket (временный) и административные + запросы; аноним изнутри сервера. + 2. Анонимные запросы к объекту с хоста (`127.0.0.1:S3_OUT_PORT`) и из + сети стенда (одноразовый контейнер того же образа), порты + контейнера S3 из сети. + 3. Bootstrap в режиме `cleanup`: объект и временные bucket-ы удалены, + остатков нет (`weed shell` в контейнере `s3`). + + Печатает таблицу «где → проверка → ожидаемо → получено» без + секретов; код 1 при любом расхождении.""" + try: + stand = s3_stand() + except (RuntimeError, KeyError, StopIteration, ValueError) as e: + print(f"FAIL: compose config of the S3 stand: {e}") + return 1 + if not compose("ps", "-q", "--status", "running", "s3").strip(): + print("FAIL: service s3 is not running, make run_docker first") + return 1 + rows: list[tuple[str, str, str, str]] = [] + problems: list[str] = [] + try: + rc, out = s3_bootstrap("check") + for line in out.splitlines(): + if line.startswith(S3_CHECK_ROW): + name, expected, got, _ = line[len(S3_CHECK_ROW) :].split("\t") + rows.append(("server", name, expected, got)) + elif "FAILED" in line and "check(s) failed" not in line: + problems.append(line.strip()) + if rc != 0 and not problems and not any(r[2] != r[3] for r in rows): + problems.append(f"s3-bootstrap check exited with {rc}") + host = f"http://127.0.0.1:{stand['out_port']}" + obj = f"{host}/{stand['bucket']}/{S3_CHECK_KEY}" + for name, url, method, data in ( + ("anonymous get object", obj, "GET", None), + ("anonymous head object", obj, "HEAD", None), + ( + "anonymous get missing object", + f"{host}/{stand['bucket']}/.s3-check/missing", + "GET", + None, + ), + ( + "anonymous list objects", + f"{host}/{stand['bucket']}?list-type=2", + "GET", + None, + ), + ("anonymous list buckets", f"{host}/", "GET", None), + ( + "anonymous put object", + f"{host}/{stand['bucket']}/.s3-check/anonymous", + "PUT", + b"x", + ), + ): + rows.append( + ("host", name, "403", anonymous_code(url, method, data)), + ) + network = subprocess.run( + [ + "docker", + "run", + "--rm", + "--network", + f"{stand['project']}_default", + "-e", + f"S3_HOST={stand['host']}", + "-e", + f"S3_PORT={stand['port']}", + "-e", + f"S3_GRPC_PORT={int(stand['port']) + 10000}", + "-e", + f"S3_BUCKET={stand['bucket']}", + "-e", + f"S3_KEY={S3_CHECK_KEY}", + "-e", + "S3_CLOSED=" + " ".join(str(p) for p in S3_CLOSED_PORTS), + "--entrypoint", + "sh", + stand["image"], + "-c", + S3_NETWORK_SCRIPT, + ], + capture_output=True, + text=True, + check=False, + ) + for line in network.stdout.splitlines(): + if line.startswith("row\t"): + _, name, expected, got = line.split("\t") + rows.append(("network", name, expected, got)) + if network.returncode != 0: + problems.append(f"network probe exited with {network.returncode}") + finally: + rc, out = s3_bootstrap("cleanup") + if rc != 0: + problems.append("cleanup: " + out.strip().splitlines()[-1]) + buckets = weed_shell("s3.bucket.list") + left_buckets = sum( + 1 + for line in buckets.splitlines() + if line.split() + and line.split()[0].startswith(f"{stand['bucket']}-check-") + ) + check_dir = S3_CHECK_KEY.split("/")[0] + objects = weed_shell(f"fs.ls /buckets/{stand['bucket']}/{check_dir}") + # пустой каталог или его нет («no entry is found») — остатков нет + left_objects = sum( + 1 + for line in objects.splitlines() + if line.strip() and "no entry" not in line + ) + rows.append(("server", "temporary buckets left", "0", str(left_buckets))) + rows.append(("server", "probe objects left", "0", str(left_objects))) + + width = max(len(name) for _, name, _, _ in rows) + print( + f"S3 {stand['host']}:{stand['port']} (host 127.0.0.1:" + f"{stand['out_port']}), bucket {stand['bucket']}, image " + f"{stand['image'].split('@')[0]}", + ) + print(f"{'where':<8} {'check':<{width}} expected got verdict") + failed = 0 + for where, name, expected, got in rows: + ok = expected == got + failed += not ok + print( + f"{where:<8} {name:<{width}} {expected:<8} {got:<6} " + f"{'ok' if ok else 'FAIL'}", + ) + for problem in problems: + print(f"FAIL: {problem}") + if failed or problems: + names = [f"{w}: {n}" for w, n, e, g in rows if e != g] + print( + f"FAIL: {failed} check(s) failed" + + (f": {'; '.join(names)}" if names else ""), + ) + return 1 + print(f"PASS: {len(rows)} checks, bucket {stand['bucket']} is private") + return 0 + + # stop-at-start: записи журнала, по которым видны этапы старта и остановки STARTED_SERVER = "Started server process" SERVER_RUNNING = "Uvicorn running on" @@ -1923,6 +2195,7 @@ def main() -> int: help="код 1 без ключей тестовой базы (сценарий «Временная база»)", ) sub.add_parser("auth-storage") + sub.add_parser("s3-check") stop = sub.add_parser("stop-at-start") stop.add_argument("--image", default="mtusi-messenger:lab4") stop.add_argument( @@ -1993,6 +2266,8 @@ def main() -> int: ) if args.cmd == "auth-storage": return cmd_auth_storage(port) + if args.cmd == "s3-check": + return cmd_s3_check() if args.cmd == "stop-at-start": return cmd_stop_at_start( args.image, diff --git a/.env.example b/.env.example index 68b3e6b7..1e42391c 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,8 @@ # Шаблон .env: `make env_setup` создаёт из него .env, не перезаписывая -# существующий файл, и подставляет случайные POSTGRES_PASSWORD и -# VALKEY_PASSWORD. В существующий .env новые строки переносятся руками. +# существующий файл, и подставляет случайные значения в пустые +# POSTGRES_PASSWORD, VALKEY_PASSWORD и пять секретов S3 (S3_ROOT_*, +# S3_JWT_SIGNING_KEY, S3_API_*). В существующий .env новые строки +# переносятся руками, секреты для них — openssl rand -hex 32. # .env не коммитить. .env читают compose, Makefile и приложение # (pydantic-settings); в контейнеры он не попадает. # Параметры приложения — в формате настроек SECTION__FIELD, без секции — @@ -11,8 +13,8 @@ # с lab3 — API_REPLICAS, IDEMPOTENCY_TTL_SECONDS, с lab4 — S3_ENDPOINT, # S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID_FILE, S3_SECRET_ACCESS_KEY_FILE, # MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS) — в REPORT.md, «Архитектура и -# решения». Строк S3 и вложений здесь пока нет: они появятся вместе с -# хранилищем лабы 4. +# решения». Имена skeleton S3_* буквально не заводятся: S3 настраивают +# строки блока S3 ниже. # порт сервиса ([app] port): на нём слушает приложение, его же # публикует compose, на нём же healthcheck @@ -62,6 +64,37 @@ CACHE__HOST=127.0.0.1 CACHE__PORT=${VALKEY_OUT_PORT} CACHE__PASSWORD=${VALKEY_PASSWORD} +# S3 (SeaweedFS) — байты вложений. Пять пустых секретов make env_setup +# заменяет случайными hex; без них compose не стартует. Кто какой секрет +# получает — docker-compose.yml, якоря x-s3-* +# имя bucket: читают приложение ([s3] bucket) и bootstrap S3, который его +# создаёт; 3–63 символа: строчные буквы, цифры, точка и дефис +S3__BUCKET=messenger +# административные ключ и секрет S3: только сервер s3 (без учётной +# записи он открыт анониму), ни API, ни bootstrap их не получают +S3_ROOT_ACCESS_KEY= +S3_ROOT_SECRET_KEY= +# ключ подписи служебных вызовов SeaweedFS (gRPC шлюза, IAM filer): +# сервер s3 и bootstrap +S3_JWT_SIGNING_KEY= +# ключи пользователя API (только объекты своего bucket): bootstrap +# заводит пользователя с ними, реплики API ходят с ними в S3. Новый +# секрет вступает в силу при следующем bootstrap (make run_docker) +S3_API_ACCESS_KEY= +S3_API_SECRET_KEY= +# адрес и порт API S3 внутри сети compose: по ним ходит API в docker, +# порт слушает сам сервер и проверяет bootstrap +S3_HOST=s3 +S3_PORT=8333 +# порт на 127.0.0.1 хоста, куда публикуется API S3: к нему подключается +# приложение в console (консоль и UI SeaweedFS не публикуются) +S3_OUT_PORT=8334 +# мосты для console: в docker их задаёт environment compose +S3__HOST=127.0.0.1 +S3__PORT=${S3_OUT_PORT} +S3__ACCESS_KEY_ID=${S3_API_ACCESS_KEY} +S3__SECRET_ACCESS_KEY=${S3_API_SECRET_KEY} + # make test_isolated: порт на 127.0.0.1, куда публикуется тестовый # контейнер API TEST_APP_PORT=18088 diff --git a/AGENTS.md b/AGENTS.md index 77b53e9c..fa3c7a93 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,9 @@ S3-совместимое хранилище и вложения-изображ `contracts/README.md`, раздел «Вложения (с lab4)»). Код перенесён из лабы 3 (репозиторий `mtusi2026lab3-safronov`, ветка `solution/bvt2301-safronov`, commit `ce89eba`) по разделу «Переход в -следующую лабу»; S3 и вложений в нём ещё нет. План работ, решения и +следующую лабу». S3 в стенде — change `s3-storage`: SeaweedFS с +приватным bucket, bootstrap и клиент `src/infra/s3/`; вложений (ручек, +`attachment_ids`) ещё нет. План работ, решения и трек «5» — `PLAN.md`. Из лабы 2: PostgreSQL как источник истины, вход по Basic → Bearer-сессия, Valkey — кэш карточек чатов. Из лабы 3: HAProxy перед ≥2 репликами API @@ -25,7 +27,8 @@ S3-совместимое хранилище и вложения-изображ открытых записей. Отчёт, evidence и рабочий план лабы 3 остались в её репозитории (`REPORT.md`, `evidence/`, `git show 063eedb:PLAN.md`). Стек: Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, -structlog (JSON в stdout), redis-py (клиент Valkey). +structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore +(клиент S3). Репозиторий — fork skeleton преподавателя. Задание, контракт и публичные проверки уже лежат в нём. Реализацию, Dockerfile, compose, собственные @@ -87,7 +90,8 @@ structlog (JSON в stdout), redis-py (клиент Valkey). публичной точкой входа; порты реплик наружу не публикуются, sticky session нет. В памяти процесса нет ничего, от чего зависит корректность: сессии, данные и ключи идемпотентности — в Postgres, - Valkey — общий кэш неизменяемых карточек. В каждом ответе API — + Valkey — общий кэш неизменяемых карточек, S3 — байты вложений. В + каждом ответе API — `X-Instance-Id`. `POST` сообщения требует `Idempotency-Key`; ключ и сообщение пишутся в одной транзакции (`api-contract.md`, `service-layer.md`). Миграции — однократно, отдельным сервисом, не @@ -96,6 +100,16 @@ structlog (JSON в stdout), redis-py (клиент Valkey). rolling_update`. Стенд и отказы — `balancer.md`. В каждом процессе uvicorn по-прежнему один worker: масштабирование — числом реплик. Всё это сохраняется в лабе 4. +- Лаба 4, S3 (change `s3-storage`): SeaweedFS в стенде, образ + закреплён тегом и digest, volume `s3_data`. Bucket приватен с первой + секунды: административная пара — только у сервера, служебные + серверы — на loopback контейнера, gRPC шлюза закрыт ключом подписи. + Bucket, политику и пользователя API создаёт одноразовый + `s3-bootstrap` (идемпотентно, сам проверяет приватность), реплики ждут + его, как миграций. У API — только ключи своего пользователя (чтение, + запись, удаление объектов своего bucket). `/health/ready` S3 не + проверяет. Приватность вне API — `make s3_check` (`docker.md`, + `infra.md`, design change `s3-storage`). - `.env`, `config.toml`, секреты, токены и реальные данные не попадают ни в git, ни в образ. В `evidence/` и `REPORT.md` — только обезличенные выводы команд. @@ -166,12 +180,12 @@ structlog (JSON в stdout), redis-py (клиент Valkey). | `service-layer.md` | `src/core/services/**` | | `repo-layer.md` | `src/core/repos/**` | | `dto.md` | `src/schemas/**` | - | `infra.md` | `src/infra/**`: логгер, PostgreSQL (engine, пул, таймауты), readiness, кэш Valkey (повтор только на обрыв, срок на команду, обход при отказе) и другие клиенты | + | `infra.md` | `src/infra/**`: логгер, PostgreSQL (engine, пул, таймауты), readiness, кэш Valkey (повтор только на обрыв, срок на команду, обход при отказе), клиент S3 (без повторов, срок на вызов, перевод ошибок) и другие клиенты | | `auth.md` | `src/**/session.py`, сервис пользователей, `dependencies.py`, `errors.py`, идентификация в `student-tests/`: пароль и KDF, разбор Basic, токен, срок и отзыв сессии | | `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, volumes, restart hook | + | `docker.md` | `Dockerfile`, `docker-compose.yml`, `.dockerignore`, `scripts/restart.sh`, `infra/**`: мультистейдж, 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`), что не меняется между метками замеров, граница чёрного ящика и планы запроса, сравнение меток, коммиты измеренных состояний | @@ -262,11 +276,11 @@ structlog (JSON в stdout), redis-py (клиент Valkey). | `make load` | нагрузка из `tests/load.py`; параметры — `tests/README.md` | | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | сохранность: создаёт данные и сессию, вызывает restart hook, проверяет те же данные прежним токеном (`tests/README.md`) | | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | отказ одной API-реплики через LB: 15 с записи параллельно hook, восстановление записи ≤10 с, без дублей (`tests/README.md`). `STOP_MODE=kill` — без graceful, `STOP_ONE_LOG=<файл>` — какой `TARGET_INSTANCE_ID` и контейнер остановлен. Между прогонами — `make replicas` | -| `make run_dev` | `make upgrade` (Postgres из compose и миграции) и `make start_cache`, затем `APP__RUN_MODE=console uv run python -m src`: 127.0.0.1:8080, reload | +| `make run_dev` | `make upgrade` (Postgres из compose и миграции), `make start_cache` и `make start_s3`, затем `APP__RUN_MODE=console uv run python -m src`: 127.0.0.1:8080, reload | | `make lint` | `ruff format` + `ruff check --fix`, дважды: так нужно из-за COM812; `tests/` и `scripts/` skeleton исключены в `[tool.ruff]` | -| `make env_setup` | `.env.example` → `.env` со случайными `POSTGRES_PASSWORD` и `VALKEY_PASSWORD`, `config_example.toml` → `config.toml`; существующие файлы не перезаписывает (новые строки шаблона переносятся руками) | -| `make run_docker` | `make env_setup` (только недостающие файлы) + `docker compose build` + `up -d`: postgres, valkey → migrate → api × `API_REPLICAS` (2) → haproxy на `127.0.0.1:APP_OUT_PORT`; `config.toml`, `infra/valkey/valkey.conf` и `infra/haproxy/haproxy.cfg` монтируются read-only. Реплики с изменённым образом пересоздаются все разом; без простоя — `make rolling_update` | -| `make stop` / `make down` | остановить / удалить контейнеры compose; volume с данными остаётся | +| `make env_setup` | `.env.example` → `.env` со случайными `POSTGRES_PASSWORD`, `VALKEY_PASSWORD` и пятью секретами S3 (печатает только имена), `config_example.toml` → `config.toml`; существующие файлы не перезаписывает (новые строки шаблона переносятся руками) | +| `make run_docker` | `make env_setup` (только недостающие файлы) + `docker compose build` + `up -d`: postgres, valkey, s3 → migrate, s3-bootstrap → api × `API_REPLICAS` (2) → haproxy на `127.0.0.1:APP_OUT_PORT`; `config.toml`, `infra/valkey/valkey.conf`, `infra/haproxy/haproxy.cfg` и `infra/s3/bootstrap.sh` монтируются read-only. Реплики с изменённым образом пересоздаются все разом; без простоя — `make rolling_update` | +| `make stop` / `make down` | остановить / удалить контейнеры compose; volumes с данными остаются; S3 останавливается плавно ~15 с | | `make logs` | журнал всех реплик API, каждая строка — JSON (`--no-log-prefix`), реплика — поле `instance_id` | | `make replicas [API_REPLICAS=N]` | вернуть остановленные реплики (те же ID) и выставить их число, ждать `healthy` (`balancer.md`) | | `make instances` | вход одним синтетическим пользователем, 12 × `GET /users/me` через LB: `X-Instance-Id` каждого ответа и итог по репликам | @@ -274,19 +288,21 @@ structlog (JSON в stdout), redis-py (клиент Valkey). | `make rolling_update [COMMIT=...] [MIGRATE=0]` | поочерёдная замена реплик без простоя (`scripts/rolling-update.sh`, `balancer.md`): сборка из рабочего дерева (или файлов `COMMIT` через `git archive`), миграции один раз, затем по одной — новая `healthy` и `UP` в LB, старая `drain` → запросов в полёте 0 → `maint` → stop → rm → слот `ready`. Нужен штатный стенд (`make replicas`) без слотов LB в ручном `drain` / `maint` (иначе код 2 и команда `set server … state ready`); сбой и Ctrl+C — `API_REPLICAS` готовых реплик, повтор доводит; `MIGRATE=0` — откат на прежний образ (после него `docker compose up` без сборки не запускать: `migrate` прежнего образа упадёт на новой ревизии) | | `make start_db` / `make stop_db` | Postgres стенда: `up -d --wait postgres` / `stop postgres` | | `make start_cache` / `make stop_cache` | Valkey стенда: `up -d --wait valkey` / `stop valkey`; volume нет, кэш после рестарта пуст | +| `make start_s3` / `make stop_s3` | S3 стенда: `up -d --wait s3`, затем `up --no-deps --exit-code-from s3-bootstrap s3-bootstrap` (код bootstrap — код цели: `--wait` одноразовый сервис не ждёт) / `stop s3` | +| `make s3_check` | приватность bucket вне API на запущенном стенде (`driver.py s3-check`): bootstrap в режиме `check` (права ключа API, чужой временный bucket, административные запросы), анонимные запросы с хоста и из сети стенда, порты контейнера S3 из сети, затем `cleanup`; таблица «где → проверка → ожидаемо → получено», код 1 при нарушении | | `make upgrade` | `start_db` + `uv run alembic upgrade head` с хоста (`127.0.0.1:POSTGRES_OUT_PORT`) | | `make revision` | `upgrade` + `alembic revision --autogenerate`, сообщение спрашивает `read -p` | -| `make wipe_data` | `down -v` — удалить данные стенда (и кэш); только после ввода `yes` | -| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_` с Valkey стенда (ключи разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test EXPECT_REPLICAS=1` (тесты реплик пропускаются с причиной), уборка при любом исходе (`student-tests.md`) | +| `make wipe_data` | `down -v` — удалить данные стенда (volumes Postgres и S3 называются в запросе) и кэш; только после ввода `yes` | +| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_` с Valkey и S3 стенда (ключи кэша и объектов разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test EXPECT_REPLICAS=1` (тесты реплик пропускаются с причиной), уборка при любом исходе — база и объекты под префиксом `test_/` (`student-tests.md`) | | `make student_test [BASE_URL=...] [EXPECT_REPLICAS=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера, кроме проверок отказов (`-m 'not fault'`); `EXPECT_REPLICAS` (по умолчанию `API_REPLICAS`) — сколько реплик за `BASE_URL`, против одного процесса — 1; сервер недоступен — код 2 и одна строка с адресом | -| `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, ~60 с) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres и Valkey, обычный и «тесный» API (срок 2 с, пул 1), hook `student-tests/fault_hook.py`; после тестов — журнал PostgreSQL стенда: сводка (`crash markers`, «too many clients», «administrator command») и ненулевой код при признаках аварийного перезапуска; стенд и его volume удаляются при любом исходе, рабочий не трогается (`student-tests.md`) | +| `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, ~70 с) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres, Valkey и S3 (с bootstrap), обычный и «тесный» API (срок 2 с, пул 1), hook `student-tests/fault_hook.py`; после тестов — журнал PostgreSQL стенда: сводка (`crash markers`, «too many clients», «administrator command») и ненулевой код при признаках аварийного перезапуска; стенд и его volumes удаляются при любом исходе, рабочий не трогается (`student-tests.md`) | | `make bench [BENCH_LABEL=...]` | полная матрица 10k / 100k / 500k читаемого чата плюс 100 000 сообщений в 1 110 фоновых чатах разного размера (~35 мин, оценка по `bench_quick`) на своём проекте compose `mtusi-bench` (HAProxy и одна реплика API, Postgres, Valkey с лимитами, без портов хоста и без `.env` рабочего стенда; k6 ходит через LB); на каждый размер — свежий стенд, `VACUUM (ANALYZE)`, планы запроса истории (`auto_explain`) по уровням чатов с вариантами индекса и запроса, в конце — пробы стоимости записи по вариантам. Результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста (`bench.md`) | | `make bench_quick` | самопроверка стенда на 1k / 5k / 10k и 3 500 фоновых сообщений (~3 мин), метка `quick-<время>`, в git не идёт | | `make bench_restore [RESTORE_LABEL=...]` | трек 2, восстановление (~20 мин, метка `restore` по умолчанию): тот же стенд и данные, без матрицы прогонов; на каждый размер — `pg_dump` во время записи через HTTP, активность после backup, `pg_restore -j` в новый контейнер Postgres на новом volume, сверка обеих баз построчно, переключение API, проверки через HTTP до и после `FLUSHALL`; время dump / restore / RTO и потерянные сообщения — в `summary.md` | | `make bench_restore_quick` | то же на 1k / 5k / 10k (~1,5 мин), метка `quick-restore-<время>`, в git не идёт; сценарий защиты трека 2 | | `make bench_failover [FAILOVER_LABEL=...]` | уровень 4, отказ реплик под нагрузкой (~6 мин, метка `baseline` по умолчанию): стенд `mtusi-bench` с HAProxy и двумя репликами с лимитами рабочего стенда, k6 — 100 записей с ключом и 100 чтений в секунду; каждая реплика в режимах `stop`, `kill`, `pause` с возвратом. Посекундная шкала, время исключения из LB и восстановления, сверка записей после повтора с тем же ключом, CPU и память каждого компонента по окнам фазы (сэмплер `scan`, `resources.csv`, `samples.csv`; CPU на запрос — только до действия) — `evidence/failover/<метка>/`. Перед запуском — проверка хоста (`bench.md`): питание, давление памяти, `Swapouts` без роста; сумма лимитов на пике больше CPU ВМ — код 2 | | `make bench_failover_quick` | то же короче, режимы `stop` и `kill` (~2 мин), с ресурсами, метка `quick-failover-<время>`, в git не идёт | -| `make bench_rollout [ROLLOUT_LABEL=...]` | уровень 4, поочерёдная замена под нагрузкой (~3 мин, метка `baseline` по умолчанию): стенд `mtusi-bench` как у `bench_failover`, реплики на образе прежнего commit (`Profile.rollout_from`, `git archive`), та же нагрузка; посреди неё `scripts/rolling-update.sh` меняет их на образ текущего checkout. Посекундная шкала с ответами старых и новых реплик, шаги по репликам, контейнеры, образы и ревизия до и после, сверка записей, CPU и память каждой старой и новой реплики, миграции и остальных компонентов по окнам до / подготовка / замена / после (CPU на запрос — до и после) — `evidence/rollout/<метка>/`. Перед запуском — проверка хоста (`bench.md`) | +| `make bench_rollout [ROLLOUT_LABEL=...]` | уровень 4, поочерёдная замена под нагрузкой (~3 мин, метка `baseline` по умолчанию): стенд `mtusi-bench` как у `bench_failover`, реплики на образе прежнего commit (`Profile.rollout_from`, `git archive`; сейчас commit лабы 3, которого здесь нет — `KNOWN_ISSUES.md`, обход `--from`), та же нагрузка; посреди неё `scripts/rolling-update.sh` меняет их на образ текущего checkout. Посекундная шкала с ответами старых и новых реплик, шаги по репликам, контейнеры, образы и ревизия до и после, сверка записей, CPU и память каждой старой и новой реплики, миграции и остальных компонентов по окнам до / подготовка / замена / после (CPU на запрос — до и после) — `evidence/rollout/<метка>/`. Перед запуском — проверка хоста (`bench.md`) | | `make bench_rollout_quick` | то же с короткими окнами (~2 мин), с ресурсами, метка `quick-rollout-<время>`, в git не идёт | | `make bench_scaling SERIES=a\|b\|pool\|ab\|db\|db4 [SCALING_LABEL=...] [RESUME=1]` | уровень 5, трек 1: серия на стенде `mtusi-bench` (метка `scaling-<серия>` по умолчанию). `a` — бюджет 4 CPU: 1 × 4, 2 × 2, 4 × 1 (~50 мин); `b` — 1…6 реплик по 1 CPU (~100 мин); `pool` — 4 реплики при `max_connections` 100 и 50 (~35 мин); `ab` — 1 × 1 и 6 × 1 для «до/после» и A/A (~35 мин); `db` — 1, 2, 4 реплики при PostgreSQL 0,5 CPU и контроль 4 × 1 при 2 CPU (~50 мин); `db4` — только 4 × 1 при 0,5 и 2 CPU (~25 мин, «до/после» `scaling-improvement`); `db_quick` — самопроверка серии `db` (~4 мин, метка `quick-*`). Ячейка — конфигурация × повтор (3), свежий стенд; открытая модель 70/20/10, фиксированные 250 и 500/с и поиск R* по SLO; сэмплер контейнеров, ВМ, LB и PostgreSQL. `RESUME=1` — продолжить прерванную метку на том же commit. Перед запуском — проверка хоста, рабочий стенд — `make stop`; метку коммитить до следующей серии (`bench.md`) | | `make bench_scaling_quick` | самопроверка серий: 1 × 1 и 2 × 1 при `max_connections` 50, короткие окна (~4 мин), метка `quick-scaling-<время>`, в git не идёт | @@ -309,7 +325,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey). src/ __main__.py # python -m src: early_stop.install() до импорта приложения → main.main() main.py # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run - config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] pool_size 10 и max_overflow 0 (постоянный пул без переполнения), idle_in_transaction_timeout_ms, [idempotency] ttl_seconds + config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] pool_size 10 и max_overflow 0 (постоянный пул без переполнения), idle_in_transaction_timeout_ms, [s3] адрес, bucket (валидатор имени), ключи API, регион, сроки, пул и endpoint_url, [idempotency] ttl_seconds api/ routers/health.py # /health/live, /health/ready: вне версии, без идентификации routers/v1/.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py) @@ -322,7 +338,7 @@ src/ repos/idempotency.py # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO services/.py # Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ и сообщение одной транзакцией - exceptions/.py # доменные исключения, реэкспорт в __init__.py + exceptions/.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing infra/ early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped API before startup» и выход 0; disarm() — первая строка lifespan logger.py # structlog, get_logger(), contextvar-ы request_id / user_id, instance_id в каждой записи @@ -333,11 +349,13 @@ src/ db/models/ # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit cache/client.py # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск cache/instance.py # глобал cache процесса API + s3/client.py # create_object_storage (aiobotocore: path-адресация, без повторов, пул), ObjectStorage: put / head / open (чтение блоками) / delete, срок на вызов и блок, ошибки → ObjectStorageUnavailable / StoredObjectMissing; StoredObjectInfo, StoredObject + s3/instance.py # глобал object_storage процесса API, namespace — имя базы; start() и aclose() в lifespan schemas/ dataclasses/.py # DTO между repo → service → api enums/.py # StrEnum доменов, RunModeEnum utils/ - constants.py # лимиты контракта, размер страницы, префиксы путей + constants.py # лимиты контракта, размер страницы, префиксы путей, имя bucket S3, разделитель ключа объекта, keep-alive клиента S3 utc.py # utcnow() (aware UTC), формат RFC 3339 с Z cursor.py # непрозрачный keyset-курсор: кодирование и разбор; поля проверяются по отдельности, незнакомые игнорируются, смена формата — новая CURSOR_VERSION student-tests/ # black-box тесты по HTTP (уровень 4): make student_test @@ -350,10 +368,10 @@ student-tests/ # black-box тесты по HTTP (уровень 4) test_rubric.py, test_race.py # обязательные сценарии и гонки уровня 4 test_.py # сценарии основных спеков, маркер @pytest.mark.spec test_failures.py # проверки отказов (маркер fault): только make failure_checks - run_isolated.py # make test_isolated: образ на временной базе test_ (stdlib) - run_failures.py # make failure_checks: стенд <рабочий>-failures, два API, pytest -m fault, журнал PostgreSQL стенда (сводка, признаки аварии — ненулевой код), уборка (stdlib) - fault_hook.py # hook стенда отказов: stop/start/pause/unpause, кэш, триггеры сбоя участников и сообщений, заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions (stdlib) - failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, LB), healthcheck PostgreSQL — на служебную базу postgres (не добавляет сессий в базу приложения), init: true у PostgreSQL (сирот psql из fill-connections подбирает init, а не postmaster) + run_isolated.py # make test_isolated: образ на временной базе test_, уборка базы и префикса test_/ в S3 (weed shell fs.rm, префикс только из проверенного имени) (stdlib) + run_failures.py # make failure_checks: стенд <рабочий>-failures (Postgres, Valkey, S3 + bootstrap), два API, pytest -m fault, журнал PostgreSQL стенда (сводка, признаки аварии — ненулевой код), уборка (stdlib) + fault_hook.py # hook стенда отказов: stop/start/pause/unpause postgres|valkey|s3, кэш, триггеры сбоя участников и сообщений, заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions (stdlib) + failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, S3, LB), stop_grace_period 2 с у S3, healthcheck PostgreSQL — на служебную базу postgres (не добавляет сессий в базу приложения), init: true у PostgreSQL (сирот psql из fill-connections подбирает init, а не postmaster) bench/ # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover / bench_rollout / bench_scaling run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover (события цели — поток docker events по контейнеру, а не буфер демона), профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker с exec_start), ресурсы профилей failover и rollout (Profile.sample_resources: сэмплер scan, карта контейнеров по меткам compose, окна, бюджет на пике, сторож), серии трека 1 (профили scaling_*, ячейки на свежем стенде, ступени k6 и поиск R*, сэмплер, продолжение RESUME, блокировка bench/.bench.lock), метрики (сумма по репликам), runs.csv / phases.csv / searches.csv / samples.csv / summary.md / meta.json scaling.py # серии трека 1 без docker: лестница и автомат поиска R*, разбор итога k6 и строк сэмплера, агрегаты окна, вердикт SLO и брака генератора, признаки узкого места (THRESHOLDS), предельный CPU на запрос, сводка серии; --selftest @@ -362,20 +380,21 @@ bench/ # нагрузочный стенд на HAProxy + resources.py # ресурсы профилей failover и rollout без docker: интервалы контейнеров (сброс при новой cgroup, заморозка, новые контейнеры с момента запуска), окна, CPU / троттлинг / память по компонентам и ВМ, CPU на запрос в установившихся окнах, resources.csv / samples.csv, разделы summary.md; --selftest failover.py # профиль failover без docker: строки k6 о запросах, статистика и журнал HAProxy, события Docker, посекундная шкала, величины фазы, summary.md rollout.py # профиль rollout без docker: строки скрипта замены, события контейнеров проекта, состояния слотов LB (UP, drain, maint, ready), шаги по репликам, шкала со старыми и новыми ответами, окна до / во время / после, summary.md - bench.compose.yml # override стенда mtusi-bench: имена, BENCH_API_REPLICAS реплик api без container_name, haproxy с лимитами BENCH_LB_*, лимиты BENCH_* (deploy.resources), без портов и config.toml, auto_explain - bench.env # подстановки compose стенда вместо .env рабочего стенда (без паролей) + bench.compose.yml # override стенда mtusi-bench: имена, BENCH_API_REPLICAS реплик api без container_name, haproxy с лимитами BENCH_LB_*, лимиты BENCH_* (deploy.resources), без портов и config.toml, auto_explain; s3 описан (mtusi-bench-s3, без порта), но профили его не запускают + bench.env # подстановки compose стенда вместо .env рабочего стенда (без паролей и секретов S3: их генерирует run.py) k6/ # сценарии k6 (через LB http://haproxy:8080): prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления), failover (постоянная интенсивность записи и чтения, строка на запрос) и retry (повтор неуспешных записей с тем же ключом), mixed (ступень серии трека 1: ramping-arrival-rate 70/20/10, тег окна, распределение по X-Instance-Id, досрочный выход); lib.js — Bearer, messageHeaders (новый или заданный Idempotency-Key) и хелперы compare.py # make bench_compare: дельта двух меток (ячейки матрицы или общие конфигурации серий), уровень шума, эффект или шум; отказ при разной методике, в том числе метке без LB и серии против матрицы ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд, с --series — серии трека 1 migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose infra/ # конфигурации сервисов стенда; README.md — skeleton valkey/valkey.conf # лимит памяти и LRU, persistence выключен + s3/bootstrap.sh # bootstrap S3 (сервис s3-bootstrap, network_mode: service:s3): apply — bucket, анонимный доступ none, политика api-objects, пользователь api и ключ из .env, проверки приватности; check и cleanup — для make s3_check; секреты — stdin weed shell и файл curl на tmpfs haproxy/haproxy.cfg # LB рабочего стенда и bench/: реплики через DNS Docker (8 слотов), проверки /health/ready (inter, fastinter, формулы обнаружения), цепочка таймаутов, http-reuse never (простаивающее соединение закрывает LB), повтор только на conn-failure, ответы LB в формате контракта, мониторинг :8404, runtime API на 127.0.0.1:9999 внутри контейнера (drain / maint / ready при замене) -scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh: LB, все реплики api, postgres, valkey +scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh: LB, все реплики api, postgres, valkey, s3 (~25 с); start api повторяет migrate и s3-bootstrap (no-op) scripts/stop-one.sh # failover hook для make test-failover: TARGET_INSTANCE_ID → реплика api этого проекта, STOP_MODE stop или kill, STOP_ONE_LOG scripts/rolling-update.sh # make rolling_update: предусловия (в том числе слоты LB без ручного состояния), сборка (или COMMIT через git archive), миграции один раз в контейнере сервиса migrate, по одной: новая UP в LB → старая drain → maint → stop (код выхода в строке) → rm → слот ready; trap при сбое и Ctrl+C; тот же скрипт — профиль rollout стенда bench/ Dockerfile # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck -docker-compose.yml # проект mtusi-lab4: postgres, valkey, migrate, api × API_REPLICAS без портов, haproxy — единственный порт API; адреса и порты из .env, volume postgres_data, лимиты у всех, окружение по сервисам +docker-compose.yml # проект mtusi-lab4: postgres, valkey, s3 (SeaweedFS, служебное на loopback, API S3 на 127.0.0.1:S3_OUT_PORT), migrate, s3-bootstrap, api × API_REPLICAS без портов, haproxy — единственный порт API; адреса и порты из .env, volumes postgres_data и s3_data, лимиты у всех, окружение и секреты по сервисам (x-db-env, x-cache-env, x-s3-env) .dockerignore config_example.toml, .env.example evidence/storage/ # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone; connection-cost.md — цена нового соединения и пинга @@ -470,7 +489,7 @@ KNOWN_ISSUES.md # найденные попутно дефекты, - Переносить: `src/`, `student-tests/`, `migrations/`, `alembic.ini`, `Dockerfile`, `docker-compose.yml`, `infra/valkey/`, - `infra/haproxy/` (без `infra/README.md` skeleton), свои + `infra/haproxy/`, `infra/s3/` (без `infra/README.md` skeleton), свои `scripts/restart.sh`, `scripts/stop-one.sh` и `scripts/rolling-update.sh` (без примеров и проверок skeleton в `scripts/`), `pyproject.toml`, `uv.lock`, `.python-version`, diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md index c54dcdd5..b7fdf77b 100644 --- a/KNOWN_ISSUES.md +++ b/KNOWN_ISSUES.md @@ -3,4 +3,20 @@ Найдены попутно, не исправлены без отдельной просьбы (AGENTS.md). Исправленные удаляются отсюда, история — в git. -Открытых записей нет: записи лабы 3 исправлены change `fix-known-issues`. +## Профиль `rollout` ссылается на commit лабы 3 + +- **Где:** `bench/run.py`, профили `rollout` и `rollout_quick`: + `rollout_from="c50b721"`. +- **Что:** commit `c50b721` — из репозитория лабы 3 + (`mtusi2026lab3-safronov`), в истории лабы 4 его нет. `make + bench_rollout_quick` и `make bench_rollout` падают за 6 с: `git + rev-parse c50b721^{commit}` — «Needed a single revision», exit 128. + Найдено в apply change `s3-storage` (2026-10-20); от S3 не зависит: + код перенесён так в `5d5d8f9`. +- **Обход:** `uv run python bench/run.py --profile rollout_quick --label + quick-rollout-<время> --from 5d5d8f9` — код 0 на рабочем дереве + `s3-storage`. +- **Предложение:** `rollout_from` — последний commit лабы 4 до + измеряемого изменения (сейчас `5d5d8f9`, перенос кода лабы 3), а в + `bench.md` — правило менять его при переходе в следующую лабу + (раздел «Переход в следующую лабу» AGENTS.md). diff --git a/Makefile b/Makefile index 21d651fd..8e4193d7 100644 --- a/Makefile +++ b/Makefile @@ -34,21 +34,31 @@ test-failover: # Приложение на хосте (свои цели; цели skeleton выше не менять) # ------------------------- -# Postgres из compose и миграции, Valkey из compose, затем сервис на -# хосте: 127.0.0.1:APP__PORT, reload по src/ +# Postgres из compose и миграции, Valkey и S3 с bootstrap из compose, +# затем сервис на хосте: 127.0.0.1:APP__PORT, reload по src/ .PHONY: run_dev -run_dev: upgrade start_cache +run_dev: upgrade start_cache start_s3 APP__RUN_MODE=console uv run python -m src # шаблоны копируются только если файла ещё нет: локальные значения # не затираются. В новый .env подставляются случайные пароли Postgres и -# Valkey: в шаблоне они пустые, общего пароля стенда в git нет +# Valkey и секреты S3: в шаблоне они пустые, общего секрета стенда в git +# нет. Печатаются только имена, значения — нет +ENV_SECRETS = POSTGRES_PASSWORD VALKEY_PASSWORD S3_ROOT_ACCESS_KEY S3_ROOT_SECRET_KEY S3_JWT_SIGNING_KEY S3_API_ACCESS_KEY S3_API_SECRET_KEY .PHONY: env_setup env_setup: - @test -f .env || sed \ - -e "s/^POSTGRES_PASSWORD=$$/POSTGRES_PASSWORD=$$(openssl rand -hex 16)/" \ - -e "s/^VALKEY_PASSWORD=$$/VALKEY_PASSWORD=$$(openssl rand -hex 16)/" \ - .env.example > .env + @if [ ! -f .env ]; then \ + sed \ + -e "s/^POSTGRES_PASSWORD=$$/POSTGRES_PASSWORD=$$(openssl rand -hex 16)/" \ + -e "s/^VALKEY_PASSWORD=$$/VALKEY_PASSWORD=$$(openssl rand -hex 16)/" \ + -e "s/^S3_ROOT_ACCESS_KEY=$$/S3_ROOT_ACCESS_KEY=$$(openssl rand -hex 10)/" \ + -e "s/^S3_ROOT_SECRET_KEY=$$/S3_ROOT_SECRET_KEY=$$(openssl rand -hex 20)/" \ + -e "s/^S3_JWT_SIGNING_KEY=$$/S3_JWT_SIGNING_KEY=$$(openssl rand -hex 32)/" \ + -e "s/^S3_API_ACCESS_KEY=$$/S3_API_ACCESS_KEY=$$(openssl rand -hex 10)/" \ + -e "s/^S3_API_SECRET_KEY=$$/S3_API_SECRET_KEY=$$(openssl rand -hex 20)/" \ + .env.example > .env; \ + echo "new .env with random $(ENV_SECRETS)"; \ + fi @test -f config.toml || cp config_example.toml config.toml @echo "env ready: .env, config.toml" @@ -68,7 +78,8 @@ API_REPLICAS ?= 2 EXPECT_REPLICAS ?= $(API_REPLICAS) DC=docker compose -# стенд: postgres, valkey -> migrate -> api × API_REPLICAS -> haproxy +# стенд: postgres, valkey, s3 -> migrate, s3-bootstrap -> api × +# API_REPLICAS -> haproxy # (единственный порт API на хосте — у haproxy). env_setup создаёт # недостающие .env и config.toml из шаблонов: без config.toml compose не # запустится (bind с create_host_path: false), без паролей — тоже. @@ -120,10 +131,12 @@ revision: upgrade @read -p "Сообщение миграции (англ., прошедшее время): " msg; \ uv run alembic revision --autogenerate -m "$$msg" -# удалить контейнеры стенда и volume с данными: только после ввода yes +# удалить контейнеры стенда и volumes с данными: только после ввода yes .PHONY: wipe_data wipe_data: - @read -p "Удалить все данные стенда (volume Postgres)? Введите yes: " answer; \ + @project=$$($(DC) config | sed -n 's/^name: //p'); \ + volumes=$$($(DC) config --volumes | sed "s/^/$${project}_/" | paste -sd ' ' -); \ + read -p "Удалить все данные стенда (volumes Postgres и S3: $$volumes)? Введите yes: " answer; \ if [ "$$answer" = "yes" ]; then \ $(DC) down -v --remove-orphans; \ else \ @@ -146,6 +159,33 @@ stop_cache: $(DC) stop valkey +# ------------------------- +# S3 (SeaweedFS, байты вложений) +# ------------------------- + +# S3 стенда и его bootstrap: --wait ждёт healthcheck сервера, но +# одноразовый сервис считает готовым уже запущенным, поэтому bootstrap — +# отдельным up с его кодом выхода (как миграции в rolling-update.sh) +.PHONY: start_s3 +start_s3: env_setup + $(DC) up -d --wait s3 + $(DC) up --no-deps --exit-code-from s3-bootstrap s3-bootstrap + +# плавная остановка ~15 с (stop_grace_period 20 с) +.PHONY: stop_s3 +stop_s3: + $(DC) stop s3 + +# проверка приватности bucket вне API на запущенном стенде: права ключа +# API, чужой bucket и административные запросы (bootstrap в режиме check), +# анонимные запросы с хоста и из сети стенда, порты контейнера S3 из сети; +# таблица «проверка → ожидаемо → получено», проверочные объекты и bucket +# удаляются. Код 1 — нарушение +.PHONY: s3_check +s3_check: + $(PYTHON) .claude/skills/run-mtusi-messenger/driver.py s3-check + + # ------------------------- # Реплики за балансировщиком (HAProxy) # ------------------------- @@ -342,11 +382,12 @@ student_test: # образ на временной базе test_: сборка, миграции, отдельный # контейнер api на 127.0.0.1:TEST_APP_PORT, make test и make student_test, -# затем уборка при любом исходе. KEEP_TEST_DB=1 оставляет базу для разбора. -# Valkey общий с рабочим стендом: ключи кэша разделены именем базы. +# затем уборка при любом исходе. KEEP_TEST_DB=1 оставляет базу и объекты +# S3 для разбора. Valkey и S3 общие с рабочим стендом: ключи кэша и +# объектов разделены именем базы, префикс test_/ удаляется при уборке. # $(PYTHON), а не uv run: uv повторно шлёт SIGINT, и Ctrl+C обрывал уборку .PHONY: test_isolated -test_isolated: env_setup start_db start_cache +test_isolated: env_setup start_db start_cache start_s3 $(PYTHON) student-tests/run_isolated.py $(if $(KEEP_TEST_DB),--keep-db,) # проверки отказов (pytest -m fault) на отдельном стенде: свой проект diff --git a/PLAN.md b/PLAN.md index 3d57a4be..bb3c3858 100644 --- a/PLAN.md +++ b/PLAN.md @@ -519,6 +519,28 @@ design) и «Вопросы» (ждут ответа; ответ дописыв красные. Поэтому рестарт hook-ом проверяется напрямую: `StartedAt`, «exists» bootstrap, объект с тем же SHA-256. +Приняты 2026-10-20 в `/opsx:apply`, подробности — design change +`s3-storage`, «Уточнения apply». + +12. **`make start_s3` — два шага**: `up -d --wait s3`, затем `up + --no-deps --exit-code-from s3-bootstrap s3-bootstrap`. `--wait` не + ждёт завершения одноразового сервиса (compose v5.5.1), вопреки + пробе propose. Так же — `run_failures.py`. +13. **Bootstrap — режимы `apply`, `check`, `cleanup`**: проверки с хоста и + из сети идут между записью проверочного объекта и его удалением. + Новый секрет API распознаётся по `SignatureDoesNotMatch`. +14. **Клиент**: `open()` читает тело блоками, срок — на каждый блок; + ключи в botocore передаются всегда, даже пустые. +15. **Ожидаемо красные шире списка tasks**: контракт лабы 4 требует + `attachment_ids` в `Message`, код лабы 3 его не отдаёт — до + `attachments` красные 30 тестов (и 2 ошибки) `make student_test` и + 5 проверок `make failure_checks`. От S3 не зависит. +16. **Дельта `health` синхронизирована в основной спек в apply**, как в + `scaling-bench`: иначе маркер нового сценария — ссылка на + неизвестный сценарий в сверке покрытия. +17. **`rollout_from c50b721` — дефект переноса** (`KNOWN_ISSUES.md`): + профиль `rollout` проверен с `--from 5d5d8f9`. + #### Вопросы 1. Как в apply добавить строки S3 в рабочий `.env`? Агент `.env` не diff --git a/bench/bench.compose.yml b/bench/bench.compose.yml index 6efe5be1..07096ebe 100644 --- a/bench/bench.compose.yml +++ b/bench/bench.compose.yml @@ -43,6 +43,15 @@ services: memory: ${BENCH_CACHE_MEMORY:?run make bench} memswap_limit: ${BENCH_CACHE_MEMORY:?run make bench} + # S3 (лаба 4) описан, но профили лаб 2–3 его не запускают: старт стенда + # перечисляет сервисы, а реплики API поднимает с --no-deps (design change + # s3-storage, решение 9). Если сервис всё же запустят — без порта хоста, + # без перезапуска и под своим именем + s3: + container_name: mtusi-bench-s3 + restart: "no" + ports: !reset [] + migrate: image: mtusi-messenger:bench # без config.toml рабочего стенда: настройки — окружение и дефолты diff --git a/bench/bench.env b/bench/bench.env index 8653f27f..e8d9d90d 100644 --- a/bench/bench.env +++ b/bench/bench.env @@ -8,4 +8,9 @@ POSTGRES_HOST=postgres POSTGRES_PORT=5432 VALKEY_HOST=valkey VALKEY_PORT=6379 +# S3 описан в compose, но профили лаб 2–3 его не запускают; секреты S3 +# генерирует run.py +S3_HOST=s3 +S3_PORT=8333 +S3__BUCKET=bench APP__PORT=8080 diff --git a/bench/run.py b/bench/run.py index 168ea22d..4dc7ec31 100644 --- a/bench/run.py +++ b/bench/run.py @@ -95,6 +95,9 @@ ENV_FILE = ROOT / "bench" / "bench.env" # что из окружения хоста нужно самому docker compose; остальное (в том # числе POSTGRES_* из shell) в стенд не попадает HOST_ENV = ("PATH", "HOME", "USER", "TMPDIR", "DOCKER_HOST", "DOCKER_CONFIG") +# части имён переменных окружения API, которые в паспорт (stand.app_env) не +# пишутся: пароли Postgres и Valkey, секрет и ключ доступа S3 +SECRET_ENV_MARKS = ("PASSWORD", "SECRET", "ACCESS_KEY") # статистика HAProxy изнутри контейнера LB (как make lb_stats): порт 8404 # наружу не опубликован, curl в образе нет, bash есть LB_STATS = ( @@ -1196,6 +1199,11 @@ def compose_env(profile: Profile) -> dict[str, str]: Пароли хранилищ — новые на каждый прогон: живут только в этом словаре и в контейнерах стенда, в результаты не пишутся. Лимиты и срок сессии — из профиля (`BENCH_*` в `bench/bench.compose.yml`). + + Секреты S3 compose требует при разборе файла (`:?` в + `docker-compose.yml`), хотя профили лаб 2–3 сервер S3 не запускают: + реплики API получают ключи, но к S3 не обращаются (design change + `s3-storage`, решение 9). """ env = {key: os.environ[key] for key in HOST_ENV if key in os.environ} return { @@ -1203,6 +1211,11 @@ def compose_env(profile: Profile) -> dict[str, str]: "LC_ALL": "C", "POSTGRES_PASSWORD": secrets.token_urlsafe(24), "VALKEY_PASSWORD": secrets.token_urlsafe(24), + "S3_ROOT_ACCESS_KEY": secrets.token_hex(10), + "S3_ROOT_SECRET_KEY": secrets.token_hex(20), + "S3_JWT_SIGNING_KEY": secrets.token_hex(32), + "S3_API_ACCESS_KEY": secrets.token_hex(10), + "S3_API_SECRET_KEY": secrets.token_hex(20), "BENCH_APP_CPUS": profile.cpus, "BENCH_APP_MEMORY": profile.memory, "BENCH_DB_CPUS": profile.db_cpus, @@ -2170,12 +2183,15 @@ class Stand: self.replicas()[0], ), ) + # без секретов: пароли хранилищ, секрет и ключ доступа S3 app_env = dict( sorted( item.split("=", 1) for item in env if re.match(r"[A-Z0-9_]+__[A-Z0-9_]+=", item) - and "PASSWORD" not in item.split("=", 1)[0] + and not any( + mark in item.split("=", 1)[0] for mark in SECRET_ENV_MARKS + ) ), ) diff --git a/config_example.toml b/config_example.toml index 37ff94d7..3098523b 100644 --- a/config_example.toml +++ b/config_example.toml @@ -59,6 +59,19 @@ chat_ttl_seconds = 3600 # соединений в пуле клиента Valkey max_connections = 10 +[s3] +# Адрес, порт, bucket и ключи пользователя API приходят из .env (мосты к +# S3_OUT_PORT и S3_API_*, S3__BUCKET) и из environment compose; здесь их +# не указывать. +# регион подписи SigV4; SeaweedFS берёт его из запроса +region = "us-east-1" +# секунды на установку соединения с S3 +connect_timeout_seconds = 1 +# секунды на весь вызов S3; меньше timeout server HAProxy (10 с) +timeout_seconds = 5 +# соединений в пуле клиента S3 на процесс +max_connections = 10 + [idempotency] # секунды, в течение которых повтор POST сообщения с тем же # Idempotency-Key возвращает исходный результат (имя skeleton diff --git a/docker-compose.yml b/docker-compose.yml index 4b1cac47..aa463894 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,5 +1,6 @@ # Стенд лабы 4: HAProxy — единственная точка входа, за ним API × -# API_REPLICAS; PostgreSQL, Valkey (кэш) и одноразовые миграции. +# API_REPLICAS; PostgreSQL, Valkey (кэш), S3 (SeaweedFS, байты вложений), +# одноразовые миграции и bootstrap S3. # Правила — .claude/rules/docker.md и balancer.md. Значения — из .env # (шаблон .env.example); литералы только у адреса публикации 127.0.0.1 и # у режима docker. Имя проекта меняется в каждой лабе: от него зависят @@ -22,6 +23,21 @@ x-cache-env: &cache-env CACHE__PORT: ${VALKEY_PORT:-6379} CACHE__PASSWORD: ${VALKEY_PASSWORD:?VALKEY_PASSWORD is empty, copy Valkey lines from .env.example} +# S3 — только api: адрес в сети, bucket и ключи пользователя API (не +# административные). Секреты S3 по сервисам (design change s3-storage, +# решение 3): административная пара — только s3, ключ подписи — s3 и +# s3-bootstrap, ключи API — s3-bootstrap и api +x-s3-env: &s3-env + S3__HOST: ${S3_HOST:-s3} + S3__PORT: ${S3_PORT:-8333} + S3__BUCKET: ${S3__BUCKET:-messenger} + S3__ACCESS_KEY_ID: ${S3_API_ACCESS_KEY:?S3_API_ACCESS_KEY is empty, copy S3 lines from .env.example} + S3__SECRET_ACCESS_KEY: ${S3_API_SECRET_KEY:?S3_API_SECRET_KEY is empty, copy S3 lines from .env.example} + +# образ сервера S3 и bootstrap: тег с версией и digest индекса (amd64 и +# arm64) +x-s3-image: &s3-image chrislusf/seaweedfs:4.48@sha256:4e61d15fd35994cb1e43e1e553dff106794841fd9a99ade2fc8c8bfce4d7872d + # config.toml только на чтение, длинной записью: без файла запуск падает, # а не создаёт на хосте каталог config.toml/ x-config-toml: &config-toml @@ -119,6 +135,123 @@ services: cpus: "0.5" memory: 128M + # S3 — байты вложений (design change s3-storage, решения 1–2): master, + # volume, filer и шлюз S3 одним процессом weed server. Служебные серверы + # слушают только 127.0.0.1 контейнера, в сеть выходят порт API S3 + # (S3_PORT) и gRPC шлюза (S3_PORT + 10000), закрытый ключом подписи. + # Entrypoint образа сам переходит на пользователя seaweed и добавляет + # -dir=/data -volume.max=0 -master.volumeSizeLimitMB=1024 + s3: + image: *s3-image + restart: unless-stopped + command: + - server + # master, volume и filer — только loopback контейнера + - -ip=127.0.0.1 + - -ip.bind=127.0.0.1 + # по умолчанию master шлёт статистику на telemetry.seaweedfs.com + - -master.telemetry=false + # узел один, выборам ждать некого: перезапуск до healthy ~7 с, а не ~24 + - -master.electionTimeout=1s + # пауза перед остановкой тома нужна кластеру, а не одному узлу + - -volume.preStopSeconds=0 + - -filer + - -s3 + - -s3.ip.bind=0.0.0.0 + - -s3.port=${S3_PORT:-8333} + # REST Catalog и Lance по умолчанию открыты на 8181 и 9101 + - -s3.port.iceberg=0 + - -s3.port.lance=0 + # встроенный IAM API на порту S3 не нужен: bootstrap — weed shell + - -s3.iam=false + # шлюз держит не больше 64 МБ загрузок одновременно, лишние ждут + - -s3.concurrentUploadLimitMB=64 + environment: + # административная пара: учётная запись есть с первого старта, и + # анонимного окна нет. Только у сервера: ни API, ни bootstrap её не + # получают + AWS_ACCESS_KEY_ID: ${S3_ROOT_ACCESS_KEY:?S3_ROOT_ACCESS_KEY is empty, copy S3 lines from .env.example} + AWS_SECRET_ACCESS_KEY: ${S3_ROOT_SECRET_KEY:?S3_ROOT_SECRET_KEY is empty, copy S3 lines from .env.example} + # без ключа подписи gRPC шлюза принимает учётную запись + # администратора от любого контейнера сети + WEED_JWT_FILER_SIGNING_KEY: ${S3_JWT_SIGNING_KEY:?S3_JWT_SIGNING_KEY is empty, copy S3 lines from .env.example} + # сборщик мусора Go чаще у предела: вместе с лимитом загрузок 20 + # одновременных PUT по 10 MiB укладываются в 512 МБ + GOMEMLIMIT: 400MiB + # порт API S3 для healthcheck + S3_PORT: ${S3_PORT:-8333} + ports: + # только localhost и только API S3: к нему подключается приложение в + # console; консоль, UI и служебные серверы не публикуются + - "127.0.0.1:${S3_OUT_PORT:-8334}:${S3_PORT:-8333}" + volumes: + # volume образа (Config.Volumes): тома, filer и IAM + - s3_data:/data + networks: + default: + # любое значение S3_HOST указывает на этот сервис + aliases: + - ${S3_HOST:-s3} + healthcheck: + # master выбран, filer и шлюз S3 отвечают; всё на loopback. $$ — + # переменная контейнера + test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:9333/cluster/healthz && wget -q -O /dev/null http://127.0.0.1:8888/healthz && wget -q -O /dev/null \"http://127.0.0.1:$$S3_PORT/healthz\""] + interval: 5s + timeout: 3s + retries: 10 + start_period: 30s + start_interval: 1s + # плавная остановка ~15 с: срок ожидания подписок filer зашит в код. + # При 10 с остановка кончалась бы SIGKILL (код 137) + stop_grace_period: 20s + deploy: + resources: + limits: + # память — GOMEMLIMIT и лимит загрузок выше + cpus: "1.0" + memory: 512M + + # bootstrap S3 — один раз до реплик, как миграции (решение 4): приватный + # bucket, пользователь API с политикой «только объекты своего bucket», + # проверки приватности вне API. Повтор сводит состояние к .env и ничего + # не ломает. В сетевом пространстве s3: master и filer сервера на + # 127.0.0.1 доступны ему, а в сети их нет. make s3_check запускает его + # же в режиме check + s3-bootstrap: + image: *s3-image + network_mode: service:s3 + user: seaweed + entrypoint: ["sh", "/opt/s3/bootstrap.sh"] + command: ["apply"] + restart: "no" + environment: + S3_BUCKET: ${S3__BUCKET:-messenger} + S3_PORT: ${S3_PORT:-8333} + # ключ подписи: им weed shell подписывает вызовы IAM filer + WEED_JWT_FILER_SIGNING_KEY: ${S3_JWT_SIGNING_KEY:?S3_JWT_SIGNING_KEY is empty, copy S3 lines from .env.example} + S3_API_ACCESS_KEY: ${S3_API_ACCESS_KEY:?S3_API_ACCESS_KEY is empty, copy S3 lines from .env.example} + S3_API_SECRET_KEY: ${S3_API_SECRET_KEY:?S3_API_SECRET_KEY is empty, copy S3 lines from .env.example} + HOME: /tmp + volumes: + - type: bind + source: ./infra/s3/bootstrap.sh + target: /opt/s3/bootstrap.sh + read_only: true + bind: + create_host_path: false + # файл ключа для curl и политика — только в памяти + tmpfs: + - /tmp + depends_on: + s3: + condition: service_healthy + deploy: + resources: + limits: + # пик по пробе — 35 MiB, 0,76 с CPU + cpus: "0.5" + memory: 128M + # миграции — один раз до реплик, сами реплики их не запускают migrate: # образ собирает сервис api (make run_docker, make test_isolated) @@ -148,7 +281,7 @@ services: image: mtusi-messenger:lab4 restart: unless-stopped environment: - <<: [*db-env, *cache-env] + <<: [*db-env, *cache-env, *s3-env] APP__PORT: ${APP__PORT:-8080} volumes: - *config-toml @@ -160,6 +293,10 @@ services: condition: service_healthy migrate: condition: service_completed_successfully + # bucket и пользователь API есть до первого запроса; первую запись + # после старта S3 (~2,5 с) делает проверка bootstrap, а не клиент + s3-bootstrap: + condition: service_completed_successfully # healthcheck — из образа; SIGKILL не раньше, чем через 10 с stop_grace_period: 10s deploy: @@ -212,3 +349,4 @@ services: volumes: postgres_data: + s3_data: diff --git a/infra/s3/bootstrap.sh b/infra/s3/bootstrap.sh new file mode 100755 index 00000000..25571b0f --- /dev/null +++ b/infra/s3/bootstrap.sh @@ -0,0 +1,318 @@ +#!/bin/sh +# Bootstrap S3 стенда (SeaweedFS): приватный bucket, пользователь API с +# политикой «только объекты своего bucket», проверки приватности вне API. +# Design change s3-storage, решения 3, 4 и 8; правила — docker.md. +# +# Запускается сервисом compose s3-bootstrap на образе сервера в сетевом +# пространстве сервиса s3 (network_mode: service:s3): master и filer +# слушают 127.0.0.1 сервера, из сети стенда их нет. Административные +# вызовы — weed shell с ключом подписи (WEED_JWT_FILER_SIGNING_KEY), а не +# административной парой S3: её хранит только сервер. +# +# Режимы: +# apply (по умолчанию) — свести состояние к окружению (.env) и проверить +# права; каждый шаг безопасно повторять; +# check — ничего не менять в настройке, проверить права и приватность +# шире, чем apply: чужой bucket (временный, создаётся и удаляется +# здесь же), административные запросы ключа API, анонимные запросы. +# Проверочный объект остаётся для проверок с хоста и из сети +# (make s3_check) до режима cleanup; +# cleanup — удалить проверочный объект и временные bucket-ы check. +# +# Секреты: в weed shell — через stdin (printf — встроенная команда sh), в +# curl — файлом -K на tmpfs; в argv процессов и в выводе их нет. Ошибка +# шага — «FAILED: <шаг>» и код 1. +set -eu + +MODE=${1:-apply} +BUCKET=${S3_BUCKET:?S3_BUCKET is not set} +S3_PORT=${S3_PORT:?S3_PORT is not set} +: "${S3_API_ACCESS_KEY:?S3_API_ACCESS_KEY is empty, copy S3 lines from .env.example}" +: "${S3_API_SECRET_KEY:?S3_API_SECRET_KEY is empty, copy S3 lines from .env.example}" +: "${WEED_JWT_FILER_SIGNING_KEY:?S3_JWT_SIGNING_KEY is empty, copy S3 lines from .env.example}" + +MASTER=127.0.0.1:9333 +S3=http://127.0.0.1:${S3_PORT} +USER_NAME=api +POLICY=api-objects +# регион подписи; SeaweedFS берёт его из запроса +REGION=us-east-1 +TAG="s3-bootstrap" +# проверочный объект make s3_check: один и тот же ключ, повтор +# перезаписывает остаток прерванного прогона +CHECK_KEY=.s3-check/probe +CHECK_BUCKET_PREFIX="${BUCKET}-check-" +# сколько секунд ждать, пока изменения IAM дойдут до шлюза (подписка на +# filer) +IAM_WAIT_SECONDS=10 + +umask 077 +WORK=$(mktemp -d) +CRED="$WORK/api.cred" +BODY="$WORK/body" +TEMP_BUCKET="" + +cleanup_work() { + if [ -n "$TEMP_BUCKET" ]; then + ws "s3.bucket.delete -name ${TEMP_BUCKET}" >/dev/null 2>&1 || true + fi + rm -rf "$WORK" +} +trap cleanup_work EXIT + +say() { + echo "${TAG}: $*" +} + +fail() { + echo "${TAG}: FAILED: $*" >&2 + exit 1 +} + +# одна команда weed shell; вывод — в stdout, код — код shell +ws() { + printf '%s\n' "$1" | weed shell -master="$MASTER" 2>&1 +} + +# команда без секретов: при ошибке печатается вывод shell +ws_step() { + step=$1 + shift + if ! out=$(ws "$*"); then + printf '%s\n' "$out" | sed "s/^/${TAG}: /" >&2 + fail "$step" + fi +} + +# команда с секретом: вывод не печатается никогда +ws_secret_step() { + step=$1 + shift + ws "$*" >/dev/null || fail "$step" +} + +# ключ API для curl: файл на tmpfs, в argv только путь +printf 'user = "%s:%s"\n' "$S3_API_ACCESS_KEY" "$S3_API_SECRET_KEY" >"$CRED" + +# подписанный ключом API запрос: печатает код ответа, тело — в $BODY +signed() { + curl -s -o "$BODY" -w '%{http_code}' --max-time 5 -K "$CRED" \ + --aws-sigv4 "aws:amz:${REGION}:s3" "$@" || echo 000 +} + +# анонимный запрос: печатает код ответа +anon() { + curl -s -o "$BODY" -w '%{http_code}' --max-time 5 "$@" || echo 000 +} + +FAILED_CHECKS=0 + +# строка проверки: имя, ожидаемый и полученный код. Код выхода 1 — в +# конце, после всех строк +check() { + name=$1 + expected=$2 + got=$3 + if [ "$expected" = "$got" ]; then + verdict=ok + else + verdict=FAIL + FAILED_CHECKS=$((FAILED_CHECKS + 1)) + fi + printf '%s: check\t%s\t%s\t%s\t%s\n' "$TAG" "$name" "$expected" "$got" "$verdict" +} + +bucket_exists() { + ws "s3.bucket.list" | grep -qE "^[[:space:]]*$1([[:space:]]|\$)" +} + +# ждать, пока ключ API примет шлюз: изменения IAM доходят подпиской на +# filer. SignatureDoesNotMatch — ключ есть, секрет другой: печатается и +# возвращается 2 +wait_api_key() { + url=$1 + i=0 + while [ "$i" -lt "$IAM_WAIT_SECONDS" ]; do + code=$(signed -X PUT --data-binary "$TAG" "$url") + if [ "$code" = 200 ]; then + return 0 + fi + if [ "$code" = 403 ] && grep -q SignatureDoesNotMatch "$BODY"; then + return 2 + fi + i=$((i + 1)) + sleep 1 + done + return 1 +} + +# ---------------------------------------------------------------- apply + +apply_bucket() { + if bucket_exists "$BUCKET"; then + say "bucket ${BUCKET} exists" + else + ws_step "bucket create" "s3.bucket.create -name ${BUCKET}" + say "bucket ${BUCKET} created" + fi + # анонимный доступ — none; меняется, только если он открыт + if ! ws "s3.anonymous.get -bucket ${BUCKET}" | grep -q '^Access: none$'; then + ws_step "anonymous access none" \ + "s3.anonymous.set -bucket ${BUCKET} -access none" + say "anonymous access to ${BUCKET} closed" + fi +} + +apply_policy() { + cat >"$WORK/policy.json" </dev/null; then + say "user ${USER_NAME} exists" + else + ws_secret_step "user create" \ + "s3.user.create -name ${USER_NAME} -access_key ${S3_API_ACCESS_KEY} -secret_key ${S3_API_SECRET_KEY}" + say "user ${USER_NAME} created" + fi + ws_step "policy attach" \ + "s3.policy.attach -policy ${POLICY} -user ${USER_NAME}" + # ключи пользователя: чужие удаляются, нужного нет — создаётся + if ! keys_out=$(ws "s3.accesskey.list -user ${USER_NAME}"); then + fail "access key list" + fi + keys=$(printf '%s\n' "$keys_out" | awk 'NR > 1 && NF { print $1 }') + for key in $keys; do + if [ "$key" != "$S3_API_ACCESS_KEY" ]; then + ws_secret_step "stale key delete" \ + "s3.accesskey.delete -user ${USER_NAME} -access_key ${key}" + say "stale key of ${USER_NAME} removed" + fi + done + if ! printf '%s\n' "$keys" | grep -qxF "$S3_API_ACCESS_KEY"; then + ws_secret_step "key create" \ + "s3.accesskey.create -user ${USER_NAME} -access_key ${S3_API_ACCESS_KEY} -secret_key ${S3_API_SECRET_KEY}" + say "key of ${USER_NAME} created" + fi +} + +recreate_key() { + ws_secret_step "key delete" \ + "s3.accesskey.delete -user ${USER_NAME} -access_key ${S3_API_ACCESS_KEY}" + ws_secret_step "key create" \ + "s3.accesskey.create -user ${USER_NAME} -access_key ${S3_API_ACCESS_KEY} -secret_key ${S3_API_SECRET_KEY}" + say "key of ${USER_NAME} recreated (secret changed)" +} + +# проверки каждого запуска: ключ API пишет, читает и удаляет проверочный +# объект, список и создание bucket — 403; аноним не читает объект и не +# видит список +apply_checks() { + probe="${S3}/${BUCKET}/.s3-bootstrap/check-$$" + status=0 + wait_api_key "$probe" || status=$? + if [ "$status" = 2 ]; then + recreate_key + status=0 + wait_api_key "$probe" || status=$? + fi + [ "$status" = 0 ] || fail "api key put (code ${code})" + [ "$(signed "$probe")" = 200 ] || fail "api key get" + [ "$(anon "$probe")" = 403 ] || fail "anonymous get is not denied" + [ "$(anon "${S3}/${BUCKET}?list-type=2")" = 403 ] \ + || fail "anonymous list is not denied" + [ "$(signed "${S3}/${BUCKET}?list-type=2")" = 403 ] \ + || fail "api key list is not denied" + [ "$(signed -X PUT "${S3}/${CHECK_BUCKET_PREFIX}forbidden-$$")" = 403 ] \ + || fail "api key bucket create is not denied" + [ "$(signed -X DELETE "$probe")" = 204 ] || fail "api key delete" + say "checks passed (api key put/get/delete; api key list and bucket" \ + "create, anonymous get and list denied)" +} + +# ---------------------------------------------------------------- check + +run_checks() { + bucket_exists "$BUCKET" || fail "bucket ${BUCKET} does not exist, run make run_docker" + access=$(ws "s3.anonymous.get -bucket ${BUCKET}" \ + | sed -n 's/^Access: //p') + check "anonymous access setting" none "${access:-unknown}" + + obj="${S3}/${BUCKET}/${CHECK_KEY}" + missing="${S3}/${BUCKET}/.s3-check/missing-$$" + # ключ API: объекты своего bucket + check "api key put object" 200 \ + "$(signed -X PUT --data-binary "$TAG check" "$obj")" + check "api key get object" 200 "$(signed "$obj")" + check "api key head object" 200 "$(signed -I "$obj")" + check "api key get missing object" 404 "$(signed "$missing")" + # ключ API: всё остальное запрещено + check "api key list objects" 403 "$(signed "${S3}/${BUCKET}?list-type=2")" + check "api key create bucket" 403 \ + "$(signed -X PUT "${S3}/${CHECK_BUCKET_PREFIX}forbidden-$$")" + check "api key delete bucket" 403 "$(signed -X DELETE "${S3}/${BUCKET}")" + check "api key get bucket policy" 403 "$(signed "${S3}/${BUCKET}?policy")" + check "api key put bucket policy" 403 \ + "$(signed -X PUT --data-binary '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":"*","Action":"s3:GetObject","Resource":"arn:aws:s3:::'"${BUCKET}"'/*"}]}' "${S3}/${BUCKET}?policy")" + check "api key get bucket acl" 403 "$(signed "${S3}/${BUCKET}?acl")" + check "api key put bucket acl public-read" 403 \ + "$(signed -X PUT -H 'x-amz-acl: public-read' "${S3}/${BUCKET}?acl")" + check "api key put object acl public-read" 403 \ + "$(signed -X PUT -H 'x-amz-acl: public-read' "${obj}?acl")" + # чужой bucket: временный, создаёт и удаляет weed shell + TEMP_BUCKET="${CHECK_BUCKET_PREFIX}$(od -An -N4 -tx4 /dev/urandom | tr -d ' ')" + ws_step "temporary bucket create" "s3.bucket.create -name ${TEMP_BUCKET}" + other="${S3}/${TEMP_BUCKET}" + check "api key put object to other bucket" 403 \ + "$(signed -X PUT --data-binary "$TAG" "${other}/probe")" + check "api key get object from other bucket" 403 "$(signed "${other}/probe")" + check "api key list other bucket" 403 "$(signed "${other}?list-type=2")" + check "api key delete other bucket" 403 "$(signed -X DELETE "$other")" + ws_step "temporary bucket delete" "s3.bucket.delete -name ${TEMP_BUCKET}" + TEMP_BUCKET="" + # аноним изнутри сервера; с хоста и из сети стенда — make s3_check + check "anonymous get object" 403 "$(anon "$obj")" + check "anonymous head object" 403 "$(anon -I "$obj")" + check "anonymous get missing object" 403 "$(anon "$missing")" + check "anonymous list objects" 403 "$(anon "${S3}/${BUCKET}?list-type=2")" + check "anonymous list buckets" 403 "$(anon "${S3}/")" + check "anonymous put object" 403 \ + "$(anon -X PUT --data-binary "$TAG" "${S3}/${BUCKET}/.s3-check/anonymous")" + check "anonymous create bucket" 403 \ + "$(anon -X PUT "${S3}/${CHECK_BUCKET_PREFIX}anonymous-$$")" + if [ "$FAILED_CHECKS" -gt 0 ]; then + fail "${FAILED_CHECKS} check(s) failed" + fi + say "checks passed; probe object ${BUCKET}/${CHECK_KEY} kept for host and network checks" +} + +run_cleanup() { + code=$(signed -X DELETE "${S3}/${BUCKET}/${CHECK_KEY}") + case "$code" in + 204 | 404) say "probe object ${BUCKET}/${CHECK_KEY} removed" ;; + *) fail "probe object delete (code ${code})" ;; + esac + # временные bucket-ы прерванных проверок + for name in $(ws "s3.bucket.list" | awk '{ print $1 }' \ + | grep -E "^${CHECK_BUCKET_PREFIX}[0-9a-f]+\$" || true); do + ws_step "temporary bucket delete" "s3.bucket.delete -name ${name}" + say "temporary bucket ${name} removed" + done +} + +case "$MODE" in + apply) + apply_bucket + apply_policy + apply_user + apply_checks + ;; + check) run_checks ;; + cleanup) run_cleanup ;; + *) fail "unknown mode ${MODE}: apply, check or cleanup" ;; +esac diff --git a/openspec/changes/s3-storage/design.md b/openspec/changes/s3-storage/design.md index 5452673a..46a3e495 100644 --- a/openspec/changes/s3-storage/design.md +++ b/openspec/changes/s3-storage/design.md @@ -502,3 +502,64 @@ botocore, тот же код подписи и моделей, что у AWS CLI Volume `mtusi-lab4_s3_data` после отката compose не знает, и `make wipe_data` его уже не удалит — только явный `docker volume rm`. Данные PostgreSQL change не трогает. + +## Уточнения apply + +Решения, принятые в `/opsx:apply` (2026-10-20) по ходу работы; копия — +`PLAN.md`, «Вопросы и решения по ходу changes» → `s3-storage`. + +1. **`--wait` не ждёт завершения bootstrap** (уточнение решения 9). + Compose v5.5.1 считает одноразовый сервис без healthcheck готовым, + как только тот запущен: `up -d --wait s3 s3-bootstrap` вернулся через + 5,6 с, а bootstrap закончил позже. Поэтому `make start_s3` — это `up + -d --wait s3`, затем `up --no-deps --exit-code-from s3-bootstrap + s3-bootstrap` (код выхода bootstrap — код цели), как миграции в + `rolling-update.sh`. Так же — `run_failures.py`. Реплики штатного + стенда это не задевает: `depends_on: service_completed_successfully` + ждёт завершения. +2. **Режимы bootstrap: `apply`, `check`, `cleanup`** (уточнение решений + 4 и 8). Проверки с хоста и из сети идут между записью проверочного + объекта и его удалением, поэтому удаление — отдельный режим + `cleanup`, а не последний шаг `check`. Объект — `.s3-check/probe` + (повтор перезаписывает остаток прерванного прогона); временный bucket + `-check-` создаёт и удаляет сам `check` (и `trap` при + сбое), `cleanup` удаляет и забытые. Строки проверок — `s3-bootstrap: + checkимяожидаемополученоok|FAIL`, их собирает + `driver.py s3-check`. Вывод `weed shell` печатается только у шагов + без секретов. `HOME=/tmp` (tmpfs) у `s3-bootstrap`: ничего не пишется + в слой контейнера. +3. **Секрет сменился — ключ пересоздаётся по `SignatureDoesNotMatch`**, + а не по любому 403 (решение 4, шаг 6): ожидание изменений IAM до + 10 с даёт `InvalidAccessKeyId`, его ждут, а не пересоздают ключ. +4. **Клиент** (решение 7): `open(key)` отдаёт `StoredObject` с `size`, + `content_type`, `iter_chunks()` и `read()`; срок `[s3] + timeout_seconds` — на вызов и на каждый блок чтения тела (отдача + 10 MiB медленному клиенту дольше срока, блок — нет). Типы + `StoredObjectInfo` и `StoredObject` — в `src/infra/s3/client.py`. + Переводятся только ошибки клиента и сети (`ClientError`, + `ConnectionError` и `HTTPClientError` botocore, `IncompleteReadError`, + `aiohttp.ClientError`, `OSError`); прочие не перехватываются (500). + Ключи передаются в botocore всегда, даже пустые: иначе он искал бы + учётные данные в окружении и `~/.aws` хоста. +5. **Ожидаемо красные шире списка tasks.md.** Контракт лабы 4 сделал + `attachment_ids` обязательным полем `Message`, а код лабы 3 его не + отдаёт (в `src/` его нет с `5d5d8f9`). До change `attachments` + падают все тесты, которые проверяют схему сообщения: в `make + student_test` (и `make test_isolated`) — 30 упавших и 2 ошибки + фикстуры с одной причиной «'attachment_ids' is a required property», + в `make failure_checks` — 5 (`test_database_stopped_and_back`, + `test_valkey_stopped`, `test_message_failure_keeps_key_free`, + `test_database_outage_keeps_key_free`, `test_key_free_after_ttl`). + От этого change это не зависит; правка — поле в `attachments`. Код 0 + `make failure_checks` до тех пор недостижим, новая проверка + `test_readiness_without_object_storage` зелёная. +6. **Дельта `health` синхронизирована в основной спек в apply**, как в + `scaling-bench` («`/opsx:sync` только её»): сверка покрытия читает + только `openspec/specs/`, и маркер нового сценария «Хранилище + объектов недоступно» без этого указывал бы на неизвестный сценарий. + Остальные дельты — при archive. +7. **Профиль `rollout` ссылается на commit лабы 3** (`rollout_from + c50b721`, его нет в истории лабы 4) — дефект переноса, записан в + `KNOWN_ISSUES.md`. `make bench_rollout_quick` падает за 6 с; + самопроверка профиля — `bench/run.py --profile rollout_quick --from + 5d5d8f9` (код 0). diff --git a/openspec/changes/s3-storage/tasks.md b/openspec/changes/s3-storage/tasks.md index 42a4841b..7de5f9bf 100644 --- a/openspec/changes/s3-storage/tasks.md +++ b/openspec/changes/s3-storage/tasks.md @@ -13,18 +13,23 @@ - `make test-persistence` и `make test-failover` — загрузка вложения с `LAB=4`; - `test_exclusion_evidence_exists` в `make student_test`; -- поэтому и итог `make test_isolated`. +- поэтому и итог `make test_isolated`; +- найдено в apply (design, «Уточнения apply», п. 5): тесты, которые + проверяют схему `Message` / `MessagePage` контракта лабы 4 + (`attachment_ids` обязателен), — 30 упавших и 2 ошибки в `make + student_test`, 5 упавших в `make failure_checks`. Поэтому `make + failure_checks` до `attachments` тоже ненулевой. Другие падения — дефект, их разбирают по AGENTS.md. ## 1. Зависимость и настройки -- [ ] 1.1 Добавить зависимость: `uv add "aiobotocore>=3.9.2,<4"` в +- [x] 1.1 Добавить зависимость: `uv add "aiobotocore>=3.9.2,<4"` в основную группу, с комментарием «клиент S3 (SeaweedFS), решение 6». Проверка: `uv lock --check`; `uv run python -c "import aiobotocore, botocore; print(aiobotocore.__version__, botocore.__version__)"` — 3.9.x и 1.43.x. -- [ ] 1.2 Секция `S3` в `src/config/settings.py` по решению 5: +- [x] 1.2 Секция `S3` в `src/config/settings.py` по решению 5: - поля, `endpoint_url`, валидатор имени bucket по `S3_BUCKET_NAME_PATTERN` в `src/utils/constants.py`; - сроки `gt=0`, пул `ge=1`; @@ -37,7 +42,7 @@ без `.env` даёт значения по умолчанию; - `S3__BUCKET=Bad_Bucket` — запуск падает, в выводе есть `bucket`; - `S3__TIMEOUT_SECONDS=0` — запуск падает. -- [ ] 1.3 Блок S3 в `.env.example` по решениям 3 и 5: `S3_HOST`, +- [x] 1.3 Блок S3 в `.env.example` по решениям 3 и 5: `S3_HOST`, `S3_PORT`, `S3_OUT_PORT`, `S3__BUCKET`, пустые `S3_ROOT_*`, `S3_API_*` и `S3_JWT_SIGNING_KEY`, мосты `S3__HOST`, `S3__PORT`, `S3__ACCESS_KEY_ID`, `S3__SECRET_ACCESS_KEY`. Шапка шаблона — без @@ -55,7 +60,7 @@ ## 2. Стенд -- [ ] 2.1 `infra/s3/bootstrap.sh` (режим по умолчанию) и сервисы `s3`, +- [x] 2.1 `infra/s3/bootstrap.sh` (режим по умолчанию) и сервисы `s3`, `s3-bootstrap` в `docker-compose.yml` по решениям 1–4: - пин тега и digest; - аргументы `weed server`, `GOMEMLIMIT`, healthcheck, @@ -81,7 +86,7 @@ 8333 и 18333; - `docker compose config` — секреты только у сервисов из таблицы; - `docker inspect` — лимиты у `s3` и `s3-bootstrap`. -- [ ] 2.2 Makefile и hook по решению 9: +- [x] 2.2 Makefile и hook по решению 9: - `start_s3` (`up -d --wait s3 s3-bootstrap`) и `stop_s3`; - `run_dev: upgrade start_cache start_s3`; - `test_isolated: … start_s3`; @@ -94,7 +99,7 @@ `StartedAt`, тот же ID; hook укладывается в 90 с (время записать); `s3-bootstrap` после рестарта — «exists»; - `docker compose stop s3` — код выхода контейнера 0, не 137. -- [ ] 2.3 `make s3_check` по решению 8: режим `check` в +- [x] 2.3 `make s3_check` по решению 8: режим `check` в `infra/s3/bootstrap.sh` (проверочный объект, временный чужой bucket, административные запросы ключом API) и команда `driver.py s3-check` скилла (stdlib): анонимные запросы с хоста и из сети стенда, порты из @@ -109,7 +114,7 @@ ## 3. Клиент хранилища -- [ ] 3.1 Клиент по решению 7: +- [x] 3.1 Клиент по решению 7: - `src/core/exceptions/storage.py` (`ObjectStorageUnavailable`, `StoredObjectMissing`) с реэкспортом; - `src/infra/s3/client.py` и `instance.py` (`namespace` — имя базы), @@ -135,7 +140,7 @@ ## 4. Стенды проверок и нагрузки -- [ ] 4.1 `make test_isolated` по решению 9: `run_isolated.py` удаляет +- [x] 4.1 `make test_isolated` по решению 9: `run_isolated.py` удаляет префикс `test_/` в начале и в уборке (`docker compose exec -T s3` + `weed shell` `fs.rm -r`). Префикс собирается только из проверенного имени временной базы, иначе отказ. При `KEEP_TEST_DB=1` префикс @@ -146,7 +151,7 @@ уборка префикса, `test_/probe` нет, `/probe` на месте; - с `KEEP_TEST_DB=1` префикс остался и напечатан; - пробные объекты затем удалить. -- [ ] 4.2 `make failure_checks` по решению 9: +- [x] 4.2 `make failure_checks` по решению 9: - `run_failures.py` поднимает `s3` и `s3-bootstrap`; - `failures.compose.yml` — у `s3` порты сброшены, `stop_grace_period: 2s`; @@ -161,7 +166,7 @@ `-failures` нет, у рабочего стенда прежний `StartedAt`; - `make student_test` — сверка покрытия считает сценарий покрытым проверкой отказа, красный только `test_exclusion_evidence_exists`. -- [ ] 4.3 `bench/` по решению 9: +- [x] 4.3 `bench/` по решению 9: - `compose_env` генерирует пять секретов S3; - фильтр `app_env` паспорта убирает имена с `PASSWORD`, `SECRET`, `ACCESS_KEY`; @@ -179,7 +184,7 @@ ## 5. Документы и проверка кода -- [ ] 5.1 Правила, AGENTS.md и скилл: +- [x] 5.1 Правила, AGENTS.md и скилл: - `infra.md` — клиент S3, ошибки, `instance.py`; - `docker.md` — сервисы `s3`, `s3-bootstrap`, healthcheck, срок остановки, порядок `restart.sh`; @@ -201,7 +206,7 @@ Проверка: `grep -rn "Строк S3\|пароли MinIO" AGENTS.md .claude .env.example` пуст; `openspec validate s3-storage --strict` — без ошибок. -- [ ] 5.2 Финальная проверка кода: +- [x] 5.2 Финальная проверка кода: - `make lint`, `make check`, `openspec validate s3-storage --strict`; - на стенде `make run_docker`: `make s3_check` — код 0, `make diff --git a/openspec/specs/health/spec.md b/openspec/specs/health/spec.md index a49b2725..2847f236 100644 --- a/openspec/specs/health/spec.md +++ b/openspec/specs/health/spec.md @@ -23,12 +23,19 @@ MUST NOT зависеть от состояния хранилища. `GET /health/ready` SHALL отвечать 200 с телом `{"status": "ok"}`, когда сервис может безопасно обслуживать обязательные запросы, и 503 с -`code` `unavailable` в формате ошибки, когда не может. На лабе 2 -критичная зависимость — PostgreSQL: проверка SHALL выполнять запрос к -нему с коротким таймаутом при каждом обращении. Valkey — кэш, без него -обязательные запросы обслуживаются из PostgreSQL, поэтому его -недоступность MUST NOT делать сервис неготовым. Проверка MUST NOT -требовать идентификации. +`code` `unavailable` в формате ошибки, когда не может. Критичная +зависимость — PostgreSQL: проверка SHALL выполнять запрос к нему с +коротким таймаутом при каждом обращении. + +Две зависимости не критичны, и их недоступность MUST NOT делать сервис +неготовым: +- Valkey — кэш: без него обязательные запросы обслуживаются из + PostgreSQL; +- S3 — хранилище байтов вложений: путь без вложений его не использует. + +Проверка MUST NOT обращаться к S3 и MUST NOT требовать идентификации. +Перечень критичных и некритичных зависимостей с причинами SHALL быть в +`REPORT.md`. #### Scenario: Сервис запущен @@ -47,6 +54,12 @@ MUST NOT зависеть от состояния хранилища. - **WHEN** Valkey остановлен, а PostgreSQL доступен - **THEN** `GET /health/ready` отвечает 200 +#### Scenario: Хранилище объектов недоступно + +- **WHEN** сервер S3 остановлен, а PostgreSQL доступен +- **THEN** `GET /health/ready` и `GET /health/live` отвечают 200 быстрее + секунды: проверка к S3 не обращается + ### Requirement: Health вне версии API и без идентификации Эндпоинты health SHALL находиться вне префикса `/api/v1`, MUST NOT diff --git a/pyproject.toml b/pyproject.toml index bb256217..fab235ef 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -20,6 +20,9 @@ dependencies = [ "argon2-cffi>=25.1.0,<26", # клиент Valkey: протокол тот же, redis.asyncio зрелее valkey-py "redis>=8.1,<9", + # клиент S3 (SeaweedFS), решение 6 design change s3-storage; + # botocore закреплён узко, обновлять вместе через uv lock + "aiobotocore>=3.9.2,<4", ] [project.optional-dependencies] diff --git a/scripts/restart.sh b/scripts/restart.sh index 28fe0187..3adca548 100755 --- a/scripts/restart.sh +++ b/scripts/restart.sh @@ -3,18 +3,20 @@ set -eu # Restart hook для make test-persistence (tests/README.md) по образцу # scripts/restart.example.sh; правила — .claude/rules/docker.md. # Перезапускает балансировщик, все реплики API и все хранилища стенда -# (Postgres и Valkey) с сохранением volume, схемы и данных: без down -v, -# FLUSHALL и повторного наполнения. Кэш Valkey после рестарта пуст: -# persistence у него выключен, данные — в Postgres. +# (Postgres, Valkey и S3) с сохранением volumes, схемы и данных: без +# down -v, FLUSHALL и повторного наполнения. Кэш Valkey после рестарта +# пуст: persistence у него выключен, данные — в Postgres. Bucket, учётные +# записи и объекты S3 лежат в его volume. # LB гасится первым и поднимается последним. start поднимает те же # контейнеры всех реплик: число реплик не меняется (реплика, остановленная -# stop-one.sh, тоже запускается). start api запускает и его зависимость -# migrate: повторный прогон миграций ничего не меняет. -# Готовность через LB ждёт сам тест. Секреты не печатает. +# stop-one.sh, тоже запускается). start api запускает и его зависимости +# migrate и s3-bootstrap: повторные миграции и bootstrap ничего не меняют. +# S3 останавливается плавно ~15 с (stop_grace_period 20 с): hook занимает +# ~30–35 с. Готовность через LB ждёт сам тест. Секреты не печатает. cd "$(dirname "$0")/.." docker compose stop haproxy api -docker compose restart postgres valkey +docker compose restart postgres valkey s3 # те же контейнеры: --wait только дожидается их healthcheck -docker compose up -d --wait postgres valkey +docker compose up -d --wait postgres valkey s3 docker compose start api haproxy diff --git a/src/config/settings.py b/src/config/settings.py index 3b2087e9..212314aa 100644 --- a/src/config/settings.py +++ b/src/config/settings.py @@ -20,7 +20,7 @@ from pydantic_settings import ( from sqlalchemy.engine import URL from src.schemas.enums import RunModeEnum -from src.utils.constants import INSTANCE_ID_PATTERN +from src.utils.constants import INSTANCE_ID_PATTERN, S3_BUCKET_NAME_PATTERN BASE_DIR = Path(__file__).resolve().parent.parent.parent ENV_PATH = BASE_DIR.joinpath(".env") @@ -172,6 +172,47 @@ class Cache(BaseModel): max_connections: int = Field(default=10, ge=1) +class S3(BaseModel): + """Подключение к S3 (SeaweedFS): байты вложений. + + Адрес, порт, bucket и ключи пользователя API приходят из `.env`: в + console — мостами к `S3_OUT_PORT` и `S3_API_*`, в docker — из + `environment` compose. Регион, сроки и пул — из `config.toml`. + Соответствие имён skeleton `S3_*` — в `REPORT.md`. + """ + + host: str = "127.0.0.1" + port: int = Field(default=8333, ge=1, le=65535) + # тот же bucket создаёт bootstrap стенда (S3__BUCKET в .env) + bucket: str = "messenger" + # ключи пользователя API в S3, не административные; пусто — warning + # при старте + access_key_id: SecretStr = SecretStr("") + secret_access_key: SecretStr = SecretStr("") + # подпись SigV4 требует регион; SeaweedFS берёт его из запроса + region: str = "us-east-1" + # секунды на установку соединения + connect_timeout_seconds: float = Field(default=1, gt=0) + # секунды на весь вызов (соединение, запрос, ответ); меньше timeout + # server HAProxy (10 с) + timeout_seconds: float = Field(default=5, gt=0) + # соединений в пуле aiohttp на процесс + max_connections: int = Field(default=10, ge=1) + + @field_validator("bucket") + @classmethod + def bucket_name(cls, value: str) -> str: + """Имя bucket по правилам S3, иначе сервис не стартует.""" + if not re.fullmatch(S3_BUCKET_NAME_PATTERN, value): + raise ValueError(f"must match {S3_BUCKET_NAME_PATTERN}") + return value + + @property + def endpoint_url(self) -> str: + """Адрес API S3; клиент сам URL не собирает.""" + return f"http://{self.host}:{self.port}" + + class Idempotency(BaseModel): """Ключи идемпотентности отправки сообщения; срок — из `config.toml`. @@ -198,6 +239,7 @@ class Settings(BaseSettings): database: Database = Database() auth: Auth = Auth() cache: Cache = Cache() + s3: S3 = S3() idempotency: Idempotency = Idempotency() @classmethod diff --git a/src/core/exceptions/__init__.py b/src/core/exceptions/__init__.py index 3ef5df1f..78f6176c 100644 --- a/src/core/exceptions/__init__.py +++ b/src/core/exceptions/__init__.py @@ -4,6 +4,7 @@ from .idempotency import IdempotencyConflict from .pagination import InvalidCursor from .service import ServiceUnavailable from .session import InvalidCredentials, Unauthenticated +from .storage import ObjectStorageUnavailable, StoredObjectMissing from .user import UsernameTaken __all__ = [ @@ -13,7 +14,9 @@ __all__ = [ "InvalidChatMembers", "InvalidCredentials", "InvalidCursor", + "ObjectStorageUnavailable", "ServiceUnavailable", + "StoredObjectMissing", "Unauthenticated", "UsernameTaken", ] diff --git a/src/core/exceptions/storage.py b/src/core/exceptions/storage.py new file mode 100644 index 00000000..f0919923 --- /dev/null +++ b/src/core/exceptions/storage.py @@ -0,0 +1,20 @@ +from .base import DomainError +from .service import ServiceUnavailable + + +class ObjectStorageUnavailable(ServiceUnavailable): + """S3 недоступен, не ответил за срок или отклонил учётные данные API. + + Наследник `ServiceUnavailable`: 503 `unavailable` по таблице + `src/api/errors.py`. Причину видно в журнале клиента, а не в ответе. + """ + + +class StoredObjectMissing(DomainError): + """Объекта с таким ключом в bucket нет. + + Отличается от недоступности S3. HTTP-ответ на него назначает change + `attachments`. + """ + + default_message = "Stored object not found" diff --git a/src/infra/logger.py b/src/infra/logger.py index 27f80f97..60566bd4 100644 --- a/src/infra/logger.py +++ b/src/infra/logger.py @@ -186,6 +186,12 @@ def configure_logger() -> None: "handlers": ["json"], "propagate": False, }, + # клиент S3: на DEBUG botocore пишет заголовки запроса с + # подписью (Authorization), поэтому явно WARNING, даже если + # кто-то опустит уровень root + "botocore": {"level": "WARNING"}, + "aiobotocore": {"level": "WARNING"}, + "aiohttp": {"level": "WARNING"}, }, }, ) diff --git a/src/infra/s3/__init__.py b/src/infra/s3/__init__.py new file mode 100644 index 00000000..953e925c --- /dev/null +++ b/src/infra/s3/__init__.py @@ -0,0 +1,13 @@ +from src.infra.s3.client import ( + ObjectStorage, + StoredObject, + StoredObjectInfo, + create_object_storage, +) + +__all__ = [ + "ObjectStorage", + "StoredObject", + "StoredObjectInfo", + "create_object_storage", +] diff --git a/src/infra/s3/client.py b/src/infra/s3/client.py new file mode 100644 index 00000000..9be3d08c --- /dev/null +++ b/src/infra/s3/client.py @@ -0,0 +1,359 @@ +"""Клиент S3 (SeaweedFS) на aiobotocore: срок на вызов, без повторов. + +Design change `s3-storage`, решения 6–7. Каждый вызов ограничен +`[s3] timeout_seconds` (`asyncio.timeout`), повторов botocore нет +(`total_max_attempts=1`): рестарт S3 повтора не требует, таймаут, как у +Valkey, не повторяется, а загрузку повторяет клиент контракта. Ошибки +переводятся в доменные исключения: + +- отказ соединения, обрыв, таймаут, 5xx и отказ в учётных данных — + `ObjectStorageUnavailable` (503 `unavailable`); +- отсутствующий ключ — `StoredObjectMissing` (`head` — `None`, `delete` — + не ошибка); +- прочие ошибки S3 не переводятся: 500, это дефект. + +В журнал — адрес, bucket, ключ объекта, размер, длительность и класс +ошибки; ключей доступа, секрета и подписи там нет. Логгеры botocore, +aiobotocore и aiohttp стоят на WARNING (`src/infra/logger.py`): на DEBUG +botocore пишет заголовки с подписью. +""" + +import asyncio +import time +from collections.abc import AsyncIterator +from contextlib import AsyncExitStack, asynccontextmanager +from dataclasses import dataclass +from typing import Any + +import aiohttp +from aiobotocore.config import AioConfig +from aiobotocore.session import get_session +from botocore.exceptions import ( + ClientError, + HTTPClientError, + IncompleteReadError, +) +from botocore.exceptions import ConnectionError as BotoConnectionError + +from src.config.settings import S3 as S3Settings +from src.core.exceptions import ObjectStorageUnavailable, StoredObjectMissing +from src.infra.logger import AbstractLogger, get_logger +from src.utils.constants import S3_KEEPALIVE_TIMEOUT_SECONDS + +logger: AbstractLogger = get_logger().bind(module="object_storage") + +# коды отказа в учётных данных: секрет или ключ API не совпали с сервером +CREDENTIAL_ERROR_CODES = frozenset( + {"AccessDenied", "InvalidAccessKeyId", "SignatureDoesNotMatch"}, +) +# отсутствующий ключ: у GET — NoSuchKey, у HEAD тела нет, только статус +MISSING_ERROR_CODES = frozenset({"NoSuchKey", "404", "NotFound"}) +# недоступность: отказ соединения и его таймаут (ConnectionError botocore: +# EndpointConnectionError, ConnectTimeoutError), обрыв и таймаут чтения +# (HTTPClientError: ConnectionClosedError, ReadTimeoutError, +# ResponseStreamingError), неполный ответ, ошибки aiohttp и сокета, +# asyncio.timeout (TimeoutError — подкласс OSError). Ошибки конфигурации +# botocore (ParamValidationError и др.) сюда не входят: это дефект, 500 +UNAVAILABLE_ERRORS: tuple[type[Exception], ...] = ( + BotoConnectionError, + HTTPClientError, + IncompleteReadError, + aiohttp.ClientError, + OSError, +) +TRANSLATED_ERRORS: tuple[type[Exception], ...] = ( + ClientError, + *UNAVAILABLE_ERRORS, +) +# размер блока чтения объекта по умолчанию +DEFAULT_CHUNK_BYTES = 64 * 1024 + + +@dataclass(frozen=True, slots=True) +class StoredObjectInfo: + """Метаданные объекта в bucket.""" + + key: str + size: int + content_type: str | None + + +class StoredObject: + """Открытый на чтение объект: метаданные и чтение блоками. + + Каждое чтение блока ограничено тем же сроком, что и вызов: отдача + 10 MiB медленному клиенту длится дольше срока, а один блок — нет. + """ + + def __init__( + self, + info: StoredObjectInfo, + body: Any, + storage: "ObjectStorage", + ) -> None: + self.info = info + self._body = body + self._storage = storage + + @property + def size(self) -> int: + return self.info.size + + @property + def content_type(self) -> str | None: + return self.info.content_type + + async def iter_chunks( + self, + chunk_bytes: int = DEFAULT_CHUNK_BYTES, + ) -> AsyncIterator[bytes]: + """Байты объекта блоками до `chunk_bytes`.""" + while True: + chunk = await self._storage._read_chunk( + self._body, + key=self.info.key, + chunk_bytes=chunk_bytes, + ) + if not chunk: + return + yield chunk + + async def read(self) -> bytes: + """Весь объект; для больших — `iter_chunks`.""" + return b"".join([chunk async for chunk in self.iter_chunks()]) + + +class ObjectStorage: + """Объекты одного bucket ключом пользователя API. + + `namespace` — имя базы PostgreSQL процесса: ключ объекта строит repo + как `f"{namespace}{S3_KEY_SEPARATOR}…"`, и объекты прогона на + временной базе (`make test_isolated`) отделены от рабочих, как ключи + кэша. Клиент aiobotocore создаёт `start()` (модели botocore грузятся + при старте, сети нет) или первый вызов; соединения aiohttp + открываются при первом запросе. + """ + + def __init__(self, s3: S3Settings, *, namespace: str) -> None: + self.namespace = namespace + self.bucket = s3.bucket + self._settings = s3 + self._endpoint = f"{s3.host}:{s3.port}" + self._timeout_seconds = s3.timeout_seconds + self._client: Any = None + self._exit_stack: AsyncExitStack | None = None + self._lock = asyncio.Lock() + + async def start(self) -> None: + """Создать клиент заранее, при старте процесса.""" + await self._get_client() + + async def aclose(self) -> None: + """Закрыть клиент и его пул соединений.""" + async with self._lock: + if self._exit_stack is not None: + await self._exit_stack.aclose() + self._exit_stack = None + self._client = None + + async def put( + self, + key: str, + data: bytes, + *, + content_type: str, + ) -> None: + """Записать объект целиком.""" + await self._call( + "put_object", + key, + size=len(data), + Body=data, + ContentType=content_type, + ) + + async def head(self, key: str) -> StoredObjectInfo | None: + """Метаданные объекта; `None` — объекта нет.""" + try: + response = await self._call("head_object", key) + except StoredObjectMissing: + return None + return StoredObjectInfo( + key=key, + size=response["ContentLength"], + content_type=response.get("ContentType"), + ) + + @asynccontextmanager + async def open(self, key: str) -> AsyncIterator[StoredObject]: + """Объект на чтение блоками; нет объекта — `StoredObjectMissing`. + + Соединение возвращается в пул (или закрывается, если тело + прочитано не до конца) при выходе из контекста. + """ + response = await self._call("get_object", key) + body = response["Body"] + info = StoredObjectInfo( + key=key, + size=response["ContentLength"], + content_type=response.get("ContentType"), + ) + try: + yield StoredObject(info, body, self) + finally: + body.close() + + async def delete(self, key: str) -> None: + """Удалить объект; отсутствие объекта — не ошибка.""" + await self._call("delete_object", key) + + async def _get_client(self) -> Any: + if self._client is not None: + return self._client + async with self._lock: + if self._client is None: + stack = AsyncExitStack() + self._client = await stack.enter_async_context( + self._create_client(), + ) + self._exit_stack = stack + return self._client + + def _create_client(self) -> Any: + s3 = self._settings + config = AioConfig( + # виртуальные хосты bucket.s3 Docker DNS не разрешает + s3={"addressing_style": "path"}, + connect_timeout=s3.connect_timeout_seconds, + read_timeout=s3.timeout_seconds, + # повторов нет: отказ — сразу 503, срок — один на вызов + retries={"total_max_attempts": 1}, + max_pool_connections=s3.max_connections, + # простаивающее соединение закрывает клиент раньше шлюза + connector_args={"keepalive_timeout": S3_KEEPALIVE_TIMEOUT_SECONDS}, + ) + # ключи передаются всегда, даже пустые: иначе botocore искал бы + # учётные данные в окружении и ~/.aws хоста + return get_session().create_client( + "s3", + endpoint_url=s3.endpoint_url, + region_name=s3.region, + aws_access_key_id=s3.access_key_id.get_secret_value(), + aws_secret_access_key=s3.secret_access_key.get_secret_value(), + config=config, + ) + + async def _call( + self, + operation: str, + key: str, + *, + size: int | None = None, + **params: Any, + ) -> dict[str, Any]: + client = await self._get_client() + started = time.monotonic() + try: + async with asyncio.timeout(self._timeout_seconds): + response = await getattr(client, operation)( + Bucket=self.bucket, + Key=key, + **params, + ) + except TRANSLATED_ERRORS as e: + failure = self._failure( + e, + operation=operation, + key=key, + started=started, + ) + if failure is None: + raise + raise failure from e + logger.debug( + "Called object storage", + operation=operation, + bucket=self.bucket, + key=key, + size=size, + duration_ms=self._duration_ms(started), + ) + return response + + async def _read_chunk( + self, + body: Any, + *, + key: str, + chunk_bytes: int, + ) -> bytes: + started = time.monotonic() + try: + async with asyncio.timeout(self._timeout_seconds): + return await body.read(chunk_bytes) + except TRANSLATED_ERRORS as e: + failure = self._failure( + e, + operation="read_body", + key=key, + started=started, + ) + if failure is None: + raise + raise failure from e + + def _failure( + self, + error: Exception, + *, + operation: str, + key: str, + started: float, + ) -> Exception | None: + """Доменное исключение вместо ошибки клиента; `None` — ошибку не + переводить (дефект, 500).""" + fields = { + "operation": operation, + "endpoint": self._endpoint, + "bucket": self.bucket, + "key": key, + "duration_ms": self._duration_ms(started), + "error_type": type(error).__name__, + } + if isinstance(error, ClientError): + code = str(error.response.get("Error", {}).get("Code", "")) + status = error.response.get("ResponseMetadata", {}).get( + "HTTPStatusCode", + 0, + ) + if code in MISSING_ERROR_CODES or status == 404: + return StoredObjectMissing() + if code in CREDENTIAL_ERROR_CODES: + logger.error( + "Object storage rejected credentials", + error_code=code, + **fields, + ) + return ObjectStorageUnavailable() + if status >= 500: + logger.warning( + "Object storage is unavailable", + error_code=code, + status=status, + **fields, + ) + return ObjectStorageUnavailable() + return None + if isinstance(error, UNAVAILABLE_ERRORS): + logger.warning("Object storage is unavailable", **fields) + return ObjectStorageUnavailable() + return None + + @staticmethod + def _duration_ms(started: float) -> int: + return round((time.monotonic() - started) * 1000) + + +def create_object_storage(s3: S3Settings, *, namespace: str) -> ObjectStorage: + """Хранилище объектов по `[s3]`; клиент и соединения — лениво.""" + return ObjectStorage(s3, namespace=namespace) diff --git a/src/infra/s3/instance.py b/src/infra/s3/instance.py new file mode 100644 index 00000000..88bce387 --- /dev/null +++ b/src/infra/s3/instance.py @@ -0,0 +1,17 @@ +"""Хранилище объектов процесса API (S3). + +Создаётся при импорте по `settings.s3`; клиент aiobotocore создаёт +lifespan (`start()`), соединения — первый вызов. Импортируют модуль +только `src/main.py` (старт и закрытие в lifespan) и +`src/api/dependencies.py`, как `src/infra/cache/instance.py`. Ключи +объектов — по имени базы из `settings.database`: `make test_isolated` с +базой `test_` пишет под своим префиксом. +""" + +from src.config import settings +from src.infra.s3.client import create_object_storage + +object_storage = create_object_storage( + settings.s3, + namespace=settings.database.name, +) diff --git a/src/main.py b/src/main.py index 1eeef931..b5d53d97 100644 --- a/src/main.py +++ b/src/main.py @@ -13,6 +13,7 @@ from src.infra.cache.instance import cache from src.infra.db.session import engine from src.infra.logger import AbstractLogger, get_logger from src.infra.password import prepare_dummy_hash +from src.infra.s3.instance import object_storage from src.schemas.enums import RunModeEnum logger: AbstractLogger = get_logger().bind(module="startup") @@ -25,15 +26,24 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]: # он должен пропустить (src/infra/early_stop.py) early_stop.disarm() database = settings.database - # engine и кэш подключаются лениво: без Postgres сервис стартует, а - # /health/ready отвечает 503; без Valkey запросы идут в Postgres + s3 = settings.s3 + # engine, кэш и S3 подключаются лениво: без Postgres сервис стартует, а + # /health/ready отвечает 503; без Valkey запросы идут в Postgres; без + # S3 — 503 только на путях вложений if not database.password.get_secret_value(): logger.warning("Database password is empty") if not settings.cache.password.get_secret_value(): logger.warning("Cache password is empty") + if not ( + s3.access_key_id.get_secret_value() + and s3.secret_access_key.get_secret_value() + ): + logger.warning("Object storage credentials are empty") # ~30 мс CPU при старте: время ответа на вход с неизвестным username # ровное с первого запроса await prepare_dummy_hash() + # модели botocore грузятся при старте, а не в первом запросе; сети нет + await object_storage.start() logger.info( "Started API", host=settings.app.host, @@ -44,12 +54,16 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]: database_name=database.name, cache_host=settings.cache.host, cache_port=settings.cache.port, + s3_host=s3.host, + s3_port=s3.port, + s3_bucket=s3.bucket, ) try: yield finally: await engine.dispose() await cache.aclose() + await object_storage.aclose() logger.info("Stopped API") diff --git a/src/utils/constants.py b/src/utils/constants.py index 620aa8b4..ee5e60d9 100644 --- a/src/utils/constants.py +++ b/src/utils/constants.py @@ -77,3 +77,14 @@ DB_CLOSE_TIMEOUT_SECONDS = 2 # начало ключей; v1 — формат значений: новый формат — v2, и старые ключи # не читаются без чистки кэша CACHE_KEY_PREFIX = "messenger:v1" + +# хранилище объектов (S3) +# имя bucket по правилам S3: 3–63 символа, строчные латинские буквы, +# цифры, точка и дефис, по краям — буква или цифра +S3_BUCKET_NAME_PATTERN = r"^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$" +# разделитель пространства имён (имени базы) и остатка ключа объекта: +# `<имя базы>/<…>`, как ключи кэша по имени базы +S3_KEY_SEPARATOR = "/" +# секунды, после которых aiohttp закрывает простаивающее соединение с S3: +# раньше шлюза SeaweedFS (120 с), чтобы запрос не ушёл в закрывающееся +S3_KEEPALIVE_TIMEOUT_SECONDS = 15 diff --git a/student-tests/failures.compose.yml b/student-tests/failures.compose.yml index 6aeb0642..82a66008 100644 --- a/student-tests/failures.compose.yml +++ b/student-tests/failures.compose.yml @@ -1,8 +1,8 @@ # Override стенда отказов make failure_checks (student-tests/run_failures.py): # тот же docker-compose.yml под проектом <рабочий>-failures (имя рабочего # проекта — из name в docker-compose.yml, сейчас mtusi-lab4), со своим -# volume и сетью. Порты Postgres и Valkey не публикуются: к ним ходит только -# fault_hook.py через docker compose exec. Сервисы api и haproxy не +# volume и сетью. Порты Postgres, Valkey и S3 не публикуются: к ним ходит +# только fault_hook.py через docker compose exec. Сервисы api и haproxy не # запускаются: контейнеры API создаёт оркестратор (docker compose run # -p 127.0.0.1:...), у реплик api своих портов нет. Порт LB сброшен, чтобы # случайный up не занял APP_OUT_PORT рабочего стенда. @@ -29,5 +29,11 @@ services: test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U \"$$POSTGRES_USER\" -d postgres"] valkey: ports: !reset [] + # свой S3 со своим volume, порт API S3 не публикуется. Срок остановки + # короткий намеренно: здесь проверяется отказ, а не плавная остановка, и + # stop не тянет 15 с (design change s3-storage, решение 9) + s3: + ports: !reset [] + stop_grace_period: 2s haproxy: ports: !reset [] diff --git a/student-tests/fault_hook.py b/student-tests/fault_hook.py index 2b272bd4..677c6a94 100755 --- a/student-tests/fault_hook.py +++ b/student-tests/fault_hook.py @@ -8,7 +8,7 @@ не трогает. Решение 3 design change `failure-checks`. Действия: - stop|start|pause|unpause postgres|valkey + stop|start|pause|unpause postgres|valkey|s3 flush-cache FLUSHALL cache-hits keyspace_hits из INFO stats cache-has-chat EXISTS ключа карточки: 0 или 1 @@ -49,7 +49,7 @@ COMPOSE_FILES = ( ROOT / "student-tests" / "failures.compose.yml", ) PROJECT_SUFFIX = "-failures" -SERVICES = ("postgres", "valkey") +SERVICES = ("postgres", "valkey", "s3") # та же проверка, что в healthcheck сервиса в docker-compose.yml. У # PostgreSQL стенда отказов healthcheck переопределён на базу postgres # (failures.compose.yml), а проба после start / unpause ходит в базу @@ -59,6 +59,10 @@ PROBES = { "postgres": 'pg_isready -q -h 127.0.0.1 -U "$POSTGRES_USER" ' '-d "$POSTGRES_DB"', "valkey": 'test "$(valkey-cli -p "$VALKEY_PORT" ping)" = PONG', + # master выбран, filer и шлюз S3 отвечают — как healthcheck сервиса s3 + "s3": "wget -q -O /dev/null http://127.0.0.1:9333/cluster/healthz && " + "wget -q -O /dev/null http://127.0.0.1:8888/healthz && " + 'wget -q -O /dev/null "http://127.0.0.1:$S3_PORT/healthz"', } PROBE_TIMEOUT_S = 30 # начало ключа карточки — копия CACHE_KEY_PREFIX из src/utils/constants.py: diff --git a/student-tests/run_failures.py b/student-tests/run_failures.py index d0a64beb..5a9b0dfa 100644 --- a/student-tests/run_failures.py +++ b/student-tests/run_failures.py @@ -1,9 +1,9 @@ """`make failure_checks`: проверки отказов на отдельном стенде. Поднимает тот же `docker-compose.yml` под проектом `<рабочий>-failures` -с override `student-tests/failures.compose.yml`: свои PostgreSQL и Valkey -со своим volume, порты хранилищ не публикуются. Затем: -- собирает образ из рабочего дерева и применяет миграции; +с override `student-tests/failures.compose.yml`: свои PostgreSQL, Valkey и +S3 со своими volumes, порты хранилищ не публикуются. Затем: +- собирает образ из рабочего дерева, применяет миграции и bootstrap S3; - запускает два контейнера API: обычный и «тесный» (сроки сессии и ключа идемпотентности 2 с, пул из одного соединения); - прогоняет тесты с маркером `fault` (`pytest -m fault`), передав им hook @@ -13,7 +13,7 @@ `fix-known-issues`); - удаляет стенд вместе с volume при любом исходе, в том числе по Ctrl+C. -Рабочий стенд, его база и кэш не затрагиваются. Только stdlib. Решения +Рабочий стенд, его база, кэш и хранилище объектов не затрагиваются. Только stdlib. Решения 1, 2, 5 design change `failure-checks`. Запускается `$(PYTHON)`, а не `uv run`, по той же причине, что `run_isolated.py`. """ @@ -257,10 +257,21 @@ def main() -> int: try: say("build image") dc(project, "build", "api") - say("start postgres and valkey") - dc(project, "up", "-d", "--wait", "postgres", "valkey") + say("start postgres, valkey and s3") + dc(project, "up", "-d", "--wait", "postgres", "valkey", "s3") say("migrations") dc(project, "run", "--rm", "migrate") + # --wait одноразовый сервис считает готовым уже запущенным: код + # выхода bootstrap — отдельным up, как make start_s3 + say("s3 bootstrap") + dc( + project, + "up", + "--no-deps", + "--exit-code-from", + "s3-bootstrap", + "s3-bootstrap", + ) say("start api containers") base_url = start_api(project, default_name, free_port(), {}) tight_url = start_api(project, tight_name, free_port(), TIGHT_ENV) diff --git a/student-tests/run_isolated.py b/student-tests/run_isolated.py index 010709d8..27033764 100644 --- a/student-tests/run_isolated.py +++ b/student-tests/run_isolated.py @@ -7,8 +7,11 @@ балансировщика, тесты реплик пропускаются), затем удаляет контейнер и базу — при любом исходе, в том числе по Ctrl+C. Рабочая база и рабочие контейнеры стенда не трогаются. Valkey стенда общий: ключи кэша включают имя базы, и -карточки тестового прогона не смешиваются с рабочими. Только stdlib: -всё через docker compose и make. Решение 12 design change +карточки тестового прогона не смешиваются с рабочими. S3 стенда тоже +общий: ключи объектов начинаются с имени базы, и префикс `test_/` +bucket удаляется в начале (хвост прошлого прогона) и в уборке через +`weed shell` в контейнере `s3` (design change `s3-storage`, решение 9). +Только stdlib: всё через docker compose и make. Решение 12 design change `postgres-storage`. Запускается напрямую `$(PYTHON)`, как проверки skeleton, а не через @@ -32,6 +35,12 @@ from pathlib import Path ROOT = Path(__file__).resolve().parents[1] ENV_FILE = ROOT / ".env" DB_NAME_RE = re.compile(r"^[a-z0-9_]+$") +# префикс объектов S3 собирается только из такого имени временной базы: +# ошибка в имени не может удалить рабочий префикс +TEST_DB_NAME_RE = re.compile(r"^test_[a-z0-9_]+$") +# как S3_BUCKET_NAME_PATTERN в src/utils/constants.py +BUCKET_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$") +DEFAULT_BUCKET = "messenger" READY_TIMEOUT_S = 60 LOG_TAIL_LINES = 50 @@ -101,6 +110,33 @@ def drop_database(name: str) -> None: psql(f'DROP DATABASE IF EXISTS "{name}" WITH (FORCE);\n') +def object_prefix(bucket: str, test_db: str) -> str: + """Путь filer префикса `test_/` в bucket; другое имя — отказ.""" + if not TEST_DB_NAME_RE.fullmatch(test_db): + raise ValueError(f"not a test database name: {test_db}") + if not BUCKET_NAME_RE.fullmatch(bucket): + raise ValueError(f"invalid bucket name: {bucket}") + return f"/buckets/{bucket}/{test_db}" + + +def remove_objects(prefix: str) -> None: + """Удалить объекты под префиксом временной базы; его отсутствие — не + ошибка. `weed shell` в контейнере `s3`: ключ подписи — в его + окружении, master и filer — на его loopback.""" + run( + "docker", + "compose", + "exec", + "-T", + "s3", + "sh", + "-c", + "exec weed shell -master=127.0.0.1:9333", + stdin=f"fs.rm -r {prefix}\n", + quiet=True, + ) + + def remove_container(name: str) -> None: run("docker", "rm", "-f", name, check=False, quiet=True) @@ -143,14 +179,24 @@ def main() -> int: if not DB_NAME_RE.fullmatch(test_db): say(f"unsupported database name: {test_db}") return 2 + try: + prefix = object_prefix(env.get("S3__BUCKET", DEFAULT_BUCKET), test_db) + except ValueError as e: + say(str(e)) + return 2 port = env["TEST_APP_PORT"] app_port = env.get("APP__PORT", "8080") container = f"{compose_project()}-test-api" base_url = f"http://127.0.0.1:{port}" - say(f"database={test_db} container={container} base_url={base_url}") + say( + f"database={test_db} objects={prefix}/ container={container} " + f"base_url={base_url}", + ) remove_container(container) drop_database(test_db) + say(f"remove objects {prefix}/") + remove_objects(prefix) results: dict[str, int] = {} failed = True @@ -224,9 +270,11 @@ def main() -> int: remove_container(container) try: if args.keep_db: - say(f"kept database {test_db}") + say(f"kept database {test_db} and objects {prefix}/") else: drop_database(test_db) + say(f"remove objects {prefix}/") + remove_objects(prefix) except subprocess.CalledProcessError as e: say(f"cleanup failed: {e}") results["cleanup"] = 1 diff --git a/student-tests/test_failures.py b/student-tests/test_failures.py index ddebb5c6..8ce42d53 100644 --- a/student-tests/test_failures.py +++ b/student-tests/test_failures.py @@ -1,7 +1,7 @@ """Проверки отказов: выполняет только `make failure_checks` (маркер `fault`). -Стенд и hook готовит `student-tests/run_failures.py`: свои Postgres и -Valkey, обычный API (`BASE_URL`) и «тесный» (сроки сессии и ключа +Стенд и hook готовит `student-tests/run_failures.py`: свои Postgres, +Valkey и S3, обычный API (`BASE_URL`) и «тесный» (сроки сессии и ключа идемпотентности 2 с, пул из одного соединения). На хранилища тесты действуют только через фикстуру `stand` (hook `student-tests/fault_hook.py`) и всегда возвращают их в рабочее состояние. Решение 4 design change `failure-checks`. @@ -42,6 +42,9 @@ IDEMPOTENCY_TTL_S = 2 POOL_TIMEOUT_S = 1 # срок проверки Postgres в /health/ready READINESS_TIMEOUT_S = 2 +# health без S3: проверка к S3 не обращается, ответ быстрее секунды (спек +# health, «Хранилище объектов недоступно»); срок вызова S3 — 5 с +OBJECT_STORAGE_HEALTH_S = 1 # сколько секунд hook держит слоты max_connections; clear-connections # освобождает их раньше FILL_HOLD_S = 30 @@ -349,6 +352,15 @@ def test_readiness_without_cache(api: Api, stand: Stand) -> None: assert api.request("GET", "/health/ready").status_code == 200 +@pytest.mark.spec("health", "Хранилище объектов недоступно") +def test_readiness_without_object_storage(api: Api, stand: Stand) -> None: + with outage(stand, "stop", "s3"): + for path in ("/health/ready", "/health/live"): + resp, took = timed(lambda path=path: api.request("GET", path)) + assert assert_ok(resp, 200, "Health") == {"status": "ok"} + assert took < OBJECT_STORAGE_HEALTH_S, f"{path} took {took:.2f}s" + + # --------------------------------------------------------------------------- # Кэш карточки чата # --------------------------------------------------------------------------- diff --git a/uv.lock b/uv.lock index 37e12f00..073ebc78 100644 --- a/uv.lock +++ b/uv.lock @@ -11,6 +11,92 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/72/15/504337e302d070bd2ff2f39418bb17d2ad73c662c403a4f37cb4e5c5b237/agent_detector-2.0.0-py3-none-any.whl", hash = "sha256:22c6a1c9c23894a12f55aea625f060b8d3330fba774de72d02d5442bb580417f", size = 9352, upload-time = "2026-09-02T14:19:50.971Z" }, ] +[[package]] +name = "aiobotocore" +version = "3.9.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "aiohttp" }, + { name = "aioitertools" }, + { name = "botocore" }, + { name = "jmespath" }, + { name = "multidict" }, + { name = "python-dateutil" }, + { name = "wrapt" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/a5/95/4f7e0453d5e81bdb1b40ecf09f135bb88e12ce27fdb3efa125022dcca5d7/aiobotocore-3.9.2.tar.gz", hash = "sha256:8e32238c5bd77717ab1ac90077ff51ab141d025528115ccc7cc9b50b2d176e5f", size = 524343, upload-time = "2026-10-01T02:01:59.522Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/09/ab/c8f982c4dfaab49200e31820a4ffe6275356f7dcaaa1024735d8f8b4e048/aiobotocore-3.9.2-py3-none-any.whl", hash = "sha256:363b4892423b272eb84afbb58000da0be6ccd0cf8a68b98438c957d05b841efc", size = 102571, upload-time = "2026-10-01T02:01:57.883Z" }, +] + +[[package]] +name = "aiohappyeyeballs" +version = "2.7.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/ce/f4/eec0465c2f67b2664688d0240b3212d5196fd89e741df67ddb81f8d35658/aiohappyeyeballs-2.7.1.tar.gz", hash = "sha256:065665c041c42a5938ed220bdcd7230f22527fbec085e1853d2402c8a3615d9d", size = 24757, upload-time = "2026-07-01T17:11:55.501Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/71/43/1947f06babed6b3f1d7f38b0c767f52df66bfb2bc10b468c4a7de9eceff2/aiohappyeyeballs-2.7.1-py3-none-any.whl", hash = "sha256:9243213661e29250eb41368e5daa826fc017156c3b8a11440826b2e3ed376472", size = 15038, upload-time = "2026-07-01T17:11:54.055Z" }, +] + +[[package]] +name = "aiohttp" +version = "3.14.5" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "aiohappyeyeballs" }, + { name = "aiosignal" }, + { name = "attrs" }, + { name = "frozenlist" }, + { name = "multidict" }, + { name = "propcache" }, + { name = "typing-extensions" }, + { name = "yarl" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/6c/4c/bdccd81e9ee225b69c60e7766c9a5b05364f118f4d383713b89a682d772d/aiohttp-3.14.5.tar.gz", hash = "sha256:5558a7f5a05af9ecf744af91e5baefc436f93c9333e656c27ec253f9a6bbe178", size = 8078052, upload-time = "2026-10-11T01:05:12.408Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d5/94/6ba86efddcb616c811b40e6a0dfdd862738f647e4e3860a961075d5e9ed8/aiohttp-3.14.5-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:df37b620684e19b5e25724412518ccafc3b1a49cdac706fdbd2f983fad943450", size = 817499, upload-time = "2026-10-11T01:00:18.901Z" }, + { url = "https://files.pythonhosted.org/packages/5e/e1/7bca6d84dabd228aa8eb4b7f9feac2586aaa9be5505d7d65bf287a615c43/aiohttp-3.14.5-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:ef60869969180ec2464f1349aff07138ae35ca2200f0946cb3552e49e8f301a8", size = 549467, upload-time = "2026-10-11T01:00:20.854Z" }, + { url = "https://files.pythonhosted.org/packages/64/91/11b89f45ca486252dd67dd5f3231fec04bf5518da39a95cb3997619f17fb/aiohttp-3.14.5-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:d079c0a0135c36e7beb6f1c88087c8f108dc5891cdd0b5eafa778421bda70ed2", size = 548067, upload-time = "2026-10-11T01:00:22.659Z" }, + { url = "https://files.pythonhosted.org/packages/22/ff/c6615806c14aab34f82b9424ccde8ce6e417315fd57ce1c5b4d4747888e1/aiohttp-3.14.5-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:abfda5cb094a829f7bc25216a32f7db2e85cc65bd59910f8e7b40b3d9b224764", size = 1896245, upload-time = "2026-10-11T01:00:24.638Z" }, + { url = "https://files.pythonhosted.org/packages/39/b2/25a8c971ae6a92c8394d77e42422d7f38989e05cf41a5ceb92d73d67ab7e/aiohttp-3.14.5-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:9cc882cf8619109583c906b4d4a85d6a111a98afa34b7a450d1e08118d016820", size = 1872180, upload-time = "2026-10-11T01:00:26.838Z" }, + { url = "https://files.pythonhosted.org/packages/2f/d5/99f93ea36cc5205e47c1e5a803e087f2ad21b5430b5db2e942cb6e988a37/aiohttp-3.14.5-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:7457580535e019e1247ea35d6a02bf081ad30c26d0cbc210c93f6c3ab67a0835", size = 1937261, upload-time = "2026-10-11T01:00:28.74Z" }, + { url = "https://files.pythonhosted.org/packages/40/a6/9ac9c9e6695040bd73d2584a1b59a9388f6433c76d5294a7bf591e21ffe5/aiohttp-3.14.5-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:c5ed596aedb9c42afd3fe0aae3117725378ac73d2cc5ddc735056fbdb96c5d02", size = 2064994, upload-time = "2026-10-11T01:00:30.623Z" }, + { url = "https://files.pythonhosted.org/packages/da/e4/aa172eb534b7f02f1f8ff1c3213347eaf3cf218db91a727c6863c22f1035/aiohttp-3.14.5-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:20f085697d7e911f1f73c43ed03fafbed1e7121797e2eb5428efa80398060584", size = 1919630, upload-time = "2026-10-11T01:00:32.548Z" }, + { url = "https://files.pythonhosted.org/packages/06/7d/4eedafc5bababa8932636c141e346806966eade12c0b7e5946d43bf8218b/aiohttp-3.14.5-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:74b0a9c8270f9b0a11410e124ff8d4f18bfc1f1837440ec84da5ae7b50927b5d", size = 1710016, upload-time = "2026-10-11T01:00:34.471Z" }, + { url = "https://files.pythonhosted.org/packages/b2/94/eee018537ba19da0ceb2ac79cab83faed4ac49568e08376e2799043f2538/aiohttp-3.14.5-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:19e2ba471507c34f8252402ab50f5ab512398b9ea8c8f1cb26beb3f75793ba30", size = 1858112, upload-time = "2026-10-11T01:00:36.581Z" }, + { url = "https://files.pythonhosted.org/packages/68/76/354653a306547238f3427283905972d796ba7c292ba9977abec9f2b6f260/aiohttp-3.14.5-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:d418ce2af40c6bb685b3f663e9e8de27cb0a22431d8e88a167348d7f01878073", size = 1896371, upload-time = "2026-10-11T01:00:38.478Z" }, + { url = "https://files.pythonhosted.org/packages/f2/ec/63e8c7136b570e356345ad3174e3820fdc973ea10712cb6c649bf875755a/aiohttp-3.14.5-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:70cb4008ac2ed1e0ca9e824deb4b53d3aa0d939109698ebf1e723a84337bd794", size = 1905836, upload-time = "2026-10-11T01:00:40.527Z" }, + { url = "https://files.pythonhosted.org/packages/57/d8/11365bda144b127928cd42533d0eff78a55613c9e28f81941bd6630ea887/aiohttp-3.14.5-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:a23fe35d776bc03cb495938b9594450d047e3bc08c5255315a82323e9cb7d2dd", size = 1696534, upload-time = "2026-10-11T01:00:42.686Z" }, + { url = "https://files.pythonhosted.org/packages/2f/3d/82df0461b18e00b2998f205c03e0d3010222478c43640aceb8e03dcd7e8f/aiohttp-3.14.5-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:3e0eb43bed3c6801a6cee315195377789e90b2a72c2277a475b578535312488d", size = 1933970, upload-time = "2026-10-11T01:00:44.71Z" }, + { url = "https://files.pythonhosted.org/packages/03/ad/6ddfe0aacd931c17b53533336d97e9d11a98b96d6ae815a9da0b19f82ccf/aiohttp-3.14.5-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:3be7dd397d64ca3e1869626fa9318aaebb54b7bf93bc72d7a205448d83e4f748", size = 1899501, upload-time = "2026-10-11T01:00:46.629Z" }, + { url = "https://files.pythonhosted.org/packages/9e/8e/189bdd9ae4793059bb09f6dc880f211a6c6c7859cebcbf33912dbfab7dd7/aiohttp-3.14.5-cp312-cp312-win32.whl", hash = "sha256:eb324e2009fb54db30a071dad7caf6998ee2879c4704007efb244514dad1fec1", size = 480370, upload-time = "2026-10-11T01:00:48.468Z" }, + { url = "https://files.pythonhosted.org/packages/ae/ce/1f08114679d49655b30a6e0a29858375c94b82c1de1a0bd0a20c2fee8b02/aiohttp-3.14.5-cp312-cp312-win_amd64.whl", hash = "sha256:2cc38a4f2b516bef1714e690df87a0e043faf1a7693c82d860091684453d5111", size = 506141, upload-time = "2026-10-11T01:00:50.272Z" }, + { url = "https://files.pythonhosted.org/packages/79/d4/c7b4f60b16a1b7e43249fa9031ae05e7e8c341ba4b7d1866f914dafeaa0e/aiohttp-3.14.5-cp312-cp312-win_arm64.whl", hash = "sha256:a63afd1f757de949028387e65a7127b61ad0f775432dbb0e62816ae619fe69ac", size = 488108, upload-time = "2026-10-11T01:00:52.321Z" }, + { url = "https://files.pythonhosted.org/packages/68/30/173960c42b05a6c59f7558e4b12a4b0d9ba376cf6aa9bde7f9e08a30ca8d/aiohttp-3.14.5-py3-none-any.whl", hash = "sha256:efc21a454892828368b11c2c780de0ff8bc991f73f6b99c6b66e56205470929b", size = 279517, upload-time = "2026-10-11T01:05:08.523Z" }, +] + +[[package]] +name = "aioitertools" +version = "0.13.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/fd/3c/53c4a17a05fb9ea2313ee1777ff53f5e001aefd5cc85aa2f4c2d982e1e38/aioitertools-0.13.0.tar.gz", hash = "sha256:620bd241acc0bbb9ec819f1ab215866871b4bbd1f73836a55f799200ee86950c", size = 19322, upload-time = "2025-11-06T22:17:07.609Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/10/a1/510b0a7fadc6f43a6ce50152e69dbd86415240835868bb0bd9b5b88b1e06/aioitertools-0.13.0-py3-none-any.whl", hash = "sha256:0be0292b856f08dfac90e31f4739432f4cb6d7520ab9eb73e143f4f2fa5259be", size = 24182, upload-time = "2025-11-06T22:17:06.502Z" }, +] + +[[package]] +name = "aiosignal" +version = "1.4.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "frozenlist" }, + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/61/62/06741b579156360248d1ec624842ad0edf697050bbaf7c3e46394e106ad1/aiosignal-1.4.0.tar.gz", hash = "sha256:f47eecd9468083c2029cc99945502cb7708b082c232f9aca65da147157b251c7", size = 25007, upload-time = "2025-07-03T22:54:43.528Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/fb/76/641ae371508676492379f16e2fa48f4e2c11741bd63c48be4b12a6b09cba/aiosignal-1.4.0-py3-none-any.whl", hash = "sha256:053243f8b92b990551949e63930a839ff0cf0b0ebbe0597b0f3fb19e1a0fe82e", size = 7490, upload-time = "2025-07-03T22:54:42.156Z" }, +] + [[package]] name = "alembic" version = "1.20.0" @@ -136,6 +222,20 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/94/51/f975cae76d44274cc2868dc9040ac5d58d464784610234455b4e7b19c6ef/black-26.5.1-py3-none-any.whl", hash = "sha256:4ed7f7da04046d2e488437170797d3b4a4ad83906683bcb7dfc68b673bbce5e2", size = 213693, upload-time = "2026-05-18T16:53:33.964Z" }, ] +[[package]] +name = "botocore" +version = "1.43.106" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "jmespath" }, + { name = "python-dateutil" }, + { name = "urllib3" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/11/b9/10ca68d0092895d5ea60f485a61a9840d5aff9d732c66ed60da53a20b1d4/botocore-1.43.106.tar.gz", hash = "sha256:006870b3b4e40547232ad12c3bb4faec91bbbe0659aafaa3b7fa48a112c4ee97", size = 16271399, upload-time = "2026-09-30T19:36:35.836Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a8/eb/c51d3b54dfaa9267a687359d946dc2a1ca6a27fb4d381773e59b7bd72bf4/botocore-1.43.106-py3-none-any.whl", hash = "sha256:c1fb8818f9957cb5037f73db34ac1a12ba43562e31d6e7f9cb7e5fc64e1dba78", size = 15965506, upload-time = "2026-09-30T19:36:32.625Z" }, +] + [[package]] name = "certifi" version = "2026.7.22" @@ -380,6 +480,31 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/7a/6d/db8b86e168fef0cf904737e275bccb683558088ef971e92d3b41ce980699/filelock-4.0.3-py3-none-any.whl", hash = "sha256:30cd166e2aee2c7534ce2c33c6367c4cd051b8368e20e2c4eb0c34f699bacfab", size = 108444, upload-time = "2026-09-23T23:40:20.819Z" }, ] +[[package]] +name = "frozenlist" +version = "1.8.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/2d/f5/c831fac6cc817d26fd54c7eaccd04ef7e0288806943f7cc5bbf69f3ac1f0/frozenlist-1.8.0.tar.gz", hash = "sha256:3ede829ed8d842f6cd48fc7081d7a41001a56f1f38603f9d49bf3020d59a31ad", size = 45875, upload-time = "2025-10-06T05:38:17.865Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/69/29/948b9aa87e75820a38650af445d2ef2b6b8a6fab1a23b6bb9e4ef0be2d59/frozenlist-1.8.0-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:78f7b9e5d6f2fdb88cdde9440dc147259b62b9d3b019924def9f6478be254ac1", size = 87782, upload-time = "2025-10-06T05:36:06.649Z" }, + { url = "https://files.pythonhosted.org/packages/64/80/4f6e318ee2a7c0750ed724fa33a4bdf1eacdc5a39a7a24e818a773cd91af/frozenlist-1.8.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:229bf37d2e4acdaf808fd3f06e854a4a7a3661e871b10dc1f8f1896a3b05f18b", size = 50594, upload-time = "2025-10-06T05:36:07.69Z" }, + { url = "https://files.pythonhosted.org/packages/2b/94/5c8a2b50a496b11dd519f4a24cb5496cf125681dd99e94c604ccdea9419a/frozenlist-1.8.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:f833670942247a14eafbb675458b4e61c82e002a148f49e68257b79296e865c4", size = 50448, upload-time = "2025-10-06T05:36:08.78Z" }, + { url = "https://files.pythonhosted.org/packages/6a/bd/d91c5e39f490a49df14320f4e8c80161cfcce09f1e2cde1edd16a551abb3/frozenlist-1.8.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:494a5952b1c597ba44e0e78113a7266e656b9794eec897b19ead706bd7074383", size = 242411, upload-time = "2025-10-06T05:36:09.801Z" }, + { url = "https://files.pythonhosted.org/packages/8f/83/f61505a05109ef3293dfb1ff594d13d64a2324ac3482be2cedc2be818256/frozenlist-1.8.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:96f423a119f4777a4a056b66ce11527366a8bb92f54e541ade21f2374433f6d4", size = 243014, upload-time = "2025-10-06T05:36:11.394Z" }, + { url = "https://files.pythonhosted.org/packages/d8/cb/cb6c7b0f7d4023ddda30cf56b8b17494eb3a79e3fda666bf735f63118b35/frozenlist-1.8.0-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:3462dd9475af2025c31cc61be6652dfa25cbfb56cbbf52f4ccfe029f38decaf8", size = 234909, upload-time = "2025-10-06T05:36:12.598Z" }, + { url = "https://files.pythonhosted.org/packages/31/c5/cd7a1f3b8b34af009fb17d4123c5a778b44ae2804e3ad6b86204255f9ec5/frozenlist-1.8.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:c4c800524c9cd9bac5166cd6f55285957fcfc907db323e193f2afcd4d9abd69b", size = 250049, upload-time = "2025-10-06T05:36:14.065Z" }, + { url = "https://files.pythonhosted.org/packages/c0/01/2f95d3b416c584a1e7f0e1d6d31998c4a795f7544069ee2e0962a4b60740/frozenlist-1.8.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d6a5df73acd3399d893dafc71663ad22534b5aa4f94e8a2fabfe856c3c1b6a52", size = 256485, upload-time = "2025-10-06T05:36:15.39Z" }, + { url = "https://files.pythonhosted.org/packages/ce/03/024bf7720b3abaebcff6d0793d73c154237b85bdf67b7ed55e5e9596dc9a/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:405e8fe955c2280ce66428b3ca55e12b3c4e9c336fb2103a4937e891c69a4a29", size = 237619, upload-time = "2025-10-06T05:36:16.558Z" }, + { url = "https://files.pythonhosted.org/packages/69/fa/f8abdfe7d76b731f5d8bd217827cf6764d4f1d9763407e42717b4bed50a0/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:908bd3f6439f2fef9e85031b59fd4f1297af54415fb60e4254a95f75b3cab3f3", size = 250320, upload-time = "2025-10-06T05:36:17.821Z" }, + { url = "https://files.pythonhosted.org/packages/f5/3c/b051329f718b463b22613e269ad72138cc256c540f78a6de89452803a47d/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:294e487f9ec720bd8ffcebc99d575f7eff3568a08a253d1ee1a0378754b74143", size = 246820, upload-time = "2025-10-06T05:36:19.046Z" }, + { url = "https://files.pythonhosted.org/packages/0f/ae/58282e8f98e444b3f4dd42448ff36fa38bef29e40d40f330b22e7108f565/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:74c51543498289c0c43656701be6b077f4b265868fa7f8a8859c197006efb608", size = 250518, upload-time = "2025-10-06T05:36:20.763Z" }, + { url = "https://files.pythonhosted.org/packages/8f/96/007e5944694d66123183845a106547a15944fbbb7154788cbf7272789536/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:776f352e8329135506a1d6bf16ac3f87bc25b28e765949282dcc627af36123aa", size = 239096, upload-time = "2025-10-06T05:36:22.129Z" }, + { url = "https://files.pythonhosted.org/packages/66/bb/852b9d6db2fa40be96f29c0d1205c306288f0684df8fd26ca1951d461a56/frozenlist-1.8.0-cp312-cp312-win32.whl", hash = "sha256:433403ae80709741ce34038da08511d4a77062aa924baf411ef73d1146e74faf", size = 39985, upload-time = "2025-10-06T05:36:23.661Z" }, + { url = "https://files.pythonhosted.org/packages/b8/af/38e51a553dd66eb064cdf193841f16f077585d4d28394c2fa6235cb41765/frozenlist-1.8.0-cp312-cp312-win_amd64.whl", hash = "sha256:34187385b08f866104f0c0617404c8eb08165ab1272e884abc89c112e9c00746", size = 44591, upload-time = "2025-10-06T05:36:24.958Z" }, + { url = "https://files.pythonhosted.org/packages/a7/06/1dc65480ab147339fecc70797e9c2f69d9cea9cf38934ce08df070fdb9cb/frozenlist-1.8.0-cp312-cp312-win_arm64.whl", hash = "sha256:fe3c58d2f5db5fbd18c2987cba06d51b0529f52bc3a6cdc33d3f4eab725104bd", size = 40102, upload-time = "2025-10-06T05:36:26.333Z" }, + { url = "https://files.pythonhosted.org/packages/9a/9a/e35b4a917281c0b8419d4207f4334c8e8c5dbf4f3f5f9ada73958d937dcc/frozenlist-1.8.0-py3-none-any.whl", hash = "sha256:0c18a16eab41e82c295618a77502e17b195883241c563b00f0aa5106fc4eaa0d", size = 13409, upload-time = "2025-10-06T05:38:16.721Z" }, +] + [[package]] name = "greenlet" version = "3.5.6" @@ -498,6 +623,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/62/a1/3d680cbfd5f4b8f15abc1d571870c5fc3e594bb582bc3b64ea099db13e56/jinja2-3.1.6-py3-none-any.whl", hash = "sha256:85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67", size = 134899, upload-time = "2025-03-05T20:05:00.369Z" }, ] +[[package]] +name = "jmespath" +version = "1.1.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/d3/59/322338183ecda247fb5d1763a6cbe46eff7222eaeebafd9fa65d4bf5cb11/jmespath-1.1.0.tar.gz", hash = "sha256:472c87d80f36026ae83c6ddd0f1d05d4e510134ed462851fd5f754c8c3cbb88d", size = 27377, upload-time = "2026-01-22T16:35:26.279Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/14/2f/967ba146e6d58cf6a652da73885f52fc68001525b4197effc174321d70b4/jmespath-1.1.0-py3-none-any.whl", hash = "sha256:a5663118de4908c91729bea0acadca56526eb2698e83de10cd116ae0f4e97c64", size = 20419, upload-time = "2026-01-22T16:35:24.919Z" }, +] + [[package]] name = "jsonschema" version = "4.26.0" @@ -611,6 +745,7 @@ name = "mtusi-messenger" version = "0.1.0" source = { editable = "." } dependencies = [ + { name = "aiobotocore" }, { name = "alembic" }, { name = "argon2-cffi" }, { name = "asyncpg" }, @@ -640,6 +775,7 @@ dev = [ [package.metadata] requires-dist = [ + { name = "aiobotocore", specifier = ">=3.9.2,<4" }, { name = "alembic", specifier = ">=1.20.0,<2" }, { name = "argon2-cffi", specifier = ">=25.1.0,<26" }, { name = "asyncpg", specifier = ">=0.31.0,<0.32" }, @@ -664,6 +800,35 @@ dev = [ { name = "pytest", specifier = ">=9.1.1,<10" }, ] +[[package]] +name = "multidict" +version = "6.9.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/d6/99/1d4d69c3512d0ddbfa3a1b69cfd9a151012ab2eb4eabbb096201b1f0b7d8/multidict-6.9.1.tar.gz", hash = "sha256:0f06e60fa190aa7abd0914c2a766736fdc8e9f34878c4346338534b73d1b20e2", size = 182404, upload-time = "2026-09-21T17:59:05.362Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d9/0d/4b5afb6d3e545c9af0cdfe2db8f6f4c6664568c23d863d888674e447e6a4/multidict-6.9.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:29138fef49828542e859828107e42e50d0e587c513b7eb4b2d92bade2b0860fe", size = 98360, upload-time = "2026-09-21T17:55:11.508Z" }, + { url = "https://files.pythonhosted.org/packages/89/ab/1b9ca66251899981b21138b87da9d5a9c2c81af12b1ea7d19466972f7fe2/multidict-6.9.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:19e31815d41cefc365489e591d105d2baceb2f65aa75d29471fbdbda8651e006", size = 59979, upload-time = "2026-09-21T17:55:12.866Z" }, + { url = "https://files.pythonhosted.org/packages/36/eb/6ae44062466c26c8469ef43f2481a6a48d8cea0587b2d54514ec92e2adfd/multidict-6.9.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6ed30be8918e18c8bed0a2e8b70639ecf02feb61ed00ca2e41cfcb2a50fa3f42", size = 57736, upload-time = "2026-09-21T17:55:14.223Z" }, + { url = "https://files.pythonhosted.org/packages/b9/5c/a67817593019257a4ac8b0d1b4c426030e637c047b0692ef405439ecea7a/multidict-6.9.1-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:637f4ae36264bd7b8d9a60193acddc1d735ad52e8ed53a19931ea6d921fea8e5", size = 333097, upload-time = "2026-09-21T17:55:15.591Z" }, + { url = "https://files.pythonhosted.org/packages/90/bf/599ae2e6222822d88a247a8a7ae82fe6fd25d5700757b79603d5edafe6a0/multidict-6.9.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:35fc236507fb1b3138f0af5ecd5f94ed752d4d6d826248eae425f86204013eea", size = 334196, upload-time = "2026-09-21T17:55:17.015Z" }, + { url = "https://files.pythonhosted.org/packages/15/10/d8aac5acacbe7f5c117866c776ec26d5f15a868759b6f37ad8e7ed3b5b02/multidict-6.9.1-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:e58952f04772f59f11c6e007471449809a30165188669bca8fdb19dde40a8f24", size = 317465, upload-time = "2026-09-21T17:55:18.412Z" }, + { url = "https://files.pythonhosted.org/packages/19/0a/714f796f7293a8b1c5c3f465a26996231d5450c54e85d64ef1258c091134/multidict-6.9.1-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:d35a4f1c63f07fbb8c8f9946dea98b21eddf6c57421585f71d91864be3ba2a24", size = 345914, upload-time = "2026-09-21T17:55:20.306Z" }, + { url = "https://files.pythonhosted.org/packages/da/b1/e37fbf769c567be277bcf32df6234035a4384677fcc1bd852752be3d6b93/multidict-6.9.1-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b5f8771aaaed7f80e84a4e471d2f29ab6721e4595075e54d03ae1ed951b2000a", size = 351163, upload-time = "2026-09-21T17:55:22.21Z" }, + { url = "https://files.pythonhosted.org/packages/ed/5b/db08419c1e1f7c9d60cfd2787b2b517d7ae4ebbda8281b48a33eb5141467/multidict-6.9.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:976fd7689d69ec78d67d31d38d396d8adb562f7e8368279f76aed4aa451fa06d", size = 336881, upload-time = "2026-09-21T17:55:23.699Z" }, + { url = "https://files.pythonhosted.org/packages/9b/07/cc9bc8a62651d2d53ab93ee4993b3a71b7cb78eb8ebfc9c757a5b6698617/multidict-6.9.1-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:95052e8777a86bae87c0bd0b5ab22d809e3d1d02bf69e3e66ddda5ba75a05805", size = 303405, upload-time = "2026-09-21T17:55:25.305Z" }, + { url = "https://files.pythonhosted.org/packages/b6/0c/8e912afafa70e944dbb8bec4b66ca6e008511395278c0d3dd0e89567536a/multidict-6.9.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:1a8adfcaf96f587ab138476eaddef95f29b8a2a8a9afbfea8d2fd62180995d02", size = 324265, upload-time = "2026-09-21T17:55:26.989Z" }, + { url = "https://files.pythonhosted.org/packages/66/6a/62c2af80fb085e6234805017af857b8e913dfac7a55e9c1349c27768c58a/multidict-6.9.1-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:1a53de2772cfb74559df2eb4456ec4eeb908435ec55a84b69370d9d745d62aa8", size = 322085, upload-time = "2026-09-21T17:55:28.732Z" }, + { url = "https://files.pythonhosted.org/packages/f8/6b/35bf801b336fd960811207203ffdcdc24acc3558b3e7ff2e1c914b141e70/multidict-6.9.1-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:0f2ce963299d42fa3f22a90adc0fdf174792ffef5ff4c7ffb68260548fb05580", size = 338107, upload-time = "2026-09-21T17:55:30.303Z" }, + { url = "https://files.pythonhosted.org/packages/80/41/495ef65bf5bba29d142d81b3fe1b8154b919bed70e96491b1e93c3c26f0f/multidict-6.9.1-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:5b30ddf7234e611ca877575b62840e6af5977f92f1f9d532eedbb05a44ff8004", size = 339631, upload-time = "2026-09-21T17:55:32.012Z" }, + { url = "https://files.pythonhosted.org/packages/19/bd/057fdff5f4e04dcd40a960e38f77d19d3c4b67dd243ffa5f43718edb29fc/multidict-6.9.1-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:63ada7ee2e9345695f9e9bc4c65d72222253f07b1ac94fd0e37555cc6f3c7f60", size = 302080, upload-time = "2026-09-21T17:55:33.817Z" }, + { url = "https://files.pythonhosted.org/packages/3f/de/9ace933ee8dad808632523726f42255b09600087219e3d4ead7369820910/multidict-6.9.1-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:3c95601ed98fad3f6e2f8fe809c3b526b0fab31ef525e00a155e227f3d17f58a", size = 341107, upload-time = "2026-09-21T17:55:35.471Z" }, + { url = "https://files.pythonhosted.org/packages/d8/ac/7c1204406097bfc5c283d4a3287d61166807d189917567df4c1318484fc4/multidict-6.9.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:c148e8b596000dd3e4bfe206e70f3e666be18d72032e0012555f2373c52e35d6", size = 333482, upload-time = "2026-09-21T17:55:37.002Z" }, + { url = "https://files.pythonhosted.org/packages/ff/c0/a70c32ea3299ebe00f44533740cb46905717c51faf29bbd3ce8bb5886d9d/multidict-6.9.1-cp312-cp312-win32.whl", hash = "sha256:f9dad513626a33670f17cddc6078e30e311f444c957e8dbfc5b2b4603c8b4edb", size = 52548, upload-time = "2026-09-21T17:55:38.529Z" }, + { url = "https://files.pythonhosted.org/packages/d7/2e/8c9c2591df01e5692ad1bf92febb082a17b1c6c3a19aa8b7ff49988fd989/multidict-6.9.1-cp312-cp312-win_amd64.whl", hash = "sha256:a16a1dc8529f9e734a41c3b856f3eae7ebacdc061dde3f8a844e0c7889c97203", size = 59622, upload-time = "2026-09-21T17:55:39.86Z" }, + { url = "https://files.pythonhosted.org/packages/d0/95/59f4472ec512bc180fd207899594c7803ece96262ff9aaa3a4b6d7da6940/multidict-6.9.1-cp312-cp312-win_arm64.whl", hash = "sha256:361f7206cf341ba94fb015688f5c8b480f8e63bd58a4c14a48aeca7851a241cc", size = 54930, upload-time = "2026-09-21T17:55:41.155Z" }, + { url = "https://files.pythonhosted.org/packages/be/59/e26cb779be4c591d1a910f59d29aca9fba4de70349840a833beba2652371/multidict-6.9.1-py3-none-any.whl", hash = "sha256:7bf6478188f4e47bf5686e8a33da4ae28bf43b1b2528d9ee144d28492bfac60b", size = 19176, upload-time = "2026-09-21T17:59:03.501Z" }, +] + [[package]] name = "mypy-extensions" version = "1.1.0" @@ -772,6 +937,32 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/45/e2/bbb7129c9e7999a6b8ee9cca3b66486c25c423ab5a75f34071798b74ce94/pre_commit-4.6.2-py2.py3-none-any.whl", hash = "sha256:e2dde9a75d3bce11bd3831c26d134df00a2803c1d818be6a0383c3dcda25dc4e", size = 226202, upload-time = "2026-08-10T22:07:16.942Z" }, ] +[[package]] +name = "propcache" +version = "0.5.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/b3/9a/9fbf4e4ec0c2d7f1c32519fff782ef467859b8faa9fbc5331a96f6395d43/propcache-0.5.4.tar.gz", hash = "sha256:ff6b113f50bc066a698db5d944d2c6dc7507168dd3341e255a8892fd0715a558", size = 61545, upload-time = "2026-09-16T00:17:14.386Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/71/cd/348d58f142aebc4873345c6b31087629182ca6e0f2b3caeaa528cf882eba/propcache-0.5.4-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:b28f41fa3b8c6900457f858ec5b03998f3a6d535fbc1bb2edec5961ea05ec429", size = 87285, upload-time = "2026-09-16T00:14:29.362Z" }, + { url = "https://files.pythonhosted.org/packages/df/f4/f3ffaee281b276da854ac1d7a6a506d26cbc62ea2e623756f1d0a4a1ba1a/propcache-0.5.4-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:dcbf346a318a5e30063f547630b02bb787ce2f45b6368d5da143660b6a3835d8", size = 50984, upload-time = "2026-09-16T00:14:30.473Z" }, + { url = "https://files.pythonhosted.org/packages/25/88/1d7df7201750b37765ef2b23bc1c526c028dadde80afa0f57a118fc01182/propcache-0.5.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:87a3caecf8095e48dc72f84bfa42e23a848cf410cc9cc13031fba4869b706a21", size = 52460, upload-time = "2026-09-16T00:14:31.692Z" }, + { url = "https://files.pythonhosted.org/packages/83/4f/48865bd02a16ee5236bc46166b2946f37b93e07b0eae355dac0be0b216ca/propcache-0.5.4-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:60a64cbccaa11b7760ce705a14ada17ba459e7ca9f23ba587eb013821032d7ef", size = 251768, upload-time = "2026-09-16T00:14:32.908Z" }, + { url = "https://files.pythonhosted.org/packages/b0/19/3742a5eed62317b03b4002ee865dc9fd720308bdd0da1f29a5786c630311/propcache-0.5.4-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a74bfa37147cc08fb29df10bd9c16f40fa7f860cd3a6d2fff853323a94f6e17f", size = 257723, upload-time = "2026-09-16T00:14:34.267Z" }, + { url = "https://files.pythonhosted.org/packages/cb/d5/ee6350fb0be9122bb6c67082a876d34b90d980d100c106af4b81023e04f4/propcache-0.5.4-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a4d7a54719b67338a305dca2ce6aafe366817df94ddfd4b5514374356f5ca546", size = 265597, upload-time = "2026-09-16T00:14:35.56Z" }, + { url = "https://files.pythonhosted.org/packages/85/9f/83a07b6ec0e043c050cfdd35fb0cf1b7897b91d554d6eea293740309afe7/propcache-0.5.4-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:2814ecd8e818f487bee4b0f921bc4d1c176cc5fc71ac0f072d0fa67eda4ac14b", size = 250424, upload-time = "2026-09-16T00:14:36.894Z" }, + { url = "https://files.pythonhosted.org/packages/33/2c/a763a8251f50fba042af0fb1f02bfec4b31381e40aff760db2be7b2e1f84/propcache-0.5.4-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:6af4693716bfb03f1752ef1b30faa593db2c01d5272e9b8564a1549452a979ab", size = 216748, upload-time = "2026-09-16T00:14:38.369Z" }, + { url = "https://files.pythonhosted.org/packages/6a/e2/4d11bea8fd6a777149c6c20645f873952eab5de3a2497aa11648ec9ab6ab/propcache-0.5.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:4fbc1a15dc8cd1689508758d626b372b1f09d28d9577667feaf9e6bfcd8efcbc", size = 246533, upload-time = "2026-09-16T00:14:39.82Z" }, + { url = "https://files.pythonhosted.org/packages/9f/36/6683597de4907e70c717e3588c541202c66086a72ff3db58be49de66e72c/propcache-0.5.4-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:cdee8205a44d0be91bbac4c41b95d86641b72dfc7aef1279400e4fda3f26a937", size = 238173, upload-time = "2026-09-16T00:14:41.259Z" }, + { url = "https://files.pythonhosted.org/packages/85/84/cb08d79f1762daafeb2b030c470cd0c725c97b8ad67412457c6f35c53e9d/propcache-0.5.4-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:9a2a8a50a93dee0268a860a07fa3b4bd968f8ce4dbd794957da772f395368526", size = 251128, upload-time = "2026-09-16T00:14:42.652Z" }, + { url = "https://files.pythonhosted.org/packages/c2/0d/41b848036db6621370c1f2e5471a7da8149c730f8552a5257567721f4576/propcache-0.5.4-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:7ffafcbfc7b549ab940047e505c831eabac5e67de53e1bc174adbc5285c55944", size = 214821, upload-time = "2026-09-16T00:14:44.112Z" }, + { url = "https://files.pythonhosted.org/packages/f1/b7/adfae4bf9c63bccf12e2d9690a175c6579047a6eec3b5a6a5f51428c15e2/propcache-0.5.4-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:d1f5a500bfcbb2c0ab85e98a0dcd70f5899d34efe365a0187700369a79603031", size = 254793, upload-time = "2026-09-16T00:14:45.429Z" }, + { url = "https://files.pythonhosted.org/packages/51/6f/eeca9647245d5f92e87d53e5f14335bb42fce1a7e6842c8045b364eded8b/propcache-0.5.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:8a235f73d6e020855dc29dff012d920c02ee0feab8d73a24185a7569f4be1161", size = 247134, upload-time = "2026-09-16T00:14:46.976Z" }, + { url = "https://files.pythonhosted.org/packages/5d/a9/424e38838793d37160b4379c702f61c74c598fc6cd17204adbe3c554f7a8/propcache-0.5.4-cp312-cp312-win32.whl", hash = "sha256:b3083bfe87f95c756e610bd8025f26cbd1cd4aaa03a422f2d65efb7a97cd53d8", size = 43073, upload-time = "2026-09-16T00:14:48.338Z" }, + { url = "https://files.pythonhosted.org/packages/58/7b/6e8ef26f6d510a7916064fec68d55fcbfbdf7eb01e377480d66a122152d8/propcache-0.5.4-cp312-cp312-win_amd64.whl", hash = "sha256:98914de2c4d7f0f9f4a8c6ea4bf05841f4175796941e3ef7d47eb718f22311fb", size = 46190, upload-time = "2026-09-16T00:14:49.99Z" }, + { url = "https://files.pythonhosted.org/packages/08/b9/72028c5b56ced97f456de6aefa79435ca64d7f77af78ea8cf3c76fc5195f/propcache-0.5.4-cp312-cp312-win_arm64.whl", hash = "sha256:8876b39961e33d912afe3c1bee18ee564fdad0206f873cc15d522756b7f50737", size = 43075, upload-time = "2026-09-16T00:14:51.155Z" }, + { url = "https://files.pythonhosted.org/packages/f5/cd/785c64ed382f3f04201870267b02783f63b4678c2acfddc177a3ebcc2727/propcache-0.5.4-py3-none-any.whl", hash = "sha256:62c60aec739ed00124573cce1178138fd690c7676352d67a37328c1cf51d7468", size = 16338, upload-time = "2026-09-16T00:17:13.106Z" }, +] + [[package]] name = "pycparser" version = "3.0" @@ -883,6 +1074,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/24/25/1de2678b631f5a49215c6c96fff41ba892b0a34df68d6d80292b1b48aa7f/pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c", size = 386536, upload-time = "2026-06-19T10:58:31.347Z" }, ] +[[package]] +name = "python-dateutil" +version = "2.9.0.post0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "six" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/66/c0/0c8b6ad9f17a802ee498c46e004a0eb49bc148f2fd230864601a86dcf6db/python-dateutil-2.9.0.post0.tar.gz", hash = "sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3", size = 342432, upload-time = "2024-03-01T18:36:20.211Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" }, +] + [[package]] name = "python-discovery" version = "1.6.1" @@ -1324,3 +1527,54 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/97/3d/91954e2f7876f74ce1213e9b92c65a63b559cc4b942a931ebeb351cd9932/websockets-17.1-cp312-cp312-win_arm64.whl", hash = "sha256:9f4a08ff7cb68c27b18e09223cc6304e01d0f82d5a240d251266dfd2e6e44729", size = 217711, upload-time = "2026-08-26T14:56:09.267Z" }, { url = "https://files.pythonhosted.org/packages/41/63/23572870e01836a98346075b9e17a8bc24a6ddd9800a3204ceee58677f3c/websockets-17.1-py3-none-any.whl", hash = "sha256:f221081107b8c48184d99f7019604486376e7ef826037e70aad6b02540732c23", size = 211134, upload-time = "2026-08-26T17:25:31.397Z" }, ] + +[[package]] +name = "wrapt" +version = "2.5.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/04/22/89e2f3bdae5cb34e0cab0cd86d7172dbf418de4b46c9b17b9c7a560dfa44/wrapt-2.5.1.tar.gz", hash = "sha256:f595bb0185aab3e9dc31950c95d914f56ea8278810c3b928f3426e12ed6d27bc", size = 184455, upload-time = "2026-10-14T00:39:39.24Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/66/9b/c7f97d5493a33b5ed01d3c85745f9bdfdd2e5c2785471b8d8b55a3c273d6/wrapt-2.5.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:6e3eff05ae616671b40d7ad0a504210329e4adc9fb91415663570aca93c5f5cc", size = 106452, upload-time = "2026-10-14T00:37:18.951Z" }, + { url = "https://files.pythonhosted.org/packages/7f/b0/335b0af2930938678fcde954b29780b26308961b93df5e0192fc182e8b7e/wrapt-2.5.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:c44dd9881626da7d621c23805f26726f6b023cf3e9755f48d092bc9cbef4a8e7", size = 106087, upload-time = "2026-10-14T00:37:20.392Z" }, + { url = "https://files.pythonhosted.org/packages/4a/5a/2a34ba5a468e9d3d6e5b0733280e1ae3c850bfc5f1d681fc0e97f564d1f2/wrapt-2.5.1-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:bfaa998ceeea4d0aa72b40cdd0023d19409504e244b439ff2aa9f01729341c5f", size = 250438, upload-time = "2026-10-14T00:37:21.882Z" }, + { url = "https://files.pythonhosted.org/packages/b3/d5/3d4ad322af74d3ab2a14f69ba844cdd3edefb555edfc1c1976ec0112d5c4/wrapt-2.5.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d6d274ec50a5b208be75596dc44ea253e65deaa6ee3a600babc86dafbb957dfc", size = 250594, upload-time = "2026-10-14T00:37:23.497Z" }, + { url = "https://files.pythonhosted.org/packages/37/1a/3cbf48425ec2c66aa9645218458da1e19e315abb9766604d3c49e579076c/wrapt-2.5.1-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:1a96e2671c60f9f09ae547b5a815cecb29af16caa68d73693387d0028788cb32", size = 229856, upload-time = "2026-10-14T00:37:25.029Z" }, + { url = "https://files.pythonhosted.org/packages/cc/e7/b2ea57f4c51258659200565af8617d76992b0fe65e6aad7162dd5720ef05/wrapt-2.5.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:729d644b6acaf4846a4ef81b037857b66a01dea6d227f827c6d71c0b6d656d6c", size = 247153, upload-time = "2026-10-14T00:37:26.67Z" }, + { url = "https://files.pythonhosted.org/packages/9d/c1/4714743e672ed1084a035a2a4f0edeef7838399753b4856a0dc46ef9487d/wrapt-2.5.1-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:859f67bfc31eb7ab55f237b629cd4ab0441b075912446481f910f7d02066811e", size = 226726, upload-time = "2026-10-14T00:37:28.425Z" }, + { url = "https://files.pythonhosted.org/packages/91/e3/c00401bcc3485eb9937c3fe4a1cc8fc3b61800b1378ea3a143ea1c30f6f6/wrapt-2.5.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:29b62e87fcd6a1893f669abfd02a596a7fc5cfa79fa57e42c4e650a6c170c67b", size = 238843, upload-time = "2026-10-14T00:37:30.075Z" }, + { url = "https://files.pythonhosted.org/packages/76/b5/c16759fb0721e63df92b576c2222ce1f11690a8b300fd91b49c55436865c/wrapt-2.5.1-cp312-cp312-win32.whl", hash = "sha256:f1c911818fb076910ef509f2298dfcb966a54a6ff068eebd459632102cf589fb", size = 100488, upload-time = "2026-10-14T00:37:31.625Z" }, + { url = "https://files.pythonhosted.org/packages/22/d5/39d5a704650f18799f37841442b464edb81cf2015f006eaef26068acc6ea/wrapt-2.5.1-cp312-cp312-win_amd64.whl", hash = "sha256:c39c7130ea0702c4ab0faf12da1df1e02d5174305c17edf02309e2f058c4114f", size = 106048, upload-time = "2026-10-14T00:37:33.188Z" }, + { url = "https://files.pythonhosted.org/packages/21/bf/65743adeeb5476920c62dad6cded7bc8789e19bd4f9a336d4ac812adb8de/wrapt-2.5.1-cp312-cp312-win_arm64.whl", hash = "sha256:e089a22ff5af1290b8c759a610830bdb2a829ef9c3d7797e4ee32c2f795ed482", size = 103200, upload-time = "2026-10-14T00:37:34.673Z" }, + { url = "https://files.pythonhosted.org/packages/bc/0c/7da7513ddcc8f1d831ec4bfbedc9f7f174ecb91042bc16916fc1e0d06b22/wrapt-2.5.1-py3-none-any.whl", hash = "sha256:c6e6c226b1ca5402d7ae5fb34a0d21f1b49124fe4200e5884d1e19e53c47ac1d", size = 81849, upload-time = "2026-10-14T00:39:37.441Z" }, +] + +[[package]] +name = "yarl" +version = "1.25.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "idna" }, + { name = "multidict" }, + { name = "propcache" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/75/16/e8be8e2fb175bbf41a0680381a319f1199fae256588241a2ac8677eafb49/yarl-1.25.1.tar.gz", hash = "sha256:03dd38de09bc213e9a8b29761eec33ee1d5318dac0e49d8af36e4d27830e23a7", size = 246245, upload-time = "2026-09-15T19:35:02.264Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/75/b3/cd32ac66ae622b854c2df0ac52106dda220d361b65a64fde7d5b3684aa3f/yarl-1.25.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:94d7aa6debf92a1dd14cb5280b083a764169a13cfb23a452111160274ed989f4", size = 144798, upload-time = "2026-09-15T19:31:01.821Z" }, + { url = "https://files.pythonhosted.org/packages/61/fb/a2c52a8007c2051ba74662afb112ecf3d00346af4c25e33df9d80fd14fb8/yarl-1.25.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:83d4a37e4b95da4d8bda930d6d35b75b4cdadbacbb4980cae290ea3100b5d51d", size = 104583, upload-time = "2026-09-15T19:31:04.05Z" }, + { url = "https://files.pythonhosted.org/packages/be/dd/ee38aec8e09fdf957e50d4085453fbe202f56c6c3b4cf07b81cdb4f09ee9/yarl-1.25.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:e029648f9c951db30e98a7d7ec90835db88ec4b32820efe2a9bdc2287e032eb6", size = 104325, upload-time = "2026-09-15T19:31:06.338Z" }, + { url = "https://files.pythonhosted.org/packages/1e/b3/058dbfb1857b484c9cf9cc135659f50b85ce66e03c99e44dc2f7b6161f55/yarl-1.25.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4d781294bb815ecb5ea57ff6bbf8038e0a31a95fdf3e1788f66e0dc100d64b58", size = 115358, upload-time = "2026-09-15T19:31:08.593Z" }, + { url = "https://files.pythonhosted.org/packages/db/39/29693446cf0cf6b15a0e2f75a5d40f93c56819b05b0622196f45e95b5cc0/yarl-1.25.1-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:e12c538e00e7c1b286a07061046b90e8124e6a9793efae2c70db6a4aad07faad", size = 107658, upload-time = "2026-09-15T19:31:10.802Z" }, + { url = "https://files.pythonhosted.org/packages/86/b3/3c4dd7e1af43b931fba95e0a722737f2ea94a6d199c802585282831d7abd/yarl-1.25.1-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:7e4de3ac4adbad3d0bc7c6f4360a7dbff5de2f15e3b723be3198074e17fd9c40", size = 122660, upload-time = "2026-09-15T19:31:12.84Z" }, + { url = "https://files.pythonhosted.org/packages/bd/b5/1b60dbc3cfc9c5712b15148c206748f2bc93953ffdbe25ea75b63dfc89c9/yarl-1.25.1-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:419f392a1da624877975709e3864dfe833af6cc7671b39318086d456e288380c", size = 126506, upload-time = "2026-09-15T19:31:15.088Z" }, + { url = "https://files.pythonhosted.org/packages/bc/7b/ca212cbe170ac8b96e45317ecbcf9c3c3ecf0cdec98d5b088a9c4088929b/yarl-1.25.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c6f117789d22dce188e5754e8bc65b7e6ebf8cb73963b9fa761f672a5883769d", size = 117050, upload-time = "2026-09-15T19:31:17.241Z" }, + { url = "https://files.pythonhosted.org/packages/cb/c3/72b4938cdbe619ad71ac156182faef4908846b84dc3ca4dbb4c4e6f84014/yarl-1.25.1-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:80e47012e730da131c9f059c80936783f9659aae22dc31c03c0595590d11ed54", size = 114174, upload-time = "2026-09-15T19:31:19.294Z" }, + { url = "https://files.pythonhosted.org/packages/e8/43/268717870f9ba0cc9701a95181587f6dc8c5f387aab4aeecc83158f38a79/yarl-1.25.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:e80f557716fd765439577131e526b8942ffc2c07bdbc5e39fa62f660ba1e963f", size = 114944, upload-time = "2026-09-15T19:31:21.414Z" }, + { url = "https://files.pythonhosted.org/packages/da/84/baa5bf504d51fe062c4bcaf62936da97fffb43285978d0b39984824231fd/yarl-1.25.1-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:f61964f235a43738bfac50da46fc4254943a7eea3051aeb0b6fc7c992c29fadc", size = 108263, upload-time = "2026-09-15T19:31:23.388Z" }, + { url = "https://files.pythonhosted.org/packages/a4/28/779a2ed9e0152a601a27039bed9aead3f0b79797a67e2c44bfa444622dd8/yarl-1.25.1-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:e546fe1d4a93ebc2910f0d768baff19faa09843ab3f2036a67ed6e69fae4419d", size = 122184, upload-time = "2026-09-15T19:31:25.343Z" }, + { url = "https://files.pythonhosted.org/packages/f8/1f/118e9e5b8f07694d63fd3222e801d7782270003f1a222aa798df3f8d5933/yarl-1.25.1-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:cce0727fd5ac04d372fa9bbfde9febc2bcf209aadfcf0468e45dec72719895d1", size = 114001, upload-time = "2026-09-15T19:31:27.465Z" }, + { url = "https://files.pythonhosted.org/packages/0f/ae/a4cf1cf372313734b17996d4007f9f73596e7a178b9485802e5494ecf484/yarl-1.25.1-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:af4ea5b37403ef4e30f3927eaed540db942bde01d8d3ff083527c0704d1c9c68", size = 120565, upload-time = "2026-09-15T19:31:29.47Z" }, + { url = "https://files.pythonhosted.org/packages/05/79/ad94f93ca731bc9e44d321833ab96b82a4f9f5f63cf773f81a4aeea5ecc1/yarl-1.25.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:68782fdb4027b8d1eee25ec35e9a6db05e863b899eb0310b3a33b6c3fef55707", size = 117060, upload-time = "2026-09-15T19:31:31.367Z" }, + { url = "https://files.pythonhosted.org/packages/bb/cc/51a7b4abf4ac593b8e7eb3794b28e5a35ae26eed8bc04787628d215af82f/yarl-1.25.1-cp312-cp312-win_amd64.whl", hash = "sha256:7d575b54cb3863ef9bc290ea4b009999d55dc237326131e4853cf33e888fee03", size = 102593, upload-time = "2026-09-15T19:31:33.329Z" }, + { url = "https://files.pythonhosted.org/packages/9d/21/0941a6b93a58b59a1ec75e5333bf06929b671309c43c0cd201c172d9c39f/yarl-1.25.1-cp312-cp312-win_arm64.whl", hash = "sha256:bc3ac7bf569f6b64dad04dd7808c7872dae8a97df657856eac05e9b7e3614a85", size = 97697, upload-time = "2026-09-15T19:31:35.855Z" }, + { url = "https://files.pythonhosted.org/packages/54/22/318c7980066769c6bcd9221ed2248294f5698811da099013098c670565ed/yarl-1.25.1-py3-none-any.whl", hash = "sha256:681c758b0490f9e96b78e5fa8e8dc6e648e9185bb6eaebe73183c33ea0c445f3", size = 63617, upload-time = "2026-09-15T19:34:59.616Z" }, +]