hatchet-client 0.1.0

Rust SDK for Hatchet: run workers and trigger tasks
Documentation
//! Choosing runs by what they are rather than by id.

use std::collections::BTreeMap;
use std::time::SystemTime;

use hatchet_proto::prost_types::Timestamp;
use hatchet_proto::v1;

use crate::error::{Error, Result};

/// The state of a run, or of one task in it.
///
/// Unlike the enums a *declaration* uses, this one is the engine's to grow —
/// `EVICTED` arrived after the others, and the official Python SDK still
/// cannot decode it (`sdks/python/hatchet_sdk/clients/admin.py:64-83`). It is
/// therefore `#[non_exhaustive]`: match with a `_` arm, and a newer engine's
/// status will not break your build. A status this SDK does not know is
/// reported as [`Error::UnknownRunStatus`](crate::Error::UnknownRunStatus)
/// rather than quietly rounded to `Queued`, which is what the official Go
/// SDK does (`pkg/client/admin.go:136-137`).
///
/// ```
/// use hatchet_client::RunStatus;
///
/// let status = RunStatus::Running;
/// match status {
///     RunStatus::Completed | RunStatus::Failed | RunStatus::Cancelled => println!("done"),
///     _ => println!("not done yet: {status}"),
/// }
/// ```
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub enum RunStatus {
    /// Accepted, waiting for a worker.
    Queued,
    /// A worker is running it.
    Running,
    /// Finished, with output.
    Completed,
    /// Finished, with an error.
    Failed,
    /// Stopped before it finished.
    Cancelled,
    /// Taken off its worker; the engine may hand it out again.
    Evicted,
}

impl RunStatus {
    /// The name the engine uses, which is also what a
    /// [`TasksFilter`] sends.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Queued => "QUEUED",
            Self::Running => "RUNNING",
            Self::Completed => "COMPLETED",
            Self::Failed => "FAILED",
            Self::Cancelled => "CANCELLED",
            Self::Evicted => "EVICTED",
        }
    }

    /// `None` for a value this SDK does not know, which only an engine newer
    /// than this SDK can send.
    pub(crate) fn from_proto(value: i32) -> Option<Self> {
        let status = match v1::RunStatus::try_from(value).ok()? {
            v1::RunStatus::Queued => Self::Queued,
            v1::RunStatus::Running => Self::Running,
            v1::RunStatus::Completed => Self::Completed,
            v1::RunStatus::Failed => Self::Failed,
            v1::RunStatus::Cancelled => Self::Cancelled,
            v1::RunStatus::Evicted => Self::Evicted,
        };
        Some(status)
    }
}

impl std::fmt::Display for RunStatus {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

/// Which runs a [`cancel_matching`](crate::RunsClient::cancel_matching) or
/// [`replay_matching`](crate::RunsClient::replay_matching) call acts on.
///
/// Every condition set here has to hold. An empty condition is not a
/// condition: a filter with no statuses matches runs in any state, and a
/// filter with no `since` matches runs of any age.
///
/// **A filter with no narrowing criterion at all — no statuses, no workflow
/// ids, no metadata — is refused with [`Error::InvalidArgument`] before any
/// call is made.** `since` and `until` alone do **not** count as narrowing:
/// left on their own they still let the filter match every run of the whole
/// tenant that started in the window, which for an old `since` (or none at
/// all) is effectively everything. Requiring at least one of `statuses`,
/// `workflow_ids` or `additional_metadata` is this SDK's own rule, not the
/// engine's — the plain shape is dangerous enough (see the warning on
/// [`RunsClient::cancel_matching`](crate::RunsClient::cancel_matching)) that
/// a call which cannot possibly narrow anything is refused rather than sent.
///
/// ```
/// use std::time::{Duration, SystemTime};
/// use hatchet_client::{RunStatus, TasksFilter};
///
/// let last_hour = SystemTime::now() - Duration::from_secs(3600);
/// let filter = TasksFilter::new()
///     .since(last_hour)
///     .statuses([RunStatus::Queued])
///     .additional_metadata([("customer", "acme")]);
/// # let _ = filter;
/// ```
#[derive(Clone, Debug, Default)]
pub struct TasksFilter {
    since: Option<SystemTime>,
    until: Option<SystemTime>,
    statuses: Vec<RunStatus>,
    workflow_ids: Vec<String>,
    /// Ordered, so the same filter makes the same request every time.
    additional_metadata: BTreeMap<String, String>,
}

impl TasksFilter {
    /// An empty filter: add at least one of [`statuses`](TasksFilter::statuses),
    /// [`workflow_ids`](TasksFilter::workflow_ids) or
    /// [`additional_metadata`](TasksFilter::additional_metadata) before
    /// using it — see the type's docs.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Also: runs that started at or after `at`. Omitted, runs of any age
    /// match.
    #[must_use = "this returns the filter to carry on from"]
    pub fn since(mut self, at: SystemTime) -> Self {
        self.since = Some(at);
        self
    }

    /// Also: runs that started at or before `at`.
    #[must_use = "this returns the filter to carry on from"]
    pub fn until(mut self, at: SystemTime) -> Self {
        self.until = Some(at);
        self
    }

    /// Also: runs in one of these states. Setting it twice replaces it.
    #[must_use = "this returns the filter to carry on from"]
    pub fn statuses(mut self, statuses: impl IntoIterator<Item = RunStatus>) -> Self {
        self.statuses = statuses.into_iter().collect();
        self
    }

    /// Also: runs of these workflows. These are workflow **definition** ids
    /// (what `PutWorkflow` answers with), not run ids.
    #[must_use = "this returns the filter to carry on from"]
    pub fn workflow_ids(mut self, ids: impl IntoIterator<Item = impl Into<String>>) -> Self {
        self.workflow_ids = ids.into_iter().map(Into::into).collect();
        self
    }

    /// Also: runs triggered with all of these metadata pairs — the ones a
    /// [`RunOpts::metadata`](crate::RunOpts::metadata) call set. Setting the
    /// same key twice keeps the last value.
    #[must_use = "this returns the filter to carry on from"]
    pub fn additional_metadata(
        mut self,
        pairs: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>,
    ) -> Self {
        self.additional_metadata.extend(
            pairs
                .into_iter()
                .map(|(key, value)| (key.into(), value.into())),
        );
        self
    }

    /// The wire filter, or why it could not be one.
    pub(crate) fn to_proto(&self) -> Result<v1::TasksFilter> {
        if self.statuses.is_empty()
            && self.workflow_ids.is_empty()
            && self.additional_metadata.is_empty()
        {
            return Err(Error::InvalidArgument(
                "a run filter needs at least one of statuses, workflow_ids or \
                 additional_metadata; `since`/`until` alone would match every run of the \
                 tenant in the window, and a filter this broad is refused rather than sent"
                    .to_string(),
            ));
        }
        if let (Some(since), Some(until)) = (self.since, self.until)
            && until < since
        {
            return Err(Error::InvalidArgument(
                "a run filter's `until` is before its `since`".to_string(),
            ));
        }
        if let Some(id) = self.workflow_ids.iter().find(|id| id.trim().is_empty()) {
            return Err(Error::InvalidArgument(format!(
                "a run filter has a blank workflow id ({id:?})"
            )));
        }
        if let Some((key, _)) = self
            .additional_metadata
            .iter()
            .find(|(key, _)| key.trim().is_empty())
        {
            return Err(Error::InvalidArgument(format!(
                "a run filter has a blank metadata key ({key:?})"
            )));
        }
        if let Some((key, _)) = self
            .additional_metadata
            .iter()
            .find(|(key, _)| key.contains(':'))
        {
            return Err(Error::InvalidArgument(format!(
                "a run filter has a metadata key containing `:` ({key:?}); the wire encodes \
                 each entry as `key:value`, so the engine could not tell where the key ends"
            )));
        }
        Ok(v1::TasksFilter {
            statuses: self
                .statuses
                .iter()
                .map(|status| status.as_str().to_string())
                .collect(),
            since: self.since.map(Timestamp::from),
            until: self.until.map(Timestamp::from),
            workflow_ids: self.workflow_ids.clone(),
            // The engine's REST filter (the one path the official SDKs
            // actually exercise) encodes metadata as `"key:value"`
            // (`sdks/python/hatchet_sdk/clients/v1/api_client.py:22-28`);
            // the gRPC `TasksFilter.additional_metadata` was measured to
            // match the same encoding. A key containing `:` is rejected in
            // `validate`, since the engine could not tell it apart.
            additional_metadata: self
                .additional_metadata
                .iter()
                .map(|(key, value)| format!("{key}:{value}"))
                .collect(),
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn every_status_has_the_protos_own_name() {
        let pairs = [
            (RunStatus::Queued, "QUEUED", v1::RunStatus::Queued),
            (RunStatus::Running, "RUNNING", v1::RunStatus::Running),
            (RunStatus::Completed, "COMPLETED", v1::RunStatus::Completed),
            (RunStatus::Failed, "FAILED", v1::RunStatus::Failed),
            (RunStatus::Cancelled, "CANCELLED", v1::RunStatus::Cancelled),
            (RunStatus::Evicted, "EVICTED", v1::RunStatus::Evicted),
        ];
        for (status, name, wire) in pairs {
            assert_eq!(status.as_str(), name);
            assert_eq!(RunStatus::from_proto(wire as i32), Some(status));
        }
    }

    #[test]
    fn an_unknown_wire_status_is_not_guessed_at() {
        assert_eq!(RunStatus::from_proto(6), None);
        assert_eq!(RunStatus::from_proto(-1), None);
    }

    /// The filter sends the engine's own spelling, so the two must never
    /// drift.
    #[test]
    fn the_status_names_are_the_protos_own() {
        for status in [
            RunStatus::Queued,
            RunStatus::Running,
            RunStatus::Completed,
            RunStatus::Failed,
            RunStatus::Cancelled,
            RunStatus::Evicted,
        ] {
            let wire =
                v1::RunStatus::from_str_name(status.as_str()).expect("the proto knows this name");
            assert_eq!(RunStatus::from_proto(wire as i32), Some(status));
        }
    }

    #[test]
    fn an_empty_filter_is_refused() {
        let error = TasksFilter::new().to_proto().unwrap_err();
        assert!(matches!(error, Error::InvalidArgument(_)), "{error:?}");
    }

    #[test]
    fn since_alone_is_not_narrowing_enough() {
        let error = TasksFilter::new()
            .since(std::time::UNIX_EPOCH)
            .to_proto()
            .unwrap_err();
        assert!(matches!(error, Error::InvalidArgument(_)), "{error:?}");
    }

    #[test]
    fn a_filter_with_a_status_sends_it_with_the_since() {
        let filter = TasksFilter::new()
            .since(std::time::UNIX_EPOCH)
            .statuses([RunStatus::Running]);
        let wire = filter.to_proto().unwrap();
        assert_eq!(wire.since.map(|t| (t.seconds, t.nanos)), Some((0, 0)));
        assert!(wire.until.is_none());
        assert_eq!(wire.statuses, vec!["RUNNING".to_string()]);
        assert!(wire.workflow_ids.is_empty());
        assert!(wire.additional_metadata.is_empty());
    }

    #[test]
    fn a_filter_with_no_since_omits_it() {
        let wire = TasksFilter::new()
            .statuses([RunStatus::Running])
            .to_proto()
            .unwrap();
        assert!(wire.since.is_none());
    }

    /// Metadata pairs go out in a stable order, so a request is comparable
    /// between runs (the same reason a worker sorts its actions).
    #[test]
    fn metadata_pairs_are_ordered() {
        let wire = TasksFilter::new()
            .additional_metadata([("b", "2"), ("a", "1")])
            .to_proto()
            .unwrap();
        assert_eq!(
            wire.additional_metadata,
            vec!["a:1".to_string(), "b:2".to_string()]
        );
    }

    #[test]
    fn a_metadata_key_containing_a_colon_is_refused() {
        let err = TasksFilter::new()
            .additional_metadata([("a:b", "1")])
            .to_proto()
            .unwrap_err();
        assert!(matches!(err, Error::InvalidArgument(_)), "{err:?}");
        assert!(err.to_string().contains("a:b"), "{err}");
    }
}