Бисёрмустаъҷирӣ ва idempotency

# 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 **бисёрмустаъҷир** аст: як gateway метавонад бисёр корфазоҳоро аз як пойгоҳи додаҳо хидмат кунад, дар ҳоле ки додаҳои онҳоро ҷудо нигоҳ медорад. Ду механизм инро бехатар мекунанд — **Postgres Row-Level Security (RLS)** барои ҷудоии хондан/навиштан ва як **қабати idempotency**, то такрорҳо ва барқароркунии навбат ҳеҷ гоҳ side-effect-и воқеиро такрор накунанд. ## Ҷудоии tenant бо Row-Level Security Ҷудоӣ дар пойгоҳи додаҳо иҷро мешавад, на танҳо дар коди барнома. AiHummer дархостҳоро тавассути як **нақши маҳдуди Postgres** (`aihummer_app`) иҷро мекунад, ки сиёсатҳои RLS татбиқшуда дорад, бинобар ин худи пойгоҳи додаҳо сатрҳоеро, ки ба tenant-и фаъол тааллуқ надоранд, рад мекунад. RLS **opt-in** аст. Шумо онро бо додани сатри пайвасти дуюм ба gateway барои нақши маҳдуд фаъол мекунед: ```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] > Барои насбҳои host-native насбкунанда `AIHUMMER_DB_APP_URL`-ро ба таври худкор > муқаррар мекунад, бинобар ин RLS дар ҷойгиркунии стандартӣ бо нобаёнӣ фаъол аст. > Агар тағйирёбанда вуҷуд надошта бошад, gateway танҳо дар owner pool кор мекунад ва > RLS фаъол нест. ### Доманабандии ҳар-tenant Дар дохили нақши маҳдуд, ҳар дархост ба tenant-и худ домана дода мешавад: gateway контексти tenant-и ҷориро дар пайваст муқаррар мекунад, то сиёсатҳои RLS нисбат ба корфазои дуруст ҳал шаванд. Филтрҳои `WHERE tenant_id = …` дар ҳама ҷо дастӣ навишта намешаванд; сиёсат онро марказона иҷро мекунад, ки маънои онро дорад, ки филтри гумшуда наметавонад сатрҳои tenant-и дигарро фош кунад. ### Ҳолати система / bypass Баъзе корҳо ба таври қонунӣ байни-tenant ҳастанд — коргарони пасзамина, ҷадвалбандҳо ва корҳои нигоҳдорӣ, ки дар саросари тамоми instance кор мекунанд. Инҳо дар як **ҳолати система / bypass** иҷро мешаванд, то онҳо чизи лозимаро бубинанд. Bypass барои коргарони боэътимоди дохилӣ ҳифз шудааст, на барои масирҳои коркарди дархост. > [!WARNING] > **Migration-ҳо ҳамеша дар owner pool иҷро мешаванд**, ҳеҷ гоҳ дар зери нақши > маҳдуд. Пайвасти owner имтиёзҳои тағйир додани схема ва татбиқи сиёсатҳои RLS-ро > дорад; нақши маҳдуд қасдан надорад. Ду сатри пайвастро ҷудо нигоҳ доред ва ба > нақши `aihummer_app` танҳо он чизеро диҳед, ки ба он лозим аст. ## Side-effect-ҳои idempotent Як навбат метавонад side-effect-ҳои воқеиро тавлид кунад: фиристодани почта, гузоштани паём ба канал. Агар навбат такрор шавад — аз сабаби хатои гузаранда ё аз он сабаб, ки gateway дар миёнаи навбат бозоғоз шуд ва барқароркунӣ онро аз нав иҷро мекунад — он side-effect-ҳо **набояд** ду маротиба рӯй диҳанд. AiHummer инро бо ду қисмати ҳамкорикунанда кафолат медиҳад. ### Калиди устувори resume-stable дар дафтари ҳисоб Ҳар side-effect нисбат ба як **калиди устувори resume-stable** сабт мешавад: калиде, ки ба таври детерминистӣ аз навбат ҳосил мешавад, бинобар ин такрори ҳамон навбат *ҳамон* калидро ҳисоб мекунад, на калиди наверо. Дафтари ҳисоб дар хотир дорад, ки кадом калидҳо аллакай амалӣ шудаанд. ### Монеаи side-effect Пеш аз он ки эффекте ба монанди **почта** ё **фиристодани канал** иҷро шавад, он аз як **монеаи side-effect** мегузарад, ки дафтари ҳисобро месанҷад. Агар ин калид аллакай шуда бошад, монеа кӯтоҳ мешавад ва эффект нодида гирифта мешавад; агар не, эффект иҷро мешавад ва калид commit мешавад. ```text side-effect requested └─▶ compute resume-stable ledger key └─▶ barrier: key already committed? ├─ yes ─▶ skip (no double-send) └─ no ─▶ perform effect ─▶ commit key ``` Натиҷа **рафтори exactly-once-и берунӣ аст, ҳарчанд расондан дар дохил at-least-once аст**. Такрорҳо аз рӯи сохт бехатар ҳастанд, ки ин чизест, ки ба барқароркунии навбат (нигаред ба [Расондан, outbox ва барқароркунӣ](/tg/v1.0/architecture/delivery-outbox)) имкон медиҳад навбати қатъшударо аз нав иҷро кунад, бе он ки муштарӣ ҳамон почта ё ҳамон ҷавобро ду маротиба гирад. > [!TIP] > Ин аст сабабе, ки AiHummer метавонад расондани кафолатнок ва барқароркунии > худкори навбатро бе хатари маъмулии паёмҳои такрорӣ пешниҳод кунад — idempotency > заминаест, ки кафолатҳои расондан дар он сохта шудаанд. ## Қадами навбатӣ ба куҷо - Рантайме, ки навбатро пеш мебарад: [Gateway ва муҳаррики навбат](/tg/v1.0/architecture/gateway-turn-engine). - Чӣ тавр ҷавобҳо маҳз як маротиба баргардонида мешаванд: [Расондан, outbox ва барқароркунӣ](/tg/v1.0/architecture/delivery-outbox).