feat: add reconcile strategies, deep check, rate limit and cost profile

- reconcile --strategy head, --deep (checksum_mismatch), restore needs the same SHA-256
- [reconciler] max_objects_per_second (2000), pause interrupted by signal
- --apply stops rechecks once the limit is exceeded (unchecked)
- pass cost in the summary: S3 objects and requests, bytes, DB sessions, phases
- S3 client counters, cleaner exits with os._exit after main()
- fault tests, hook args, driver reconcile-signal --pace
- bench profile reconcile / reconcile_quick: fill outside the API, gateway metrics, background load
- sync spec deltas, rules, AGENTS.md, PLAN.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-23 04:52:56 +03:00
co-authored by Claude Opus 5.5
parent dcdfe5f2e4
commit 8d4cf7eebf
41 changed files with 5344 additions and 441 deletions
+11 -1
View File
@@ -30,4 +30,14 @@ if __name__ == "__main__":
)
sys.exit(2)
sys.exit(main())
code = main()
# engine и клиент S3 закрыты, «Stopped cleaner» записан: выход без
# финализации интерпретатора. При 0,25 CPU она длится 0,8–1,5 с (модули
# botocore, SQLAlchemy), и остановка по сигналу во время паузы предела
# скорости не укладывалась бы в секунду (design change
# track2-reconcile-cost, «Уточнения apply», п. 14)
import os
sys.stdout.flush()
sys.stderr.flush()
os._exit(code)
+72 -9
View File
@@ -1,8 +1,10 @@
"""Уборщик незавершённых загрузок и сверка bucket и БД.
`python -m src.cleaner [--once]` — сервис уборки; `python -m src.cleaner
reconcile [--apply] [--max-changes N]` — разовая сверка, по умолчанию
dry-run (design change `track2-reconciler`, решение 1).
reconcile [--apply] [--max-changes N] [--strategy batch|head] [--deep]
[--max-objects-per-second R]` — разовая сверка, по умолчанию dry-run
(design change `track2-reconciler`, решение 1; стратегия, глубина и
предел скорости — design change `track2-reconcile-cost`, решения 4–6).
Отдельный процесс стенда, а не задача реплик API (design change
`upload-consistency`, решения 2, 4, 5). Свои engine (пул из
@@ -23,6 +25,7 @@ dry-run (design change `track2-reconciler`, решение 1).
import argparse
import asyncio
import math
import signal
from contextlib import AbstractAsyncContextManager, suppress
from datetime import timedelta
@@ -42,6 +45,7 @@ from src.infra.db.scope import session_scope
from src.infra.logger import AbstractLogger, get_logger
from src.infra.s3 import create_object_storage
from src.schemas import dataclasses
from src.schemas.enums import ReconcileStrategy
from src.utils.utc import utcnow
logger: AbstractLogger = get_logger().bind(module="cleaner")
@@ -77,6 +81,16 @@ def _positive_int(value: str) -> int:
return number
def _non_negative_float(value: str) -> float:
try:
number = float(value)
except ValueError:
raise argparse.ArgumentTypeError("must be a number") from None
if not math.isfinite(number) or number < 0:
raise argparse.ArgumentTypeError("must be a non-negative number")
return number
def _parse_args(argv: list[str] | None) -> argparse.Namespace:
parser = argparse.ArgumentParser(
prog="python -m src.cleaner",
@@ -105,6 +119,25 @@ def _parse_args(argv: list[str] | None) -> argparse.Namespace:
default=None,
help="change limit of the pass (default: [reconciler] max_changes)",
)
reconcile.add_argument(
"--strategy",
choices=[item.value for item in ReconcileStrategy],
default=ReconcileStrategy.BATCH.value,
help="batch: list pages and one database query per page; head: a "
"database query per object and HEAD per ready row",
)
reconcile.add_argument(
"--deep",
action="store_true",
help="read objects and compare their SHA-256 with the metadata",
)
reconcile.add_argument(
"--max-objects-per-second",
type=_non_negative_float,
default=None,
help="S3 objects per second, 0 - no limit "
"(default: [reconciler] max_objects_per_second)",
)
return parser.parse_args(argv)
@@ -115,11 +148,10 @@ def main(argv: list[str] | None = None) -> int:
run(
mode=MODE_RECONCILE,
apply=args.apply,
max_changes=(
settings.reconciler.max_changes
if args.max_changes is None
else args.max_changes
),
max_changes=args.max_changes,
strategy=ReconcileStrategy(args.strategy),
deep=args.deep,
max_objects_per_second=args.max_objects_per_second,
),
)
return asyncio.run(run(mode=MODE_ONCE if args.once else MODE_SERVICE))
@@ -130,12 +162,24 @@ async def run(
mode: str,
apply: bool = True,
max_changes: int | None = None,
strategy: ReconcileStrategy = ReconcileStrategy.BATCH,
deep: bool = False,
max_objects_per_second: float | None = None,
) -> int:
"""Проверка grace, затем проходы уборки до сигнала (или один с
`--once`) с плановой сверкой — или одна разовая сверка."""
`--once`) с плановой сверкой — или одна разовая сверка. Стратегия и
глубина — только у разовой сверки; плановая — `batch`, поверхностная,
предел скорости из настроек (design change `track2-reconcile-cost`,
решения 4–6)."""
cleaner = settings.cleaner
reconciler = settings.reconciler
limit = reconciler.max_changes if max_changes is None else max_changes
rate = (
reconciler.max_objects_per_second
if max_objects_per_second is None
else max_objects_per_second
)
once_pass = mode == MODE_RECONCILE
bound = live_upload_bound_seconds(settings)
if cleaner.pending_grace_seconds <= bound:
# до engine и клиента S3: ни одного обращения к хранилищам
@@ -193,7 +237,10 @@ async def run(
reconcile_interval_seconds=reconciler.interval_seconds,
reconcile_page_size=reconciler.page_size,
reconcile_max_changes=limit,
reconcile_apply=apply if mode == MODE_RECONCILE else None,
reconcile_max_objects_per_second=rate,
reconcile_apply=apply if once_pass else None,
reconcile_strategy=strategy.value if once_pass else None,
reconcile_deep=deep if once_pass else None,
database_host=settings.database.host,
database_port=settings.database.port,
database_name=settings.database.name,
@@ -207,6 +254,9 @@ async def run(
reconcile,
apply=apply,
max_changes=limit,
strategy=strategy,
deep=deep,
max_objects_per_second=rate,
stop=stop,
)
exit_code = _reconcile_exit_code(result)
@@ -255,10 +305,17 @@ async def _serve(
pause = cleaner.interval_seconds
if next_reconcile is not None and not stop.is_set():
if loop.time() >= next_reconcile:
# плановая — стратегия по умолчанию, поверхностная, пределы
# из настроек
await _reconcile_once(
reconcile,
apply=True,
max_changes=settings.reconciler.max_changes,
strategy=ReconcileStrategy.BATCH,
deep=False,
max_objects_per_second=(
settings.reconciler.max_objects_per_second
),
stop=stop,
)
next_reconcile = loop.time() + interval
@@ -296,6 +353,9 @@ async def _reconcile_once(
*,
apply: bool,
max_changes: int,
strategy: ReconcileStrategy,
deep: bool,
max_objects_per_second: float,
stop: asyncio.Event,
) -> dataclasses.ReconcilePassDTO | None:
"""Проход сверки; `None` — непредвиденная ошибка: `error` с
@@ -310,6 +370,9 @@ async def _reconcile_once(
max_changes=max_changes,
page_size=settings.reconciler.page_size,
batch_size=settings.cleaner.batch_size,
strategy=strategy,
deep=deep,
max_objects_per_second=max_objects_per_second,
stop_requested=stop.is_set,
)
except Exception as e:
+4
View File
@@ -280,6 +280,10 @@ class Reconciler(BaseModel):
page_size: int = Field(default=1000, ge=1, le=1000)
# предел изменений за проход: больше — ни одного изменения и код 3
max_changes: int = Field(default=100, ge=1)
# предел скорости прохода: объектов S3 в секунду в среднем от начала
# прохода (ключи страниц списка, HEAD, GET, DELETE); 0 — без предела
# (design change `track2-reconcile-cost`, решение 6)
max_objects_per_second: float = Field(default=2000.0, ge=0)
class Settings(BaseSettings):
File diff suppressed because it is too large Load Diff
+2
View File
@@ -1,5 +1,6 @@
from src.infra.s3.client import (
ObjectStorage,
StorageStats,
StoredObject,
StoredObjectInfo,
StoredObjectPage,
@@ -8,6 +9,7 @@ from src.infra.s3.client import (
__all__ = [
"ObjectStorage",
"StorageStats",
"StoredObject",
"StoredObjectInfo",
"StoredObjectPage",
+51 -3
View File
@@ -26,6 +26,13 @@ bucket и БД процессом уборщика (design change `track2-reconc
решение 3): страница — один вызов со сроком, нет bucket — ошибка, а не
пустая страница.
Счётчики клиента (design change `track2-reconcile-cost`, решение 8):
попытки вызовов по операциям (`list`, `head`, `get`, `delete`, `put` —
считаются до вызова, в том числе неудачные), ключи страниц списка и
прочитанные байты объектов. `stats()` отдаёт неизменяемый снимок
`StorageStats`; стоимость прохода сверка считает разностью снимков.
Поведение вызовов, сроки и перевод ошибок от счётчиков не зависят.
В журнал — адрес, bucket, ключ объекта, размер, длительность и класс
ошибки; ключей доступа, секрета и подписи там нет. Логгеры botocore,
aiobotocore и aiohttp стоят на WARNING (`src/infra/logger.py`): на DEBUG
@@ -34,10 +41,12 @@ botocore пишет заголовки с подписью.
import asyncio
import time
from collections.abc import AsyncIterator
from collections import Counter
from collections.abc import AsyncIterator, Mapping
from contextlib import AsyncExitStack, asynccontextmanager
from dataclasses import dataclass
from datetime import datetime
from types import MappingProxyType
from typing import Any, BinaryIO
import aiohttp
@@ -88,12 +97,33 @@ TRANSLATED_ERRORS: tuple[type[Exception], ...] = (
)
# размер блока чтения объекта по умолчанию
DEFAULT_CHUNK_BYTES = 64 * 1024
# имя операции botocore → имя в счётчиках клиента
OPERATION_NAMES = MappingProxyType(
{
"list_objects_v2": "list",
"head_object": "head",
"get_object": "get",
"delete_object": "delete",
"put_object": "put",
},
)
@dataclass(frozen=True, slots=True)
class StorageStats:
"""Снимок счётчиков клиента с его создания: `calls` — попытки вызовов
по операциям (`list`, `head`, `get`, `delete`, `put`), `listed_keys` —
ключи страниц списка, `read_bytes` — прочитанные байты объектов."""
calls: Mapping[str, int]
listed_keys: int
read_bytes: int
@dataclass(frozen=True, slots=True)
class StoredObjectInfo:
"""Метаданные объекта в bucket. `last_modified` — время записи по часам
S3 (точность — секунда), из списка и HEAD; у `open` его нет."""
S3 (точность — секунда), из списка, HEAD и GET."""
key: str
size: int
@@ -176,6 +206,19 @@ class ObjectStorage:
self._client: Any = None
self._exit_stack: AsyncExitStack | None = None
self._lock = asyncio.Lock()
self._calls: Counter[str] = Counter()
self._listed_keys = 0
self._read_bytes = 0
def stats(self) -> StorageStats:
"""Неизменяемый снимок счётчиков клиента с его создания."""
return StorageStats(
calls=MappingProxyType(
{name: self._calls[name] for name in OPERATION_NAMES.values()},
),
listed_keys=self._listed_keys,
read_bytes=self._read_bytes,
)
async def start(self) -> None:
"""Создать клиент заранее, при старте процесса."""
@@ -244,6 +287,7 @@ class ObjectStorage:
if token is not None:
params["ContinuationToken"] = token
response = await self._call("list_objects_v2", None, **params)
self._listed_keys += len(response.get("Contents", ()))
objects = tuple(
StoredObjectInfo(
key=item["Key"],
@@ -273,6 +317,7 @@ class ObjectStorage:
key=key,
size=response["ContentLength"],
content_type=response.get("ContentType"),
last_modified=response.get("LastModified"),
)
try:
yield StoredObject(info, body, self)
@@ -342,6 +387,7 @@ class ObjectStorage:
"""Вызов клиента со сроком и переводом ошибок. `key=None` — вызов
над bucket без ключа (список), в журнал тогда — `prefix`."""
client = await self._get_client()
self._calls[OPERATION_NAMES.get(operation, operation)] += 1
started = time.monotonic()
if key is not None:
params["Key"] = key
@@ -383,7 +429,7 @@ class ObjectStorage:
started = time.monotonic()
try:
async with asyncio.timeout(self._timeout_seconds):
return await body.read(chunk_bytes)
chunk = await body.read(chunk_bytes)
except TRANSLATED_ERRORS as e:
failure = self._failure(
e,
@@ -394,6 +440,8 @@ class ObjectStorage:
if failure is None:
raise
raise failure from e
self._read_bytes += len(chunk)
return chunk
def _failure(
self,
+33 -3
View File
@@ -1,9 +1,19 @@
from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
from dataclasses import dataclass
from dataclasses import dataclass, field
from datetime import datetime
from types import MappingProxyType
from uuid import UUID
from src.schemas.enums import AttachmentStatus, ImageType, ReconcileFinding
from src.schemas.enums import (
AttachmentStatus,
ImageType,
ReconcileFinding,
ReconcileStrategy,
)
def _empty_mapping() -> Mapping[str, int]:
return MappingProxyType({})
@dataclass(frozen=True, slots=True)
@@ -65,7 +75,9 @@ class ReconcileFindingDTO:
`attachment_id` — если известен (из ключа или строки), `age_seconds` —
возраст объекта (`LastModified`) или строки (`updated_at` у ready,
`created_at` у pending). `size_bytes` и `stored_size` — размеры строки и
объекта, если известны оба.
объекта, если известны оба. `sha256` — SHA-256 оригинала из строки:
по нему перепроверка и действие сверяют прочитанный объект (design
change `track2-reconcile-cost`, решение 5); в журнал не попадает.
"""
kind: ReconcileFinding
@@ -74,6 +86,7 @@ class ReconcileFindingDTO:
age_seconds: int
size_bytes: int | None = None
stored_size: int | None = None
sha256: bytes | None = None
@dataclass(frozen=True, slots=True)
@@ -86,6 +99,14 @@ class ReconcilePassDTO:
сколько расхождений не записано отдельными записями,
`interrupted_by` — причина прерывания (`object_storage`, `database`,
`stop`) или `None`.
Стоимость прохода (design change `track2-reconcile-cost`, решения 8 и
15): `strategy`, `deep` и `max_objects_per_second` (0 — без предела);
`storage_objects` — затронутые объекты S3 (ключи страниц списка, HEAD,
GET, DELETE), `s3_requests` — вызовы S3 по операциям, `read_bytes` —
прочитанные байты объектов, `db_sessions` — сеансы с PostgreSQL,
`unchecked` — кандидаты, которых `--apply` не перепроверял после
решённого отказа по пределу, `phase_ms` — длительность шагов прохода.
"""
apply: bool
@@ -101,6 +122,15 @@ class ReconcilePassDTO:
unlogged: int
interrupted_by: str | None
duration_ms: int
strategy: ReconcileStrategy = ReconcileStrategy.BATCH
deep: bool = False
max_objects_per_second: float = 0
storage_objects: int = 0
s3_requests: Mapping[str, int] = field(default_factory=_empty_mapping)
read_bytes: int = 0
db_sessions: int = 0
unchecked: int = 0
phase_ms: Mapping[str, int] = field(default_factory=_empty_mapping)
@dataclass(frozen=True, slots=True)
+2
View File
@@ -3,6 +3,7 @@ from .attachment import (
ImageType,
ReconcileAction,
ReconcileFinding,
ReconcileStrategy,
)
from .settings import RunModeEnum
@@ -11,5 +12,6 @@ __all__ = [
"ImageType",
"ReconcileAction",
"ReconcileFinding",
"ReconcileStrategy",
"RunModeEnum",
]
+15
View File
@@ -38,6 +38,21 @@ class ReconcileFinding(StrEnum):
# ключ под префиксом вложений, которого API не пишет, или ключ строки
# другого вида
UNKNOWN_OBJECT = "unknown_object"
# строка ready, объект того же размера, а SHA-256 содержимого другой;
# ищет только глубокая сверка (design change `track2-reconcile-cost`,
# решение 5)
CHECKSUM_MISMATCH = "checksum_mismatch"
class ReconcileStrategy(StrEnum):
"""Стратегия обхода сверки (design change `track2-reconcile-cost`,
решение 4). `batch` — страница списка и одно выражение к БД на
страницу, ключи списка в множестве; `head` — выборка строки на объект
списка и HEAD на строку `ready`, без множества. Плановая сверка — только
`batch`."""
BATCH = "batch"
HEAD = "head"
class ReconcileAction(StrEnum):
+4
View File
@@ -83,6 +83,10 @@ ATTACHMENT_ORIGINAL_SUFFIX = "original"
# записями журнала; остальные — только числом в итоге (design change
# `track2-reconciler`, решение 8)
RECONCILE_FINDINGS_LOGGED_MAX = 1000
# пауза предела скорости сверки — кусками не дольше этого, с проверкой
# сигнала между ними: остановка не ждёт конца паузы (design change
# `track2-reconcile-cost`, решение 6)
RECONCILE_PACE_STEP_SECONDS = 0.2
# секунды в Retry-After ответа 429, когда места загрузки процесса заняты:
# за секунду реплика доводит несколько загрузок (7–8,5 по 10 MiB), а повтор
# через LB уходит на следующую реплику (design change `upload-memory`,