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