This is the ThingsDB documentation for version v0, click here for the latest version!
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
Length of the data, stored as Unsigned, 32-bit, Little Endian. The header size is not included in the length.
The Id can be used as an identifier of your package. When ThingsDB send a response on a request, it will use the same Id so this allows you to map a response to a request. This is useful if you want to send multiple requests in parallel. It needs to be stored as 16-bit, Little Endian.
Package type is used to describe what kind of package is transmitted.
||32||Ping, useful as keep-alive.|
||35||Watch for changes on specific things.|
||36||Stop watching for changes on specific things.|
||37||Run a procedure, see procedures for more info.|
Inverse of the type:
type ^ 0xff. This is used as a check-bit.
Data serialized using MessagePack.
┌───────────┬───────────┬───────────┬───────────┬───────────┐ │ LEN (4) │ Id (2) │ TYPE (1) │ CHK (1) │ DATA (..) │ └───────────┴───────────┴───────────┴───────────┴───────────┘
ThingsDB can respond with one of the following response type:
||16||Success response to
||17||Success response to
||18||Success response to
||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:
Serializing the above using MessagePack results in the following
Now we create the header. For this example we just use Id 0:
So our total package will be:
Some more examples: