ID	IEP-67
Author	Unknown User (ptupitsyn)
Sponsor	Unknown User (ptupitsyn)
Created	01 Feb 2021
Status

Motivation

Thin clients currently require manual binary configuration for settings like compact footer and simple/full name mapper, which is complicated and error-prone.

Description

Extend the protocol to retrieve those settings automatically on start.

Feature Flag

BINARY_CONFIGURATION bitmask feature flag lets the client know that binary configuration can be requested.

Operation

Name	Code
OP_BINARY_CONFIGURATION_GET	3004

Request
(empty)

Response
bool	compactFooter
byte	binaryNameMapperMode (0 = basic full name, 1 = basic simple name, 2 = custom)

Assumptions

An alternative approach is to include this information into the handshake, which eliminates an extra request. However, a single partition-aware client performs a handshake with multiple server nodes. Binary configuration is guaranteed to be the same on all nodes in the cluster, so the client only needs to request it once. As a result, it is more efficient to perform one extra request than extending the handshake message.
When "custom" mapper type is returned by the server, client is supposed to check that local BinaryConfiguration has a custom name mapper defined, and log/throw and error otherwise. We could return the type name of the custom mapper from the server, but it is of little use - we can't validate the client-side type name in non-Java clients, and even with Java client the class name can be different.

Compatibility Risks

Compact Footer

Java thin client has compactFooter=false by default, even though it is true by default on the server.
Python, PHP, Node.js, C++ thin clients do not support compactFooter at all.

Therefore, we must ensure that the behavior never changes from false to true on existing clusters, because some thin clients won't be able to read the data with compact footers.

As of now, only .NET thin client can use the compactFooter value from the cluster, because the default value is true, and changing from true to false is safe: anyone can read full footers.

Name Mapper

Thin client implementations must ensure that current name mapper behavior does not change. For example, if current implementation always uses full name mapper, a new version can't change this to simple name automatically using the cluster settings. This will break existing clusters.

Therefore, nameMapper value from the cluster should be only used to log a warning when a mismatch is detected.