Протокол шлюза (WebSocket)

Спецификация, раздел 6.5 и 6.7. Реализация — backend/internal/gateway, клиент — web/src/lib/gateway.ts.

Подключение

wss://gateway.klichat.ru/?v=1&encoding=json (в dev — ws://localhost:8081/; Vite проксирует /gateway). v принимает 1, 9, 10 (псевдонимы для библиотек ботов); другое значение → закрытие 4012. compress=zlib-stream поддерживается: кадры уходят двоичными, сжатые одним потоком zlib на соединение, каждый завершается Z_SYNC_FLUSH (00 00 ff ff) — это формат, который ждут zlib-sync в discord.js и zlib в discord.py. Без параметра работает обычное сжатие WebSocket (permessage-deflate). encoding=msgpack — с 1.0.

Пакет: {"op": <int>, "d": <any>, "s": <int|null>, "t": <string|null>}. s и t заполнены только у DISPATCH. Лимит входящих пакетов: 120 за 60 секунд на соединение, иначе 4008. Максимальный размер пакета — 64 КБ.

Жизненный цикл

клиент                                   сервер
  │ ── WebSocket connect ───────────────────▶ │
  │ ◀── op 10 HELLO {heartbeat_interval} ───  │
  │ ── op 2 IDENTIFY {token, properties} ───▶ │
  │ ◀── op 0 READY (s=1) ───────────────────  │
  │ ── op 1 HEARTBEAT <last s> (каждые 41,25 с)
  │ ◀── op 11 HEARTBEAT_ACK
  │ ◀── op 0 DISPATCH … (s растёт)
  │      … обрыв …
  │ ── connect, HELLO, op 6 RESUME {token, session_id, seq}
  │ ◀── пропущенные DISPATCH, затем RESUMED   — или op 9 INVALID_SESSION (false) → IDENTIFY

• Первый HEARTBEAT клиент шлёт через случайную долю интервала, далее — строго по интервалу.
• Нет HEARTBEAT полтора интервала → сервер закрывает соединение 4009. Нет ACK у клиента → клиент переподключается с RESUME.
• op 7 RECONNECT — сервер просит переподключиться (деплой, ребаланс); клиент делает RESUME.
• Буфер RESUME на сервере — 500 последних событий на сессию или 3 минуты (Redis).

Опкоды

Коды закрытия

READY

{"op":0,"s":1,"t":"READY","d":{
  "v":1,
  "user":{"id":"…","username":"nikita","global_name":"Никита","avatar":null,"bot":false},
  "session_id":"3f9c…","resume_gateway_url":"wss://gateway.klichat.ru",
  "guilds":[{"id":"…","unavailable":true}],
  "private_channels":[…],"relationships":[…],"read_state":[…],"calls":[…],"user_settings":{…}
}}

calls — идущие звонки в ЛС пользователя (объекты Call с voice_states).

Для пользователей серверы лежат прямо в READY (guilds[] в форме GUILD_CREATE). Для ботов, как у Discord, READY содержит guilds: [{id, unavailable: true}], а затем приходит GUILD_CREATE на каждый сервер.

READY бота

{"op":0,"s":1,"t":"READY","d":{
  "v":1,
  "user":{"id":"…","username":"dezhurnyy","global_name":"Дежурный","discriminator":"0","avatar":null,"bot":true,"public_flags":0,"mfa_enabled":true,"verified":true},
  "session_id":"3f9c…","resume_gateway_url":"ws://localhost:8081",
  "application":{"id":"…","flags":262144},
  "shard":[0,1],
  "guilds":[{"id":"…","unavailable":true}],
  "private_channels":[],"relationships":[],"read_state":[],"presences":[]
}}

application.flags — флаги приложения в битах Discord: GATEWAY_PRESENCE 1<<12, GATEWAY_GUILD_MEMBERS 1<<14, GATEWAY_MESSAGE_CONTENT 1<<18 по включённым в «Приложениях» привилегированным intents.

GUILD_CREATE боту — объект Guild с channels, threads, roles, emojis, voice_states, member_count, joined_at и members: без intent GUILD_MEMBERS в members только сам бот, с ним — до 250 первых участников; presences заполняются только с GUILD_PRESENCES.

Присутствие

Статусы как у Discord: online, idle, dnd, invisible; чужой невидимый — offline. Человек выбирает статус и свой статус в PATCH /users/@me/settings: они хранятся на сервере, приходят в READY (user_settings.status, user_settings.custom_status: {text} | null) и с каждой новой сессией, так что невидимый остаётся невидимым после любого переподключения. Смена — USER_SETTINGS_UPDATE своим сессиям (тело как ответ PATCH) и PRESENCE_UPDATE друзьям и серверам.

{"t":"PRESENCE_UPDATE","d":{"user":{"id":"…"},"guild_id":"…","status":"dnd","client_status":{"web":"dnd"},
  "activities":[{"id":"custom","name":"Custom Status","type":4,"state":"на паре до шести"},
                {"name":"Dota 2","type":0,"steam_app_id":"570"}]}}

• Свой статус — активность type 4, текст в state, первой в списке; игра — type 0 (steam_app_id — наше поле для обложки). У offline активностей нет.
• Невидимого остальные видят offline (в READY, GUILD_CREATE, списке участников, PRESENCE_UPDATE); его собственные сессии получают PRESENCE_UPDATE о себе без guild_id со status: "invisible". Серверные копии присутствия о самом себе шлюз людям не пересылает — только ботам.
• op 3 человека статус не меняет: status: "idle" или afk: true отмечает сессию как «отошедшую», и когда отошли все сессии, выбравший online становится idle. Ручные idle, dnd, invisible важнее. Клиент может прислать то же в presence IDENTIFY. activities каждого op 3 заменяют игру целиком (пустой список — не играет).
• Бот задаёт всё через op 3 и presence в IDENTIFY, как в Discord (client.user.setPresence): статус (offline — невидимый), одна активность типов 0, 1 (с url http/https), 2, 3, 5 и свой статус type 4. IDENTIFY без presence (или с {}) возвращает статус, заданный до переподключения, — если бот вернулся в течение 10 минут.
• «Не беспокоить» — push-уведомления не отправляются, пока статус выбран (даже с закрытым клиентом); счётчики упоминаний растут как обычно.

REQUEST_GUILD_MEMBERS (op 8)

{"op":8,"d":{"guild_id":"…","query":"","limit":0,"presences":false,"user_ids":["…"],"nonce":"…"}} — query (начало имени пользователя, отображаемого имени или ника, до 100 результатов), user_ids (строка или список, до 100) или всё (query: "", limit 0 — без ограничения). Ответ — GUILD_MEMBERS_CHUNK частями по 1000 участников:

{"t":"GUILD_MEMBERS_CHUNK","d":{"guild_id":"…","members":[{"user":{…},"roles":[…],"joined_at":"…"}],
  "chunk_index":0,"chunk_count":1,"nonce":"…","presences":[…],"not_found":["…"]}}

nonce возвращается как прислан, presences только при presences: true (боту — при intent GUILD_PRESENCES), not_found — при запросе по user_ids. Боту без GUILD_MEMBERS полный список не отдаётся: приходит пустая часть, чтобы библиотека не ждала таймаута; поиск по имени и по id работает и без него.

События DISPATCH

READY, RESUMED, GUILD_CREATE/UPDATE/DELETE, GUILD_MEMBER_ADD/UPDATE/REMOVE, GUILD_MEMBERS_CHUNK, GUILD_MEMBER_LIST_UPDATE, GUILD_ROLE_CREATE/UPDATE/DELETE, GUILD_BAN_ADD/REMOVE, GUILD_EMOJIS_UPDATE, GUILD_STICKERS_UPDATE, GUILD_AUDIT_LOG_ENTRY_CREATE, GUILD_IMPORT_UPDATE, CHANNEL_CREATE/UPDATE/DELETE, CHANNEL_PINS_UPDATE, THREAD_CREATE/UPDATE/DELETE, MESSAGE_CREATE/UPDATE/DELETE/DELETE_BULK, MESSAGE_REACTION_ADD/REMOVE/REMOVE_ALL/REMOVE_EMOJI, MESSAGE_ACK, TYPING_START, PRESENCE_UPDATE, VOICE_STATE_UPDATE, VOICE_SERVER_UPDATE, CALL_CREATE/UPDATE/DELETE, AUTO_MODERATION_RULE_CREATE/UPDATE/DELETE, AUTO_MODERATION_ACTION_EXECUTION, RELATIONSHIP_ADD/REMOVE, USER_UPDATE, USER_SETTINGS_UPDATE, INVITE_CREATE/DELETE, WEBHOOKS_UPDATE, INTERACTION_CREATE (2.0).

USER_UPDATE приходит не только о себе: при смене имени или аватара друга либо собеседника в ЛС клиент получает его публичный объект user; участникам общих серверов то же изменение приходит как GUILD_MEMBER_UPDATE (полный member).

Формы объектов — как в openapi.yaml (Message, Channel, Member, Role…). Событие MESSAGE_CREATE возвращает nonce из запроса, чтобы клиент заменил оптимистичное сообщение.

Intents (боты)

Биты как у Discord: GUILDS 1<<0, GUILD_MEMBERS 1<<1 (привилегированный), GUILD_MODERATION 1<<2, GUILD_EXPRESSIONS 1<<3, GUILD_INVITES 1<<6, GUILD_VOICE_STATES 1<<7, GUILD_PRESENCES 1<<8 (привилегированный), GUILD_MESSAGES 1<<9, GUILD_MESSAGE_REACTIONS 1<<10, GUILD_MESSAGE_TYPING 1<<11, DIRECT_MESSAGES 1<<12, DIRECT_MESSAGE_REACTIONS 1<<13, DIRECT_MESSAGE_TYPING 1<<14, MESSAGE_CONTENT 1<<15 (привилегированный), AUTO_MODERATION_CONFIGURATION 1<<20, AUTO_MODERATION_EXECUTION 1<<21. Пользовательские сессии intents не передают и получают всё.

IDENTIFY бота: {"token": "klb_…", "intents": 33281, "shard": [0, 1], "properties": {…}} — токен без префикса Bot (с ним тоже принимается). Неизвестные биты intents игнорируются. Привилегированные intents (GUILD_MEMBERS, GUILD_PRESENCES, MESSAGE_CONTENT) должны быть включены владельцем в разделе «Приложения», иначе соединение закрывается кодом 4014 (PrivilegedIntentsRequired в discord.py). shard[0] != 0 → 4010 (пока один шард).

Фильтр событий бота по intents:

Без MESSAGE_CONTENT в MESSAGE_CREATE/UPDATE серверов поля content, embeds, attachments приходят пустыми, если бот не автор и не упомянут. Пользовательские события (MESSAGE_ACK, RELATIONSHIP_*, CALL_*, GUILD_MEMBER_LIST_UPDATE, USER_GUILD_SETTINGS_UPDATE, CHANNEL_RECIPIENT_*, ЛС-каналы в CHANNEL_CREATE) ботам не отправляются. Перевыпуск токена или удаление приложения закрывает сессии бота кодом 4004.

Статус реализации

Полное описание REST — OpenAPI 3.1. Разделы: вся документация.