Көп-жалдаушылық және идемпотенттілік

# 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 — **көп-жалдаушылы**: бір шлюз бір дерекқордан көптеген жұмыс кеңістігіне қызмет көрсете алады, олардың деректерін бөлек ұстай отырып. Мұны екі тетік қауіпсіз етеді — оқу/жазу оқшаулауы үшін **Postgres Row-Level Security (RLS)** және қайталаулар мен бұрылысты қалпына келтіру нақты-дүниелік жанама әсерді ешқашан қайталамайтындай **идемпотенттілік қабаты**. ## Row-Level Security көмегімен жалдаушыны оқшаулау Оқшаулау тек қолданба кодында емес, дерекқорда мәжбүрленеді. AiHummer сұрауларды RLS саясаттары қолданылған **шектеулі Postgres рөлі** (`aihummer_app`) арқылы іске қосады, осылайша дерекқордың өзі белсенді жалдаушыға тиесілі емес жолдарды қабылдамайды. RLS — **таңдамалы**. Сіз оны шлюзге шектеулі рөл үшін екінші қосылым жолын беру арқылы белсендіресіз: ```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] > Хост-туған орнатулар үшін орнатушы `AIHUMMER_DB_APP_URL`-ді > автоматты түрде орнатады, сондықтан стандартты орналастыруда RLS әдепкі бойынша қосулы. Егер > айнымалы болмаса, шлюз тек иесінің пулында жұмыс істейді және RLS > белсенді емес. ### Жалдаушы-бойынша шектеу Шектеулі рөл ішінде әрбір сұрау өзінің жалдаушысына шектеледі: шлюз қосылымда ағымдағы жалдаушы контекстін орнатады, осылайша RLS саясаттары дұрыс жұмыс кеңістігіне қарай шешіледі. `WHERE tenant_id = …` сүзгілері барлық жерде қолмен жазылмайды; саясат оны орталықтандырылған түрде мәжбүрлейді, бұл өткізіп жіберілген сүзгінің басқа жалдаушының жолдарын ағыза алмайтынын білдіреді. ### Жүйелік / айналып өту режимі Кейбір жұмыс заңды түрде жалдаушыаралық болады — бүкіл данада жұмыс істейтін фондық жұмысшылар, жоспарлаушылар және қызмет көрсету тапсырмалары. Олар өздеріне керектіні көре алатындай **жүйелік / айналып өту режимінде** жұмыс істейді. Айналып өту сенімді ішкі жұмысшыларға сақталған, сұрау-өңдеу жолдарына емес. > [!WARNING] > **Көшірулер әрқашан иесінің пулында іске қосылады**, ешқашан шектеулі рөл астында емес. > Иесінің қосылымында схеманы өзгертуге және RLS саясаттарын қолдануға > артықшылықтар бар; шектеулі рөлде әдейі жоқ. Екі қосылым > жолын бөлек ұстаңыз және `aihummer_app` рөліне тек оған керектіні ғана беріңіз. ## Идемпотентті жанама әсерлер Бұрылыс нақты-дүниелік жанама әсерлер тудыруы мүмкін: пошта жіберу, арнаға кері хабарлама жариялау. Егер бұрылыс қайталанса — өтпелі қателіктен немесе шлюз бұрылыс ортасында қайта іске қосылып, қалпына келтіру оны қайта ойнатқандықтан — сол жанама әсерлер екі рет болмауы **керек**. AiHummer мұны екі бірлесіп жұмыс істейтін бөлікпен кепілдейді. ### Қайта-басталуға-тұрақты тізілім кілті Әрбір жанама әсер **қайта-басталуға-тұрақты тізілім кілтіне** қарсы жазылады: бұл бұрылыстан детерминистік түрде шығарылған кілт, осылайша сол бұрылыстың қайта ойнатылуы жаңа емес, *сол* кілтті есептейді. Тізілім қандай кілттердің әлдеқашан әрекет етілгенін есте сақтайды. ### Жанама-әсер тосқауылы **Пошта** немесе **арнаға-жіберу** сияқты әсер орындалмас бұрын, ол тізілімді тексеретін **жанама-әсер тосқауылынан** өтеді. Егер бұл кілт әлдеқашан іске қосылған болса, тосқауыл қысқа тұйықтайды да әсер өткізіп жіберіледі; егер жоқ болса, әсер орындалады және кілт бекітіледі. ```text side-effect requested └─▶ compute resume-stable ledger key └─▶ barrier: key already committed? ├─ yes ─▶ skip (no double-send) └─ no ─▶ perform effect ─▶ commit key ``` Нәтиже — **жеткізу іштей кемінде-бір-рет болса да, дәл-бір-рет сыртқы тәртіп**. Қайталаулар құрылымы бойынша қауіпсіз, бұл бұрылысты қалпына келтіруге (қараңыз: [Жеткізу, outbox және қалпына келтіру](/kk/v1.0/architecture/delivery-outbox)) клиент сол электрондық хатты немесе сол жауапты екі рет алмай, үзілген бұрылысты қайта ойнатуға мүмкіндік береді. > [!TIP] > Дәл сондықтан AiHummer қайталанатын хабарламалардың әдеттегі қаупінсіз кепілдендірілген жеткізу мен > автоматты бұрылысты қалпына келтіруді ұсына алады — идемпотенттілік — жеткізу > кепілдіктері тұрғызылатын негіз. ## Әрі қарай қайда - Бұрылысты жетектейтін орындалу ортасы: [Шлюз және бұрылыс қозғалтқышы](/kk/v1.0/architecture/gateway-turn-engine). - Жауаптардың дәл бір рет қалай қайтарылатыны: [Жеткізу, outbox және қалпына келтіру](/kk/v1.0/architecture/delivery-outbox).