Swap:Custom Protocol

SWAP has a custom protocol available that is used for management and inter-node communication. This is a persistent socket connection between nodes. This is not run over http due to the small size of most messages and overhead in establishing a connection for each message.

Mina

SWAP uses mina to manage socket communication. Protocol decoding is handled through a set of filters and a final handler to dispatch command.

The SwapProtocolEncoder/Decoder filters translates messages to and from SwapMessages. These SwapMessages are delivered to the registered mina handler. The NetworkIOHandler class provides a simple mechanism for decoding SwapMessages and dispatching multiple calls corresponding to the type of message received.

Wire-level message Structure

Each SWAP command is sent as a list of a single SWAP message. This is done to allow efficient packing of small messages (ie, results of stat, etc)

• Int - size of message (type + reps + content)
• short - message type (See MessageType enum)
• short - repetitions of message
• byte[] - content

Content is the list of packed messages. Each message is composed of a set of primitive segments (long, string, uuid, long[], etc). What segments comprise a message are described in the MessageType enum. Allowable types of segments are defined in MessageSegment.

For example, the GET_PATH_DETAILS request has the following structure:

• UUID - uuid of file group
• STRING[] - list of paths for details w/in that file group.

To request for just one group the message would have the following information:

• size=message size
• type=13,
• reps=1
• UUID of file group
• "path1","path2"

Since we can issue multiple requests of the same message, in one message, we could include a request for files from two different groups. This message would look slightly different:

• size=message size
• type=13
• reps=2
• UUID of group 1
• "path1","path2"
• UUID of group 2
• "path3","path4"

This packing and unpacking is handled by the two mina filters, SwapProtocolEncoder and SwapProtocolDecoder. These two filters encode/decode messages to and from an array of SwapMessage. A SwapMessage is a simple container holding the type of message along w/ the an array of Objects representing the message content. The size of the content is equal to the number of segments in a message * the number of repetitions in a message.

Authentication

Due to how swap authenticates against LDAP, clients must supply a clear-text username and password to the server. To secure this, an ssl tunnel is established during the initial connection to a swap server. As part of authentication a client will instruct the server whether or not it should keep the ssl connection enabled, disable it, or let server decide. The server will respond with an AUTH_RESPONSE indicating success/failure and whether SSL will remain enabled. The server is able to override a clients request to disable or keep ssl enabled.

1. Connect to server
2. Start SSL Tunnel
3. Server: Send SASL_MECHANISMS
4. Client: Send SASL_REQUEST
5. Server: send SASL_RESPONSE. (repeat req/response)
6. On success, client and server toggle SSL state.
7. Client requests whatever startup junk it needs

Once a client authenticated, it may not re-authenticate as a different user, a reconnect is required.

The SwapAuthFilter filter intercepts authentication requests and handles enabling/disabling ssl. In addition, it ensures that no authentication information is delivered to the higher level handler, and that no requests are processed until a client has successfully authenticated.