"""Согласованность PostgreSQL (метаданные) и S3 (байты): сборка мусора и сверка. lab5: префиксы бакета staging/ — принятый оригинал до обработки (API); final//original — опубликованный оригинал (worker); final//p<версия>/<вариант>. — варианты (worker); originals/ — оригиналы lab4 (до перехода на lab5). Строка pending ссылается на staging_key (объект появляется ПОСЛЕ строки). Добавлен проход D — очистка staging: ready-вложения (staging больше не нужен, результат опубликован) и failed старше STAGING_RETENTION_SECONDS (после этого replay невозможен — нужен повторный upload). Текущую работу (queued/processing) сборщик не трогает никогда. Почему неучтённых объектов «навсегда» не бывает (подробно — REPORT.md): загрузка: [1] INSERT attachments(state=pending, object_key) COMMIT [2] S3 PUT object_key [3] UPDATE state=ready WHERE state=pending COMMIT -> 201 Ключ объекта записан в БД ДО того, как объект появится в бакете. Сбой/обрыв между шагами: после [1] -> строка pending без объекта; после [2] -> строка pending + объект (S3 прошёл, COMMIT [3] — нет); ошибка S3 в [2] -> API сам компенсирует: DELETE pending; ошибка БД в [3] -> API сам компенсирует: DELETE object (pending уберёт GC). Процесс может умереть в любой точке, поэтому компенсация в запросе — оптимизация, а гарантию даёт сборщик: A. stale pending: строки pending старше GRACE. Сначала строка удаляется (DELETE ... WHERE state='pending' RETURNING object_key — атомарный захват: если запрос всё-таки успел сделать [3], строка уже ready и не удаляется), затем удаляется объект. Если удаление объекта не удалось — объект стал «сиротой» и будет убран проходом B. B. orphan objects: объекты в бакете (префикс originals/), для ключа которых в БД нет строки, и LastModified старше GRACE. Строка всегда создаётся раньше объекта и после удаления не возрождается (ключ одноразовый), поэтому «нет строки» + «старше GRACE» = объект не принадлежит живой загрузке. C. missing objects: строки ready без объекта (или с другим размером) — только отчёт: восстановить байты нельзя, удалять метаданные автоматически опасно. GRACE (ATTACHMENT_GC_GRACE_SECONDS, по умолчанию 900 с, минимум 300 с) много больше самой долгой загрузки: чтение тела <= UPLOAD_READ_TIMEOUT_SECONDS (60 с) + проверка + S3 PUT (connect 2 с + read 10 с) x S3_MAX_ATTEMPTS (2). Строки ready и вложения, на которые ссылаются сообщения, сборщик не трогает никогда (FK message_attachments -> attachments ON DELETE RESTRICT). CLI (по умолчанию dry-run, ничего не меняет): python -m src.reconcile # отчёт python -m src.reconcile --apply # исправить A и B python -m src.reconcile --apply --grace-seconds 0 # только на учебном стенде """ import argparse import json import logging import time from datetime import datetime, timedelta, timezone from typing import Dict, List, Optional from psycopg_pool import ConnectionPool from .objectstore import ObjectStore, ObjectStoreUnavailable log = logging.getLogger("messenger.reconcile") OBJECT_PREFIX = "originals/" # lab4 STAGING_PREFIX = "staging/" FINAL_PREFIX = "final/" SCANNED_PREFIXES = (STAGING_PREFIX, FINAL_PREFIX, OBJECT_PREFIX) GC_LOCK_ID = 2026_0004 BATCH = 500 def _try_lock(conn) -> bool: return conn.execute("SELECT pg_try_advisory_lock(%s)", (GC_LOCK_ID,)).fetchone()[0] def _unlock(conn) -> None: conn.execute("SELECT pg_advisory_unlock(%s)", (GC_LOCK_ID,)) def collect_stale_pending(pool: ConnectionPool, store: ObjectStore, grace_seconds: int, apply: bool, report: Dict) -> None: """Проход A. dry-run: только подсчёт; apply: строка -> затем объект.""" with pool.connection() as conn: rows = conn.execute( """ SELECT id, COALESCE(staging_key, object_key) FROM attachments WHERE state = 'pending' AND created_at < clock_timestamp() - make_interval(secs => %s) ORDER BY created_at LIMIT %s """, (grace_seconds, BATCH), ).fetchall() report["stale_pending"] = len(rows) report["stale_pending_ids"] = [str(r[0]) for r in rows[:20]] if not apply: return deleted_rows = deleted_objects = 0 for att_id, _key in rows: with pool.connection() as conn: claimed = conn.execute( """ DELETE FROM attachments WHERE id = %s AND state = 'pending' AND created_at < clock_timestamp() - make_interval(secs => %s) RETURNING COALESCE(staging_key, object_key) """, (att_id, grace_seconds), ).fetchone() if claimed is None: continue # загрузка успела завершиться (ready) — не трогаем deleted_rows += 1 try: store.delete(claimed[0]) deleted_objects += 1 except ObjectStoreUnavailable: # Объект стал сиротой без строки; его уберёт проход B. log.warning("gc: object delete deferred to orphan sweep") report["stale_pending_rows_deleted"] = deleted_rows report["stale_pending_object_deletes"] = deleted_objects def known_keys(pool: ConnectionPool, keys: List[str]) -> set: """Ключи, на которые ссылается БД: оригинал, staging или вариант.""" with pool.connection() as conn: rows = conn.execute( """ SELECT object_key FROM attachments WHERE object_key = ANY(%s) UNION SELECT staging_key FROM attachments WHERE staging_key = ANY(%s) UNION SELECT object_key FROM attachment_variants WHERE object_key = ANY(%s) """, (keys, keys, keys), ).fetchall() return {r[0] for r in rows} def clean_staging(pool: ConnectionPool, store: ObjectStore, retention_seconds: int, apply: bool, report: Dict) -> None: """Проход D: staging, который больше не нужен. Строка обновляется ПОСЛЕ удаления объекта; сбой между шагами безопасен (повторное удаление отсутствующего — no-op).""" with pool.connection() as conn: rows = conn.execute( """ SELECT id, staging_key, state FROM attachments WHERE staging_key IS NOT NULL AND (state = 'ready' OR (state = 'failed' AND updated_at < clock_timestamp() - make_interval(secs => %s))) ORDER BY updated_at LIMIT %s """, (retention_seconds, BATCH), ).fetchall() report["staging_to_clean"] = len(rows) if not apply: return cleaned = 0 for att_id, key, state in rows: try: store.delete(key) except ObjectStoreUnavailable: log.warning("gc: staging delete deferred") break with pool.connection() as conn: conn.execute("UPDATE attachments SET staging_key = NULL WHERE id = %s AND staging_key = %s " "AND state = %s", (att_id, key, state)) cleaned += 1 report["staging_cleaned"] = cleaned def sweep_orphans(pool: ConnectionPool, store: ObjectStore, grace_seconds: int, apply: bool, report: Dict, verify_ready: bool = True) -> None: """Проходы B и C: полный обход префикса бакета страницами по 1000.""" cutoff = datetime.now(timezone.utc) - timedelta(seconds=grace_seconds) token: Optional[str] = None listed = orphans = orphans_young = deleted = 0 seen_keys: List[str] = [] orphan_sample: List[str] = [] started = time.monotonic() for prefix in SCANNED_PREFIXES: token = None while True: items, token = store.list_page(prefix, token) listed += len(items) if items: keys = [k for k, _, _ in items] known = known_keys(pool, keys) for key, modified, _size in items: if key in known: if verify_ready: seen_keys.append(key) continue orphans += 1 if modified > cutoff: orphans_young += 1 # возможно, живая загрузка/обработка или ещё не истёк grace continue if len(orphan_sample) < 20: orphan_sample.append(key) if apply and not known_keys(pool, [key]): # Повторная проверка непосредственно перед удалением. store.delete(key) deleted += 1 if not token: break report["objects_listed"] = listed report["orphan_objects"] = orphans report["orphan_objects_within_grace"] = orphans_young report["orphan_objects_sample"] = orphan_sample if apply: report["orphan_objects_deleted"] = deleted report["bucket_scan_seconds"] = round(time.monotonic() - started, 3) if verify_ready: # C: ready-строки, для которых объекта нет в листинге (или не тот размер). present = set(seen_keys) with pool.connection() as conn: rows = conn.execute( "SELECT id, object_key, size_bytes FROM attachments WHERE state = 'ready' " "UNION ALL SELECT attachment_id, object_key, size_bytes FROM attachment_variants" ).fetchall() missing = [str(r[0]) for r in rows if r[1] not in present] report["ready_rows"] = len(rows) report["missing_objects"] = len(missing) report["missing_object_ids"] = missing[:20] def run_once(pool: ConnectionPool, store: ObjectStore, grace_seconds: int, apply: bool, orphan_sweep: bool = True, staging_retention_seconds: int = 86400) -> Optional[Dict]: """Один проход под advisory lock. None — сейчас работает другая реплика.""" report: Dict = {"mode": "apply" if apply else "dry-run", "grace_seconds": grace_seconds} with pool.connection() as lock_conn: lock_conn.autocommit = True if not _try_lock(lock_conn): return None try: collect_stale_pending(pool, store, grace_seconds, apply, report) clean_staging(pool, store, staging_retention_seconds, apply, report) if orphan_sweep: sweep_orphans(pool, store, grace_seconds, apply, report) finally: _unlock(lock_conn) # Соединение вернётся в общий пул — режим транзакций как у остальных. lock_conn.autocommit = False return report def gc_loop(pool: ConnectionPool, store: ObjectStore, settings, stop) -> None: """Фон в каждой реплике: проход A каждые N с, проход B — реже. Lock — одна реплика.""" import os # lab7: у API нет права List и записи в final/ (least privilege S3) — полный обход # бакета (проход B/C) выполняет только worker (ORPHAN_SWEEP_ENABLED=false у API). sweep_enabled = os.environ.get("ORPHAN_SWEEP_ENABLED", "true").strip().lower() != "false" last_sweep = time.monotonic() while not stop.wait(settings.attachment_gc_interval_seconds): try: sweep = sweep_enabled and time.monotonic() - last_sweep >= settings.orphan_sweep_interval_seconds report = run_once(pool, store, settings.attachment_gc_grace_seconds, apply=True, orphan_sweep=sweep, staging_retention_seconds=settings.staging_retention_seconds) if report is None: continue if sweep: last_sweep = time.monotonic() if report.get("stale_pending") or report.get("orphan_objects_deleted") or report.get("missing_objects") \ or report.get("staging_cleaned"): log.info("attachment gc: %s", json.dumps(report, ensure_ascii=False)) except Exception as exc: # БД/S3 недоступны — следующий проход повторит log.warning("attachment gc skipped: %s", type(exc).__name__) def main() -> None: parser = argparse.ArgumentParser(description="Reconcile attachments metadata (PostgreSQL) with S3 objects") parser.add_argument("--apply", action="store_true", help="delete stale pending rows and orphan objects") parser.add_argument("--grace-seconds", type=int, default=None, help="override ATTACHMENT_GC_GRACE_SECONDS (values < 300 only for lab tests)") parser.add_argument("--no-orphan-sweep", action="store_true", help="skip bucket listing") args = parser.parse_args() logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s %(message)s") from .config import load_settings from .db import create_pool settings = load_settings() if not ObjectStore.configured(settings): raise SystemExit("S3 is not configured") grace = settings.attachment_gc_grace_seconds if args.grace_seconds is None else args.grace_seconds pool = create_pool(settings) pool.wait(timeout=15) store = ObjectStore(settings) try: started = time.monotonic() report = run_once(pool, store, grace, args.apply, orphan_sweep=not args.no_orphan_sweep, staging_retention_seconds=settings.staging_retention_seconds) if report is None: raise SystemExit("another reconciler holds the lock; retry later") report["total_seconds"] = round(time.monotonic() - started, 3) print(json.dumps(report, ensure_ascii=False, indent=2)) finally: pool.close() if __name__ == "__main__": main()