
                         EVENTQL BINARY PROTOCOL v1


Table of Contents

  1. Preface
  2. Overview
  3. Life of a Connection
  4. Frame header
    4.1. opcode
    4.2. flags
    4.3. length
  5. Messages


1. Preface

The EventQL binary protocol took a lot of ideas from the MySQL and Cassandra
Binary Protocols.

2. Overview

  The EventQL binary protocol is a frame based protocol. Frames are defined as:

      0         8        16        24        32
      +---------+---------+-------------------+
      |      opcode       |      flags        |
      +---------+---------+-------------------+
      |                length                 |
      +---------+---------+---------+---------+
      |                                       |
      .            ...  body ...              .
      .                                       .
      +----------------------------------------

  The protocol is big-endian (network byte order).

  Each frame contains a fixed size header (8 bytes) followed by a variable size
  body. The header is described in Section 4. The content of the body depends
  on the header opcode value (the body can in particular be empty for some
  opcode values). The list of allowed opcode is defined Section 4.4 and the
  details of each corresponding message is described Section 5.

  Note to client implementors: clients library should always assume that the
  body of a given frame may contain more data than what is described in this
  document. It will however always be safe to ignore the remaining of the frame
  body in such cases. The reason is that this may allow to sometimes extend the
  protocol with optional features without needing to change the protocol
  version.

  The EventQL protocol is generally speaking a simple request/response protocol.
  However, some requests will result in more than one response frame and some
  opcodes may be sent by the client even though another request has not completed
  yet (such as the KILL opcode). Still, the protocol does not allow "multiplexing"
  of multiple queries or independent operations onto a single connection at the
  same time.

3. Life of a Connection

  The lifetime of a connection consists of two phases: Initiation and Operation.
  A connection is always initiated by the client. To initiate a query, the client
  connects to the server and sends the initial HELLO frame. In the most simple
  case the server responds with a HELLO_ACK frame and the connection transitions
  to the operational phase. Depending on the auth method, more frames might
  be exchanged during the initiation process.

  Once the query is in operational state, the client may initiate a new
  request by sending one of these opcodes:

  After the request has completed, the client may reuse the connection to
  issue another request. At which point a request is considered complete depends
  on the specific opcode and is describe in the entry for the corresponding opcode
  in section 5.

  Note that some opcodes allow the client to send a subset of other opcodes while
  the request is still running.

4. Frame header

4.1. opcode

  A 16-bit integer that distinguishes the type of message:
    0x00    ERROR
    0x07    QUERY

  Messages are described in Section 5.

4.2. flags

  Flags applying to this frame.The flags are currently unused and ignored.

4.3. length

  A 32-bit integer representing the length of the body of the frame (note:
  currently a frame is limited to 256MB in length).

5. Messages

