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 for the Protobuf protocol. The Protobuf protocol will then expect a second "version" byte, that will tell it the major version of the protobuf implementation being used. This will allow the sever to ensure it can correctly parse incoming messages well enough to at least perform handshaking with the client. The major version corresponding to the structure and definitions presented in this document is 1.
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.
Usage | Notation |
---|---|
definition | = |
alteration | | |
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 = (Request | Response) | Description | |
---|---|---|
Request | type = Request | This field will contain the Request component. |
Response | type = Response
| This field will contain the Response component. |
Request
The request will contain an operation specific request structure.
Request = RequestAPI | Notes | Description |
---|---|---|
RequestAPI | type = variable | The specific Request message. Here are some examples of Request messages. PutRequest | GetRequest | PutAllRequest | GetAllRequest |ServerConfigRequest | ClientConfigRequest | AuthRequest |
Response
The response contains the response object corresponding to the request, or an error response object.
Response = APIResponse | Description | |
---|---|---|
APIResponse | type = variable | The Api specific Reponse message. Here are some examples of Response messages PutResponse | GetResponse | PutAllResponse | GetAllResponse | ServerConfigResposne | ClientConfigResponse | AuthResponse | ErrorResponse |
ErrorResponse
The server will raise an error when it failed to execute API request from the client. The error response wraps an error object detailing the failure.
ErrorResponse = Error | Description | |
---|---|---|
error | type = Error | The error message |
Error
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 = errorCode message | Description | |
---|---|---|
errorCode | type = int | Numeric code referencing the type of failure |
message | type = String | The error message |
EncodedValue
Some data being sent between the client and server, for the most part these rely on protobuf for proper serialization, except for CustomEncodedValues
EncodedValue = (one of the below) | Description |
---|---|
intResult | 32-bit signed integer |
longResult | 64-bit signed integer |
shortResult | 16-bit signed integer |
byteResult | 8-bit signed integer |
booleanResult | True or False. |
doubleResult | 64-bit floating point number. |
floatResult | 32-bit floating point number. |
binaryResult | A binary blob to be stored in the region. |
stringResult | Character string |
customEncodedValue | Data which doesn't use protobuf serialization |
CustomEncodedValue
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 | |
---|---|---|
encodingType | type = EncodingType | The encoding type of the following bytes. |
value | type = bytes | Serialized Value Object which Geode can understand |
EncodingType
Currently supported types are:
Name | Description |
---|---|
JSON | UTF-8 encoded string, containing a JSON document that will be deserialized in the same way as the REST API. |
Entry
This structure represents a pair of data corresponding to a key and associated value.
Entry = EncodedValue Error | Description | |
---|---|---|
key | type = EncodedValue | Data referencing the corresponding value |
value | type = EncodedValue | Data associated to the corresponding key |
KeyedError
Some responses may contain multiple errors keyed to different inputs. This object enables this behavior.
KeyedError = EncodedValue Error | Description | |
---|---|---|
key | type = EncodedValue | Key corresponding to this error |
error | type = Error | Details about the failure |