conductor/client/scheduler_client.rs
1// Copyright {{.Year}} Conductor OSS
2// Licensed under the Apache License, Version 2.0. See LICENSE in the project root for license information.
3
4use crate::error::{ConductorError, Result};
5use crate::http::{ApiClient, ApiPath};
6use crate::models::{
7 MetadataTag, SaveScheduleRequest, SearchResultWorkflowScheduleExecution, WorkflowSchedule,
8};
9
10/// Client for managing workflow schedules.
11#[derive(Clone)]
12pub struct SchedulerClient {
13 api: ApiClient,
14}
15
16impl SchedulerClient {
17 /// Create a new scheduler client.
18 #[must_use]
19 pub fn new(api: ApiClient) -> Self {
20 Self { api }
21 }
22
23 /// Save (create or update) a schedule.
24 ///
25 /// # Errors
26 ///
27 /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, or an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status.
28 pub async fn save_schedule(&self, request: &SaveScheduleRequest) -> Result<()> {
29 self.api
30 .post_no_response("/scheduler/schedules", request)
31 .await
32 }
33
34 /// Get a schedule by name.
35 ///
36 /// # Errors
37 ///
38 /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
39 pub async fn get_schedule(&self, name: &str) -> Result<WorkflowSchedule> {
40 let path = format!("/scheduler/schedules/{name}");
41 self.api
42 .get(ApiPath::templated(&path, "/scheduler/schedules/{name}"))
43 .await
44 }
45
46 /// Get all schedules, optionally filtered by workflow name.
47 ///
48 /// # Errors
49 ///
50 /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
51 pub async fn get_all_schedules(
52 &self,
53 workflow_name: Option<&str>,
54 ) -> Result<Vec<WorkflowSchedule>> {
55 if let Some(wf_name) = workflow_name {
56 self.api
57 .get_with_params("/scheduler/schedules", &[("workflowName", wf_name)])
58 .await
59 } else {
60 self.api.get("/scheduler/schedules").await
61 }
62 }
63
64 /// Get next few schedule execution times for a cron expression.
65 ///
66 /// # Errors
67 ///
68 /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
69 pub async fn get_next_few_schedule_execution_times(
70 &self,
71 cron_expression: &str,
72 schedule_start_time: Option<i64>,
73 schedule_end_time: Option<i64>,
74 limit: Option<i32>,
75 ) -> Result<Vec<i64>> {
76 let mut params: Vec<(&str, String)> = vec![("cronExpression", cron_expression.to_owned())];
77
78 if let Some(start) = schedule_start_time {
79 params.push(("scheduleStartTime", start.to_string()));
80 }
81 if let Some(end) = schedule_end_time {
82 params.push(("scheduleEndTime", end.to_string()));
83 }
84 if let Some(l) = limit {
85 params.push(("limit", l.to_string()));
86 }
87
88 let params_ref: Vec<(&str, &str)> = params.iter().map(|(k, v)| (*k, v.as_str())).collect();
89 self.api
90 .get_with_params("/scheduler/nextFewSchedules", ¶ms_ref)
91 .await
92 }
93
94 /// Delete a schedule.
95 ///
96 /// # Errors
97 ///
98 /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, or an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status.
99 pub async fn delete_schedule(&self, name: &str) -> Result<()> {
100 let path = format!("/scheduler/schedules/{name}");
101 self.api
102 .delete_no_content(ApiPath::templated(&path, "/scheduler/schedules/{name}"))
103 .await
104 }
105
106 /// Pause a schedule
107 ///
108 /// Per-schedule pause/resume is `PUT`-mapped on OSS Conductor
109 /// (`scheduler/core/.../rest/SchedulerResource.java` maps only `@PutMapping`).
110 /// Orkes Conductor accepts both `GET` and `PUT` as of the dual
111 /// `@RequestMapping(method = {GET, PUT})` added in 2026-07; deployments older
112 /// than that are `GET`-only. So PUT is tried first and a `405` falls back to
113 /// GET, which covers every server family without an extra probe.
114 ///
115 /// # Errors
116 ///
117 /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, or an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status.
118 pub async fn pause_schedule(&self, name: &str) -> Result<()> {
119 let path = format!("/scheduler/schedules/{name}/pause");
120 let template = "/scheduler/schedules/{name}/pause";
121 match self
122 .api
123 .put_no_body(ApiPath::templated(&path, template))
124 .await
125 {
126 Err(ConductorError::Server { status: 405, .. }) => {
127 self.api
128 .get_no_response(ApiPath::templated(&path, template))
129 .await
130 }
131 result => result,
132 }
133 }
134
135 /// Pause all schedules
136 ///
137 /// `GET`-mapped on both server families (admin/debug endpoint), unlike the
138 /// per-schedule pause/resume calls above -- no PUT is ever sent here.
139 ///
140 /// # Errors
141 ///
142 /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, or an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status.
143 pub async fn pause_all_schedules(&self) -> Result<()> {
144 self.api.get_no_response("/scheduler/admin/pause").await
145 }
146
147 /// Resume a schedule
148 ///
149 /// See [`Self::pause_schedule`] for the PUT-with-GET-fallback rationale.
150 ///
151 /// # Errors
152 ///
153 /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, or an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status.
154 pub async fn resume_schedule(&self, name: &str) -> Result<()> {
155 let path = format!("/scheduler/schedules/{name}/resume");
156 let template = "/scheduler/schedules/{name}/resume";
157 match self
158 .api
159 .put_no_body(ApiPath::templated(&path, template))
160 .await
161 {
162 Err(ConductorError::Server { status: 405, .. }) => {
163 self.api
164 .get_no_response(ApiPath::templated(&path, template))
165 .await
166 }
167 result => result,
168 }
169 }
170
171 /// Resume all schedules
172 ///
173 /// `GET`-mapped on both server families (admin/debug endpoint), unlike the
174 /// per-schedule pause/resume calls above -- no PUT is ever sent here.
175 ///
176 /// # Errors
177 ///
178 /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, or an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status.
179 pub async fn resume_all_schedules(&self) -> Result<()> {
180 self.api.get_no_response("/scheduler/admin/resume").await
181 }
182
183 /// Search schedule executions.
184 ///
185 /// # Errors
186 ///
187 /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
188 pub async fn search_schedule_executions(
189 &self,
190 start: Option<i32>,
191 size: Option<i32>,
192 sort: Option<&str>,
193 free_text: Option<&str>,
194 query: Option<&str>,
195 ) -> Result<SearchResultWorkflowScheduleExecution> {
196 let mut params: Vec<(&str, String)> = Vec::new();
197
198 if let Some(s) = start {
199 params.push(("start", s.to_string()));
200 }
201 if let Some(s) = size {
202 params.push(("size", s.to_string()));
203 }
204 if let Some(s) = sort {
205 params.push(("sort", s.to_owned()));
206 }
207 if let Some(ft) = free_text {
208 params.push(("freeText", ft.to_owned()));
209 }
210 if let Some(q) = query {
211 params.push(("query", q.to_owned()));
212 }
213
214 let params_ref: Vec<(&str, &str)> = params.iter().map(|(k, v)| (*k, v.as_str())).collect();
215 self.api
216 .get_with_params("/scheduler/search/executions", ¶ms_ref)
217 .await
218 }
219
220 /// Requeue all execution records
221 ///
222 /// `GET`-mapped on both server families (admin/debug endpoint), unlike the
223 /// per-schedule pause/resume calls above -- no PUT is ever sent here.
224 ///
225 /// # Errors
226 ///
227 /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, or an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status.
228 pub async fn requeue_all_execution_records(&self) -> Result<()> {
229 self.api.get_no_response("/scheduler/admin/requeue").await
230 }
231
232 /// Set tags for a schedule.
233 ///
234 /// # Errors
235 ///
236 /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, or an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status.
237 pub async fn set_scheduler_tags(&self, tags: &[MetadataTag], name: &str) -> Result<()> {
238 let path = format!("/scheduler/schedules/{name}/tags");
239 self.api
240 .put_no_response(
241 ApiPath::templated(&path, "/scheduler/schedules/{name}/tags"),
242 tags,
243 )
244 .await
245 }
246
247 /// Get tags for a schedule.
248 ///
249 /// # Errors
250 ///
251 /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
252 pub async fn get_scheduler_tags(&self, name: &str) -> Result<Vec<MetadataTag>> {
253 let path = format!("/scheduler/schedules/{name}/tags");
254 self.api
255 .get(ApiPath::templated(
256 &path,
257 "/scheduler/schedules/{name}/tags",
258 ))
259 .await
260 }
261
262 /// Delete tags from a schedule.
263 ///
264 /// # Errors
265 ///
266 /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
267 pub async fn delete_scheduler_tags(&self, tags: &[MetadataTag], name: &str) -> Result<()> {
268 let path = format!("/scheduler/schedules/{name}/tags");
269 self.api
270 .delete_with_body(
271 ApiPath::templated(&path, "/scheduler/schedules/{name}/tags"),
272 tags,
273 )
274 .await
275 }
276}
277
278#[cfg(test)]
279mod tests {
280 use super::*;
281 use crate::Configuration;
282
283 #[test]
284 fn test_scheduler_client_creation() {
285 let config = Configuration::new("http://localhost:8080/api");
286 let api = ApiClient::new(config).unwrap();
287 let _client = SchedulerClient::new(api);
288 }
289}