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