Native protocol layer¶

Messages¶

Every protocol message is identified by an opcode, and has a corresponding Message subclass.

A Frame wraps a message to add metadata, such as the protocol version and stream id.

+-------+ contains +------------+
| Frame +--------->+ Message    +
+-------+          +------------+
                   | int opcode |
                   +--+---------+
                      |
                      |    +---------+
                      +----+ Query   |
                      |    +---------+
                      |
                      |    +---------+
                      +----+ Execute |
                      |    +---------+
                      |
                      |    +---------+
                      +----+ Rows    |
                           +---------+
                           
                           etc.

All value classes are immutable, but for efficiency they don’t make defensive copies of their fields. If these fields are mutable (for example collections), they shouldn’t be modified after creating a message instance.

The code makes very few assumptions about how the messages will be used. Data is often represented in the most simple way. For example, ProtocolConstants uses simple integer constants to represent protocol codes (enums wouldn’t work at that level, because we need to add new codes in the DSE driver); the driver generally rewraps them in more type-safe structures before exposing them to higher-level layers.

Encoding/decoding¶

For every message, there is a corresponding Message.Codec for encoding and decoding. A FrameCodec relies on a set of message codecs, for one or more protocol versions. Given an incoming frame, it looks up the right message codec to use, based on the protocol version and opcode. Optionally, it compresses frame bodies with a Compressor.

+-----------------+                +-------------------+
| FrameCodec[B]   +----------------+ PrimitiveCodec[B] |
+-----------------+                +-------------------+
| B encode(Frame) |
| Frame decode(B) +-------+        +---------------+
+------+----------+       +--------+ Compressor[B] |
       |                           +---------------+
       |
       |                           +-------------------+
       +---------------------------+ Message.Codec     |
           1 codec per opcode      +-------------------+
           and protocol version    | B encode(Message) |
                                   | Message decode(B) |
                                   +-------------------+

Most of the time, you’ll want to use the full set of message codecs for a given protocol version. CodecGroup provides a convenient way to register multiple codecs at once. The project provides default implementations for all supported protocol version, both for clients like the driver (e.g. encode QUERY, decode RESULT), or servers like Simulacron (decode QUERY encode RESULT).

+-------------+
|  CodecGroup |
+------+------+
       |
       |    +------------------------+
       +----+ ProtocolV3ClientCodecs |
       |    +------------------------+
       |
       |    +------------------------+
       +----+ ProtocolV3ServerCodecs |
       |    +------------------------+
       |
       |    +------------------------+
       +----+ ProtocolV4ClientCodecs |
       |    +------------------------+
       |
       |    +------------------------+
       +----+ ProtocolV4ClientCodecs |
       |    +------------------------+
       |
       |    +------------------------+
       +----+ ProtocolV5ClientCodecs |
       |    +------------------------+
       |
       |    +------------------------+
       +----+ ProtocolV5ClientCodecs |
            +------------------------+

The native protocol layer is agnostic to the actual binary representation. In the driver, this happens to be a Netty ByteBuf, but the encoding logic doesn’t need to be aware of that. This is expressed by the type parameter B in FrameCodec<B>. PrimitiveCodec<B> abstracts the basic primitives to work with a B: how to create an instance, read and write data to it, etc.

public interface PrimitiveCodec<B> {
  B allocate(int size);
  int readInt(B source);
  void writeInt(int i, B dest);
  ...
}

Everything else builds upon those primitives. By just switching the PrimitiveCodec implementation, the whole protocol layer could be reused with a different type, such as byte[].

In summary, to initialize a FrameCodec, you need:

• a PrimitiveCodec;

• a Compressor (optional);

• one or more CodecGroups.