1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
use core::{fmt, time};
use core::future::Future;
use std::borrow::Cow;

use redis::{Cmd, ToRedisArgs, RedisError, FromRedisValue};
use redis::aio::ConnectionManager;

use crate::types::{idents, RedisType, TimestampId, StreamId, TrimMethod, GroupInfo, PendingStats, EntryValue, PendingEntry, PendingParams, PendingParamsConfig, FetchParams, FetchParamsConfig, FetchResult, FetchEntries};
use crate::iters::{FetchIter, PendingIter};

#[derive(Clone)]
///Queue configuration
pub struct QueueConfig {
    ///Stream name to be used by `Queue`
    pub stream: Cow<'static, str>,
}

#[derive(Clone)]
///Queue
pub struct Queue {
    config: QueueConfig,
    conn: ConnectionManager,
}

impl Queue {
    ///Creates new instance from existing connection
    pub fn new(config: QueueConfig, conn: ConnectionManager) -> Self {
        Self {
            config,
            conn,
        }
    }

    ///Creates command with specified `name` targeting configured `stream`
    fn cmd(&self, name: &str) -> Cmd {
        let mut cmd = Cmd::new();
        cmd.arg(name).arg(self.config.stream.as_ref());
        cmd
    }

    #[inline(always)]
    ///Gets underlying connection
    pub fn connection(&self) -> ConnectionManager {
        self.conn.clone()
    }

    ///Creates group within queue where pending messages are stored.
    ///
    ///User MUST create group before using it.
    ///
    ///If config's `stream` doesn't exist yet, creates it
    pub async fn create_group(&self, group: &str) -> Result<(), RedisError> {
        let mut conn = self.connection();
        let mut cmd = self.cmd(idents::TYPE);
        let typ: RedisType = cmd.query_async(&mut conn).await?;
        match typ {
            //Make sure if key doesn't exist or it is stream, otherwise we should fail immediately
            RedisType::Stream | RedisType::None => (),
            _ => return Err((redis::ErrorKind::ClientError, "key is already used by non-stream type").into()),
        }

        cmd = Cmd::new();
        cmd.arg(idents::XGROUP)
           .arg(idents::CREATE)
           .arg(self.config.stream.as_ref())
           .arg(group)
           .arg("$")
           .arg(idents::MKSTREAM);

        match cmd.query_async(&mut conn).await {
            Ok(()) => Ok(()),
            Err(error) => match error.code() {
                //Group already exists
                Some(idents::BUSYGROUP) => Ok(()),
                _ => Err(error),
            },
        }
    }

    async fn inner_time_ref(conn: &mut ConnectionManager) -> Result<time::Duration, RedisError> {
        let mut cmd = Cmd::new();
        //https://redis.io/commands/time/
        //The TIME command returns the current server time as a two items lists: a Unix timestamp
        //and the amount of microseconds already elapsed in the current second
        cmd.arg(idents::TIME);
        let result: (u64, u64) = cmd.query_async(conn).await?;
        let secs = time::Duration::from_secs(result.0);
        let micros = time::Duration::from_micros(result.1);
        Ok(secs + micros)
    }

    #[inline(always)]
    async fn inner_time(mut conn: ConnectionManager) -> Result<time::Duration, RedisError> {
        Self::inner_time_ref(&mut conn).await
    }

    #[inline(always)]
    ///Returns redis's current time
    pub fn time(&self) -> impl Future<Output = Result<time::Duration, RedisError>> + Send {
        Self::inner_time(self.connection())
    }

    ///Returns number of elements within queue
    pub async fn len(&self) -> Result<usize, RedisError> {
        let mut conn = self.connection();

        let cmd = self.cmd(idents::XLEN);
        cmd.query_async(&mut conn).await
    }

    ///Marks specified `StreamId` as successfully consumed, resulting in corresponding messages' deletion.
    pub async fn consume(&self, group: &str, ids: &[StreamId]) -> Result<usize, RedisError> {
        let mut conn = self.connection();

        let mut cmd = self.cmd(idents::XACK);
        cmd.arg(group).arg(ids);
        cmd.query_async(&mut conn).await
    }

    ///Requests to delete message from the stream.
    pub async fn delete(&self, ids: &[StreamId]) -> Result<usize, RedisError> {
        let mut conn = self.connection();

        let mut cmd = self.cmd(idents::XDEL);
        cmd.arg(ids);
        cmd.query_async(&mut conn).await
    }

    ///Trims elements according to specified `method`
    pub async fn trim(&self, method: TrimMethod) -> Result<u64, RedisError> {
        let mut conn = self.connection();

        let mut cmd = self.cmd(idents::XTRIM);
        cmd.arg(method);
        cmd.query_async(&mut conn).await
    }

    ///Purges whole message stream
    pub async fn purge(&self) -> Result<(), RedisError> {
        let mut conn = self.connection();
        self.cmd("DEL").query_async(&mut conn).await
    }

    ///Retrieves summary of every group existing within stream
    pub async fn groups_info(&self) -> Result<Vec<GroupInfo>, RedisError> {
        let mut conn = self.connection();

        let mut cmd = Cmd::new();
        cmd.arg(idents::XINFO)
           .arg(idents::GROUPS)
           .arg(self.config.stream.as_ref());
        cmd.query_async(&mut conn).await
    }

    ///Retrieves pending messages statistics for `group`
    pub async fn pending_stats(&self, group: &str) -> Result<PendingStats, RedisError> {
        let mut conn = self.connection();

        let mut cmd = self.cmd(idents::XPENDING);
        cmd.arg(&group);

        cmd.query_async(&mut conn).await
    }

    ///Adds item to the queue at the end of queue.
    ///
    ///Returns `StreamId` of newly created item
    pub async fn append<T: ToRedisArgs>(&self, item: &EntryValue<T>) -> Result<StreamId, RedisError> {
        let mut conn = self.connection();

        let mut cmd = self.cmd(idents::XADD);
        cmd.arg("*").arg(item);
        cmd.query_async(&mut conn).await
    }

    ///Adds item to the queue with ID generated from current time plus provided `delay`
    ///
    ///Returns `StreamId` of newly created item
    pub async fn append_delayed<T: ToRedisArgs>(&self, item: &EntryValue<T>, delay: time::Duration) -> Result<StreamId, RedisError> {
        let mut conn = self.connection();
        let now = Self::inner_time_ref(&mut conn).await?.saturating_add(delay);
        let id = TimestampId::new(now);

        let mut cmd = self.cmd(idents::XADD);
        cmd.arg(id).arg(item);
        cmd.query_async(&mut conn).await
    }

    ///Retrieves pending messages within stream.
    pub async fn pending(&self, params: &PendingParams<'_>) -> Result<Vec<PendingEntry>, RedisError> {
        let mut conn = self.connection();

        //Despite its name, `Cmd::arg` can be one or multiple arguments
        //So we can encode everything using ToRedisArgs
        let args = PendingParamsConfig {
            params,
            config: &self.config,
        };
        let mut cmd = Cmd::new();
        cmd.arg(idents::XPENDING).arg(&args);

        cmd.query_async(&mut conn).await
    }

    ///Attempts to fetch message from within queue.
    ///
    ///By new it means messages that are not read yet.
    ///
    ///Once message is read, it is added as pending to group, according to configuration.
    ///
    ///When processing is finished, user must acknowledge ids to remove them from pending group.
    ///Until then these messages can be always re-fetched.
    pub async fn fetch<T: FromRedisValue>(&self, params: &FetchParams<'_>) -> Result<FetchResult<T>, redis::RedisError> {
        let mut conn = self.connection();

        //Despite its name, `Cmd::arg` can be one or multiple arguments
        //So we can encode everything using ToRedisArgs
        let args = FetchParamsConfig {
            params,
            config: &self.config,
        };
        let mut cmd = Cmd::new();
        cmd.arg(idents::XREADGROUP).arg(&args);

        //If there are no messages, it returns NIL so handle it by returning result with empty entires to avoid extra Option indirection
        match cmd.query_async::<_, Option<(FetchResult<T>,)>>(&mut conn).await? {
            Some((res,)) => Ok(res),
            None => Ok(FetchResult {
                stream: args.config.stream.clone().into_owned(),
                entries: Vec::new(),
            }),
        }
    }

    ///Attempts to fetch message from within queue.
    ///
    ///By new it means messages that are not read yet.
    ///
    ///Once message is read, it is added as pending to group, according to configuration.
    ///
    ///When processing is finished, user must acknowledge ids to remove them from pending group.
    ///Until then these messages can be always re-fetched.
    pub async fn fetch_entries<T: FromRedisValue>(&self, params: &FetchParams<'_>) -> Result<FetchEntries<T>, redis::RedisError> {
        let mut conn = self.connection();

        //Despite its name, `Cmd::arg` can be one or multiple arguments
        //So we can encode everything using ToRedisArgs
        let args = FetchParamsConfig {
            params,
            config: &self.config,
        };
        let mut cmd = Cmd::new();
        cmd.arg(idents::XREADGROUP).arg(&args);

        //If there are no messages, it returns NIL so handle it by returning result with empty entires to avoid extra Option indirection
        match cmd.query_async::<_, Option<(FetchEntries<T>,)>>(&mut conn).await? {
            Some((res,)) => Ok(res),
            None => Ok(FetchEntries {
                entries: Vec::new(),
            }),
        }
    }

    #[inline(always)]
    ///Creates new fetch iterator.
    ///
    ///This is just useful utility when there is no need to change `params` at runtime.
    pub fn fetch_iter<'a>(&self, params: FetchParams<'a>) -> FetchIter<'a> {
        FetchIter::new(params, self.clone())
    }

    #[inline(always)]
    ///Creates new pending info iterator.
    ///
    ///This is just useful utility when there is no need to change `params` at runtime.
    pub fn pending_iter<'a>(&self, params: PendingParams<'a>) -> PendingIter<'a> {
        PendingIter::new(params, self.clone())
    }
}

impl fmt::Debug for Queue {
    #[inline]
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt.debug_struct("Queue").field("name", &self.config.stream).finish()
    }
}