Livrare, outbox și recuperare — AiHummer Documentație

Când un tur se încheie, răspunsul tot trebuie să ajungă la canalul din care a venit — în mod fiabil și exact o singură dată. AiHummer gestionează acest lucru cu un outbox tranzacțional, efecte secundare idempotente și recuperarea turului după o repornire. O magistrală NATS opțională poate prelua livrarea pentru implementări mai mari.

Livrare garantată

Răspunsul nu este trimis în linie la finalul unui tur. În schimb, este pus în coadă în outbox ca parte a aceleiași lucrări care l-a produs, iar un worker de livrare îl preia și îl trimite către canalul de origine. Deoarece răspunsul este înregistrat durabil înainte de a pleca, o defecțiune între „răspuns produs“ și „răspuns trimis“ nu îl poate pierde — la repornire intrarea din outbox este încă acolo, iar livrarea se reia.

turn produces reply
   └─▶ enqueue in outbox (durable)
         └─▶ delivery worker ─▶ originating channel
               └─ acknowledged ─▶ marked delivered

Livrarea este împerecheată cu idempotența, astfel încât acest worker cel-puțin-o-dată să producă un comportament extern exact-o-dată: o cheie de registru stabilă la reluare și o barieră de efecte secundare asigură faptul că un răspuns relivrat sau reluat este trimis către canal o singură dată (vezi Multitenanță și idempotență).

[!NOTE] „Exact-o-dată“ descrie aici rezultatul vizibil în exterior: utilizatorul primește răspunsul o singură dată. Intern, workerul poate încerca livrarea de mai multe ori; stratul de idempotență comprimă aceste încercări într-o singură trimitere vizibilă.

Recuperarea turului după o repornire

Dacă gateway-ul repornește în mijlocul unui tur — o implementare, o defecțiune, o repornire a gazdei — lucrarea nu este abandonată. Recuperarea turului reia turul întrerupt astfel încât acesta să se poată finaliza. Acest lucru este sigur doar pentru că efectele secundare sunt idempotente: orice e-mail sau trimitere pe canal care s-a întâmplat deja înainte de repornire este recunoscut după cheia sa de registru și sărit, în timp ce părțile care nu s-au întâmplat rulează până la finalizare. Utilizatorul vede un singur răspuns complet, mai degrabă decât unul pe jumătate făcut sau un duplicat.

Magistrala NATS opțională

În mod implicit, livrarea funcționează în întregime prin PostgreSQL, ceea ce menține o implementare minimă la un singur gateway plus o bază de date. Pentru configurări mai mari sau cu mai multe gateway-uri, puteți pune livrarea pe o magistrală NATS configurându-i URL-ul:

# gateway.env
AIHUMMER_NATS_URL=nats://127.0.0.1:4222

Magistrala este cu adevărat opțională — lăsați AIHUMMER_NATS_URL nesetat și outbox-ul rulează fără ea. Când este prezentă, NATS devine transportul prin care circulă lucrarea de livrare, ceea ce se potrivește gateway-urilor scalate orizontal în spatele unui proxy.

[!TIP] Actualizările fără timp de nefuncționare rulează două sau mai multe gateway-uri în spatele unui reverse proxy. Programatorul rămâne cu un singur lider printr-un advisory lock Postgres, iar livrarea idempotentă înseamnă că gateway-urile suplimentare pot împărți sarcina fără a trimite ceva de două ori.

Ce trebuie monitorizat

Livrarea este locul în care apar primele probleme de fiabilitate, așa că este lucrul de monitorizat. AiHummer trimite telemetrie prin OTLP (AIHUMMER_OTEL_ENDPOINT) și livrează tablouri de bord Grafana; nu există un endpoint Prometheus /metrics de extras.

Dispozițiile de livrare — rezultatul fiecărei încercări de livrare. O rată în creștere a eșecurilor indică o problemă de canal sau din aval.
Adâncimea outbox — câte răspunsuri așteaptă să fie livrate. O creștere susținută înseamnă că livrarea rămâne în urmă.
Adâncimea DLQ — intrările care și-au epuizat reîncercările și au ajuns în coada de litere moarte. Orice creștere a DLQ merită investigată.

[!WARNING] Monitorizați acestea alături de latența turului și rata de erori. Un outbox sau un DLQ în creștere este un avertisment timpuriu că canalele din aval sunt degradate, chiar și atunci când tururile în sine încă reușesc.

Unde mergem mai departe

Idempotența care face livrarea exact-o-dată: Multitenanță și idempotență.
Motorul care produce răspunsul în primul rând: Gateway și motorul de tururi.