github.com/slspeek/camlistore_namedsearch@v0.0.0-20140519202248-ed6f70f7721a/website/content/docs/terms (about) 1 <h1>Terminology</h1> 2 3 <p>To stay sane and communicate effectively we try hard to use 4 consistent terminology throughout the pieces of the project. Please let us know 5 if things here are confusing or lacking.</p> 6 7 <dl class='terms'> 8 9 <!-- ---------------------------------------------------------------------- --> 10 <dt id='blob'>blob</dt> 11 12 <dd>an immutable sequence of 0 or more bytes, with no extra metadata</dd> 13 14 <!-- ---------------------------------------------------------------------- --> 15 <dt id='blobref'>blobref</dt> 16 17 <dd>a reference to a blob, consisting of a cryptographic hash 18 function name and that hash function's digest of the blob's bytes, 19 in hex. Examples of valid blobrefs include: 20 <pre> 21 sha1-f1d2d2f924e986ac86fdf7b36c94bcdf32beec15 22 md5-d3b07384d113edec49eaa6238ad5ff00 23 sha256-b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c</pre> 24 Concatenating the two together with a hyphen is the common 25 representation, with both parts in all lower case. 26 </dd> 27 28 <!-- ---------------------------------------------------------------------- --> 29 <dt id='blobserver'>blob server</dt> 30 31 <dd>the simplest and lowest layer of the Camlistore servers (see: <a 32 href="/docs/arch">architecture</a>). A blob server, while 33 potentially shared between users, is <em>logically private to a 34 single user</em> and holds that user's blobs (<a 35 href="/docs/schema">whatever they may represent</a>). 36 37 <p>The protocol to speak with a blob server is simply:</p> 38 <ul> 39 40 <li><a 41 href="/gw/doc/protocol/blob-get-protocol.txt"><b>get</b></a> 42 a blob by its blobref.</li> 43 44 <li><a 45 href="/gw/doc/protocol/blob-upload-protocol.txt"><b>put</b></a> 46 a blob by its blobref.</li> 47 48 <li><a 49 href="/gw/doc/protocol/blob-enumerate-protocol.txt"><b>enumerate</b></a> 50 all your blobs, sorted by their blobrefs. Enumeration is 51 only really used by your search server and by a <em>full sync</em> 52 between your blob server mirrors.</li> 53 </ul> 54 <p>(Note: no delete operation)</p> 55 </dd> 56 57 <!-- ---------------------------------------------------------------------- --> 58 <dt id='schemablob'>schema blob</dt> 59 60 <dd>a <a href="/docs/schema">Camlistore-recognized data structure</a>, serialized as a JSON 61 object (map). A schema blob must have top-level keys 62 <code>camliVersion</code> and <code>camliType</code> and start with a open brace (<code>{</code>, byte 0x7B). You may use any valid JSON 63 serialization library to generate schema blobs. Whitespace or formatting doesn't matter, as long as the blob 64 starts with <code>{</code> and is <a href="http://json.org/">valid JSON</a> in its entirety. 65 66 <p>Example:</p> 67 <pre class='sty'> 68 { 69 "aKey": "itsValue", 70 "camliType": "foo", 71 "camliVersion": 1, 72 "somethingElse": [1, 2, 3] 73 }</pre> 74 75 </dd> 76 77 78 <!-- ---------------------------------------------------------------------- --> 79 <dt id='claim'>signed schema blob (aka "claim")</dt> 80 81 <dd>if you <a href="/docs/json-signing">sign</a> a schema blob, 82 it's now a "signed schema blob" or "claim". The terms are used pretty 83 interchangeably but generally it's called a <em>claim</em> when the target of 84 the schema blob is an object's permanode (see below). 85 86 </dd> 87 88 89 <!-- ---------------------------------------------------------------------- --> 90 <dt id='object'>object</dt> 91 92 <dd>something that's mutable. While a <em>blob</em> is a single 93 immutable thing, an <em>object</em> is a collection of claims 94 which mutate an object over time. See <a href="#permanode" class='local'>permanode</a> for fuller discussion. 95 </dd> 96 97 <!-- ---------------------------------------------------------------------- --> 98 <dt id='permanode'>permanode</dt> 99 100 <dd>since an object is mutable and Camlistore is primarily content-addressed, 101 the question arises how you could have a stable reference to something that's 102 changing. Camlistore solves this with the concept of a <em>permanode</em>. 103 Like a permalink on the web, a permanode is a stable link to a Camli object. 104 105 <p>A permanode is simply a <a href="/docs/json-signing">signed</a> 106 schema blob with no data inside that would be interesting to 107 mutate. See <a href="/gw/doc/schema/objects/permanode.txt">the 108 permanode spec</a>.</p> 109 110 <p>A permanent reference to a mutable object then is simply the blobref of 111 the permanode.</p> 112 113 <p>The signer of a permanode is its owner and search server and 114 indexer will take this into account. While multiple users may collaborate 115 on mutating an object (by all creating new, signed mutation schema blobs), 116 the owner ultimately decides the policies on how the mutations are respected.</p> 117 118 <p>Example permanode blob: (as generated with <code><a href="/cmd/camput">camput</a> --permanode</code>)</p> 119 120 <pre class='sty' style="overflow: auto;">{"camliVersion": 1, 121 "camliSigner": "sha1-c4da9d771661563a27704b91b67989e7ea1e50b8", 122 "camliType": "permanode", 123 "random": "HJ#/s#S+Q$rh:lHJ${)v" 124 ,"camliSig":"iQEcBAABAgAGBQJNQzByAAoJEGjzeDN/6vt85G4IAI9HdygAD8bgz1BnRak6fI+L1dT56MxNsHyAoJaNjYJYKvWR4mrzZonF6l/I7SlvwV4mojofHS21urL8HIGhcMN9dP7Lr9BkCB428kvBtDdazdfN/XVfALVWJOuZEmg165uwTreMOUs377IZom1gjrhnC1bd1VDG7XZ1bP3PPxTxqppM0RuuFWx3/SwixSeWnI+zj9/Qon/wG6M/KDx+cCzuiBwwnpHf8rBmBLNbCs8SVNF3mGwPK0IQq/l4SS6VERVYDPlbBy1hNNdg40MqlJ5jr+Zln3cwF9WzQDznasTs5vK/ylxoXCvVFdOfwBaHkW1NHc3RRpwR0wq2Q8DN3mQ==gR7A"}</pre> 125 126 </dd> 127 128 <!-- ---------------------------------------------------------------------- --> 129 <dt id='frontend'>frontend</dt> 130 <dd>the public-facing server that handles sharing and unified access to both 131 your blob server and search server. (see <a href="arch">architecture diagram</a>) 132 </dd> 133 134 <!-- ---------------------------------------------------------------------- --> 135 <dt id='fullsync'>full sync</dt> 136 <dd>synchronizing all your blobs between two or more of your blob servers 137 (e.g. mirroring between your house, App Engine, and Amazon). 138 139 <p>Generally a full sync will be done with the <em>blob server</em>'s enumerate 140 support and no knowledge of the schema. It's a dumb copy of all blobs that the 141 other party doesn't already have.</p> 142 </dd> 143 144 <!-- ---------------------------------------------------------------------- --> 145 <dt id='graphsync'>graph sync</dt> 146 147 <dd>as opposed to a <em>full sync</em>, a graph sync is synchronizing 148 a sub-graph of your blobs between blob servers. This level of sync will operate 149 with knowledge of the schema.</dd> 150 151 <!-- ---------------------------------------------------------------------- --> 152 <dt id='searchserver'>search server</dt> 153 <dt id='indexer'>indexer</dt> 154 155 <dd>TODO: finish documenting</dd> 156 157 </dl> 158 159 <script> 160 var terms = document.getElementsByTagName("dt"); 161 for (var i = 0; i < terms.length; i++) { 162 var term = terms[i]; 163 var id = term.getAttribute("id"); 164 if (!id) { 165 continue; 166 } 167 var link = document.createElement("span"); 168 link.setAttribute("class", "termhashlink"); 169 link.innerHTML = " [<a href='#" + id + "'>#</a>]"; 170 term.appendChild(link); 171 } 172 </script>