Merge branch 'master' of github.com:basho/riak_wiki

pages/Riak/Developers/Client-Implementation-Guide/PBC-API/PBC-API.md

@@ -0,0 +1,117 @@
+This is an overview of the operations you can perform over the Protocol Buffers
+Client (PBC) interface to Riak, and can be used as a guide for developing a
+compliant client.
+
+<div id="toc"></div>
+
+## Protocol
+
+Riak listens on a TCP port (8087 by default) for incoming connections. Once
+connected the client can send a stream of requests on the same connection.
+
+Each operation consists of a request message and one or more response messages.
+Messages are all encoded the same way
+* 32-bit length of message code + protocol buffer message in network order
+* 8-bit message code to identify the protocol buffer message
+* N-bytes of protocol buffers encoded message
+
+### Example
+
+
+```bash
+00 00 00 07 09 0A 01 62 12 01 6B
+|----Len---|MC|----Message-----|
+
+Len = 0x07
+Message Code (MC) = 0x09 = RpbGetReq
+RpbGetReq Message = 0x0A 0x01 0x62 0x12 0x01 0x6B
+
+Decoded Message:
+bucket: "b"
+key: "k"
+```
+
+
+### Message Codes
+
+<table>
+<tr><td>0</td><td>RpbErrorResp</td></tr>
+<tr><td>1</td><td>RpbPingReq</td></tr>
+<tr><td>2</td><td>RpbPingResp</td></tr>
+<tr><td>3</td><td>RpbGetClientIdReq</td></tr>
+<tr><td>4</td><td>RpbGetClientIdResp</td></tr>
+<tr><td>5</td><td>RpbSetClientIdReq</td></tr>
+<tr><td>6</td><td>RpbSetClientIdResp</td></tr>
+<tr><td>7</td><td>RpbGetServerInfoReq</td></tr>
+<tr><td>8</td><td>RpbGetServerInfoResp</td></tr>
+<tr><td>9</td><td>RpbGetReq</td></tr>
+<tr><td>10</td><td>RpbGetResp</td></tr>
+<tr><td>11</td><td>RpbPutReq</td></tr>
+<tr><td>12</td><td>RpbPutResp</td></tr>
+<tr><td>13</td><td>RpbDelReq</td></tr>
+<tr><td>14</td><td>RpbDelResp</td></tr>
+<tr><td>15</td><td>RpbListBucketsReq</td></tr>
+<tr><td>16</td><td>RpbListBucketsResp</td></tr>
+<tr><td>17</td><td>RpbListKeysReq</td></tr>
+<tr><td>18</td><td>RpbListKeysResp</td></tr>
+<tr><td>19</td><td>RpbGetBucketReq</td></tr>
+<tr><td>20</td><td>RpbGetBucketResp</td></tr>
+<tr><td>21</td><td>RpbSetBucketReq</td></tr>
+<tr><td>22</td><td>RpbSetBucketResp</td></tr>
+<tr><td>23</td><td>RpbMapRedReq</td></tr>
+<tr><td>24</td><td>RpbMapRedResp</td></tr>
+</table>
+
+
+<div class="info"><div class="title">Message Definitions</div>
+<p>All Protocol Buffers messages can be found defined in the
+[[riakclient.proto|http://github.com/basho/riak-erlang-client/blob/master/src/
+riakclient.proto]] file in the Erlang client.</p>
+</div>
+
+
+### Error Response
+
+If the server experiences an error processing a request it will return an
+RpbErrorResp message instead of the response expected for the given request
+(e.g. RbpGetResp is the expected response to RbpGetReq).  Error messages contain
+an error string and an error code.
+
+```bash
+message RpbErrorResp {
+    required bytes errmsg = 1;
+    required uint32 errcode = 2;
+}
+```
+
+
+Values:
+
+* **errmsg** - a string representation of what went wrong
+* **errcode** - a numeric code. Currently only RIAKC_ERR_GENERAL=1 is defined.
+
+## Bucket Operations
+
+* [[PBC List Buckets]]
+* [[PBC List Keys]]
+* [[PBC Get Bucket Properties]]
+* [[PBC Set Bucket Properties]]
+
+## Object/Key Operations
+
+* [[PBC Fetch Object]]
+* [[PBC Store Object]]
+* [[PBC Delete Object]]
+
+## Query Operations
+
+* [[PBC MapReduce]]
+
+## Server Operations
+
+* [[PBC Ping]]
+* [[PBC Get Client ID]]
+* [[PBC Set Client ID]]
+* [[PBC Server Info]]
+
+

pages/Riak/Developers/Client-Implementation-Guide/PBC-API/PBC-Delete-Object.md

@@ -0,0 +1,60 @@
+Deletes an object from the specified bucket / key.
+
+## Request
+
+```bash
+message RpbDelReq {
+    required bytes bucket = 1;
+    required bytes key = 2;
+    optional uint32 rw = 3;
+    optional bytes vclock = 4;
+    optional uint32 r = 5;
+    optional uint32 w = 6;
+    optional uint32 pr = 7;
+    optional uint32 pw = 8;
+    optional uint32 dw = 9;
+}
+```
+
+Optional Parameters
+
+* **rw** - how many replicas to delete before returning a successful response;
+possible values include 'default', 'one', 'quorum', 'all', or any integer <= N
+([[default is defined per the bucket|PBC API#Set Bucket Properties]])
+* **vclock** - opaque vector clock provided by an earlier RpbGetResp message.
+Use to prevent deleting of objects that have been modified since the last get request
+* **r** - (read quorum) how many replicas need to agree when retrieving the object; possible values include 'default', 'one', 'quorum', 'all', or any integer <= N ([[default is defined per the bucket|PBC API#Set Bucket Properties]])
+* **w** - (write quorum) how many replicas to write to before returning a successful response; possible values include 'default', 'one', 'quorum', 'all', or any integer <= N ([[default is defined per the bucket|PBC API#Set Bucket Properties]])
+* **pr** - (primary read quorum) how many primary replicas need to be available when retrieving the object; possible values include 'default', 'one', 'quorum', 'all', or any integer <= N ([[default is defined per the bucket|PBC API#Set Bucket Properties]])
+* **pw** - how many primary nodes must be up when the write is attempted; possible values include 'default', 'one', 'quorum', 'all', or any integer <= N ([[default is defined per the bucket|PBC API#Set Bucket Properties]])
+* **dw** - how many replicas to commit to durable storage before returning a successful response; possible values include 'default', 'one', 'quorum', 'all', or any integer <= N ([[default is defined per the bucket|PBC API#Set Bucket Properties]])
+
+## Response
+
+Only the message code is returned.
+
+## Example
+
+Request
+
+```bash
+Hex      00 00 00 12 0D 0A 0A 6E 6F 74 61 62 75 63 6B 65
+         74 12 01 6B 18 01
+Erlang <<0,0,0,18,13,10,10,110,111,116,97,98,117,99,107,101,116,18,1,107,24,1>>
+
+RpbDelReq protoc decode:
+bucket: "notabucket"
+key: "k"
+rw: 1
+
+```
+
+
+Response
+
+```bash
+Hex      00 00 00 01 0E
+Erlang <<0,0,0,1,14>>
+
+RpbDelResp - only message code defined
+```

pages/Riak/Developers/Client-Implementation-Guide/PBC-API/PBC-Fetch-Object.md

@@ -0,0 +1,158 @@
+Fetch an object from Riak
+
+## Request
+
+
+```bash
+message RpbGetReq {
+    required bytes bucket = 1;
+    required bytes key = 2;
+    optional uint32 r = 3;
+    optional uint32 pr = 4;
+    optional bool basic_quorum = 5;
+    optional bool notfound_ok = 6;
+    optional bytes if_modified = 7;
+    optional bool head = 8;
+    optional bool deletedvclock = 9;
+}
+```
+
+
+Optional Parameters
+
+* **r** - (read quorum) how many replicas need to agree when retrieving the
+object; possible values include 'default', 'one', 'quorum', 'all', or any
+integer <= N ([[default is defined per the bucket|PBC API#Set Bucket
+Properties]])
+* **pr** - (primary read quorum) how many primary replicas need to be available
+when retrieving the object; possible values include 'default', 'one', 'quorum',
+'all', or any integer <= N ([[default is defined per the bucket|PBC API#Set
+Bucket Properties]])
+* **basic_quorum** - whether to return early in some failure cases (eg. when r=1
+and you get 2 errors and a success basic_quorum=true would return an error)
+([[default is defined per the bucket|PBC API#Set Bucket Properties]])
+* **notfound_ok** - whether to treat notfounds as successful reads for the
+purposes of R ([[default is defined per the bucket|PBC API#Set Bucket
+Properties]])
+* **if_modified** - when a vclock is supplied as this option only return the
+object if the vclocks don't match
+* **head** - return the object with the value(s) set as empty - allows you to
+get the metadata without a potentially large value
+* **deletedvclock** - return the tombstone's vclock, if applicable
+
+## Response
+
+
+```bash
+message RpbGetResp {
+    repeated RpbContent content = 1;
+    optional bytes vclock = 2;
+    optional bool unchanged = 3;
+}
+```
+
+
+Values
+
+* **content** - value+metadata entries for the object. If there are siblings
+there will be more than one entry. If the key is not found, content will be
+empty.
+* **vclock** - vclock Opaque vector clock that must be included in *RpbPutReq*
+to resolve the siblings.
+* **unchanged** - if if_modified was specified in the get request but the object
+has not been modified, this will be set to true
+
+The content entries hold the object value and any metadata
+
+
+```bash
+// Content message included in get/put responses
+message RpbContent {
+    required bytes value = 1;
+    optional bytes content_type = 2;     // the media type/format
+    optional bytes charset = 3;
+    optional bytes content_encoding = 4;
+    optional bytes vtag = 5;
+    repeated RpbLink links = 6;          // links to other resources
+    optional uint32 last_mod = 7;
+    optional uint32 last_mod_usecs = 8;
+    repeated RpbPair usermeta = 9;       // user metadata stored with the object
+    repeated RpbPair indexes = 10;
+}
+```
+
+
+Each object can contain user-supplied metadata (X-Riak-Meta-\* in the HTTP
+interface) consisting of a key/value pair. (e.g. key=X-Riak-Meta-ACL
+value=users:r,administrators:f would allow an application to store access
+control information for it to enforce (*not* Riak)).
+
+
+```bash
+// Key/value pair - used for user metadata
+message RpbPair {
+    required bytes key = 1;
+    optional bytes value = 2;
+}
+```
+
+
+Links store references to related bucket/keys and can be accessed through link
+walking in map/reduce.
+
+
+```bash
+// Link metadata
+message RpbLink {
+    optional bytes bucket = 1;
+    optional bytes key = 2;
+    optional bytes tag = 3;
+}
+```
+
+
+
+<div class="note"><div class="title">Missing keys</div>
+<p>Remember - if a key is not stored in Riak an RpbGetResp without content and
+vclock fields will be returned. This should be mapped to whatever convention the
+client language uses to return not found, e.g. the erlang client returns an atom
+<code>{error, notfound}</code></p>
+</div>
+
+
+## Example
+
+Request
+
+```bash
+Hex      00 00 00 07 09 0A 01 62 12 01 6B
+Erlang <<0,0,0,7,9,10,1,98,18,1,107>>
+
+RpbGetReq protoc decode:
+bucket: "b"
+key: "k"
+```
+
+
+Response
+
+```bash
+Hex      00 00 00 4A 0A 0A 26 0A 02 76 32 2A 16 33 53 44
+         6C 66 34 49 4E 4B 7A 38 68 4E 64 68 79 49 6D 4B
+         49 72 75 38 BB D7 A2 DE 04 40 E0 B9 06 12 1F 6B
+         CE 61 60 60 60 CC 60 CA 05 52 2C AC C2 5B 3F 65
+         30 25 32 E5 B1 32 EC 56 B7 3D CA 97 05 00
+Erlang <<0,0,0,74,10,10,38,10,2,118,50,42,22,51,83,68,108,102,52,73,78,75,122,
+         56,104,78,100,104,121,73,109,75,73,114,117,56,187,215,162,222,4,64,
+         224,185,6,18,31,107,206,97,96,96,96,204,96,202,5,82,44,172,194,91,63,
+         101,48,37,50,229,177,50,236,86,183,61,202,151,5,0>>
+
+RpbGetResp protoc decode:
+content {
+  value: "v2"
+  vtag: "3SDlf4INKz8hNdhyImKIru"
+  last_mod: 1271442363
+  last_mod_usecs: 105696
+}
+vclock: "k316a```314`312005R,254302[?e0%23452612354V267=312227005000"
+```