This document describes version 22 of the protocol used by Xapian's remote backend. The protocol assumes a reliable two-way connection across which arbitrary data can be sent - this could be provided by a TCP socket for example (as it is with xapian-tcpsrv), but any such connection could be used. For example, you could used xapian-progsrv across an ssh connection, or even a custom server across a suitable serial connection.
All messages start with a single byte identifying code. A message from client
to server has a MSG_XXX
identifying code, while a message from
server to client has a REPLY_XXX
identifying code (but note that a
reply might not actually be in response to a message - REPLY_GREETING isn't -
and some messages result in multiple replies).
The identifying code is followed by the encoded length of the contents followed by the contents themselves.
Inside the contents, strings are general passed as an encoded
length followed by the string data (this is indicated below by
L<...>
) except when the string is the last or only
thing in the contents in which case we know the length because
we know the length of the contents so we don't need to explicitly
specify it.
Integers are encoded using the same encoding used for string lengths
(indicated by I<...>
below).
Floating pointing values are passed using a bit packed encoding of the sign
and exponent and a base-256 encoding of the mantissa which avoids any rounding
issues (assuming that both machines have FLT_RADIX equal to some power of 2).
This is indicated by F<...>
below.
Boolean values are passed as a single byte which is the ASCII character
value for 0
or 1
. This is indicated by
B<...>
below.
REPLY_GREETING <protocol version> I<db doc count> B<has positions?> F<db average length>
The protocol version is simply passed as a single byte ('\x09'
for version 9).
REPLY_EXCEPTION <serialised Xapian::Error object>
If an unknown exception is caught by the server, this message is sent but with empty contents.
This message can be sent at any point - the serialised exception is unserialised by the client and thrown. The server and client both abort any current sequence of messages.
MSG_ALLTERMS
REPLY_ALLTERMS I<term freq> L<term name>
...
REPLY_DONE
MSG_TERMEXISTS <term name>
REPLY_TERMEXISTS
or REPLY_TERMDOESNTEXIST
MSG_TERMFREQ <term name>
REPLY_TERMFREQ I<term freq>
MSG_COLLFREQ <term name>
REPLY_COLLFREQ I<collection freq>
MSG_DOCUMENT I<document id>
REPLY_DOCUMENT L<document data>
REPLY_VALUE I<value no> <value>
...
REPLY_DONE
MSG_DOCLENGTH I<document id>
REPLY_DOCLENGTH F<document length>
MSG_KEEPALIVE
REPLY_DONE
MSG_REOPEN
MSG_QUERY L<serialised Xapian::Query object>
I<query length> I<collapse key number> <docid order>
I<sort key number> <sort by> B<sort value forward>
<percent cutoff> F<weight cutoff>
REPLY_STATS <serialised Stats object>
MSG_GETMSET I<first> I<max items>
<serialised global Stats object>
REPLY_RESULTS <serialised Xapian::MSet object>
docid order is '0'
, '1'
or '2'
.
sort by is '0'
, '1'
, '2'
or '3'
.
MSG_TERMLIST I<document id>
REPLY_TERMLIST I<wdf> I<term freq> L<term name>
...
REPLY_DONE
MSG_SHUTDOWN
No reply is sent - this message signals that the client has ended the session.
MSG_UPDATE
REPLY_UPDATE I<db doc count> B<has positions?> F<db average length>
Only useful for a WritableDatabase
(since the same statistics
are sent when the connection is initiated in the REPLY_GREETING
and they don't change if the database can't change).
MSG_ADDDOCUMENT <serialised Xapian::Document object>
REPLY_ADDDOCUMENT I<document id>
MSG_DELETEDOCUMENT I<document id>
MSG_REPLACEDOCUMENT I<document id> <serialised Xapian::Document object>
MSG_CANCEL
MSG_CANCEL
REPLY_DONE