The WARP Protocol Version 1.0.2
Data Packet Structure
All data sent on the full duplex connection between the client and server
MUST follow this structure:
-
Data is sent in packets formed by a header describing some info about the
packet itself followed by a data length and data payload.
-
All packets MUST follow big endian style ("network order").
-
The packet header is always 24 bits long and follow this format:
-
Octet 0 (8 bits) contains the packet type.
-
Octets 1-2 (16 bits) set the length of the data payload carried by the
packet itself in numbers octets and MAY be zero.
-
If the length of the data payload is more than zero, octets from 3 to (length
+ 3) contain the payload data or content.
| 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 |
0xfe |
Client Server |
One end of the peer notifies the other that the connections is going
to be closed |
N/A |
| FATAL |
0xff |
Client
Serve |
A protocol error occourred, the connection must be closed. |
N/A |
|
|
|
|
|
| CONF_WELCOME |
0x01 |
Server |
First message sent by Server after a client connection. |
CONF_DEPLOY |
| CONF_DEPLOY |
0x05 |
Client |
Deploy a web application. |
CONF_APPLIC |
| CONF_APPLIC |
0x06 |
Server |
Application deployed successfully. |
CONF_MAP, CONF_DEPLOY |
| CONF_MAP |
0x07 |
Client |
Require for application mapping information |
CONF_MAP_DONE,CONF_MAP_ALLOW,CONF_MAP_DENY |
| CONF_MAP_ALLOW |
0x08 |
Server |
Allow client to map the request |
N/A |
| CONF_MAP_DENY |
0x09 |
Server |
Deny client to map the request |
N/A |
| CONF_MAP_DONE |
0x0a |
Server |
All the ALLOW/DENY map have been transfered |
CONF_DEPLOY, CONF_DONE |
| CONF_DONE |
0x0e |
Client |
Configuration completly sent to the server |
CONF_PROCEED |
| CONF_PROCEED |
0x0f |
Server |
Server ready to accept requests. |
Request elements (REQ_INIT, REQ_CONTENT, REQ_SCHEME, REQ_AUTH, REQ_HEADER,
REQ_SERVER, REQ_CLIENT, REQ_PROCEED) |
|
|
|
|
|
| REQ_INIT |
0x10 |
Client |
New request. |
N/A |
| REQ_CONTENT |
0x11 |
Client |
Mine type and length |
N/A |
| REQ_SCHEME |
0x12 |
Client |
Scheme |
N/A |
| REQ_AUTH |
0x13 |
Client |
Authentication |
N/A |
| REQ_HEADER |
0x14 |
Client |
Header element |
N/A |
| REQ_SERVER |
0x15 |
Client |
server information |
N/A |
| REQ_CLIENT |
0x16 |
Client |
remote peer information |
N/A |
| REQ_PROCEED |
0x1f |
Client |
process request |
Reponse elements, ASK_SSL, ASK_SSL_CLIENT or CBK_READ. |
|
|
|
|
|
| ASK_SSL |
0x43 |
Server |
Request SSL information |
REP_SSL_NO, REP_SSL |
| ASK_SSL_CLIENT |
0x44 |
Server |
Request for CC |
REP_SSL_NO, REP_SSL_CERT |
| REP_SSL_NO |
0x5f |
Client |
SSL information not available. |
Reponse elements. |
| REP_SSL |
0x52 |
Client |
SSL information. |
Reponse elements. |
| REP_SSL_CERT |
0x53 |
Client |
Client certificate. |
Reponse elements. |
|
|
|
|
|
| CBK_READ |
0x40 |
Server |
Request for body data. |
CBK_DATA, CBK_DONE |
| CBK_DATA |
0x41 |
Client |
Chunk of data. |
CBK_READ or Reponse elements. |
| CBK_DONE |
0x42 |
Client |
End of data. |
Reponse elements. |
|
|
|
|
|
| RES_STATUS |
0x20 |
Server |
HTTP status. |
N/A |
| RES_HEADER |
0x21 |
Server |
response header. |
N/A |
| RES_COMMIT |
0x2f |
Server |
send data to browser. |
N/A |
| RES_BODY |
0x30 |
Server |
data reponse element |
N/A |
| RES_DONE |
0x3f |
Server |
end of reponse |
Request elements. |
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.
-
[string]: A detail message on why the connection must be closed.
DISCONNECT 0xfe
The client or the server is going to close the connection (no fatal
protocol error).
FATAL 0x0ff
A protocol error occourred, the connection must be closed.
-
[string]: An error message.
CONF_WELCOME 0x01
The server issues this packet when a connection is opened. The server
awaits for configuration information.
-
[ushort] Major protocol version.
-
[ushort] Minor protocol version.
-
[integer] The server unique-id.
CONF_DEPLOY 0x05
The client attempts to deploy a web application.
-
[string] The application name.
-
[string] The virtual host name.
-
[ushort] The virtual host port.
-
[string] The web-application URL path.
CONF_APPLIC 0x06
The server replies to a CONF_DEPLOY message with the web application
identifier of the configured application.
-
[integer] The web application unique id for this server.
-
[string] The web application real path (where it's expanded).
CONF_MAP 0x07
The client requests to the server to enumerate all mappings for a specified
web-application. The server replies to this message with a serie of MAP_ALLOW
and MAP_DENY packets, terminated by a MAP_DONE packet.
-
[integer] The web application unique id for this server.
CONF_MAP_ALLOW 0x08:
The server replies to a CONF_MAP message with those packets to indicate
a mapping to a static page, or a resource that can be served autonomously
by the remote end (the web server).
-
[string] An url-pattern as defined by the Servlet specification.
CONF_MAP_DENY 0x09
The server replies to a CONF_MAP message with those packets to indicate
a mapping to a resource that must be served by the server (servlet container).
-
[string] An url-pattern as defined by the Servlet specification.
CONF_MAP_DONE 0x0a
The server replies to a CONF_MAP message with this packet to indicate
that all servlet mappings have been successfully transfered to the other
end.
CONF_DONE 0x0e
Client issues this message when all configurations have been processed.
CONF_PROCEED 0x0f
Server issues this message in response to a CONF_DONE message, to acknowledge
its readiness to accept requests.
REQ_INIT 0x10
The client requests to the WARP server that a request is about to be
processed.
-
[integer] The web-application unique ID for this server. (From the
CONF_MAP).
-
[string] The HTTP method used for this request.
-
[string] The request URI.
-
[string] The request query arguments.
-
[string] The request protocol (HTTP/1.0, HTTP/1.1...).
REQ_CONTENT 0x11
The mime content type and length of this request.
-
[string] The MIME content type of this reques.
-
[integer] The content length of this request.
REQ_SCHEME 0x12
The scheme description of this request.
-
[string] The scheme (part before :// in the URL) of this request.
REQ_AUTH 0x13
Authentication information of the HTTP remote peer.
-
[string] The remote-user name.
-
[string] The authentication information.
REQ_HEADER 0x14
An HTTP request header. There are severals.
-
[string] The header name.
-
[string] The header value.
REQ_SERVER 0x15
The HTTP server information.
-
[string] The HTTP server host name.
-
[string] The HTTP server IP address.
-
[ushort] The port receiving the HTTP request.
REQ_CLIENT 0x16
The HTTP client (remote peer) information.
-
[string] The HTTP client host name.
-
[string] The HTTP client IP address.
-
[ushort] The remote port originating the HTTP request.
REQ_PROCEED 0x1f
The client finished transmitting the request. The server can now proceed
and process the request.
ASK_SSL 0x43
The WARP server (Tomcat) asks the WARP client to transfer the basic
SSL information (cypher, keysize and session).
ASK_SSL_CLIENT 0x44
The WARP server (Tomcat) asks the WARP server to transfer the client
certificate. (just the first element of the chain and the webserver
should request for it to the browser if possible).
REP_SSL_CERT 0x52
The client certificate (remote peer).
-
[string] The client certificate. (PEM format).
REP_SSL 0x53
SSL information.
-
[string] The cipher_suite.
-
[string] The ssl session. (That is not in the spec's).
-
[ushort] size of the algorithm (56-128).
REP_SSL_NO 0x5F
The requested SSL information is not available.
CBK_READ 0x40
A request callback. The WARP server queries the WARP client (HTTP
server) to transmit a chunk of the request body.
-
[ushort] The max number of bytes the server is able to receive.
CBK_DATA 0x41
As requested by the WARP server, the WARP client (HTTP server) transmits
a chunk of the request body.
-
[raw] A chunk of the request body.
CBK_DONE 0x42
The WARP client (HTTP server) informs the WARP server that the request
body has been fully transmitted.
RES_STATUS 0x20
The server replies with the HTTP response status for the request.
-
[ushort] The HTTP status of the response.
-
[string] The HTTP response message.
RES_HEADER 0x21
An HTTP MIME response header to send to the client. There are severals
of these.
-
[string] The MIME header name.
-
[string] The MIME header value.
RES_COMMIT 0x2f
The server indicates that the first part of the response (HTTP status
line and MIME headers) are to be committed to the client (remote peer).
RES_BODY 0x30
The HTTP response body.
-
[raw] A chunk of the response body. Up to 65535 bytes.
RES_DONE 0x3f
The server finished transmitting the response.