 fox
II/IDEC networks :: idec.spec :: / feed
|
Login |
[>]
Описание протокола
idec.spec
gornekib(fox,1) — All
2024-11-20 16:45:21
Источник https://git.luxferre.top/tii/file/ii-doc.txt.html
1 ii protocol documentation
2 =========================
3 This document describes the basic ii protocol, as implemented in tii.
4 It aims to be as clear and concise as possible.
5
6 Network structure
7 -----------------
8 Clients aka points can:
9 * post messages
10 * fetch echos (conferences) and their message ID lists
11 * fetch messages by their IDs
12
13 Nodes aka stations can:
14 * accept (or reject) posted messages from points
15 * serve echo lists
16 * serve echos and their indexes (message ID lists)
17 * serve message bundles or single messages
18 * fetch echos and messages from other stations
19
20 The main transport protocol is currently HTTP/HTTPS, although the spec doesn't
21 theoretically limit the ways of message transfer. E.g. fetching can be easily
22 implemented over Gopher/Finger/Nex/Spartan/Gemini etc.
23
24 The API spec below is given for the HTTP(S) protocol.
25
26 Echo and message naming convention
27 ----------------------------------
28 Within the network, echo names must be from 3 to 120 characters long and have
29 at least one dot (.) character. Message IDs must be exactly 20 characters long
30 and depend on the message contents hash upon posting (see the exact algorithm
31 below in the "Message ID generation algorithm" section).
32
33 Station (node) HTTP API
34 -----------------------
35 Every station must implement the following HTTP API calls.
36 In case of multi-line responses, the newline separator must be "\n" character
37 (line feed, ASCII 10).
38 All station responses must end with a newline separator.
39
40 - Fetching the public echo list -
41
42 Request: GET /list.txt
43 Response: newline-separated list of echo_name:msg_count:echo_description
44
45 Note: the msg_count field must reflect the actual non-blacklisted message
46 count that the station can serve.
47
48 - Fetching the public message blacklist -
49
50 Request: GET /blacklist.txt
51 Response: newline-separated list of message IDs
52
53 The blacklisted message IDs must not be served to the clients in any of the
54 API calls specified below.
55
56 - Listing messages in a single echo -
57
58 Request: GET /e/echo.name
59 Response: newline-separated message ID list
60
61 When a new message is posted to the echo, it gets appended to the end of the
62 corresponding message ID list for this echo.
63
64 The message order in an echo does not always match the timestamp ordering;
65 it is fully up to the client on how to sort the messages internally. The
66 messages are only guaranteed to be saved by the server in the order they
67 arrive onto the server.
68
69 - Listing messages in any amount of echos -
70
71 Request: GET /u/e/echo.1.name/echo.2.name/...
72 Limited request: GET /u/e/echo.1.name/echo.2.name/.../offset:limit
73 Response: newline-separated list of echo names and message IDs in the format:
74
75 echo.1.name
76 msgid1fromecho1
77 msgid2fromecho1
78 ...
79 echo.2.name
80 msgid1fromecho2
81 msgid2fromecho2
82 ...
83
84 In case of limited request, the offset can be negative. E.g. -10:10 means
85 requesting last 10 messages from the index. If the offset:limit pair is not
86 valid for a particular echo, all message IDs from this echo are returned.
87
88 The same message ID ordering rule as for /e applies to /u/e as well.
89
90 - Fetching a single message by its ID -
91
92 Request: GET /m/msgid
93 Response: plaintext message in the Node-to Point Message format
94
95 - Fetching a message bundle -
96
97 Request: GET /u/m/msgid1/msgid2/...
98 Response: newline-separated list of msgid:base64_msgtext
99
100 Here, base64_msgtext is a Base64-encoded Node-to-Point Message (see below).
101 The standardized ID count limit is at most 40 messages per bundle.
102
103 - Posting a message (via POST) -
104
105 Request: POST /u/point
106 Content-Type: application/x-www-form-urlencoded
107 Data: pauth=auth_string&tmsg=base64_msgtext
108 Response: in case of success, must start with "msg ok", otherwise with "error"
109
110 Here, auth_string is the user's authorization string and base64_msgtext is the
111 Base64-encoded Point-to-Node Message (see below).
112 The maximum length of the tmsg field must be 87382 bytes.
113
114 - Posting a message (via GET) -
115
116 Request: GET /u/point/auth_string/base64_msgtext
117 Response: in case of success, must start with "msg ok", otherwise with "error"
118
119 Here, auth_string is the user's authorization string and base64_msgtext is the
120 Base64URL-encoded Point-to-Node Message.
121 The maximum length of the tmsg field must be 87382 bytes.
122
123 Note: the Base64URL encoding means that after the standard Base64 encoding,
124 the + character is replaced with -, the / character is replaced with _, and
125 the = character is omitted from the end.
126
127 - Pushing a message bundle to another node -
128
129 Request: POST /u/push
130 Content-Type: application/x-www-form-urlencoded
131 Data: nauth=auth_string&upush=bundle_contents&echoarea=echo.name
132 Response: in case of success, must start with "message saved: ok", otherwise
133 with "error:"
134
135 Here, auth_string is the node authorization string and bundle_contents is the
136 message bundle in the exact format as received by GET /u/m API method.
137
138 Node-to-Point Message format
139 ----------------------------
140 The encoding must be UTF-8 and the newline separator must be "\n" (ASCII 10).
141 Every Node-to-Point message contains the following fields in this particular
142 order, all of them are mandatory and start on a new line each:
143
144 * Line 1: message tags. Must start with "ii/ok". If "ii/ok/repto/id" form is
145 encountered, then the id refers to the message this message replies to.
146 * Line 2: echo name where the message was posted.
147 * Line 3: message Unix timestamp (integer, in seconds, UTC)
148 * Line 4: message sender name
149 * Line 5: message sender address (autofilled by the originating station)
150 * Line 6: message recipient name (or All if there's no particular recipient)
151 * Line 7: message subject
152 * Line 8: must be empty
153 * Line 9 and further: message body
154
155 Point-to-Node Message format
156 ----------------------------
157 The encoding must be UTF-8 and the newline separator must be "\n" (ASCII 10).
158 Every Point-to-Node message contains the following fields in this particular
159 order, all of them are mandatory and start on a new line each:
160
161 * Line 1: echo name where the message is being posted.
162 * Line 2: message recipient name (or All if there's no particular recipient)
163 * Line 3: message subject
164 * Line 4: must be empty
165 * Line 5 and further: message body
166
167 If you are replying to a message [msgid], then message body must begin with:
168
169 @repto:msgid
170
171 and the message text itself must start on the next line.
172
173 Message ID generation algorithm
174 -------------------------------
175 This algorithm must be implemented by every station to generate message IDs:
176
177 1. Calculate SHA256 of the message in the Node-to-Point format as binary data.
178 2. Calculate Base64 of the resulting binary hash sum.
179 3. Truncate to the first 20 characters.
180 4. Replace all occurrences of + or - with A, and / or _ with z.
181 5. The result of these operations is your ii message ID.
182
183 --- Luxferre ---
idec.spec
gornekib(fox,1) — All
2024-11-20 16:45:21
Источник https://git.luxferre.top/tii/file/ii-doc.txt.html
1 ii protocol documentation
2 =========================
3 This document describes the basic ii protocol, as implemented in tii.
4 It aims to be as clear and concise as possible.
5
6 Network structure
7 -----------------
8 Clients aka points can:
9 * post messages
10 * fetch echos (conferences) and their message ID lists
11 * fetch messages by their IDs
12
13 Nodes aka stations can:
14 * accept (or reject) posted messages from points
15 * serve echo lists
16 * serve echos and their indexes (message ID lists)
17 * serve message bundles or single messages
18 * fetch echos and messages from other stations
19
20 The main transport protocol is currently HTTP/HTTPS, although the spec doesn't
21 theoretically limit the ways of message transfer. E.g. fetching can be easily
22 implemented over Gopher/Finger/Nex/Spartan/Gemini etc.
23
24 The API spec below is given for the HTTP(S) protocol.
25
26 Echo and message naming convention
27 ----------------------------------
28 Within the network, echo names must be from 3 to 120 characters long and have
29 at least one dot (.) character. Message IDs must be exactly 20 characters long
30 and depend on the message contents hash upon posting (see the exact algorithm
31 below in the "Message ID generation algorithm" section).
32
33 Station (node) HTTP API
34 -----------------------
35 Every station must implement the following HTTP API calls.
36 In case of multi-line responses, the newline separator must be "\n" character
37 (line feed, ASCII 10).
38 All station responses must end with a newline separator.
39
40 - Fetching the public echo list -
41
42 Request: GET /list.txt
43 Response: newline-separated list of echo_name:msg_count:echo_description
44
45 Note: the msg_count field must reflect the actual non-blacklisted message
46 count that the station can serve.
47
48 - Fetching the public message blacklist -
49
50 Request: GET /blacklist.txt
51 Response: newline-separated list of message IDs
52
53 The blacklisted message IDs must not be served to the clients in any of the
54 API calls specified below.
55
56 - Listing messages in a single echo -
57
58 Request: GET /e/echo.name
59 Response: newline-separated message ID list
60
61 When a new message is posted to the echo, it gets appended to the end of the
62 corresponding message ID list for this echo.
63
64 The message order in an echo does not always match the timestamp ordering;
65 it is fully up to the client on how to sort the messages internally. The
66 messages are only guaranteed to be saved by the server in the order they
67 arrive onto the server.
68
69 - Listing messages in any amount of echos -
70
71 Request: GET /u/e/echo.1.name/echo.2.name/...
72 Limited request: GET /u/e/echo.1.name/echo.2.name/.../offset:limit
73 Response: newline-separated list of echo names and message IDs in the format:
74
75 echo.1.name
76 msgid1fromecho1
77 msgid2fromecho1
78 ...
79 echo.2.name
80 msgid1fromecho2
81 msgid2fromecho2
82 ...
83
84 In case of limited request, the offset can be negative. E.g. -10:10 means
85 requesting last 10 messages from the index. If the offset:limit pair is not
86 valid for a particular echo, all message IDs from this echo are returned.
87
88 The same message ID ordering rule as for /e applies to /u/e as well.
89
90 - Fetching a single message by its ID -
91
92 Request: GET /m/msgid
93 Response: plaintext message in the Node-to Point Message format
94
95 - Fetching a message bundle -
96
97 Request: GET /u/m/msgid1/msgid2/...
98 Response: newline-separated list of msgid:base64_msgtext
99
100 Here, base64_msgtext is a Base64-encoded Node-to-Point Message (see below).
101 The standardized ID count limit is at most 40 messages per bundle.
102
103 - Posting a message (via POST) -
104
105 Request: POST /u/point
106 Content-Type: application/x-www-form-urlencoded
107 Data: pauth=auth_string&tmsg=base64_msgtext
108 Response: in case of success, must start with "msg ok", otherwise with "error"
109
110 Here, auth_string is the user's authorization string and base64_msgtext is the
111 Base64-encoded Point-to-Node Message (see below).
112 The maximum length of the tmsg field must be 87382 bytes.
113
114 - Posting a message (via GET) -
115
116 Request: GET /u/point/auth_string/base64_msgtext
117 Response: in case of success, must start with "msg ok", otherwise with "error"
118
119 Here, auth_string is the user's authorization string and base64_msgtext is the
120 Base64URL-encoded Point-to-Node Message.
121 The maximum length of the tmsg field must be 87382 bytes.
122
123 Note: the Base64URL encoding means that after the standard Base64 encoding,
124 the + character is replaced with -, the / character is replaced with _, and
125 the = character is omitted from the end.
126
127 - Pushing a message bundle to another node -
128
129 Request: POST /u/push
130 Content-Type: application/x-www-form-urlencoded
131 Data: nauth=auth_string&upush=bundle_contents&echoarea=echo.name
132 Response: in case of success, must start with "message saved: ok", otherwise
133 with "error:"
134
135 Here, auth_string is the node authorization string and bundle_contents is the
136 message bundle in the exact format as received by GET /u/m API method.
137
138 Node-to-Point Message format
139 ----------------------------
140 The encoding must be UTF-8 and the newline separator must be "\n" (ASCII 10).
141 Every Node-to-Point message contains the following fields in this particular
142 order, all of them are mandatory and start on a new line each:
143
144 * Line 1: message tags. Must start with "ii/ok". If "ii/ok/repto/id" form is
145 encountered, then the id refers to the message this message replies to.
146 * Line 2: echo name where the message was posted.
147 * Line 3: message Unix timestamp (integer, in seconds, UTC)
148 * Line 4: message sender name
149 * Line 5: message sender address (autofilled by the originating station)
150 * Line 6: message recipient name (or All if there's no particular recipient)
151 * Line 7: message subject
152 * Line 8: must be empty
153 * Line 9 and further: message body
154
155 Point-to-Node Message format
156 ----------------------------
157 The encoding must be UTF-8 and the newline separator must be "\n" (ASCII 10).
158 Every Point-to-Node message contains the following fields in this particular
159 order, all of them are mandatory and start on a new line each:
160
161 * Line 1: echo name where the message is being posted.
162 * Line 2: message recipient name (or All if there's no particular recipient)
163 * Line 3: message subject
164 * Line 4: must be empty
165 * Line 5 and further: message body
166
167 If you are replying to a message [msgid], then message body must begin with:
168
169 @repto:msgid
170
171 and the message text itself must start on the next line.
172
173 Message ID generation algorithm
174 -------------------------------
175 This algorithm must be implemented by every station to generate message IDs:
176
177 1. Calculate SHA256 of the message in the Node-to-Point format as binary data.
178 2. Calculate Base64 of the resulting binary hash sum.
179 3. Truncate to the first 20 characters.
180 4. Replace all occurrences of + or - with A, and / or _ with z.
181 5. The result of these operations is your ii message ID.
182
183 --- Luxferre ---
[>]
Описание протокола
idec.spec
gornekib(fox,1) — All
2024-11-20 17:23:18
источник https://github.com/idec-net/new-docs/blob/master/standarts.md
Стандарт и его реализация
=========================
Эхи и сообщения
---------------
**Имя эхи** - от 3 до 120 символов: маленькие латинские буквы, цифры, символы подчёркивания, минуса и точки. Название должно содержать минимум одну точку. В старых версиях обязано заканчиваться на точку и число.
Примеры правильных названий эх: 1.1 ii.14 ii.about.14 to.ivan.15, my.beseda
**Id сообщения (msgid)** - уникальный номер, который генерируется станцией, как 20 первых символов base64 sha256-bin хэша сообщения.
Примечание: production-реализации нод заменяют в полученной base64-строке плюс (+) и слэш (/) либо их аналоги (- и _) на буквы "A" и "Z" соответственно, дабы убрать из msgid спецсимволы.
Сама эха представляет собой изнутри всего лишь список (массив) msgid, расположенных в определённом порядке. После каждого написанного/принятого сообщения его msgid добавляется в конец этого списка.
База данных
-----------
Простейшая база данных реализации IDEC и ii состоит из двух каталогов: echo/ и msg/. В msg/ хранятся сами сообщения (имя файла = msgid). В echo/ хранятся индексы сообщений, т.е. файлы эхоконференций (имя файла = название эхи).
Файл в echo/<эха> состоит из списка имён файлов сообщений, находящихся в msg/, по порядку, в конце пустая строка. Из-за простой структуры базы данных сообщения можно передавать даже оффлайн, на флешке: достаточно лишь положить сообщение в msg/ и в файле эхоконференции прописать его хэш (вручную или простейшим скриптом).
Хранить файлы на самом деле можно и в json, и в sqlite, и в любом другом формате на ваше усмотрение.
Получение данных
----------------
Получить данные из нужных эх может любой пользователь, авторизованный или нет. Сначала нужно получить список сообщений эхи, и потом загрузить недостающие сообщения, которых ещё нет в базе данных. Подобным образом могут получать данные любые поинты, и так же, настроив взаимное получение данных друг с друга, обмениваться между собой ноды. Подробности на странице протокола.
бандл (нод2нод)
---------------
Бандл - это полное, сформированное сообщение, уже имеющее идентификатор. Возможно, не одно.
По умолчанию, при распаковке, бандл создаёт все эхи, которые указаны в заголовках. То есть, распаковка бандла - это команда сохранить такое-то сообщение и прописать его во все эхи.
Бандлу не нужен онлайн. Можно создать бандл со всеми нужными сообщениями и передать его любым способом - после его распаковки в базе создадутся все сообщения.
Формат кодирования:
```
msgid:text
msgid:text
msgid:text
и так далее
```
где text - это просто текстовый файл самого сообщения, кодированный base64 (все серверы обязаны принимать как обычный, так и urlsafe-словарь, генерируются же бандлы в формате обычного base64). Разделитель для бандла - новая линия (LF, код 10).
Формат текста в бандле
----------------------
Строка Поле Описание
1 tags теги (используются только для repto и для идентификатора ii/ok)
2 echoarea основная эхоконференция, в которую помещается сообщение
3 date число секунд от эпохи unix, в utc
4 msgfrom отправитель
5 addr адрес отправителя (практического смысла не имеет, служит для того, чтобы узнавать, с какой станции пришло сообщение)
6 msgto пользователь, которому предназначено сообщение (либо All)
7 subj тема сообщения
8 - пустая строка
9 и далее msg текст сообщения
Формат тегов
------------
Строки, разделённые слешами. Сначала ключ, потом значение и так далее.
Образец: ii/ok/repto/fjLkfrmjNvO4fjzlUs5U
Тег ii/ok проставляется обязательно. Требуется для совместимости с ii.
Пример текста
-------------
```
ii/ok/repto/IZXhLBKJx0rhx0lXYu3L
im.16
1455789357
Vasya
Lunar, 2
Pupkin
Re: Мое первое сообщение в эху
текст сообщения
```
Сообщения, которые отправляют поинты (msgline)
----------------------------------------------
Перед отправкой этот файл кодируется base64.
Строка Поле Описание
1 echoarea эхоконференция, в которую помещается сообщение
2 msgto пользователь, которому вы пишете (либо All, если обращаетесь ко всем)
3 subj тема сообщения
4 - пустая строка
5 repto если начинается с @repto:, то нода проставляет тэг repto (указывает id письма, на которое отвечаем). Иначе строка относится к тексту сообщения
6 и далее msg текст сообщения
Внимание!
Пустые поля (в том числе subj или msg) не допускаются.
В отличие от бандлов, в одном запросе нельзя передать сразу несколько сообщений.
Максимальный размер файла 64КБ (65536 байт) на полезную нагрузку (а в base64-виде - 4/3 от исходного, т.е. 87382 байт)
Пример
```
im.16
All
Тестируем
@repto:2hEUbMAxKSA83vcmgU4s
И вот я пишу своё первое письмо в нашу секту.
Меня видно?
```
idec.spec
gornekib(fox,1) — All
2024-11-20 17:23:18
источник https://github.com/idec-net/new-docs/blob/master/standarts.md
Стандарт и его реализация
=========================
Эхи и сообщения
---------------
**Имя эхи** - от 3 до 120 символов: маленькие латинские буквы, цифры, символы подчёркивания, минуса и точки. Название должно содержать минимум одну точку. В старых версиях обязано заканчиваться на точку и число.
Примеры правильных названий эх: 1.1 ii.14 ii.about.14 to.ivan.15, my.beseda
**Id сообщения (msgid)** - уникальный номер, который генерируется станцией, как 20 первых символов base64 sha256-bin хэша сообщения.
Примечание: production-реализации нод заменяют в полученной base64-строке плюс (+) и слэш (/) либо их аналоги (- и _) на буквы "A" и "Z" соответственно, дабы убрать из msgid спецсимволы.
Сама эха представляет собой изнутри всего лишь список (массив) msgid, расположенных в определённом порядке. После каждого написанного/принятого сообщения его msgid добавляется в конец этого списка.
База данных
-----------
Простейшая база данных реализации IDEC и ii состоит из двух каталогов: echo/ и msg/. В msg/ хранятся сами сообщения (имя файла = msgid). В echo/ хранятся индексы сообщений, т.е. файлы эхоконференций (имя файла = название эхи).
Файл в echo/<эха> состоит из списка имён файлов сообщений, находящихся в msg/, по порядку, в конце пустая строка. Из-за простой структуры базы данных сообщения можно передавать даже оффлайн, на флешке: достаточно лишь положить сообщение в msg/ и в файле эхоконференции прописать его хэш (вручную или простейшим скриптом).
Хранить файлы на самом деле можно и в json, и в sqlite, и в любом другом формате на ваше усмотрение.
Получение данных
----------------
Получить данные из нужных эх может любой пользователь, авторизованный или нет. Сначала нужно получить список сообщений эхи, и потом загрузить недостающие сообщения, которых ещё нет в базе данных. Подобным образом могут получать данные любые поинты, и так же, настроив взаимное получение данных друг с друга, обмениваться между собой ноды. Подробности на странице протокола.
бандл (нод2нод)
---------------
Бандл - это полное, сформированное сообщение, уже имеющее идентификатор. Возможно, не одно.
По умолчанию, при распаковке, бандл создаёт все эхи, которые указаны в заголовках. То есть, распаковка бандла - это команда сохранить такое-то сообщение и прописать его во все эхи.
Бандлу не нужен онлайн. Можно создать бандл со всеми нужными сообщениями и передать его любым способом - после его распаковки в базе создадутся все сообщения.
Формат кодирования:
```
msgid:text
msgid:text
msgid:text
и так далее
```
где text - это просто текстовый файл самого сообщения, кодированный base64 (все серверы обязаны принимать как обычный, так и urlsafe-словарь, генерируются же бандлы в формате обычного base64). Разделитель для бандла - новая линия (LF, код 10).
Формат текста в бандле
----------------------
Строка Поле Описание
1 tags теги (используются только для repto и для идентификатора ii/ok)
2 echoarea основная эхоконференция, в которую помещается сообщение
3 date число секунд от эпохи unix, в utc
4 msgfrom отправитель
5 addr адрес отправителя (практического смысла не имеет, служит для того, чтобы узнавать, с какой станции пришло сообщение)
6 msgto пользователь, которому предназначено сообщение (либо All)
7 subj тема сообщения
8 - пустая строка
9 и далее msg текст сообщения
Формат тегов
------------
Строки, разделённые слешами. Сначала ключ, потом значение и так далее.
Образец: ii/ok/repto/fjLkfrmjNvO4fjzlUs5U
Тег ii/ok проставляется обязательно. Требуется для совместимости с ii.
Пример текста
-------------
```
ii/ok/repto/IZXhLBKJx0rhx0lXYu3L
im.16
1455789357
Vasya
Lunar, 2
Pupkin
Re: Мое первое сообщение в эху
текст сообщения
```
Сообщения, которые отправляют поинты (msgline)
----------------------------------------------
Перед отправкой этот файл кодируется base64.
Строка Поле Описание
1 echoarea эхоконференция, в которую помещается сообщение
2 msgto пользователь, которому вы пишете (либо All, если обращаетесь ко всем)
3 subj тема сообщения
4 - пустая строка
5 repto если начинается с @repto:, то нода проставляет тэг repto (указывает id письма, на которое отвечаем). Иначе строка относится к тексту сообщения
6 и далее msg текст сообщения
Внимание!
Пустые поля (в том числе subj или msg) не допускаются.
В отличие от бандлов, в одном запросе нельзя передать сразу несколько сообщений.
Максимальный размер файла 64КБ (65536 байт) на полезную нагрузку (а в base64-виде - 4/3 от исходного, т.е. 87382 байт)
Пример
```
im.16
All
Тестируем
@repto:2hEUbMAxKSA83vcmgU4s
И вот я пишу своё первое письмо в нашу секту.
Меня видно?
```
[>]
Описание протокола
idec.spec
gornekib(fox,1) — All
2024-11-20 17:25:32
источник https://github.com/idec-net/new-docs/blob/master/protocol.md
Api обмена IDEC и ii, протокол
==============================
Протокол может быть реализован поверх чего угодно: будь то простые файлы, принесённые на физическом носителе, ssh, ftp, http или что-нибудь ещё. Пока что на практике применяется только его http-версия.
Схема параметров
----------------
Для обмена сообщениями в серверах используется понятие схемы параметров. Она представляет из себя строку, которая передаётся серверу через GET запрос, состоящую из слешей и того, что находится между ними. Пример: /u/e/echoname.100. Разные параметры этой схемы отвечают за разную выдачу или принятие информации сервером.
В настоящее время у нас используется схема /u/ (универсальная). /u/ - это запросы для обмена сообщениями, на которых и строится вся синхронизация.
О кодах ответов (в том числе об ошибках) ноды можно прочитать здесь.
Обработчики /u/
---------------
Вся синхронизация односторонняя. Две ноды просто собирают друг у друга сообщения. Пойнты же, наоборот, проталкивают свои письма, которые нода добавляет в общую БД сети, одобряя их (или не делает, не одобряя).
/u/e/эха.номер/эха.номер/эха.номер...
Список идентификаторов сообщений из заданных эхоконференций, в формате:
```
эха
msgid
msgid
msgid
эха
msgid
```
Отличить эху от id очень просто - в имени эхи есть точка, а в msgid - нет.
/u/m/msgid/msgid/msgid...
Бандл - основной способ получения сообщений на клиенте и при синхронизации серверов. Формат указан на странице стандартов.
GET /u/point/pauth/tmsg или POST /u/point
Передаёт пользовательское сообщение на ноду в виде запакованного текста base64 определённого формата. (если его передавать через GET-запрос, то оно там уже обязано быть base64-urlsafe).
pauth здесь - поинтовая строка авторизации (пароль), tmsg - закодированное base64 сообщение (см. msgline, стандарты). В случае POST параметры называются так же: pauth и tmsg.
Максимальный размер base64-кодированного сообщения - 87382 байт (соответствует 64КБ для исходного файла).
Нода должна вернуть в ответ строку начинающуюся с msg ok.
Другие схемы
------------
/e/эха.номер
Выдаёт файл определённой эхоконференции для просмотра вручную. В обмене не применяется.
/m/msgid
Выдаёт единственное сообщение (опять см. стандарты) в "сыром" виде (без base64). В обмене также не используется, служит для отладки.
idec.spec
gornekib(fox,1) — All
2024-11-20 17:25:32
источник https://github.com/idec-net/new-docs/blob/master/protocol.md
Api обмена IDEC и ii, протокол
==============================
Протокол может быть реализован поверх чего угодно: будь то простые файлы, принесённые на физическом носителе, ssh, ftp, http или что-нибудь ещё. Пока что на практике применяется только его http-версия.
Схема параметров
----------------
Для обмена сообщениями в серверах используется понятие схемы параметров. Она представляет из себя строку, которая передаётся серверу через GET запрос, состоящую из слешей и того, что находится между ними. Пример: /u/e/echoname.100. Разные параметры этой схемы отвечают за разную выдачу или принятие информации сервером.
В настоящее время у нас используется схема /u/ (универсальная). /u/ - это запросы для обмена сообщениями, на которых и строится вся синхронизация.
О кодах ответов (в том числе об ошибках) ноды можно прочитать здесь.
Обработчики /u/
---------------
Вся синхронизация односторонняя. Две ноды просто собирают друг у друга сообщения. Пойнты же, наоборот, проталкивают свои письма, которые нода добавляет в общую БД сети, одобряя их (или не делает, не одобряя).
/u/e/эха.номер/эха.номер/эха.номер...
Список идентификаторов сообщений из заданных эхоконференций, в формате:
```
эха
msgid
msgid
msgid
эха
msgid
```
Отличить эху от id очень просто - в имени эхи есть точка, а в msgid - нет.
/u/m/msgid/msgid/msgid...
Бандл - основной способ получения сообщений на клиенте и при синхронизации серверов. Формат указан на странице стандартов.
GET /u/point/pauth/tmsg или POST /u/point
Передаёт пользовательское сообщение на ноду в виде запакованного текста base64 определённого формата. (если его передавать через GET-запрос, то оно там уже обязано быть base64-urlsafe).
pauth здесь - поинтовая строка авторизации (пароль), tmsg - закодированное base64 сообщение (см. msgline, стандарты). В случае POST параметры называются так же: pauth и tmsg.
Максимальный размер base64-кодированного сообщения - 87382 байт (соответствует 64КБ для исходного файла).
Нода должна вернуть в ответ строку начинающуюся с msg ok.
Другие схемы
------------
/e/эха.номер
Выдаёт файл определённой эхоконференции для просмотра вручную. В обмене не применяется.
/m/msgid
Выдаёт единственное сообщение (опять см. стандарты) в "сыром" виде (без base64). В обмене также не используется, служит для отладки.
[>]
Описание протокола
idec.spec
gornekib(fox,1) — All
2024-11-20 17:32:27
источник https://github.com/idec-net/new-docs/blob/master/extensions.md
Расширения IDEC
===============
Здесь описаны расширения протокола, являющиеся основным отличием IDEC от ii. Многие из них реализовывать совсем необязательно.
Количество сообщений в эхоконференциях
--------------------------------------
Предназначен для отслеживания изменений в эхе и для отсеивания лишнего трафика. Обычное целое число. Важно: параметр неубывающий. Если в эхе удалили сообщения, то возвращаемое число не должно уменьшаться.
Метод
GET /x/с/<параметры>
Параметры
Единственный параметр метода - список, разделенный '/'.
Возвращаемое значение
Словарь "эха":"количество".
Пример
```
GET /x/c/test.14/im.100
test.14:221
im.100:1500
```
Push (пуш), обратная синхронизация
----------------------------------
Предназначен для получения сервером (нодой) сообщений от другого доверенного авторизованного сервера. Может быть полезным для транзитных гейтов-посредников или серверов с неработающим фетчингом. Хоть пуш и является частью /u/, он остаётся необязательным расширением.
Проще говоря, push - это бандл наоборот. Если фетчинг скачивает бандлы, то push их проталкивает на другой узел. Сначала у push-ноды запрашивается список сообщений, которые уже есть в эхе, а затем через /u/push загружаются недостающие.
Метод
POST /u/push
Параметры в теле POST запроса:
nauth - ключ для авторизации на сервере (пароль)
upush - бандл сообщений
echoarea - эхоконференция, в которую помещать сообщения
Возвращаемое значение
Может отличаться, в зависимости от сервера, либо отсутствовать. PHP-нода возвращает message saved: ok для каждого сообщения в бандле в случае успешного принятия, либо error: <название ошибки> в случае неправильного формата сообщений или error: no auth, если неправильный пароль.
Список эхоконференций
---------------------
Нужен для автоматического получения данных о наличии эх на станции. Может пригодиться для автоподписки на клиентах.
Метод
GET /list.txt
Возвращаемое значение
Словарь "эха":"количество сообщений":"описание эхи".
Пример
```
GET /list.txt
test.14:35:Тестирование и проверки
im.100:270:Болталка, общение на любые темы
```
Чёрный список
-------------
Номера тех сообщений, которые нода не принимает во время обмена и не показывает в эхоконференциях. Используется для чистки станции от спама/некорректных сообщений.
Метод
GET /blacklist.txt
Возвращаемое значение
Список номеров сообщений на каждой строке по одному.
Сокращённый индекс (расширенный /u/e)
-------------------------------------
Вариант схемы /u/e с указанием смещения и количества отдаваемых msgid. Полезно для экономии трафика, чтобы не скачивать абсолютно все сообщения с эхи, а только нужные.
Метод
/u/e/эха/эха/эха/.../<смещение>:<лимит> <Смещение> и <лимит> - целые числа. Смещение может быть отрицательным. Если параметры указаны ошибочно, выдаёт эхи целиком.
Возвращаемое значение
Список сообщений из заданных эхоконференций, с максимумом <лимит>.
Пример
```
GET /u/e/ii.test.14/test.15/1:2
ii.test.14
msgid
msgid
test.15
msgid
msgid
```
```
GET /u/e/ii.test.14/test.15/-5:5
ii.test.14
msgid
msgid
msgid
msgid
msgid
test.15
msgid
msgid
msgid
msgid
msgid
```
Список схем
-----------
Нужен, чтобы узнать, какие дополнительные возможности поддерживает станция.
Метод
GET /x/features
Пример
```
GET /x/features
x/c
list.txt
blacklist.txt
```
Полный перечень обозначения возможностей:
u/e — расширенная схема u/e
list.txt - список эхоконференций
blacklist.txt - чёрный список сообщений
x/file - файловые запросы
x/c - количество сообщений в эхе на ноде
f/ - файлэхоконференции
Размещение файлов
-----------------
Сисоп складывает разные файлы себе на ноду, а поинты (либо просто желающие) могут их скачивать.
Методы
POST /x/filelist или GET /x/filelist/pauth
Получение списка файлов в формате <Имя>:<Размер в байтах>:<Описание>. Параметр pauth - строка авторизации. Если pauth проходит проверку (существует поинт с таким паролем), то к публичному списку добавляется также список скрытых от посторонних глаз файлов.
POST /x/file или GET /x/file/filename
Параметры для запросов: pauth и filename. pauth - строка авторизации (передаётся всегда в POST), filename - имя скачиваемого файла.
Если filename отсутствует, то выдаётся ошибка. Если параметр pauth верный (т.е. пароль верный), то это даёт пользователю возможность скачивать скрытые файлы. Если файл публичный, то pauth может быть и неверным. Внимание: POST-параметры имеют приоритет перед GET.
Примеры
```
POST /x/filelist pauth=12345
myfile.txt:421:Интересная информация
cats.jpg:63253:Скрытый файл
```
POST /x/file pauth=12345;filename=cats.jpg
или
POST /x/file/cats.jpg pauth=12345
<Содержимое скрытого файла>
POST /x/file filename=myfile.txt
или
GET /x/file/myfile.txt
<Содержимое публичного файла>
GET /x/file/cats.jpg
<Ошибка, т.к. пароль не указан, а файл приватный>
Файлэхоконференции
------------------
Механизм распространения файлов пользователями сети по принципам, схожим с распространением эхоконференций.
Имя файлэхи - от 3 до 120 символов: маленькие латинские буквы, цифры, символы подчёркивания, минуса и точки.
Вся синхронизация односторонняя. Две ноды просто собирают друг у друга файлы. Пойнты же, наоборот, публикуют свои файлы, которые нода добавляет в общую БД сети, одобряя их (или не делает, не одобряя).
Метод
GET /f/c/test1/test2
Параметры
Единственный параметр метода - список, разделенный '/'.
Возвращаемое значение
Словарь "файлэха":"количество".
Пример
```
GET /f/c/test1/test2
test1:32
test2:17
```
Список файлэхоконференций
-------------------------
Аналог /list.txt для файлэхоконференций.
Метод
GET /f/list.txt
Возвращаемое значение
Словарь "фэха":"количество сообщений":"описание эхи".
Пример
```
GET /f/list.txt
books:35:Книги
pics:270:Картинки
```
Чёрный список для файлэх
------------------------
Хеши тех файлов, которые нода не принимает во время обмена и не показывает в файлэхоконференциях. Используется для чистки станции от спама/некорректных файлов.
Метод
GET /f/blacklist.txt
Возвращаемое значение
Список хешей файлов на каждой строке по одному.
Метод /f/e
----------
Возвращает список файлов с метаинформацией для указанных файлэхоконференций.
Возвращаемое значение
Список файлов из заданных файлэхоконференций.
Пример
```
GET /f/e/файлэха1/файлэха2
файлэха1
fid:filename:size:address:description
fid:filename:size:address:description
fid:filename:size:address:description
файлэха2
fid:filename:size:address:description
```
Где
fid — file ID, представляющий собой хеш содержимого файла, сформированный по тем же правилам, что и msgid.
filename — имя файла, ограничено длиной 120 символов
size — размер файла в байтах
address — адрес отправителя файла
description — краткое описание файла, ограничено 1024 символами. Если в файл-строке и дальше встречаются двоеточия-разделители с информацией, то весь текст после них идёт в счёт description.
Отличить фэху от строчки файла очень просто по наличию ":". В имени файлэхи этот символ недопустим. Внимание: все поля, включая description, обязательны к заполнению.
Также метод поддерживает сокращённый индекс подобно расширенной схеме u/e. Например,
GET /f/e/fecho1/fecho2/-2:2
вернёт в индексе только последние два файла из указанных файлэхоконференций.
Метод
GET /f/f/fecho/fid
Возвращаемое значение
Возвращает файл из указанной файлэхоконференции с указанным файл ID.
Метод
POST /f/p
Публикует файл в файлэхе на узле.
Передаваемые параметры (заполняются все):
pauth — строка авторизации поинта
fecho — имя файлэхоконференции
file — отправляемый файл, имя файла максимально 120 символов латиницей; допустимы цифры, точки, нижние подчёркивания, дефисы.
dsc — описание файла, юникод
idec.spec
gornekib(fox,1) — All
2024-11-20 17:32:27
источник https://github.com/idec-net/new-docs/blob/master/extensions.md
Расширения IDEC
===============
Здесь описаны расширения протокола, являющиеся основным отличием IDEC от ii. Многие из них реализовывать совсем необязательно.
Количество сообщений в эхоконференциях
--------------------------------------
Предназначен для отслеживания изменений в эхе и для отсеивания лишнего трафика. Обычное целое число. Важно: параметр неубывающий. Если в эхе удалили сообщения, то возвращаемое число не должно уменьшаться.
Метод
GET /x/с/<параметры>
Параметры
Единственный параметр метода - список, разделенный '/'.
Возвращаемое значение
Словарь "эха":"количество".
Пример
```
GET /x/c/test.14/im.100
test.14:221
im.100:1500
```
Push (пуш), обратная синхронизация
----------------------------------
Предназначен для получения сервером (нодой) сообщений от другого доверенного авторизованного сервера. Может быть полезным для транзитных гейтов-посредников или серверов с неработающим фетчингом. Хоть пуш и является частью /u/, он остаётся необязательным расширением.
Проще говоря, push - это бандл наоборот. Если фетчинг скачивает бандлы, то push их проталкивает на другой узел. Сначала у push-ноды запрашивается список сообщений, которые уже есть в эхе, а затем через /u/push загружаются недостающие.
Метод
POST /u/push
Параметры в теле POST запроса:
nauth - ключ для авторизации на сервере (пароль)
upush - бандл сообщений
echoarea - эхоконференция, в которую помещать сообщения
Возвращаемое значение
Может отличаться, в зависимости от сервера, либо отсутствовать. PHP-нода возвращает message saved: ok для каждого сообщения в бандле в случае успешного принятия, либо error: <название ошибки> в случае неправильного формата сообщений или error: no auth, если неправильный пароль.
Список эхоконференций
---------------------
Нужен для автоматического получения данных о наличии эх на станции. Может пригодиться для автоподписки на клиентах.
Метод
GET /list.txt
Возвращаемое значение
Словарь "эха":"количество сообщений":"описание эхи".
Пример
```
GET /list.txt
test.14:35:Тестирование и проверки
im.100:270:Болталка, общение на любые темы
```
Чёрный список
-------------
Номера тех сообщений, которые нода не принимает во время обмена и не показывает в эхоконференциях. Используется для чистки станции от спама/некорректных сообщений.
Метод
GET /blacklist.txt
Возвращаемое значение
Список номеров сообщений на каждой строке по одному.
Сокращённый индекс (расширенный /u/e)
-------------------------------------
Вариант схемы /u/e с указанием смещения и количества отдаваемых msgid. Полезно для экономии трафика, чтобы не скачивать абсолютно все сообщения с эхи, а только нужные.
Метод
/u/e/эха/эха/эха/.../<смещение>:<лимит> <Смещение> и <лимит> - целые числа. Смещение может быть отрицательным. Если параметры указаны ошибочно, выдаёт эхи целиком.
Возвращаемое значение
Список сообщений из заданных эхоконференций, с максимумом <лимит>.
Пример
```
GET /u/e/ii.test.14/test.15/1:2
ii.test.14
msgid
msgid
test.15
msgid
msgid
```
```
GET /u/e/ii.test.14/test.15/-5:5
ii.test.14
msgid
msgid
msgid
msgid
msgid
test.15
msgid
msgid
msgid
msgid
msgid
```
Список схем
-----------
Нужен, чтобы узнать, какие дополнительные возможности поддерживает станция.
Метод
GET /x/features
Пример
```
GET /x/features
x/c
list.txt
blacklist.txt
```
Полный перечень обозначения возможностей:
u/e — расширенная схема u/e
list.txt - список эхоконференций
blacklist.txt - чёрный список сообщений
x/file - файловые запросы
x/c - количество сообщений в эхе на ноде
f/ - файлэхоконференции
Размещение файлов
-----------------
Сисоп складывает разные файлы себе на ноду, а поинты (либо просто желающие) могут их скачивать.
Методы
POST /x/filelist или GET /x/filelist/pauth
Получение списка файлов в формате <Имя>:<Размер в байтах>:<Описание>. Параметр pauth - строка авторизации. Если pauth проходит проверку (существует поинт с таким паролем), то к публичному списку добавляется также список скрытых от посторонних глаз файлов.
POST /x/file или GET /x/file/filename
Параметры для запросов: pauth и filename. pauth - строка авторизации (передаётся всегда в POST), filename - имя скачиваемого файла.
Если filename отсутствует, то выдаётся ошибка. Если параметр pauth верный (т.е. пароль верный), то это даёт пользователю возможность скачивать скрытые файлы. Если файл публичный, то pauth может быть и неверным. Внимание: POST-параметры имеют приоритет перед GET.
Примеры
```
POST /x/filelist pauth=12345
myfile.txt:421:Интересная информация
cats.jpg:63253:Скрытый файл
```
POST /x/file pauth=12345;filename=cats.jpg
или
POST /x/file/cats.jpg pauth=12345
<Содержимое скрытого файла>
POST /x/file filename=myfile.txt
или
GET /x/file/myfile.txt
<Содержимое публичного файла>
GET /x/file/cats.jpg
<Ошибка, т.к. пароль не указан, а файл приватный>
Файлэхоконференции
------------------
Механизм распространения файлов пользователями сети по принципам, схожим с распространением эхоконференций.
Имя файлэхи - от 3 до 120 символов: маленькие латинские буквы, цифры, символы подчёркивания, минуса и точки.
Вся синхронизация односторонняя. Две ноды просто собирают друг у друга файлы. Пойнты же, наоборот, публикуют свои файлы, которые нода добавляет в общую БД сети, одобряя их (или не делает, не одобряя).
Метод
GET /f/c/test1/test2
Параметры
Единственный параметр метода - список, разделенный '/'.
Возвращаемое значение
Словарь "файлэха":"количество".
Пример
```
GET /f/c/test1/test2
test1:32
test2:17
```
Список файлэхоконференций
-------------------------
Аналог /list.txt для файлэхоконференций.
Метод
GET /f/list.txt
Возвращаемое значение
Словарь "фэха":"количество сообщений":"описание эхи".
Пример
```
GET /f/list.txt
books:35:Книги
pics:270:Картинки
```
Чёрный список для файлэх
------------------------
Хеши тех файлов, которые нода не принимает во время обмена и не показывает в файлэхоконференциях. Используется для чистки станции от спама/некорректных файлов.
Метод
GET /f/blacklist.txt
Возвращаемое значение
Список хешей файлов на каждой строке по одному.
Метод /f/e
----------
Возвращает список файлов с метаинформацией для указанных файлэхоконференций.
Возвращаемое значение
Список файлов из заданных файлэхоконференций.
Пример
```
GET /f/e/файлэха1/файлэха2
файлэха1
fid:filename:size:address:description
fid:filename:size:address:description
fid:filename:size:address:description
файлэха2
fid:filename:size:address:description
```
Где
fid — file ID, представляющий собой хеш содержимого файла, сформированный по тем же правилам, что и msgid.
filename — имя файла, ограничено длиной 120 символов
size — размер файла в байтах
address — адрес отправителя файла
description — краткое описание файла, ограничено 1024 символами. Если в файл-строке и дальше встречаются двоеточия-разделители с информацией, то весь текст после них идёт в счёт description.
Отличить фэху от строчки файла очень просто по наличию ":". В имени файлэхи этот символ недопустим. Внимание: все поля, включая description, обязательны к заполнению.
Также метод поддерживает сокращённый индекс подобно расширенной схеме u/e. Например,
GET /f/e/fecho1/fecho2/-2:2
вернёт в индексе только последние два файла из указанных файлэхоконференций.
Метод
GET /f/f/fecho/fid
Возвращаемое значение
Возвращает файл из указанной файлэхоконференции с указанным файл ID.
Метод
POST /f/p
Публикует файл в файлэхе на узле.
Передаваемые параметры (заполняются все):
pauth — строка авторизации поинта
fecho — имя файлэхоконференции
file — отправляемый файл, имя файла максимально 120 символов латиницей; допустимы цифры, точки, нижние подчёркивания, дефисы.
dsc — описание файла, юникод