An overview of the WARP protocol

The WARP protocol was inspired and designed by the great effort made by the Apache JServ team in finding a efficent stream-based protocol to transfer pre-parsed HTTP requests. Much of its structure was derived from the AJPv21 protocol, and has been updated to add few features, and remove its reparsing overhead.

When thinking about forwarding HTTP requests between a web server (Apache HTTPd) and a servlet container (Apache Tomcat), we must realize that much of the pre-parsing of the HTTP data is already performed by the web-server. Therefore, the scope of the WARP protocol is to minimize the overhead of re-transmitting a pre-parsed HTTP request to the servlet container, encoding data in a way that it's accessible in a very fast and efficent way, without adding a subsequent post-parsing stage.

In addition, the WARP protocol defines a way over which the HTTP server and the servlet container can negotiate their resources (in our case, web applications), maintaining a tight integration between the applications deployed by the servlet container, and their host mapping within the web server.

The structure of a generic WARP packet.

To minimize parsing overhead on both sides (HTTP server and servlet container) the WARP protocol defines a packet structure, which is used to encapsulate all data passed over a reliable full-duplex connection (the WARP connection).

Each byte (octet) in a WARP packet MUST be transmitted according to the "network order" (or big endian style), and each packet is composed of the following parts:

• An 8 bits long packet type describing the content of the following payload (if any), an operation to perform by the peer, or a reply to an operation requested by the peer.
• A 16 bits long payload length specifying the length of the payload carried by this packet.
• A zero-or-more bytes long payload. The length (in bytes) of this part must be specified in the previous two bytes (payload length).

The WARP Packet Structure

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 somehow more complex, and it is defined in the following way:

• The first two octets represent the string length as an unsigned 16 bits value. The 0x0 and 0x0ffff values (namely the sequence of all zero bits and the sequence of all one bits) have a special meaning.
• If the string length (first two octets) is not 0x0 or 0x0ffff, a sequence of bytes follow, as long as the number of bytes specified in length. The bytes in this field are the UTF-8 representation of the string.
• If length is 0x0, the string is assumed to be the empty string.
• If length is 0x0ffff, the string is assumed to be the null string.

The "FooX" string

The following is a list of packet types and their relative expected responses:

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.