a0c3c0cbb5
- Matrix Client (підключення та синхронізація) - RBAC Checker (перевірка прав через Postgres) - Job Creator (створення jobs з команд) - NATS Publisher (публікація jobs у streams) - K8s deployment - README з документацією Команди: !embed, !retrieve, !summarize TODO: Реальна інтеграція з Matrix homeserver, статуси результатів
130 lines
3.2 KiB
Markdown
130 lines
3.2 KiB
Markdown
# Matrix Gateway
|
||
|
||
**Дата:** 2026-01-10
|
||
**Версія:** 1.0.0
|
||
|
||
---
|
||
|
||
## 📋 Призначення
|
||
|
||
Matrix Gateway — компонент, який зв'язує Matrix rooms з NATS JetStream jobs:
|
||
|
||
1. **Приймає команди** з Matrix rooms (формат: `!command args`)
|
||
2. **Перевіряє RBAC** через Postgres
|
||
3. **Створює jobs** у NATS JetStream
|
||
4. **Публікує статуси** назад у Matrix
|
||
|
||
---
|
||
|
||
## 🔧 Команди
|
||
|
||
### Підтримувані команди:
|
||
|
||
- `!embed <text>` — створює embedding job (online priority)
|
||
- `!retrieve <query>` — створює retrieval job (online priority)
|
||
- `!summarize <thread_id>` — створює summarization job (offline priority)
|
||
|
||
### Приклад:
|
||
|
||
```
|
||
!embed Привіт, це тестовий текст для embedding
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 Deployment
|
||
|
||
### K8s
|
||
|
||
```bash
|
||
kubectl apply -f infrastructure/kubernetes/matrix-gateway/deployment.yaml
|
||
```
|
||
|
||
### Docker
|
||
|
||
```bash
|
||
docker build -t matrix-gateway:latest .
|
||
docker run -d \
|
||
-e MATRIX_HOMESERVER=https://matrix.org \
|
||
-e MATRIX_USER=@user:matrix.org \
|
||
-e MATRIX_PASSWORD=password \
|
||
-e MATRIX_ROOM_ID=!roomid:matrix.org \
|
||
-e NATS_URL=nats://nats-client.nats:4222 \
|
||
-e POSTGRES_URL=postgresql://... \
|
||
matrix-gateway:latest
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 RBAC
|
||
|
||
RBAC перевірка виконується через таблицю `matrix_rbac` в Postgres:
|
||
|
||
```sql
|
||
CREATE TABLE matrix_rbac (
|
||
user_id VARCHAR(255) PRIMARY KEY,
|
||
permissions TEXT[] NOT NULL,
|
||
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
```
|
||
|
||
### Додавання користувача:
|
||
|
||
```sql
|
||
INSERT INTO matrix_rbac (user_id, permissions)
|
||
VALUES ('@user:matrix.org', ARRAY['execute_job', 'admin']);
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 Архітектура
|
||
|
||
```
|
||
Matrix Room
|
||
↓
|
||
Matrix Gateway
|
||
├── RBAC Checker (Postgres)
|
||
├── Job Creator
|
||
└── NATS Publisher
|
||
↓
|
||
NATS JetStream
|
||
├── MM_ONLINE (embed, retrieve, summarize)
|
||
└── MM_OFFLINE (backfill, index)
|
||
↓
|
||
Worker Daemon
|
||
└── Job Executor
|
||
↓
|
||
Memory Service / Qdrant / PostgreSQL
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 Потік виконання
|
||
|
||
1. Користувач відправляє команду в Matrix room: `!embed текст`
|
||
2. Matrix Gateway отримує повідомлення
|
||
3. RBAC перевірка: чи має користувач право `execute_job`?
|
||
4. Парсинг команди та створення job payload
|
||
5. Публікація job у NATS (subject: `mm.embed.online`)
|
||
6. Підтвердження в Matrix: `✅ Job створено: <job_id>`
|
||
7. Worker Daemon бере job, виконує, пише результат
|
||
8. (Опціонально) Matrix Gateway публікує результат назад у Matrix
|
||
|
||
---
|
||
|
||
## 📁 Структура коду
|
||
|
||
```
|
||
gateway/
|
||
├── main.py # Entry point
|
||
├── matrix_client.py # Matrix connection & sync
|
||
├── nats_publisher.py # NATS job publishing
|
||
├── rbac.py # RBAC checking
|
||
└── job_creator.py # Job creation from commands
|
||
```
|
||
|
||
---
|
||
|
||
*Документ створено: 2026-01-10 19:30 CET*
|