Command Server

A server that allows communication with Mercurial's API over a pipe.

1. Protocol

All communication with the server is done on stdin/stdout. The byte order used by the server is big-endian.

Data sent from the server is channel based, meaning a (channel [character], length [unsigned int]) pair is sent before the actual data. For example:

o
1234
<data: 1234 bytes>

that is 1234 bytes sent on channel 'o', with the data following.

When starting the server, it will send a new-line separated list of capabilities (on the 'o' channel), in this format:

capabilities:\n
capability1\n
capability2\n
...

At the most basic level, the server will support the 'runcommand' capability.

1.1. Encoding

Strings sent from the server are all local strings.

1.2. Channels

There are currently 5 channels:

• o - Output channel. Everything that Mercurial writes to stdout when running from the command line is written on this channel.
• e - Error channel. When running commands, it correlates to stderr.

• i - Input channel. The length field here can either be 0, telling the client to send all input, or some positive number telling the client to send at most <length> bytes.

• l - Line based input channel. The client should send a single line of input (trimmed if length is not 0). This channel is used when Mercurial is iterating over stdin.

Input should be sent on stdin in the following format:

length
data

length = 0 sent by the client is interpreted as EOF by the server.

• d - Debug channel. Used when the server is started with logging to '-'.

1.3. Capabilities

The server is running on an endless loop (until stdin is closed) waiting for commands. A command request looks like this:

commandname\n
<command specific request>

• runcommand - Run the command specified by a list of \0-terminated strings. An unsigned int indicating the length of the arguments should be sent before the list. Example:

runcommand\n
8
log\0
-l\0
5

Which corresponds to running 'hg log -l 5'.

CategoryDeveloper