userver: userver/storages/redis/client.hpp Source File
Loading...
Searching...
No Matches
client.hpp
Go to the documentation of this file.
1#pragma once
2
3/// @file userver/storages/redis/client.hpp
4/// @brief @copybrief storages::redis::Client
5
6#include <chrono>
7#include <memory>
8#include <string>
9
10#include <userver/storages/redis/base.hpp>
11#include <userver/storages/redis/wait_connected_mode.hpp>
12
13#include <userver/storages/redis/bit_operation.hpp>
14#include <userver/storages/redis/client_fwd.hpp>
15#include <userver/storages/redis/command_options.hpp>
16#include <userver/storages/redis/request.hpp>
17#include <userver/storages/redis/request_eval.hpp>
18#include <userver/storages/redis/request_evalsha.hpp>
19#include <userver/storages/redis/request_generic.hpp>
20#include <userver/storages/redis/transaction.hpp>
21
22USERVER_NAMESPACE_BEGIN
23
24namespace storages::redis {
25
26enum class PubShard {
27 kZeroShard,
28 kRoundRobin,
29};
30
31/// @ingroup userver_clients
32///
33/// @brief Valkey or Redis client.
34///
35/// Usually retrieved from components::Redis component.
36///
37/// ## Example usage:
38///
39/// @snippet storages/redis/client_redistest.cpp Sample Redis Client usage
40class Client {
41public:
42 virtual ~Client() = default;
43
44 virtual size_t ShardsCount() const = 0;
45 virtual bool IsInClusterMode() const = 0;
46
47 virtual size_t ShardByKey(const std::string& key) const = 0;
48
49 void CheckShardIdx(size_t shard_idx) const;
50
51 virtual void WaitConnectedOnce(RedisWaitConnected wait_connected) = 0;
52
53 // redis commands:
54
55 virtual RequestAppend Append(std::string key, std::string value, const CommandControl& command_control) = 0;
56
57 virtual RequestBitop Bitop(
58 BitOperation op,
59 std::string dest_key,
60 std::vector<std::string> src_keys,
61 const CommandControl& command_control
62 ) = 0;
63
64 virtual RequestDbsize Dbsize(size_t shard, const CommandControl& command_control) = 0;
65
66 virtual RequestDecr Decr(std::string key, const CommandControl& command_control) = 0;
67
68 virtual RequestDel Del(std::string key, const CommandControl& command_control) = 0;
69
70 virtual RequestDel Del(std::vector<std::string> keys, const CommandControl& command_control) = 0;
71
72 virtual RequestUnlink Unlink(std::string key, const CommandControl& command_control) = 0;
73
74 virtual RequestUnlink Unlink(std::vector<std::string> keys, const CommandControl& command_control) = 0;
75
76 /// @brief Invoke the execution of a server-side Lua script.
77 ///
78 /// For huge scripts consider EvalSha() to save network bandwidth.
79 ///
80 /// Sample usage:
81 /// @snippet redis/src/storages/redis/client_cluster_redistest.cpp Sample eval usage
82 template <typename ScriptResult, typename ReplyType = ScriptResult>
83 RequestEval<ScriptResult, ReplyType> Eval(
84 std::string script,
85 std::vector<std::string> keys,
86 std::vector<std::string> args,
87 const CommandControl& command_control
88 ) {
89 return RequestEval<ScriptResult, ReplyType>{
90 EvalCommon(std::move(script), std::move(keys), std::move(args), command_control)};
91 }
92
93 /// @brief Invoke the execution of a server-side Lua script that was previously uploaded to the server via
94 /// ScriptLoad() member function.
95 ///
96 /// For small scripts consider using a simpler Eval() member function.
97 ///
98 /// Sample usage:
99 /// @snippet redis/src/storages/redis/client_cluster_redistest.cpp Sample evalsha usage
100 template <typename ScriptResult, typename ReplyType = ScriptResult>
101 RequestEvalSha<ScriptResult, ReplyType> EvalSha(
102 std::string script_hash,
103 std::vector<std::string> keys,
104 std::vector<std::string> args,
105 const CommandControl& command_control
106 ) {
107 return RequestEvalSha<ScriptResult, ReplyType>{
108 EvalShaCommon(std::move(script_hash), std::move(keys), std::move(args), command_control)};
109 }
110
111 /// @brief Execute a custom Redis command.
112 /// @param key_index Index of the key in the args vector used to determine the shard
113 ///
114 /// Sample usage:
115 /// @snippet redis/src/storages/redis/client_cluster_redistest.cpp Sample generic command usage
116 template <typename ReplyType>
117 RequestGeneric<ReplyType> GenericCommand(
118 std::string command,
119 std::vector<std::string> args,
120 size_t key_index,
121 const CommandControl& command_control
122 ) {
123 return RequestGeneric<ReplyType>{
124 GenericCommon(std::move(command), std::move(args), key_index, command_control)};
125 }
126
127 /// @brief Load the script to the server for further execution via EvalSha() member function.
128 ///
129 /// Sample usage:
130 /// @snippet redis/src/storages/redis/client_cluster_redistest.cpp Sample evalsha usage
131 virtual RequestScriptLoad ScriptLoad(std::string script, size_t shard, const CommandControl& command_control) = 0;
132
133 /// @overload
134 template <typename ScriptInfo, typename ReplyType = std::decay_t<ScriptInfo>>
135 RequestEval<std::decay_t<ScriptInfo>, ReplyType> Eval(
136 const ScriptInfo& script_info,
137 std::vector<std::string> keys,
138 std::vector<std::string> args,
139 const CommandControl& command_control
140 ) {
141 return RequestEval<std::decay_t<ScriptInfo>, ReplyType>{
142 EvalCommon(script_info.GetScript(), std::move(keys), std::move(args), command_control)};
143 }
144
145 virtual RequestExists Exists(std::string key, const CommandControl& command_control) = 0;
146
147 virtual RequestExists Exists(std::vector<std::string> keys, const CommandControl& command_control) = 0;
148
149 virtual RequestExpire Expire(std::string key, std::chrono::seconds ttl, const CommandControl& command_control) = 0;
150
151 virtual RequestGeoadd Geoadd(std::string key, GeoaddArg point_member, const CommandControl& command_control) = 0;
152
153 virtual RequestGeoadd
154 Geoadd(std::string key, std::vector<GeoaddArg> point_members, const CommandControl& command_control) = 0;
155
156 virtual RequestGeoradius Georadius(
157 std::string key,
158 Longitude lon,
159 Latitude lat,
160 double radius,
161 const GeoradiusOptions& georadius_options,
162 const CommandControl& command_control
163 ) = 0;
164
165 virtual RequestGeosearch Geosearch(
166 std::string key,
167 std::string member,
168 double radius,
169 const GeosearchOptions& geosearch_options,
170 const CommandControl& command_control
171 ) = 0;
172
173 virtual RequestGeosearch Geosearch(
174 std::string key,
175 std::string member,
176 BoxWidth width,
177 BoxHeight height,
178 const GeosearchOptions& geosearch_options,
179 const CommandControl& command_control
180 ) = 0;
181
182 virtual RequestGeosearch Geosearch(
183 std::string key,
184 Longitude lon,
185 Latitude lat,
186 double radius,
187 const GeosearchOptions& geosearch_options,
188 const CommandControl& command_control
189 ) = 0;
190
191 virtual RequestGeosearch Geosearch(
192 std::string key,
193 Longitude lon,
194 Latitude lat,
195 BoxWidth width,
196 BoxHeight height,
197 const GeosearchOptions& geosearch_options,
198 const CommandControl& command_control
199 ) = 0;
200
201 virtual RequestGet Get(std::string key, const CommandControl& command_control) = 0;
202
203 virtual RequestGetset Getset(std::string key, std::string value, const CommandControl& command_control) = 0;
204
205 virtual RequestHdel Hdel(std::string key, std::string field, const CommandControl& command_control) = 0;
206
207 virtual RequestHdel
208 Hdel(std::string key, std::vector<std::string> fields, const CommandControl& command_control) = 0;
209
210 virtual RequestHexists Hexists(std::string key, std::string field, const CommandControl& command_control) = 0;
211
212 virtual RequestHget Hget(std::string key, std::string field, const CommandControl& command_control) = 0;
213
214 // use Hscan in case of a big hash
215 virtual RequestHgetall Hgetall(std::string key, const CommandControl& command_control) = 0;
216
217 virtual RequestHincrby
218 Hincrby(std::string key, std::string field, int64_t increment, const CommandControl& command_control) = 0;
219
220 virtual RequestHincrbyfloat
221 Hincrbyfloat(std::string key, std::string field, double increment, const CommandControl& command_control) = 0;
222
223 // use Hscan in case of a big hash
224 virtual RequestHkeys Hkeys(std::string key, const CommandControl& command_control) = 0;
225
226 virtual RequestHlen Hlen(std::string key, const CommandControl& command_control) = 0;
227
228 virtual RequestHmget
229 Hmget(std::string key, std::vector<std::string> fields, const CommandControl& command_control) = 0;
230
231 virtual RequestHmset Hmset(
232 std::string key,
233 std::vector<std::pair<std::string, std::string>> field_values,
234 const CommandControl& command_control
235 ) = 0;
236
237 /// @brief Iterate over a collection of elements.
238 ///
239 /// Sample usage:
240 /// @snippet redis/src/storages/redis/client_scan_redistest.cpp Sample Hscan usage
241 virtual RequestHscan Hscan(std::string key, HscanOptions options, const CommandControl& command_control) = 0;
242
243 virtual RequestHset
244 Hset(std::string key, std::string field, std::string value, const CommandControl& command_control) = 0;
245
246 virtual RequestHsetnx
247 Hsetnx(std::string key, std::string field, std::string value, const CommandControl& command_control) = 0;
248
249 // use Hscan in case of a big hash
250 virtual RequestHvals Hvals(std::string key, const CommandControl& command_control) = 0;
251
252 virtual RequestIncr Incr(std::string key, const CommandControl& command_control) = 0;
253
254 [[deprecated("use Scan")]] virtual RequestKeys
255 Keys(std::string keys_pattern, size_t shard, const CommandControl& command_control) = 0;
256
257 virtual RequestLindex Lindex(std::string key, int64_t index, const CommandControl& command_control) = 0;
258
259 virtual RequestLlen Llen(std::string key, const CommandControl& command_control) = 0;
260
261 virtual RequestLpop Lpop(std::string key, const CommandControl& command_control) = 0;
262
263 virtual RequestLpush Lpush(std::string key, std::string value, const CommandControl& command_control) = 0;
264
265 virtual RequestLpush
266 Lpush(std::string key, std::vector<std::string> values, const CommandControl& command_control) = 0;
267
268 virtual RequestLpushx Lpushx(std::string key, std::string element, const CommandControl& command_control) = 0;
269
270 virtual RequestLrange
271 Lrange(std::string key, int64_t start, int64_t stop, const CommandControl& command_control) = 0;
272
273 virtual RequestLrem
274 Lrem(std::string key, int64_t count, std::string element, const CommandControl& command_control) = 0;
275
276 virtual RequestLtrim Ltrim(std::string key, int64_t start, int64_t stop, const CommandControl& command_control) = 0;
277
278 virtual RequestMget Mget(std::vector<std::string> keys, const CommandControl& command_control) = 0;
279
280 virtual RequestMset
281 Mset(std::vector<std::pair<std::string, std::string>> key_values, const CommandControl& command_control) = 0;
282
283 virtual TransactionPtr Multi() = 0;
284
285 virtual TransactionPtr Multi(Transaction::CheckShards check_shards) = 0;
286
287 virtual RequestPersist Persist(std::string key, const CommandControl& command_control) = 0;
288
289 virtual RequestPexpire
290 Pexpire(std::string key, std::chrono::milliseconds ttl, const CommandControl& command_control) = 0;
291
292 virtual RequestPing Ping(size_t shard, const CommandControl& command_control) = 0;
293
294 virtual RequestPingMessage Ping(size_t shard, std::string message, const CommandControl& command_control) = 0;
295
296 virtual void
297 Publish(std::string channel, std::string message, const CommandControl& command_control, PubShard policy) = 0;
298
299 virtual void Spublish(std::string channel, std::string message, const CommandControl& command_control) = 0;
300
301 virtual RequestRename Rename(std::string key, std::string new_key, const CommandControl& command_control) = 0;
302
303 virtual RequestRpop Rpop(std::string key, const CommandControl& command_control) = 0;
304
305 virtual RequestRpush Rpush(std::string key, std::string value, const CommandControl& command_control) = 0;
306
307 virtual RequestRpush
308 Rpush(std::string key, std::vector<std::string> values, const CommandControl& command_control) = 0;
309
310 virtual RequestRpushx Rpushx(std::string key, std::string element, const CommandControl& command_control) = 0;
311
312 /// @brief Add member to a set of elements.
313 ///
314 /// Sample usage:
315 /// @snippet redis/src/storages/redis/client_scan_redistest.cpp Sample Sadd and Sscan usage
316 virtual RequestSadd Sadd(std::string key, std::string member, const CommandControl& command_control) = 0;
317
318 /// @overload
319 virtual RequestSadd
320 Sadd(std::string key, std::vector<std::string> members, const CommandControl& command_control) = 0;
321
322 /// @brief Iterate over a collection of elements.
323 ///
324 /// Sample usage:
325 /// @snippet redis/src/storages/redis/client_scan_redistest.cpp Sample Scan usage
326 virtual RequestScan Scan(size_t shard, ScanOptions options, const CommandControl& command_control) = 0;
327
328 virtual RequestScard Scard(std::string key, const CommandControl& command_control) = 0;
329
330 virtual RequestSet Set(std::string key, std::string value, const CommandControl& command_control) = 0;
331
332 virtual RequestSet
333 Set(std::string key, std::string value, std::chrono::milliseconds ttl, const CommandControl& command_control) = 0;
334
335 virtual RequestSetIfExist SetIfExist(std::string key, std::string value, const CommandControl& command_control) = 0;
336
337 virtual RequestSetIfExist SetIfExist(
338 std::string key,
339 std::string value,
340 std::chrono::milliseconds ttl,
341 const CommandControl& command_control
342 ) = 0;
343
344 virtual RequestSetIfNotExist
345 SetIfNotExist(std::string key, std::string value, const CommandControl& command_control) = 0;
346
347 virtual RequestSetIfNotExist SetIfNotExist(
348 std::string key,
349 std::string value,
350 std::chrono::milliseconds ttl,
351 const CommandControl& command_control
352 ) = 0;
353
354 virtual RequestSetIfNotExistOrGet
355 SetIfNotExistOrGet(std::string key, std::string value, const CommandControl& command_control) = 0;
356
357 virtual RequestSetIfNotExistOrGet SetIfNotExistOrGet(
358 std::string key,
359 std::string value,
360 std::chrono::milliseconds ttl,
361 const CommandControl& command_control
362 ) = 0;
363
364 virtual RequestSetex
365 Setex(std::string key, std::chrono::seconds seconds, std::string value, const CommandControl& command_control) = 0;
366
367 virtual RequestSismember Sismember(std::string key, std::string member, const CommandControl& command_control) = 0;
368
369 // use Sscan in case of a big set
370 virtual RequestSmembers Smembers(std::string key, const CommandControl& command_control) = 0;
371
372 virtual RequestSrandmember Srandmember(std::string key, const CommandControl& command_control) = 0;
373
374 virtual RequestSrandmembers Srandmembers(std::string key, int64_t count, const CommandControl& command_control) = 0;
375
376 virtual RequestSrem Srem(std::string key, std::string member, const CommandControl& command_control) = 0;
377
378 virtual RequestSrem
379 Srem(std::string key, std::vector<std::string> members, const CommandControl& command_control) = 0;
380
381 /// @brief Iterate over a collection of elements.
382 ///
383 /// Sample usage:
384 /// @snippet redis/src/storages/redis/client_scan_redistest.cpp Sample Sadd and Sscan usage
385 virtual RequestSscan Sscan(std::string key, SscanOptions options, const CommandControl& command_control) = 0;
386
387 virtual RequestStrlen Strlen(std::string key, const CommandControl& command_control) = 0;
388
389 virtual RequestTime Time(size_t shard, const CommandControl& command_control) = 0;
390
391 virtual RequestTtl Ttl(std::string key, const CommandControl& command_control) = 0;
392
393 virtual RequestType Type(std::string key, const CommandControl& command_control) = 0;
394
395 virtual RequestZadd
396 Zadd(std::string key, double score, std::string member, const CommandControl& command_control) = 0;
397
398 virtual RequestZadd Zadd(
399 std::string key,
400 double score,
401 std::string member,
402 const ZaddOptions& options,
403 const CommandControl& command_control
404 ) = 0;
405
406 virtual RequestZadd Zadd(
407 std::string key,
408 std::vector<std::pair<double, std::string>> scored_members,
409 const CommandControl& command_control
410 ) = 0;
411
412 virtual RequestZadd Zadd(
413 std::string key,
414 std::vector<std::pair<double, std::string>> scored_members,
415 const ZaddOptions& options,
416 const CommandControl& command_control
417 ) = 0;
418
419 virtual RequestZaddIncr
420 ZaddIncr(std::string key, double score, std::string member, const CommandControl& command_control) = 0;
421
422 virtual RequestZaddIncrExisting
423 ZaddIncrExisting(std::string key, double score, std::string member, const CommandControl& command_control) = 0;
424
425 virtual RequestZcard Zcard(std::string key, const CommandControl& command_control) = 0;
426
427 virtual RequestZcount Zcount(std::string key, double min, double max, const CommandControl& command_control) = 0;
428
429 virtual RequestZrange
430 Zrange(std::string key, int64_t start, int64_t stop, const CommandControl& command_control) = 0;
431
432 virtual RequestZrangeWithScores
433 ZrangeWithScores(std::string key, int64_t start, int64_t stop, const CommandControl& command_control) = 0;
434
435 virtual RequestZrangebyscore
436 Zrangebyscore(std::string key, double min, double max, const CommandControl& command_control) = 0;
437
438 virtual RequestZrangebyscore
439 Zrangebyscore(std::string key, std::string min, std::string max, const CommandControl& command_control) = 0;
440
441 virtual RequestZrangebyscore Zrangebyscore(
442 std::string key,
443 double min,
444 double max,
445 const RangeOptions& range_options,
446 const CommandControl& command_control
447 ) = 0;
448
449 virtual RequestZrangebyscore Zrangebyscore(
450 std::string key,
451 std::string min,
452 std::string max,
453 const RangeOptions& range_options,
454 const CommandControl& command_control
455 ) = 0;
456
457 virtual RequestZrangebyscoreWithScores
458 ZrangebyscoreWithScores(std::string key, double min, double max, const CommandControl& command_control) = 0;
459
460 virtual RequestZrangebyscoreWithScores ZrangebyscoreWithScores(
461 std::string key,
462 std::string min,
463 std::string max,
464 const CommandControl& command_control
465 ) = 0;
466
467 virtual RequestZrangebyscoreWithScores ZrangebyscoreWithScores(
468 std::string key,
469 double min,
470 double max,
471 const RangeOptions& range_options,
472 const CommandControl& command_control
473 ) = 0;
474
475 virtual RequestZrangebyscoreWithScores ZrangebyscoreWithScores(
476 std::string key,
477 std::string min,
478 std::string max,
479 const RangeOptions& range_options,
480 const CommandControl& command_control
481 ) = 0;
482
483 virtual RequestZrem Zrem(std::string key, std::string member, const CommandControl& command_control) = 0;
484
485 virtual RequestZrem
486 Zrem(std::string key, std::vector<std::string> members, const CommandControl& command_control) = 0;
487
488 virtual RequestZremrangebyrank
489 Zremrangebyrank(std::string key, int64_t start, int64_t stop, const CommandControl& command_control) = 0;
490
491 virtual RequestZremrangebyscore
492 Zremrangebyscore(std::string key, double min, double max, const CommandControl& command_control) = 0;
493
494 virtual RequestZremrangebyscore
495 Zremrangebyscore(std::string key, std::string min, std::string max, const CommandControl& command_control) = 0;
496
497 /// @brief Iterate over a collection of elements.
498 ///
499 /// Sample usage:
500 /// @snippet redis/src/storages/redis/client_scan_redistest.cpp Sample Zscan usage
501 virtual RequestZscan Zscan(std::string key, ZscanOptions options, const CommandControl& command_control) = 0;
502
503 virtual RequestZscore Zscore(std::string key, std::string member, const CommandControl& command_control) = 0;
504
505 // end of redis commands
506
507 RequestGet Get(std::string key, RetryNilFromMaster, const CommandControl& command_control);
508
509 RequestHget Hget(std::string key, std::string field, RetryNilFromMaster, const CommandControl& command_control);
510
511 RequestZscore
512 Zscore(std::string key, std::string member, RetryNilFromMaster, const CommandControl& command_control);
513
514 void Publish(std::string channel, std::string message, const CommandControl& command_control);
515
516 RequestScan Scan(size_t shard, const CommandControl& command_control);
517
518 RequestHscan Hscan(std::string key, const CommandControl& command_control);
519
520 RequestSscan Sscan(std::string key, const CommandControl& command_control);
521
522 RequestZscan Zscan(std::string key, const CommandControl& command_control);
523
524protected:
525 virtual RequestEvalCommon EvalCommon(
526 std::string script,
527 std::vector<std::string> keys,
528 std::vector<std::string> args,
529 const CommandControl& command_control
530 ) = 0;
531 virtual RequestEvalShaCommon EvalShaCommon(
532 std::string script_hash,
533 std::vector<std::string> keys,
534 std::vector<std::string> args,
535 const CommandControl& command_control
536 ) = 0;
537 virtual RequestGenericCommon GenericCommon(
538 std::string command,
539 std::vector<std::string> args,
540 size_t key_index,
541 const CommandControl& command_control
542 ) = 0;
543};
544
545std::string CreateTmpKey(const std::string& key, std::string prefix);
546
547} // namespace storages::redis
548
549USERVER_NAMESPACE_END