Introduction
Geode is a reliable distributed data management tool. There is a demand to access Geode from various programming languages. But the existing client-server protocol is too complex to understand, and it’s not even documented. That establishes the need for a new client-server protocol.
Protocol Terms
Any binary protocol will require following things
Version: This indicates the API version.
Request Type: This indicates API needs to invoke.
Correlation Id: This helps to relate request-response.
Object Type: What is the type of serialized object.
Response Type: It indicates whether a response is partial or complete.
ErrorCodes: It indicates the problem with API invocation.
Streaming support: To support the large request, response or continuous response.
Request Format: Api request and response.
Byte Order(Big Endian)
Message: Bytes which contains defined format.
Request: It indicates client's message
Response: It indicates server's message.
Connect
The new protocol will be integrated with current Geode server. The new client driver can connect with Geode server by sending byte “110”.
Request Type
Following table contains the request type and its corresponding id. RequestTypeId would recognize the API, which client want to invoke on the server. The request format will contain the 2-bytes(int16) for request type id. It will be marked as requestTypeId in request format.
RequestType | RequestTypeId |
---|---|
MetaDataConfigRequestType | 1 |
AuthenticationRequestType | 2 |
PutRequestType | 3 |
GetRequestType | 4 |
PutAllRequestType | 5 |
GetAllRequestType | 6 |
FunctionRequestType | 7 |
CreateRequestType | 8 |
InvalidateRequestType | 9 |
DestroyRequestType | 10 |
KeySetRequestType | 11 |
ValuesRequestType | 12 |
EntrySetRequestType | 13 |
ContainsValueForKeyRequestType | 14 |
ContainsKeyRequestType | 15 |
ContainsValueRequestType | 16 |
RemoveAllRequestType | 17 |
SizeRequestType | 18 |
PutIfAbsentRequestType | 19 |
RemoveIfValueIsSameRequestType | 20 |
ReplaceIfValueIsSameRequestType | 21 |
ReplaceIfValueExistType | 22 |
API Version
API version will be associated with request api. The request fromat will contain 1-byte for version. It will be marked as apiVerision in 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 request format.
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. For the purpose of the request format, we would distinguish key type and value type.
ObjectKeyType
Geode supports only few object types as the region Key. The region key will be marked as KeyObject in the request format.
ObjectValueType
All the supported Geode types can be defined as the region value. In the request format, the region value will be marked as ValueObject. The ValueObject will contain the serialized bytes. We will have the ability to send those bytes in the chunk.
ResponseType
ReponseType will indicate that whether the response is partial or complete. A client can process a partial response. Response with FullResponse type id will indicate the completion of that request.
The response format will contain the 2-bytes(int16) for response type. It will be marked as FullResponse or PartialResponse in the response format.
ResponseType | ResponseTypeId |
---|---|
FullResponse | 1 |
PartialResponse | 2 |
Error Codes
Error codes indicate the issue with the invocation of API at the server. We have following error code for various issues at the server. The response format will contain the 2-bytes(int16) for error codes. It will be marked as ErrorCode in the response format.
Exception Type | ErrorCode |
---|---|
AUTHENICATION_REQUIRED_EXCEPTION | 1 |
AUTHORIZATION_FAILED_EXCEPTION | 2 |
AUTHETICATIONFAILED_EXCEPTION | 3 |
BUCKET_MOVED_EXCEPTION | 4 |
SERIALIZATION_EXCEPTION | 5 |
INTERRUPTED_EXCEPTION | 6 |
ILLEGAL_ARGUMNET_EXCEPTION | 7 |
ILLEGAL_STATE_EXCEPTION | 8 |
TIMEOUT_EXCEPTION | 9 |
CACHE_WRITER_EXCEPTION | 10 |
REGION_EXIST_EXCEPTION | 11 |
REGION_NOT_EXIST_EXCEPTION | 12 |
LEASE_EXPIRED_EXCEPTION | 13 |
CACHE_LOADER_EXCEPTION | 14 |
REGION_DESTROYED_EXCEPTION | 15 |
ENTRY_DESTROYED_EXCEPTION | 16 |
ENTRY_NOT_FOUND_EXCEPTION | 17 |
FUNCTION_NOT_FOUND_EXCEPTION | 18 |
FUNCTION_ATTRIBUTE_MISMATCH_EXCEPTION | 19 |
FUNCTION_EXECUTION_EXCEPTION | 20 |
CONCURRENT_MODIFICATION_EXCEPTION | 21 |
UNKNOWN_EXCEPTION | 22 |
CLASS_CAST_EXCEPTION | 23 |
GEODE_IO_EXCEPTION | 24 |
NULL_POINTER_EXCEPTION | 25 |
ENTRY_EXIST_EXCEPTION | 26 |
DISK_ACCESS_EXCEPTION | 27 |
QUERY_EXCEPTION | 28 |
CACHE_CLOSED_EXCEPTION | 29 |
MESSAGE_FORMAT_EXCEPTION | 30 |
CACHE_LISTENER_EXCEPTION | 31 |
CQ_EXCEPTION | 32 |
CQ_CLOSED_EXCEPTION | 33 |
CQ_QUERY_EXCEPTION | 34 |
CQ_EXIST_EXCEPTION | 35 |
CQ_INVALID_EXCEPTION | 36 |
INVALID_DELTA_EXCEPTION | 37 |
TRANSACTION_EXCEPTION | 38 |
TRANSACTION_DATA_NODE_DEPARTED_EXCEPTION | 39 |
TRANSACTION_REBALANCED_EXCEPTION | 40 |
COMMIT_CONFLICT_EXCEPTION | 41 |
PUTALL_PARTIAL_RESULT_EXCEPTION | 42 |
Format Grammer
Format is described using Extended Backus–Naur form grammer.
ProtocolTypes
The format contains following fixed and variable types. They need to serialize in Big Indian byte order as showed for the example.
Type | Number Of Bytes | Value | SerializedBytes |
---|---|---|---|
boolean | Fixed = 1 | true | 0x01 |
boolean | Fixed = 1 | false | 0x00 |
int8 | Fixed = 1 | 1 | 0x01 |
int16 | Fixed = 2 | 1 | 0x00 0x01 |
int32 | Fixed = 4 | 1 | 0x00 0x00 0x00 0x01 |
String(utf) | Variable
| "Geode" | 0x00 0x05 (length) 0x47 0x65 0x6f 0x64 0x65 (utf encoding) |
Message(Framing)
A message is series of bytes which contains request or response. If the message is large, then we will have provision to divide the message into small messages. The message will be sent in following way.
Message --> MessageHeader (Request | Response) |
---|
MessageHeader --> defined below |
Request --> defined below |
Response --> defined below |
MessageHeader
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.
- The Client would use correlation id to match the response to its request as well.
MessageHeader --> Size isPartialMessage CorrelationId |
---|
Size --> fixedSize = 4 bytes, type = int32 (Size of request or response) |
isPartialMessage --> fixedSize = 1 byte, type = boolean |
CorrelationId --> fixedSize = 4 bytes, type = int32 |
Request Format
The request would contain the fixed size request header, optional metadata and Request api parameters. The request header will have requestType, apiVersion, and hasMetaData flag to indicate whether the request contains some metadata.
Request --> RequestTypeId apiVersion hasMetaData [MetaData] RequestAPI |
---|
RequestTypeId --> fixedSize = 2 bytes, type = int16 |
apiVersion --> fixedSize = 2 bytes, type = int16 |
hasMetaData --> fixedSize = 1 byte, type = boolean (if there is any meta data associated with this request) |
MetaData --> optional |
RequestAPI --> (PutRequest | GetRequest | PutAllRequest | GetAllRequest) |
Response Format
The response would contain the fixed size response header, optional metadata and return values. The resposne header will have resposneType, which indicates its partial response, full response or error. A hasMetaData flag indicates whether the response contains some metadata.
Response --> (ResponseTypeId | ErrorCode) hasMetaData [MetaData] APIResponse |
---|
ResponseTypeId --> fixedSize = 2 bytes, type = int16 |
ErrorCode --> fixedSize = 2 bytes, type = int16 |
hasMetaData --> fixedSize = 1 byte, type = boolean (if there is any meta data associated with this request) |
MetaData --> Optional |
APIResponse –> (PutResponse | GetResponse | PutAlLRequest | GetAllRequest) |
ValueObject
The purpose of ValueObject to divide the large serialized value into small value chunks. We will have SerializedBytesHeader with each partial serialized bytes. It would contain size of
ValueObject --> Serializedbytes |
---|
Serializedbytes --> SerializedBytesHeader PartialSerializedBytes {SerializedBytesHeader PartialSerializedBytes} |
SerializedBytesHeader --> Size isPartialBytes |
Size --> int32 (Number of serialized bytes) |
isPartialBytes --> boolean |
APIS
PutRequestResponse
PutRequest --> RegionName KeyObject CallbackArg ValueObject |
---|
RegionName --> String |
KeyObject --> Serialized bytes of Geode key object type |
CallbackArg –-> Serialized bytes of Geode object type |
PutResponse –-> Success |
---|
Success --> Boolean |
GetRequestResponse
GetRequest --> RegionName KeyObject CallbackArg |
---|
RegionName --> String |
KeyObject --> Serialized bytes of Geode key object type |
CallbackArg –-> Serialized bytes of Geode object type |
GetResponse --> Result |
---|
Result --> Serialized bytes of Geode object type |
GetAllRequestResponse
GetAllRequest --> RegionName NumberOfKeys KeyObject {KeyObject} CallbackArg |
---|
RegionName --> String |
NumberOfKeys --> int |
KeyObject --> Serialized bytes of Geode key object type |
CallbackArg –-> Serialized bytes of Geode object type |
GetAllResponse --> NumberOfResults KeyObject Result {KeyObject Result} |
---|
KeyObject Result --> int |
Result --> Serialized bytes of Geode object type |
PutAllRequestResponse
PutAllRequest --> RegionName NumberOfKeys KeyObject ValueObject {KeyObject ValueObject} CallbackArg |
---|
RegionName --> String |
NumberOfKeys --> int |
CallbackArg –-> Serialized bytes of Geode object type |
PutAllResponse –-> Success |
---|
Success --> Boolean |
MetaData
The purpose of metadata to pass defined key value pair with request and response.
Examples
PutRequest
string regionName = "ExampleRegion"
Key = 101
Value = "New Geode Client Server Protocol"
CallbackArg = Null
MessageHeader (Size PartialMessage CorrelationId Request) | Request (RequestType apiVersion hasMetaData [MetaData] RequestAPI ) | RequestAPI (PutRequest (RegionName KeyObject CallbackArg ValueObject)) | ValueObject (Serializedbytes( SerializedBytesHeader PartialSerializedBytes)) SerializedBytesHeader( Size isPartialBytes) PartialSerializedBytes |
---|---|---|---|
Size = Size of Request (66) 0x00 0x00 0x00 0x42 | RequestType (PutRequestType = 3) 0x00 0x03 | RegionName(type:String, value:"ExampleRegion" ) len = 0x00 0x0d Utf Encoding = 0x45 0x78 0x61 0x6d 0x70 0x6c 0x65 0x52 0x65 0x67 0x69 0x6f 0x6e | Size = (number of serialized bytes = 35) 0x00 0x00 0x00 0x23 |
PartialMessage = (type = Boolean, value = false) 0x00 | apiVersion (1) 0x00 0x01 | KeyObject (Serialzied using geode types, value = 101) Geode Int type = 0x39 Value = 0x00 0x00 0x00 0x65 | isPartialBytes = (It contains all serialized bytes, type = boolean) 0x00 |
CorrelationId = 1 0x00 0x00 0x00 0x01 | hasMetaData (false) 0x00 | CallbackArg (Serialzied using geode types, value = null) Value = 0x29 | PartialSerializedBytes (Serialized as Geode String type, value = "New Geode Client Server Protocol") Geode String type = 0x57 Serialized Encoded length = 0x00 0x20 Encoded String = 0x4e 0x65 0x77 0x20 0x47 0x65 0x6f 0x64 0x65 0x20 0x43 0x6c 0x69 0x65 0x6e 0x74 0x20 0x53 0x65 0x72 0x76 0x65 0x72 0x20 0x50 0x72 0x6f 0x74 0x6f 0x63 0x6f 0x6c |
PutResponse
MessageHeader(Size PartialMessage CorrelationId Response) | Response (ResponseTypeId hasMetaData [MetaData] APIResponse | APIResponse(PutResponse (Success)) | |
---|---|---|---|
Size = Size of Request (4) 0x00 0x00 0x00 0x04 | ResponseTypeId (FullResponse, type=int16, value =1) 0x00 0x01 | Success(type=boolean, value = true) 0x01 | |
PartialMessage = (type = Boolean, value = false) 0x00 | hasMetaData (false) 0x00 | ||
CorrelationId = 1 0x00 0x00 0x00 0x01 |