/
protocol.txt
181 lines (138 loc) · 6.66 KB
1
=======================================
2
===== IcculusNews Protocol v. 2.0 =====
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
=======================================
Assumptions:
- Everything is sent in text format, and all commands have a
terminating newline.
- Line ends are UNIX.
- The astroda has an epsonnage rating of 94.5% +/- 0.5%.
- Lines beginning with "-->" represent messages sent from client to
server; lines beginning with "<--", server to client.
- If no commands are sent by the client to the server for a duration of
10 seconds, the server should close the connection.
- In general, nominal responses from the server are preceded by a '+'
(ASCII 43); error responses are preceded by a '-' (ASCII 45).
- Commands are not case-sensitive.
Generic:
<-- - can't execute query: <errstr> (MSG_SERVFAIL)
If, at any time, the server is unable to perform a needed SQL query,
it will send MSG_SERVFAIL, where <errstr> is an arbitrary text string
describing the error encountered, and close the connection.
--> NOOP (MSG_NOOP)
<-- + epson the whole astroda (MSG_ASTRODA)
NOOP serves as a no-operation, used in order to circumvent the
connection timeout.
<-- - USAGE: <command> <arguments> (MSG_USAGE)
If the server receives a command that has an invalid number of
arguments, the server should respond with MSG_USAGE.
<-- + Uh, okay. (MSG_NOCMD)
If an empty line is sent as a command, the server should respond with
MSG_NOCMD.
<-- - Unknown command "<command>". (MSG_INVALCMD)
If the server has received a command that it does not recognize, it
should respond with MSG_INVALCMD.
48
49
50
51
52
53
54
55
56
57
58
59
<-- + Here comes... (MSG_STARTDAT)
If the last command received by the server expects a response greater
than one line in length, the server should prefix the response with
MSG_STARTDAT.
<-- . (MSG_ENDDAT)
MSG_ENDDAT is used to end a block of data begun with MSG_STARTDAT that
has non-constant length. Such data is returned by ENUM queues and
DIGEST, among others.
60
61
62
63
64
65
66
67
Connection and Authentication:
--> connect()
By default, the IcculusNews daemon runs on port 263 of the
server. It expects no input to begin the connection process.
<-- + IcculusNews daemon <version> (MSG_VER)
68
--> AUTH ["<username>" "<password>" | -] (MSG_AUTH)
69
70
71
72
73
74
<-- + <uid>, <qid> (MSG_UIDQID)
<-- - Authorization for "<username>" failed. (MSG_AUTHFAIL)
<-- - This account has been disabled. (MSG_ACCTLOCK)
<-- - Failed to set default queue: <errstr> (MSG_NODQUEUE)
<version> is an arbitrary text string describing the version of
75
76
77
the daemon. Once this string has been sent, the server expects a
MSG_AUTH in response. All other inputs will result in the sending of
MSG_NOTAUTH and the closing of the connection.
78
79
80
81
82
83
A properly-formatted MSG_AUTH will solicit one of four replies:
MSG_UIDQID, MSG_AUTHFAIL, MSG_ACCTLOCK, or MSG_NODQUEUE.
The <username> and <password> arguments to MSG_AUTH are
arbitrary text strings describing the username/password pair of a user
84
85
86
87
88
89
90
on the remote server. Alternately, the client can specify a '-' (ASCII
45) to authenticate as the anonymous user. If the MSG_AUTH does not
describe a valid user, the server should respond with MSG_AUTHFAIL. If
the user whose account is described is not authorized to log in, the
server should respond with MSG_ACCTLOCK. If the user's default queue
cannot be set, the server should respond with MSG_NODQUEUE, where
<errstr> is an arbitrary text string describing the error encountered.
91
92
93
94
95
96
97
98
If authentication has completed successfully, the server will
reply with MSG_UIDQID, where <uid> is an integer representing the
current user ID, and <qid> is an integer representing the current queue
ID.
Queue Information:
99
100
101
102
103
104
105
106
107
108
109
110
111
112
--> ENUM queues (MSG_ENUMQ)
<-- (MSG_STARTDAT)
<-- <qid> (MSG_QID)
<-- <queue name> (MSG_QNAME)
<-- ...
<-- (MSG_ENDDAT)
MSG_ENUMQ is a request for basic information on all queues on
the current server. The server should respond with a block of data
beginning with MSG_STARTDAT. This block of data should contain a
number of MSG_QID / MSG_QNAME pairs, each corresponding to the queue ID
and queue name of a single queue. The end of the data should be marked
with a MSG_ENDDAT.
113
114
User Information:
115
116
117
118
119
120
121
--> USERINFO (MSG_USERINFO)
<-- (MSG_UIDQID)
MSG_USERINFO is a request for information on the current user
and queue in use. The server should respond with a MSG_UIDQID, where
<uid> is the current user ID, and <qid> is the current queue ID.
122
123
Article Information:
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
--> DIGEST [<offset> | -] <n> (MSG_DIGEST)
<-- - no queue selected. (MSG_NOQUEUE)
<-- (MSG_STARTDAT)
<-- <aid> (MSG_AID)
<-- <title> (MSG_ATITLE)
<-- <ctime> (MSG_ACTIME)
<-- <uid> (MSG_AOWNERID)
<-- <uname> (MSG_AOWNERNM)
<-- <ip> (MSG_AOWNERIP)
<-- <approved> (MSG_AAPPROVE)
<-- <deleted> (MSG_ADELETED)
<-- ...
<-- (MSG_ENDDAT)
MSG_DIGEST is a request for information on a set of articles in
the currently-selected queue. <offset> is either an integer indicating
the upper bound on the article ID to be queried, such that all articles
returned have an article ID of less than <offset>, or a '-' (ASCII 45),
indicating no upper bound. <n> is an upper bound on the number of
articles for which information is wanted; if there are fewer than <n>
records matching the server's query, the block will end prematurely.
If the current queue is 0, the server should reply with
MSG_NOQUEUE. Otherwise, it should return a block of data. The block
of data should begin with MSG_STARTDAT, and then contain a number of
MSG_AID / MSG_ATITLE / MSG_ACTIME / MSG_AOWNERID / MSG_AOWNERNM /
MSG_AOWNERIP / MSG_AAPPROVE / MSG_ADELETED sets, where:
- MSG_AID is an integer describing the article's article ID;
- MSG_ATITLE is an arbitrary text string defining the title of the
article (titles do not have to be unique across articles);
- MSG_ACTIME is the time at which the article was created (in
YYYY-MM-DD HH:MM:SS format);
- MSG_AOWNERID is the user ID of the creator of the article;
- MSG_AOWNERNM is the user name of the creator of the article (or the
system-wide anonymous username if UID 0);
- MSG_AOWNERIP is the dotted-quad IP of the computer from which the
article was submitted;
- MSG_AAPPROVE is a flag stating the article's approval status (1 if
the article has been approved, 0 otherwise);
- MSG_ADELETED is a flag stating the article's deletion status (1 if it
is marked to be deleted at the next purge, 0 otherwise).
The end of the block should be marked with MSG_ENDDAT.
169
170
171
172
173
174
Article Submission:
Article Editation:
Disconnection:
175
176
--> QUIT (MSG_QUIT)
<-- + kthxbye (MSG_BYE)
177
178
179
180
MSG_QUIT indicates that the client has requested to close the
connection. The server should comply and reply with a MSG_BYE before
calling close().