THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
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.
| Usage | Notation |
|---|---|
| definition | = |
| alteration | | |
| optional | [ ... ] |
| repetition | { ... } |
Generic Message definition
Every message will adhere to the following generic message definition.
| Message => MessageHeader (Request | Response) |
|---|
| MessageHeader => defined below |
| Request => defined below |
| Response => defined below |
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
...
The request would contain the fixed size request header, optional metadata and request api API parameters.
| Request => RequestHeader [MetaData] RequestAPI |
|---|
| RequestHeader => defined below |
| MetaData => optional |
RequestAPI => (PutRequest | GetRequest | PutAllRequest | GetAllRequest |ServerConfigRequest | ClientConfigRequest | AuthRequest) |
...
The response header will have resposneType, which indicates its partial response, full response or error. A hasMetaData flag indicates whether the response contains some metadata.
| ResponseHeader => ( ResponseTypeId | ErrorCode) hasMetaData CorrelationId | Description | ||
|---|---|---|---|
| ResponseTypeId => fixedSize = 2 bytes, type = int16 | |||
| ErrorCode => fixedSize = 2 bytes, type = int16 | When there is error response will have error message(String) for it |
ErrorResponse
The server will raise the error when it failed to execute api API request from the client. The error code and message should help the client to diagnose the issue.
...
The Value is serialized bytes for the Geode region value. It contains value header and series of bytes. Using value header, we can send a big serialized object in more than one chunk.
| Value => ValueHeader value {ValueHeader value} | Description |
|---|---|
| ValueHeader => defined below | |
| value => bytes | Serialized Value Object which Geode can understand |
...
| Response MetaData Key | MetaData KeyId | MetaData Value | Description |
|---|---|---|---|
| UPDATE_PR_META_DATA | 1 fixedSize = 2 bytes, type = int16 | true fixedSize = 1 byte, 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. |
ServerConfigRequest
The purpose of ServerConfigRequest request to get a server config from the server. The client needs to send this request after connecting to the server. If the client knows server properties, then there is no need to send this request.
| ServerConfigRequest => {} |
|---|
| ServerConfigResponse =>NumberOfProperties PropertyId PropertyValue{ PropertyId PropertyValue} | |
|---|---|
| NumberOfProperties => fixedSize = 2 bytes, type = int16 | |
| Propertyid => fixedSize = 2 bytes, type = int16 | |
| PropertyValue => variable, Value as defined in table below |
| Server Response Properties | PropertyId | PropertyValue | Description |
|---|---|---|---|
| SECURITY_ENABLED | 1 | boolean | Whether security is enabled at server |
| DIFFIE_HELLMAN_KEY | 2 | byte[] | The server Diffie-Hellman key if the credential is required to encrypt. |
| MAX_TIME_BETWEEN_CLIENT_PING | 3 | int32 | If the client connection is idle for MAX_TIME_BETWEEN_CLIENT_PING seconds then the server will close that connection. |
...
The Purpose of ClientConfigRequest request to send a client config to a server. The client needs to send this request after connecting to the server. This request is optional for a client unless a server is configured for the Diffie-hellman algorithm.
| ClientConfigRequest | NumberOfProperties PropertyId PropertyValue{ PropertyId PropertyValue} |
|---|---|
| NumberOfProperties | fixedSize = 2 bytes, type = int16 |
| Propertyid | fixedSize = 2 bytes, type = int16 |
| PropertyValue | variable, Value as defined in table below |
| ClientConfigResponse ==> Success |
|---|
| Success => fixedSize = 1 byte, type = boolean |
| Client Request Properties | PropertyId | PropertyValue | Description | |
|---|---|---|---|---|
| CLIENT_ID | 1 | string | Unique id for the client; if a client doesn't send this property then the server will just create id (client-host, client-port, server-host, server-port). | optional |
| ClIENT_READ_TIMEOUT | 2 | int32 | The client will wait for ClIENT_READ_TIMEOUT for a server response. It's an optional property. | optional |
| DIFFIE_HELLMAN_KEY | 3 | byte[] | The client Diffie-Hellman key is required to encrypt the credential. | If a server is configured with it then the client should send this. |
AuthRequest
The purpose of AuthRequest to authenticate the client connection. A client can send the auth request in the following format. Before sending the auth request a client can verify the server config by sending the ServerConfigRequest. A client can send a key-value pair of credentials to authenticate itself.
Those pair needs to serialized in following way. If Diffie-Hellman encryption is enabled on the server side then need to encrypt those serialized bytes. And then send those encrypted bytes to the server. The server will decrypt those bytes and create the key-value pair.
| AuthRequest | isDiffieHellmanEnabled ( NumberOfProperties PropertyId PropertyValue{ PropertyId PropertyValue} | NumberOfEncryptedBytes EncryptedCredentials ) |
|---|---|
| isDiffieHellmanEnabled | fixedSize = 1 byte, type = boolean |
| NumberOfProperties | fixedSize = 2 bytes, type = int16 |
| Propertyid | bytes |
| PropertyValue | bytes |
| EncrptedCredentials | bytes |
| AuthResponse => Success |
|---|
| Success => fixedSize = 1 byte, type = boolean |
Examples
PutRequest
string regionName = "ExampleRegion"
...