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