======================
nmdb_ Network Protocol
======================
:Author: Alberto Bertogli (albertito@blitiri.com.ar)
**NOTE:** All integers are in network byte order.
The nmdb network protocol relies on a message passing underlying transport
protocol. It can be used on top of TIPC, UDP, TCP (with a thin messaging
layer) or SCTP. This document describes the protocol in a
transport-independent way, assuming the transport protocol can send and
receive messages reliably and preserve message boundaries. No ordering
guarantee is required for the request-reply part of the protocol, but it is
highly desirable to avoid reordering of requests.
Requests
========
All requests begin with a common header, and then have a request-specific
payload. They look like this::
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Ver | Request ID |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Request code | Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
: Payload :
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Where the fields are:
Ver (4 bits)
Version of the protocol. Must be 1.
Request ID (28 bits)
A number identifying the request. A request is uniquely represented by the
*(ID, sender)* pair, where *sender* is the sender host information. IDs can
be reused once a matching response has arrived to the sender.
Request code (16 bits)
The code of the operation to be performed. They're defined in the server
source code.
Flags (16 bits)
Flags that affect the request code.
Payload (variable, can be absent)
The payload is specific to the request code. Some requests carry no
associated payload.
Request codes
-------------
The following table was taken from the server source, which should be the
authoritative source of information. The codes are included here just for
completeness.
============== ======
Name Code
============== ======
REQ_GET 0x101
REQ_SET 0x102
REQ_DEL 0x103
REQ_CAS 0x104
REQ_INCR 0x105
REQ_STATS 0x106
REQ_FIRSTKEY 0x107
REQ_NEXTKEY 0x108
============== ======
Flags
-----
Note that not all requests accept all the flags. Flags that are not relevant
for a given request will be ignored.
================= ====== =============================================
Name Code Relevant to
================= ====== =============================================
FLAGS_CACHE_ONLY 1 REQ_GET, REQ_SET, REQ_DEL, REQ_CAS, REQ_INCR
FLAGS_SYNC 2 REQ_SET, REQ_DEL
================= ====== =============================================
Request payload formats
-----------------------
REQ_GET
These requests have the same payload format, and only differ on the code.
First the key size (32 bits), and then the key.
REQ_SET
Like the previous requests, they share the payload format. First the key
size (32 bits), then the value size (32 bits), then the key, and then the
value.
REQ_DEL
You guessed it, they share the payload format too: first the key size (32
bits), and then the key.
REQ_CAS
First the key size, then the old value size, then the new value size, and
then the key, the old value and the new value.
REQ_INCR
First the key size (32 bits), then the key, and then the increment as a
signed network byte order 64 bit integer.
REQ_FIRSTKEY
No payload.
REQ_NEXTKEY
The key size and then the key.
Replies
=======
Replies begin with the ID they correspond to, then a reply code, and then a
reply-specific payload. They look like this::
+------------+------------------+--- - - - ---+
| Request ID | Reply code | Payload |
+------------+------------------+--- - - - ---+
Where the fields are:
Request ID
The request ID this reply corresponds to. 32 bits.
Reply code
The code of the reply. They're defined in the server
Payload
The payload is specific to the reply code. Some replies can carry no
associated payload.
All integers are in network byte ordering.
Reply codes
-----------
The following table was taken from the server source, which should be the
authoritative source of information. The codes are included here just for
completeness.
================ ======
Name Code
================ ======
REP_ERR 0x800
REP_CACHE_HIT 0x801
REP_CACHE_MISS 0x802
REP_OK 0x803
REP_NOTIN 0x804
REP_NOMATCH 0x805
================ ======
Reply payload formats
---------------------
REP_ERR
The payload is a 32-bit error code, according to the table below.
REP_CACHE_MISS, REP_NOTIN and REP_NOMATCH
These replies have no payload.
REP_CACHE_HIT
The first 32 bits are the value size, then the value.
REP_OK
Depending on the request, this reply does or doesn't have an associated
value. For *REQ_SET**, *REQ_DEL** and *REQ_CAS** there is no payload. But
for *REQ_GET* and *REQ_NEXTKEY* the first 32 bits are the value size, and
then the value; and for *REQ_INCR* the first 32 bits are the payload size,
and then the post-increment value as a signed 64-bit integer in network byte
order.
Reply error codes
-----------------
============ ====== =========================
Name Code Description
============ ====== =========================
ERR_VER 0x101 Version mismatch
ERR_SEND 0x102 Error sending data
ERR_BROKEN 0x103 Broken request
ERR_UNKREQ 0x104 Unknown request
ERR_MEM 0x105 Memory allocation error
ERR_DB 0x106 Database error
ERR_RO 0x107 Server in read-only mode
============ ====== =========================
.. _nmdb: http://blitiri.com.ar/p/nmdb/