test: add idle S3 upload fault check on a short S3 timeout API

Fourth API of the failure stand (S3__TIMEOUT_SECONDS=1), slow streamed
download in the test client, test_upload_after_idle_s3 and the
fix-upload-put-flake spec deltas synced into the main specs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-23 01:05:00 +03:00
co-authored by Claude Opus 5.5
parent 7d4b2cb37e
commit 4cfaab0063
8 changed files with 223 additions and 22 deletions
@@ -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
+13
View File
@@ -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 за
+18
View File
@@ -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 нет
+9 -4
View File
@@ -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 проходить проверку границы живой
+34
View File
@@ -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,
+16 -1
View File
@@ -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
+25 -5
View File
@@ -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
+103 -7
View File
@@ -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
# вносит расхождения с обеих сторон и запускает разовую сверку; плановая