connectors/webapp/docs/warp.xml

<?xml version="1.0"?>

<document title="WARP 0.10">
  <description>
    The WARP protocol version 0.10
  </description>

  <section title="Introduction">
    <description>
      An overview of the WARP protocol
    </description>

    <p>
      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.
    </p>
    
    <p>
      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.
    </p>

    <p>
      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.
    </p>
  </section>

  <section title="Packet Structure">
    <description>
      The structure of a generic WARP packet.
    </description>

    <p>
      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).
    </p>

    <p>
      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:
    </p>

    <ul>
      <li>
        An 8 bits long <b>packet type</b> 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.
      </li>
      <li>
        A 16 bits long <b>payload length</b> specifying the length of the
        payload carried by this packet.
      </li>
      <li>
        A zero-or-more bytes long <b>payload</b>. The length (in bytes) of
        this part must be specified in the previous two bytes (payload length).
      </li>
    </ul>

    <img src="images/packet.gif" alt="The WARP Packet Structure"/>

  </section>

  <section title="Payload">
    <description>
      Payload Structure
    </description>

    <p>
      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.
    </p>
  
    <p>
      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).
    </p>

    <p>
      A string is somehow more complex, and it is defined in the following way:
    </p>
    
    <ul>
      <li>
        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.
      </li>
      <li>
        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.
      </li>
      <li>
        If length is 0x0, the string is assumed to be the empty string.
      </li>
      <li>
        If length is 0x0ffff, the string is assumed to be the null string.
      </li>
    </ul>
  
    <img src="images/string.gif" alt="The &#34;FooX&#34; string"/>

</section>

<section title="Packet Types">
  <description>
   The following is a list of packet types and their relative expected
   responses:
  </description>
<p>
<table>
<tr>
<td5>Packet/States Table</td5>
</tr>

<tr>
<td>Name</td>

<td>Type</td>

<td>Originator</td>

<td>Description</td>

<td>Expects</td>
</tr>

<tr>
<td>ERROR</td>

<td>0x00</td>

<td>Client Server</td>

<td>One end of the peer notifies the other of a fatal connection error</td>

<td>N/A</td>
</tr>

<tr>
<td>DISCONNECT</td>

<td>0xfe</td>

<td>Client Server</td>

<td>One end of the peer notifies the other that the connections is going
to be closed</td>

<td>N/A</td>
</tr>

<tr>
<td>FATAL</td>

<td>0xff</td>

<td>Client
<br/>Serve</td>

<td>A protocol error occourred, the connection must be closed.</td>

<td>N/A</td>
</tr>

<tr>
<td></td>

<td></td>

<td></td>

<td></td>

<td></td>
</tr>

<tr>
<td>CONF_WELCOME</td>

<td>0x01</td>

<td>Server</td>

<td>First message sent by Server after a client connection.</td>

<td>CONF_DEPLOY</td>
</tr>

<tr>
<td>CONF_DEPLOY</td>

<td>0x05</td>

<td>Client</td>

<td>Deploy a web application.</td>

<td>CONF_APPLIC</td>
</tr>

<tr>
<td>CONF_APPLIC</td>

<td>0x06</td>

<td>Server</td>

<td>Application deployed successfully.</td>

<td>CONF_MAP, CONF_DEPLOY</td>
</tr>

<tr>
<td>CONF_MAP</td>

<td>0x07</td>

<td>Client</td>

<td>Require for application mapping information</td>

<td>CONF_MAP_DONE,CONF_MAP_ALLOW,CONF_MAP_DENY</td>
</tr>

<tr>
<td>CONF_MAP_ALLOW</td>

<td>0x08</td>

<td>Server</td>

<td>Allow client to map the request</td>

<td>N/A</td>
</tr>

<tr>
<td>CONF_MAP_DENY</td>

<td>0x09</td>

<td>Server</td>

<td>Deny client to map the request</td>

<td>N/A</td>
</tr>

<tr>
<td>CONF_MAP_DONE</td>

<td>0x0a</td>

<td>Server</td>

<td>All the ALLOW/DENY map have been transfered</td>

<td>CONF_DEPLOY, CONF_DONE</td>
</tr>

<tr>
<td>CONF_DONE</td>

<td>0x0e</td>

<td>Client</td>

<td>Configuration completly sent to the server</td>

<td>CONF_PROCEED</td>
</tr>

<tr>
<td>CONF_PROCEED</td>

<td>0x0f</td>

<td>Server</td>

<td>Server ready to accept requests.</td>

<td>Request elements (REQ_INIT, REQ_CONTENT, REQ_SCHEME, REQ_AUTH, REQ_HEADER,
REQ_SERVER, REQ_CLIENT, REQ_PROCEED)</td>
</tr>

<tr>
<td></td>

<td></td>

<td></td>

<td></td>

<td></td>
</tr>

<tr>
<td>REQ_INIT</td>

<td>0x10</td>

<td>Client</td>

<td>New request.</td>

<td>N/A</td>
</tr>

<tr>
<td>REQ_CONTENT</td>

<td>0x11</td>

<td>Client</td>

<td>Mine type and length</td>

<td>N/A</td>
</tr>

<tr>
<td>REQ_SCHEME</td>

<td>0x12</td>

<td>Client</td>

<td>Scheme</td>

<td>N/A</td>
</tr>

<tr>
<td>REQ_AUTH</td>

<td>0x13</td>

<td>Client</td>

<td>Authentication</td>

<td>N/A</td>
</tr>

<tr>
<td>REQ_HEADER</td>

<td>0x14</td>

<td>Client</td>

<td>Header element</td>

<td>N/A</td>
</tr>

<tr>
<td>REQ_SERVER</td>

<td>0x15</td>

<td>Client</td>

<td>server information</td>

<td>N/A</td>
</tr>

<tr>
<td>REQ_CLIENT</td>

<td>0x16</td>

<td>Client</td>

<td>remote peer information</td>

<td>N/A</td>
</tr>

<tr>
<td>REQ_PROCEED</td>

<td>0x1f</td>

<td>Client</td>

<td>process request</td>

<td>Reponse elements, ASK_SSL, ASK_SSL_CLIENT or CBK_READ.</td>
</tr>

<tr>
<td></td>

<td></td>

<td></td>

<td></td>

<td></td>
</tr>

<tr>
<td>ASK_SSL</td>

<td>0x43</td>

<td>Server</td>

<td>Request SSL information</td>

<td>REP_SSL_NO, REP_SSL</td>
</tr>

<tr>
<td>ASK_SSL_CLIENT</td>

<td>0x44</td>

<td>Server</td>

<td>Request for CC</td>

<td>REP_SSL_NO, REP_SSL_CERT</td>
</tr>

<tr>
<td>REP_SSL_NO</td>

<td>0x5f</td>

<td>Client</td>

<td>SSL information not available.</td>

<td>Reponse elements.</td>
</tr>

<tr>
<td>REP_SSL</td>

<td>0x52</td>

<td>Client</td>

<td>SSL information.</td>

<td>Reponse elements.</td>
</tr>

<tr>
<td>REP_SSL_CERT</td>

<td>0x53</td>

<td>Client</td>

<td>Client certificate.</td>

<td>Reponse elements.</td>
</tr>

<tr>
<td></td>

<td></td>

<td></td>

<td></td>

<td></td>
</tr>

<tr>
<td>CBK_READ</td>

<td>0x40</td>

<td>Server</td>

<td>Request for body data.</td>

<td>CBK_DATA, CBK_DONE</td>
</tr>

<tr>
<td>CBK_DATA</td>

<td>0x41</td>

<td>Client</td>

<td>Chunk of data.</td>

<td>CBK_READ or Reponse elements.</td>
</tr>

<tr>
<td>CBK_DONE</td>

<td>0x42</td>

<td>Client</td>

<td>End of data.</td>

<td>Reponse elements.</td>
</tr>

<tr>
<td></td>

<td></td>

<td></td>

<td></td>

<td></td>
</tr>

<tr>
<td>RES_STATUS</td>

<td>0x20</td>

<td>Server</td>

<td>HTTP status.</td>

<td>N/A</td>
</tr>

<tr>
<td>RES_HEADER</td>

<td>0x21</td>

<td>Server</td>

<td>response header.</td>

<td>N/A</td>
</tr>

<tr>
<td>RES_COMMIT</td>

<td>0x2f</td>

<td>Server</td>

<td>send data to browser.</td>

<td>N/A</td>
</tr>

<tr>
<td>RES_BODY</td>

<td>0x30</td>

<td>Server</td>

<td>data reponse element</td>

<td>N/A</td>
</tr>

<tr>
<td>RES_DONE</td>

<td>0x3f</td>

<td>Server</td>

<td>end of reponse</td>

<td>Request elements.</td>
</tr>
</table>
</p>

</section>

<section  title="Type Details">
  <description>
    Packet Type Details
  </description>

<p><br/><b>ERROR</b> 0x00
<br/>Specifies an unrecoverable protocol error. After the client or the
server issues this packet the socket underlying the WARP connection must
be closed.
<br/>This message can be sent at any time by the client or the server.
<ul>
<li>
[string]: A detail message on why the connection must be closed.</li>
</ul>
</p><p>
<b>DISCONNECT</b> 0xfe
<br/>The client or the server is going to close the connection (no fatal
protocol error).
</p><p><b>FATAL</b> 0x0ff
<br/>A protocol error occourred, the connection must be closed.
<ul>
<li>
[string]: An error message.</li>
</ul>
</p><p>
<b>CONF_WELCOME</b> 0x01
<br/>The server issues this packet when a connection is opened. The server
awaits for configuration information.
<ul>
<li>
[ushort] Major protocol version.</li>

<li>
[ushort] Minor protocol version.</li>

<li>
[integer] The server unique-id.</li>
</ul>
</p><p>
<b>CONF_DEPLOY </b>0x05
<br/>The client attempts to deploy a web application.
<ul>
<li>
[string] The application name.</li>

<li>
[string] The virtual host name.</li>

<li>
[ushort] The virtual host port.</li>

<li>
[string] The web-application URL path.</li>
</ul>
</p><p>
<b>CONF_APPLIC</b> 0x06
<br/>The server replies to a CONF_DEPLOY message with the web application
identifier of the configured application.
<ul>
<li>
[integer] The web application unique id for this server.</li>

<li>
[string] The web application real path (where it's expanded).</li>
</ul>
</p><p>
<b>CONF_MAP</b> 0x07
<br/>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.
<ul>
<li>
[integer] The web application unique id for this server.</li>
</ul>
</p><p>
<b>CONF_MAP_ALLOW</b> 0x08:
<br/>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).
<ul>
<li>
[string] An url-pattern as defined by the Servlet specification.</li>
</ul>
</p><p>
<b>CONF_MAP_DENY</b> 0x09
<br/>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).
<ul>
<li>
[string] An url-pattern as defined by the Servlet specification.</li>
</ul>
</p><p>
<b>CONF_MAP_DONE</b> 0x0a
<br/>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.
</p><p>
<b>CONF_DONE</b> 0x0e
<br/>Client issues this message when all configurations have been processed.
</p><p><b>CONF_PROCEED</b> 0x0f
<br/>Server issues this message in response to a CONF_DONE message, to acknowledge
its readiness to accept requests.
</p><p><b>REQ_INIT</b> 0x10
<br/>The client requests to the WARP server that a request is about to be
processed.
<ul>
<li>
[integer] The web-application unique ID for this server. (From the
CONF_MAP).</li>

<li>
[string] The HTTP method used for this request.</li>

<li>
[string] The request URI.</li>

<li>
[string] The request query arguments.</li>

<li>
[string] The request protocol (HTTP/1.0, HTTP/1.1...).</li>
</ul>
</p><p>
<b>REQ_CONTENT</b> 0x11
<br/>The mime content type and length of this request.
<ul>
<li>
[string] The MIME content type of this reques.</li>

<li>
[integer] The content length of this request.</li>
</ul>
</p><p>
<b>REQ_SCHEME</b> 0x12
<br/>The scheme description of this request.
<ul>
<li>
[string] The scheme (part before :// in the URL) of this request.</li>
</ul>
</p><p>
<b>REQ_AUTH</b> 0x13
<br/>Authentication information of the HTTP remote peer.
<ul>
<li>
[string] The remote-user name.</li>

<li>
[string] The authentication information.</li>
</ul>
</p><p>
<b>REQ_HEADER</b> 0x14
<br/>An HTTP request header. There are severals.
<ul>
<li>
[string] The header name.</li>

<li>
[string] The header value.</li>
</ul>
</p><p>
<b>REQ_SERVER </b>0x15
<br/>The HTTP server information.
<ul>
<li>
[string] The HTTP server host name.</li>

<li>
[string] The HTTP server IP address.</li>

<li>
[ushort] The port receiving the HTTP request.</li>
</ul>
</p><p>
<b>REQ_CLIENT</b> 0x16
<br/>The HTTP client (remote peer) information.
<ul>
<li>
[string] The HTTP client host name.</li>

<li>
[string] The HTTP client IP address.</li>

<li>
[ushort] The remote port originating the HTTP request.</li>
</ul>
</p><p>
<b>REQ_PROCEED</b> 0x1f
<br/>The client finished transmitting the request. The server can now proceed
and process the request.
</p><p>
<b>ASK_SSL</b> 0x43
<br/>The WARP server (Tomcat) asks the WARP client to transfer the basic
SSL information (cypher, keysize and session).
</p><p><b>ASK_SSL_CLIENT</b> 0x44
<br/>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).
</p><p>
<b>REP_SSL_CERT</b> 0x52
<br/>The client certificate (remote peer).
<ul>
<li>
[string] The client certificate. (PEM format).</li>
</ul>
</p><p>
<b>REP_SSL</b> 0x53
<br/>SSL information.
<ul>
<li>
[string] The cipher_suite.</li>

<li>
[string] The ssl session. (That is not in the spec's).</li>

<li>
[ushort] size of the algorithm (56-128).</li>
</ul>
</p><p>
<b>REP_SSL_NO</b> 0x5F
<br/>The requested SSL information is not available.
</p><p>
<b>CBK_READ</b> 0x40
<br/>A request callback. The WARP server queries the WARP client (HTTP
server) to transmit a chunk of the request body.
<ul>
<li>
[ushort] The max number of bytes the server is able to receive.</li>
</ul>
</p><p>
<b>CBK_DATA</b> 0x41
<br/>As requested by the WARP server, the WARP client (HTTP server) transmits
a chunk of the request body.
<ul>
<li>
[raw] A chunk of the request body.</li>
</ul>
</p><p>
<b>CBK_DONE</b> 0x42
<br/>The WARP client (HTTP server) informs the WARP server that the request
body has been fully transmitted.
</p><p>
<b>RES_STATUS</b> 0x20
<br/>The server replies with the HTTP response status for the request.
<ul>
<li>
[ushort] The HTTP status of the response.</li>

<li>
[string] The HTTP response message.</li>
</ul>
</p><p>
<b>RES_HEADER</b> 0x21
<br/>An HTTP MIME response header to send to the client. There are severals
of these.
<ul>
<li>
[string] The MIME header name.</li>

<li>
[string] The MIME header value.</li>
</ul>
</p><p>
<b>RES_COMMIT</b> 0x2f
<br/>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).
</p><p>
<b>RES_BODY</b> 0x30
<br/>The HTTP response body.
<ul>
<li>[raw] A chunk of the response body. Up to 65535 bytes.</li>
</ul>
</p><p>
<b>RES_DONE</b> 0x3f
<br/>The server finished transmitting the response.
</p>

</section>

</document>