1use 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
24pub const DEFAULT_RETRIES: u32 = 2;
26
27const MAX_BACKOFF: Duration = Duration::from_secs(5);
35
36const USER_AGENT: &str = concat!("fx/", env!("CARGO_PKG_VERSION"));
37
38#[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
48impl 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 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 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 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 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 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 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 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 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 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 continue;
312 };
313 let payload = payload.trim();
314 if last_event.as_deref() == Some("error") {
315 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 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#[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 pub fn retries(mut self, retries: u32) -> Self {
422 self.retries = retries;
423 self
424 }
425
426 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
451pub 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
475pub 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
489fn 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
502fn 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#[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 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 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 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 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}