doc/api/storage.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: api
   4 title: Storage in Keep
   5 ...
   6
   7 h2. Storing data
   8
   9 Storing data in Keep follows this process:
  10
  11 # The client fetches a list of keep servers (or proxies) using the @accessible@ method on "keep_services":{{site.baseurl}}/api/methods/keep_services.html
  12 # Data is split into 64 MiB blocks and the MD5 hash is computed for each block.
  13 # The client uploads each block to one or more Keep servers, based on the number of desired replicas.  The priority order is determined using rendezvous hashing, described below.
  14 # The Keep server returns a block locator (the MD5 sum of the block) and a "signed token" which the client can use as proof of knowledge for the block.
  15 # The client constructs a @manifest@ which lists the blocks by MD5 hash and how to reassemble them into the original files.
  16 # The client creates a "collection":{{site.baseurl}}/api/methods/collections.html and provides the @manifest_text@
  17 # The API server accepts the collection after validating the signed tokens (proof of knowledge) for each block.
  18
  19 h2. Fetching data
  20
  21 # The client requests a @collection@ object including @manifest_text@
  22 # The server adds "token signatures" which provide proof of access for each block
  23 # The client fetches a list of keep servers (or proxies) using the @accessible@ method on "keep_services":{{site.baseurl}}/api/methods/keep_services.html
  24 # For each data block, the client chooses the highest priority server using rendezvous hashing, described below.
  25 # The client sends the data block request to the keep server, including the token signature (proof of access).
  26 # The server provides the block data after validating the token signature for the block (if the server does not have the block, it returns a 404 and the client tries the next highest priority server)
  27
  28 h2. Keep server API
  29
  30 The Keep server is accessed via a simple HTTP REST API.
  31
  32 *GET /blocklocator+size+A@token*
  33
  34 Fetch the data block, if the token is valid.
  35
  36 *PUT /blocklocator*
  37
  38 Returns the md5 sum of the data along with the signed token.
  39
  40 h2. Rendezvous hashing
  41
  42 Each @keep_service@ resource has an assigned uuid.  To determine priority assignments of blocks to servers, for each keep service compute the MD5 sum of the string concatenation of the block locator (hex-coded hash part only) and service uuid, then sort this list in descending order.  Blocks are preferentially placed on servers at the beginning of the list.
  43
  44 h1. Keep locator format
  45
  46 <pre>
  47 locator       ::= sized-digest hint*
  48
  49 sized-digest  ::= digest size-hint
  50
  51 digest        ::= <32 lowercase hexadecimal digits>
  52
  53 size-hint     ::= "+" [0-9]+
  54
  55 hint          ::= "+" hint-type hint-content
  56
  57 hint-type     ::= [A-Z]+
  58
  59 hint-content  ::= [A-Za-z0-9@_-]*
  60
  61 sign-hint      ::= "+A" <40 lowercase hexadecimal digits> "@" sign-timestamp
  62
  63 sign-timestamp ::= <8 lowercase hexadecimal digits>
  64 </pre>
  65
  66 h2. Regular expressions to validat locator
  67
  68 <pre>
  69 /^([0-9a-f]{32})\+([0-9]+)(\+[A-Z][-A-Za-z0-9@_]*)*$/
  70 </pre>
  71
  72 h2. Valid examples
  73
  74 |@d41d8cd98f00b204e9800998ecf8427e+0@|
  75 |@d41d8cd98f00b204e9800998ecf8427e+0+Z@|
  76 |@d41d8cd98f00b204e9800998ecf8427e+0+Z+Ada39a3ee5e6b4b0d3255bfef95601890afd80709@53bed294@|
  77
  78 h2. Invalid examples
  79
  80 ||Why|
  81 |@d41d8cd98f00b204e9800998ecf8427e@|No size hint|
  82 |@d41d8cd98f00b204e9800998ecf8427e+Z+0@|Other hint before size hint|
  83 |@d41d8cd98f00b204e9800998ecf8427e+0+0@|Multiple size hints|
  84 |@d41d8cd98f00b204e9800998ecf8427e+0+z@|Hint does not start with uppercase letter|
  85 |@d41d8cd98f00b204e9800998ecf8427e+0+Zfoo*bar@|Hint contains invalid character @*@|
  86
  87 h2. Manifest v1
  88
  89 A manifest is utf-8 encoded text, consisting of zero or more newline-terminated streams.
  90
  91 Each stream consists of three or more space-delimited tokens:
  92 * The first token is a stream name, consisting of one or more path components, delimited by @"/"@.
  93 ** The first path component is always @"."@.
  94 ** No path component is empty.
  95 ** No path component is "." or "..".
  96 ** The stream name never begins or ends with @"/"@.
  97 * The second token is a data blob locator (see [[Keep locator format]]).
  98 * ...possibly followed by more data blob locators...
  99 * The first token that is not a block locator, and all subsequent tokens, are file tokens.
 100 ** A file token has three parts, delimited by @":"@: position, size, filename.
 101 ** Position and size are given in decimal, and are counted from the beginning of the first data blob.
 102 ** Filename may contain @"/"@ characters, but must not start or end with @"/"@, and must not contain @"//"@.
 103 ** Filename components (delimited by @"/"@) must not be @"."@ or @".."@.
 104
 105 A manifest contains no TAB characters, nor other ASCII whitespace characters other than the spaces or newline delimiters specified above.
 106
 107 A manifest always ends with a newline -- except the empty (zero-length) string, which is a valid manifest.
 108
 109 h2. Normalized manifest v1
 110
 111 A normalized manifest has the following additional restrictions.
 112
 113 * Streams are in alphanumeric order.
 114 * Each stream name is unique within the manifest.
 115 * Files within a stream are in alphanumeric order.
 116 * Blocks within a stream are ordered based on first appearence in the list of file segments, a given block is listed at most once in a stream.
 117 * Filename must not contain @"/"@.