Skip to main content

conductor/http/
api_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 reqwest::{Client, Response, StatusCode};
5use serde::{de::DeserializeOwned, Serialize};
6use std::sync::Arc;
7use std::time::{Duration, Instant};
8use tokio::sync::{Mutex, RwLock};
9use tracing::{debug, error, info, warn};
10
11use crate::configuration::Configuration;
12use crate::error::{ConductorError, Result};
13use crate::http::metrics::HttpMetricsObserver;
14
15/// Token response from authentication endpoint.
16#[derive(Debug, serde::Deserialize)]
17struct TokenResponse {
18    token: String,
19}
20
21/// Maximum consecutive auth failures before stopping retry attempts.
22const MAX_AUTH_FAILURES: u32 = 5;
23
24/// Pairs a resolved request path with a bounded-cardinality metric template.
25///
26/// For **static** endpoints (no dynamic segments) simply pass a `&str` —
27/// the [`From<&str>`] impl uses the same string for both the request path
28/// and the metric label.
29///
30/// For **dynamic** endpoints use [`ApiPath::templated`] to supply the
31/// resolved path alongside its template:
32///
33/// ```ignore
34/// let path = format!("/workflow/{}", workflow_id);
35/// api.get(ApiPath::templated(&path, "/workflow/{workflowId}")).await
36/// ```
37pub struct ApiPath<'a> {
38    pub(crate) path: &'a str,
39    pub(crate) metric_uri: &'a str,
40}
41
42impl<'a> ApiPath<'a> {
43    /// Use when the resolved path differs from the metric template.
44    #[must_use]
45    pub fn templated(path: &'a str, template: &'a str) -> Self {
46        Self {
47            path,
48            metric_uri: template,
49        }
50    }
51}
52
53impl<'a> From<&'a str> for ApiPath<'a> {
54    fn from(path: &'a str) -> Self {
55        Self {
56            path,
57            metric_uri: path,
58        }
59    }
60}
61
62/// HTTP API client for Conductor server.
63///
64/// Thread-safe and cloneable. Multiple clones share the same connection pool
65/// and authentication state.
66///
67/// # Authentication
68///
69/// The client automatically handles authentication when credentials are configured:
70/// - Fetches tokens from `/token` endpoint using key/secret
71/// - Proactively refreshes tokens before TTL expiration (default: 45 min)
72/// - Automatically retries requests on 401 after refreshing token
73/// - Gracefully handles OSS Conductor (no auth endpoint returns 404)
74///
75/// # Environment Variables
76///
77/// Configure via environment variables or `.env` file:
78/// - `CONDUCTOR_SERVER_URL`: Server API URL (default: <http://localhost:8080/api>)
79/// - `CONDUCTOR_AUTH_KEY`: Authentication key ID (Orkes Conductor)
80/// - `CONDUCTOR_AUTH_SECRET`: Authentication secret (Orkes Conductor)
81/// - `CONDUCTOR_AUTH_TOKEN_TTL_MINS`: Token TTL in minutes (default: 45)
82/// - `CONDUCTOR_DEBUG`: Enable debug logging (true/false)
83/// - `CONDUCTOR_TIMEOUT_SECS`: Request timeout in seconds (default: 30)
84#[derive(Clone)]
85pub struct ApiClient {
86    client: Client,
87    config: Arc<RwLock<Configuration>>,
88    base_url: String,
89    /// Track consecutive auth failures for backoff.
90    auth_failures: Arc<RwLock<u32>>,
91    /// Last time we attempted token refresh (for backoff).
92    last_refresh_attempt: Arc<RwLock<Option<Instant>>>,
93    /// Mutex to ensure only one token refresh happens at a time.
94    token_refresh_lock: Arc<Mutex<()>>,
95    /// Cached result of OSS detection (None = not yet probed).
96    is_oss: Arc<RwLock<Option<bool>>>,
97    /// HTTP metrics observer. `None` when the client is created standalone
98    /// (without a `TaskHandler`). `Some` after [`set_http_observer`](Self::set_http_observer).
99    http_metrics: Option<Arc<dyn HttpMetricsObserver>>,
100}
101
102impl ApiClient {
103    /// Create a new API client.
104    ///
105    /// The client will automatically handle authentication if credentials are
106    /// configured via `CONDUCTOR_AUTH_KEY` and `CONDUCTOR_AUTH_SECRET` environment
107    /// variables, or via `Configuration::with_auth()`.
108    ///
109    /// # Errors
110    ///
111    /// Returns [`crate::error::ConductorError::Http`] if the underlying `reqwest` client fails to build
112    /// (e.g. TLS backend initialization failure) -- this doesn't make any network request.
113    pub fn new(config: Configuration) -> Result<Self> {
114        let client = Client::builder()
115            .timeout(config.timeout)
116            .connect_timeout(config.connect_timeout)
117            .pool_max_idle_per_host(10)
118            .build()?;
119
120        let base_url = config.server_api_url.trim_end_matches('/').to_owned();
121
122        Ok(Self {
123            client,
124            config: Arc::new(RwLock::new(config)),
125            base_url,
126            auth_failures: Arc::new(RwLock::new(0)),
127            last_refresh_attempt: Arc::new(RwLock::new(None)),
128            token_refresh_lock: Arc::new(Mutex::new(())),
129            is_oss: Arc::new(RwLock::new(None)),
130            http_metrics: None,
131        })
132    }
133
134    /// Get the base URL.
135    #[must_use]
136    pub fn base_url(&self) -> &str {
137        &self.base_url
138    }
139
140    /// Install an HTTP metrics observer on an existing client.
141    ///
142    /// All subsequent clones share the same observer via `Arc`.
143    pub fn set_http_observer(&mut self, observer: Arc<dyn HttpMetricsObserver>) {
144        self.http_metrics = Some(observer);
145    }
146
147    /// Unified post-request bookkeeping: tracing log + observer callback.
148    ///
149    /// `path` is the interpolated request path (for the tracing log).
150    /// `metric_uri` is the bounded-cardinality path template used as the
151    /// `uri` label (e.g. `/tasks/poll/batch/{taskType}`).
152    /// `status_str` is the HTTP status code rendered as a string, or `"0"`
153    /// for pre-response transport errors.
154    #[inline]
155    fn record_request(
156        &self,
157        method: &str,
158        path: &str,
159        metric_uri: &str,
160        status_str: &str,
161        duration: Duration,
162    ) {
163        debug!(
164            method = method,
165            url = %format!("{}{}", self.base_url, path),
166            status = status_str,
167            duration_ms = %duration.as_millis(),
168            "API request completed"
169        );
170        if let Some(obs) = &self.http_metrics {
171            obs.observe(method, metric_uri, status_str, duration);
172        }
173    }
174
175    /// Convenience: call [`record_request`](Self::record_request) with a
176    /// successful response's status code.
177    #[inline]
178    fn record_response(
179        &self,
180        method: &str,
181        path: &str,
182        metric_uri: &str,
183        status: StatusCode,
184        duration: Duration,
185    ) {
186        self.record_request(method, path, metric_uri, status.as_str(), duration);
187    }
188
189    /// Send a prepared request, recording the outcome (success *and* transport
190    /// failures) to the `http_metrics` observer and the `debug!` tracing log.
191    ///
192    /// Transport-level failures (no HTTP status produced) are observed with
193    /// `status = "0"`, matching the convention of the canonical SDK metrics
194    /// harmonization plan.
195    async fn send_observed(
196        &self,
197        method: &str,
198        path: &str,
199        metric_uri: &str,
200        request: reqwest::RequestBuilder,
201    ) -> Result<Response> {
202        let start = Instant::now();
203        let result = request.send().await;
204        let duration = start.elapsed();
205        match &result {
206            Ok(resp) => self.record_response(method, path, metric_uri, resp.status(), duration),
207            Err(_) => self.record_request(method, path, metric_uri, "0", duration),
208        }
209        result.map_err(ConductorError::Http)
210    }
211
212    /// GET request.
213    ///
214    /// # Errors
215    ///
216    /// 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.
217    pub async fn get<T>(&self, path: impl Into<ApiPath<'_>>) -> Result<T>
218    where
219        T: DeserializeOwned,
220    {
221        let p = path.into();
222        self.request::<(), T>(reqwest::Method::GET, p.path, p.metric_uri, None)
223            .await
224    }
225
226    /// GET request returning raw text (for endpoints that respond with
227    /// `text/plain` rather than JSON, e.g. secret values)
228    ///
229    /// # Errors
230    ///
231    /// 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.
232    pub async fn get_text(&self, path: impl Into<ApiPath<'_>>) -> Result<String> {
233        let p = path.into();
234        let url = format!("{}{}", self.base_url, p.path);
235
236        let mut request = self.client.get(&url);
237        request = self.add_auth_header(request).await?;
238
239        let response = self
240            .send_observed("GET", p.path, p.metric_uri, request)
241            .await?;
242        let status = response.status();
243
244        if status.is_success() {
245            Ok(response.text().await?)
246        } else {
247            Err(self.handle_error_response(response).await)
248        }
249    }
250
251    /// GET request with query parameters.
252    ///
253    /// # Errors
254    ///
255    /// 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.
256    pub async fn get_with_params<T>(
257        &self,
258        path: impl Into<ApiPath<'_>>,
259        params: &[(&str, &str)],
260    ) -> Result<T>
261    where
262        T: DeserializeOwned,
263    {
264        let p = path.into();
265        let url = format!("{}{}", self.base_url, p.path);
266
267        let mut request = self.client.get(&url);
268        request = self.add_auth_header(request).await?;
269        request = request.query(params);
270
271        let response = self
272            .send_observed("GET", p.path, p.metric_uri, request)
273            .await?;
274        self.handle_response(response).await
275    }
276
277    /// GET request that returns the raw, unbuffered [`Response`] instead of deserializing it.
278    ///
279    /// For endpoints whose body is consumed incrementally (e.g. Server-Sent Events) rather than
280    /// parsed as a single JSON document. Applies the same auth-header/refresh handling as
281    /// [`get`](Self::get), but does not retry on 401 — a streaming caller has already begun
282    /// reading the body by the time a status past the headers would be observed, so there is no
283    /// safe point to re-issue the request transparently.
284    ///
285    /// # Errors
286    ///
287    /// 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.
288    pub async fn get_stream(&self, path: impl Into<ApiPath<'_>>) -> Result<Response> {
289        let p = path.into();
290        let url = format!("{}{}", self.base_url, p.path);
291
292        let mut request = self.client.get(&url);
293        request = self.add_auth_header(request).await?;
294
295        let response = self
296            .send_observed("GET", p.path, p.metric_uri, request)
297            .await?;
298        let status = response.status();
299
300        if status.is_success() {
301            Ok(response)
302        } else {
303            Err(self.handle_error_response(response).await)
304        }
305    }
306
307    /// POST request.
308    ///
309    /// # Errors
310    ///
311    /// 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.
312    pub async fn post<B, T>(&self, path: impl Into<ApiPath<'_>>, body: &B) -> Result<T>
313    where
314        B: Serialize + ?Sized,
315        T: DeserializeOwned,
316    {
317        let p = path.into();
318        self.request_with_body(reqwest::Method::POST, p.path, p.metric_uri, body)
319            .await
320    }
321
322    /// POST request returning raw text.
323    ///
324    /// # Errors
325    ///
326    /// 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.
327    pub async fn post_text<B>(&self, path: impl Into<ApiPath<'_>>, body: &B) -> Result<String>
328    where
329        B: Serialize,
330    {
331        let p = path.into();
332        let url = format!("{}{}", self.base_url, p.path);
333
334        let mut request = self.client.post(&url);
335        request = self.add_auth_header(request).await?;
336        request = request.json(body);
337
338        let response = self
339            .send_observed("POST", p.path, p.metric_uri, request)
340            .await?;
341        let status = response.status();
342
343        if status.is_success() {
344            Ok(response.text().await?)
345        } else {
346            Err(self.handle_error_response(response).await)
347        }
348    }
349
350    /// PUT request.
351    ///
352    /// # Errors
353    ///
354    /// 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.
355    pub async fn put<B, T>(&self, path: impl Into<ApiPath<'_>>, body: &B) -> Result<T>
356    where
357        B: Serialize + ?Sized,
358        T: DeserializeOwned,
359    {
360        let p = path.into();
361        self.request_with_body(reqwest::Method::PUT, p.path, p.metric_uri, body)
362            .await
363    }
364
365    /// DELETE request.
366    ///
367    /// # Errors
368    ///
369    /// 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.
370    pub async fn delete<T>(&self, path: impl Into<ApiPath<'_>>) -> Result<T>
371    where
372        T: DeserializeOwned,
373    {
374        let p = path.into();
375        self.request::<(), T>(reqwest::Method::DELETE, p.path, p.metric_uri, None)
376            .await
377    }
378
379    /// DELETE request with no response body.
380    ///
381    /// # Errors
382    ///
383    /// 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.
384    pub async fn delete_no_content(&self, path: impl Into<ApiPath<'_>>) -> Result<()> {
385        let p = path.into();
386        let url = format!("{}{}", self.base_url, p.path);
387
388        let mut request = self.client.delete(&url);
389        request = self.add_auth_header(request).await?;
390
391        let response = self
392            .send_observed("DELETE", p.path, p.metric_uri, request)
393            .await?;
394        let status = response.status();
395
396        if status.is_success() || status == StatusCode::NO_CONTENT {
397            Ok(())
398        } else {
399            Err(self.handle_error_response(response).await)
400        }
401    }
402
403    /// DELETE request with body.
404    ///
405    /// # Errors
406    ///
407    /// 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.
408    pub async fn delete_with_body<B>(&self, path: impl Into<ApiPath<'_>>, body: &B) -> Result<()>
409    where
410        B: Serialize + ?Sized,
411    {
412        let p = path.into();
413        let url = format!("{}{}", self.base_url, p.path);
414
415        let mut request = self.client.delete(&url);
416        request = self.add_auth_header(request).await?;
417        request = request.json(body);
418
419        let response = self
420            .send_observed("DELETE", p.path, p.metric_uri, request)
421            .await?;
422        let status = response.status();
423
424        if status.is_success() || status == StatusCode::NO_CONTENT {
425            Ok(())
426        } else {
427            Err(self.handle_error_response(response).await)
428        }
429    }
430
431    /// DELETE request with query parameters.
432    ///
433    /// # Errors
434    ///
435    /// 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.
436    pub async fn delete_with_params(
437        &self,
438        path: impl Into<ApiPath<'_>>,
439        params: &[(&str, &str)],
440    ) -> Result<()> {
441        let p = path.into();
442        let url = format!("{}{}", self.base_url, p.path);
443
444        let mut request = self.client.delete(&url);
445        request = self.add_auth_header(request).await?;
446        request = request.query(params);
447
448        let response = self
449            .send_observed("DELETE", p.path, p.metric_uri, request)
450            .await?;
451        let status = response.status();
452
453        if status.is_success() || status == StatusCode::NO_CONTENT {
454            Ok(())
455        } else {
456            Err(self.handle_error_response(response).await)
457        }
458    }
459
460    /// POST request with no response.
461    ///
462    /// # Errors
463    ///
464    /// 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.
465    pub async fn post_no_response<B>(&self, path: impl Into<ApiPath<'_>>, body: &B) -> Result<()>
466    where
467        B: Serialize + ?Sized,
468    {
469        let p = path.into();
470        let url = format!("{}{}", self.base_url, p.path);
471
472        let mut request = self.client.post(&url);
473        request = self.add_auth_header(request).await?;
474        request = request.json(body);
475
476        let response = self
477            .send_observed("POST", p.path, p.metric_uri, request)
478            .await?;
479        let status = response.status();
480
481        if status.is_success() {
482            Ok(())
483        } else {
484            Err(self.handle_error_response(response).await)
485        }
486    }
487
488    /// POST request with no body.
489    ///
490    /// # Errors
491    ///
492    /// 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.
493    pub async fn post_no_body<T>(&self, path: impl Into<ApiPath<'_>>) -> Result<T>
494    where
495        T: DeserializeOwned,
496    {
497        let p = path.into();
498        let url = format!("{}{}", self.base_url, p.path);
499
500        let mut request = self.client.post(&url);
501        request = self.add_auth_header(request).await?;
502
503        let response = self
504            .send_observed("POST", p.path, p.metric_uri, request)
505            .await?;
506        self.handle_response(response).await
507    }
508
509    /// POST request with no body and no response.
510    ///
511    /// # Errors
512    ///
513    /// 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.
514    pub async fn post_no_body_no_response(&self, path: impl Into<ApiPath<'_>>) -> Result<()> {
515        let p = path.into();
516        let url = format!("{}{}", self.base_url, p.path);
517
518        let mut request = self.client.post(&url);
519        request = self.add_auth_header(request).await?;
520
521        let response = self
522            .send_observed("POST", p.path, p.metric_uri, request)
523            .await?;
524        let status = response.status();
525
526        if status.is_success() {
527            Ok(())
528        } else {
529            Err(self.handle_error_response(response).await)
530        }
531    }
532
533    /// PUT request with no response.
534    ///
535    /// # Errors
536    ///
537    /// 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.
538    pub async fn put_no_response<B>(&self, path: impl Into<ApiPath<'_>>, body: &B) -> Result<()>
539    where
540        B: Serialize + ?Sized,
541    {
542        let p = path.into();
543        let url = format!("{}{}", self.base_url, p.path);
544
545        let mut request = self.client.put(&url);
546        request = self.add_auth_header(request).await?;
547        request = request.json(body);
548
549        let response = self
550            .send_observed("PUT", p.path, p.metric_uri, request)
551            .await?;
552        let status = response.status();
553
554        if status.is_success() {
555            Ok(())
556        } else {
557            Err(self.handle_error_response(response).await)
558        }
559    }
560
561    /// PUT request with no request body and no response body
562    ///
563    /// For endpoints mapped as a bare `@PutMapping` with no `@RequestBody` --
564    /// e.g. `/scheduler/schedules/{name}/pause`. Sends no payload and no
565    /// `Content-Type` at all, rather than a JSON `null`.
566    ///
567    /// # Errors
568    ///
569    /// 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.
570    pub async fn put_no_body(&self, path: impl Into<ApiPath<'_>>) -> Result<()> {
571        let p = path.into();
572        let url = format!("{}{}", self.base_url, p.path);
573
574        let mut request = self.client.put(&url);
575        request = self.add_auth_header(request).await?;
576
577        let response = self
578            .send_observed("PUT", p.path, p.metric_uri, request)
579            .await?;
580        let status = response.status();
581
582        if status.is_success() {
583            Ok(())
584        } else {
585            Err(self.handle_error_response(response).await)
586        }
587    }
588
589    /// PUT request with raw text body.
590    ///
591    /// # Errors
592    ///
593    /// 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.
594    pub async fn put_raw(&self, path: impl Into<ApiPath<'_>>, body: &str) -> Result<()> {
595        let p = path.into();
596        let url = format!("{}{}", self.base_url, p.path);
597
598        let mut request = self.client.put(&url);
599        request = self.add_auth_header(request).await?;
600        request = request.body(body.to_owned());
601        request = request.header("Content-Type", "text/plain");
602
603        let response = self
604            .send_observed("PUT", p.path, p.metric_uri, request)
605            .await?;
606        let status = response.status();
607
608        if status.is_success() {
609            Ok(())
610        } else {
611            Err(self.handle_error_response(response).await)
612        }
613    }
614
615    /// POST request with JSON body and query parameters.
616    ///
617    /// # Errors
618    ///
619    /// 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.
620    pub async fn post_with_params<B, T>(
621        &self,
622        path: impl Into<ApiPath<'_>>,
623        body: &B,
624        params: &[(&str, &str)],
625    ) -> Result<T>
626    where
627        B: Serialize + ?Sized,
628        T: DeserializeOwned,
629    {
630        let p = path.into();
631        let url = format!("{}{}", self.base_url, p.path);
632
633        let mut request = self.client.post(&url);
634        request = self.add_auth_header(request).await?;
635        request = request.query(params);
636        request = request.json(body);
637
638        let response = self
639            .send_observed("POST", p.path, p.metric_uri, request)
640            .await?;
641        self.handle_response(response).await
642    }
643
644    /// POST request with raw text body and query parameters.
645    ///
646    /// # Errors
647    ///
648    /// 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.
649    pub async fn post_raw_with_params(
650        &self,
651        path: impl Into<ApiPath<'_>>,
652        body: &str,
653        params: &[(&str, &str)],
654    ) -> Result<()> {
655        let p = path.into();
656        let url = format!("{}{}", self.base_url, p.path);
657
658        let mut request = self.client.post(&url);
659        request = self.add_auth_header(request).await?;
660        request = request.query(params);
661        request = request.body(body.to_owned());
662        request = request.header("Content-Type", "text/plain");
663
664        let response = self
665            .send_observed("POST", p.path, p.metric_uri, request)
666            .await?;
667        let status = response.status();
668
669        if status.is_success() {
670            Ok(())
671        } else {
672            Err(self.handle_error_response(response).await)
673        }
674    }
675
676    /// PUT request with raw text body and query parameters.
677    ///
678    /// # Errors
679    ///
680    /// 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.
681    pub async fn put_raw_with_params(
682        &self,
683        path: impl Into<ApiPath<'_>>,
684        body: &str,
685        params: &[(&str, &str)],
686    ) -> Result<()> {
687        let p = path.into();
688        let url = format!("{}{}", self.base_url, p.path);
689
690        let mut request = self.client.put(&url);
691        request = self.add_auth_header(request).await?;
692        request = request.query(params);
693        request = request.body(body.to_owned());
694        request = request.header("Content-Type", "text/plain");
695
696        let response = self
697            .send_observed("PUT", p.path, p.metric_uri, request)
698            .await?;
699        let status = response.status();
700
701        if status.is_success() {
702            Ok(())
703        } else {
704            Err(self.handle_error_response(response).await)
705        }
706    }
707
708    /// GET request with no response.
709    ///
710    /// # Errors
711    ///
712    /// 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.
713    pub async fn get_no_response(&self, path: impl Into<ApiPath<'_>>) -> Result<()> {
714        let p = path.into();
715        let url = format!("{}{}", self.base_url, p.path);
716
717        let mut request = self.client.get(&url);
718        request = self.add_auth_header(request).await?;
719
720        let response = self
721            .send_observed("GET", p.path, p.metric_uri, request)
722            .await?;
723        let status = response.status();
724
725        if status.is_success() {
726            Ok(())
727        } else {
728            Err(self.handle_error_response(response).await)
729        }
730    }
731
732    /// Generic request method (no body) with automatic 401 retry.
733    async fn request<B, T>(
734        &self,
735        method: reqwest::Method,
736        path: &str,
737        metric_uri: &str,
738        body: Option<&B>,
739    ) -> Result<T>
740    where
741        B: Serialize,
742        T: DeserializeOwned,
743    {
744        let url = format!("{}{}", self.base_url, path);
745        let method_str = method.as_str().to_owned();
746
747        let mut request = self.client.request(method.clone(), &url);
748        request = self.add_auth_header(request).await?;
749
750        if let Some(b) = body {
751            request = request.json(b);
752        }
753
754        let response = self
755            .send_observed(&method_str, path, metric_uri, request)
756            .await?;
757        let status = response.status();
758
759        // If 401, try refreshing token and retry once
760        if self.is_token_expired_error(status) {
761            debug!(method = %method, url = %url, "Got 401, refreshing token and retrying");
762
763            if self.force_refresh_token().await.is_ok() {
764                let mut request = self.client.request(method.clone(), &url);
765                request = self.add_auth_header(request).await?;
766
767                if let Some(b) = body {
768                    request = request.json(b);
769                }
770
771                let response = self
772                    .send_observed(&method_str, path, metric_uri, request)
773                    .await?;
774                return self.handle_response(response).await;
775            }
776        }
777
778        self.handle_response(response).await
779    }
780
781    /// Generic request method with body (supports slices) with automatic 401 retry.
782    async fn request_with_body<B, T>(
783        &self,
784        method: reqwest::Method,
785        path: &str,
786        metric_uri: &str,
787        body: &B,
788    ) -> Result<T>
789    where
790        B: Serialize + ?Sized,
791        T: DeserializeOwned,
792    {
793        let url = format!("{}{}", self.base_url, path);
794        let method_str = method.as_str().to_owned();
795
796        let mut request = self.client.request(method.clone(), &url);
797        request = self.add_auth_header(request).await?;
798        request = request.json(body);
799
800        let response = self
801            .send_observed(&method_str, path, metric_uri, request)
802            .await?;
803        let status = response.status();
804
805        // If 401, try refreshing token and retry once
806        if self.is_token_expired_error(status) {
807            debug!(method = %method, url = %url, "Got 401, refreshing token and retrying");
808
809            if self.force_refresh_token().await.is_ok() {
810                let mut request = self.client.request(method.clone(), &url);
811                request = self.add_auth_header(request).await?;
812                request = request.json(body);
813
814                let response = self
815                    .send_observed(&method_str, path, metric_uri, request)
816                    .await?;
817                return self.handle_response(response).await;
818            }
819        }
820
821        self.handle_response(response).await
822    }
823
824    /// Handle successful response, deserializing the body.
825    async fn handle_response<T>(&self, response: Response) -> Result<T>
826    where
827        T: DeserializeOwned,
828    {
829        let status = response.status();
830
831        if status.is_success() {
832            // Reset auth failures on successful request
833            *self.auth_failures.write().await = 0;
834
835            let bytes = response.bytes().await.map_err(ConductorError::Http)?;
836            let text = String::from_utf8_lossy(&bytes);
837
838            if text.trim().is_empty() {
839                // Try to deserialize from empty - works for Option<T> or ()
840                serde_json::from_str("null").map_err(ConductorError::Json)
841            } else {
842                serde_json::from_str(&text).map_err(|e| {
843                    error!(body = %text, error = %e, "Failed to parse response");
844                    ConductorError::Json(e)
845                })
846            }
847        } else {
848            Err(self.handle_error_response(response).await)
849        }
850    }
851
852    /// Check if a 401 response indicates an expired/invalid token that should trigger retry.
853    fn is_token_expired_error(&self, status: StatusCode) -> bool {
854        status == StatusCode::UNAUTHORIZED
855    }
856
857    /// Handle error response.
858    async fn handle_error_response(&self, response: Response) -> ConductorError {
859        let status = response.status();
860        let status_code = status.as_u16();
861
862        // Track auth failures for backoff
863        if status == StatusCode::UNAUTHORIZED {
864            let mut failures = self.auth_failures.write().await;
865            *failures += 1;
866            warn!(failures = *failures, "Authentication failure");
867        }
868
869        let message = response
870            .text()
871            .await
872            .unwrap_or_else(|_| "Unknown error".to_owned());
873
874        match status {
875            StatusCode::UNAUTHORIZED => ConductorError::auth(format!("Unauthorized: {message}")),
876            StatusCode::NOT_FOUND => ConductorError::api(format!("Not found: {message}"), None),
877            StatusCode::BAD_REQUEST => ConductorError::api(format!("Bad request: {message}"), None),
878            _ => ConductorError::server(status_code, message),
879        }
880    }
881
882    /// Add authentication header to request.
883    ///
884    /// Uses a mutex to ensure only one token refresh happens at a time,
885    /// preventing thundering herd on token expiration. Also proactively
886    /// refreshes tokens before TTL expiration.
887    async fn add_auth_header(
888        &self,
889        request: reqwest::RequestBuilder,
890    ) -> Result<reqwest::RequestBuilder> {
891        // First check current state (fast path, no lock needed for read)
892        {
893            let config = self.config.read().await;
894
895            // Auth disabled (e.g., OSS Conductor) - return request as-is
896            if config.auth_disabled {
897                return Ok(request);
898            }
899
900            // No auth credentials configured - return request as-is
901            if !config.has_auth() {
902                return Ok(request);
903            }
904
905            // Have a valid token that doesn't need refresh - use it
906            if let Some(ref token) = config.auth_token {
907                if !config.token_needs_refresh() {
908                    return Ok(request.header("X-Authorization", token));
909                }
910            }
911        }
912
913        // Need to refresh token - acquire the refresh lock to prevent concurrent refreshes
914        let _refresh_guard = self.token_refresh_lock.lock().await;
915
916        // Double-check if another thread already refreshed the token while we waited
917        {
918            let config = self.config.read().await;
919            if config.auth_disabled {
920                return Ok(request);
921            }
922            if let Some(ref token) = config.auth_token {
923                if !config.token_needs_refresh() {
924                    return Ok(request.header("X-Authorization", token));
925                }
926            }
927        }
928
929        // Actually refresh the token
930        match self.refresh_token().await {
931            Ok(()) => {}
932            Err(e) => {
933                // Check if auth was disabled during refresh (404 from OSS Conductor)
934                let config = self.config.read().await;
935                if config.auth_disabled {
936                    return Ok(request);
937                }
938                return Err(e);
939            }
940        }
941
942        // Now get the new token
943        let config = self.config.read().await;
944        if let Some(ref token) = config.auth_token {
945            return Ok(request.header("X-Authorization", token));
946        }
947
948        Ok(request)
949    }
950
951    /// Refresh authentication token.
952    ///
953    /// Handles several scenarios:
954    /// - Success: Updates token and resets failure counter
955    /// - 404: OSS Conductor without auth - disables auth for future requests
956    /// - 401: Invalid credentials - increments failure counter with backoff
957    /// - Other errors: Network issues, etc.
958    async fn refresh_token(&self) -> Result<()> {
959        let config = self.config.read().await;
960
961        // Check if auth is disabled
962        if config.auth_disabled {
963            return Ok(());
964        }
965
966        let (key, secret) = match (&config.auth_key, &config.auth_secret) {
967            (Some(k), Some(s)) => (k.clone(), s.clone()),
968            _ => return Ok(()),
969        };
970
971        // Check failure count and apply backoff
972        let failures = *self.auth_failures.read().await;
973        if failures >= MAX_AUTH_FAILURES {
974            error!(
975                failures = failures,
976                max = MAX_AUTH_FAILURES,
977                "Token refresh has failed too many times. Please check your CONDUCTOR_AUTH_KEY and CONDUCTOR_AUTH_SECRET."
978            );
979            return Err(ConductorError::auth(format!(
980                "Token refresh failed {failures} times. Check your authentication credentials."
981            )));
982        }
983
984        // Calculate backoff based on failures (exponential: 1s, 2s, 4s, 8s, 16s)
985        if failures > 0 {
986            // Check time since last attempt
987            if let Some(last_attempt) = *self.last_refresh_attempt.read().await {
988                let backoff = Duration::from_secs(2_u64.pow(failures.min(5)));
989                let elapsed = last_attempt.elapsed();
990
991                if elapsed < backoff {
992                    let remaining = backoff.checked_sub(elapsed).unwrap_or_default();
993                    warn!(
994                        failures = failures,
995                        backoff_secs = backoff.as_secs(),
996                        remaining_secs = remaining.as_secs(),
997                        "Auth backoff active, waiting before retry"
998                    );
999                    tokio::time::sleep(remaining).await;
1000                }
1001            }
1002        }
1003
1004        drop(config); // Release read lock
1005
1006        // Update last refresh attempt time
1007        *self.last_refresh_attempt.write().await = Some(Instant::now());
1008
1009        debug!("Refreshing authentication token");
1010
1011        let url = format!("{}/token", self.base_url);
1012        let body = serde_json::json!({
1013            "keyId": key,
1014            "keySecret": secret
1015        });
1016
1017        let response = match self.client.post(&url).json(&body).send().await {
1018            Ok(resp) => {
1019                debug!(
1020                    method = "POST",
1021                    url = %url,
1022                    status = %resp.status(),
1023                    "Token refresh request completed"
1024                );
1025                resp
1026            }
1027            Err(e) => {
1028                *self.auth_failures.write().await += 1;
1029                error!(error = %e, "Network error during token refresh");
1030                return Err(ConductorError::Http(e));
1031            }
1032        };
1033
1034        let status = response.status();
1035
1036        if status.is_success() {
1037            let token_response: TokenResponse = response.json().await?;
1038            let mut config = self.config.write().await;
1039            config.update_token(token_response.token);
1040            *self.auth_failures.write().await = 0;
1041            debug!("Token refreshed successfully");
1042            Ok(())
1043        } else if status == StatusCode::NOT_FOUND {
1044            // 404 indicates OSS Conductor without authentication endpoint
1045            // Disable auth to prevent future attempts
1046            info!(
1047                "Authentication endpoint /token not found (404). \
1048                Running in open mode without authentication (Conductor OSS)."
1049            );
1050            let mut config = self.config.write().await;
1051            config.disable_auth();
1052            *self.auth_failures.write().await = 0;
1053            *self.is_oss.write().await = Some(true);
1054            Ok(())
1055        } else if status == StatusCode::UNAUTHORIZED {
1056            // 401 from /token endpoint - invalid credentials
1057            let message = response.text().await.unwrap_or_default();
1058            let mut failures = self.auth_failures.write().await;
1059            *failures += 1;
1060            error!(
1061                status = %status,
1062                failures = *failures,
1063                "Authentication failed. Please check your CONDUCTOR_AUTH_KEY and CONDUCTOR_AUTH_SECRET."
1064            );
1065            Err(ConductorError::auth(format!(
1066                "Invalid credentials: {} (attempt {}/{})",
1067                message, *failures, MAX_AUTH_FAILURES
1068            )))
1069        } else {
1070            // Other errors
1071            let message = response.text().await.unwrap_or_default();
1072            *self.auth_failures.write().await += 1;
1073            error!(status = %status, message = %message, "Failed to refresh token");
1074            Err(ConductorError::auth(format!(
1075                "Failed to get token: {status} - {message}"
1076            )))
1077        }
1078    }
1079
1080    /// Force refresh the authentication token.
1081    ///
1082    /// Called when a request fails with 401, indicating the token may have
1083    /// been invalidated server-side before TTL expiration.
1084    ///
1085    /// # Errors
1086    ///
1087    /// 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.
1088    pub async fn force_refresh_token(&self) -> Result<()> {
1089        // Clear current token to force refresh
1090        {
1091            let mut config = self.config.write().await;
1092            config.clear_token();
1093        }
1094
1095        // Acquire lock and refresh
1096        let _refresh_guard = self.token_refresh_lock.lock().await;
1097        self.refresh_token().await
1098    }
1099
1100    /// Check whether the server is OSS Conductor (vs Orkes Enterprise).
1101    ///
1102    /// Probes `POST /token` with dummy credentials on first call and caches
1103    /// the result. OSS Conductor returns 404 (the endpoint does not exist);
1104    /// Enterprise returns a non-404 status (e.g. 401/403 for invalid creds).
1105    ///
1106    /// This mirrors the detection strategy used by the JavaScript SDK.
1107    pub async fn is_oss(&self) -> bool {
1108        // Fast path: already probed
1109        if let Some(cached) = *self.is_oss.read().await {
1110            return cached;
1111        }
1112
1113        // Probe /token
1114        let url = format!("{}/token", self.base_url);
1115        let body = serde_json::json!({"keyId": "probe", "keySecret": "probe"});
1116        let is_oss = match self.client.post(&url).json(&body).send().await {
1117            Ok(resp) => resp.status() == StatusCode::NOT_FOUND,
1118            Err(_) => false,
1119        };
1120
1121        info!(
1122            "Server detection: {} (POST {} \u{2192} {})",
1123            if is_oss { "OSS" } else { "Enterprise" },
1124            url,
1125            if is_oss { "404" } else { "non-404" }
1126        );
1127
1128        *self.is_oss.write().await = Some(is_oss);
1129        is_oss
1130    }
1131
1132    /// Get configuration (for reading settings).
1133    pub async fn get_config(&self) -> Configuration {
1134        self.config.read().await.clone()
1135    }
1136}
1137
1138#[cfg(test)]
1139mod tests {
1140    use super::*;
1141
1142    #[test]
1143    fn test_api_client_creation() {
1144        let config = Configuration::new("http://localhost:8080/api");
1145        let client = ApiClient::new(config);
1146        assert!(client.is_ok());
1147
1148        let client = client.unwrap();
1149        assert_eq!(client.base_url(), "http://localhost:8080/api");
1150    }
1151}