ID | IEP-9 |
Author | Pavel Tupitsyn |
Sponsor | Pavel Tupitsyn |
Created | 20-NOV-2017 |
Status | DRAFT |
Implement thin Ignite client in any programming language / platform using a well-defined binary connectiona protocol.
"Thin" here means that we do not start an Ignite node in order to communicate with the cluster, we do not implement discovery/communication spi logic, as opposed to currently available Ignite Client Mode.
Every Ignite node listens on a TCP port. Thin client implementations connect to any node in the cluster through TCP socket and perform Ignite operations using a well-defined binary protocol.
Server-side connection parameters are defined in ClientConnectorConfiguration
class. Default port is 10800. Connector is enabled by default, no configuration changes needed.
Byte order is little-endian. Strings are UTF-8 with int prefix (no null terminator). All data types in this proposal are Java-like (byte = 8 bits, short = 2 bytes, int = 4 bytes, long = 8 bytes).
User data, such as cache keys and values, is represented in Ignite Binary Object format. Binary Object can be a primitive or a complex object.
Primitives
Primitives are represented as a type code + value:
byte | Type code |
... | Value |
Available primitives are listed below:
Name | Type Code | Size |
---|---|---|
byte | ||
All messages, request and response, including handshake, start with int
message length (excluding these first 4 bytes). E.g. empty message would be represented by 4 zero bytes.
int | Length of Payload |
... | Payload |
Length is omitted in all message descriptions below for brevity.
The first message upon connection establishment must be a handshake. Handshake ensures that client and server versions are compatible.
Request | |
byte | Handshake code, always 1 |
short | Version major |
short | Version minor |
short | Version patch |
byte | Client code, always 2 |
Response (success) | |
byte | Success flag, 1 |
Response (failure) | |
byte | Success flag, 0 |
short | Server version major |
short | Server version minor |
short | Server version patch |
string | Error message |
Upon successful handshake client can start performing operations by sending a request with specific op code. Each operation has it's own request and response format, with a common header.
Request | |
short | Operation code |
long | Request id, generated by client and returned as-is in response |
... | Operation-specific data |
Response | |
long | Request id (see above) |
... | Operation-specific data |
Operation codes and request ids are omitted everywhere below for brevity.
OP_CACHE_GET = 1
Request | |
int | Cache ID: Java-style hash code of the cache name |
byte | flags |
BinaryObject | key |
Let's see how request and response would look for a cache.get operation for integer key and value:
TODO
Similar protocols from other vendors:
See "thin client" component in JIRA