xapian-core/net/replication_protocol.rst

   1 .. Copyright (C) 2008 Lemur Consulting Ltd
   2 .. Copyright (C) 2010,2014 Olly Betts
   3
   4 ====================================
   5 Xapian Database Replication Protocol
   6 ====================================
   7
   8 .. contents:: Table of contents
   9
  10 This document contains details of the implementation of the replication
  11 protocol, version 1.  For details of how and why to use the replication
  12 protocol, see the separate `Replication Users Guide <replication.html>`_
  13 document.
  14
  15 Protocol description
  16 ====================
  17
  18 The protocol used to transfer the updates is based on the RemoteConnection
  19 system (also used for remote Xapian databases).  This provides a "message"
  20 layer abstraction for the connections; so the communication is based on a set
  21 of messages, each with a type, and some associated data.
  22
  23 Where the following description refers to "packed" strings or integers, this
  24 means packed according to the same methods for packing these into databases.
  25
  26 Client messages
  27 ---------------
  28
  29 The client sends a single message type to the server: this is a message of type
  30 'R', and includes the name of a database to be replicated and a revision string
  31 for that database.  This message is sent whenever the client wants to receive
  32 updates for a database.
  33
  34 Server messages
  35 ---------------
  36
  37 The server can send a variety of messages.  The message types are currently
  38 defined in an enum in common/replicationprotocol.h (in which each type is
  39 preceded by ``REPL_REPLY_``):
  40
  41  - END_OF_CHANGES: this indicates that no further changes are needed, and ends
  42    the response to the original request.  It contains no data.
  43
  44  - FAIL: this indicates that a consistent set of changes couldn't be sent.  It
  45    may occur because the database is being changed too quickly at the senders
  46    end, or for other reasons.  It ends the response to the original request,
  47    and may occur when any other messages are expected.
  48
  49  - DB_HEADER: this indicates that an entire database copy is about to be sent.
  50    It contains a string representing the UUID of the database which is about to
  51    be sent, followed by a (packed) unsigned integer, representing the revision
  52    number of the copy which is about to be sent.
  53
  54  - DB_FILENAME: this contains the name of the next file to be sent in a DB copy
  55    operation.
  56
  57  - DB_FILEDATA: this contains the contents of a file in a DB copy operation.
  58    The contents of the message are the details of the file.
  59
  60  - DB_FOOTER: this indicates the end of a DB copy operation.  The contents of
  61    this message are a single (packed) unsigned integer, which represents a
  62    revision number.  The newly copied database is not safe to make live until
  63    changesets up to the specified revision have been applied.
  64
  65  - CHANGESET: this indicates that a changeset file (see below) is being sent.
  66
  67 Changeset files
  68 ===============
  69
  70 Changes are represented by changeset files.  When changeset logging is enabled
  71 for a database, just before each commit a changeset file is created in
  72 the database directory.  This file contains a record of the changes made,
  73 currently in the following format (but note that this format may change in
  74 the future):
  75
  76  - 12 bytes holding the string "FlintChanges", "ChertChanges" or "GlassChanges"
  77    (used to check that a file is a changeset file).
  78
  79  - The format of the changeset (as a variable length unsigned integer).
  80
  81  - The revision number of the database before the changes were applied (as a
  82    variable length unsigned integer).
  83
  84  - The revision number of the database after the changes were applied (as a
  85    variable length unsigned integer).
  86
  87  - A byte:
  88
  89    - 0 if the changes can safely be applied to a live database
  90
  91    - 1 if the changes cannot be applied while searching is in progress.  (This
  92      will be set if the database was modified in "DANGEROUS" mode).
  93
  94  - A series of items:
  95
  96    - A byte: 0 if there are no more items in the changeset, 1 if the next item
  97      is a base file, 2 if the next item is a list of blocks.
  98
  99    - A (packed) string, holding a table name.
 100
 101    - If a base file:
 102
 103      - The letter of the base file (currently 'A' or 'B').
 104
 105      - The length of the file (as a variable length unsigned integer).
 106
 107      - The contents of the base file.
 108
 109    - If a list of blocks:
 110
 111      - The blocksize in use (for glass, divided by GLASS_MIN_BLOCKSIZE).
 112
 113      - A list of items:
 114
 115        - A variable length unsigned integer holding 0 if the list is at an end,
 116          or holding (block number + 1) otherwise.
 117
 118        - The contents of the block.
 119
 120  - A revision number that the database must be upgraded to, with more
 121    changesets, before it is safe to be made live.  This will normally be the
 122    revision number of the database after the changes were applied, but if the
 123    changeset was created by copying parts of the database without a read lock,
 124    and modifications were made to the database while the copy was in progress,
 125    parts of the copy may contain later revisions than intended - in this
 126    situation further changesets will be needed to ensure that these parts of
 127    the database are fully integrated.