commit 374be3b9afff4eec6844b9c9f85f0891441ca1cd
parent 9fcd156ce77cfb4714053081a94f3d0c31faff26
Author: Luxferre <lux@ferre>
Date: Mon, 28 Oct 2024 12:07:52 +0200
Updated ii-doc
Diffstat:
| M | ii-doc.txt | | | 75 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------- |
1 file changed, 54 insertions(+), 21 deletions(-)
diff --git a/ii-doc.txt b/ii-doc.txt
@@ -11,10 +11,10 @@ Clients aka points can:
* fetch messages by their IDs
Nodes aka stations can:
-* accept (or not accept) posted messages from points
+* accept (or reject) posted messages from points
* serve echo lists
-* serve echos and their message ID lists
-* serve message bundles
+* serve echos and their indexes (message ID lists)
+* serve message bundles or single messages
* fetch echos and messages from other stations
The main transport protocol is currently HTTP/HTTPS, although the spec doesn't
@@ -27,26 +27,44 @@ Echo and message naming convention
----------------------------------
Within the network, echo names must be from 3 to 120 characters long and have
at least one dot (.) character. Message IDs must be exactly 20 characters long
-and depend on the message contents hash (see the exact algorithm below).
+and depend on the message contents hash upon posting (see the exact algorithm
+below in the "Message ID generation algorithm" section).
-Station (node) HTTP API (as implemented in tii)
------------------------------------------------
+Station (node) HTTP API
+-----------------------
Every station must implement the following HTTP API calls.
In case of multi-line responses, the newline separator must be "\n" character
(line feed, ASCII 10).
+All station responses must end with a newline separator.
- Fetching the public echo list -
Request: GET /list.txt
Response: newline-separated list of echo_name:msg_count:echo_description
-Note: msg_count must not decrease even if some messages are deleted.
-Some nodes (e.g. ii-php) still can violate this rule, so the message count
-reported by nodes still should not be the basis for any client-side logic.
+Note: the msg_count field must reflect the actual non-blacklisted message
+count that the station can serve.
-- Listing messages in the echo(s) -
+- Fetching the public message blacklist -
+
+Request: GET /blacklist.txt
+Response: newline-separated list of message IDs
+
+The blacklisted message IDs must not be served to the clients in any of the
+API calls specified below.
+
+- Listing messages in a single echo -
+
+Request: GET /e/echo.name
+Response: newline-separated message ID list
+
+When a new message is posted to the echo, it gets appended to the end of the
+corresponding message ID list for this echo.
+
+- Listing messages in any amount of echos -
Request: GET /u/e/echo.1.name/echo.2.name/...
+Limited request: GET /u/e/echo.1.name/echo.2.name/.../offset:limit
Response: newline-separated list of echo names and message IDs in the format:
echo.1.name
@@ -58,38 +76,56 @@ msgid1fromecho2
msgid2fromecho2
...
-When a new message is posted to the echo, it gets appended to the end of the
-corresponding message ID list for this echo.
+In case of limited request, the offset can be negative. E.g. -10:10 means
+requesting last 10 messages from the index.
+
+- Fetching a single message by its ID -
+
+Request: GET /m/msgid
+Response: plaintext message in the Node-to Point Message format
-- Fetching the message bundles -
+- Fetching a message bundle -
Request: GET /u/m/msgid1/msgid2/...
Response: newline-separated list of msgid:base64_msgtext
-where base64_msgtext is a Base64-encoded Node-to-Point Message (see below).
+Here, base64_msgtext is a Base64-encoded Node-to-Point Message (see below).
- Posting a message (via POST) -
Request: POST /u/point
Content-Type: application/x-www-form-urlencoded
Data: pauth=auth_string&tmsg=base64_msgtext
-Response: in case of success, must start with "msg ok"
+Response: in case of success, must start with "msg ok", otherwise with "error"
-where base64_msgtext is the Base64-encoded Point-to-Node Message (see below).
+Here, auth_string is the user's authorization string and base64_msgtext is the
+Base64-encoded Point-to-Node Message (see below).
The maximum length of the tmsg field must be 87382 bytes.
- Posting a message (via GET) -
Request: GET /u/point/auth_string/base64_msgtext
-Response: in case of success, must start with "msg ok"
+Response: in case of success, must start with "msg ok", otherwise with "error"
-where base64_msgtext is the Base64URL-encoded Point-to-Node Message.
+Here, auth_string is the user's authorization string and base64_msgtext is the
+Base64URL-encoded Point-to-Node Message.
The maximum length of the tmsg field must be 87382 bytes.
Note: the Base64URL encoding means that after the standard Base64 encoding,
the + character is replaced with -, the / character is replaced with _, and
the = character is omitted from the end.
+- Pushing a message bundle to another node -
+
+Request: POST /u/push
+Content-Type: application/x-www-form-urlencoded
+Data: nauth=auth_string&upush=bundle_contents&echoarea=echo.name
+Response: in case of success, must start with "message saved: ok", otherwise
+ with "error:"
+
+Here, auth_string is the node authorization string and bundle_contents is the
+message bundle in the exact format as received by GET /u/m API method.
+
Node-to-Point Message format
----------------------------
The encoding must be UTF-8 and the newline separator must be "\n" (ASCII 10).
@@ -140,9 +176,6 @@ Implementation notes
* Most HTTP servers are configured to reject long GET lines, so tii passes a
limited amount of message IDs to the /u/m endpoints. This behaviour can be
configured in the stations.txt file.
-* Some of the crucial validations are for message IDs to be 20 lines and for
- all messages (Node-to-Point and Point-to-Node) to strictly have LF line
- endings, not CRLF.
* The message order in an echo does not always match the timestamp ordering;
it is fully up to the client on how to sort the messages internally. The
messages are only guaranteed to be saved by the server in the order they
