Multitenanță și 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 **multitenant**: un singur gateway poate deservi 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 — **Row-Level Security (RLS) Postgres** pentru izolarea citire/scriere și un **strat de idempotență**, astfel încât reîncercările și recuperarea turului să nu dubleze niciodată un efect secundar din lumea reală. ## Izolarea tenanților cu Row-Level Security Izolarea este aplicată 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 politici RLS aplicate, astfel încât baza de date însăși respinge rândurile care nu aparțin tenantului activ. RLS este **opt-in**. Î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 pe gazdă, programul de instalare setează > `AIHUMMER_DB_APP_URL` automat, deci RLS este activat în mod implicit într-o > implementare standard. Dacă variabila lipsește, gateway-ul rulează doar pe > owner pool, iar RLS nu este activ. ### Scoping per tenant În cadrul rolului restricționat, fiecare cerere este limitată la tenantul său: gateway-ul setează contextul tenantului curent pe conexiune, astfel încât politicile RLS să se rezolve față de spațiul de lucru corect. Filtrele `WHERE tenant_id = …` nu sunt scrise manual peste tot; politica le aplică central, ceea ce înseamnă că un filtru omis nu poate scurge rândurile altui tenant. ### Mod de sistem / bypass O parte din lucrare este în mod legitim inter-tenant — workeri de fundal, programatoare și lucrări de întreținere care operează pe întreaga instanță. Acestea rulează într-un **mod de sistem / bypass**, astfel încât să poată vedea ce au nevoie. Bypass-ul este rezervat workerilor interni de încredere, nu căilor de gestionare a cererilor. > [!WARNING] > **Migrările rulează întotdeauna pe owner pool**, niciodată sub rolul > restricționat. Conexiunea de proprietar are privilegiile de a modifica schema > și de a aplica politici RLS; rolul restricționat în mod deliberat nu le are. > Păstrați cele două șiruri de conexiune distincte și acordați rolului > `aihummer_app` doar ceea ce are nevoie. ## Efecte secundare idempotente Un tur poate produce efecte secundare în lumea reală: trimiterea de e-mail, postarea unui mesaj înapoi pe un canal. Dacă un tur este reîncercat — din cauza unei erori tranzitorii sau pentru că gateway-ul a repornit în mijlocul turului, iar recuperarea îl reia — acele efecte secundare **nu** trebuie să se întâmple de două ori. AiHummer garantează acest lucru cu două piese care cooperează. ### O cheie de registru stabilă la reluare Fiecare efect secundar este înregistrat față de o **cheie de registru stabilă la reluare**: o cheie derivată determinist din tur, astfel încât o reluare a aceluiași tur calculează *aceeași* cheie, mai degrabă decât una nouă. Registrul își amintește care chei au fost deja acționate. ### O barieră de efecte secundare Înainte ca un efect cum ar fi **mail** sau **trimitere pe canal** să fie efectuat, acesta trece printr-o **barieră de efecte secundare** care verifică registrul. Dacă această cheie a fost deja declanșată, bariera scurtcircuitează ș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 un **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 recuperării turului (vezi [Livrare, outbox și recuperare](/ro/v1.0/architecture/delivery-outbox)) să reia 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 turului fără riscul obișnuit de mesaje duplicate — > idempotența este fundația pe care sunt construite garanțiile de livrare. ## Unde mergem mai departe - Runtime-ul care conduce un tur: [Gateway și motorul de tururi](/ro/v1.0/architecture/gateway-turn-engine). - Cum sunt returnate răspunsurile exact o singură dată: [Livrare, outbox și recuperare](/ro/v1.0/architecture/delivery-outbox).