|Version 2 (modified by adam, 10 years ago)|
We originally proposed using XML-RPC to communicate between hm and HMd, and between HMd and the back-end processes. This now looks problematic, as we wish to have multiple responses (for example, updates on progress) to a single request.
The proposed solution now is to have our own protocol between these processes. The protocol will resemble a stripped down version of HTTP or SIP. To send a request, a TCP connection will be setup between the "client" process and the relevant "server" process. A request is sent. One or more responses are received (all requests generate at least one response). The connection can then be torn down, but in most cases it would remain up to be reused by subsequent requests, which helps maintain relative sequencing of requests and responses. Requests can be pipelined; that is more than one request can be sent without waiting for the response. This is necessary to permit large quantities of data to be transferred rapidly.
For syntax, the proposal is to have an ASCII-encoded frame, which can then transport arbitrary data, including binary payloads. The channel should be regarded as 8-bit clean - bytes containing a value of zero can be conveyed.
The format for requests should be:
<CR> Type <SPACE> Method Name <SPACE> SeqNo <SPACE> Payload Length <CR> Payload
Type is REQ. Only one space should be used between the fields, and a single <CR> should be used to delimit the start of the payload. The payload length field delimits the end of the payload.
The syntax of the payload is independent from the transport described here, much as HTTP can transport images, HTML and other types. Unlike in HTTP, the protocol does not indicate the format of the payload - it is simply opaque data to be handed to the relevant method to parse. Thus some methods might use XML as the syntax of the payload whereas this might be innappropriate for other methods.
An example of a request might be:
REQ set_power_state 3 26 computer3 on computer4 off
The method name is set_power_state. This message has sequence number 3, and the payload is 26 bytes in length. This particular message uses a simple ASCII format for the payload, but this is determined only by the parser for set_power_state, and is not a limitation of the transport protocol.
The format for requests should be:
<CR> Type <SPACE> Response Code <SPACE> SeqNo <SPACE> Payload Length <CR> Payload
Type is RESP. Only one space should be used between the fields, and a single <CR> should be used to delimit the start of the payload. The payload length field delimits the end of the payload.
Response Code is a three-digit numeric code indicating whether or not the request was a success. The response codes should be taken directly from the SIP RFC. 200 indicates success, 100-199 indicate a provisional response, 400-499 indicates an error on the part of the client, and 500-599 indicate an error on the part of the server.
An example of a response chain (more than one response to a single request) might be:
RESP 100 3 16 msg Please wait. RESP 500 3 26 computer3 off computer4 off
The 100 response is a provisional request indicating a message to display to the user. The 500 response sent later indicates a failure occurred. In this case it also indicates what actually happened (as opposed to what the client asked to happen). Again, the format of the payloads is dependent only on the method in the request - this could have been in XML or any other format that was thought appropriate by the person implementing the relevant method.