The WARP Protocol Version 1.0
Data Packet Structure
All data sent on the full duplex connection between the client and server MUST follow this structure:
WARP Packet | ||||||||||||||
Octet | 1 | 2 | 3 | 4 .. (length+3) | ||||||||||
Bits | 0 | 1 | .. | 6 | 7 | 0 | 1 | .. | 14 | 15 | 0 | 1 | .. | |
Description | Packet Type | Payload Length | Payload Data (Content) |
Payload Structure
The payload of a packet can be structured in two ways, depending on its type: the packet can either contain raw data (such as an HTTP request or response body) or a combination of numeric values and strings.
By definition a numeric value is a 32 bit signed integer represented in network byte order (the value of 6 decimal would be represented as 000000000000000000000000000000000110 binary (110 preceeded by 29 zeroes).
A string is defined in the following way: the first two octets represent the string length as an unsigned 16 bits value. This value indicates the number of octets that compose the encoded string. The string is not NULL terminated and is encoded following the UTF-8 standard. For example the string "fooBar" would be represented as:
String | ||||||||||||
Octet | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | ||||
Bits | 0 | 1 | .. | 14 | 15 | .. | ||||||
Content | 110 bin = 6 dec | f | o | o | B | a | r |
Packet Types
The following is a list of packet types and their relative expected responses:
Packet/States Table | ||||
Name | Type | Originator | Description | Expects |
ERROR | 0x00 | Client Server | One end of the peer notifies the other of a fatal connection error | N/A |
DISCONNECT | 0x01 | Client Server | One end of the peer notifies the oter that the connections is going to be closed | N/A |
AUTHENTICATE | 0x02 | Server | The server requires the client to authenticate | LOGIN |
LOGIN | 0x03 | Client | The client tries to authenticate itself | HELLO |
HELLO | 0x04 | Server | Server welcomes the client | HELLO |
HOST | 0x05 | Client | The client transmits the definition of a virtual host | HOSTID |
HOSTID | 0x06 | Server | The server transmits the HOST ID associated with the virtual host | APPL |
APPL | 0x07 | Client | The client transmits the definition of a web application | APPLID, APPLREJ |
APPLID | 0x08 | Server | The server transmits the APPLICATION ID associated with a web application | HOST, APPL, DONE |
APPLREJ | 0x09 | Server | The server reports that the web application is not available | HOST, APPL, DONE |
DONE | 0x0A | Client | The server notifies the end of its configurations | |
REQUEST | 0x20 | Client | The client starts a new request | |
PARAM | 0x21 | Client | A request parameter | |
HEADER | 0x22 | Client Server | A peer notifies the other of a MIME header | |
COMPLETE | 0x23 | Client Server | The client (or the server) notifies that the request (or the response) has been fully transmitted | READ, RESPONSE, TRANSLATE |
READ | 0x24 | Server | The server requests to the client a chunk of the HTTP request body | BODY |
BODY | 0x25 | Client Server | The client (or the server) transmits a chunk of an HTTP request (or response) body | |
RESPONSE | 0x26 | Server | The server transmits the HTTP status of the response | |
ABORT | 0x27 | Client | The client notifies that a request needs to be aborted | COMPLETE |
TRANSLATE | 0x28 | Server | The server requests to the client to translate an URI to a file path | TRANSLATION |
TRANSLATION | 0x29 | Client | The client returns the translation of the requested URI |
Packet Type Details
ERROR 0x00
Specifies an unrecoverable protocol error. After the client or the server issues this
packet the socket underlying the WARP connection must be closed.
This message can be sent at any time by the client or the server.
DISCONNECT 0x01
The client or the server is going to close the connection (no fatal protocol error).
This message can be sent at any time by the client or the server.
AUTH 0x02
When the connection to the server is opened, and the server requires the peer to authenticate itself, this packet is sent to the client containing a challenge used to perform an MD5 hash.
LOGIN 0x03
After the client receives an AUTH message, the challenge string is appended to the shared secred and the MD5 hashing algorithm is applied to the result. This value is sent back for authentication.
HELLO 0x04
The server welcomes the client issuing this message after the client performed its authentication or after the socket is opened if the server doesn't require authentication.
HOST 0x05
The client transmits to the server the definition of a virtual host.
HOSTID 0x06
The server replies to a HOST message specifying a unique HOST ID that will be used further on to identify the virtual host associated with a request.
APPL 0x07
The client transmits to the server the definition of a web application.
APPLID 0x08
The server acknowledges the deployment of a web application returning a unique id into its virtual host, and the web application root path (if available).
APPLREJ 0x09
The server rejects the deployment of a web application.
DONE 0x0A
The client indicates that all configurations (virtual hosts and web applications) have been transmitted. The next packet transmitted by the client will be a REQUEST packet.
REQUEST 0x20
The client initiates transmitting a request. The next packet transmitted by the client will be either a PARAM packet (if parameters are encoded in the request URI) or HEADER packet.
PARAM 0x21
The client transmits a request parameter encoded in the URL requested by the client. (Parameters passed in the body of a request must not be parsed). The next packet transmitted by the client will be another PARAM packet, a HEADER packet or a COMPLETE packet.
HEADER 0x22
When this packet is sent by the client, the header is one of the MIME headers received with the
body of the HTTP request. In this case, the next packet sent by the client will be another HEADER
packet or a COMPLETE packet.
When this packet is sent by the server, the header is a MIME header that will be included in the
response body. The next packet sent by the server will be either another HEADER packet, or one of
READ, RESPONSE, TRANSLATE or COMPLETE packet.
COMPLETE 0x23
When this packet is sent by the client, the client means that all headers and parameters associated
with a request have been transmitted to the server, and the request can be executed. The control is then
given to the server which will issue one of READ, RESPONSE or TRANSLATE packets.
When this packet is sent by the server, the server means that the response to the request has been
fully transmitted back to the client. The control is then give back to the client which will issue a
REQUEST packet when a new request needs to be processed.
READ 0x24
The server requests to the client to forward a chunk of the request body. The returned request body chunk can be shorter than the requested size, but not bigger.
BODY 0x25
This packet is sent by the client in response to a READ message. The HTTP request body is read up to the
requested length and forwarded back to the server.
When this packet is sent by the server, the server means to transmit the HTTP request body to the client.
RESPONSE 0x26
The server initiates transmitting the response back to the client, specifying an HTTP response state, and a detail message for it.
ABORT 0x27
The client indicates to the server that the request needs to be aborted.
TRANSLATE 0x28
The server requests to the client to translate a URI into a file path.
TRANSLATION 0x29
The client returns the translation of the requested URI path.