Multichiria & idempotență

# gateway.env
# Owner pool — runs migrations and privileged maintenance
AIHUMMER_DATABASE_URL=postgres://aihummer:***@localhost:5432/aihummer?sslmode=disable
# Restricted role — activates RLS for normal request traffic
AIHUMMER_DB_APP_URL=postgres://aihummer_app:***@localhost:5432/aihummer?sslmode=disable

side-effect requested
   └─▶ compute resume-stable ledger key
         └─▶ barrier: key already committed?
               ├─ yes ─▶ skip (no double-send)
               └─ no  ─▶ perform effect ─▶ commit key

AiHummer este **multichiriaș**: un singur gateway poate deservi mai multe spații de lucru dintr-o singură bază de date, păstrând în același timp datele lor separate. Două mecanisme fac acest lucru sigur — **Securitatea la nivel de rând în Postgres (RLS)** pentru izolarea citirii/scrierii, și un **strat de idempotentă** astfel încât reîncercările și recuperarea rotației să nu dubleze niciodată un efect secundar din lumea reală. **Nivel:** Izolarea multitenant la nivel de rând prin Row-Level Security este restricționată de versiunea plătită **Întreprindere** nivel — nu face parte din platforma gratuită/Community; stratul de idempotentă face parte din nucleu. ## Izolarea chiriașului cu securitate la nivel de rând Izolarea este impusă la nivelul bazei de date, nu doar în codul aplicației. AiHummer rulează interogări printr-un **rol Postgres restricționat** (`aihummer_app`) care are aplicate politici RLS, astfel încât baza de date însăși respinge rândurile care nu aparțin chiriașului activ. RLS este **a opta**. Îl activați oferind gateway-ului un al doilea șir de conexiune pentru rolul restricționat: ```ini # gateway.env # Owner pool — runs migrations and privileged maintenance AIHUMMER_DATABASE_URL=postgres://aihummer:***@localhost:5432/aihummer?sslmode=disable # Restricted role — activates RLS for normal request traffic AIHUMMER_DB_APP_URL=postgres://aihummer_app:***@localhost:5432/aihummer?sslmode=disable ``` > [!NOTE] > Pentru instalările native ale gazdei, programul de instalare setează `AIHUMMER_DB_APP_URL` > automat, astfel încât RLS este activat implicit într-o implementare standard. Dacă > variabila este absentă, gateway-ul funcționează doar pe pool-ul proprietar și RLS nu este > activ. ### Definirea domeniului per chiriaș În rolul restricționat, fiecare cerere este limitată la chiriașul său: gateway-ul setează contextul chiriașului curent pe conexiune astfel încât politicile RLS să se rezolve în funcție de spațiul de lucru corect. `WHERE tenant_id = …` filtrele nu sunt realizate manual peste tot; politica le aplică centralizat, ceea ce înseamnă că un filtru omis nu poate scurge rândurile unui alt chiriaș. ### Sistem / mod ocolire Unele lucrări sunt în mod legitim cross-tenant — lucrători de fundal, programatori și sarcini de întreținere care operează pe întreaga instanță. Acestea rulează într-un **sistem / modul ocolire** pentru ca ei să poată vedea ceea ce au nevoie. Ocolirea este rezervată lucrătorilor interni de încredere, nu pentru căile de gestionare a solicitărilor. > [!WARNING] > **Migrațiile rulează întotdeauna pe pool-ul proprietarului**, niciodată sub rolul restricționat. > Conexiunea proprietarului are privilegiile de a modifica schema și de a aplica RLS > politici; rolul restricționat în mod deliberat nu o face. Păstrați cele două conexiuni > șiruri distincte și acordă `aihummer_app` rol doar ceea ce are nevoie. ## Efecte secundare idempotente O rotație poate produce efecte secundare în lumea reală: trimiterea de e-mailuri, postarea unui mesaj înapoi pe un canal. Dacă o rotație este reîncercată — din cauza unei erori temporare sau pentru că gateway-ul a repornit la mijlocul rotației și recuperarea o reexează — acele efecte secundare trebuie **nu** se întâmplă de două ori. AiHummer garantează acest lucru cu două piese care cooperează. ### O cheie de registru stabilă pentru CV Fiecare efect secundar este înregistrat împotriva unui **cheie de registru stabil de reluare**: o cheie care este derivată determinist din tur, astfel încât o reluare a aceluiași tur să calculeze *aceeași* cheie și nu una nouă. Registrul își amintește ce chei au fost deja acționate. ### O barieră a efectelor secundare Înainte de un efect cum ar fi **poștă** sau **canal-trimitere** este efectuat, trece printr-un **barieră de efecte secundare** care verifică registrul. Dacă această cheie a fost deja activată, bariera se scurtează și efectul este sărit; dacă nu, efectul rulează și cheia este înregistrată. ```text side-effect requested └─▶ compute resume-stable ledger key └─▶ barrier: key already committed? ├─ yes ─▶ skip (no double-send) └─ no ─▶ perform effect ─▶ commit key ``` Rezultatul este **comportament extern exact-o-dată chiar dacă livrarea este cel puțin-o-dată intern**. Reîncercările sunt sigure prin construcție, ceea ce permite recuperarea turnului (vezi [Livrare și recuperare de încredere](/ro/v1.0/architecture/delivery-outbox)) reda un tur întrerupt fără ca un client să primească același e-mail sau același răspuns de două ori. > [!TIP] > Acesta este motivul pentru care AiHummer poate oferi livrare garantată și recuperare automată a virajului > fără riscul obișnuit de mesaje duplicate — idempotenta este fundamentul > garanțiile de livrare sunt construite pe. ## Unde următor? - Motorul de execuție care conduce un tur: [Poartă și motor de virare](/ro/v1.0/architecture/gateway-turn-engine). - Cum răspunsurile sunt returnate exact o dată: [Livrare și recuperare de încredere](/ro/v1.0/architecture/delivery-outbox).