[jboss-dev-forums] [JBoss Remoting Development] Document updated/added: "R3.1 Remote Protocol Specification"

[David Lloyd]

JBoss development,

The document "R3.1 Remote Protocol Specification", was updated Jan 6, 2010
by David Lloyd.

To view the document, visit:
http://community.jboss.org/docs/DOC-14535#cf

Document:
--------------------------------------------------------------
h1. Remote Protocol Specification
 
h2. Table of Contents
 
* 
#Remote_Protocol_Specification


** 
#Table_of_Contents


** 
#Overview


** 
#Message_Format


*** 
#Framing


*** 
#Header


**** 
#First_and_Last_Markers


**** 
#End_of_Data_Marker


*** 
#Flow_Control


** 
#Negotiation


** 
#Security


*** 
#Confidentiality


*** 
#Authentication


** 
#Remoting_Clients


** 
#Remoting_Requests_And_Replies



 
h2. Overview
 
The "remote" protocol is the protocol by which two Remoting 3 endpoints may be connected to communicate with one another.  The protocol requirements are:
1. Security: provide authentication and confidentiality support for clients and servers
2. Concurrency: allow multiple clients and requests to be active concurrently
3. Streaming: allow embedded streams
4. Efficiency: Make requests as compact as possible.
5. Performance: Provide equivalent or better latency characteristics than Remoting 2.
 
h2. Message Format
h3. Framing
Since the "remote" protocol is a message-oriented protocol, and TCP is a stream-oriented protocol, an additional level of framing is required.  The "remote" protocol uses a simple length-data framing scheme.
 
                      Bit #:
          7   6   5   4   3   2   1   0
  Byte# +---+---+---+---+---+---+---+---+
     0  |          Length (MSB)         |
        +-------------------------------+
     1  |          Length (LSB)         |
        +-------------------------------+
     2+ |            Data ...           |
        |                               |
        :                               :
        .                               .

 
Since every message has a predetermined length, the TCP_NODELAY socket option should *always* be employed to minimize message transmission latency on send.
h3. Header
All regular messages in the "remote" protocol have a common structure.  They are all preceded by a message header, which associates the message with a specific request, client, or stream channel.
 
                      Bit #:
          7   6   5   4   3   2   1   0
  Byte# +---+---+---+---+---+---+---+---+
     0  | L | F | A | X | S.Ch.ID (MSB) |
        +---+---+---+---+---+---+---+---+
     1  |    Source Channel ID (LSB)    |
        +---+---+---+---+---+---+---+---+
     2  | X | X | D | E | D.Ch.ID (MSB) |
        +---+---+---+---+---+---+---+---+
     3  |  Destination Channel ID (LSB) |
        +-------------------------------+
     4  |    Data...                    |
        :                               :
        .                               .

 
The meaning of each field is as follows:
* *X* - Reserved, set to 0 for forward compatibility.
* *L* - "Last", indicates that this message will be the last in the stream; once
* *F* - "First", indicates that this message is the first message in this direction for a channel pair.
* *A* - "Acknowledge", indicates that a previously received message should be acknowledged (see *flow control* for more information).
* *D* - "Data", a marker which indicates that the message contains a data message (with a length of zero or more).
* *E* - "End-of-data", a marker which indicates the end of a substream.
* *Source Channel ID* - the channel ID of the sender.
* *Destination Channel ID* - the channel ID of the recipient.
 
A subchannel is uniquely identified by a source/destination channel ID pair, not unlike how unique TCP connections are identified.  This means that more than one source channel ID can be connected to a destination channel ID, and there can be more than one connection with the same source ID, so long as the destination channel ID is different between each connection.
h4. First and Last Markers
The First and Last markers on a message delineate the beginning and ending of a connection.  Once a Last marker is read on the remote side, no further data will be received on the channel.  When a Last marker is both sent and received, the associated channel ID pair becomes free for reuse.
h4. End of Data Marker
The End-of-data marker does not have a significance to the overall protocol; it is used by the transport to mark the end of a message.  The bit will be set on the last packet of such a message.
h3. Flow Control
Flow control is accomplished by two mechanisms.  The first is a negotiated limit on the number of allowed concurrent subchannels.  When this limit is reached, the peer interested in establishing a new subchannel is forced to wait.  If the peer ignores the subchannel limit, the connection may be terminated immediately.
 
The second mechanism is a fixed window size associated with each subchannel.  For a subchannel with a window size of +N+, each peer may send up to +N+ messages on that subchannel without waiting for an "acknowledge" reply.  Further messages may not be sent until a message is received with the "A" bit set, at which time exactly one message is considered to be acknowledged.  If the window size for a subchannel is disregarded, the connection may be terminated immediately.
 
Such an acknowledgement may be sent in conjunction with a data message travelling in the opposite direction, or it may be sent as a standalone (dataless) message.
h2. Negotiation
In order to reach agreement on what features should be available on the connection (selecting a marshaller, agreeing on parameters such as class tables and so forth), a negotiation phase is employed after authentication completes but before requests may be transferred.
h2. Security
h3. Confidentiality
Confidentiality protection is implemented via TLS.  All TLS authentication options are supported, including but not limited to client authentication via TLS.  These connection parameters may be specified as options when the connection is created.
h3. Authentication
Server authentication occurs naturally via the TLS server certificate validation process.  While clients may also be authenticated via this process, SASL-based authentication is also performed by the server.  If, for some reason, client authentication is not desired via SASL, then a NULL SASL mechanism should be selected.  If both client and server authentication is desired via SASL, then an appropriate mechanism supporting both should be chosen.
 
h2. Remoting Clients
 
h2. Remoting Requests And Replies

--------------------------------------------------------------