Skip to main content

gitfox_client/
client.rs

1//! The HTTP client every other module and both front-ends (CLI, and later MCP)
2//! go through.
3
4use std::fmt;
5use std::time::{Duration, SystemTime, UNIX_EPOCH};
6
7use reqwest::header::{ACCEPT, AUTHORIZATION, CONTENT_TYPE, HeaderMap, HeaderName, HeaderValue};
8use serde::de::DeserializeOwned;
9use serde_json::Value;
10use url::Url;
11use url::form_urlencoded;
12
13use crate::auth::AuthApi;
14use crate::error::{Error, Result};
15use crate::pipeline::PipelinesApi;
16use crate::principal::PrincipalsApi;
17use crate::pull_request::PullRequestsApi;
18use crate::repo::ReposApi;
19
20pub use reqwest::Method;
21
22pub const DEFAULT_TIMEOUT_SECS: u64 = 30;
23
24/// Attempts after the first, for requests that are safe to repeat.
25pub const DEFAULT_RETRIES: u32 = 2;
26
27/// The longest we will wait between attempts, including a server's own
28/// `Retry-After`.
29///
30/// Someone is usually watching a CLI run. A command that goes silent for
31/// minutes because a header asked it to is worse than one that gives up and
32/// says why — the caller can always run it again, and an agent can back off on
33/// its own schedule.
34const MAX_BACKOFF: Duration = Duration::from_secs(5);
35
36const USER_AGENT: &str = concat!("fx/", env!("CARGO_PKG_VERSION"));
37
38/// A GitFox API client bound to one host.
39#[derive(Clone)]
40pub struct GitFoxClient {
41    base_url: Url,
42    token: Option<String>,
43    timeout_secs: u64,
44    retries: u32,
45    http: reqwest::Client,
46}
47
48/// Redacted on purpose: the token must never reach a log line or an error
49/// message. Every `{:?}` of a client or anything holding one goes through here.
50impl fmt::Debug for GitFoxClient {
51    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
52        f.debug_struct("GitFoxClient")
53            .field("base_url", &self.base_url.as_str())
54            .field("token", &self.token.as_ref().map(|_| "***"))
55            .field("timeout_secs", &self.timeout_secs)
56            .field("retries", &self.retries)
57            .finish()
58    }
59}
60
61impl GitFoxClient {
62    pub fn builder(host: impl Into<String>) -> GitFoxClientBuilder {
63        GitFoxClientBuilder {
64            host: host.into(),
65            token: None,
66            timeout_secs: DEFAULT_TIMEOUT_SECS,
67            retries: DEFAULT_RETRIES,
68            insecure: false,
69        }
70    }
71
72    pub fn base_url(&self) -> &Url {
73        &self.base_url
74    }
75
76    pub fn has_token(&self) -> bool {
77        self.token.is_some()
78    }
79
80    pub fn auth(&self) -> AuthApi<'_> {
81        AuthApi::new(self)
82    }
83
84    pub fn repos(&self) -> ReposApi<'_> {
85        ReposApi::new(self)
86    }
87
88    pub fn pull_requests(&self) -> PullRequestsApi<'_> {
89        PullRequestsApi::new(self)
90    }
91
92    pub fn principals(&self) -> PrincipalsApi<'_> {
93        PrincipalsApi::new(self)
94    }
95
96    pub fn pipelines(&self) -> PipelinesApi<'_> {
97        PipelinesApi::new(self)
98    }
99
100    /// Resolve an API path against the host.
101    ///
102    /// Accepts `/api/v1/user`, `api/v1/user` and a fully qualified URL, so
103    /// `fx api` can take whatever the user pasted.
104    pub fn resolve(&self, path: &str) -> Result<Url> {
105        if path.starts_with("http://") || path.starts_with("https://") {
106            return Url::parse(path).map_err(|e| Error::InvalidUrl(format!("{path}: {e}")));
107        }
108        self.base_url
109            .join(path.trim_start_matches('/'))
110            .map_err(|e| Error::InvalidUrl(format!("{path}: {e}")))
111    }
112
113    /// The one place an HTTP request is issued. Everything typed is built on top.
114    ///
115    /// Transient failures are retried with exponential backoff — but only for
116    /// methods that are safe to repeat. See [`is_retryable_method`].
117    pub async fn request(
118        &self,
119        method: Method,
120        path: &str,
121        body: Option<&Value>,
122        extra_headers: &[(String, String)],
123    ) -> Result<RawResponse> {
124        let url = self.resolve(path)?;
125        let budget = if is_retryable_method(&method) {
126            self.retries
127        } else {
128            0
129        };
130
131        let mut attempt = 0;
132        loop {
133            tracing::debug!(method = %method, url = %url, attempt, "gitfox request");
134            let outcome = self
135                .attempt(method.clone(), url.clone(), body, extra_headers)
136                .await;
137
138            let Err(error) = outcome else {
139                return outcome;
140            };
141
142            let Some(delay) = self.backoff(&error, attempt, budget) else {
143                return Err(error);
144            };
145            tracing::warn!(
146                method = %method,
147                url = %url,
148                attempt,
149                delay_ms = delay.as_millis(),
150                error = %error,
151                "transient failure; retrying"
152            );
153            tokio::time::sleep(delay).await;
154            attempt += 1;
155        }
156    }
157
158    /// One trip to the server, with no retry logic of its own.
159    async fn attempt(
160        &self,
161        method: Method,
162        url: Url,
163        body: Option<&Value>,
164        extra_headers: &[(String, String)],
165    ) -> Result<RawResponse> {
166        let mut req = self.http.request(method, url);
167        // JSON unless the caller asked for something else. The pull request
168        // diff endpoint serves either JSON or a raw unified diff depending on
169        // this header, which is the whole reason it is overridable.
170        if !extra_headers
171            .iter()
172            .any(|(name, _)| name.eq_ignore_ascii_case("accept"))
173        {
174            req = req.header(ACCEPT, "application/json");
175        }
176        if let Some(token) = &self.token {
177            let mut value = HeaderValue::from_str(&format!("Bearer {token}"))
178                .map_err(|_| Error::Builder("token contains invalid header bytes".into()))?;
179            // Marks the header sensitive so it stays out of any logging that
180            // honours the flag.
181            value.set_sensitive(true);
182            req = req.header(AUTHORIZATION, value);
183        }
184        for (name, value) in extra_headers {
185            let name = HeaderName::from_bytes(name.as_bytes())
186                .map_err(|_| Error::Builder(format!("invalid header name `{name}`")))?;
187            let value = HeaderValue::from_str(value)
188                .map_err(|_| Error::Builder(format!("invalid value for header `{name}`")))?;
189            req = req.header(name, value);
190        }
191        if let Some(body) = body {
192            req = req.header(CONTENT_TYPE, "application/json").json(body);
193        }
194
195        let response = req.send().await.map_err(|e| self.transport_error(&e))?;
196        let status = response.status();
197        let headers = response.headers().clone();
198        let text = response
199            .text()
200            .await
201            .map_err(|e| self.transport_error(&e))?;
202        let json = if text.trim().is_empty() {
203            None
204        } else {
205            serde_json::from_str::<Value>(&text).ok()
206        };
207
208        let raw = RawResponse {
209            status: status.as_u16(),
210            headers,
211            json,
212            text,
213        };
214
215        if status.is_success() {
216            Ok(raw)
217        } else {
218            Err(self.status_error(&raw))
219        }
220    }
221
222    /// How long to wait before trying again, or `None` to give up.
223    ///
224    /// A server that said `Retry-After` is obeyed up to [`MAX_BACKOFF`];
225    /// otherwise the delay doubles each attempt from 250ms, with jitter so a
226    /// fleet of agents retrying at once does not do so in lockstep.
227    fn backoff(&self, error: &Error, attempt: u32, budget: u32) -> Option<Duration> {
228        if attempt >= budget || !is_transient(error) {
229            return None;
230        }
231        if let Error::RateLimited { retry_after, .. } = error
232            && let Some(secs) = retry_after
233        {
234            return Some(Duration::from_secs(*secs).min(MAX_BACKOFF));
235        }
236        let base = Duration::from_millis(250 * 2u64.pow(attempt.min(6)));
237        Some((base + jitter(base)).min(MAX_BACKOFF))
238    }
239
240    /// Read a server-sent-event stream, collecting each `data:` payload that
241    /// deserialises into `T`.
242    ///
243    /// Stops on the stream's own `event: error` / `data: eof`, or once `idle`
244    /// passes with no new bytes — a stream following something still in
245    /// progress never ends on its own, so a snapshot has to decide when the
246    /// backlog has been drained.
247    ///
248    /// The client's request timeout is deliberately not applied: it bounds a
249    /// whole request/response, which for a stream would cut the body off
250    /// mid-flight. The idle window bounds this instead.
251    pub async fn sse_lines<T: DeserializeOwned>(
252        &self,
253        path: &str,
254        idle: Duration,
255    ) -> Result<Vec<T>> {
256        let url = self.resolve(path)?;
257        tracing::debug!(url = %url, "gitfox log stream");
258
259        let mut req = self
260            .http
261            .get(url)
262            .header(ACCEPT, "text/event-stream")
263            .timeout(Duration::from_secs(60 * 60));
264        if let Some(token) = &self.token {
265            let mut value = HeaderValue::from_str(&format!("Bearer {token}"))
266                .map_err(|_| Error::Builder("token contains invalid header bytes".into()))?;
267            value.set_sensitive(true);
268            req = req.header(AUTHORIZATION, value);
269        }
270
271        let mut response = req.send().await.map_err(|e| self.transport_error(&e))?;
272        // An SSE endpoint answers 200 and reports failure inside the stream, so
273        // a non-success status here is a genuine transport-level refusal.
274        if !response.status().is_success() {
275            let status = response.status().as_u16();
276            let text = response.text().await.unwrap_or_default();
277            let json = serde_json::from_str::<Value>(&text).ok();
278            return Err(self.status_error(&RawResponse {
279                status,
280                headers: HeaderMap::new(),
281                json,
282                text,
283            }));
284        }
285
286        let mut collected = Vec::new();
287        let mut buffer = Vec::new();
288        let mut last_event: Option<String> = None;
289
290        loop {
291            let chunk = match tokio::time::timeout(idle, response.chunk()).await {
292                // Nothing new for a while: the backlog is drained.
293                Err(_) => break,
294                Ok(Ok(Some(chunk))) => chunk,
295                Ok(Ok(None)) => break,
296                Ok(Err(e)) => return Err(self.transport_error(&e)),
297            };
298            buffer.extend_from_slice(&chunk);
299
300            while let Some(newline) = buffer.iter().position(|b| *b == b'\n') {
301                let line = buffer.drain(..=newline).collect::<Vec<u8>>();
302                let line = String::from_utf8_lossy(&line);
303                let line = line.trim_end_matches(['\r', '\n']);
304
305                if let Some(name) = line.strip_prefix("event:") {
306                    last_event = Some(name.trim().to_string());
307                    continue;
308                }
309                let Some(payload) = line.strip_prefix("data:") else {
310                    // `: ping` keepalives and blank separators.
311                    continue;
312                };
313                let payload = payload.trim();
314                if last_event.as_deref() == Some("error") {
315                    // `data: eof` is the ordinary end of a finished step's
316                    // stream, not a failure worth surfacing.
317                    return Ok(collected);
318                }
319                if let Ok(value) = serde_json::from_str::<T>(payload) {
320                    collected.push(value);
321                }
322            }
323        }
324        Ok(collected)
325    }
326
327    /// Convenience wrapper for typed GET requests.
328    pub async fn get_json<T: DeserializeOwned>(&self, path: &str) -> Result<T> {
329        self.request(Method::GET, path, None, &[])
330            .await?
331            .deserialize()
332    }
333
334    fn transport_error(&self, err: &reqwest::Error) -> Error {
335        if err.is_timeout() {
336            Error::Timeout(self.timeout_secs)
337        } else if err.is_decode() {
338            Error::Decode(err.to_string())
339        } else {
340            Error::Network(err.to_string())
341        }
342    }
343
344    fn status_error(&self, raw: &RawResponse) -> Error {
345        let fallback = if raw.text.trim().is_empty() {
346            format!("HTTP {}", raw.status)
347        } else {
348            raw.text.trim().chars().take(500).collect()
349        };
350        let message = Error::message_from_body(&raw.json, &fallback);
351        match raw.status {
352            429 => Error::RateLimited {
353                retry_after: raw
354                    .headers
355                    .get("retry-after")
356                    .and_then(|v| v.to_str().ok())
357                    .and_then(|v| v.trim().parse::<u64>().ok()),
358                message,
359            },
360            401 if self.token.is_none() => Error::AuthRequired,
361            401 | 403 => Error::AuthFailed,
362            404 => Error::NotFound {
363                kind: "resource",
364                reference: message,
365            },
366            408 | 504 => Error::Timeout(self.timeout_secs),
367            status => Error::Api {
368                status,
369                message,
370                body: raw.json.clone(),
371            },
372        }
373    }
374}
375
376/// A response that succeeded at the HTTP level, kept in both raw and parsed form
377/// so `fx api` can pass anything through untouched.
378#[derive(Debug, Clone)]
379pub struct RawResponse {
380    pub status: u16,
381    pub headers: HeaderMap,
382    pub json: Option<Value>,
383    pub text: String,
384}
385
386impl RawResponse {
387    pub fn json_or_null(&self) -> Value {
388        self.json.clone().unwrap_or(Value::Null)
389    }
390
391    pub fn deserialize<T: DeserializeOwned>(&self) -> Result<T> {
392        let value = self
393            .json
394            .clone()
395            .ok_or_else(|| Error::Decode("expected a JSON response body".into()))?;
396        serde_json::from_value(value).map_err(|e| Error::Decode(e.to_string()))
397    }
398}
399
400pub struct GitFoxClientBuilder {
401    host: String,
402    token: Option<String>,
403    timeout_secs: u64,
404    retries: u32,
405    insecure: bool,
406}
407
408impl GitFoxClientBuilder {
409    pub fn token(mut self, token: Option<String>) -> Self {
410        self.token = token.filter(|t| !t.trim().is_empty());
411        self
412    }
413
414    pub fn timeout_secs(mut self, secs: u64) -> Self {
415        self.timeout_secs = secs;
416        self
417    }
418
419    /// How many times to try again after a transient failure. Zero disables
420    /// retrying entirely.
421    pub fn retries(mut self, retries: u32) -> Self {
422        self.retries = retries;
423        self
424    }
425
426    /// Skip TLS verification. Self-hosted instances with private CAs need it;
427    /// callers are expected to warn the user loudly when they turn it on.
428    pub fn insecure(mut self, insecure: bool) -> Self {
429        self.insecure = insecure;
430        self
431    }
432
433    pub fn build(self) -> Result<GitFoxClient> {
434        let base_url = normalize_host(&self.host)?;
435        let http = reqwest::Client::builder()
436            .user_agent(USER_AGENT)
437            .timeout(Duration::from_secs(self.timeout_secs))
438            .danger_accept_invalid_certs(self.insecure)
439            .build()
440            .map_err(|e| Error::Builder(e.to_string()))?;
441        Ok(GitFoxClient {
442            base_url,
443            token: self.token,
444            timeout_secs: self.timeout_secs,
445            retries: self.retries,
446            http,
447        })
448    }
449}
450
451/// Turn whatever the user configured into a base URL that `Url::join` behaves
452/// well against: `git.example.com` -> `https://git.example.com/`.
453pub fn normalize_host(host: &str) -> Result<Url> {
454    let host = host.trim();
455    if host.is_empty() {
456        return Err(Error::InvalidUrl("host is empty".into()));
457    }
458    let with_scheme = if host.contains("://") {
459        host.to_string()
460    } else {
461        format!("https://{host}")
462    };
463    let mut url =
464        Url::parse(&with_scheme).map_err(|e| Error::InvalidUrl(format!("{host}: {e}")))?;
465    if url.cannot_be_a_base() || url.host_str().is_none() {
466        return Err(Error::InvalidUrl(format!("{host}: missing host")));
467    }
468    if !url.path().ends_with('/') {
469        let path = format!("{}/", url.path());
470        url.set_path(&path);
471    }
472    Ok(url)
473}
474
475/// Whether repeating this method is safe.
476///
477/// `POST` is excluded on purpose. A retried `POST /pullreq` that timed out
478/// after the server accepted it would open a second pull request — silently
479/// doing the thing twice is worse than reporting that it might not have
480/// happened at all. `PATCH` is excluded for the same reason: GitFox uses it for
481/// partial updates, which are not guaranteed idempotent.
482pub fn is_retryable_method(method: &Method) -> bool {
483    matches!(
484        *method,
485        Method::GET | Method::HEAD | Method::OPTIONS | Method::PUT | Method::DELETE
486    )
487}
488
489/// Whether this failure is worth another try.
490///
491/// Deliberately narrow: a 500 is not here, because an internal error that
492/// repeats is usually a bug being hit again rather than a blip, and retrying it
493/// just triples the time before the user sees the message.
494fn is_transient(error: &Error) -> bool {
495    match error {
496        Error::Network(_) | Error::Timeout(_) | Error::RateLimited { .. } => true,
497        Error::Api { status, .. } => matches!(status, 502..=504),
498        _ => false,
499    }
500}
501
502/// Up to half the base delay, derived from the clock rather than a PRNG so the
503/// crate keeps no random-number dependency.
504fn jitter(base: Duration) -> Duration {
505    let nanos = SystemTime::now()
506        .duration_since(UNIX_EPOCH)
507        .map(|d| d.subsec_nanos() as u64)
508        .unwrap_or(0);
509    Duration::from_millis((base.as_millis() as u64 / 2).saturating_mul(nanos % 1000) / 1000)
510}
511
512/// A percent-encoded query string.
513///
514/// Kept here rather than in each endpoint module so every request encodes the
515/// same way, and so `Option` parameters can be dropped without an `if` at each
516/// call site.
517#[derive(Debug, Default, Clone)]
518pub struct Query(Vec<(String, String)>);
519
520impl Query {
521    pub fn new() -> Self {
522        Self::default()
523    }
524
525    pub fn push(&mut self, key: &str, value: impl ToString) -> &mut Self {
526        self.0.push((key.to_string(), value.to_string()));
527        self
528    }
529
530    /// Append only when the value is present, so unset filters never reach the
531    /// server as empty strings (which GitFox treats as a real filter).
532    pub fn push_opt<T: ToString>(&mut self, key: &str, value: Option<T>) -> &mut Self {
533        if let Some(value) = value {
534            self.push(key, value);
535        }
536        self
537    }
538
539    pub fn extend<T: ToString>(
540        &mut self,
541        key: &str,
542        values: impl IntoIterator<Item = T>,
543    ) -> &mut Self {
544        for value in values {
545            self.push(key, value);
546        }
547        self
548    }
549
550    pub fn is_empty(&self) -> bool {
551        self.0.is_empty()
552    }
553
554    pub fn encode(&self) -> String {
555        form_urlencoded::Serializer::new(String::new())
556            .extend_pairs(self.0.iter().map(|(k, v)| (k.as_str(), v.as_str())))
557            .finish()
558    }
559
560    /// `path?a=1&b=2`, or `path` when there is nothing to add.
561    pub fn apply(&self, path: &str) -> String {
562        if self.is_empty() {
563            return path.to_string();
564        }
565        format!("{path}?{}", self.encode())
566    }
567}
568
569#[cfg(test)]
570mod tests {
571    use super::*;
572
573    #[test]
574    fn adds_https_when_scheme_is_missing() {
575        assert_eq!(
576            normalize_host("git.example.com").unwrap().as_str(),
577            "https://git.example.com/"
578        );
579    }
580
581    #[test]
582    fn keeps_explicit_scheme_port_and_base_path() {
583        assert_eq!(
584            normalize_host("http://localhost:3000").unwrap().as_str(),
585            "http://localhost:3000/"
586        );
587        assert_eq!(
588            normalize_host("https://example.com/gitfox")
589                .unwrap()
590                .as_str(),
591            "https://example.com/gitfox/"
592        );
593    }
594
595    #[test]
596    fn rejects_unusable_hosts() {
597        for bad in ["", "   ", "https://"] {
598            assert!(
599                normalize_host(bad).is_err(),
600                "expected `{bad}` to be rejected"
601            );
602        }
603    }
604
605    #[test]
606    fn resolves_paths_with_and_without_leading_slash() {
607        let c = GitFoxClient::builder("https://git.example.com")
608            .build()
609            .unwrap();
610        assert_eq!(
611            c.resolve("/api/v1/user").unwrap().as_str(),
612            "https://git.example.com/api/v1/user"
613        );
614        assert_eq!(
615            c.resolve("api/v1/user").unwrap().as_str(),
616            "https://git.example.com/api/v1/user"
617        );
618    }
619
620    #[test]
621    fn resolve_preserves_a_base_path() {
622        let c = GitFoxClient::builder("https://example.com/gitfox")
623            .build()
624            .unwrap();
625        assert_eq!(
626            c.resolve("/api/v1/user").unwrap().as_str(),
627            "https://example.com/gitfox/api/v1/user"
628        );
629    }
630
631    #[test]
632    fn resolve_preserves_a_percent_encoded_slash_in_a_repo_ref() {
633        // `ai/backend` travels as one path segment, `ai%2Fbackend`. If `join`
634        // ever decoded or double-encoded it, every repo-scoped call would 404.
635        let c = GitFoxClient::builder("https://git.example.com")
636            .build()
637            .unwrap();
638        let url = c.resolve("/api/v1/repos/ai%2Fbackend/pullreq").unwrap();
639        assert_eq!(
640            url.as_str(),
641            "https://git.example.com/api/v1/repos/ai%2Fbackend/pullreq"
642        );
643    }
644
645    #[test]
646    fn resolve_keeps_a_query_string_intact() {
647        let c = GitFoxClient::builder("https://git.example.com")
648            .build()
649            .unwrap();
650        let url = c
651            .resolve("/api/v1/repos/ai%2Fbackend/pullreq?state=open&limit=30")
652            .unwrap();
653        assert_eq!(url.query(), Some("state=open&limit=30"));
654        assert_eq!(url.path(), "/api/v1/repos/ai%2Fbackend/pullreq");
655    }
656
657    #[test]
658    fn query_encodes_pairs_and_skips_absent_values() {
659        let mut q = Query::new();
660        q.push("limit", 30)
661            .push_opt("author_id", Some(7))
662            .push_opt::<String>("query", None)
663            .extend("state", ["open", "merged"]);
664        assert_eq!(
665            q.apply("/x"),
666            "/x?limit=30&author_id=7&state=open&state=merged"
667        );
668        assert_eq!(Query::new().apply("/x"), "/x");
669    }
670
671    #[test]
672    fn query_escapes_values_that_would_break_the_url() {
673        let mut q = Query::new();
674        q.push("query", "fix: auth & tokens");
675        assert_eq!(q.encode(), "query=fix%3A+auth+%26+tokens");
676    }
677
678    #[test]
679    fn an_explicit_accept_header_replaces_the_default() {
680        // Verified through the header names the builder ends up with rather
681        // than by sending: two Accept headers would make the server choose.
682        let names = ["Accept", "accept", "ACCEPT"];
683        for name in names {
684            assert!(
685                [(name.to_string(), "text/plain".to_string())]
686                    .iter()
687                    .any(|(n, _)| n.eq_ignore_ascii_case("accept")),
688                "`{name}` should be recognised as Accept"
689            );
690        }
691        assert!(
692            ![("X-Trace".to_string(), "1".to_string())]
693                .iter()
694                .any(|(n, _)| n.eq_ignore_ascii_case("accept"))
695        );
696    }
697
698    #[test]
699    fn debug_never_reveals_the_token() {
700        let c = GitFoxClient::builder("git.example.com")
701            .token(Some("super-secret-token".into()))
702            .build()
703            .unwrap();
704        let rendered = format!("{c:?}");
705        assert!(!rendered.contains("super-secret-token"), "{rendered}");
706        assert!(rendered.contains("***"), "{rendered}");
707    }
708
709    #[test]
710    fn blank_tokens_are_treated_as_absent() {
711        let c = GitFoxClient::builder("git.example.com")
712            .token(Some("   ".into()))
713            .build()
714            .unwrap();
715        assert!(!c.has_token());
716    }
717}