ID	IEP-76
Author	Pavel Tupitsyn
Sponsor	Pavel Tupitsyn
Created	23 Jun 2021
Status	DRAFT

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. Main differences are:

MsgPack as underlying binary format (IEP-75 Thin Client MsgPack Serialization)
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 needed.
Netty is used on the server for network IO.

Data Format

MsgPack is used for data serialization.

Data Types Mapping

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).

Integer data types, varint encoding

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.

Message format

All messages, request and response, except handshake, start with int message length (excluding the length itself).

Any MsgPack int type can be used (see varint above). Empty message will be single 0 byte.
Maximum message length is 2147483647 (Integer.MAX_VALUE and maximum byte array length in Java)

int	Length of Payload
...	Payload

Handshake

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
boolean	Success flag
string	When success flag is false: Error message
bin	When success flag is true: Server features (bitmask)
map (string → any)	When success flag is true: Extensions (auth, attributes, etc). Client can skip unknown extension data (when server is newer).

Client Operations

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

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.

OP_CREATE_TABLE = 1

TODO: Schema, settings - extendable (map-based)

OP_GET_TABLE_NAMES = 2

TODO:

OP_GET_TABLE_INFO = 3

TODO

OP_DROP_TABLE = 4

TODO: by name

Risks and Assumptions