idec-doc/main.org

IDEC

• Конференции и сообщения
  • Имя конференции
  • Идентификатор сообщения
  • Конференция
• Обмен сообщениями
• Формат сообщения
  • Пример сообщения
• Бандл
  • Формат бандла
• Формат отправляемых сообщений
  • Пример отарвляемого сообщения
• API
  • Индекс конференции
  • Сообщение
  • Индекс нескольких конференций
  • Бандл сообщений
  • Отправка сообщения клиентов
  • Ограничение на размер сообщения
• Расширенный API
  • Количество сообщений в конференциях
  • PUSH, обратная синхронизация
  • Список конференций
  • Чёрный список
  • Сокращённый индекс конференций
  • Размещение файлов
    • Получение списка файлов
    • Получение файлов
  • Файловые конференции
  • Список файловых конференций
  • Чёрный список файлов
  • Список файлов в файловых конференциях
  • Получение файла из файловой конференции
  • Отправка файлов в файловую конференцию
  • Количество файлов в конференции
  • Список расширений

Конференции и сообщения

Имя конференции

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

Примеры: pipe.2032, idec.talks.

Идентификатор сообщения

Каждое сообщение в сети имеет уникальный идентификатор, который генерируется сервером в момент получения сообщения от клиента.

Идентификатор сообщения представляет собой первые 20 символов base64 sha256-bin хэша сообщения. В этой строке производится замена символов - на A и _ на Z.

Конференция

Представляет собой список идентификаторов сообщений, расположенных в порядке попадания на сервер.

Обмен сообщениями

Обмен сообщениями осуществляется через получение списка идентификаторов конференции и сверку с локальной базой. Недостающие сообщения запрашиваются у сервера и сохраняются.

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

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

Пример сообщения

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

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

Бандл

Бандл - формат сообщений с уже имеющимися идентификаторами. Используется для загрузки сообщений через схему u/e или для отправки сообщений сервером на сервер с помощью метода u/push (см. ниже).

Формат бандла

msgid:encoded_message
msgid:encoded_message
msgid:encoded_message
и так далее

где msgid — уникальный идентификатор сообщения, а encoded_mesdssage это сообщение в текстовом представлении, кодированное алгоритмом base64. Все серверы обязаны принимать как обычный, так и urlsafe-словарь (см. описание base64).

Формат отправляемых сообщений

Клиенты отправляют сообщения в более простом формате:

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

Пример отарвляемого сообщения

pipe.2032
All
Тестируем

@repto:2hEUbMAxKSA83vcmgU4s
И вот я пишу своё первое письмо в нашу секту.
Меня видно?

API

Индекс конференции

GET /e/<конференция> Передаёт список идентификаторов сообщений указанной конференции.

Сообщение

GET /m/<идентификатор сообщения> Передаёт указанное сообщение в текстовом виде

Индекс нескольких конференций

GET /u/e/<список конференций> Передаёт список идентификаторов сообщений указанных конференций. Конференции в запросе разделяются косой чертой.

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

idec.talks
OjU4mxENGATlllgsLv09
Tx7xf96bpRhHSeM3cqYf
z5r9E9vNvX4Z7qgXRGmF
NgJwEzpkMGrwV3nvOahs
k9DH6B5APwiAlXgo9ZZh

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

GET /u/m/<список идентификаторов сообщений>

Передаёт бандл с указанными сообщениями (см. бандл).

Отправка сообщения клиентов

GET /u/point/<строка авторизации>/<кодированное сообщение> или POST /u/point.

Передаёт пользовательское сообщение на сервер.

<строка авторизации> — строка авторизации клиента. <кодированное сообщение> — отправляемое сообщение в кодировке base64. В случае отправки сообщения посредством POST-запроса, параметры называются pauth для строки авторизации и tmsg для кодированного сообщения.

Ограничение на размер сообщения

Максимальный размер base64-кодированного сообщения — 87372 байта, что соответствует 64 килобайтам для исходного сообщения.

В случае удачной отправки, сервер должен вернуть строку, начинающуюся с msg ok.

Расширенный API

Количество сообщений в конференциях

GET /x/c/<список конференций>

Возвращает информацию о количестве сообщений в указанных конференциях. Формат ответа:

pipe.2032:3553
idec.talks:1047

PUSH, обратная синхронизация

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

POST /u/push

Параметры в теле POST-запроса:

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

Список конференций

GET /list.txt

Возвращает список конференций с количеством сообщений и кратким описанием. Например,

idec.talks:1047:Обсуждение технологии и сети
pipe.2032:3553:Болталка

Чёрный список

GET /blacklist.txt

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

Сокращённый индекс конференций

GET /u/e/<список конференций>/<смещение>:<количество сообщений>

Смещение может быть отрицательным. В таком случае смещение считается с конца списка идентификаторов сообщений. Например /u/e/idec.talks/-5:5 возьмёт пять последних сообщений в конференции idec.talks.

Размещение файлов

Системный оператор сервера может размещать файлы. Файлы могут быть общедоступными, доступными только для клиентов сервера и доступны индивидуально каждому клиенту отдельно. Со стороны клиента доступ ко всем файлом осуществляется одинаково.

Получение списка файлов

POST /x/filelist или GET /x/filelist/pauth

Параметр pauth как в POST-, так и в GET-запросе содержит строку авторизации клиента. Если строка авторизации проходит проверку на сервере, то к списку общедоступных файлов добавляются скрытые файлы.

В ответе содержится информация о доступных файлах. Например,

haiku_caesium.png:22368:Цезий под Haiku OS
hotdoged0.png:83425:Редактор HotdogEd

Получение файлов

POST /x/file или GET /x/file/filename

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

• pauth — строка авторизации;
• filename — имя запрашиваемого файла.

Файловые конференции

Механизм распространения файлов пользователями сети похож на механизм распространения текстовых конференций.

Имя файловой конференции — от 3 до 120 символов. Допустимо использование латинских букв, цифр, символов подчёркивания, минуса и точки. В отличие от текстовых конференций, наличие точки в имени не является обязательным.

Список файловых конференций

GET /f/list.txt

Ответ аналогичен ответу сервера на запрос /list.txt:

books.tech:14:Техническая литература
music:45:Музыка
pictures:39:Картинки
books:33:Художественная литература

Чёрный список файлов

По аналогии с сообщениями, оператор сервера также может вносить в чёрный список файлы.

GET /f/blacklist.txt

Возвращает список идентификаторов файлов по одному в строке.

Список файлов в файловых конференциях

GET /f/e/<список файловых конференций>

Ответ:

fid:filename:size:address:description

Описание полей:

• fid — идентификатор файла, представляющий собой хэш содержимого файла, сформированный по тем же правилам, что и идентификатор сообщения;
• filename — имя файла, ограничено длинной 120 символов;
• size — размер файла в байтах;
• address — адрес отправителя файла;
• description — краткое описание файлв, ограничено 1024 символами. Если в описании встречается символ :, то он относится именно к описанию.

Пример ответа:

pictures
mUHFSUWA0CEt5nkFhHCV:sunvox_screenshot.png:42638:tavern,1:Скриншот sunvox'а
SGNtswGoVuol2e9Zo1JM:twilight_sparkle_with_ak_74_by_kebzone-d5v46ll.png:221376:mira, 1:test picture
COVuRckMwrAqVG9ixLtZ:evening_emacs.jpg:364649:tavern,1:Вечером за emacs'ом
music
HtgILK6ds9KBVdvZMAM0:Mellow-D.zip:83548476:tavern,1:Mellow-D's modules
C8ryyhK26A80Q1J0T3Fn:Mortimer_Twang.zip:31541274:tavern,1:Mortimer Twang. Amiga mods.
jSIAEx7M8ESNooTnBdGB:Necros.zip:39524876:tavern,1:Necros's mods

Отличить имя файловой конференции от записи о файла просто — в имени конференции не может встречаться символ :.

Метод /f/e поддерживает сокращённый индекс по аналогии схеме /u/e (см. выше).

Получение файла из файловой конференции

GET /f/f/<файловая конференция>/<идентификатор файла>

Возвращает указанный файл из указанной конференции.

Отправка файлов в файловую конференцию

POST /f/p

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

• pauth — строка авторизации клиента;
• fecho — имя файловой конференции;
• file — отаравляемый файл; имя файлоа ограничено 120 символами; допустимы латинские буквы, цифры, точки, подчёркивание, минус;
• dsc — описание файла в кодировке UTF-8.

Количество файлов в конференции

GET /f/c/<список конференций>

Ответ схож с тем, что сервер возвращает на запрос /x/c:

pictures:39
books.tech:14

Список расширений

Возвращает расширения, поддерживаемые сервером.

GET /x/features

Перечень возможностей:

• u/e — сокращённый индекс конференций;
• list.txt — список конференций;
• blacklist.txt — чёрный список сообщений;
• x/file — файловые запросы;
• x/c — количество сообщений в конференциях;
• f/ — файловые конференции.