Skip to main content
Version: 0.8.0

Networking

The Skyhash protocol uses a very simple data exchange model.

This is for version 0.8.0!

This information on networking only corresponds to Skytable 0.8.0 (Octave). If you're using a different version consider looking for the appropriate document.

We use three connection stages:

  • Client handshake: The client sends a handshake packet
    • The handshake contains all necessary information to successfully establish a connection
    • The structure of the client handshake depends on the authentication plugin in use (since authentication data has to be exchanged before the connection can be established)
    • For the pwd plugin the client handshake looks like this: 
      H00000<username length>\n<password length>\n<username><password>
  • Server handshake:
    • Accepted: If the server accepts the handshake information then it will respond with: H000
    • Rejected: If the server rejects the handshake information then it will respond with H01<8-bit error code>. You can find out what happened using the error code index
  • Data exchange: This is where the client and server exchange data

How to communicate:

  • Open a TCP connection to the server
  • Do the handshake (as described above) and handle any errors
  • Encode queries as described below

Client​

Data types​

The client side needs to send encoded data types to the server (in the form of parameters) so that the server can process them.

Types:

  • Null: Encoded as 0
  • Bool: Encoded as 1<0 or 1>\n
  • Unsigned integer: A 64-bit unsigned integer. Encoded as 2<integer>\n
  • Signed integer: A 64-bit unsigned integer. Encoded as 3<integer>\n
  • Float: A 64-bit (double precision) floating point value. Encoded as 4<float>\n
  • Binary: A binary blob. Encoded as 5<size>\n<payload>
  • String: An UTF-8 string. Encoded as 6<size>\n<payload>

Queries​

A query has three sections:

  • The metaframe:
    • Contains metadata about the query
    • Encoded as: <total packet size>\n (total size of the other two sections)
  • The dataframe header: Encoded as <query body size>\n
  • The dataframe:
    • First part contains the query body, encoded as: <query body> (the query body is simply appended here)
    • Second part contains the payload body with all the parameters, encoded as: <parameter>\n ... (repeat for all parameters)

Server​

Data types​

The server will respond with different data types, depending on the context. These include:

  • Null: Encoded as 0
  • Bool: encoded as 1<0 or 1>\n
  • Unsigned integers:
    • First byte: 2 -> 8-bit, 3 -> 16-bit, 4 -> 32-bit, 5 -> 64-bit
    • Payload: <integer>\n
  • Signed integers:
    • First byte: 6 -> 8-bit, 7 -> 16-bit, 8 -> 32-bit, 9 -> 64-bit
    • Payload: <integer>\n
  • Simple collections:
    • First byte: 10 -> binary, 11 -> string
    • Payload: <size>\n<body>
  • Complex collections:
    • First byte: 11 -> list
    • Payload: <size>\n<other server data types>

Responses​

The server can respond with any of the data types above, or it can respond with a special response type like these:

  • Error: Encoded as 0x10<16-bit error code>
  • Row: The server has returned a row. Encoded as 0x11<column cnt>\n<data type>
  • Empty: This indicates that the query ran successfully but nothing appropriate can be returned (like HTTP's 200 status). Encoded as 0x12
  • Multirow: The server has returned multiple rows. Encoded as 0x13<row count>\n<rows ...>