ID | IEP-76 |
Author | |
Sponsor | |
Created |
|
Status | DRAFT |
Thin client protocol will be the primary way to interact with Ignite 3.0 from code.
Adapt Ignite 2.x protocol for Ignite 3.0. Main differences are:
ClientConnectorConfiguration
class.MsgPack is used for data serialization.
Ignite data types defined in IEP-54 map to MsgPack data types the following way:
Ignite Type | Size | MsgPack Type | Notes |
---|---|---|---|
Bitmask(n) | ⌈n/8⌉ bytes | bin8 / bin16 / bin32 | |
IntX, UintX | 1-8 bytes | fixint / intX / uintX | Integer types are interchangeable when possible. fixint (1 byte) can be passed as a value for uint64 column. |
Float | 4 bytes | float32 | |
Double | 8 bytes | float64 | |
Number([n]) | Variable | ext16 (up to 2^8 - 1 bytes) | Extension 1 |
Decimal | Variable | ext16 (up to 2^8 - 1 bytes) | Extension 2 |
UUID | 16 bytes | fixext16 | Extension 3 |
String | Variable | str | |
Date | 3 bytes | fixext4 | Extension 4 |
Time | 4 bytes | fixext4 | Extension 5 |
Datetime | 7 bytes | fixext8 | Extension 6 |
Timestamp | 8 bytes | timestamp 64 | |
Binary | Variable | bin32 (up to 2^32 - 1 bytes) |
"Extension X" is a MsgPack extension type (up to 128 extension types are allowed).
MsgPack provides multiple data types for integer values. When encoding a value, smallest data type for that value is picked automatically.
"int" is used below to denote int format family. Values such as payload size, request ID, error codes, are encoded this way - using variable number of bytes based on the value.
All messages, request and response, except handshake, start with int message length (excluding the length itself).
int | Length of Payload |
... | Payload |
Request | |
---|---|
4 bytes | Magic number 49 47 4E 49, or "IGNI". Helps identifying misconfigured SSL or other apps probing the port. |
int | Payload length |
int | Version major |
int | Version minor |
int | Version patch |
int | Client code (1 for JDBC, 2 for general-purpose client) |
bin | Features (bitmask) |
map (string → any) | Extensions (auth, attributes, etc). Server can skip unknown extension data (when client is newer). |
Response | |
---|---|
4 bytes | Magic number 49 47 4E 49, or "IGNI". Helps identifying misconfigured SSL or different server on the port. |
int | Payload length |
int | Server version major |
int | Server version minor |
int | Server version patch |
int | Error code (0 for success) |
string | Error message (when error code is not 0) |
bin | When error code is 0: Server features (bitmask) |
map (string → any) | When error code is 0: Extensions (auth, attributes, etc). Client can skip unknown extension data (when server is newer). |
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 | |
int | Operation code |
int | Request id, generated by client and returned as-is in response |
... | Operation-specific data |
Response | |
int | Type = 0 |
int | Request id |
int | Error code (0 for success) |
string | Error message (when error code is not 0) |
... | Operation-specific data |
Request or response without operation-specific data is called basic request or basic response below.
Clients should expect notification messages at any moment after the successful handshake.
Notification | |
int | Type = 1 |
int | Notification code |
... | Notification-specific data |
Operation codes and request ids are omitted everywhere below for brevity.
Request | |
---|---|
map | configuration (name, partitions, replicas, columns, indices, ...) - according to TableConfigurationSchema |
Response | |
---|---|
UUID | table ID |
Request | |
---|---|
string | table name |
Basic response.
Basic request.
Response | |
---|---|
int | N = table count |
N * (UUID + string) | pairs of tables ids and names |
Request | |
---|---|
string | table name |
Response | |
---|---|
UUID or nil | table ID or null when table with the given name does not exist |
Request | |
---|---|
UUID | table ID |
arr or nil | schema IDs, or null to get all |
Response | |
---|---|
map (int → array (array)) | Map from schema ID to columns. Column is represented by an array of values for: name, type, isKey. The array can contain extra data in future for additional properties. |
Request | |
---|---|
UUID | table ID |
int | schema ID |
arr | values for all columns in given schema (nil when value is missing for a column) |
Basic response.
Client side is supposed to match provided columns against the latest known schema. If columns don't match, request the latest schema and try again.
Request | |
---|---|
UUID | table ID |
int | schema ID |
arr | values for key columns (in schema order) |
Response | |
---|---|
int | schema id for the current tuple |
arr | tuple values in schema order |
Clients should retrieve schemas with SCHEMAS_GET and cache them per table.
Request | |
---|---|
UUID | table ID |
int | schema ID |
arr of arr | array of rows with values for key columns (in schema order) |
Response | |
---|---|
int | schema ID (for all tuples in response) |
arr of arr | array of rows with values in schema order |
TODO