Skip to main content

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", &params_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", &params_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}