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