xapian-core/net/remote_protocol.rst

   1 Remote Backend Protocol
   2 =======================
   3
   4 This document describes *version 40.0* of the protocol used by Xapian's
   5 remote backend. The major protocol version increased to 40 in Xapian
   6 1.5.0.
   7
   8 .. , and the minor protocol version to 1 in Xapian 1.2.4.
   9
  10 Clients and servers must support matching major protocol versions and the
  11 client's minor protocol version must be the same or lower. This means that for
  12 a minor protocol version change, you can upgrade first servers and then
  13 clients and everything should work during the upgrades.
  14
  15 The protocol assumes a reliable two-way connection across which
  16 arbitrary data can be sent - this could be provided by a TCP socket for
  17 example (as it is with xapian-tcpsrv), but any such connection could be
  18 used. For example, you could used xapian-progsrv across an ssh
  19 connection, or even a custom server across a suitable serial connection.
  20
  21 All messages start with a single byte identifying code. A message from
  22 client to server has a ``MSG_XXX`` identifying code, while a message
  23 from server to client has a ``REPLY_XXX`` identifying code (but note
  24 that a reply might not actually be in response to a message -
  25 ``REPLY_UPDATE`` is sent by the server when the connection is opened - and some
  26 messages result in multiple replies).
  27
  28 The identifying code is followed by the encoded length of the contents
  29 followed by the contents themselves.
  30
  31 Inside the contents, strings are generally passed as an encoded length
  32 followed by the string data (this is indicated below by ``L<...>``)
  33 except when the string is the last or only thing in the contents in
  34 which case we know the length because we know the length of the contents
  35 so we don't need to explicitly specify it (indicated by ``<...>`` below).
  36
  37 Integers are encoded using the same encoding used for string lengths
  38 (indicated by ``I<...>`` below).
  39
  40 Floating pointing values are passed using a bit packed encoding of the
  41 sign and exponent and a base-256 encoding of the mantissa which avoids
  42 any rounding issues (assuming that both machines have ``FLT_RADIX`` equal
  43 to some power of 2). This is indicated by ``F<...>`` below.
  44
  45 Boolean values are passed as a single byte which is the ASCII character
  46 value for ``0`` or ``1``. This is indicated by ``B<...>`` below.
  47
  48 Unsigned byte values are indicated by ``C<...>`` below.
  49
  50 Server statistics
  51 -----------------
  52
  53 -  ``REPLY_UPDATE <protocol major version> <protocol minor version> I<db doc count> I(<last docid> - <db doc count>) I<doclen lower bound> I(<doclen upper bound> - <doclen lower bound>) B<has positions?> I<db total length> <UUID>``
  54
  55 The protocol major and minor versions are passed as a single byte each
  56 (e.g. ``'\x1e\x01'`` for version 30.1). The server and client must
  57 understand the same protocol major version, and the server protocol
  58 minor version must be greater than or equal to that of the client (this
  59 means that the server understands newer MSG\_\ *XXX*, but will only send
  60 newer REPLY\_\ *YYY* in response to an appropriate client message.
  61
  62 Exception
  63 ---------
  64
  65 -  ``REPLY_EXCEPTION <serialised Xapian::Error object>``
  66
  67 If an unknown exception is caught by the server, this message is sent
  68 but with empty contents.
  69
  70 This message can be sent at any point - the serialised exception is
  71 unserialised by the client and thrown. The server and client both abort
  72 any current sequence of messages.
  73
  74 Write Access
  75 ------------
  76
  77 -  ``MSG_WRITEACCESS``
  78 -  ``REPLY_UPDATE [...]``
  79
  80 The reply message is the same format as the server's opening greeting given
  81 above.
  82
  83 If write access isn't supported or the database is locked by another writer,
  84 then an exception is thrown.
  85
  86 By default the server is also read-only, even if writing is supported.
  87 If the client wants to be able to write, it needs to request this
  88 explicitly. We do this so that the same server can support multiple
  89 read-only clients and one writing client at once, without the protocol
  90 for read-only clients requiring an extra message. The overhead of an
  91 extra message exchange for a writer is unlikely to matter as indexing is
  92 rarely so real-time critical as searching.
  93
  94 All Terms
  95 ---------
  96
  97 -  ``MSG_ALLTERMS``
  98 -  ``REPLY_ALLTERMS I<term freq> C<chars of previous term to reuse> <string to append>``
  99 -  ``...``
 100 -  ``REPLY_DONE``
 101
 102 Term Exists
 103 -----------
 104
 105 -  ``MSG_TERMEXISTS <term name>``
 106 -  ``REPLY_TERMEXISTS`` or ``REPLY_TERMDOESNTEXIST``
 107
 108 Term Frequency
 109 --------------
 110
 111 -  ``MSG_TERMFREQ <term name>``
 112 -  ``REPLY_TERMFREQ I<term freq>``
 113
 114 Collection Frequency
 115 --------------------
 116
 117 -  ``MSG_COLLFREQ <term name>``
 118 -  ``REPLY_COLLFREQ I<collection freq>``
 119
 120 Document
 121 --------
 122
 123 -  ``MSG_DOCUMENT I<document id>``
 124 -  ``REPLY_DOCDATA <document data>``
 125 -  ``REPLY_VALUE I<value no> <value>``
 126 -  ``...``
 127 -  ``REPLY_DONE``
 128
 129 Document Length
 130 ---------------
 131
 132 -  ``MSG_DOCLENGTH I<document id>``
 133 -  ``REPLY_DOCLENGTH I<document length>``
 134
 135 Keep Alive
 136 ----------
 137
 138 -  ``MSG_KEEPALIVE``
 139 -  ``REPLY_DONE``
 140
 141 Reopen
 142 ------
 143
 144 -  ``MSG_REOPEN``
 145 -  ``REPLY_DONE`` or ``REPLY_UPDATE [...]``
 146
 147 If the database was already at the latest version, ``REPLY_DONE`` is returned.
 148
 149 If it was reopened, then the reply message is the same format as the server's
 150 opening greeting given above.
 151
 152 Query
 153 -----
 154
 155 -  ``MSG_QUERY L<serialised Xapian::Query object> I<query length> I<collapse max> [I<collapse key number> (if collapse_max non-zero)] <docid order> I<sort key number> <sort by> B<sort value forward> F<time limit> <percent threshold> F<weight threshold> <serialised Xapian::Weight object> <serialised Xapian::RSet object> [L<serialised Xapian::MatchSpy object>...]``
 156 -  ``REPLY_STATS <serialised Stats object>``
 157 -  ``MSG_GETMSET I<first> I<max items> I<check at least> <serialised global Stats object>``
 158 -  ``REPLY_RESULTS L<the result of calling serialise_results() on each Xapian::MatchSpy> <serialised Xapian::MSet object>``
 159
 160 docid order is ``'0'``, ``'1'`` or ``'2'``.
 161
 162 sort by is ``'0'``, ``'1'``, ``'2'`` or ``'3'``.
 163
 164 Termlist
 165 --------
 166
 167 -  ``MSG_TERMLIST I<document id>``
 168 -  ``REPLY_DOCLENGTH I<document length>``
 169 -  ``REPLY_TERMLIST I<wdf> I<term freq> C<chars of previous term to reuse> <string to append>``
 170 -  ``...``
 171 -  ``REPLY_DONE``
 172
 173 Positionlist
 174 ------------
 175
 176 -  ``MSG_POSITIONLIST I<document id> <term name>``
 177 -  ``REPLY_POSITIONLIST I<termpos delta - 1>``
 178 -  ``...``
 179 -  ``REPLY_DONE``
 180
 181 Since positions must be strictly monotonically increasing, we encode
 182 ``(pos - lastpos - 1)`` so that small differences between large position
 183 values can still be encoded compactly. The first position is encoded as
 184 its true value.
 185
 186 Positionlist count
 187 ------------------
 188
 189 -  ``MSG_POSITIONLISTCOUNT I<document id> <term name>``
 190 -  ``REPLY_POSITIONLISTCOUNT I<count>``
 191
 192 Get the length of the positionlist without fetching the list itself.
 193
 194 Postlist
 195 --------
 196
 197 -  ``MSG_POSTLIST <term name>``
 198 -  ``REPLY_POSTLISTSTART I<termfreq> I<collfreq>``
 199 -  ``REPLY_POSTLISTITEM I<docid delta - 1> I<wdf> F<document length>``
 200 -  ``...``
 201 -  ``REPLY_DONE``
 202
 203 Since document IDs in postlists must be strictly monotonically
 204 increasing, we encode ``(docid - lastdocid - 1)`` so that small
 205 differences between large document IDs can still be encoded compactly.
 206 The first document ID is encoded as its true value - 1 (since document
 207 IDs are always > 0).
 208
 209 Shut Down
 210 ---------
 211
 212 -  ``MSG_SHUTDOWN``
 213
 214 No reply is sent - this message signals that the client has ended the
 215 session.
 216
 217 Update
 218 ------
 219
 220 -  ``MSG_UPDATE``
 221 -  ``REPLY_UPDATE I<db doc count> I<last docid> B<has positions?> I<db total length> <UUID>``
 222
 223 Only useful for a ``WritableDatabase`` (since the same statistics are
 224 sent when the connection is initiated in the ``REPLY_GREETING`` and they
 225 don't change if the database can't change).
 226
 227 Add document
 228 ------------
 229
 230 -  ``MSG_ADDDOCUMENT <serialised Xapian::Document object>``
 231 -  ``REPLY_ADDDOCUMENT I<document id>``
 232
 233 Delete document
 234 ---------------
 235
 236 -  ``MSG_DELETEDOCUMENT I<document id>``
 237 -  ``REPLY_DONE``
 238
 239 Delete document by term
 240 -----------------------
 241
 242 -  ``MSG_DELETEDOCUMENTTERM <term name>``
 243
 244 Replace document
 245 ----------------
 246
 247 -  ``MSG_REPLACEDOCUMENT I<document id> <serialised Xapian::Document object>``
 248
 249 Replace document by term
 250 ------------------------
 251
 252 -  ``MSG_REPLACEDOCUMENTTERM L<term name> <serialised Xapian::Document object>``
 253
 254 Cancel
 255 ------
 256
 257 -  ``MSG_CANCEL``
 258
 259 Commit
 260 ------
 261
 262 -  ``MSG_COMMIT``
 263 -  ``REPLY_DONE``
 264
 265 Set metadata
 266 ------------
 267
 268 -  ``MSG_SETMETADATA L<key> <value>``
 269
 270 Get metadata
 271 ------------
 272
 273 -  ``MSG_GETMETADATA <key>``
 274 -  ``REPLY_METADATA <value>``
 275
 276 Metadata keys
 277 -------------
 278
 279 -  ``MSG_METADATAKEYLIST <prefix>``
 280 -  ``REPLY_METADATAKEYLIST C<chars of previous key to reuse> <string to append>``
 281 -  ``...``
 282 -  ``REPLY_DONE``
 283
 284 Add spelling
 285 ------------
 286
 287 -  ``MSG_ADDSPELLING I<freqinc> <word>``
 288
 289 Remove spelling
 290 ---------------
 291
 292 -  ``MSG_REMOVESPELLING I<freqdec> <word>``
 293 -  ``REPLY_REMOVESPELLING I<result>``