1/* ------------------------------------------------------------------- 2** 3** riakclient.proto: Protocol buffers for riak 4** 5** Copyright (c) 2007-2010 Basho Technologies, Inc. All Rights Reserved. 6** 7** This file is provided to you under the Apache License, 8** Version 2.0 (the "License"); you may not use this file 9** except in compliance with the License. You may obtain 10** a copy of the License at 11** 12** http://www.apache.org/licenses/LICENSE-2.0 13** 14** Unless required by applicable law or agreed to in writing, 15** software distributed under the License is distributed on an 16** "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17** KIND, either express or implied. See the License for the 18** specific language governing permissions and limitations 19** under the License. 20** 21** ------------------------------------------------------------------- 22*/ 23/* 24** Revision: 1.1 25** 26** Lowest Common Denominator Protocol Buffers Client 27** - no ENUM (protobuffs_erlang does not support) 28** 29** Protocol 30** 31** The protocol encodes requests and responses as protocol buffer messages. 32** Each request message results in one or more response messages. 33** As message type and length are not encoded by PB they are sent 34** on the wire as 35** 36** <length:32> <msg_code:8> <pbmsg> 37** 38** length is the length of msg_code (1 byte) plus the message length 39** in bytes encoded in network order (big endian) 40** 41** msg_code indicates what is encoded as pbmsg 42** 43** pbmsg is the encoded protocol buffer message 44** 45** On connect, the client can make requests and will receive responses. 46** For each request message there is a corresponding response message, 47** or the server will respond with an error message if something has 48** gone wrong. 49** 50** The client should be prepared to handle messages without any pbmsg 51** (i.e. length==1) for requests like ping or a put without return_body set. 52** 53** RpbGetClientIdReq -> RpbGetClientIdResp 54** RpbSetClientIdReq -> RpbSetClientIdResp 55** RpbGetServerInfoReq -> RpbGetServerInfoResp 56** RpbPingReq -> RpbPingResp 57** RpbGetReq -> RpbErrorResp | RbpGetResp 58** RpbPutReq -> RpbErrorResp | RpbPutResp 59** RpbDelReq -> RpbErrorResp | RpbDelResp 60** RpbListBucketsReq -> RpbErrorResp | RpbListBucketsResp 61** RpbListKeysReq -> RpbErrorResp | RpbListKeysResp{1,} 62** RpbGetBucketReq -> RpbErrorResp | RpbGetBucketResp 63** 64** 65** Message Codes 66** 0 - RpbErrorResp 67** 1 - RpbPingReq - 0 length 68** 2 - RpbPingResp (pong) - 0 length 69** 3 - RpbGetClientIdReq 70** 4 - RpbGetClientIdResp 71** 5 - RpbSetClientIdReq 72** 6 - RpbSetClientIdResp 73** 7 - RpbGetServerInfoReq 74** 8 - RpbGetServerInfoResp 75** 9 - RpbGetReq 76** 10 - RpbGetResp 77** 11 - RpbPutReq 78** 12 - RpbPutResp - 0 length 79** 13 - RpbDelReq 80** 14 - RpbDelResp 81** 15 - RpbListBucketsReq 82** 16 - RpbListBucketsResp 83** 17 - RpbListKeysReq 84** 18 - RpbListKeysResp{1,} 85** 19 - RpbGetBucketReq 86** 20 - RpbGetBucketResp 87** 21 - RpbSetBucketReq 88** 22 - RpbSetBucketResp 89** 23 - RpbMapRedReq 90** 24 - RpbMapRedResp{1,} 91** 92*/ 93 94// Error response - may be generated for any Req 95message RpbErrorResp { 96 required bytes errmsg = 1; 97 required uint32 errcode = 2; 98} 99 100// Get ClientId Request - no message defined, just send RpbGetClientIdReq message code 101message RpbGetClientIdResp { 102 required bytes client_id = 1; // Client id in use for this connection 103} 104 105message RpbSetClientIdReq { 106 required bytes client_id = 1; // Client id to use for this connection 107} 108// Set ClientId Request - no message defined, just send RpbSetClientIdReq message code 109 110// Get server info request - no message defined, just send RpbGetServerInfoReq message code 111 112message RpbGetServerInfoResp { 113 optional bytes node = 1; 114 optional bytes server_version = 2; 115} 116 117 118// Get Request - retrieve bucket/key 119message RpbGetReq { 120 required bytes bucket = 1; 121 required bytes key = 2; 122 optional uint32 r = 3; 123} 124 125// Get Response - if the record was not found there will be no content/vclock 126message RpbGetResp { 127 repeated RpbContent content = 1; 128 optional bytes vclock = 2; // the opaque vector clock for the object 129} 130 131 132// Put request - if options.return_body is set then the updated metadata/data for 133// the key will be returned. 134message RpbPutReq { 135 required bytes bucket = 1; 136 required bytes key = 2; 137 optional bytes vclock = 3; 138 required RpbContent content = 4; 139 optional uint32 w = 5; 140 optional uint32 dw = 6; 141 optional bool return_body = 7; 142} 143 144// Put response - same as get response 145message RpbPutResp { 146 repeated RpbContent content = 1; 147 optional bytes vclock = 2; // the opaque vector clock for the object 148} 149 150 151// Delete request 152message RpbDelReq { 153 required bytes bucket = 1; 154 required bytes key = 2; 155 optional uint32 rw = 3; 156} 157 158// Delete response - not defined, will return a RpbDelResp on success or RpbErrorResp on failure 159 160// List buckets request - no message defined, just send RpbListBucketsReq 161 162// List buckets response 163message RpbListBucketsResp { 164 repeated bytes buckets = 1; 165} 166 167 168// List keys in bucket request 169message RpbListKeysReq { 170 required bytes bucket = 1; 171} 172 173// List keys in bucket response - one or more of these packets will be sent 174// the last one will have done set true (and may not have any keys in it) 175message RpbListKeysResp { 176 repeated bytes keys = 1; 177 optional bool done = 2; 178} 179 180// Get bucket properties request 181message RpbGetBucketReq { 182 required bytes bucket = 1; 183} 184 185// Get bucket properties response 186message RpbGetBucketResp { 187 required RpbBucketProps props = 1; 188} 189 190// Set bucket properties request 191message RpbSetBucketReq { 192 required bytes bucket = 1; 193 required RpbBucketProps props = 2; 194} 195 196 197// Set bucket properties response - no message defined, just send RpbSetBucketResp 198 199 200// Map/Reduce request 201message RpbMapRedReq { 202 required bytes request = 1; 203 required bytes content_type = 2; 204} 205 206// Map/Reduce response 207// one or more of these packets will be sent the last one will have done set 208// true (and may not have phase/data in it) 209message RpbMapRedResp { 210 optional uint32 phase = 1; 211 optional bytes response = 2; 212 optional bool done = 3; 213} 214 215// Content message included in get/put responses 216// Holds the value and associated metadata 217message RpbContent { 218 required bytes value = 1; 219 optional bytes content_type = 2; // the media type/format 220 optional bytes charset = 3; 221 optional bytes content_encoding = 4; 222 optional bytes vtag = 5; 223 repeated RpbLink links = 6; // links to other resources 224 optional uint32 last_mod = 7; 225 optional uint32 last_mod_usecs = 8; 226 repeated RpbPair usermeta = 9; // user metadata stored with the object 227} 228 229// Key/value pair - used for user metadata 230message RpbPair { 231 required bytes key = 1; 232 optional bytes value = 2; 233} 234 235// Link metadata 236message RpbLink { 237 optional bytes bucket = 1; 238 optional bytes key = 2; 239 optional bytes tag = 3; 240} 241 242// Bucket properties 243message RpbBucketProps { 244 optional uint32 n_val = 1; 245 optional bool allow_mult = 2; 246} 247