|
Size: 4801
Comment:
|
Size: 5084
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 34: | Line 34: |
| Strings are encoded in the local encoding. For now the server cannot be queried for the local encoding. If the client wishes to set it, it should start the server with the proper HGENCODING. |
Strings are encoded in the local encoding. For now the server cannot be queried for the local encoding. If the client wishes to set it, it should start the server with the proper HGENCODING. |
| Line 40: | Line 39: |
| * o - Output channel. Most of the communication happens on this channel. When running commands, output Mercurial writes to stdout is written to this channel. * e - Error channel. When running commands, this 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 interacts with the user or when iterating over stdin. |
* 'o'utput channel: most of the communication happens on this channel. When running commands, output Mercurial writes to stdout is written to this channel. * 'e'rror channel: when running commands, this correlates to stderr. * 'i'nput channel: the length field here tells the client how many bytes to send. * 'l'ine based input channel: the client should send a single line of input (trimmed to length). This channel is used when Mercurial interacts with the user or when iterating over stdin. |
| Line 54: | Line 53: |
| * r - Result channel. The server uses this channel to tell the client that a command finished by writing its return code (a signed integer). * d - Debug channel. Used when the server is started with logging to '-'. |
* 'r'esult channel: the server uses this channel to tell the client that a command finished by writing its return value (command specific). * 'd'ebug channel: used when the server is started with logging to '-'. |
| Line 57: | Line 56: |
| === Capabilities === | === Commands === |
| Line 66: | Line 65: |
| * 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: | If an unknown request is sent to the server it is ignored, without sending back any kind of response to the client. Clients are expected to check what commands are supported by the server by consulting the capabilities. ==== 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: |
| Line 80: | Line 83: |
==== getencoding ==== Returns the servers encoding on the result channel. client: {{{ getencoding\n }}} server responds with: {{{ r 5 ascii }}} |
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. For now the server cannot be queried for the local encoding. If the client wishes to set it, it should start the server with the proper HGENCODING.
1.2. Channels
There are currently 5 channels:
- 'o'utput channel: most of the communication happens on this channel. When running commands, output Mercurial writes to stdout is written to this channel.
- 'e'rror channel: when running commands, this correlates to stderr.
- 'i'nput channel: the length field here tells the client how many bytes to send.
- 'l'ine based input channel: the client should send a single line of input (trimmed to length). This channel is used when Mercurial interacts with the user or when 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.
- 'r'esult channel: the server uses this channel to tell the client that a command finished by writing its return value (command specific).
- 'd'ebug channel: used when the server is started with logging to '-'.
1.3. Commands
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>
If an unknown request is sent to the server it is ignored, without sending back any kind of response to the client. Clients are expected to check what commands are supported by the server by consulting the capabilities.
1.3.1. 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'.
The server responds with input/output generated by Mercurial on the matching channels. When the command returns, the server writes the return code (signed integer) of the command to the 'r'esult channel.
1.3.2. getencoding
Returns the servers encoding on the result channel.
client:
getencoding\n
server responds with:
r 5 ascii
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 |
|
|
|
|
server is waiting for a command |
|
runcommand\n |
client talks to server on stdin |
starts running command |
|
|
o: 27 |
|
|
o: 3 |
|
|
o: 1 |
|
|
o: 53 |
|
|
o: 16 |
|
|
o: 16 |
|
|
o: 18 |
|
|
r: 4 |
|
server finished running command, writes ret on the 'r' channel 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 |
|
|
server is waiting for a command |
|
runcommand\n |
client talks to server on stdin |
starts running command |
|
|
o: 26 |
|
|
l: 0 |
|
server tells client to send it a line |
|
21 |
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 |
r: 4 |
|
server finished running command, writes ret on the 'r' channel to the client |
|
closes server stdin |
client disconnects |
server exits |
|
client waits for server to exit |