Motivation

Thin client protocol will be the primary way to interact with Ignite 3.0 from code.

Description

Adapt Ignite 2.x protocol for Ignite 3.0. The main differences are:

• MsgPack as underlying binary format (IEP-75: Thin Client MsgPack Serialization)
• A different set of data types (IEP-54: Schema-first Approach)
• More flexible and extensible handshake with magic header string

TCP Socket

• Every Ignite node listens on a TCP port. Thin client implementations connect to any node in the cluster (possibly multiple nodes) through a 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 are needed.
• Netty is used on the server for network IO.

Data Format

MsgPack is used for data serialization (uses big-endian byte order).

Data Types Mapping

Ignite data types defined in IEP-54 map to MsgPack data types the following way:

"Extension X" is a MsgPack extension type (up to 128 extension types are allowed).

Integer data types, varint encoding

MsgPack provides multiple data types for integer values. When encoding a value, the 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.

Message format

All messages, requests and responses, except handshake, start with a 4-byte message length (excluding the length itself).

• Message length is not encoded with MsgPack, 4 bytes contain raw int32 value in little-endian byte order.
• Maximum message length is 2147483647 (Integer.MAX_VALUE and maximum byte array length in Java)

Tuple serialization

• This IEP covers Table API - Ignite#tables(), which is the only public API available at the moment.
• Table API operates on tuples (Tuple and TupleBuilder interfaces).
• Tuple is a set of key-value pairs - column name and value.
• Values can be of basic types described above and in IEP-54, according to the table schema. 
• Table schema can evolve over time, columns get added and removed. Ignite tracks the evolution with incrementing integer schema version.
• All schema versions are stored by Ignite. It is possible to retrieve the set of columns for any version.

A simple way to serialize a tuple would be to write a map (String → ...) from column name to value.

However, thanks to schema-first approach, we can avoid sending column names with the values (serializing strings is expensive). Instead, we can write an integer schema version, and then values for every column in that schema.

values "type" below indicates a raw sequence of values (not a MsgPack array). Since we know the number of columns in the schema, we don't need an array header.

To read or write a value for a column, we get the column type from the schema and use corresponding MsgPack data type according to Data Types Mapping above.

for (Column col : tuple) {
	switch (col.type().spec()) {
    	case BYTE:
        	packer.packByte(tuple.byteValue(col.name()));
	        break;
	    case SHORT:
...

Key tuples

Key tuples are tuples with key columns only. Key columns always come first in the schema. So if there are 2 key columns, first two values of the tuple is the key.

Null vs NoValue

Ignite Table API handles "column set to null" (1) and "column not set" (2) differently.

• Non-nullable column does not allow (1), but allows (2) as long as there is a default value.
• Nullable column will be set to null in (1) and to default value in (2).

NoValue custom protocol type reflects this distinction.

Handshake

Client Operations

 Upon successful handshake, client can start performing operations by sending a request with specific op code. Each operation has its own request and response format, with a common header.

Request or response without operation-specific data is called basic request or basic response below.

Notifications

Clients should expect notification messages at any moment after the successful handshake.

Operation codes and request ids are omitted everywhere below for brevity.

TABLES_GET = 3

Basic request.

Note: tables can only be created/deleted with SQL, there are no TABLE_CREATE or TABLE_DROP operations.

TABLE_GET = 4

SCHEMAS_GET = 5

TUPLE_UPSERT = 10

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.
• If the latest schema still does not match, and live schema is enabled, use TUPLE_UPSERT_SCHEMALESS

TUPLE_GET = 12

Clients should retrieve schemas with SCHEMAS_GET and cache them per table.

TUPLE_UPSERT_ALL = 13

Basic response.

TUPLE_GET_ALL = 15

TUPLE_GET_AND_UPSERT = 16

TUPLE_INSERT = 18

TUPLE_INSERT_ALL = 20

TUPLE_REPLACE = 22

TUPLE_REPLACE_EXACT = 24

TUPLE_GET_AND_REPLACE = 26

TUPLE_DELETE = 28

TUPLE_DELETE_ALL = 29

TUPLE_DELETE_EXACT = 30

TUPLE_DELETE_ALL_EXACT = 31

TUPLE_GET_AND_DELETE = 32

TUPLE_CONTAINS_KEY = 33

TX_BEGIN = 43

TX_COMMIT = 44

Basic response

TX_ROLLBACK = 45

Basic response

Risks and Assumptions

• This IEP covers handshake and Tables API, which is the only public API available at the moment.
• Invoke API is out of scope: code deployment and processor serialization should be designed separately.

Discussion Links

• https://lists.apache.org/thread.html/r719c076b9d2423c99f471075c0c3bae7642d693331bc1767b4d87e32%40%3Cdev.ignite.apache.org%3E

Reference Links

• PoC: https://github.com/apache/ignite-3/pull/191
• IEP-75: Thin Client MsgPack Serialization
• IEP-9 Thin Client Protocol (Ignite 2.x protocol)

Tickets