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}