doc/io_storage_backend.txt

   1                    Elliptics network project
   2            http://www.ioremap.net/projects/elliptics
   3                Evgeniy Polyakov <zbr@ioremap.net>
   4
   5
   6           IO storage backends requirements and design
   7
   8
   9 IO storage backend is the lowest layer in the elliptics hierarchy. It is responsible
  10 for the actual data storing, thus it has to be able to process transactions and parse
  11 commands.
  12
  13 So, for the reference, a short description of the elliptics protocol.
  14 Each packet in the elliptics network contains at least two global parts:
  15 main header and one or more attributes.
  16
  17 All structure fields are sent (and stored in the backend) in little endian format
  18 and have to be converted before used via special helpers.
  19
  20 If not noted specially, all sizes have to be checked by the backend to be valid,
  21 i.e. not go outside of the provided buffers.
  22
  23
  24 Main header (struct dnet_cmd).
  25 ------------------------------
  26 This structure is used to specify transaction ID of the all inner attributes
  27 (or commands), processing flags (like ACK request for given transaction or flag,
  28 specifying that transaction reply was split into multiple packets and this is
  29 the last one (or not the last)), ID of the transaction, completion status
  30 (filled in replies only) and size of the inner data (not counting size of the
  31 main header, i.e. structure you read about).
  32
  33 Attributes or commands (struct dnet_attr).
  34 ------------------------------------------
  35 Each attribute structure represents a command to be processed in the given transaction.
  36 It may or may not contain additional data (this can be determined by checking its
  37 size field), data processing flags and command itself.
  38
  39 Only several commands are mandatory in the protocol
  40 (described in include/dnet/packet.h) and have to be understood by the backend
  41 (see examples in example/*_backend.c files), all others may or may not be supported
  42 by the backend in question. For example remote command execution may be only supported
  43 by the private implementation of the storage.
  44
  45
  46 This document describes mandatory IO commands which have to be supported by every
  47 IO backend to be able to work in the elliptics network.
  48
  49
  50 DNET_CMD_WRITE
  51 --------------
  52 This command is used to specify data to be stored on the given node.
  53 Attribute size has to match size of the data plus size of the dnet_io_attr structure,
  54 which describes IO pattern.
  55
  56 It includes data size, offset to be placed at and flags. Two other fields are ID of the
  57 main object this transaction belongs to (parent field) and ID of the transaction
  58 itself (id field). If it is a stand-alone transaction, the latter is not used.
  59
  60 Example for the data write into some file: 'parent' field will contain transformed
  61 file name, and 'id' field will contain ID of the transformed data. Size will specify
  62 number of attached bytes, offset will be set to the offset in the updated file this
  63 data was placed at.
  64
  65 Storage backend should check that attribute size matches data size specified in
  66 dnet_io_attr and size of this structure.
  67
  68 DNET_CMD_READ
  69 -------------
  70 When size specified in dnet_io_attr structure equals to zero, this means that the
  71 whole object has to be returned back to the client. It is possible that requested
  72 size and offset will be out of the object range (for example when stored object
  73 corresponds to 100-200 bytes range, but requested offset is 300) or partially cross.
  74 To rule this case out there is a helper dnet_backend_check_get_size() which will
  75 take dnet_io_attr attribute structure and size of the stored record, and return
  76 size to be read from the given record and pushed back to the client. If it is zero,
  77 nothing should be returned, likely because request is out of range.
  78
  79 Each reply (weather it is read data reply or anything else) should include
  80 at least original transaction number with the special DNET_TRANS_REPLY bit set.
  81 Its ID usually should match the request one. There are special helpers to deal with it.