Skip to main content

hatchet_client/runs/
filter.rs

1//! Choosing runs by what they are rather than by id.
2
3use 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/// The state of a run, or of one task in it.
12///
13/// Unlike the enums a *declaration* uses, this one is the engine's to grow —
14/// `EVICTED` arrived after the others, and the official Python SDK still
15/// cannot decode it (`sdks/python/hatchet_sdk/clients/admin.py:64-83`). It is
16/// therefore `#[non_exhaustive]`: match with a `_` arm, and a newer engine's
17/// status will not break your build. A status this SDK does not know is
18/// reported as [`Error::UnknownRunStatus`](crate::Error::UnknownRunStatus)
19/// rather than quietly rounded to `Queued`, which is what the official Go
20/// SDK does (`pkg/client/admin.go:136-137`).
21///
22/// ```
23/// use hatchet_client::RunStatus;
24///
25/// let status = RunStatus::Running;
26/// match status {
27///     RunStatus::Completed | RunStatus::Failed | RunStatus::Cancelled => println!("done"),
28///     _ => println!("not done yet: {status}"),
29/// }
30/// ```
31#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
32#[non_exhaustive]
33pub enum RunStatus {
34    /// Accepted, waiting for a worker.
35    Queued,
36    /// A worker is running it.
37    Running,
38    /// Finished, with output.
39    Completed,
40    /// Finished, with an error.
41    Failed,
42    /// Stopped before it finished.
43    Cancelled,
44    /// Taken off its worker; the engine may hand it out again.
45    Evicted,
46}
47
48impl RunStatus {
49    /// The name the engine uses, which is also what a
50    /// [`TasksFilter`] sends.
51    #[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    /// `None` for a value this SDK does not know, which only an engine newer
64    /// than this SDK can send.
65    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/// Which runs a [`cancel_matching`](crate::RunsClient::cancel_matching) or
85/// [`replay_matching`](crate::RunsClient::replay_matching) call acts on.
86///
87/// Every condition set here has to hold. An empty condition is not a
88/// condition: a filter with no statuses matches runs in any state, and a
89/// filter with no `since` matches runs of any age.
90///
91/// **A filter with no narrowing criterion at all — no statuses, no workflow
92/// ids, no metadata — is refused with [`Error::InvalidArgument`] before any
93/// call is made.** `since` and `until` alone do **not** count as narrowing:
94/// left on their own they still let the filter match every run of the whole
95/// tenant that started in the window, which for an old `since` (or none at
96/// all) is effectively everything. Requiring at least one of `statuses`,
97/// `workflow_ids` or `additional_metadata` is this SDK's own rule, not the
98/// engine's — the plain shape is dangerous enough (see the warning on
99/// [`RunsClient::cancel_matching`](crate::RunsClient::cancel_matching)) that
100/// a call which cannot possibly narrow anything is refused rather than sent.
101///
102/// ```
103/// use std::time::{Duration, SystemTime};
104/// use hatchet_client::{RunStatus, TasksFilter};
105///
106/// let last_hour = SystemTime::now() - Duration::from_secs(3600);
107/// let filter = TasksFilter::new()
108///     .since(last_hour)
109///     .statuses([RunStatus::Queued])
110///     .additional_metadata([("customer", "acme")]);
111/// # let _ = filter;
112/// ```
113#[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    /// Ordered, so the same filter makes the same request every time.
120    additional_metadata: BTreeMap<String, String>,
121}
122
123impl TasksFilter {
124    /// An empty filter: add at least one of [`statuses`](TasksFilter::statuses),
125    /// [`workflow_ids`](TasksFilter::workflow_ids) or
126    /// [`additional_metadata`](TasksFilter::additional_metadata) before
127    /// using it — see the type's docs.
128    #[must_use]
129    pub fn new() -> Self {
130        Self::default()
131    }
132
133    /// Also: runs that started at or after `at`. Omitted, runs of any age
134    /// match.
135    #[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    /// Also: runs that started at or before `at`.
142    #[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    /// Also: runs in one of these states. Setting it twice replaces it.
149    #[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    /// Also: runs of these workflows. These are workflow **definition** ids
156    /// (what `PutWorkflow` answers with), not run ids.
157    #[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    /// Also: runs triggered with all of these metadata pairs — the ones a
164    /// [`RunOpts::metadata`](crate::RunOpts::metadata) call set. Setting the
165    /// same key twice keeps the last value.
166    #[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    /// The wire filter, or why it could not be one.
180    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            // The engine's REST filter (the one path the official SDKs
233            // actually exercise) encodes metadata as `"key:value"`
234            // (`sdks/python/hatchet_sdk/clients/v1/api_client.py:22-28`);
235            // the gRPC `TasksFilter.additional_metadata` was measured to
236            // match the same encoding. A key containing `:` is rejected in
237            // `validate`, since the engine could not tell it apart.
238            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    /// The filter sends the engine's own spelling, so the two must never
274    /// drift.
275    #[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    /// Metadata pairs go out in a stable order, so a request is comparable
329    /// between runs (the same reason a worker sorts its actions).
330    #[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}