IDEC

Содержание

ВНИМАНИЕ! Это черновик стандарта.

1. Общее описание

IDEC - стандарт обмена текстовыми сообщениями. Обмен построен на простой сверке списков и запросе недостающих сообщений.

2. Протокол

Реализация протокола может строиться поверх любого протокола обмена текстом с поддержкой кодировки UTF-8. Часть запросов, достаточная для полноценного обмена, может работать в семибитных средах передачи сообщений. Данное описание строится на примере протокола HTTP, как самого используемого на момент написания документации. Однако, HTTP лишь один из возможных способов передачи информации для IDEC.

2.1. Разделитель строк

В качестве разделителя строк в индексах, сообщениях и бандлах используется символ \n (0x0A).

2.2. /e/

Запрашивает индекс сообщений с аплинка для одной конференции. Возвращает список msgid (идентификаторов сообщений) в порядке получения их узлом.

2.2.1. Запрос

GET /e/area.name

2.2.2. Ответ

msgid0
msgid1
msgid2
...
msgidN

Ответ завершается символом переноса строки.

2.3. /m/

Запрашивает одно сообщение с аплинка в некодированом виде. Возвращает текст сообщения в стандартном для ii/IDEC формате (см. формат сообщения).

2.3.1. Запрос

GET /m/msgid

2.3.2. Ответ

ii/ok/repto/IZXhLBKJx0rhx0lXYu3L
im.16
1455789357
Vasya
Lunar,2
Pupkin
Re: Мое первое сообщение в эху

текст сообщения

2.4. /u/e/

Запрашивает индекс сообщений с аплинка для списка конференций. Возвращает список msgid в порядке получения их узлом. Индекс каждой конференции предваряется её именем.

2.4.1. Запрос

GET /u/e/area.one/area.two

2.4.2. Ответ

area.one
msgid0
msgid1
msgid2
...
msgidN
area.two
msgid3
msgid4
msgid5
...
msgidK

Ответ завершается символом переноса строки.

Также можно запросить частичный индекс через механизм слайсов (срезов индекса). Для запроса слайса достаточно в конце запроса добавить смещение начала слайса и количество запрашиваемых сообщений, разделённых двоеточием. Смещение может быть отрицательным. В этом случае оно будет отсчитываться от конца списка сообщений. Например,

Нумерация сообщений в смещении начинается с нуля. Первый msgid имеет индекс 0, последний — -1.

Количество сообщений указывается от 0 до произвольного числа. Если количество равно нулю, индекс строится от смещения до конца. Если сумма смещения и количества превышает фактическу ю длину индекса на узле, отдаются все msgid от смещения до конца индекса.

/u/e/area.one/area.two/0:10 запрашивает первые десять сообщений в индексе, а /u/e/area.one/area.two/-10:10 запрашивает последние десять сообщений в индексе.

2.5. /u/m/

Запрашивает бандл (см. бандл) сообщений с аплинка. Каждая строка бандла состоит из msgid и сообщения, кодированного посредством base64, разделённых двоеточием.

2.5.1. Запрос

GET /u/m/msgid0/msgid1/msgid2/.../msgidN

2.5.2. Ответ

msgid0:BASE64_STRING
msgid1:BASE64_STRING
msgid2:BASE64_STRING
...
msgidN:BASE64_STRING

Ответ завершается символом переноса строки.

Узел должен обеспечивать запрос 40 сообщений в одном запросе /u/m. Клиент может запрашивать меньше, но узел должен обеспечивать передачу именно 40 сообщений за запрос.

2.6. /u/point/

Отправка пользовательского сообщения для регистрации узлом сети.

2.6.1. Запрос

GET /u/point/pauth/tmsg или POST /u/point

Поля:

  • pauth — строка аутентификации пользователя;
  • tmsg — кодированное BASE64 сообщение.

В случае отправки через GET-запрос поле tmsg обязательно должно быть кодировано в urlsafe BASE64.

В POST-запросе параметры называются так же: pauth и tmsg.

2.6.2. Ответ

  1. В случае успешной отправки

    msg ok

  2. В случае ошибки

    error: <сообщение об ошибке>

2.7. /u/push/

Отправляет бандл сообщений на узел. Используется в случае, если узел сети не может быть аплинком. Например, не имеет статического внешнего IP-адреса.

2.7.1. Запрос

POST /u/push

Параметры запроса:

  • nauth — строка авторизации узла;
  • upush — бандл сообщений;
  • echoarea — конференция, в которую отправляются сообщения.

Строка авторизации узла не является строкой аутентификации пользователя.

С помощью /u/point пользователь отправляет одно сообщение, с помощь. /u/push один узел сети отправляет произвольное множество сообщений другому узлу.

2.7.2. Ответ

  1. В случае успешного принятия сообщения

    message saved: ok

  2. В случае ошибки

    error: <сообщение об ошибке>

  3. В случае ошибки авторизации

    error: no auth

2.8. /list.txt

Возвращает список конференций узла. Может содержать не все конференции, существующие на узле, на усмотрение оператора. Содержит название конференции, количество сообщений в ней, за вычетом помещённых в чёрный список (см. blacklist.txt), и краткое описание разделённые двоеточием. В описании допускается использование символа двоеточия.

2.8.1. Запрос

GET /list.txt

2.8.2. Ответ

area.one:count:description
area.two:count:description
...
area.nth:count:description

Ответ завершается символом переноса строки.

2.9. /blacklist.txt

Возвращает чёрный список узла. Сообщения из чёрного списка не отдаются даунлинкам, не принимаются от аплинков и не учитываются при подсчёте количества сообщений в конференции.

2.9.1. Запрос

GET /blacklist.txt

2.9.2. Ответ

msgid0
msgid1
msgid2
...
msgidN

Ответ завершается символом переноса строки.

3. Название конференции

Может содержать от 3 до 120 символов: строчные буквы английского алфавита, цифры, символы подчёркивания, минуса и точки. Обязано содержать хотя бы одну точку.

4. Формирование идентификатора сообщения

Идентификатор сообщения должен быть уникальным для всей сети. Для формирования идентификатора используются первые 20 символов base64 строки, полученной из sha256-bin хеша сохранённого узлом сообщения в виде сообщения сети (см. формат сообщения).

Символы плюс и слеша (+ и /) либо их аналоги (- и _) заменяются на буквы A и z соответственно.

5. Формат сообщения

Строка Поле Описание
1 tags теги (используются только для repto и для идентификатора ii/ok)
2 area основная конференция, в которую помещается сообщение
3 date число секунд от эпохи unix, в UTC
4 msgfrom отправитель
5 addr адрес отправителя
6 msgto пользователь, которому предназначено сообщение (либо All)
7 subj тема сообщения
8 - пустая строка
9 и далее msg текст сообщения

Если сообщение не является ответом на другое сообщение, то строка тегов имеет вид:

ii/ok

иначе:

ii/ok/repto/msgid, где msgid — идентификатор исходного сообщения.

Адрес отправителя представляет собой имя узла сети и номер поинта, разделённых запятой без пробела. например, tavern,1.

6. Формат отправляемого поинтом сообщения

Строка Поле Описание
1 area конференция, в которую помещается сообщение
2 msgto пользователь, которому вы пишете (либо All, если обращаетесь ко всем)
3 subj тема сообщения
4 - пустая строка
5 repto если начинается с @repto:, то нода проставляет тэг repto (указывает msgid исходного сообщения).
    Иначе строка относится к тексту сообщения
6 и далее msg текст сообщения

При получении сообщения от поинта, узел преобразует его в формат сообщения сети, присваивает ему msgid и сохраняет в своей базе сообщений.

Если указанной конференции на узле не существует, узел должен её создать и сохранить сообщение в неё.

7. Бандл сообщений

Бандл сообщений используется для передачи произвольного количества сообщений в одном запросе. Также может использоваться для передачи сообщений любым другим способом в виде простого файла. Представляет собой msgid и кодированное сообщение, разделённое символом двоеточия. 

msgid0:BASE64_STRING
msgid1:BASE64_STRING
msgid2:BASE64_STRING
...
msgidN:BASE64_STRING

Завершается символом переноса строки.