1use std::collections::BTreeMap;
4use std::time::SystemTime;
5
6use hatchet_proto::prost_types::Timestamp;
7use hatchet_proto::v1;
8
9use crate::error::{Error, Result};
10
11#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
32#[non_exhaustive]
33pub enum RunStatus {
34 Queued,
36 Running,
38 Completed,
40 Failed,
42 Cancelled,
44 Evicted,
46}
47
48impl RunStatus {
49 #[must_use]
52 pub fn as_str(self) -> &'static str {
53 match self {
54 Self::Queued => "QUEUED",
55 Self::Running => "RUNNING",
56 Self::Completed => "COMPLETED",
57 Self::Failed => "FAILED",
58 Self::Cancelled => "CANCELLED",
59 Self::Evicted => "EVICTED",
60 }
61 }
62
63 pub(crate) fn from_proto(value: i32) -> Option<Self> {
66 let status = match v1::RunStatus::try_from(value).ok()? {
67 v1::RunStatus::Queued => Self::Queued,
68 v1::RunStatus::Running => Self::Running,
69 v1::RunStatus::Completed => Self::Completed,
70 v1::RunStatus::Failed => Self::Failed,
71 v1::RunStatus::Cancelled => Self::Cancelled,
72 v1::RunStatus::Evicted => Self::Evicted,
73 };
74 Some(status)
75 }
76}
77
78impl std::fmt::Display for RunStatus {
79 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
80 f.write_str(self.as_str())
81 }
82}
83
84#[derive(Clone, Debug, Default)]
114pub struct TasksFilter {
115 since: Option<SystemTime>,
116 until: Option<SystemTime>,
117 statuses: Vec<RunStatus>,
118 workflow_ids: Vec<String>,
119 additional_metadata: BTreeMap<String, String>,
121}
122
123impl TasksFilter {
124 #[must_use]
129 pub fn new() -> Self {
130 Self::default()
131 }
132
133 #[must_use = "this returns the filter to carry on from"]
136 pub fn since(mut self, at: SystemTime) -> Self {
137 self.since = Some(at);
138 self
139 }
140
141 #[must_use = "this returns the filter to carry on from"]
143 pub fn until(mut self, at: SystemTime) -> Self {
144 self.until = Some(at);
145 self
146 }
147
148 #[must_use = "this returns the filter to carry on from"]
150 pub fn statuses(mut self, statuses: impl IntoIterator<Item = RunStatus>) -> Self {
151 self.statuses = statuses.into_iter().collect();
152 self
153 }
154
155 #[must_use = "this returns the filter to carry on from"]
158 pub fn workflow_ids(mut self, ids: impl IntoIterator<Item = impl Into<String>>) -> Self {
159 self.workflow_ids = ids.into_iter().map(Into::into).collect();
160 self
161 }
162
163 #[must_use = "this returns the filter to carry on from"]
167 pub fn additional_metadata(
168 mut self,
169 pairs: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>,
170 ) -> Self {
171 self.additional_metadata.extend(
172 pairs
173 .into_iter()
174 .map(|(key, value)| (key.into(), value.into())),
175 );
176 self
177 }
178
179 pub(crate) fn to_proto(&self) -> Result<v1::TasksFilter> {
181 if self.statuses.is_empty()
182 && self.workflow_ids.is_empty()
183 && self.additional_metadata.is_empty()
184 {
185 return Err(Error::InvalidArgument(
186 "a run filter needs at least one of statuses, workflow_ids or \
187 additional_metadata; `since`/`until` alone would match every run of the \
188 tenant in the window, and a filter this broad is refused rather than sent"
189 .to_string(),
190 ));
191 }
192 if let (Some(since), Some(until)) = (self.since, self.until)
193 && until < since
194 {
195 return Err(Error::InvalidArgument(
196 "a run filter's `until` is before its `since`".to_string(),
197 ));
198 }
199 if let Some(id) = self.workflow_ids.iter().find(|id| id.trim().is_empty()) {
200 return Err(Error::InvalidArgument(format!(
201 "a run filter has a blank workflow id ({id:?})"
202 )));
203 }
204 if let Some((key, _)) = self
205 .additional_metadata
206 .iter()
207 .find(|(key, _)| key.trim().is_empty())
208 {
209 return Err(Error::InvalidArgument(format!(
210 "a run filter has a blank metadata key ({key:?})"
211 )));
212 }
213 if let Some((key, _)) = self
214 .additional_metadata
215 .iter()
216 .find(|(key, _)| key.contains(':'))
217 {
218 return Err(Error::InvalidArgument(format!(
219 "a run filter has a metadata key containing `:` ({key:?}); the wire encodes \
220 each entry as `key:value`, so the engine could not tell where the key ends"
221 )));
222 }
223 Ok(v1::TasksFilter {
224 statuses: self
225 .statuses
226 .iter()
227 .map(|status| status.as_str().to_string())
228 .collect(),
229 since: self.since.map(Timestamp::from),
230 until: self.until.map(Timestamp::from),
231 workflow_ids: self.workflow_ids.clone(),
232 additional_metadata: self
239 .additional_metadata
240 .iter()
241 .map(|(key, value)| format!("{key}:{value}"))
242 .collect(),
243 })
244 }
245}
246
247#[cfg(test)]
248mod tests {
249 use super::*;
250
251 #[test]
252 fn every_status_has_the_protos_own_name() {
253 let pairs = [
254 (RunStatus::Queued, "QUEUED", v1::RunStatus::Queued),
255 (RunStatus::Running, "RUNNING", v1::RunStatus::Running),
256 (RunStatus::Completed, "COMPLETED", v1::RunStatus::Completed),
257 (RunStatus::Failed, "FAILED", v1::RunStatus::Failed),
258 (RunStatus::Cancelled, "CANCELLED", v1::RunStatus::Cancelled),
259 (RunStatus::Evicted, "EVICTED", v1::RunStatus::Evicted),
260 ];
261 for (status, name, wire) in pairs {
262 assert_eq!(status.as_str(), name);
263 assert_eq!(RunStatus::from_proto(wire as i32), Some(status));
264 }
265 }
266
267 #[test]
268 fn an_unknown_wire_status_is_not_guessed_at() {
269 assert_eq!(RunStatus::from_proto(6), None);
270 assert_eq!(RunStatus::from_proto(-1), None);
271 }
272
273 #[test]
276 fn the_status_names_are_the_protos_own() {
277 for status in [
278 RunStatus::Queued,
279 RunStatus::Running,
280 RunStatus::Completed,
281 RunStatus::Failed,
282 RunStatus::Cancelled,
283 RunStatus::Evicted,
284 ] {
285 let wire =
286 v1::RunStatus::from_str_name(status.as_str()).expect("the proto knows this name");
287 assert_eq!(RunStatus::from_proto(wire as i32), Some(status));
288 }
289 }
290
291 #[test]
292 fn an_empty_filter_is_refused() {
293 let error = TasksFilter::new().to_proto().unwrap_err();
294 assert!(matches!(error, Error::InvalidArgument(_)), "{error:?}");
295 }
296
297 #[test]
298 fn since_alone_is_not_narrowing_enough() {
299 let error = TasksFilter::new()
300 .since(std::time::UNIX_EPOCH)
301 .to_proto()
302 .unwrap_err();
303 assert!(matches!(error, Error::InvalidArgument(_)), "{error:?}");
304 }
305
306 #[test]
307 fn a_filter_with_a_status_sends_it_with_the_since() {
308 let filter = TasksFilter::new()
309 .since(std::time::UNIX_EPOCH)
310 .statuses([RunStatus::Running]);
311 let wire = filter.to_proto().unwrap();
312 assert_eq!(wire.since.map(|t| (t.seconds, t.nanos)), Some((0, 0)));
313 assert!(wire.until.is_none());
314 assert_eq!(wire.statuses, vec!["RUNNING".to_string()]);
315 assert!(wire.workflow_ids.is_empty());
316 assert!(wire.additional_metadata.is_empty());
317 }
318
319 #[test]
320 fn a_filter_with_no_since_omits_it() {
321 let wire = TasksFilter::new()
322 .statuses([RunStatus::Running])
323 .to_proto()
324 .unwrap();
325 assert!(wire.since.is_none());
326 }
327
328 #[test]
331 fn metadata_pairs_are_ordered() {
332 let wire = TasksFilter::new()
333 .additional_metadata([("b", "2"), ("a", "1")])
334 .to_proto()
335 .unwrap();
336 assert_eq!(
337 wire.additional_metadata,
338 vec!["a:1".to_string(), "b:2".to_string()]
339 );
340 }
341
342 #[test]
343 fn a_metadata_key_containing_a_colon_is_refused() {
344 let err = TasksFilter::new()
345 .additional_metadata([("a:b", "1")])
346 .to_proto()
347 .unwrap_err();
348 assert!(matches!(err, Error::InvalidArgument(_)), "{err:?}");
349 assert!(err.to_string().contains("a:b"), "{err}");
350 }
351}