Příjem dat

Dokument je kontrakt, který musí implementace splnit — hlavička to říká rovnou: klient feedu zatím neexistuje. Popisuje smyčku, sedm invariantů a aritmetiku denního limitu, ze které plyne, jak rychle vůbec může backfill doběhnout.

Stav: plánováno — položky 1.1 až 1.4 fáze 1 nejsou zahájené
Vlastnictví feedu: právě jeden poller, Redis lease s TTL
Checkpoint: posune se jen ve stejné transakci jako zápis akcí
Limity: kontrolované před síťovým voláním, konfigurovatelné jen přísněji
Cíl zpoždění: událost zpracovaná do 24 hodin

Smyčka

Získej lease. Když ho drží někdo jiný, skonči — feed vlastní právě jeden proces.
Přečti checkpoint: id poslední trvale zpracované akce.
Zkontroluj rozpočet požadavků před odesláním; přes rozpočet se spí, ne posílá.
Stáhni dávku za checkpointem a naparsuj ji do typovaných akcí. Chybný tvar znamená fail closed a checkpoint se neposune.
Zapiš akce append-only a idempotentně podle id akce, ve stejné transakci posuň checkpoint.
Zařaď dokumentové úlohy pro akce, které odkazují dokument, a opakuj do vyčerpání dávky nebo limitu tiku.

Sedm invariantů a proč na nich záleží

Pravidlo	Proč
Feed vlastní právě jeden poller	souběžné pollery duplikují práci a závodí o checkpoint
Zápis akcí a posun checkpointu v jedné transakci	pád mezi tím buď znovu stáhne (bezpečné), nebo přeskočí (ztráta dat)
Zápisy jsou idempotentní podle id akce	znovu stažená dávka musí být no-op, ne duplikát
Checkpoint necouvá bez zásahu operátora	couvnutí je operace z runbooku, ne vedlejší efekt
Limity se kontrolují před odesláním požadavku	reagovat až na HTTP 429 je už porušení provozních podmínek
Chyba parsování nikdy neposune checkpoint	tiché přeskočení dávky je neviditelná ztráta dat
Akce se nikdy nemění ani nemažou	replika je zdroj pravdy; opravy patří na stranu projektoru

Backfill, živý provoz a jeden strop

Obojí obsluhuje stejná cesta kódem, liší se jen počáteční checkpoint. Živý provoz startuje na aktuální hladině a jede na cronu, backfill startuje na dolní hranici fáze (pro MVP 1. 1. 2018) a jede na denní rozpočet, dokud nedožene.

Aritmetika, kterou je nutné udělat před návrhem backfillu: 3000 požadavků denně při nabízené velikosti stránky je tvrdý strop rychlosti přehrání historie. Plán fázování v specifikaci existuje kvůli tomuhle číslu, ne navzdory jemu.

Backfill a živý provoz nesmí běžet současně proti témuž checkpointu. Buď doběhne backfill a živý provoz naváže, nebo mají oddělené checkpointy a lease — a to druhé si vyžádá ADR.

Přehrání a metriky

Přestavba projekce přehraje uložené akce od začátku. Nic nestahuje a nic znovu nevytěžuje, protože výsledky extrakce jsou v cache podle hashe dokumentu. Proto je přehrání běžná reakce na chybu v projektoru, ne krizová operace; postup je v runbooku.

Sledované metriky jsou zpoždění za rejstříkem, aktuální id checkpointu, průchodnost, důvody selhání ze zavřeného slovníku, stav breakeru a zbývající rozpočet požadavků. Žádný label nikdy nenese spisovou značku, jméno ani osobní údaj.

Kde to v repozitáři žije

docs/INGESTION.md — smyčka, invarianty, limity, backfill versus živý provoz, přehrání, metriky
docs/ISIR-SOURCE-SEMANTICS.md — publikované limity a fail-closed mapování stavů zdroje
docs/runbooks/replay.md — operátorský postup přehrání projekce
src/progresus_isir/config.py — publikované stropy a validace, že lokální limit smí být jen přísnější

Souvisí

Klient WS ISIR a limity

Plánováno

SOAP klient k IsirWsPublicService, typované parsování akcí, fail-closed mapování chybových stavů a limiter vynucený dřív, než požadavek opustí proces. Publikované stropy 50/min a 3000/den půjde nastavit jen přísněji, nikdy volněji.

Detail

Replika a checkpoint

Plánováno

Append-only log akcí, idempotentní zápis podle ID akce a checkpoint posouvaný ve stejné transakci jako zápis. Pád bude znamenat znovunačtení dávky, nikdy její přeskočení.

Detail

Event sourcing, protože zdroj je event stream

Systém je konzumentem oficiálního proudu událostí. Z něj staví lokální append-only repliku a z ní přehrává projekci aktuálního stavu. Oprava chyby v interpretaci znamená přehrát log, ne znovu stahovat rejstřík.

Detail

Zpět na sekci Dokumentace