blob: 81ae31fd8f32f5d395df93344e2634450f65d9ce [file] [log] [blame]
William Kurkianea869482019-04-09 15:16:11 -04001// Copyright 2016 The etcd Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15package clientv3
16
17import pb "go.etcd.io/etcd/etcdserver/etcdserverpb"
18
19type opType int
20
21const (
22 // A default Op has opType 0, which is invalid.
23 tRange opType = iota + 1
24 tPut
25 tDeleteRange
26 tTxn
27)
28
29var noPrefixEnd = []byte{0}
30
31// Op represents an Operation that kv can execute.
32type Op struct {
33 t opType
34 key []byte
35 end []byte
36
37 // for range
38 limit int64
39 sort *SortOption
40 serializable bool
41 keysOnly bool
42 countOnly bool
43 minModRev int64
44 maxModRev int64
45 minCreateRev int64
46 maxCreateRev int64
47
48 // for range, watch
49 rev int64
50
51 // for watch, put, delete
52 prevKV bool
53
54 // for watch
55 // fragmentation should be disabled by default
56 // if true, split watch events when total exceeds
57 // "--max-request-bytes" flag value + 512-byte
58 fragment bool
59
60 // for put
61 ignoreValue bool
62 ignoreLease bool
63
64 // progressNotify is for progress updates.
65 progressNotify bool
66 // createdNotify is for created event
67 createdNotify bool
68 // filters for watchers
69 filterPut bool
70 filterDelete bool
71
72 // for put
73 val []byte
74 leaseID LeaseID
75
76 // txn
77 cmps []Cmp
78 thenOps []Op
79 elseOps []Op
80}
81
82// accessors / mutators
83
84// IsTxn returns true if the "Op" type is transaction.
85func (op Op) IsTxn() bool {
86 return op.t == tTxn
87}
88
89// Txn returns the comparison(if) operations, "then" operations, and "else" operations.
90func (op Op) Txn() ([]Cmp, []Op, []Op) {
91 return op.cmps, op.thenOps, op.elseOps
92}
93
94// KeyBytes returns the byte slice holding the Op's key.
95func (op Op) KeyBytes() []byte { return op.key }
96
97// WithKeyBytes sets the byte slice for the Op's key.
98func (op *Op) WithKeyBytes(key []byte) { op.key = key }
99
100// RangeBytes returns the byte slice holding with the Op's range end, if any.
101func (op Op) RangeBytes() []byte { return op.end }
102
103// Rev returns the requested revision, if any.
104func (op Op) Rev() int64 { return op.rev }
105
106// IsPut returns true iff the operation is a Put.
107func (op Op) IsPut() bool { return op.t == tPut }
108
109// IsGet returns true iff the operation is a Get.
110func (op Op) IsGet() bool { return op.t == tRange }
111
112// IsDelete returns true iff the operation is a Delete.
113func (op Op) IsDelete() bool { return op.t == tDeleteRange }
114
115// IsSerializable returns true if the serializable field is true.
Abhilash S.L3b494632019-07-16 15:51:09 +0530116func (op Op) IsSerializable() bool { return op.serializable }
William Kurkianea869482019-04-09 15:16:11 -0400117
118// IsKeysOnly returns whether keysOnly is set.
Abhilash S.L3b494632019-07-16 15:51:09 +0530119func (op Op) IsKeysOnly() bool { return op.keysOnly }
William Kurkianea869482019-04-09 15:16:11 -0400120
121// IsCountOnly returns whether countOnly is set.
Abhilash S.L3b494632019-07-16 15:51:09 +0530122func (op Op) IsCountOnly() bool { return op.countOnly }
William Kurkianea869482019-04-09 15:16:11 -0400123
124// MinModRev returns the operation's minimum modify revision.
125func (op Op) MinModRev() int64 { return op.minModRev }
126
127// MaxModRev returns the operation's maximum modify revision.
128func (op Op) MaxModRev() int64 { return op.maxModRev }
129
130// MinCreateRev returns the operation's minimum create revision.
131func (op Op) MinCreateRev() int64 { return op.minCreateRev }
132
133// MaxCreateRev returns the operation's maximum create revision.
134func (op Op) MaxCreateRev() int64 { return op.maxCreateRev }
135
136// WithRangeBytes sets the byte slice for the Op's range end.
137func (op *Op) WithRangeBytes(end []byte) { op.end = end }
138
139// ValueBytes returns the byte slice holding the Op's value, if any.
140func (op Op) ValueBytes() []byte { return op.val }
141
142// WithValueBytes sets the byte slice for the Op's value.
143func (op *Op) WithValueBytes(v []byte) { op.val = v }
144
145func (op Op) toRangeRequest() *pb.RangeRequest {
146 if op.t != tRange {
147 panic("op.t != tRange")
148 }
149 r := &pb.RangeRequest{
150 Key: op.key,
151 RangeEnd: op.end,
152 Limit: op.limit,
153 Revision: op.rev,
154 Serializable: op.serializable,
155 KeysOnly: op.keysOnly,
156 CountOnly: op.countOnly,
157 MinModRevision: op.minModRev,
158 MaxModRevision: op.maxModRev,
159 MinCreateRevision: op.minCreateRev,
160 MaxCreateRevision: op.maxCreateRev,
161 }
162 if op.sort != nil {
163 r.SortOrder = pb.RangeRequest_SortOrder(op.sort.Order)
164 r.SortTarget = pb.RangeRequest_SortTarget(op.sort.Target)
165 }
166 return r
167}
168
169func (op Op) toTxnRequest() *pb.TxnRequest {
170 thenOps := make([]*pb.RequestOp, len(op.thenOps))
171 for i, tOp := range op.thenOps {
172 thenOps[i] = tOp.toRequestOp()
173 }
174 elseOps := make([]*pb.RequestOp, len(op.elseOps))
175 for i, eOp := range op.elseOps {
176 elseOps[i] = eOp.toRequestOp()
177 }
178 cmps := make([]*pb.Compare, len(op.cmps))
179 for i := range op.cmps {
180 cmps[i] = (*pb.Compare)(&op.cmps[i])
181 }
182 return &pb.TxnRequest{Compare: cmps, Success: thenOps, Failure: elseOps}
183}
184
185func (op Op) toRequestOp() *pb.RequestOp {
186 switch op.t {
187 case tRange:
188 return &pb.RequestOp{Request: &pb.RequestOp_RequestRange{RequestRange: op.toRangeRequest()}}
189 case tPut:
190 r := &pb.PutRequest{Key: op.key, Value: op.val, Lease: int64(op.leaseID), PrevKv: op.prevKV, IgnoreValue: op.ignoreValue, IgnoreLease: op.ignoreLease}
191 return &pb.RequestOp{Request: &pb.RequestOp_RequestPut{RequestPut: r}}
192 case tDeleteRange:
193 r := &pb.DeleteRangeRequest{Key: op.key, RangeEnd: op.end, PrevKv: op.prevKV}
194 return &pb.RequestOp{Request: &pb.RequestOp_RequestDeleteRange{RequestDeleteRange: r}}
195 case tTxn:
196 return &pb.RequestOp{Request: &pb.RequestOp_RequestTxn{RequestTxn: op.toTxnRequest()}}
197 default:
198 panic("Unknown Op")
199 }
200}
201
202func (op Op) isWrite() bool {
203 if op.t == tTxn {
204 for _, tOp := range op.thenOps {
205 if tOp.isWrite() {
206 return true
207 }
208 }
209 for _, tOp := range op.elseOps {
210 if tOp.isWrite() {
211 return true
212 }
213 }
214 return false
215 }
216 return op.t != tRange
217}
218
219// OpGet returns "get" operation based on given key and operation options.
220func OpGet(key string, opts ...OpOption) Op {
221 // WithPrefix and WithFromKey are not supported together
222 if isWithPrefix(opts) && isWithFromKey(opts) {
223 panic("`WithPrefix` and `WithFromKey` cannot be set at the same time, choose one")
224 }
225 ret := Op{t: tRange, key: []byte(key)}
226 ret.applyOpts(opts)
227 return ret
228}
229
230// OpDelete returns "delete" operation based on given key and operation options.
231func OpDelete(key string, opts ...OpOption) Op {
232 // WithPrefix and WithFromKey are not supported together
233 if isWithPrefix(opts) && isWithFromKey(opts) {
234 panic("`WithPrefix` and `WithFromKey` cannot be set at the same time, choose one")
235 }
236 ret := Op{t: tDeleteRange, key: []byte(key)}
237 ret.applyOpts(opts)
238 switch {
239 case ret.leaseID != 0:
240 panic("unexpected lease in delete")
241 case ret.limit != 0:
242 panic("unexpected limit in delete")
243 case ret.rev != 0:
244 panic("unexpected revision in delete")
245 case ret.sort != nil:
246 panic("unexpected sort in delete")
247 case ret.serializable:
248 panic("unexpected serializable in delete")
249 case ret.countOnly:
250 panic("unexpected countOnly in delete")
251 case ret.minModRev != 0, ret.maxModRev != 0:
252 panic("unexpected mod revision filter in delete")
253 case ret.minCreateRev != 0, ret.maxCreateRev != 0:
254 panic("unexpected create revision filter in delete")
255 case ret.filterDelete, ret.filterPut:
256 panic("unexpected filter in delete")
257 case ret.createdNotify:
258 panic("unexpected createdNotify in delete")
259 }
260 return ret
261}
262
263// OpPut returns "put" operation based on given key-value and operation options.
264func OpPut(key, val string, opts ...OpOption) Op {
265 ret := Op{t: tPut, key: []byte(key), val: []byte(val)}
266 ret.applyOpts(opts)
267 switch {
268 case ret.end != nil:
269 panic("unexpected range in put")
270 case ret.limit != 0:
271 panic("unexpected limit in put")
272 case ret.rev != 0:
273 panic("unexpected revision in put")
274 case ret.sort != nil:
275 panic("unexpected sort in put")
276 case ret.serializable:
277 panic("unexpected serializable in put")
278 case ret.countOnly:
279 panic("unexpected countOnly in put")
280 case ret.minModRev != 0, ret.maxModRev != 0:
281 panic("unexpected mod revision filter in put")
282 case ret.minCreateRev != 0, ret.maxCreateRev != 0:
283 panic("unexpected create revision filter in put")
284 case ret.filterDelete, ret.filterPut:
285 panic("unexpected filter in put")
286 case ret.createdNotify:
287 panic("unexpected createdNotify in put")
288 }
289 return ret
290}
291
292// OpTxn returns "txn" operation based on given transaction conditions.
293func OpTxn(cmps []Cmp, thenOps []Op, elseOps []Op) Op {
294 return Op{t: tTxn, cmps: cmps, thenOps: thenOps, elseOps: elseOps}
295}
296
297func opWatch(key string, opts ...OpOption) Op {
298 ret := Op{t: tRange, key: []byte(key)}
299 ret.applyOpts(opts)
300 switch {
301 case ret.leaseID != 0:
302 panic("unexpected lease in watch")
303 case ret.limit != 0:
304 panic("unexpected limit in watch")
305 case ret.sort != nil:
306 panic("unexpected sort in watch")
307 case ret.serializable:
308 panic("unexpected serializable in watch")
309 case ret.countOnly:
310 panic("unexpected countOnly in watch")
311 case ret.minModRev != 0, ret.maxModRev != 0:
312 panic("unexpected mod revision filter in watch")
313 case ret.minCreateRev != 0, ret.maxCreateRev != 0:
314 panic("unexpected create revision filter in watch")
315 }
316 return ret
317}
318
319func (op *Op) applyOpts(opts []OpOption) {
320 for _, opt := range opts {
321 opt(op)
322 }
323}
324
325// OpOption configures Operations like Get, Put, Delete.
326type OpOption func(*Op)
327
328// WithLease attaches a lease ID to a key in 'Put' request.
329func WithLease(leaseID LeaseID) OpOption {
330 return func(op *Op) { op.leaseID = leaseID }
331}
332
333// WithLimit limits the number of results to return from 'Get' request.
334// If WithLimit is given a 0 limit, it is treated as no limit.
335func WithLimit(n int64) OpOption { return func(op *Op) { op.limit = n } }
336
337// WithRev specifies the store revision for 'Get' request.
338// Or the start revision of 'Watch' request.
339func WithRev(rev int64) OpOption { return func(op *Op) { op.rev = rev } }
340
341// WithSort specifies the ordering in 'Get' request. It requires
342// 'WithRange' and/or 'WithPrefix' to be specified too.
343// 'target' specifies the target to sort by: key, version, revisions, value.
344// 'order' can be either 'SortNone', 'SortAscend', 'SortDescend'.
345func WithSort(target SortTarget, order SortOrder) OpOption {
346 return func(op *Op) {
347 if target == SortByKey && order == SortAscend {
348 // If order != SortNone, server fetches the entire key-space,
349 // and then applies the sort and limit, if provided.
350 // Since by default the server returns results sorted by keys
351 // in lexicographically ascending order, the client should ignore
352 // SortOrder if the target is SortByKey.
353 order = SortNone
354 }
355 op.sort = &SortOption{target, order}
356 }
357}
358
359// GetPrefixRangeEnd gets the range end of the prefix.
360// 'Get(foo, WithPrefix())' is equal to 'Get(foo, WithRange(GetPrefixRangeEnd(foo))'.
361func GetPrefixRangeEnd(prefix string) string {
362 return string(getPrefix([]byte(prefix)))
363}
364
365func getPrefix(key []byte) []byte {
366 end := make([]byte, len(key))
367 copy(end, key)
368 for i := len(end) - 1; i >= 0; i-- {
369 if end[i] < 0xff {
370 end[i] = end[i] + 1
371 end = end[:i+1]
372 return end
373 }
374 }
375 // next prefix does not exist (e.g., 0xffff);
376 // default to WithFromKey policy
377 return noPrefixEnd
378}
379
380// WithPrefix enables 'Get', 'Delete', or 'Watch' requests to operate
381// on the keys with matching prefix. For example, 'Get(foo, WithPrefix())'
382// can return 'foo1', 'foo2', and so on.
383func WithPrefix() OpOption {
384 return func(op *Op) {
385 if len(op.key) == 0 {
386 op.key, op.end = []byte{0}, []byte{0}
387 return
388 }
389 op.end = getPrefix(op.key)
390 }
391}
392
393// WithRange specifies the range of 'Get', 'Delete', 'Watch' requests.
394// For example, 'Get' requests with 'WithRange(end)' returns
395// the keys in the range [key, end).
396// endKey must be lexicographically greater than start key.
397func WithRange(endKey string) OpOption {
398 return func(op *Op) { op.end = []byte(endKey) }
399}
400
401// WithFromKey specifies the range of 'Get', 'Delete', 'Watch' requests
402// to be equal or greater than the key in the argument.
403func WithFromKey() OpOption {
404 return func(op *Op) {
405 if len(op.key) == 0 {
406 op.key = []byte{0}
407 }
408 op.end = []byte("\x00")
409 }
410}
411
412// WithSerializable makes 'Get' request serializable. By default,
413// it's linearizable. Serializable requests are better for lower latency
414// requirement.
415func WithSerializable() OpOption {
416 return func(op *Op) { op.serializable = true }
417}
418
419// WithKeysOnly makes the 'Get' request return only the keys and the corresponding
420// values will be omitted.
421func WithKeysOnly() OpOption {
422 return func(op *Op) { op.keysOnly = true }
423}
424
425// WithCountOnly makes the 'Get' request return only the count of keys.
426func WithCountOnly() OpOption {
427 return func(op *Op) { op.countOnly = true }
428}
429
430// WithMinModRev filters out keys for Get with modification revisions less than the given revision.
431func WithMinModRev(rev int64) OpOption { return func(op *Op) { op.minModRev = rev } }
432
433// WithMaxModRev filters out keys for Get with modification revisions greater than the given revision.
434func WithMaxModRev(rev int64) OpOption { return func(op *Op) { op.maxModRev = rev } }
435
436// WithMinCreateRev filters out keys for Get with creation revisions less than the given revision.
437func WithMinCreateRev(rev int64) OpOption { return func(op *Op) { op.minCreateRev = rev } }
438
439// WithMaxCreateRev filters out keys for Get with creation revisions greater than the given revision.
440func WithMaxCreateRev(rev int64) OpOption { return func(op *Op) { op.maxCreateRev = rev } }
441
442// WithFirstCreate gets the key with the oldest creation revision in the request range.
443func WithFirstCreate() []OpOption { return withTop(SortByCreateRevision, SortAscend) }
444
445// WithLastCreate gets the key with the latest creation revision in the request range.
446func WithLastCreate() []OpOption { return withTop(SortByCreateRevision, SortDescend) }
447
448// WithFirstKey gets the lexically first key in the request range.
449func WithFirstKey() []OpOption { return withTop(SortByKey, SortAscend) }
450
451// WithLastKey gets the lexically last key in the request range.
452func WithLastKey() []OpOption { return withTop(SortByKey, SortDescend) }
453
454// WithFirstRev gets the key with the oldest modification revision in the request range.
455func WithFirstRev() []OpOption { return withTop(SortByModRevision, SortAscend) }
456
457// WithLastRev gets the key with the latest modification revision in the request range.
458func WithLastRev() []OpOption { return withTop(SortByModRevision, SortDescend) }
459
460// withTop gets the first key over the get's prefix given a sort order
461func withTop(target SortTarget, order SortOrder) []OpOption {
462 return []OpOption{WithPrefix(), WithSort(target, order), WithLimit(1)}
463}
464
465// WithProgressNotify makes watch server send periodic progress updates
466// every 10 minutes when there is no incoming events.
467// Progress updates have zero events in WatchResponse.
468func WithProgressNotify() OpOption {
469 return func(op *Op) {
470 op.progressNotify = true
471 }
472}
473
474// WithCreatedNotify makes watch server sends the created event.
475func WithCreatedNotify() OpOption {
476 return func(op *Op) {
477 op.createdNotify = true
478 }
479}
480
481// WithFilterPut discards PUT events from the watcher.
482func WithFilterPut() OpOption {
483 return func(op *Op) { op.filterPut = true }
484}
485
486// WithFilterDelete discards DELETE events from the watcher.
487func WithFilterDelete() OpOption {
488 return func(op *Op) { op.filterDelete = true }
489}
490
491// WithPrevKV gets the previous key-value pair before the event happens. If the previous KV is already compacted,
492// nothing will be returned.
493func WithPrevKV() OpOption {
494 return func(op *Op) {
495 op.prevKV = true
496 }
497}
498
499// WithFragment to receive raw watch response with fragmentation.
500// Fragmentation is disabled by default. If fragmentation is enabled,
501// etcd watch server will split watch response before sending to clients
502// when the total size of watch events exceed server-side request limit.
503// The default server-side request limit is 1.5 MiB, which can be configured
504// as "--max-request-bytes" flag value + gRPC-overhead 512 bytes.
505// See "etcdserver/api/v3rpc/watch.go" for more details.
506func WithFragment() OpOption {
507 return func(op *Op) { op.fragment = true }
508}
509
510// WithIgnoreValue updates the key using its current value.
511// This option can not be combined with non-empty values.
512// Returns an error if the key does not exist.
513func WithIgnoreValue() OpOption {
514 return func(op *Op) {
515 op.ignoreValue = true
516 }
517}
518
519// WithIgnoreLease updates the key using its current lease.
520// This option can not be combined with WithLease.
521// Returns an error if the key does not exist.
522func WithIgnoreLease() OpOption {
523 return func(op *Op) {
524 op.ignoreLease = true
525 }
526}
527
528// LeaseOp represents an Operation that lease can execute.
529type LeaseOp struct {
530 id LeaseID
531
532 // for TimeToLive
533 attachedKeys bool
534}
535
536// LeaseOption configures lease operations.
537type LeaseOption func(*LeaseOp)
538
539func (op *LeaseOp) applyOpts(opts []LeaseOption) {
540 for _, opt := range opts {
541 opt(op)
542 }
543}
544
545// WithAttachedKeys makes TimeToLive list the keys attached to the given lease ID.
546func WithAttachedKeys() LeaseOption {
547 return func(op *LeaseOp) { op.attachedKeys = true }
548}
549
550func toLeaseTimeToLiveRequest(id LeaseID, opts ...LeaseOption) *pb.LeaseTimeToLiveRequest {
551 ret := &LeaseOp{id: id}
552 ret.applyOpts(opts)
553 return &pb.LeaseTimeToLiveRequest{ID: int64(id), Keys: ret.attachedKeys}
554}
555
556// isWithPrefix returns true if WithPrefix is being called in the op
557func isWithPrefix(opts []OpOption) bool { return isOpFuncCalled("WithPrefix", opts) }
558
559// isWithFromKey returns true if WithFromKey is being called in the op
560func isWithFromKey(opts []OpOption) bool { return isOpFuncCalled("WithFromKey", opts) }