09 Pipeline - dicechess-sync

🔄 ETL Pipeline: dicechess-sync

dicechess-sync — это приватный сервис сбора и очистки данных (ETL), предназначенный для исторического импорта (backfill) сыгранных партий с официального сайта dicechess.com, их нормализации и синхронизации с базой данных dicechess-analytics.

IMPORTANT

Причина приватности репозитория:
Репозиторий содержит обратную разработку (reverse engineering) приватного API dicechess.com. На сайте нет публичного разрешения на автоматический сбор данных, поэтому все детали скрейпинга и обхода защиты вынесены в приватный контур. Публичные проекты (dicechess-analytics, dicechess-engine-scala) остаются полностью независимыми и чистыми от специфики API dicechess.com.

---

1. Архитектурные границы проекта

Сервис работает как мост между закрытым веб-клиентом и нашей открытой аналитической платформой.

graph TD
    subgraph dicechess.com [dicechess.com (Внешний ресурс)]
        API[Private API]
    end

    subgraph Private_Pipeline [dicechess-sync (Приватный контур)]
        direction TB
        Crawler[Crawler Daemon / Crawl Service]
        SQLite[(Local SQLite Cache)]
    end

    subgraph Public_Analytics [dicechess-analytics (Публичный контур)]
        Ingest[POST /api/games Ingest API]
        Postgres[(PostgreSQL Analytical DB)]
        Engine[Scala 3 Engine Validation]
    end

    subgraph Backup_Storage [Dexus Home Server (Архив)]
        DexusArchive[(dicechess-raw-archive)]
    end

    %% Взаимодействия
    API -->|1. Raw JSON (jwt auth)| Crawler
    Crawler <-->|2. Read/Write Catalog & Blobs| SQLite
    Crawler -->|3. GameIngestWire (token auth)| Ingest
    Ingest -->|4. Replay & Validate| Engine
    Ingest -->|5. Write Games & FENs| Postgres
    Crawler -->|6. Mirror Raw Cache| DexusArchive

---

2. Локальное хранилище данных (SQLite)

Локальная база данных SQLite работает по принципу Bronze-слоя (хранилище сырых неизмененных ответов API). Это критически важное архитектурное решение:

TIP

Преимущество сырого кэша:
Поскольку правила парсинга ходов, расчета FEN и проверки на стороне движка постоянно дорабатываются, мы можем полностью переписать парсер/нормализатор ходов и пересчитать всю историю игр локально, не делая ни одного повторного запроса к защищенному сайту.

Таблицы базы данных:

erDiagram
    players {
        integer user_id PK "DiceChess ID"
        text username
        text player_type "human | bot | guest"
        integer rating_classic
        integer rating_x2
        integer priority "Max known rating"
        text sync_status "pending | in_progress | synced | error"
        integer enumerate_offset "Pagination cursor"
        integer synced_through_ms "StartTime cursor"
    }

    games {
        text game_id PK "UUID"
        text status "discovered | fetched | posted | rejected | error"
        integer white_user_id "FK to players"
        integer black_user_id "FK to players"
        integer started_at_ms "Unix timestamp"
        integer allow_doubling "0/1 (classic/x2)"
        integer is_cancelled
        text post_result "created | exists"
    }

    raw_game_data {
        text game_id PK "FK to games"
        text history_meta_json "Metadata from player history"
        text move_history_json "Verbatim response from game-move-history"
        text move_history_fetched_at
        text archived_at "Timestamp of dexus mirror"
    }

    games ||--o| raw_game_data : "has raw"

---

3. Машины состояний (State Machines)

Для надежной обработки сбоев сети, ошибок валидации движка и блокировок API, процессы краулинга игроков и обработки игр разделены на две независимые машины состояний.

3.1. Жизненный цикл партии (Games)

stateDiagram-v2
    [*] --> Discovered : Player history enumeration
    Discovered --> Fetched : Fetch game-move-history API
    Discovered --> Error_Fetch : Network / Auth Failure (Retry)
    Error_Fetch --> Discovered : Backoff timer expired
    
    Fetched --> Posted : POST 201 Created / 200 Exists (Ingested)
    Fetched --> Rejected : POST 422 Unprocessable (Invalid Moves)
    Fetched --> Error_Post : 5xx / Ingestion Timeout (Retry)
    Fetched --> Error_Normalize : Parse error / Bug in code
    
    Error_Post --> Fetched : Backoff timer expired
    Error_Normalize --> Fetched : Manual code-fix & DB update
    Rejected --> Fetched : Manual rebuild on Engine upgrade
    
    Posted --> [*]

3.2. Жизненный цикл краулинга игрока (Players)

stateDiagram-v2
    [*] --> Pending : Discovered via leaderboard or opponent BFS
    Pending --> In_Progress : Selected by rating priority
    In_Progress --> Synced : All historical pages parsed
    In_Progress --> Error : API blocks / Timeout (Retry)
    Error --> Pending : Backoff timer expired
    Synced --> Pending : Re-queued for incremental updates (START_DATE)

---

4. Конвейер обработки данных (The 5-Step Pipeline)

Процесс обработки каждой партии разделен на 5 изолированных шагов:

Шаг 1. Discover (Поиск игроков)

Поиск начинается с «семян» (Seeds): топ-200 игроков из классического лидерборда и лидерборда X2 (GET /api/leaderboard). Очередь BFS (обход в ширину) растет за счет добавления оппонентов из сыгранных партий. Приоритет обхода отдается игрокам с максимальным рейтингом.

Шаг 2. Enumerate (Сбор метаданных партий)

Для выбранного игрока постранично запрашивается его история (POST /api/player/history).

• Запрос возвращает метаданные партий (рейтинги игроков на момент игры, лимиты времени, результаты).
• Новые партии вносятся в таблицу games в статусе discovered.
• Оппоненты добавляются в таблицу players в статусе pending (если их там еще не было).

Шаг 3. Fetch Raw (Скачивание лога ходов)

Для партий в статусе discovered запрашивается детальный лог состояний доски (GET /api/game-move-history?gameId=...). Полученный тяжелый JSON-ответ сохраняется без изменений в таблицу raw_game_data, переводя игру в статус fetched.

Шаг 4. Normalize (Очистка и нормализация ходов)

Приватный API game-move-history возвращает не список ходов, а лог изменения состояний (gameMoveHistoryStateMap), который имеет ряд особенностей:

• Отсутствие четких границ ходов: один ход игрока складывается из нескольких записей — события броска кубиков и от 1 до 3 событий микро-ходов.
• Смешанный регистр фигур: цвет кодируется регистром букв в кубиках (P/N/B/R/Q/K — белые, p/n/b/r/q/k — черные).
• Служебные записи: состояние может содержать технические отметки (например, ожидание удвоения ставок или сдача партии).

Нормализатор преобразует этот лог в чистые ходы: брошенные кубики, координаты микро-ходов в стандартном формате и позиции доски.

Шаг 5. Post Ingest (Отправка в аналитику)

Сформированный JSON-пакет (GameIngestWire) отправляется на endpoint POST /api/games аналитического сервиса. Аналитический сервис повторно прокручивает ходы через официальный Scala-движок, проверяет их легальность, вычисляет контрольные суммы позиций (xxhash64) для дедупликации и записывает партию в боевую БД.

---

5. Защита от блокировок (Rate Limiting & Safety)

Постоянный скрейпинг исторического архива (сотни тысяч партий) легко может спровоцировать бан со стороны хостинга или Cloudflare. В dicechess-sync встроена многоуровневая защита:

1. Single-flight Queue: Все внешние запросы к сайту строго последовательны. Запросы никогда не выполняются параллельно с одного JWT-токена.
2. Случайный Jitter: Между запросами выдерживается случайная пауза (джиттер) от 1 до 3 секунд для имитации человеческого поведения.
3. Обнаружение Cloudflare Challenge: Если API начинает отдавать страницу с проверкой капчи или 403 Forbidden, краулер немедленно останавливается, отправляя уведомление администратору, вместо того чтобы перегружать домен запросами.
4. Exponential Backoff: При сетевых ошибках или 429 Too Many Requests время ожидания до повторного запроса увеличивается экспоненциально (до нескольких часов).

---

6. Зеркалирование архива (Archiving)

Параллельно основному конвейеру работает независимый фоновый поток архивации. Он считывает сырые данные из таблицы raw_game_data и зеркалирует их на центральный сервер бэкапов dexus в базу dicechess-raw-archive. Это обеспечивает 100% сохранность истории игр проекта на случай утери локального диска или поломки контейнера.