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
Message(Framing)
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:
...
The ApiId recognizes the API, a client wants to invoke on the server. The request format will contain the 2-byte(int16) for Api API id. It will be marked as ApiId in the request format.
...
API version will be associated with the request apiAPI. 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.
...
| 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 |
| int64 | Fixed = 8 | 1 | 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x01 |
| String(modified UTF 8 ) | Variable
| "Geode" | 0x00 0x05 (length) 0x47 0x65 0x6f 0x64 0x65 (utf encoding) |
| byte[] | Variable
| {1,2} | 0x00 0x02 (length) 0x01 0x02 |
| bytes | Variable: series of bytes containing a serialized value. |
...
| Anchor |
|---|
...
|
...
|
...
...
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.
- It will be used for correlating the request to its response.
| MessageHeader => Size CorrelationId isPartialMessage CorrelationIdhasMetaData | Description | ||
|---|---|---|---|
| Size => fixedSize = 4 bytes, type = int32 | Size of request or response | ||
| CorrelationId => fixedSize = 4 bytes, type = int32 | The correlationID used to track a request/response | ||
| isPartialMessage => fixedSize = 1 byte, type = boolean | CorrelationId | Is this a partial message | |
| hasMetaData => fixedSize = | 4 bytes1 byte, type = | int32boolean | Does the message have meta data associated with it |
| Anchor | ||||
|---|---|---|---|---|
|
Request
The request would contain the fixed size request header, optional metadata and request api parameters.
...
| RequestHeader => ApiId apiVersion hasMetaData | Description | |
|---|---|---|
| ApiId => fixedSize = 2 bytes, type = int16 | ||
| apiVersion => fixedSize = 1 byte, type = int8 | hasMetaData => fixedSize = 1 byte, type = boolean | if there is any meta data associated with this request
| Anchor | ||||
|---|---|---|---|---|
|
Response
The response would contain the fixed size response header, optional metadata and return values.
...
| 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 | ||
| hasMetaData => fixedSize = 1 byte, type = boolean | if there is any meta data associated with this request |
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.
...