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.