diff --git a/openspec/changes/fix-upload-put-flake/tasks.md b/openspec/changes/fix-upload-put-flake/tasks.md index 9d08ee6f..273a2b7e 100644 --- a/openspec/changes/fix-upload-put-flake/tasks.md +++ b/openspec/changes/fix-upload-put-flake/tasks.md @@ -9,11 +9,11 @@ ## 1. Тест до кода -- [ ] 1.1 `student-tests/api_client.py`: метод `Api` для скачивания +- [x] 1.1 `student-tests/api_client.py`: метод `Api` для скачивания оригинала потоком с паузой между блоками. Он отдаёт статус, заголовки и байты, идентификация — через `actor` (`student-tests.md`, «Как устроен набор»). Проверка: `make lint`, метод использует тест 1.4. -- [ ] 1.2 `student-tests/run_failures.py`: четвёртый API +- [x] 1.2 `student-tests/run_failures.py`: четвёртый API `<проект>-api-s3`: - `S3_ENV = {"S3__TIMEOUT_SECONDS": "1"}`, тестам — `FAULT_S3_BASE_URL` и `FAULT_S3_ENV`; @@ -24,11 +24,11 @@ Проверка: `make failure_checks FAULT_ARGS='-k idle_s3'` печатает адрес четвёртого API, после команды `docker ps -a` и `docker volume ls` с меткой проекта отказов пусты. -- [ ] 1.3 `student-tests/conftest.py`: `FAULT_S3_BASE_URL` обязателен для +- [x] 1.3 `student-tests/conftest.py`: `FAULT_S3_BASE_URL` обязателен для тестов `fault` (без него — выход с кодом 2, как у трёх адресов), фикстура `s3_api` со сроком клиента 30 с. Проверка: `pytest -m fault` без стенда останавливается до первого теста с кодом 2. -- [ ] 1.4 `student-tests/test_failures.py`: `test_upload_after_idle_s3`, +- [x] 1.4 `student-tests/test_failures.py`: `test_upload_after_idle_s3`, маркер `spec("attachments", "Загрузка после простоя S3")`, по design, решение 3: - `assert_s3_stand` сверяет `FAULT_S3_ENV` с ожидаемым; @@ -41,7 +41,7 @@ - вероятность промаха (≈ 4e-12) — в докстринге. Проверка: `make lint`. -- [ ] 1.5 Синхронизировать дельты `attachments`, `object-storage` и +- [x] 1.5 Синхронизировать дельты `attachments`, `object-storage` и `student-tests` в основные спеки (`openspec/specs/`): сверка покрытия читает только их, и маркер нового сценария без этого — ссылка на неизвестный сценарий. Проверка: `make student_test diff --git a/openspec/specs/attachments/spec.md b/openspec/specs/attachments/spec.md index a5d71e05..e09bc0f1 100644 --- a/openspec/specs/attachments/spec.md +++ b/openspec/specs/attachments/spec.md @@ -526,6 +526,11 @@ S3: без зафиксированных метаданных объект не После возврата S3 загрузка и скачивание SHALL проходить без перезапуска API. +503 на загрузке и скачивании SHALL означать только такой отказ S3: +недоступен, не ответил за срок или отказал. Доступный S3 MUST NOT давать +503 из-за того, что реплика какое-то время не обращалась к нему, в том +числе после скачивания больших оригиналов. + #### Scenario: S3 остановлен - **WHEN** вложение загружено, затем S3 остановлен, и участник @@ -542,6 +547,14 @@ API. - **THEN** оба ответа 503 `unavailable` не позже срока вызова S3 с запасом, а после разморозки скачивание — 200 +#### Scenario: Загрузка после простоя S3 + +- **WHEN** участники одновременно скачали оригинал в несколько MiB, + затем реплика дольше срока вызова S3 не обращалась к S3, а S3 всё это + время доступен, и участник одну за другой загружает файлы +- **THEN** каждая загрузка — 201, ни одной 503 +- **AND** скачанные байты совпадают с загруженными + ### Requirement: Вложение доступно через любую реплику Готовое вложение SHALL скачиваться через любую реплику API за diff --git a/openspec/specs/object-storage/spec.md b/openspec/specs/object-storage/spec.md index d9084e6e..7d457b3d 100644 --- a/openspec/specs/object-storage/spec.md +++ b/openspec/specs/object-storage/spec.md @@ -343,6 +343,14 @@ SHALL сохраняться и после принудительного зав каждая страница списка, SHALL быть ограничен сроком из настроек. После отказа или истечения срока вызов MUST NOT повторяться автоматически. +Срок из настроек SHALL быть единственным сроком вызова, и он +заканчивается вместе с вызовом: у потокового чтения он действует на +каждый блок. Соединение, которое простаивает в пуле клиента, MUST NOT +ломаться от срока прошлого вызова. Поэтому вызов после простоя S3 дольше +срока вызова SHALL проходить, если S3 доступен, — в том числе после +потокового чтения большого объекта. Ошибкой недоступности такой вызов +SHALL заканчиваться только по причинам из списка ниже. + Ошибкой недоступности, которую API отдаёт как 503 `unavailable` в формате контракта, SHALL заканчиваться вызов, если S3: - недоступен; @@ -379,6 +387,16 @@ bucket — ошибка, а не пустая страница. После во - **WHEN** S3 снова доступен, а приложение не перезапускалось - **THEN** следующий вызов проходит +#### Scenario: Вызов после простоя + +- **WHEN** приложение одновременно прочитало потоком несколько объектов + по несколько MiB, затем дольше срока вызова, но меньше срока жизни + простаивающего соединения не обращалось к S3, а S3 всё это время + доступен +- **THEN** следующие записи объектов проходят, ни одна не завершается + ошибкой недоступности +- **AND** S3 получает тело каждой записи целиком + #### Scenario: Объекта нет - **WHEN** приложение читает ключ, которого в bucket нет diff --git a/openspec/specs/student-tests/spec.md b/openspec/specs/student-tests/spec.md index 5bfe5ad4..5913e7d0 100644 --- a/openspec/specs/student-tests/spec.md +++ b/openspec/specs/student-tests/spec.md @@ -373,20 +373,25 @@ PostgreSQL стенда, с Valkey и S3 стенда. Команда SHALL по видна», «Сбой записи метаданных», «Фиксация ready не удалась», «Обрыв передачи тела», «Отказ раньше очереди», «Все места заняты», «Очередь ожидания полна», «Ожидание места», «Место освобождается», «Медленный - клиент», «Медленная передача в срок», «Потерянный оригинал»; + клиент», «Медленная передача в срок», «Потерянный оригинал», «Загрузка + после простоя S3»; - `storage-consistency`: все сценарии. Команда SHALL: - собрать образ из рабочего дерева; - поднять отдельный стенд со своими PostgreSQL, Valkey и S3, применить миграции и bootstrap S3; -- запустить три API: +- запустить четыре API: - с настройками по умолчанию; - «тесный» — с коротким сроком сессии и ключа идемпотентности и пулом из одного соединения; - «узкий по загрузкам» — с одним местом загрузки, одной загрузкой в - очереди, коротким сроком ожидания места и коротким сроком тела. Их - значения SHALL передаваться проверкам; + очереди, коротким сроком ожидания места и коротким сроком тела; + - «с коротким сроком S3» — со сроком вызова S3 в одну секунду: простой + дольше срока вызова в проверке длится полторы секунды, а не шесть. + + Значения «узкого» API и API с коротким сроком S3 SHALL передаваться + проверкам, и проверки SHALL сверять с ними стенд; - запустить уборщика с коротким grace и интервалом, сравнимыми со временем теста, без плановой сверки, и передать их значения проверкам. Grace при этом SHALL проходить проверку границы живой diff --git a/student-tests/api_client.py b/student-tests/api_client.py index 4d1371d5..15b49472 100644 --- a/student-tests/api_client.py +++ b/student-tests/api_client.py @@ -4,6 +4,7 @@ import base64 import dataclasses import hashlib import secrets +import time import uuid from collections.abc import Callable, Sequence from dataclasses import dataclass @@ -21,6 +22,8 @@ MAX_PAGES = 1000 # с лабы 3 обязателен у POST сообщения: одна отправка — один ключ, повтор # неподтверждённой отправки — тот же ключ IDEMPOTENCY_KEY = "Idempotency-Key" +# блок медленного скачивания: столько же отдаёт за раз поток S3 в API +DOWNLOAD_CHUNK_BYTES = 64 * 1024 class _NewKey: @@ -332,6 +335,37 @@ class Api: params=params, ) + def attachment_content_slowly( + self, + actor: Actor | None, + attachment_id: str, + *, + pause_s: float, + chunk_bytes: int = DOWNLOAD_CHUNK_BYTES, + ) -> httpx.Response: + """Байты оригинала потоком: пауза `pause_s` после каждого блока + `chunk_bytes` — клиент читает медленнее сети. + + Отдаёт ответ со статусом, заголовками и прочитанными байтами в + `content`, как `attachment_content`: его проверяет тот же + `assert_content`. + """ + with self.client.stream( + "GET", + f"{API}/attachments/{attachment_id}/content", + headers=actor.headers() if actor is not None else {}, + ) as streamed: + chunks = [] + for chunk in streamed.iter_bytes(chunk_bytes): + chunks.append(chunk) + time.sleep(pause_s) + return httpx.Response( + streamed.status_code, + headers=streamed.headers, + content=b"".join(chunks), + request=streamed.request, + ) + def messages_page( self, actor: Actor, diff --git a/student-tests/conftest.py b/student-tests/conftest.py index 62209dcf..b5ce42ec 100644 --- a/student-tests/conftest.py +++ b/student-tests/conftest.py @@ -24,9 +24,14 @@ FAULT_TIGHT_BASE_URL = os.environ.get("FAULT_TIGHT_BASE_URL", "").rstrip("/") FAULT_UPLOADS_BASE_URL = os.environ.get("FAULT_UPLOADS_BASE_URL", "").rstrip( "/", ) +# API стенда отказов с коротким сроком вызова S3 (change fix-upload-put-flake) +FAULT_S3_BASE_URL = os.environ.get("FAULT_S3_BASE_URL", "").rstrip("/") FAULT_HOOK_TIMEOUT_S = 120 # срок клиента «узкого» API: больше ожидания места, срока тела и шагов UPLOADS_CLIENT_TIMEOUT_S = 30 +# срок клиента API с коротким сроком S3: медленное скачивание оригинала +# в несколько MiB длится дольше 5 с по умолчанию у `Api` +S3_CLIENT_TIMEOUT_S = 30 @pytest.hookimpl(tryfirst=True) @@ -60,7 +65,10 @@ def pytest_collection_finish(session: pytest.Session) -> None: item for item in session.items if item.get_closest_marker("fault") ] if selected and not ( - FAULT_HOOK and FAULT_TIGHT_BASE_URL and FAULT_UPLOADS_BASE_URL + FAULT_HOOK + and FAULT_TIGHT_BASE_URL + and FAULT_UPLOADS_BASE_URL + and FAULT_S3_BASE_URL ): pytest.exit( "fault checks need the failure stand and its hook: " @@ -184,3 +192,10 @@ def uploads_api() -> Iterator[Api]: timeout=UPLOADS_CLIENT_TIMEOUT_S, ) as client: yield client + + +@pytest.fixture(scope="session") +def s3_api() -> Iterator[Api]: + """API стенда отказов со сроком вызова S3 1 с (`FAULT_S3_ENV`).""" + with Api(FAULT_S3_BASE_URL, timeout=S3_CLIENT_TIMEOUT_S) as client: + yield client diff --git a/student-tests/run_failures.py b/student-tests/run_failures.py index 80d3580c..e27bd1e4 100644 --- a/student-tests/run_failures.py +++ b/student-tests/run_failures.py @@ -9,11 +9,13 @@ S3 со своими volumes, порты хранилищ не публикую решение 10) без плановой сверки (design change `track2-reconciler`, решение 9) и передаёт значения тестам; уборщика с плановой сверкой `<проект>-cleaner-scheduled` запускает hook и убирает этот скрипт; -- запускает три контейнера API: обычный (с `MAX_UPLOAD_BYTES=1` и +- запускает четыре контейнера API: обычный (с `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1` в окружении — лимиты вложений от них не зависят), «тесный» (сроки сессии и ключа идемпотентности 2 с, пул из одного - соединения) и «узкий по загрузкам» (одно место загрузки, одна в - очереди, ожидание места 1 с, срок тела 3 с; change `upload-memory`); + соединения), «узкий по загрузкам» (одно место загрузки, одна в + очереди, ожидание места 1 с, срок тела 3 с; change `upload-memory`) и + «с коротким сроком S3» (срок вызова S3 1 с; change + `fix-upload-put-flake`); - прогоняет тесты с маркером `fault` (`pytest -m fault`), передав им hook `student-tests/fault_hook.py`; при падении печатает журналы API и уборщика; @@ -91,6 +93,13 @@ UPLOADS_ENV = { "UPLOADS__WAIT_TIMEOUT_SECONDS": "1", "UPLOADS__BODY_TIMEOUT_SECONDS": "3", } +# API «с коротким сроком S3» (change fix-upload-put-flake, design, решение +# 3): срок вызова S3 1 с, и простой дольше срока в test_upload_after_idle_s3 +# — 1,5 с, а не 6. Других тестов на нём нет: пул S3 процесса — только от +# этого теста. Те же пары тест получает в `FAULT_S3_ENV` и сверяет стенд +S3_ENV = { + "S3__TIMEOUT_SECONDS": "1", +} def say(message: str) -> None: @@ -308,10 +317,17 @@ def main() -> int: default_name = f"{project}-api" tight_name = f"{project}-api-tight" uploads_name = f"{project}-api-uploads" + s3_name = f"{project}-api-s3" # уборщик с плановой сверкой — его запускает hook run-cleaner (design # change track2-reconciler, решение 11); убирается вместе с API scheduled_name = f"{project}-cleaner-scheduled" - containers = [default_name, tight_name, uploads_name, scheduled_name] + containers = [ + default_name, + tight_name, + uploads_name, + s3_name, + scheduled_name, + ] say(f"project={project} (working stand: {working})") if not cleanup(project, containers): @@ -355,8 +371,10 @@ def main() -> int: free_port(), UPLOADS_ENV, ) + s3_url = start_api(project, s3_name, free_port(), S3_ENV) say( - f"ready: api={base_url} tight={tight_url} uploads={uploads_url}", + f"ready: api={base_url} tight={tight_url} uploads={uploads_url} " + f"s3={s3_url}", ) env = ( os.environ @@ -364,10 +382,12 @@ def main() -> int: "BASE_URL": base_url, "FAULT_TIGHT_BASE_URL": tight_url, "FAULT_UPLOADS_BASE_URL": uploads_url, + "FAULT_S3_BASE_URL": s3_url, "FAULT_HOOK": str(FAULT_HOOK), "FAULT_PROJECT": project, "FAULT_LIMITS_ENV": env_pairs(LIMITS_ENV), "FAULT_UPLOADS_ENV": env_pairs(UPLOADS_ENV), + "FAULT_S3_ENV": env_pairs(S3_ENV), } | storage_names(project) | timings diff --git a/student-tests/test_failures.py b/student-tests/test_failures.py index 64a3cd99..c6a93ed6 100644 --- a/student-tests/test_failures.py +++ b/student-tests/test_failures.py @@ -5,14 +5,17 @@ Valkey и S3, уборщик незавершённых загрузок (grace `FAULT_CLEANER_GRACE_S`, `FAULT_CLEANER_INTERVAL_S`), обычный API (`BASE_URL`, с `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1` в окружении), «тесный» (сроки сессии и ключа идемпотентности 2 с, пул из одного -соединения) и «узкий по загрузкам» (`FAULT_UPLOADS_BASE_URL`: одно место +соединения), «узкий по загрузкам» (`FAULT_UPLOADS_BASE_URL`: одно место загрузки, одна в очереди, ожидание 1 с, срок тела 3 с — change -`upload-memory`). На хранилища и API тесты действуют только через фикстуру -`stand` (hook `student-tests/fault_hook.py`) и всегда возвращают их в -рабочее состояние. Решение 4 design change `failure-checks`, решение 10 -design change `upload-consistency`, решение 11 design change -`track2-reconciler` (сверка bucket и БД — в конце модуля: её тесты -оставляют помеченные потерянными вложения, прежние тесты таких не ждут). +`upload-memory`) и «с коротким сроком S3» (`FAULT_S3_BASE_URL`: срок вызова +S3 1 с — change `fix-upload-put-flake`). На хранилища и API тесты +действуют только через фикстуру `stand` (hook +`student-tests/fault_hook.py`) и всегда возвращают их в рабочее +состояние. Решение 4 design change `failure-checks`, решение 10 design +change `upload-consistency`, решение 11 design change `track2-reconciler` +(сверка bucket и БД — в конце модуля: её тесты оставляют помеченные +потерянными вложения, прежние тесты таких не ждут), решение 3 design +change `fix-upload-put-flake`. """ import hashlib @@ -23,6 +26,7 @@ import threading import time import uuid from collections.abc import Callable, Collection, Iterator +from concurrent.futures import ThreadPoolExecutor from contextlib import contextmanager from dataclasses import dataclass from typing import Any @@ -38,6 +42,7 @@ from contract import ( assert_error, assert_ok, assert_unauthorized, + describe, ) pytestmark = pytest.mark.fault @@ -1484,6 +1489,97 @@ def test_slow_body( ) +# --------------------------------------------------------------------------- +# Простой S3 после скачиваний (change fix-upload-put-flake, design, решение +# 3): API «с коротким сроком S3» — срок вызова S3 из FAULT_S3_ENV +# (run_failures.py, S3_ENV), других тестов на нём нет +# --------------------------------------------------------------------------- + +S3_ENV = dict( + item.split("=", 1) for item in os.environ.get("FAULT_S3_ENV", "").split() +) +# окружение, с которым тест ниже ждёт API с коротким сроком S3 +EXPECTED_S3_ENV = {"S3__TIMEOUT_SECONDS": "1"} +SHORT_S3_TIMEOUT_S = float(S3_ENV.get("S3__TIMEOUT_SECONDS", "1")) +# раунды: скачивания, простой дольше срока вызова S3, загрузки +IDLE_ROUNDS = 8 +IDLE_DOWNLOADS = 10 +IDLE_UPLOADS = 12 +IDLE_EXTRA_S = 0.5 +# медленный клиент: пауза после каждого блока 64 KiB +IDLE_READ_PAUSE_S = 0.002 + + +def assert_s3_stand() -> None: + """Без этого окружения API с коротким сроком S3 тест ничего не + доказывает: простой 1,5 с был бы короче срока вызова.""" + assert S3_ENV == EXPECTED_S3_ENV, ( + f"short S3 timeout stand started with {S3_ENV}, " + f"expected {EXPECTED_S3_ENV}" + ) + + +@pytest.mark.spec("attachments", "Загрузка после простоя S3") +def test_upload_after_idle_s3( + s3_api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Скачивания большого оригинала, простой S3 дольше срока вызова, + затем загрузки — каждая 201, ни одной 503. + + Раунд: 10 одновременных медленных скачиваний (своё соединение у + каждого клиента, барьер, 2 мс на блок 64 KiB) PNG ~4 MiB, простой + `S3__TIMEOUT_SECONDS + 0,5` с без запросов к этому API, 12 загрузок + `sample.png` по одной: пул клиента S3 отдаёт соединения по порядку + возврата, и 12 вызовов проходят через все ≤ 10 его соединений. + + До правки клиента (срок чтения aiohttp, переживший ответ) соединение + портится в раунде с p ≈ 0,28 (design, «Как подтверждено», п. 8): + промах раунда — 0,72^10 ≈ 0,037, восьми раундов — ≈ 4e-12. После + правки 8 раундов — ~16 с. + """ + assert_s3_stand() + base_url = str(s3_api.client.base_url) + original = images.png_noise(1024, 1365, seed=4) + attachment = s3_api.upload( + alice, + chat["id"], + original, + filename="idle-original.png", + ) + sample = images.sample_png() + + def download(barrier: threading.Barrier) -> httpx.Response: + with Api(base_url, timeout=THREAD_CLIENT_TIMEOUT_S) as own: + # соединение открыто до барьера: после него сразу скачивание + own.request("GET", "/health/live") + barrier.wait() + return own.attachment_content_slowly( + alice, + attachment["id"], + pause_s=IDLE_READ_PAUSE_S, + ) + + for round_number in range(1, IDLE_ROUNDS + 1): + barrier = threading.Barrier(IDLE_DOWNLOADS) + with ThreadPoolExecutor(max_workers=IDLE_DOWNLOADS) as pool: + downloads = list( + pool.map(download, [barrier] * IDLE_DOWNLOADS), + ) + for resp in downloads: + assert_content(resp, original, "image/png") + time.sleep(SHORT_S3_TIMEOUT_S + IDLE_EXTRA_S) + for upload_number in range(1, IDLE_UPLOADS + 1): + resp = upload_raw(s3_api, alice, chat, sample) + assert resp.status_code == 201, describe( + resp, + f"round {round_number}, upload {upload_number} after " + f"{SHORT_S3_TIMEOUT_S + IDLE_EXTRA_S:.1f}s of S3 idle", + ) + assert_ok(resp, 201, "Attachment") + + # --------------------------------------------------------------------------- # Сверка bucket и БД (change track2-reconciler, design, решение 11). Hook # вносит расхождения с обеих сторон и запускает разовую сверку; плановая