Fork: 0
root / gnexus-handbook
Transfer to URL with SHA Find file
Newer
Older
gnexus-handbook / 10-platform / notifications.md
@Eugene Sukhodolskiy Eugene Sukhodolskiy 5 hours ago 3 KB notifications.md — конвенция интеграции сервисов с Synapse; референс-варианты Synapse в mcp/auth
Raw Blame History

Уведомления: Gnexus Synapse

Исходящие уведомления сервисов (email, Telegram, web-push, system-to-system доставка) идут через хаб Gnexus Synapse. Каждый сервис, который шлёт уведомления, интегрируется с Synapse и не держит собственных каналов доставки. Как Synapse доставляет и кому — решает маршрутизация Synapse, не отправитель.

Правила

  • Каналы доставки (email, Telegram, push) и их секреты живут в Synapse, а не в каждом сервисе. Секреты интеграции — в .env и gnexus-creds.
  • Что шлёт сервис — это его знание («что случилось у меня»): конверт события. Кому и куда доставить — решают правила маршрутизации в Synapse. В конверте нет получателей, каналов и топиков.
  • Свой очередь/механизм ретраев для уведомлений не строить — это забота Synapse.

Интеграция отправителя

  1. Регистрация источника: админка Synapse → Источники → создать (или MCP-инструментом). На выходе — API-ключ syn_*, показывается ровно один раз: в .env сервиса и в gnexus-creds. Ключ — только удостоверение источника; имя source в конверте должно совпадать с источником ключа (анти-спуфинг).
  2. Отправка: POST https://synapse.gnexus.space/api/v1/events, заголовок Authorization: Bearer syn_*. Приём мгновенно возвращает 202 — обработка асинхронная. Статус доставки — GET /api/v1/events/{id}.
  3. Конверт v1: поля source, subject, action, priority (low|normal|high|critical), payload (объект), dedup_key, ttl_seconds, scheduled_at. Полный контракт — docs/05-ingestion-api.md в репо Synapse.
  4. Адресное уведомление пользователю — конвенция payload.user_id = sub gnexus-auth (это часть payload-конвенции, не получатель).
  5. Client-libs: тонкие клиенты без очередей — gn-synapse-client-py (PyPI gnexus-synapse), gn-synapse-client-php (Composer gnexus/synapse-client), установка по тегу v0.1.0. Конфиг только env:| env | что | |---|---| | SYNAPSE_URL | базовый URL хаба | | SYNAPSE_API_KEY | ключ syn_* источника | | SYNAPSE_TIMEOUT | таймаут HTTP, сек | | SYNAPSE_DEFAULT_SOURCE | умолчание source (смягчает 403 анти-спуфинга) |

Интеграция получателя (system-to-system)

Сервис, который хочет получать события (Navi-инстансы и др.), отдаёт webhook-эндпоинт, и он регистрируется в Synapse как цель (Target). Дальше Synapse сам шлёт deliveries с ретраями; статусы видны в логе доставок админки.

Ссылки