Protocol
========
-Empire's client server protocol is plain text. It is simple enough
-that you could play using nothing more than telnet. That's a feature.
+The protocol between Empire client and server is plain text. It is
+simple enough that you could play using nothing more than telnet.
+That's a feature.
A session uses either ASCII or UTF-8, controlled by session option
utf-8. See below for session options. The session always starts in
Client-server communication is line-oriented.
-The server sends lines of output. Each output line starts with a
-character identifying the line, followed by a space, then arbitrary
-text, then a line feed.
+The server sends lines of output. Each output line starts with an
+identification string, followed by a space, then arbitrary text, then
+a line feed.
-Identification characters encode small integers called output ids.
-Ids less than 10 are encoded as decimal digits, and larger ids as
-lower case letters, starting with 'a'. Symbolic names for ids are
+Identification strings encode small integers called output IDs as base
+36 numbers. Characters '0' to '9' represent digits 0 to 9, and 'a' to
+'z' represent 10..35, as do 'A' to 'Z'. Symbolic names for IDs are
defined in proto.h.
+empire-client versions before version 4.3.11 parse large output IDs
+incorrectly. Such IDs do not currently occur.
+
Clients shall be able to safely handle output lines of arbitrary
length. Naturally, a client may not be able to handle a sufficiently
large line without loss of functionality, but safety must be ensured.
ASCII name decimal meaning
----------------------------------------------------
+ bell 7 ring the bell
horizontal tab 9 move to next tab stop(1)
line feed 10 end of line
shift out 14 begin highlighting(2)
occur and may be ignored.
The server prompts for input. Each prompt `consumes' one line of
-input. Input lines are arbitrary text, terminated by line feed, which
-is optionally preceded by carriage return (decimal 13). Lines should
-not contain ASCII control characters other than horizontal tab.
-Clients should not send overlong or malformed UTF-8 sequences.
+input (except for C_EXECUTE, and when a command is aborted, as
+described below). Input lines are arbitrary text, terminated by line
+feed, which is optionally preceded by carriage return (decimal 13).
+Lines should not contain ASCII control characters other than
+horizontal tab. Clients should not send overlong or malformed UTF-8
+sequences.
A client is called synchronous if it waits for a prompt before it
sends another line of input. Else it is called asynchronous.
because the server may well block on output, which then deadlocks the
session.
-An Empire session consists of two phases: login and playing.
-emp_client is synchronous during the former and asynchronous during
-the latter. It can currently deadlock as described above.
+An Empire session consists of three phases: login, playing, and
+shutdown. empire-client is synchronous in the login phase, and
+asynchronous afterwards. Versions before 4.3.11 could deadlock as
+described above.
Login phase
-----------
The server starts with a C_INIT prompt. The login phase ends when the
server sends another C_INIT prompt, which starts the playing phase, or
-when it closes the connection.
+when it enters the shutdown phase, as described below
The server replies to a login command with another prompt. Except as
noted below, the server replies C_BADCMD for syntax errors, C_CMDERR
* kill
- If another connection is open for this country, forcibly close it,
- else do nothing. Country must be authenticated.
+ If another connection for this country is in the playing phase,
+ force it into the shutdown phase, else do nothing. Country must be
+ authenticated.
Reply is C_EXIT regardless of success.
may or may not process valid parts of rejected requests.
If there are no arguments, the server lists its options. For each
- option, it sends a C_DATA line with OPTION=VALUE as text.
+ option, it sends a C_DATA line with OPTION=VALUE as text, and
+ finally a C_CMDOK. If it supports no options at all, it may reply
+ with C_BADCMD instead.
See below for supported session options.
Authenticate. Country name must be set already.
-* play [USER [COUNTRY [PASSWORD]]]
+* play [USER COUNTRY PASSWORD]
Start playing.
- Optional argument USER sets the user name.
-
- Optional argument COUNTRY sets the country name.
+ If no arguments are given, the country must be authenticated
+ already.
- Optional argument PASSWORD authenticates. If it isn't present, the
- country must be authenticated already.
+ Else, argument USER sets the user name, COUNTRY sets the country
+ name, and PASSWORD authenticates.
Some error conditions result in a C_EXIT reply. Clients should
treat it just like C_CMDERR.
* quit
- Terminate the session. The server replies with C_EXIT and closes
- the connection.
+ Terminate the session. The server replies with C_EXIT and enters
+ the shutdown phase.
* sanc
Set the user name. This is optional and defaults to "".
+If the login phase takes more than login_grace_time (default 120s),
+the server enters the shutdown phase.
+
Playing phase
-------------
described below. Anything else is either a command or input for a
command, depending on how the server prompts for the line.
-The following ids occur:
+empire-client signals `EOF' when it encounters an end-of-file
+condition while reading player input. It signals `interrupt' when it
+catches SIGINT, which is normally triggered by Ctrl-C.
+
+The following IDs occur:
* Command prompt C_PROMPT
- The server consumes a line of input. On EOF, the server terminates
- the session. Interrupt is ignored. Anything else is interpreted as
- Empire command.
+ The server consumes a line of input. On EOF, the server enters the
+ shutdown phase. Interrupt is ignored. Anything else is interpreted
+ as Empire command.
Text is minutes used, space, BTUs left. Both numbers are in
decimal. Clients shall ignore additional text separated by another
space.
- emp_client prints this prompt using format "[%d:%d] Command : ".
+ empire-client prints this prompt using format "[%d:%d] Command : ".
Clients with a tty-like user interface are advised to use a similar
format, to minimize differences to the examples in info.
-* Sub-prompt C_FLUSH
+* Argument prompt C_FLUSH
The server consumes a line of input and passes it to the currently
- executing command. Commands usually fail on EOF or interrupt.
+ executing command.
+
+ The server aborts the command on interrupt and EOF. Any argument
+ prompts it may send before the next command prompt do not consume
+ input. On EOF, the server then enters the shutdown phase (but see
+ C_EXECUTE for an exception).
+
+ If an update runs while the server waits for the line of input to
+ arrive, the current command is aborted. Whether the server consumes
+ a line of input for this argument prompt is unpredictable. Any
+ argument prompts it may send before the next command prompt do not
+ consume input.
Text is a human-readable prompt supplied by the command.
- emp_client prints the text verbatim.
+ empire-client prints the text verbatim.
* Data C_DATA
Text is human-readable server output.
- emp_client prints the text verbatim.
+ empire-client prints the text verbatim.
* Control C_EXECUTE
- Request execution of a script. The text is a copy of the execute
- command's first argument. Its syntax and semantics is left to the
- client.
+ Request execution of a batch file. The text is whatever was on the
+ line of input after the execute command. Its syntax and semantics
+ are left to the client.
- emp_client interprets the text as file name, and sends the contents
- of that file.
+ empire-client interprets the first word (sequence of non-space
+ characters) in the text as file name, and sends the contents of that
+ file.
The security considerations on C_PIPE (below) apply to C_EXECUTE as
well.
- The client shall mark the end of the script by signalling EOF as
- described above. It may signal interrupt if it is unable or
- unwilling to send the complete script.
+ Note that servers before 4.3.11 sent a copy of the execute command's
+ first argument as text. This made it hard for clients to ensure
+ that the text is identical to what was sent, because the server
+ strips funny characters and interprets and strips '"' characters
+ when splitting input lines into command and arguments.
- While executing the script, the server sends no C_PROMPT command
- prompts. It still sends C_FLUSH sub-prompts.
+ empire-client gets confused when old servers mangle the text that
+ way.
- Certain bad failures make the server ignore the rest of the script
- file. This feature is too hard to predict to be really useful.
+ The client shall mark the end of the batch file by signalling EOF as
+ described above. This does not terminate the session. It may
+ signal interrupt if it is unable or unwilling to send the complete
+ batch file.
- Strictly asynchronous clients cannot support C_EXECUTE correctly.
- By the time C_EXECUTE arrives, the client may have sent more input
- already. That input `overtakes' the script in the input stream.
+ While executing the batch file, the server rejects redirections and
+ execute commands, and sends no C_PROMPT command prompts. It still
+ sends C_FLUSH argument prompts.
- emp_client has this problem.
+ Protocol flaw: not sending C_PROMPT here screws up redirections:
+ they'd apply until the next C_PROMPT, i.e. from start of redirected
+ command until end of containing batch file. That's why the server
+ rejects redirections in batch files.
- Clients are not required to support C_EXECUTE. Clients are
- encouraged to offer alternative means for scripting.
+ Certain bad failures make the server ignore the rest of the batch
+ file. This feature is too hard to predict to be really useful.
-* Control C_EXIT
+ Protocol flaw: strictly asynchronous clients cannot support
+ C_EXECUTE correctly. By the time C_EXECUTE arrives, the client may
+ have sent more input already. That input `overtakes' the contents
+ of the batch file in the input stream, and is interpreted as part of
+ the batch file. Because this is almost certain to happen when the
+ execute comes from a batch file, the server rejects execute commands
+ there.
- End of session. The server will close the connection. Text is a
- human-readable farewell.
+ empire-client has this problem.
- emp_client prints this text prepended with "Exit: ".
+ Clients are not required to support C_EXECUTE. Clients are
+ encouraged to offer alternative means for scripting.
* Control C_FLASH
Asynchronous message. The client should display the text
immediately.
- emp_client prints the text verbatim, prepended by a newline. This
- is clearly sub-optimal, because it can be inserted in the middle of
- user input. Clients wishing to to display asynchronous messages
- together with normal I/O should insert them before the current
- prompt.
+ empire-client prints the text verbatim, prepended by a line feed.
+ This is clearly sub-optimal, because it can be inserted in the
+ middle of user input. Clients wishing to display asynchronous
+ messages together with normal I/O should insert them before the
+ current prompt.
Although asynchronous messages can be switched off with the toggle
command, client support for C_FLASH is not really optional, because
Notification that the number of unread telegrams changed. The text
is the notification in human-readable form.
- emp_client prints the last received C_INFORM text right before each
- prompt. It also repeats the last prompt when a C_INFORM arrives.
- This is sub-optimal just like its treatment of C_FLASH.
+ empire-client prints the last received C_INFORM text right before
+ each prompt. It also repeats the last prompt when a C_INFORM
+ arrives. This is sub-optimal just like its treatment of C_FLASH.
The user can switch these off with the toggle command. Client
support is not really optional for the same reasons as for C_FLASH.
* Control C_PIPE
- When a command is redirected to a pipeline, its output is prededed
+ When a command is redirected to a pipeline, its output is preceded
by a C_PIPE line. The text is a copy of the redirection, starting
with '|'. Syntax and semantics of the text after the '|' are left
to the client.
- emp_client executes text after '|' as shell command, with standard
- input connected to the Empire command's output.
+ empire-client executes text after '|' as shell command, with
+ standard input connected to the Empire command's output.
+
+ The redirection applies to a single command, i.e. until the next
+ C_PROMPT.
For obvious security reasons, clients supporting pipes shall ensure
that the text is identical to whatever was sent to the server. Note
that the server recognizes redirection only in command lines, not
argument lines. Asynchronous clients cannot distinguish the two.
- emp_client prepares for redirections being recognized in any line,
- and copes with only some of them being actually recognized.
+ empire-client prepares for redirections being recognized in any
+ line, and copes with only some of them being actually recognized.
* Control C_REDIR
- When a command is redirected to a file, its output is prededed by a
+ When a command is redirected to a file, its output is preceded by a
C_REDIR line. The text is a copy of the redirection, starting with
'>', optionally followed by '>' or '!'. Syntax and semantics of the
remaining text are left to the client.
- emp_client interprets the first word (sequence of non-space
+ empire-client interprets the first word (sequence of non-space
characters) in the remaining text as file name, and redirects the
command's output to that file. The use of the first word is
unfortunate, as it arbitrarily limits the user's choice of file
existing file, with '>>' it appends to the file, and with just '>'
it refuses to overwrite an existing file.
+ The redirection applies to a single command, i.e. until the next
+ C_PROMPT.
+
The security considerations on C_PIPE apply to C_REDIR as well.
-* Other ids
+* Other IDs
+
+ Other IDs do not occur currently. Clients shall deal gracefully
+ with IDs they don't know.
+
+ empire-client treats unknown IDs like C_DATA. Versions before
+ 4.3.11 prepend "Aborted\n" to C_ABORT lines, and "Error; " to
+ C_CMDERR and C_BADCMD lines for historical reasons.
- Other ids do not occur currently. Clients shall deal gracefully
- with ids they don't know.
+Shutdown phase
+--------------
- emp_client treats unknown ids like C_DATA. For historical reasons,
- it prepends "Aborted\n" to C_ABORT lines, and "Error; " to C_CMDERR
- and C_BADCMD lines.
+In the shutdown phase, the server first sends a C_EXIT message. Its
+text is a human-readable farewell.
+empire-client prints this text prepended with "Exit: ".
+
+The server then waits for the output queue to drain, then shuts down
+the output direction of the connection. This makes the client detect
+an end-of-file condition after it received all output. The client
+should then close its end of the connection. The server continues to
+read and ignore input until it detects an end-of-file condition. It
+then closes its end of the connection, and the session terminates.
+
+If the server closed its end of the connection without waiting for the
+client to close the other end first, asynchronous clients could lose
+output: an attempt to send input after the server closed its end would
+fail with a connection reset error even when some output is still in
+flight. Versions before 4.3.30 could misbehave like that in certain
+circumstances.
+
+If the shutdown phase doesn't complete within login_grace_time
+(default 120s), the server closes the connection immediately. Output
+may be lost.
Session Options
===============
Timestamp values are currently seconds since the epoch, but this might
change, and clients are advised not to rely on it.
-Experimental extended dump
---------------------------
+Extended dump
+-------------
Traditional dumps have a number of shortcomings. They cover only the
-most important part of the game state: sectors, ships, planes, land
-units, nukes, but not game configuration, loans, news, and so forth.
+most important part of the game state (sectors, ships, planes, land
+units, nukes), but not game configuration, loans, news, and so forth.
They are not quite complete even for what they attempt to cover.
Finally, their output is harder to parse than necessary.
The new `xdump' command is designed to overcome these deficiencies.
-It still needs significant work, and is subject to change in
-incompatible ways. To protect real games from known and unknown flaws
-in xdump, it is only accessible when option GUINEA_PIGS is enabled.
-
-Technical xdump documentation to be written.
+See doc/xdump for the full story.
Advice on parsing human-readable command output
projects / empserver / blobdiff