Skip to main content

conductor/client/
conductor_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::configuration::Configuration;
5use crate::error::Result;
6use crate::events::EventDispatcher;
7use crate::http::ApiClient;
8
9#[cfg(feature = "agents")]
10use super::AgentClient;
11use super::{
12    AuthorizationClient, EventClient, IntegrationClient, MetadataClient, OrkesMetadataClient,
13    PromptClient, SchedulerClient, SchemaClient, SecretClient, TaskClient, WorkflowClient,
14};
15
16/// Main Conductor client combining all API clients.
17///
18/// This is the primary entry point for interacting with the Conductor API.
19/// Also available as the `OrkesClients` alias.
20#[derive(Clone)]
21pub struct ConductorClient {
22    api: ApiClient,
23    /// Shared event dispatcher used by service clients that emit events
24    /// (currently [`WorkflowClient`]). Defaults to an empty dispatcher;
25    /// replace with [`Self::with_event_dispatcher`] to wire up listeners
26    /// such as the metrics collector.
27    events: EventDispatcher,
28}
29
30impl ConductorClient {
31    /// Create a new Conductor client with the given configuration.
32    ///
33    /// # Errors
34    ///
35    /// Returns [`crate::error::ConductorError::Http`] if the underlying `reqwest` client fails to build
36    /// (e.g. TLS backend initialization failure) -- this doesn't make any network request.
37    pub fn new(config: Configuration) -> Result<Self> {
38        let api = ApiClient::new(config)?;
39        Ok(Self {
40            api,
41            events: EventDispatcher::default(),
42        })
43    }
44
45    /// Create from an existing API client.
46    #[must_use]
47    pub fn from_api_client(api: ApiClient) -> Self {
48        Self {
49            api,
50            events: EventDispatcher::default(),
51        }
52    }
53
54    /// Share an [`EventDispatcher`] with this client so that service clients
55    /// (such as [`WorkflowClient`]) publish events to it.
56    ///
57    /// Typically used to route workflow-lifecycle events through the same
58    /// dispatcher as [`TaskHandler`](crate::worker::TaskHandler), allowing a
59    /// single `MetricsCollector` to observe both task- and workflow-level
60    /// metrics.
61    #[must_use]
62    pub fn with_event_dispatcher(mut self, events: EventDispatcher) -> Self {
63        self.events = events;
64        self
65    }
66
67    /// Access the shared event dispatcher.
68    #[must_use]
69    pub fn event_dispatcher(&self) -> &EventDispatcher {
70        &self.events
71    }
72
73    /// Get the task client for polling and updating tasks.
74    #[must_use]
75    pub fn task_client(&self) -> TaskClient {
76        TaskClient::new(self.api.clone())
77    }
78
79    /// Alias for `task_client()`.
80    #[must_use]
81    pub fn get_task_client(&self) -> TaskClient {
82        self.task_client()
83    }
84
85    /// Get the workflow client for workflow operations.
86    #[must_use]
87    pub fn workflow_client(&self) -> WorkflowClient {
88        WorkflowClient::new_with_events(self.api.clone(), self.events.clone())
89    }
90
91    /// Alias for `workflow_client()`.
92    #[must_use]
93    pub fn get_workflow_client(&self) -> WorkflowClient {
94        self.workflow_client()
95    }
96
97    /// Get the metadata client for managing definitions.
98    #[must_use]
99    pub fn metadata_client(&self) -> MetadataClient {
100        MetadataClient::new(self.api.clone())
101    }
102
103    /// Alias for `metadata_client()`.
104    #[must_use]
105    pub fn get_metadata_client(&self) -> MetadataClient {
106        self.metadata_client()
107    }
108
109    /// Get the Orkes metadata client with tagging APIs.
110    ///
111    /// This client extends `MetadataClient` with Orkes-specific features
112    /// like workflow and task tagging. Access base methods via Deref.
113    #[must_use]
114    pub fn orkes_metadata_client(&self) -> OrkesMetadataClient {
115        OrkesMetadataClient::new(self.api.clone())
116    }
117
118    /// Alias for `orkes_metadata_client()`.
119    #[must_use]
120    pub fn get_orkes_metadata_client(&self) -> OrkesMetadataClient {
121        self.orkes_metadata_client()
122    }
123
124    /// Get the scheduler client for managing workflow schedules.
125    #[must_use]
126    pub fn scheduler_client(&self) -> SchedulerClient {
127        SchedulerClient::new(self.api.clone())
128    }
129
130    /// Alias for `scheduler_client()`.
131    #[must_use]
132    pub fn get_scheduler_client(&self) -> SchedulerClient {
133        self.scheduler_client()
134    }
135
136    /// Get the secret client for managing secrets.
137    #[must_use]
138    pub fn secret_client(&self) -> SecretClient {
139        SecretClient::new(self.api.clone())
140    }
141
142    /// Alias for `secret_client()`.
143    #[must_use]
144    pub fn get_secret_client(&self) -> SecretClient {
145        self.secret_client()
146    }
147
148    /// Get the authorization client for users, groups, and permissions.
149    #[must_use]
150    pub fn authorization_client(&self) -> AuthorizationClient {
151        AuthorizationClient::new(self.api.clone())
152    }
153
154    /// Alias for `authorization_client()`.
155    #[must_use]
156    pub fn get_authorization_client(&self) -> AuthorizationClient {
157        self.authorization_client()
158    }
159
160    /// Get the integration client for external system integrations.
161    #[must_use]
162    pub fn integration_client(&self) -> IntegrationClient {
163        IntegrationClient::new(self.api.clone())
164    }
165
166    /// Alias for `integration_client()`.
167    #[must_use]
168    pub fn get_integration_client(&self) -> IntegrationClient {
169        self.integration_client()
170    }
171
172    /// Get the prompt client for AI prompt templates.
173    #[must_use]
174    pub fn prompt_client(&self) -> PromptClient {
175        PromptClient::new(self.api.clone())
176    }
177
178    /// Alias for `prompt_client()`.
179    #[must_use]
180    pub fn get_prompt_client(&self) -> PromptClient {
181        self.prompt_client()
182    }
183
184    /// Get the schema client for schema definitions.
185    #[must_use]
186    pub fn schema_client(&self) -> SchemaClient {
187        SchemaClient::new(self.api.clone())
188    }
189
190    /// Alias for `schema_client()`.
191    #[must_use]
192    pub fn get_schema_client(&self) -> SchemaClient {
193        self.schema_client()
194    }
195
196    /// Get the event client for event queue configurations.
197    #[must_use]
198    pub fn event_client(&self) -> EventClient {
199        EventClient::new(self.api.clone())
200    }
201
202    /// Alias for `event_client()`.
203    #[must_use]
204    pub fn get_event_client(&self) -> EventClient {
205        self.event_client()
206    }
207
208    /// Get the agent client for the Agent Runtime control-plane API (`/agent/*`).
209    ///
210    /// Requires the `agents` Cargo feature.
211    #[cfg(feature = "agents")]
212    #[must_use]
213    pub fn agent_client(&self) -> AgentClient {
214        AgentClient::new(self.api.clone())
215    }
216
217    /// Alias for `agent_client()`.
218    #[cfg(feature = "agents")]
219    #[must_use]
220    pub fn get_agent_client(&self) -> AgentClient {
221        self.agent_client()
222    }
223
224    /// Get the underlying API client.
225    #[must_use]
226    pub fn api_client(&self) -> &ApiClient {
227        &self.api
228    }
229
230    /// Check whether the server is OSS Conductor (vs Orkes Enterprise).
231    ///
232    /// The result is cached after the first call. See [`ApiClient::is_oss`] for
233    /// details on the detection mechanism.
234    pub async fn is_oss(&self) -> bool {
235        self.api.is_oss().await
236    }
237
238    /// Get configuration.
239    pub async fn config(&self) -> Configuration {
240        self.api.get_config().await
241    }
242}
243
244/// Builder for `ConductorClient`.
245pub struct ConductorClientBuilder {
246    config: Configuration,
247}
248
249impl ConductorClientBuilder {
250    /// Create a new builder with default configuration.
251    #[must_use]
252    pub fn new() -> Self {
253        Self {
254            config: Configuration::default(),
255        }
256    }
257
258    /// Create a builder from an existing configuration.
259    #[must_use]
260    pub fn from_config(config: Configuration) -> Self {
261        Self { config }
262    }
263
264    /// Set the server URL.
265    #[must_use]
266    pub fn server_url(mut self, url: impl Into<String>) -> Self {
267        self.config.server_api_url = url.into();
268        self
269    }
270
271    /// Set authentication credentials.
272    #[must_use]
273    pub fn auth(mut self, key: impl Into<String>, secret: impl Into<String>) -> Self {
274        self.config.auth_key = Some(key.into());
275        self.config.auth_secret = Some(secret.into());
276        self
277    }
278
279    /// Enable debug mode.
280    #[must_use]
281    pub fn debug(mut self, enabled: bool) -> Self {
282        self.config.debug = enabled;
283        self
284    }
285
286    /// Build the client.
287    ///
288    /// # Errors
289    ///
290    /// 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.
291    pub fn build(self) -> Result<ConductorClient> {
292        ConductorClient::new(self.config)
293    }
294}
295
296impl Default for ConductorClientBuilder {
297    fn default() -> Self {
298        Self::new()
299    }
300}
301
302#[cfg(test)]
303mod tests {
304    use super::*;
305
306    #[test]
307    fn test_builder() {
308        let client = ConductorClientBuilder::new()
309            .server_url("http://localhost:8080/api")
310            .debug(true)
311            .build();
312
313        client.unwrap();
314    }
315
316    #[test]
317    fn test_client_creation() {
318        let config = Configuration::new("http://localhost:8080/api");
319        let client = ConductorClient::new(config);
320        client.unwrap();
321    }
322}