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: capability1\n
capability2\n
...

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

1.1. Encoding

Strings are encoded in the local encoding.

1.2. Channels

There are currently 5 channels:

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.

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\n
8
log\0
-l\0
5

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

The server responds with input/output generated by Mercurial on the matching channels. When the command returns, the server writes the following to the 'o' channel:

\0
<return code>

1.4. Examples

1.4.1. runcommand

Complete example of a client running 'hg summary', right after starting the server:

(text in the server column is <channel>: <length>, where length is really 4 byte unsigned ints, not plain text like below)

server

client

notes

connected, waiting for capabilities

o: 24
capabilities: runcommand

waiting for a command

runcommand\n
7
summary

client talks to server on stdin

starts running command

o: 27
parent: 14571:17c0cb1045e5

o: 3
tip

o: 1
\n

o: 53
paper, coal: display diffstat on the changeset page\n

o: 16
branch: default\n

o: 16
commit: (clean)\n

o: 18
update: (current)\n

o: 5
\0 0

server finished running command, writes \0+returncode to the client

closes server stdin

client disconnects

server exits

client waits for server to exit

And another one with activity on the input channels too by running 'import -':

(starting after client read capabilities)

server

client

notes

waiting for a command

runcommand\n
8
import\0
-

client talks to server on stdin

starts running command

o: 26
applying patch from stdin\n

l: 0

server tells client to send it a line

21
# HG changeset patch\n

client responds with <length><line>

l: 0

server processes line, asks for another one

...this goes on until the client has no more input

l: 0

0

it responds with length=0

o: 5
\0 0

server finished running command, writes \0+returncode to the client

closes server stdin

client disconnects

server exits

client waits for server to exit


CategoryDeveloper