Skip to end of metadata
Go to start of metadata

Protocol negotiation


Protocol Negotiation

In order to use the existing Geode client/server infrastructure, we will be leveraging the current Geode "cache server" component.  In the current server implementation, the server expects an initial "handshake" byte, which tells the server the client protocol and how it should be handled. A client, using the new protocol, can connect with the Geode server by sending a protocol byte. Initially, this protocol will begin with the byte 110.

Protocol Field Definitions

It is advised to read the Protocol Field Definitions page before reading this document to understand the data types referenced.

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. 

Additional Request and Response message definitions can be found in the API's section.

Message definition grammar

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

optional[ ... ]
repetition{ ... }
Grouping( ... )

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.

Message = MessageHeader (Request Response)Description
MessageHeadertype = MessageHeaderThe MessageHeader corresponding to this Message.
Requesttype = RequestThis field will contain the Request component.

type = Response


This field will contain the Response component.


The Message header is a fixed size header which contains the size of a message, boolean flag to indicates whether a message is partial, and correlation id for that request message. The correlation id is used for the dual purpose here.

  • If a message is sent in multiple sub-messages, then it will be used for combining the whole message. 
  • It will be used for correlating the request to its response.
MessageHeader = Size CorrelationId isPartialMessage hasMetaDataDescription
Sizetype = int32Size of request or response (not including this header)
CorrelationIdtype = int32The correlationID used to match a request to its corresponding response. This will be important if/when we allow for out-of-order messages in the future.
isPartialMessagetype = booleanIs this a partial message? The exact semantics of partial messages is to be determined.


The request contains optional metadata and the request structure itself. 

Request = [MetaData] RequestAPI
MetaDataoptional, type = MetaDataThis field is optional and will be populated if the MessageHeader.hasMeta is true


type = variable

The specific Request message. Here are some examples of Request messages.

PutRequest | GetRequest | PutAllRequest | GetAllRequest |ServerConfigRequest | ClientConfigRequest | AuthRequest


The response contains optional metadata and the return value.

Response = [MetaData] APIResponse


optional, type = MetaData

This field is optional and will be populated if the MessageHeader.hasMeta is true
APIResponsetype = variable

The Api specific Reponse message. Here are some examples of Response messages

PutResponse GetResponse | PutAllResponse | GetAllResponse | ServerConfigResposne | ClientConfigResponse | AuthResponse | ErrorResponse


The server will raise the error when it failed to execute API request from the client. The error code and message should help the client to diagnose the issue.

ErrorResponse = errorMessageDescription
errorMessagetype = StringThe error message


EncodedValue represents a serialized value in a format that Geode can understand. It is used for both keys and values in database requests.

Value = {ValueHeader value}Description
encodingTypetype = int8 (encoding type)The encoding type of the following bytes.
valuetype = bytesSerialized Value Object which Geode can understand

Encoding Types

Currently supported types are:

Int32-bit signed integer, big-endian encoded
Long64-bit signed integer, big-endian encoded
Short16-bit signed integer, big-endian encoded
Byte8-bit signed integer, big-endian encoded
BooleanTrue or False.
StringUTF-8 encoded string. (whether it can contain nulls is TBD)
BinaryA binary blob to be stored in the region.
JSONUTF-8 encoded string, containing a JSON document that will be deserialized in the same way as the REST API.
Float32-bit floating point number.
Double64-bit floating point number.



The purpose of a metadata to pass defined key value pair with request and response. That will be optional for a client. If there is any metadata associated with request or response, then need to set "hasMetadata" flag to "true" in request or response header. After that send metadata in the following format.

MetaData = NumberOfMetadata { MetadataKeyId MetadataKeyValue} Description
NumberOfMetadatatype = int16The number of MetaDataKeyId : MetaDataKeyValue combinations
MetadataKeyIdtype = int16Supported MetaDataKeyId's can be found in the table "Supported MetaData - MetaData KeyId"
MetadataKeyValuetype = variableThe MetaData value for the KeyId. The supported dataType can be found in the table "Supported MetaData - MetaData Value Type"

Supported MetaData

 We would have following pre-defined key and value for a metadata. Note this list will grow over time.

MetaData for Requests

Request MetaData Key
MetaData KeyId
MetaData Value example
MetaData Value Type



type = boolean

Geode will expect key as JSON string(or bytes) and it will convert that string into PDX key.

If the response requires a key, then it will convert the PDX key to JSON string(or bytes) back.





type = boolean

Geode will expect Value as JSON string(or bytes) and it will convert that string into PDX value.

If the response requires a value, then it will convert PDX value to JSON string(or bytes) back.




EventId {

uniqueId: type = String


SequenceId: type=int64


type = bytes

The eventid is used to identify same region event in Geode. Geode keeps map of "uniqueId + threadId" Vs

"SequenceId" to know whether region event has been already seen or not.


MetaData for Responses

Response MetaData Key
MetaData KeyId
MetaData Value example
MetaData Value Type



type = boolean

[optional]The server accepted and forwarded the request to the appropriate

node holding the affected cache entry.  A smart client should refresh its partitioned

region location metadata for higher performance.

  • No labels