...

The high-level goals for the protocol are defined here.

Message Definition

A message is a series of bytes which contains the request or response. If the message is large, then we will have provision to divide the message into small messages. In that case, client/server needs to collect all messages to parse the request/response.

The message will be sent in following way.  A client can send the multiple messages on the connection and the server will respond to those messages in same order. 

Message definition grammar

In order to consistently define messages the Extended Backus–Naur form grammar will be used.

...

Every message will adhere to the following generic message definition. A Message will comprise of a MessageHeader and either a Request or Response component.

Protocol Terminology

  Any binary protocol requires the following things:

• Version: This indicates the API version.

• Correlation Id: This should be different per request sent. It allows correlation of request and response.

• Object Type: The type of a serialized object.

• Response Type: It indicates whether a response is partial or complete.

• ErrorCodes: It indicates the problem with API invocation.

• Chunk Response: Send large response in multiple chunks.

• Continuous Response: Client can register(Observer pattern) for events and then server notify the client if those events occur.

• Request: It indicates client's message

• Response: It indicates server's message.

• Request Format: Format of request API and its parameters, which client wants to invoke.

• Response Format: Format for API return value, which client invoked.

• Message: Set of bytes which contain the Message Header and Request/Response.

• Serialized Byte Order: Big Endian

Connect 

In order to fit into the existing Geode client/server infrastructure, we will be leveraging the current Geode "cache server" component.  It accepts an initial byte that tells it what type of client is connecting to the server and how the client should be handled. A client using the new protocol can connect with the Geode server by sending a protocol byte. Initially, we will support the following two protocols:

• byte - 110: Message will contain the whole request or response. 
• byte - 111: If the message is large then client or server can divide the message into the set of small messages. Then they need to collect all the small message and parse the whole request or response.

We may add additional protocol definitions here to indicate the use of an alternative serialization mechanism.  For instance bytes 112 & 113 might indicate the but require the server to use Protobuf for serialization of client/server messages.  How we handle other serialization libraries will be addressed when the pluggable-serialization architecture is roughed out.

API Id

The ApiId recognizes the API, a client wants to invoke on the server. The request format will contain the 2-byte(int16) for API id. It will be marked as ApiId in the request format.

API Version

API version will be associated with the request API. The request format will contain a 1-byte(int8) for the version. It will be marked as ApiVersion in the request format. Its current value will be 1.

Correlation Id

The purpose of correlation id to match the request and its corresponding response. The request format will contain the 4-bytes(int32) for correlation Id. It will be marked as CorrelationId in the request and response format. The client needs to send correlation id with the request and server will send the same id with the response.

Object Type

We will support all the object types which Geode understands. This would include all the primitive java types, an array of primitive types, collections, java serialization, data serializable, PDX serialization and custom user data serializers. The client needs to serialize objects as described here.  This might be extended as part of making the Geode storage format pluggable.

ObjectKeyType

Geode supports only few object types as the region Key. The region key will be marked as Key in the request format. the client needs to serialize key as described here.

ResponseType

The Response Type indicates whether the response is partial or complete. The response with the FullResponse type id indicates the completion of that request. And the response with PartialResponse type id indicates the response is partial. The response format will contain the 2-bytes(int16) for response type. It will be marked as ResponseTypeId in the response format.

Error Codes

The Error codes indicate the issue with the invocation of API at the server. We have defined the error code for various issues here. The response format will contain the 2-bytes(int16) for error codes. It will be marked as ErrorCode in the response format.

ProtocolType

The protocol descriptions use the following types. These may be mapped to a pluggable serialization description language but their native serialization is described here.  The native serialization uses network byte order ("big-endian").

Message Definition

A message is a series of bytes which contains the request or response. If the message is large, then we will have provision to divide the message into small messages. In that case, client/server needs to collect all messages to parse the request/response.

The message will be sent in following way.  A client can send the multiple messages on the connection and the server will respond to those messages in same order. 

Message definition grammar

In order to consistently define messages the Extended Backus–Naur form grammar will be used.

Generic Message definition

Every message will adhere to the following generic message definition. A Message will comprise of a MessageHeader and either a Request or Response component.

Connect 

In order to fit into the existing Geode client/server infrastructure, we will be leveraging the current Geode "cache server" component.  It accepts an initial byte that tells it what type of client is connecting to the server and how the client should be handled. A client using the new protocol can connect with the Geode server by sending a protocol byte. Initially, we will support the following two protocols:

• byte - 110: Message will contain the whole request or response. 
• byte - 111: If the message is large then client or server can divide the message into the set of small messages. Then they need to collect all the small message and parse the whole request or response.

We may add additional protocol definitions here to indicate the use of an alternative serialization mechanism.  For instance bytes 112 & 113 might indicate the but require the server to use Protobuf for serialization of client/server messages.  How we handle other serialization libraries will be addressed when the pluggable-serialization architecture is roughed out.

API Id

The ApiId recognizes the API, a client wants to invoke on the server. The request format will contain the 2-byte(int16) for API id. It will be marked as ApiId in the request format.

API Version

API version will be associated with the request API. The request format will contain a 1-byte(int8) for the version. It will be marked as ApiVersion in the request format. Its current value will be 1.

Correlation Id

The purpose of correlation id to match the request and its corresponding response. The request format will contain the 4-bytes(int32) for correlation Id. It will be marked as CorrelationId in the request and response format. The client needs to send correlation id with the request and server will send the same id with the response.

Object Type

We will support all the object types which Geode understands. This would include all the primitive java types, an array of primitive types, collections, java serialization, data serializable, PDX serialization and custom user data serializers. The client needs to serialize objects as described here.  This might be extended as part of making the Geode storage format pluggable.

ObjectKeyType

Geode supports only few object types as the region Key. The region key will be marked as Key in the request format. the client needs to serialize key as described here.

ResponseType

The Response Type indicates whether the response is partial or complete. The response with the FullResponse type id indicates the completion of that request. And the response with PartialResponse type id indicates the response is partial. The response format will contain the 2-bytes(int16) for response type. It will be marked as ResponseTypeId in the response format.

Error Codes

The Error codes indicate the issue with the invocation of API at the server. We have defined the error code for various issues here. The response format will contain the 2-bytes(int16) for error codes. It will be marked as ErrorCode in the response format.

ProtocolType

The protocol descriptions use the following types. These may be mapped to a pluggable serialization description language but their native serialization is described here.  The native serialization uses network byte order ("big-endian").

Anchor
MessageHeader MessageHeader

...

RequestHeader

The request header contains the ApiId, ApiVersion, and hasMetaData flag to indicate whether the request contains some metadata.

...

ResponseHeader

...