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:
+11
-1
@@ -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
@@ -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:
|
||||
|
||||
@@ -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
@@ -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
@@ -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,
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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",
|
||||
]
|
||||
|
||||
@@ -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):
|
||||
|
||||
@@ -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`,
|
||||
|
||||
Reference in New Issue
Block a user