client: Unbreak standalone build
[empserver] / doc / clients-howto
1 This file contains material useful for client writers.
2
3 Protocol
4 ========
5
6 The protocol between Empire client and server is plain text.  It is
7 simple enough that you could play using nothing more than telnet.
8 That's a feature.
9
10 A session uses either ASCII or UTF-8, controlled by session option
11 utf-8.  See below for session options.  The session always starts in
12 ASCII.
13
14 Client-server communication is line-oriented.
15
16 The server sends lines of output.  Each output line starts with an
17 identification string, followed by a space, then arbitrary text, then
18 a line feed.
19
20 Identification strings encode small integers called output IDs as base
21 36 numbers.  Characters '0' to '9' represent digits 0 to 9, and 'a' to
22 'z' represent 10..35, as do 'A' to 'Z'.  Symbolic names for IDs are
23 defined in proto.h.
24
25 empire-client versions before version 4.3.11 parse large output IDs
26 incorrectly.  Such IDs do not currently occur.
27
28 Clients shall be able to safely handle output lines of arbitrary
29 length.  Naturally, a client may not be able to handle a sufficiently
30 large line without loss of functionality, but safety must be ensured.
31
32 When using ASCII, the most significant bit in text characters
33 indicates highlighting.
34
35 The following control characters have a defined meaning:
36
37   ASCII name         decimal  meaning
38   ----------------------------------------------------
39   bell                   7    ring the bell
40   horizontal tab         9    move to next tab stop(1)
41   line feed             10    end of line
42   shift out             14    begin highlighting(2)
43   shift in              15    end highlighting(2)
44
45   (1) Tab stops are every eight columns.
46   (2) Only if session uses UTF-8
47
48 Other ASCII control characters should not occur and may be ignored by
49 clients.  Likewise, overlong or malformed UTF-8 sequences should not
50 occur and may be ignored.
51
52 The server prompts for input.  Each prompt `consumes' one line of
53 input (except for C_EXECUTE, and when a command is aborted, as
54 described below).  Input lines are arbitrary text, terminated by line
55 feed, which is optionally preceded by carriage return (decimal 13).
56 Lines should not contain ASCII control characters other than
57 horizontal tab.  Clients should not send overlong or malformed UTF-8
58 sequences.
59
60 A client is called synchronous if it waits for a prompt before it
61 sends another line of input.  Else it is called asynchronous.
62
63 Asynchronous clients must take care to avoid blocking on sending
64 input.  If the client process blocks that way, it can't receive server
65 output until the server reads more input.  That may never happen,
66 because the server may well block on output, which then deadlocks the
67 session.
68
69 An Empire session consists of three phases: login, playing, and
70 shutdown.  empire-client is synchronous in the login phase, and
71 asynchronous afterwards.  Versions before 4.3.11 could deadlock as
72 described above.
73
74 Login phase
75 -----------
76
77 In the login phase, the server prompts for login commands.
78
79 The server starts with a C_INIT prompt.  The login phase ends when the
80 server sends another C_INIT prompt, which starts the playing phase, or
81 when it enters the shutdown phase, as described below
82
83 The server replies to a login command with another prompt.  Except as
84 noted below, the server replies C_BADCMD for syntax errors, C_CMDERR
85 for other errors, and C_CMDOK on success.  In any case, the prompt
86 text contains further information intended for humans.
87
88 Login commands are:
89
90 * client CLIENT-ID...
91
92   Identify the client.  This is optional.  If given, version
93   information should be included.
94
95 * coun COUNTRY
96
97   Set country name to COUNTRY.
98
99 * kill
100
101   If another connection for this country is in the playing phase,
102   force it into the shutdown phase, else do nothing.  Country must be
103   authenticated.
104
105   Reply is C_EXIT regardless of success.
106
107 * options OPTION[=VALUE]...
108
109   Negotiate session options.  Each argument requests setting OPTION to
110   VALUE.  The string VALUE is interpreted in an option-specific way.
111   The form without the `=' sets it to an option-specific implied
112   value.
113
114   The server accepts the request by sending C_CMDOK.  If the server
115   encounters an unknown option, it rejects the request by sending
116   C_BADCMD.  It rejects unsupported values by sending C_CMDERR.  It
117   may or may not process valid parts of rejected requests.
118
119   If there are no arguments, the server lists its options.  For each
120   option, it sends a C_DATA line with OPTION=VALUE as text, and
121   finally a C_CMDOK.  If it supports no options at all, it may reply
122   with C_BADCMD instead.
123
124   See below for supported session options.
125
126 * pass PASSWORD
127
128   Authenticate.  Country name must be set already.
129
130 * play [USER COUNTRY PASSWORD]
131
132   Start playing.
133
134   If no arguments are given, the country must be authenticated
135   already.
136
137   Else, argument USER sets the user name, COUNTRY sets the country
138   name, and PASSWORD authenticates.
139
140   Some error conditions result in a C_EXIT reply.  Clients should
141   treat it just like C_CMDERR.
142
143   On success, the server sends C_INIT.  The text is the protocol
144   version number in decimal, currently 2.  The client should terminate
145   on protocol versions it doesn't know how to handle.
146
147   The protocol version is not expected to change often.  In fact, it
148   hasn't changed since the oldest known versions of Empire.
149
150   Unlike the first C_INIT, the second one is not a prompt, i.e the
151   server does not consume a line of input for it.
152
153   The session then proceeds to the playing phase.
154
155 * quit
156
157   Terminate the session.  The server replies with C_EXIT and enters
158   the shutdown phase.
159
160 * sanc
161
162   List all countries that are still in sanctuary.  The output consists
163   of a number of C_DATA lines with human-readable text.
164
165   This command is only recognized if option BLITZ is enabled.
166
167 * user NAME
168
169   Set the user name.  This is optional and defaults to "".
170
171 If the login phase takes more than login_grace_time (default 120s),
172 the server enters the shutdown phase.
173
174 Playing phase
175 -------------
176
177 In the playing phase, the server sends data, control and prompt lines.
178
179 Clients signal `EOF' by sending a line "ctld\n", and `interrupt' by
180 sending "aborted\n".  The server treats these conditions specially, as
181 described below.  Anything else is either a command or input for a
182 command, depending on how the server prompts for the line.
183
184 empire-client signals `EOF' when it encounters an end-of-file
185 condition while reading player input.  It signals `interrupt' when it
186 catches SIGINT, which is normally triggered by Ctrl-C.
187
188 The following IDs occur:
189
190 * Command prompt C_PROMPT
191
192   The server consumes a line of input.  On EOF, the server enters the
193   shutdown phase.  Interrupt is ignored.  Anything else is interpreted
194   as Empire command.
195
196   Text is minutes used, space, BTUs left.  Both numbers are in
197   decimal.  Clients shall ignore additional text separated by another
198   space.
199
200   empire-client prints this prompt using format "[%d:%d] Command : ".
201   Clients with a tty-like user interface are advised to use a similar
202   format, to minimize differences to the examples in info.
203
204 * Argument prompt C_FLUSH
205
206   The server consumes a line of input and passes it to the currently
207   executing command.
208
209   The server aborts the command on interrupt and EOF.  Any argument
210   prompts it may send before the next command prompt do not consume
211   input.  On EOF, the server then enters the shutdown phase (but see
212   C_EXECUTE for an exception).
213
214   If an update runs while the server waits for the line of input to
215   arrive, the current command is aborted.  Whether the server consumes
216   a line of input for this argument prompt is unpredictable.  Any
217   argument prompts it may send before the next command prompt do not
218   consume input.
219
220   Text is a human-readable prompt supplied by the command.
221
222   empire-client prints the text verbatim.
223
224 * Data C_DATA
225
226   Text is human-readable server output.
227
228   empire-client prints the text verbatim.
229
230 * Control C_EXECUTE
231
232   Request execution of a batch file.  The text is whatever was on the
233   line of input after the execute command.  Its syntax and semantics
234   are left to the client.
235
236   empire-client interprets the first word (sequence of non-space
237   characters) in the text as file name, and sends the contents of that
238   file.
239
240   The security considerations on C_PIPE (below) apply to C_EXECUTE as
241   well.
242
243   Note that servers before 4.3.11 sent a copy of the execute command's
244   first argument as text.  This made it hard for clients to ensure
245   that the text is identical to what was sent, because the server
246   strips funny characters and interprets and strips '"' characters
247   when splitting input lines into command and arguments.
248
249   empire-client gets confused when old servers mangle the text that
250   way.
251
252   The client shall mark the end of the batch file by signalling EOF as
253   described above.  This does not terminate the session.  It may
254   signal interrupt if it is unable or unwilling to send the complete
255   batch file.
256
257   While executing the batch file, the server rejects redirections and
258   execute commands, and sends no C_PROMPT command prompts.  It still
259   sends C_FLUSH argument prompts.
260
261   Protocol flaw: not sending C_PROMPT here screws up redirections:
262   they'd apply until the next C_PROMPT, i.e. from start of redirected
263   command until end of containing batch file.  That's why the server
264   rejects redirections in batch files.
265
266   Certain bad failures make the server ignore the rest of the batch
267   file.  This feature is too hard to predict to be really useful.
268
269   Protocol flaw: strictly asynchronous clients cannot support
270   C_EXECUTE correctly.  By the time C_EXECUTE arrives, the client may
271   have sent more input already.  That input `overtakes' the contents
272   of the batch file in the input stream, and is interpreted as part of
273   the batch file.  Because this is almost certain to happen when the
274   execute comes from a batch file, the server rejects execute commands
275   there.
276
277   empire-client has this problem.
278
279   Clients are not required to support C_EXECUTE.  Clients are
280   encouraged to offer alternative means for scripting.
281
282 * Control C_FLASH
283
284   Asynchronous message.  The client should display the text
285   immediately.
286
287   empire-client prints the text verbatim, prepended by a line feed.
288   This is clearly sub-optimal, because it can be inserted in the
289   middle of user input.  Clients wishing to display asynchronous
290   messages together with normal I/O should insert them before the
291   current prompt.
292
293   Although asynchronous messages can be switched off with the toggle
294   command, client support for C_FLASH is not really optional, because
295   a C_FLASH could arrive before the client manages to switch them off.
296   And if the client lets the user send arbitrary commands, the user
297   can switch it back on at any time.  A session option controlling
298   C_FLASH would make more sense.  Since all popular clients support
299   C_FLASH, it's not worth the trouble.
300
301 * Control C_INFORM
302
303   Notification that the number of unread telegrams changed.  The text
304   is the notification in human-readable form.
305
306   empire-client prints the last received C_INFORM text right before
307   each prompt.  It also repeats the last prompt when a C_INFORM
308   arrives.  This is sub-optimal just like its treatment of C_FLASH.
309
310   The user can switch these off with the toggle command.  Client
311   support is not really optional for the same reasons as for C_FLASH.
312
313 * Control C_PIPE
314
315   When a command is redirected to a pipeline, its output is preceded
316   by a C_PIPE line.  The text is a copy of the redirection, starting
317   with '|'.  Syntax and semantics of the text after the '|' are left
318   to the client.
319
320   empire-client executes text after '|' as shell command, with
321   standard input connected to the Empire command's output.
322
323   The redirection applies to a single command, i.e. until the next
324   C_PROMPT.
325
326   For obvious security reasons, clients supporting pipes shall ensure
327   that the text is identical to whatever was sent to the server.  Note
328   that the server recognizes redirection only in command lines, not
329   argument lines.  Asynchronous clients cannot distinguish the two.
330
331   empire-client prepares for redirections being recognized in any
332   line, and copes with only some of them being actually recognized.
333
334 * Control C_REDIR
335
336   When a command is redirected to a file, its output is preceded by a
337   C_REDIR line.  The text is a copy of the redirection, starting with
338   '>', optionally followed by '>' or '!'.  Syntax and semantics of the
339   remaining text are left to the client.
340
341   empire-client interprets the first word (sequence of non-space
342   characters) in the remaining text as file name, and redirects the
343   command's output to that file.  The use of the first word is
344   unfortunate, as it arbitrarily limits the user's choice of file
345   names.  If the text starts with '>!', it silently overwrites any
346   existing file, with '>>' it appends to the file, and with just '>'
347   it refuses to overwrite an existing file.
348
349   The redirection applies to a single command, i.e. until the next
350   C_PROMPT.
351
352   The security considerations on C_PIPE apply to C_REDIR as well.
353
354 * Other IDs
355
356   Other IDs do not occur currently.  Clients shall deal gracefully
357   with IDs they don't know.
358
359   empire-client treats unknown IDs like C_DATA.  Versions before
360   4.3.11 prepend "Aborted\n" to C_ABORT lines, and "Error; " to
361   C_CMDERR and C_BADCMD lines for historical reasons.
362
363 Shutdown phase
364 --------------
365
366 In the shutdown phase, the server first sends a C_EXIT message.  Its
367 text is a human-readable farewell.
368
369 empire-client prints this text prepended with "Exit: ".
370
371 The server then waits for the output queue to drain, then shuts down
372 the output direction of the connection.  This makes the client detect
373 an end-of-file condition after it received all output.  The client
374 should then close its end of the connection.  The server continues to
375 read and ignore input until it detects an end-of-file condition.  It
376 then closes its end of the connection, and the session terminates.
377
378 If the server closed its end of the connection without waiting for the
379 client to close the other end first, asynchronous clients could lose
380 output: an attempt to send input after the server closed its end would
381 fail with a connection reset error even when some output is still in
382 flight.  Versions before 4.3.30 could misbehave like that in certain
383 circumstances.
384
385 If the shutdown phase doesn't complete within login_grace_time
386 (default 120s), the server closes the connection immediately.  Output
387 may be lost.
388
389 Session Options
390 ===============
391
392 Session options control client preferences.  They are not persistent;
393 each session starts with the same default session options.
394
395 The only session option so far is utf-8.  It controls whether to use
396 ASCII (disabled) or UTF-8 (enabled).  Initial value is disabled.
397 Setting it to 0 disables, setting it to 1 enables, and the implied
398 value is enabled.
399
400 Session options should not be confused with command toggle, which
401 controls player preferences.  Clients should leave those accessible to
402 their users.
403
404
405 Commands Useful for Clients
406 ===========================
407
408 Traditional dumps
409 -----------------
410
411 A number of commands are available for clients that wish to maintain
412 their own game state.  These commands are called dumps.
413
414       dump  - Dump sector information
415       ldump - Dump land unit information
416       lost  - Report lost items
417       ndump - Dump nuclear stockpile information
418       pdump - Dump plane information
419       sdump - Dump ship information
420
421 See the various info pages on these for complete documentation on how
422 they work and how you can use them to help improve your clients.
423
424 Each of the above commands prints a timestamp, which is a decimal
425 number.  This together with the timestamp selector enables you to dump
426 incrementally, i.e.  retrieve only what changed since another dump.
427 For instance, if `dump *' printed timestamp 855544597, `dump *
428 ?timestamp>855544596' dumps everything changed since.
429
430 Note that the condition compares with the timestamp value minus one.
431 That's because timestamps have a noticeable granularity: things may
432 change between a dump and the next timestamp increase.
433
434 Timestamp values are currently seconds since the epoch, but this might
435 change, and clients are advised not to rely on it.
436
437 Extended dump
438 -------------
439
440 Traditional dumps have a number of shortcomings.  They cover only the
441 most important part of the game state (sectors, ships, planes, land
442 units, nukes), but not game configuration, loans, news, and so forth.
443 They are not quite complete even for what they attempt to cover.
444 Finally, their output is harder to parse than necessary.
445
446 The new `xdump' command is designed to overcome these deficiencies.
447 See doc/xdump for the full story.
448
449
450 Advice on parsing human-readable command output
451 ===============================================
452
453 To be written.