Skip to main content

hatchet_rest/
workflows.rs

1//! Registered workflows: list, find by name, delete (`workflow:list`,
2//! `workflow:delete`).
3
4use serde::Deserialize;
5use serde_json::Value;
6
7use crate::transport::Query;
8use crate::{JsonObject, Operation, Page, ResourceMeta, RestClient, Result};
9
10/// A workflow's tag (`WorkflowTag`).
11#[derive(Clone, Debug, Deserialize)]
12#[non_exhaustive]
13pub struct WorkflowTag {
14    /// The tag.
15    pub name: String,
16    /// Its colour in the dashboard.
17    pub color: String,
18}
19
20/// A registered workflow (`Workflow`).
21#[derive(Clone, Debug, Deserialize)]
22#[serde(rename_all = "camelCase")]
23#[non_exhaustive]
24pub struct Workflow {
25    /// Id and timestamps; `metadata.id` is what [`WorkflowsApi::delete`]
26    /// takes.
27    pub metadata: ResourceMeta,
28    /// The name as registered (lowercased, namespaced).
29    pub name: String,
30    /// The tenant. Both supported engines send `""` in the workflow list.
31    #[serde(default)]
32    pub tenant_id: String,
33    /// Its description.
34    #[serde(default)]
35    pub description: Option<String>,
36    /// Whether it is paused.
37    #[serde(default)]
38    pub is_paused: Option<bool>,
39    /// Its tags.
40    #[serde(default)]
41    pub tags: Vec<WorkflowTag>,
42    /// Its versions, as the engine sends them (`null` when absent, as in
43    /// the list).
44    #[serde(default)]
45    pub versions: Value,
46    /// Its jobs, as the engine sends them (`null` when absent, as in the
47    /// list).
48    #[serde(default)]
49    pub jobs: Value,
50    /// Fields this crate does not model, as the engine sent them.
51    #[serde(flatten)]
52    pub other: JsonObject,
53}
54
55/// Which workflows [`WorkflowsApi::list`] returns. Only the settings given
56/// a value are sent.
57#[derive(Clone, Debug, Default)]
58#[must_use]
59pub struct WorkflowListQuery {
60    offset: Option<i64>,
61    limit: Option<i64>,
62    name: Option<String>,
63}
64
65impl WorkflowListQuery {
66    /// Every workflow (the spec's default page size is 50).
67    pub fn new() -> Self {
68        Self::default()
69    }
70
71    /// Skip this many.
72    pub fn offset(mut self, offset: i64) -> Self {
73        self.offset = Some(offset);
74        self
75    }
76
77    /// At most this many.
78    pub fn limit(mut self, limit: i64) -> Self {
79        self.limit = Some(limit);
80        self
81    }
82
83    /// Search by name, as declared (the client applies its namespace, see
84    /// [`RestClient::workflow_name`]). The engine's search is a substring
85    /// match, not an exact one — `gre` finds `greet`; for an exact match
86    /// use [`WorkflowsApi::find`].
87    pub fn name(mut self, name: impl Into<String>) -> Self {
88        self.name = Some(name.into());
89        self
90    }
91
92    fn query(&self, client: &RestClient) -> Query {
93        let mut query = Query::new();
94        query.push_opt("offset", self.offset);
95        query.push_opt("limit", self.limit);
96        query.push_opt(
97            "name",
98            self.name.as_deref().map(|name| client.workflow_name(name)),
99        );
100        query
101    }
102}
103
104/// Registered workflows; from [`RestClient::workflows`].
105#[derive(Clone, Copy, Debug)]
106pub struct WorkflowsApi<'a> {
107    pub(crate) client: &'a RestClient,
108}
109
110impl WorkflowsApi<'_> {
111    /// Lists workflows (`workflow:list`).
112    ///
113    /// ```no_run
114    /// # async fn example(rest: hatchet_rest::RestClient) -> hatchet_rest::Result<()> {
115    /// use hatchet_rest::WorkflowListQuery;
116    ///
117    /// let page = rest.workflows().list(WorkflowListQuery::new().limit(100)).await?;
118    /// for workflow in &page.rows {
119    ///     println!("{} ({})", workflow.name, workflow.metadata.id);
120    /// }
121    /// # Ok(())
122    /// # }
123    /// ```
124    ///
125    /// # Errors
126    ///
127    /// As for any call (see [`Error`](crate::Error)).
128    pub async fn list(&self, query: WorkflowListQuery) -> Result<Page<Workflow>> {
129        self.client
130            .inner
131            .call(Operation::WorkflowList, &[], query.query(self.client))
132            .await
133    }
134
135    /// The workflow registered as `name` (as declared; the client applies
136    /// its namespace), or `None`. Searches with `workflow:list?name=` and
137    /// keeps only an **exact** match of the registered name — the official
138    /// Go SDK takes the first row of the search
139    /// (`sdks/go/features/workflows.go`), which for `greet` can be
140    /// `greeter`. Only the first page of the search (the engine's default
141    /// page size) is looked at.
142    ///
143    /// ```no_run
144    /// # async fn example(rest: hatchet_rest::RestClient) -> hatchet_rest::Result<()> {
145    /// if let Some(workflow) = rest.workflows().find("nightly-report").await? {
146    ///     rest.workflows().delete(&workflow.metadata.id).await?;
147    /// }
148    /// # Ok(())
149    /// # }
150    /// ```
151    ///
152    /// # Errors
153    ///
154    /// As for any call (see [`Error`](crate::Error)).
155    pub async fn find(&self, name: &str) -> Result<Option<Workflow>> {
156        let wanted = self.client.workflow_name(name);
157        let page = self.list(WorkflowListQuery::new().name(name)).await?;
158        Ok(page
159            .rows
160            .into_iter()
161            .find(|workflow| workflow.name == wanted))
162    }
163
164    /// Deletes a workflow by id (`workflow:delete`). Both supported engines
165    /// answer `204`; any 2xx is success (the official Go SDK treats only
166    /// `200` as success). Sent once, never retried.
167    ///
168    /// # Errors
169    ///
170    /// [`Error::InvalidArgument`](crate::Error::InvalidArgument) for an
171    /// empty id, before anything is sent; otherwise as for any call (see
172    /// [`Error`](crate::Error)).
173    pub async fn delete(&self, workflow_id: &str) -> Result<()> {
174        self.client
175            .inner
176            .call_unit(Operation::WorkflowDelete, &[workflow_id])
177            .await
178    }
179}
180
181impl RestClient {
182    /// Registered workflows: `list`, `find`, `delete`.
183    pub fn workflows(&self) -> WorkflowsApi<'_> {
184        WorkflowsApi { client: self }
185    }
186}