Клиент-серверный протокол
Актуально для: SimpleTwo 0.9.x · Версия протокола: 4 · Проверено: 24.10.2026
Это контракт, а не описание текущей реализации: то, что здесь написано, продукт обязан соблюдать, а менять это можно только по правилам из §14. Страница адресована тем, кто пишет собственного клиента, бота, мост или интеграцию.
1. Единственное правило, из которого следует остальное
Идентификатор — серверный, имя — читательское, а то, что написал клиент, никогда не является удостоверением личности.
Отправителя аутентифицировала служба — значит, только она может сказать, кто говорит. Клиент сообщает, что он делает и кому, но никогда — кто он.
Три следствия, применяемые везде ниже:
- Личность проставляет сервер.
sender,from,userпишет служба из аутентифицированной сессии. У типа запроса по возможности просто нет такого поля — чтобы клиент физически не мог его заявить. - Адресацию проверяет сервер.
toсверяется с членством, а не принимается на веру. - Поле, которое нужно игнорировать, должно быть удалено. Поле, которое читателю велено пропускать, — это поле, которому поверит следующий читатель.
2. Транспорт и аутентификация
| База | https://<хост messaging>/v1 |
| Аутентификация | Authorization: Bearer <токен> в каждом запросе, включая рукопожатие сокета |
| Боты | тот же заголовок с токеном bot_…; ограничены областями и списком бесед, каждый запрос аудируется, включая чтения |
| Ошибки | JSON {"code": "<идентификатор>", "error": "<фраза>"} |
| События | один WebSocket: GET /v1/ws?token=…&device=… |
Коды состояния несут смысл, и клиент обязан их различать:
| Код | Значит | Что делает клиент |
|---|---|---|
| 400 | запрос неверен или называет неизвестное | это дефект: сообщить, не повторять |
| 401 | токен отсутствует, истёк или отозван | обновить и повторить один раз |
| 403 | аутентифицирован и не имеет права | не повторять: это ответ, а не сбой |
| 404 | нет такого — или нет для этого вызывающего | считать отсутствующим |
| 409 | конфликт состояния (повторное вступление, занятое имя) | разрешить и повторить |
| 410 | этой формы больше нет; в сообщении названа замена | чинить клиент |
| 429 | ограничение частоты | отступить; на сокет это не влияет |
403 намеренно покрывает и «не существует», и «не ваше» везде, где различить их означало бы раскрыть каталог, который вызывающему не виден.
3. Версия протокола, и что говорят старому клиенту
Одно монотонное целое на весь контракт — и HTTP, и кадры сокета вместе. Не semver: единственный вопрос, который кто-либо задаёт, — «этот клиент старше, чем требует сервер?», а это сравнение. Одно число на обе поверхности потому, что это один контракт: день, когда они разъедутся, — это день, когда клиент сможет удовлетворить половину.
Версия 3, нижняя граница 3 — релиз неизменяемых идентификаторов. Каждый человек на проводе —
отправитель, участник, контакт, блокировка, «я», первая часть identity в звонке — это неизменяемый
uid учётной записи, а не логин; логин — атрибут, который клиент показывает (поле login в
каталоге). Сборка протокола 2 читает логины там, где теперь uid, поэтому получает client_too_old.
| Заголовок | Направление | Значение |
|---|---|---|
X-SimpleTwo-Protocol | сервер → клиент | что говорит служба |
X-SimpleTwo-Protocol-Min | сервер → клиент | самый старый клиент, который ещё обслуживается |
X-SimpleTwo-Client-Protocol | клиент → сервер | что говорит клиент |
Именно заголовки, а не поля тела: клиент обязан иметь возможность узнать, что отстал, из того запроса, который он и так делал, — в том числе из неудачного. Заголовок переживает 4xx, тело которого клиент не понял.
Три состояния, и все три обязаны существовать:
| Клиент относительно сервера | Сервер | Клиент |
|---|---|---|
| текущий | обычная работа | ничего |
отстал, но не ниже Min | обычная работа, считается по версиям | ненавязчивое «доступно обновление» |
ниже Min | отказ: client_too_old | блокирующий экран: эта сборка не говорит с этим сервером |
Без неё любое изменение контракта — выбор между «сломать людей молча» и «нести алиас вечно», а
алиас нельзя снять никогда: доказать, что последний старый клиент исчез, невозможно. Со средней
строкой у отказа от старой формы появляется конец: поднять Min в назначенный день, посмотрев
на отчёт о населении, после того как приложение неделями предупреждало людей само.
Служба сообщает не только отказы, но и состав подключённых: /healthz и консоль разбивают
клиентов по версии протокола и платформе. Одного счётчика мало: «0,4% Android на протоколе 5» и
«31% iOS на протоколе 5» — это одно и то же «больше нуля» и совершенно разные решения.
4. У ошибок есть коды
Ошибка — это {"code", "error"}: код для ветвления, фраза для журнала. Формулировку владеет
клиент, а не сервер: перевод живёт в клиентском ядре. Каталог кодов — на отдельной странице
Коды ошибок, и он проверяется в CI: код, который служба может отправить, а клиент
не умеет перевести, — это дефект сборки, а не мелочь перевода.
Код — это идентификатор: он никогда не переименовывается и не переиспользуется. Переименование молча меняет то, что покажет уже установленный клиент.
5. Три поверхности, и почему их три
| Поверхность | Что несёт | Хранится | Пример |
|---|---|---|---|
| Сообщения | содержимое беседы | да, адресуется по seq | строка чата, файл, итог звонка |
| Сигнальные станцы | переговоры сторон | нет | звонок, отмена, отказ, вход |
| Эфемерные кадры | подсказка про «прямо сейчас» | нет | набор текста, присутствие |
Это не таксономия ради таксономии. Сигналинг когда-то ездил сообщениями — и маршрутизация с личностью оказывались внутри тела, которое написал клиент; тогда клиент мог позвонить, выдавая себя за коллегу. Поверхности различаются тем, кто что вправе заявить.
6. Сообщения
POST /v1/conversations/{id}/messages
{ "kind": "text", "body": "привет", "client_msg_id": "…" }
Виды — белый список: text, media, location, contact, call, system. Всё
остальное — 400.
systemпишет сервер. Клиенту — 403, с единственным исключением по форме: итог звонка, который несёт результат, длительность и флаги и не несёт личности.call— только итог. Шаг звонка, отправленный сюда, получает 410: шаги — это сигналинг. Одно от другого отличается по форме: у шага естьaction, у итога —outcome.
sender, seq и отметки времени проставляет сервер. Клиент обязан брать авторство из
конверта, а не из тела. client_msg_id делает повтор идемпотентным — это то, что позволяет
клиенту переотправлять, не задваивая.
7. Сигнальные станцы
POST /v1/signal
{ "to": "i.ivanov", "kind": "call", "step": "invite",
"call": "c-7f3a", "seq": 1, "body": { "video": true, "room": "conv-42" } }
| Поле | Кто заявляет | Примечание |
|---|---|---|
to | клиент, проверяется | беседа, в которой он состоит, либо человек, с которым есть общая |
kind | клиент, по белому списку | call, webrtc, sub; незнакомое семейство — 400 |
step | клиент | call: invite, cancel, join, end, decline, hold, transfer; webrtc: offer, answer, candidate, camera; sub: subscribe, unsubscribe |
call, seq | клиент | идентификатор попытки и порядок шагов внутри неё |
Отправителя проставляет служба. Станца не хранится: она доставляется тем, кто сейчас на связи, и не становится строкой беседы.
8. События сокета
Одно соединение. Каждое событие — {"type", "conv?", "seq?", "ts", "data", "rev?", "rev_count?"};
ts — секунды unix, как и все прочие метки на проводе.
| Тип | Данные |
|---|---|
message.new / message.edit / message.delete | сообщение |
receipt | {user, conversation_id, seq, state} — delivered или read, водяной знак: относится ко всему до seq включительно |
signal | станца (§7) |
typing | {user} — никогда самому отправителю |
uploading | {user, file, progress} или {user, file, done: true} — кто-то отправляет в комнату файл (§9); никогда самому отправителю |
presence | действующее присутствие одного человека |
inbox, conversation.updated | беседа, вместе с участниками |
reaction, pin, membership, unit, draft, avatar, purge, group, conversation.deleted | как названо |
calendar.changed | {calendar_id, sync_seq} — курсор календаря сдвинулся, клиент дочитывает изменения у службы календарей |
directory.changed | {user, rev} — человек появился, изменился, заблокирован или ушёл; область видимости применяется при вычитке |
guest.recovery.requested | {} — приглашённый гость не может войти; адресовано пригласившему, содержимого не несёт намеренно |
Беседа, приехавшая событием, несёт участников — всегда для личных и секретных чатов и для комнат, пока участников не больше шестнадцати. Счётчики непрочитанного, закрепления и приглушения в событие не кладутся: это ответы на вопрос «кто спрашивает», а событие уходит всем сразу.
9. Эфемерные кадры
Единственное, что клиент кладёт на сокет:
{ "kind": "typing", "conv": "c-42" }
{ "kind": "presence", "awake": false }
{ "kind": "uploading", "conv": "c-42", "file": "photo", "progress": 42 }
Оба поля заявляются и оба проверяются, kind — по белому списку. Поля для человека нет: его
проставляет служба из аутентифицированного соединения. Ключ type на входящем кадре не
принимается — это исходящий словарь сервера, и принимать его обратно значит держать ровно ту
путаницу, которую правило убирает.
У протокола не может быть постоянной оговорки «мы принимаем и старую форму»: это протокол с
двумя формами, потому что «последний старый клиент исчез» не доказуемо никогда. Поэтому старая
форма отклоняется, отказы считаются (/healthz), а цена — в релизных заметках. Так,
шаг звонка, отправленный старым способом, получает 410, и это даже не компромисс: старый клиент
всё равно не слушает события signal, так что принятый вызов дошёл бы до тишины.
Набор текста доставляется другим участникам комнаты и никогда не отражается отправителю.
«Отправляет фото… 42 %». Кадр uploading (с 12.10.2026): file — одно из
photo, video, audio, voice, file; progress — от 0 до 100, done: true — закончил
(отправил или отказался). Другие участники получают событие uploading с user, проставленным
службой. Служба пропускает не больше одного кадра с прогрессом в секунду на человека и беседу
(первый кадр и done проходят всегда); отправитель повторяет кадр не реже раза в 5 секунд, а
получатель гасит индикатор, который не повторялся 6 секунд. Не хранится и не отражается
отправителю, как и набор текста. Версия протокола не меняется: и кадр, и событие — добавления.
10. Присутствие
Присутствие человека — не свойство соединения. Сокет держит и свёрнутое приложение, поэтому
«подключён» и «доступен» — разные вещи, и клиент сообщает своё состояние кадром presence
(awake). На этом же различии стоит решение о пуше: доставленным сообщение считается только
если приложение и подключено, и не спит.
11. Имена и аватары
На проводе едет идентификатор, а отображаемое имя подставляет читатель из своего кеша
каталога. Из этого следует практическое: то, что придёт в вашу интеграцию, — это username, а
не «Иван Петров», и телефонный номер разрешается тем же путём.
12. Возможности: что вправе этот вызывающий
Клиент спрашивает, что он вправе предложить; сервер решает, что он примет. Первый ответ нужен, чтобы нарисовать экран, второй — единственный, который что-то решает.
Две области: учётная запись целиком (GET /v1/me/capabilities) и права внутри беседы. Три
правила, обязательных для любого клиента:
- Неизвестное имя права = не выдано. Так словарь расширяется в безопасную сторону: новое право включает новую кнопку в новом клиенте, а старый просто ничего не показывает.
- Ответ 404 — это не пустой набор, а установка, которая старше этого раздела.
- Совет — не разрешение. Ограничение интерфейса не заменяет проверку на сервере; сервер проверяет в любом случае.
13. Время на проводе
Каждая метка времени — момент в RFC3339, и каждая служба ставит её в UTC. Это всё правило; остальное — цена его нарушения.
Читатель обязан принимать все формы, которые порождает сериализация: …T00:00:00Z и
…T00:00:00.881243881Z. Читатель, принимающий одну из них, и есть дефект: он не падает, он
молча возвращает пустоту, и на экране остаётся прочерк там, г де должна быть дата. Клиент хранит
момент, а не его написание: строка сортируется лексикографически, что совпадает с хронологией
ровно до первого смещения.
Поля сокета (ts) и токенов (exp, iat, rnw) — это секунды unix.
14. Как это расширяется
Добавляя поле, спросите: мог ли его написать клиент? Если да, и кто-то читает его как личность или как право — ему не место в протоколе: оно едет в конверте, где его проставляет служба.
Добавляя форму «клиент → сервер», спросите, какая это из трёх поверхностей: переговоры — станца, подсказка про сейчас — кадр, содержимое — сообщение.
Добавляя вид, семейство или тип кадра — вносите его в белый список. Форма, которая доставлена и проигнорирована, неотличима для отправителя от потерянной.
15. Гости и возвращение доступа
Гость — учётная запись, которую кто-то здесь пригласил: телефон, срок, и поле «кто пригласил». Пароль гости теряют регулярно, поэтому восстановление устроено так:
| Вызов | Кто может | Что делает |
|---|---|---|
POST /v1/auth/recover {phone} | любой | «не могу войти». Отвечает {status:"ok"} всегда — одинаково на известный и неизвестный номер, иначе это способ выяснить, есть ли такая учётная запись |
POST /v1/auth/recover/confirm {phone, code, new_password} | любой | меняет код на новый пароль. Десять минут, пять попыток, одноразово, хранится хешированным |
Пять попыток принадлежат номеру, а не коду: повторный запрос не покупает новых попыток.
15.1 Карточка приглашения и что на ней
Карточка — одна строка: simpletwo://enroll?d=<base64url(json)>. Она открывает приложение как
ссылка и сканируется как QR; пишет и читает её ядро, одинаково на всех клиентах. Старая карточка
голым JSON по-прежнему читается: такие уже напечатаны и лежат у людей.
Внутри: адрес сервера c, учётная запись u, секрет p и i — признак «адрес по простому
HTTP», выводимый из самого адреса, а не принимаемый на веру.
p — одноразовый код, а не пароль. Он покупает ровно одно:
POST /v1/auth/enroll/confirm new_password
Код тратится этим вызовом, действует трое суток, хранится хешированным. До того как его использовали, у учётной записи пароля нет вообще — карточка единственный вход; после — карточка не стоит ничего. Раньше на ней был настоящий пароль учётной записи, который жил столько же, сколько сама учётная запись.
Потерянную до использования карточку перевыпускает пригласивший
(POST /v1/guests/{username}/card) — и только пока гость ни разу не входил. После этого ответ —
восстановление доступа (§15), которое доказывает телефон.
16. За грузка файла и докачка
Два входа, и второй не заменяет первый.
В один приём. POST /v1/uploads?conv=<id>, multipart/form-data, поле file. В ответе —
вложение. Это правильный вызов для фотографии, и так работают сегодняшние клиенты.
С докачкой — для всего, что телефон может не досылать за один раз. Это tus 1.0.0
(ядро плюс расширения creation и termination), а не наш собственный протокол: для tus есть
готовые библиотеки на всех платформах, и ровно этот же контракт будет у файлового хранилища —
двух способов отправить файл в платформе не будет.
| Шаг | Запрос | Ответ |
|---|---|---|
| Открыть | POST /v1/uploads/sessions?conv=<id> с Upload-Length и Upload-Metadata (filename, filetype, в base64) | 201, заголовки Location, Upload-Offset: 0, Upload-Expires, X-S2-Part-Size и то же самое в теле JSON |
| Спросить | HEAD /v1/uploads/sessions/{id} | 200, Upload-Offset, Upload-Length |
| Слать | PATCH /v1/uploads/sessions/{id}, Content-Type: application/offset+octet-stream, Upload-Offset: <байт> | 204 и новое смещение, либо 200 с вложением на том запросе, который завершил загрузку |
| Отказаться | DELETE /v1/uploads/sessions/{id} | 204, уже отправленные части удаляются |
| Узнать пределы | OPTIONS /v1/uploads/sessions | Tus-Version, Tus-Extension, Tus-Max-Size — предел размера ещё до того, как в него упёрлись |
Tus-Resumable: 1.0.0 есть в каждом ответе. Два отступления от спецификации, названные
здесь, а не обнаруженные вами: беседа передаётся параметром запроса (?conv=), как во всех
остальных вызовах этой службы, и завершающий PATCH отвечает 200 с телом вложения вместо
пустого 204 — клиенту нужны идентификатор, размеры и признак превью, чтобы нарисовать
сообщение, а лишний круг на плохой связи стоит дороже отступления.
Три правила, на которые можно опираться:
- Идентификатор вложения равен идентификатору сессии. Если завершающий
PATCHдошёл, а ответ на него — нет, файл уже загружен: используйте тот идентифика тор, который у вас есть, вместо повторной отправки. ПовторныйPATCHответит404, потому что сессии больше нет. - Смещение, которое назвала служба, — это то, что она держит. Байт подтверждается после того, как записан, и никогда до.
- Неверное смещение ничего не пишет.
409, кодupload_offset_mismatch, и в ответе — смещение, с которого продолжать. - Пишущий один. Второй одновременный
PATCHполучает409с кодомupload_busy: спроситеHEADи продолжайте, а не начинайте заново.
Предел размера проверяется при открытии сессии, по Upload-Length, а не после того, как файл
прошёл по сети. Незавершённая сессия живёт сутки, потом её убирает уборщик — вместе с тем, что
уже лежит в хранилище.
Скачивание, докачка и то, как файл выглядит до того, как пришёл
GET /v1/uploads/{id} (и ?thumb=1) — обычный HTTP-ресурс: Range → 206 с Content-Range,
Accept-Ranges: bytes; сильный ETag (у файла и у его превью — разные); If-Range с ним
отвечает 206 для того же файла и 200 со всем телом для другого — никогда кусок чужого;
If-None-Match отвечает 304. Байты вложения не меняются никогда (новый файл — новый
идентификатор), поэтому Cache-Control говорит immutable.
Метаданные вложения несут то, что клиент рисует ещё до первого байта: width и height (после
поворота по EXIF), has_thumb (превью до 512 px лежит по ?thumb=1) и preview — base64 JPEG
не больше 32 px и не больше 1 КБ, который рисуется сразу, растянутым и размытым. Файлы диска
(…/nodes/{id}/content, ETag — sha256 содержимого) отвечают так же, их узлы несут те же
четыре поля, превью — по …/nodes/{id}/thumb.
Чего этот документ не описывает
Собственный API координатора (политики доступа, шлюзы, встречи) и вход у каталога — отдельные
поверхности с теми же правилами; они описаны в справочнике эндпоинтов
(координатор, каталог). Пропуск в звонок беседы —
POST /v1/calls/token этой службы, у координатора такой двери нет.
Федерация между установками описана со стороны администратора в
отдельной статье.