binary protocol v3

[thibaultcha]

• update constants' version_codes
• stream id is now 2 bytes long (a [short] value), so the header is now 1 byte longer (9 bytes total).
• BATCH messages now have <flags> (like QUERY and EXECUTE) and a corresponding optional <serial_consistency> parameters (see Section 4.1.7).
• User Defined Types and tuple types have been added to ResultSet metadata (see 4.2.5.2) and a new section on the serialization format of UDT and tuple values has been added to the documentation (Section 7).
  • UDT
  • Tuple
• The serialization format for collection has changed (both the collection size and the length of each argument is now 4 bytes long). See Section 6.
• The format of "Schema_change" results (Section 4.2.5.5) and "SCHEMA_CHANGE" events (Section 4.2.6) has been modified, and now includes changes related to user types.

---

• QUERY, EXECUTE and BATCH messages can now optionally provide the default timestamp for the query. As this feature is optionally enabled by clients, implementing it is at the discretion of the client.
• QUERY, EXECUTE and BATCH messages can now optionally provide the names for the values of the query. As this feature is optionally enabled by clients, implementing it is at the discretion of the client.

[jbochi]

That's awesome. Feel free to send a pull request now. We can work on the optional arguments in a different issue.

[thibaultcha]

I'm just realizing we don't support skip_metadata and serial_consitency flags. The specs don't say they are optional so I was implementing them.

In regards of the v3: I wanted to support both v2 and v3 (and we still can) but I was struggling with the current structure and I wasn't sure how. I just came up with an idea: we could have a Protocol class as an attribute of a session, and a subclass for v2 and v3 implementations, overriding what needs to be.

In any case I think a refactor of the structure should be done to have a cleaner code base. I would like to have such a structure (I'm just making this up, haven't given it much thought yet):

cassandra
├── cassandra.lua
├── utils.lua -- we kinda need this for methods such as `shuffle`, `split`, bit operations, big endian etc...
├── constants.lua -- those could have more than just the values. For ex it could specify how the `paging_size` flag should be encoded (as an `[int]`), and thus reduce the quantity of code needed everywhere it's used (just an example)
├── marshallers -- only deal with converting lua types to cql types
│   ├── marshall.lua
│   └── unmarshall.lua
└── protocol -- those could be classes for v2, v3...
    ├── reader.lua
    └── writer.lua

We could breakup the project into smaller, more maintainable and documentable files.

[thibaultcha]

I am not sure if supporting the v2 is valuable though. iirc, Cassandra 1.x needs the binary v1, and 2.x (or is it 2.1?) can have v2 or v3 (really not sure about that, need to check). If this is true, we could just drop v2 all along.

[thibaultcha]

Types could also be classes. That way it gets easy and elegant to serialize/deserialize them, do bit operations on them etc. A simple example:

local flags_repr = 0
flags_repr = setbit(flags_repr, constants.query_flags.VALUES)

becomes

local flags = Byte.new() -- a [byte]
flags:setbit(constants.query_flags.VALUES)