THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
The high-level goals for the protocol are defined here.
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 Error codes indicate the issue with the invocation of API at the server. We have defined the error code for various issues here. The response format will contain the 2-bytes(int16) for error codes. It will be marked as ErrorCode in the response format.
Format grammar
The format is described using Extended Backus–Naur form grammar.
...
(int16) for error codes. It will be marked as ErrorCode in the response format.
ProtocolType
The protocol descriptions use the following types. These may be mapped to a pluggable serialization description language but their native serialization is described here. The native serialization uses network byte order ("big-endian").
...
| 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. |
...
| byte[] | Variable
| {1,2} | 0x00 0x02 (length) 0x01 0x02 |
| bytes | Variable: series of bytes containing a serialized value. |
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 => MessageHeader (Request | Response ) |
|---|
| MessageHeader => defined below |
| Request => defined below |
| Response => defined below |
...
| MessageHeader => Size isPartialMessage CorrelationId | Description |
|---|---|
| Size => fixedSize = 4 bytes, type = int32 | Size of request or response |
| isPartialMessage => fixedSize = 1 byte, type = boolean | |
| CorrelationId => fixedSize = 4 bytes, type = int32 |
Request
...
The request would contain the fixed size request header, optional metadata and request api parameters.
| Request => RequestHeader [MetaData] RequestAPI |
|---|
| RequestHeader => defined below |
| MetaData => optional |
RequestAPI => (PutRequest | GetRequest | PutAllRequest | GetAllRequest |ServerConfigRequest | ClientConfigRequest | AuthRequest) |
RequestHeader
The request header contains the ApiId, ApiVersion, and hasMetaData flag to indicate whether the request contains some metadata.
| 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 |
Response
...
The response would contain the fixed size response header, optional metadata and return values.
...
| Response => ResponseHeader [MetaData] APIResponse |
|---|
| ResponseHeader => defined below |
| MetaData => Optional |
| APIResponse => (PutResponse | GetResponse | PutAllResponse | GetAllResponse | ServerConfigResposne | ClientConfigResponse | AuthResponse | ErrorResponse) |
ResponseHeader
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.
...
| ValueHeader => Size hasPartialBytes | Description |
|---|---|
| Size => fixedSize = 4 bytes, type = int32 | Number of serialized bytes |
| hasPartialBytes => fixedSize = 1 byte, type = boolean | Whether this contains partial bytes of value |
APIS
...
Metadata
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 { MetadataKeyId MetadataKeyValue} | |
|---|---|
| NumberOfMetadata=> fixedSize = 2 bytes, type = int16 | |
| MetadataKeyId => fixedSize = 2 bytes, type = int16 | |
| MetadataKeyValue => variable, Value as defined in table below |
...