forked from ghaskins/riak_wiki
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'master' of github.com:basho/riak_wiki
- Loading branch information
Showing
21 changed files
with
1,518 additions
and
1,291 deletions.
There are no files selected for viewing
935 changes: 0 additions & 935 deletions
935
pages/Riak/Developers/Client-Implementation-Guide/PBC-API.textile
This file was deleted.
Oops, something went wrong.
117 changes: 117 additions & 0 deletions
117
pages/Riak/Developers/Client-Implementation-Guide/PBC-API/PBC-API.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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]] | ||
|
||
|
60 changes: 60 additions & 0 deletions
60
pages/Riak/Developers/Client-Implementation-Guide/PBC-API/PBC-Delete-Object.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
``` |
158 changes: 158 additions & 0 deletions
158
pages/Riak/Developers/Client-Implementation-Guide/PBC-API/PBC-Fetch-Object.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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" | ||
``` |
Oops, something went wrong.