This is a more in depth view of the socket protocol used for communication with ThingsDB. In case you just want to use ThingsDB using one of the language bindings, then this info can be skipped. If you plan to implement your own connector, then this info might be useful to you.
This section applies to communication with ThingsDB over a socket, either by using TCP or a UNIX PIPE connection.
Once a connection is made, packages can be send to ThingsDB. Each package starts
with a 8 bytes header using little endian, followed by optional data. Before you can
send queries to ThingsDB, the connection must be authenticated. This can be done by
sending an AUTH package.
Length of the data, stored as Unsigned, 32-bit, Little Endian. The header size is not included in the length.
The ID is a unique identifier assigned to your package by ThingsDB. It allows you to easily map responses to their corresponding requests,
especially when sending multiple requests concurrently. This identifier is a 16-bit integer, ideally stored in little-endian format for consistency.
While using an unsigned integer is recommended, signed values can also be used.
Package type is used to describe what kind of package is transmitted.
| Type | Number | Description |
|---|---|---|
PING |
32 | Ping, useful as keep-alive. |
AUTH |
33 | Authorization., expects: [username, password] or a token_string. |
QUERY |
34 | Query ThingsDB. |
RUN |
37 | Run a procedure, see procedures for more info. |
JOIN |
38 | Join one or more room(s). |
LEAVE |
39 | Leave one or more room(s). |
EMIT |
40 | Emit an event to a room. |
Inverse of the type: type ^ 0xff. This is used as a check-bit.
Data serialized using MessagePack.
Package format:
┌───────────┬───────────┬───────────┬───────────┬───────────┐
│ LEN (4) │ ID (2) │ TYPE (1) │ CHK (1) │ DATA (..) │
└───────────┴───────────┴───────────┴───────────┴───────────┘
ThingsDB can respond with one of the following response type:
| Type | Number | Description |
|---|---|---|
PONG |
16 | Success response to PING (header only). |
OK |
17 | Success response to AUTH and EMIT (header only). |
DATA |
18 | Success response to QUERY, RUN, JOIN and LEAVE (with data). |
ERROR |
19 | Error response (with data). |
As an example we create an authentication package for the default admin user with password pass.
This is the package data for our authentication request:
["admin", "pass"]
Serializing the above using MessagePack results in the following 12 bytes:
\x92\xa5admin\xa4pass
Now we create the header. For this example we just use ID 0:
\x0c\x00\x00\x00\x00\x00\x21\xdeSo our total package will be:
\x0c\x00\x00\x00\x00\x00\x21\xde\x92\xa5admin\xa4pass
Some more examples: