tii

Tcl-based suite for working with ii/idec protocol
git clone git://git.luxferre.top/tii.git
Log | Files | Refs | README

ii-doc.txt (6724B)


      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 ---