1use std::sync::{Arc, Mutex};
2use std::thread::JoinHandle;
3use std::time::{Duration, Instant};
4
5use percent_encoding::{AsciiSet, NON_ALPHANUMERIC, percent_decode_str, utf8_percent_encode};
6use reqwest::blocking::RequestBuilder;
7use serde::Deserialize;
8use serde::de::DeserializeOwned;
9
10use crate::error::{ApiError, Error, Result};
11
12pub type Query = Vec<(String, String)>;
15
16pub const DEFAULT_MAX_RESPONSE_SIZE: u64 = 256 * 1024 * 1024;
18
19const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
20
21const MAX_RETRIES: u32 = 3;
23const RETRY_STATUSES: [u16; 3] = [502, 503, 504];
26const CONNECT_RETRY_WAIT: Duration = Duration::from_secs(1);
28const MAX_RETRY_WAIT: Duration = Duration::from_secs(60);
30
31#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
33#[non_exhaustive]
34pub enum Method {
35 Get,
36 Post,
37 Put,
38 Patch,
39 Delete,
40}
41
42impl Method {
43 pub fn as_str(self) -> &'static str {
45 match self {
46 Self::Get => "GET",
47 Self::Post => "POST",
48 Self::Put => "PUT",
49 Self::Patch => "PATCH",
50 Self::Delete => "DELETE",
51 }
52 }
53
54 fn is_idempotent(self) -> bool {
57 !matches!(self, Self::Post | Self::Patch)
58 }
59
60 fn to_reqwest(self) -> reqwest::Method {
61 match self {
62 Self::Get => reqwest::Method::GET,
63 Self::Post => reqwest::Method::POST,
64 Self::Put => reqwest::Method::PUT,
65 Self::Patch => reqwest::Method::PATCH,
66 Self::Delete => reqwest::Method::DELETE,
67 }
68 }
69}
70
71impl std::fmt::Display for Method {
72 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
73 f.write_str(self.as_str())
74 }
75}
76
77#[derive(Debug, Clone, PartialEq, Eq)]
79pub struct InvalidMethod(pub String);
80
81impl std::fmt::Display for InvalidMethod {
82 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
83 write!(f, "invalid HTTP method: {}", self.0)
84 }
85}
86
87impl std::error::Error for InvalidMethod {}
88
89impl std::str::FromStr for Method {
90 type Err = InvalidMethod;
91
92 fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
94 match s.to_ascii_uppercase().as_str() {
95 "GET" => Ok(Self::Get),
96 "POST" => Ok(Self::Post),
97 "PUT" => Ok(Self::Put),
98 "PATCH" => Ok(Self::Patch),
99 "DELETE" => Ok(Self::Delete),
100 _ => Err(InvalidMethod(s.to_owned())),
101 }
102 }
103}
104
105#[derive(Clone)]
113pub struct Client {
114 http: reqwest::blocking::Client,
115 api_url: String,
116 token: Option<String>,
117 timeout: Duration,
118 connect_timeout: Duration,
119 max_response_size: u64,
120 throttle: Option<Arc<Throttle>>,
121}
122
123impl std::fmt::Debug for Client {
124 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
126 f.debug_struct("Client")
127 .field("api_url", &self.api_url)
128 .field("token", &self.token.as_ref().map(|_| "<redacted>"))
129 .field("timeout", &self.timeout)
130 .field("connect_timeout", &self.connect_timeout)
131 .field("max_response_size", &self.max_response_size)
132 .field("throttle", &self.throttle)
133 .finish_non_exhaustive()
134 }
135}
136
137#[derive(Debug, Clone, PartialEq, Eq)]
142pub struct Upload {
143 pub filename: String,
144 pub content: Arc<[u8]>,
145 pub content_type: String,
147}
148
149impl Upload {
150 pub fn new(filename: impl Into<String>, content: impl Into<Arc<[u8]>>, content_type: impl Into<String>) -> Self {
151 Self {
152 filename: filename.into(),
153 content: content.into(),
154 content_type: content_type.into(),
155 }
156 }
157
158 pub fn from_path(path: impl AsRef<std::path::Path>) -> std::io::Result<Self> {
160 let path = path.as_ref();
161 let filename = path.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default();
162 let content_type = guess_content_type(&filename);
163 Ok(Self::new(filename, std::fs::read(path)?, content_type))
164 }
165}
166
167fn guess_content_type(filename: &str) -> &'static str {
168 let ext = filename.rsplit_once('.').map(|(_, e)| e.to_ascii_lowercase()).unwrap_or_default();
169 match ext.as_str() {
170 "pdf" => "application/pdf",
171 "png" => "image/png",
172 "jpg" | "jpeg" => "image/jpeg",
173 "gif" => "image/gif",
174 "webp" => "image/webp",
175 "svg" => "image/svg+xml",
176 "txt" => "text/plain",
177 "csv" => "text/csv",
178 "xml" => "application/xml",
179 "json" => "application/json",
180 _ => "application/octet-stream",
181 }
182}
183
184#[derive(Clone)]
186pub struct ClientBuilder {
187 base_url: String,
188 token: Option<String>,
189 timeout: Duration,
190 connect_timeout: Option<Duration>,
191 max_response_size: u64,
192 allow_insecure_http: bool,
193}
194
195impl ClientBuilder {
196 pub fn from_env() -> Result<Self> {
199 let url = std::env::var("CT_URL").map_err(|_| Error::InvalidBaseUrl("CT_URL is not set".into()))?;
200 Ok(Client::builder(&url).token(std::env::var("CT_TOKEN").ok()))
201 }
202
203 pub fn token(mut self, token: impl Into<Option<String>>) -> Self {
205 self.token = token.into();
206 self
207 }
208
209 pub fn timeout(mut self, timeout: Duration) -> Self {
213 self.timeout = timeout;
214 self
215 }
216
217 pub fn connect_timeout(mut self, timeout: Duration) -> Self {
221 self.connect_timeout = Some(timeout);
222 self
223 }
224
225 pub fn max_response_size(mut self, bytes: u64) -> Self {
229 self.max_response_size = bytes;
230 self
231 }
232
233 pub fn allow_insecure_http(mut self, allow: bool) -> Self {
237 self.allow_insecure_http = allow;
238 self
239 }
240
241 pub fn build(self) -> Result<Client> {
242 let connect_timeout = self.connect_timeout.unwrap_or(DEFAULT_CONNECT_TIMEOUT).min(self.timeout);
243 let http = http_client()
244 .timeout(self.timeout)
245 .connect_timeout(connect_timeout)
246 .build()
247 .map_err(Error::transport)?;
248 Ok(Client {
249 http,
250 api_url: normalize_base_url(&self.base_url, self.allow_insecure_http)?,
251 token: self.token,
252 timeout: self.timeout,
253 connect_timeout,
254 max_response_size: self.max_response_size,
255 throttle: None,
256 })
257 }
258}
259
260fn http_client() -> reqwest::blocking::ClientBuilder {
262 if rustls::crypto::CryptoProvider::get_default().is_none() {
266 let _ = rustls::crypto::ring::default_provider().install_default();
267 }
268 reqwest::blocking::Client::builder()
269 .user_agent(USER_AGENT)
270 .redirect(redirect_policy())
271}
272
273fn redirect_policy() -> reqwest::redirect::Policy {
279 reqwest::redirect::Policy::custom(|attempt| {
280 if attempt.previous().len() >= 10 {
281 attempt.error("too many redirects")
282 } else if matches!(attempt.status().as_u16(), 307 | 308) {
283 attempt.follow()
284 } else {
285 attempt.stop()
286 }
287 })
288}
289
290const USER_AGENT: &str = concat!("churchtools-api/", env!("CARGO_PKG_VERSION"));
291
292#[derive(Debug)]
294struct Throttle {
295 interval: Duration,
296 next: Mutex<Instant>,
297}
298
299impl Throttle {
300 fn wait(&self) {
301 let now = Instant::now();
302 let start = {
303 let mut next = self.next.lock().unwrap_or_else(|e| e.into_inner());
304 let start = (*next).max(now);
305 *next = start + self.interval;
306 start
307 };
308 std::thread::sleep(start - now);
309 }
310}
311
312impl Client {
313 pub fn new(base_url: &str, token: Option<String>) -> Result<Self> {
317 Self::builder(base_url).token(token).build()
318 }
319
320 pub fn builder(base_url: &str) -> ClientBuilder {
322 ClientBuilder {
323 base_url: base_url.to_owned(),
324 token: None,
325 timeout: Duration::from_secs(30),
326 connect_timeout: None,
327 max_response_size: DEFAULT_MAX_RESPONSE_SIZE,
328 allow_insecure_http: false,
329 }
330 }
331
332 pub fn with_min_interval(mut self, min_interval: Duration) -> Self {
340 self.throttle = Some(Arc::new(Throttle {
341 interval: min_interval,
342 next: Mutex::new(Instant::now()),
343 }));
344 self
345 }
346
347 pub fn login_with_password(&self, username: &str, password: &str) -> Result<Self> {
359 let session = Self {
362 http: http_client()
363 .timeout(self.timeout)
364 .connect_timeout(self.connect_timeout)
365 .cookie_store(true)
366 .build()
367 .map_err(Error::transport)?,
368 token: None,
369 ..self.clone()
370 };
371 #[derive(Deserialize)]
372 #[serde(rename_all = "camelCase")]
373 struct LoginData {
374 person_id: i64,
375 }
376 let body = serde_json::json!({ "username": username, "password": password, "rememberMe": false });
377 let login: LoginData = session.request_data(Method::Post, "/login", &[], Some(&body))?;
378 let token: String = session.request_data(
379 Method::Get,
380 &format!("/persons/{}/logintoken", login.person_id),
381 &[],
382 None,
383 )?;
384 Ok(Self {
385 token: Some(token),
386 ..self.clone()
387 })
388 }
389
390 pub fn from_env() -> Result<Self> {
394 ClientBuilder::from_env()?.build()
395 }
396
397 pub fn api_url(&self) -> &str {
399 &self.api_url
400 }
401
402 pub fn request(
407 &self,
408 method: Method,
409 path: &str,
410 query: &[(String, String)],
411 body: Option<&serde_json::Value>,
412 ) -> Result<Vec<u8>> {
413 self.send(method, path, query, |builder| match body {
414 Some(body) => Ok(builder.json(body)),
415 None => Ok(builder),
416 })
417 }
418
419 pub fn request_json_bytes(
422 &self,
423 method: Method,
424 path: &str,
425 query: &[(String, String)],
426 body: Option<&[u8]>,
427 ) -> Result<Vec<u8>> {
428 self.send(method, path, query, |builder| match body {
429 Some(body) => Ok(builder
430 .header(reqwest::header::CONTENT_TYPE, "application/json")
431 .body(body.to_vec())),
432 None => Ok(builder),
433 })
434 }
435
436 pub fn request_multipart(
439 &self,
440 method: Method,
441 path: &str,
442 query: &[(String, String)],
443 form: &[(String, String)],
444 file_field: &str,
445 files: &[Upload],
446 ) -> Result<Vec<u8>> {
447 self.send(method, path, query, |builder| {
448 let mut multipart = reqwest::blocking::multipart::Form::new();
450 for (key, value) in form {
451 multipart = multipart.text(key.clone(), value.clone());
452 }
453 for file in files {
454 let reader = std::io::Cursor::new(file.content.clone());
456 let part = reqwest::blocking::multipart::Part::reader_with_length(reader, file.content.len() as u64)
457 .file_name(file.filename.clone())
458 .mime_str(&file.content_type)
459 .map_err(Error::transport)?;
460 multipart = multipart.part(file_field.to_owned(), part);
461 }
462 Ok(builder.multipart(multipart))
463 })
464 }
465
466 fn send(
468 &self,
469 method: Method,
470 path: &str,
471 query: &[(String, String)],
472 with_body: impl Fn(RequestBuilder) -> Result<RequestBuilder>,
473 ) -> Result<Vec<u8>> {
474 check_path(path)?;
475 let mut attempt = 0;
476 let mut connect_retried = false;
477 loop {
478 if let Some(throttle) = &self.throttle {
479 throttle.wait();
480 }
481 let mut builder = self
482 .http
483 .request(method.to_reqwest(), format!("{}{}", self.api_url, path))
484 .header("Accept", "application/json")
485 .query(query);
486 if let Some(token) = &self.token {
487 let mut value = reqwest::header::HeaderValue::try_from(format!("Login {token}"))
488 .map_err(|_| Error::InvalidToken)?;
489 value.set_sensitive(true);
491 builder = builder.header(reqwest::header::AUTHORIZATION, value);
492 }
493 let response = match with_body(builder)?.send() {
494 Ok(response) => response,
495 Err(err) if err.is_connect() && !connect_retried => {
498 connect_retried = true;
499 std::thread::sleep(CONNECT_RETRY_WAIT);
500 continue;
501 }
502 Err(err) => return Err(Error::transport(err)),
503 };
504 let status = response.status().as_u16();
505 let retryable = status == 429 || (RETRY_STATUSES.contains(&status) && method.is_idempotent());
506 if retryable && attempt < MAX_RETRIES {
507 attempt += 1;
508 std::thread::sleep(retry_after(response.headers(), attempt));
509 continue;
510 }
511 if response.status().is_redirection() {
512 let location = response.headers().get(reqwest::header::LOCATION);
513 return Err(Error::Redirect {
514 status,
515 location: location.and_then(|v| v.to_str().ok()).map(str::to_owned),
516 });
517 }
518 let bytes = read_body(response, self.max_response_size)?;
519 if !(200..300).contains(&status) {
520 return Err(ApiError::from_response(status, bytes).into());
521 }
522 return Ok(bytes);
523 }
524 }
525
526 pub fn request_data<T: DeserializeOwned>(
528 &self,
529 method: Method,
530 path: &str,
531 query: &[(String, String)],
532 body: Option<&serde_json::Value>,
533 ) -> Result<T> {
534 decode_data(&self.request(method, path, query, body)?)
535 }
536
537 pub fn request_json<T: DeserializeOwned>(
539 &self,
540 method: Method,
541 path: &str,
542 query: &[(String, String)],
543 body: Option<&serde_json::Value>,
544 ) -> Result<T> {
545 decode(&self.request(method, path, query, body)?)
546 }
547
548 pub fn pages(&self, path: &str, query: Query) -> Pages {
559 Pages { fetcher: PageFetcher::new(self, path, query) }
560 }
561
562 pub fn collect_pages<T: DeserializeOwned>(&self, path: &str, query: Query) -> Result<Vec<T>> {
564 self.items(path, query).collect()
565 }
566
567 pub fn items<T: DeserializeOwned>(&self, path: &str, query: Query) -> Items<T> {
572 Items { fetcher: PageFetcher::new(self, path, query), buffer: Vec::new().into_iter() }
573 }
574}
575
576struct PageFetcher {
579 client: Client,
580 path: String,
581 query: Query,
582 pending: Option<Pending>,
584 handed_out: u64,
586 prefetch: bool,
587}
588
589enum Pending {
590 Page(u64),
592 Spawned(u64, JoinHandle<Result<Vec<u8>>>),
594}
595
596impl PageFetcher {
597 fn new(client: &Client, path: &str, query: Query) -> Self {
598 Self {
599 client: client.clone(),
600 path: path.to_owned(),
601 query: query.into_iter().filter(|(k, _)| k != "page").collect(),
602 pending: Some(Pending::Page(1)),
603 handed_out: 0,
604 prefetch: true,
605 }
606 }
607
608 fn fetch(&mut self) -> Option<(u64, Result<Vec<u8>>)> {
611 let (page, result) = match self.pending.take()? {
612 Pending::Page(page) => (page, request_page(&self.client, &self.path, &self.query, page)),
613 Pending::Spawned(page, handle) => {
614 (page, handle.join().unwrap_or_else(|panic| std::panic::resume_unwind(panic)))
615 }
616 };
617 self.handed_out += 1;
618 Some((page, result))
619 }
620
621 fn advance(&mut self, next: Option<u64>) {
626 self.pending = next.map(|page| {
627 if !self.prefetch || self.handed_out < 2 {
628 return Pending::Page(page);
629 }
630 let (client, path, query) = (self.client.clone(), self.path.clone(), self.query.clone());
631 let thread = std::thread::Builder::new().name("churchtools-api prefetch".into());
632 match thread.spawn(move || request_page(&client, &path, &query, page)) {
633 Ok(handle) => Pending::Spawned(page, handle),
634 Err(_) => Pending::Page(page),
636 }
637 });
638 }
639}
640
641fn request_page(client: &Client, path: &str, query: &Query, page: u64) -> Result<Vec<u8>> {
642 let mut query = query.clone();
643 query.push(("page".into(), page.to_string()));
644 client.request(Method::Get, path, &query, None)
645}
646
647pub struct Items<T> {
649 fetcher: PageFetcher,
650 buffer: std::vec::IntoIter<T>,
651}
652
653impl<T> Items<T> {
654 pub fn prefetch(mut self, enabled: bool) -> Self {
657 self.fetcher.prefetch = enabled;
658 self
659 }
660}
661
662impl<T: DeserializeOwned> Iterator for Items<T> {
663 type Item = Result<T>;
664
665 fn next(&mut self) -> Option<Self::Item> {
666 #[derive(Deserialize)]
667 struct Page<T> {
668 data: Vec<T>,
669 meta: Option<serde_json::Value>,
671 }
672 loop {
673 if let Some(item) = self.buffer.next() {
674 return Some(Ok(item));
675 }
676 let (page, result) = self.fetcher.fetch()?;
677 match result.and_then(|bytes| decode::<Page<T>>(&bytes)) {
679 Ok(body) => {
680 let meta = body.meta.and_then(|m| serde_json::from_value(m).ok());
681 self.fetcher.advance(next_page(meta, !body.data.is_empty(), page));
682 self.buffer = body.data.into_iter();
683 }
684 Err(e) => return Some(Err(e)),
686 }
687 }
688 }
689}
690
691pub struct Pages {
693 fetcher: PageFetcher,
694}
695
696impl Pages {
697 pub fn prefetch(mut self, enabled: bool) -> Self {
707 self.fetcher.prefetch = enabled;
708 self
709 }
710}
711
712impl Iterator for Pages {
713 type Item = Result<Vec<u8>>;
714
715 fn next(&mut self) -> Option<Self::Item> {
716 let (page, result) = self.fetcher.fetch()?;
717 if let Ok(bytes) = &result {
718 self.fetcher.advance(next_page_number(bytes, page));
719 }
720 Some(result)
721 }
722}
723
724fn read_body(response: reqwest::blocking::Response, limit: u64) -> Result<Vec<u8>> {
726 use std::io::Read;
727
728 let too_large = || Error::ResponseTooLarge { limit };
729 if response.content_length().is_some_and(|len| len > limit) {
730 return Err(too_large());
731 }
732 let mut bytes = Vec::with_capacity(response.content_length().unwrap_or(0).min(1 << 20) as usize);
734 response.take(limit.saturating_add(1)).read_to_end(&mut bytes).map_err(Error::Read)?;
735 if bytes.len() as u64 > limit {
736 return Err(too_large());
737 }
738 Ok(bytes)
739}
740
741#[derive(Deserialize)]
742struct Meta {
743 pagination: Option<Pagination>,
744}
745
746#[derive(Deserialize)]
747#[serde(rename_all = "camelCase")]
748struct Pagination {
749 current: u64,
750 last_page: u64,
751}
752
753fn next_page(meta: Option<Meta>, has_items: bool, requested: u64) -> Option<u64> {
755 let pagination = meta?.pagination?;
756 (has_items && pagination.current == requested && pagination.current < pagination.last_page)
759 .then_some(requested + 1)
760}
761
762fn next_page_number(body: &[u8], requested: u64) -> Option<u64> {
764 #[derive(Deserialize)]
765 struct Body {
766 meta: Option<Meta>,
767 #[serde(default)]
768 data: HasItems,
769 }
770 let body = serde_json::from_slice::<Body>(body).ok()?;
771 next_page(body.meta, body.data.0, requested)
772}
773
774struct HasItems(bool);
776
777impl Default for HasItems {
778 fn default() -> Self {
779 Self(true)
780 }
781}
782
783impl<'de> Deserialize<'de> for HasItems {
784 fn deserialize<D: serde::Deserializer<'de>>(d: D) -> std::result::Result<Self, D::Error> {
785 use serde::de::{IgnoredAny, SeqAccess, Visitor};
786
787 struct V;
788 impl<'de> Visitor<'de> for V {
789 type Value = HasItems;
790 fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
791 f.write_str("any JSON value")
792 }
793 fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> std::result::Result<HasItems, A::Error> {
794 let first = seq.next_element::<IgnoredAny>()?;
795 while seq.next_element::<IgnoredAny>()?.is_some() {}
796 Ok(HasItems(first.is_some()))
797 }
798 fn visit_map<A: serde::de::MapAccess<'de>>(self, map: A) -> std::result::Result<HasItems, A::Error> {
799 IgnoredAny.visit_map(map).map(|_| HasItems(true))
800 }
801 fn visit_unit<E>(self) -> std::result::Result<HasItems, E> {
802 Ok(HasItems(true))
803 }
804 fn visit_bool<E>(self, _: bool) -> std::result::Result<HasItems, E> {
805 Ok(HasItems(true))
806 }
807 fn visit_i64<E>(self, _: i64) -> std::result::Result<HasItems, E> {
808 Ok(HasItems(true))
809 }
810 fn visit_u64<E>(self, _: u64) -> std::result::Result<HasItems, E> {
811 Ok(HasItems(true))
812 }
813 fn visit_f64<E>(self, _: f64) -> std::result::Result<HasItems, E> {
814 Ok(HasItems(true))
815 }
816 fn visit_str<E>(self, _: &str) -> std::result::Result<HasItems, E> {
817 Ok(HasItems(true))
818 }
819 }
820 d.deserialize_any(V)
821 }
822}
823
824fn retry_after(headers: &reqwest::header::HeaderMap, attempt: u32) -> Duration {
827 headers
828 .get(reqwest::header::RETRY_AFTER)
829 .and_then(|v| v.to_str().ok())
830 .and_then(|v| parse_retry_after(v.trim(), chrono::Utc::now()))
831 .unwrap_or(Duration::from_secs(1 << attempt))
832 .min(MAX_RETRY_WAIT)
833}
834
835fn parse_retry_after(value: &str, now: chrono::DateTime<chrono::Utc>) -> Option<Duration> {
836 if let Ok(seconds) = value.parse::<u64>() {
837 return Some(Duration::from_secs(seconds));
838 }
839 let at = chrono::DateTime::parse_from_rfc2822(value).ok()?;
841 Some((at.to_utc() - now).to_std().unwrap_or_default())
842}
843
844pub fn decode_data<T: DeserializeOwned>(bytes: &[u8]) -> Result<T> {
846 if bytes.trim_ascii().is_empty() {
847 return decode(bytes); }
849 decode::<Envelope<T>>(bytes).map(|e| e.data).or_else(|err| {
850 match serde_json::from_slice::<Envelope<serde_json::Value>>(bytes) {
852 Ok(Envelope { data: serde_json::Value::Array(a) }) if a.is_empty() => {
853 serde_json::from_value(serde_json::json!({})).map_err(|_| err)
854 }
855 _ => Err(err),
856 }
857 })
858}
859
860#[derive(Deserialize)]
861struct Envelope<T> {
862 data: T,
863}
864
865pub fn decode<T: DeserializeOwned>(bytes: &[u8]) -> Result<T> {
867 if bytes.trim_ascii().is_empty() {
868 return serde_json::from_value(serde_json::Value::Null).map_err(|source| Error::Decode {
870 source,
871 body: String::new(),
872 });
873 }
874 serde_json::from_slice(bytes).map_err(|source| Error::Decode {
875 source,
876 body: String::from_utf8_lossy(bytes).into_owned(),
877 })
878}
879
880fn normalize_base_url(base_url: &str, allow_insecure_http: bool) -> Result<String> {
885 let invalid = |why: &str| Error::InvalidBaseUrl(format!("{base_url}: {why}"));
886 let mut url = reqwest::Url::parse(base_url.trim()).map_err(|e| invalid(&e.to_string()))?;
887 match url.scheme() {
888 "https" => {}
889 "http" if allow_insecure_http || is_loopback(&url) => {}
890 "http" => {
891 return Err(invalid(
892 "http:// would send the token unencrypted; use https:// \
893 (or allow_insecure_http for a trusted network)",
894 ));
895 }
896 _ => return Err(invalid("expected https://")),
897 }
898 if url.host_str().is_none_or(str::is_empty) {
899 return Err(invalid("no host"));
900 }
901 if url.query().is_some() || url.fragment().is_some() {
902 return Err(invalid("must not contain `?` or `#`"));
903 }
904 if !url.username().is_empty() || url.password().is_some() {
905 return Err(invalid("must not contain user name or password; pass a token instead"));
906 }
907 let path = url.path().trim_end_matches('/');
908 let path = path.strip_suffix("/api").unwrap_or(path).to_owned();
909 url.set_path(&format!("{path}/api"));
910 Ok(url.into())
911}
912
913fn check_path(path: &str) -> Result<()> {
917 let valid = path.strip_prefix('/').is_some_and(|rest| {
918 rest.split('/').all(|segment| {
919 let decoded = percent_decode_str(segment).decode_utf8_lossy();
920 !segment.is_empty() && decoded != "." && decoded != ".."
921 })
922 });
923 if valid { Ok(()) } else { Err(Error::InvalidPath(path.to_owned())) }
924}
925
926fn is_loopback(url: &reqwest::Url) -> bool {
927 let host = url.host_str().unwrap_or_default();
928 host == "localhost"
929 || host
930 .trim_start_matches('[')
931 .trim_end_matches(']')
932 .parse::<std::net::IpAddr>()
933 .is_ok_and(|ip| ip.is_loopback())
934}
935
936const PATH_SEGMENT: &AsciiSet = &NON_ALPHANUMERIC.remove(b'-').remove(b'_').remove(b'.').remove(b'~');
937
938pub fn encode_path_segment(value: impl std::fmt::Display) -> String {
940 utf8_percent_encode(&value.to_string(), PATH_SEGMENT).to_string()
941}
942
943#[cfg(test)]
944mod tests {
945 use std::io::{BufRead, BufReader, Read, Write};
946
947 use super::*;
948
949 fn serve(responses: Vec<String>) -> (String, Arc<Mutex<Vec<String>>>) {
952 let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
953 let url = format!("http://{}", listener.local_addr().unwrap());
954 let seen = Arc::new(Mutex::new(Vec::new()));
955 let log = seen.clone();
956 std::thread::spawn(move || {
957 for (stream, response) in listener.incoming().zip(responses) {
958 let mut stream = stream.unwrap();
959 let mut reader = BufReader::new(stream.try_clone().unwrap());
960 let mut line = String::new();
961 reader.read_line(&mut line).unwrap();
962 let request: Vec<&str> = line.split_whitespace().take(2).collect();
963 log.lock().unwrap().push(request.join(" "));
964 let mut length = 0;
965 loop {
966 let mut header = String::new();
967 if reader.read_line(&mut header).unwrap() == 0 || header == "\r\n" {
968 break;
969 }
970 if let Some((name, value)) = header.split_once(':')
971 && name.eq_ignore_ascii_case("content-length")
972 {
973 length = value.trim().parse().unwrap();
974 }
975 }
976 reader.read_exact(&mut vec![0; length]).unwrap();
977 stream.write_all(response.as_bytes()).unwrap();
978 }
979 });
980 (url, seen)
981 }
982
983 fn reply(status: &str, headers: &str, body: &str) -> String {
984 format!(
985 "HTTP/1.1 {status}\r\n{headers}Content-Length: {}\r\nConnection: close\r\n\r\n{body}",
986 body.len()
987 )
988 }
989
990 #[test]
991 fn connect_timeout_defaults_to_10s_but_not_above_timeout() {
992 let client = Client::new("https://x.church.tools", None).unwrap();
993 assert_eq!(client.connect_timeout, Duration::from_secs(10));
994 let short = Client::builder("https://x.church.tools").timeout(Duration::from_secs(3)).build().unwrap();
995 assert_eq!(short.connect_timeout, Duration::from_secs(3));
996 let custom = Client::builder("https://x.church.tools")
997 .timeout(Duration::from_secs(600))
998 .connect_timeout(Duration::from_millis(200))
999 .build()
1000 .unwrap();
1001 assert_eq!((custom.timeout, custom.connect_timeout), (Duration::from_secs(600), Duration::from_millis(200)));
1002 let start = Instant::now();
1004 let blackhole = Client::builder("http://10.255.255.1").allow_insecure_http(true);
1005 let blackhole = blackhole.timeout(Duration::from_secs(600)).connect_timeout(Duration::from_millis(200));
1006 assert!(blackhole.build().unwrap().request(Method::Get, "/x", &[], None).is_err());
1007 assert!(start.elapsed() < Duration::from_secs(5));
1008 }
1009
1010 #[test]
1011 fn responses_above_the_size_limit_are_rejected() {
1012 let declared = reply("200 OK", "", r#"{"data":"0123456789"}"#);
1013 let undeclared = "HTTP/1.1 200 OK\r\nConnection: close\r\n\r\n{\"data\":\"0123456789\"}".to_owned();
1015 let small = reply("200 OK", "", r#"{"data":1}"#);
1016 let (url, _) = serve(vec![declared, undeclared, small]);
1017 let client = Client::builder(&url).max_response_size(12).build().unwrap();
1018 for _ in 0..2 {
1019 let err = client.request(Method::Get, "/x", &[], None).unwrap_err();
1020 assert!(matches!(err, Error::ResponseTooLarge { limit: 12 }), "{err}");
1021 }
1022 assert_eq!(client.request(Method::Get, "/x", &[], None).unwrap(), br#"{"data":1}"#);
1023 }
1024
1025 #[test]
1026 fn redirects_that_would_turn_a_write_into_a_get_are_errors() {
1027 let (url, seen) = serve(vec![reply("302 Found", "Location: /api/elsewhere\r\n", "")]);
1028 let client = Client::new(&url, None).unwrap();
1029 let body = serde_json::json!({"name": "x"});
1030 let err = client.request(Method::Post, "/groups", &[], Some(&body)).unwrap_err();
1031 let Error::Redirect { status, location } = err else { panic!("{err}") };
1032 assert_eq!((status, location.as_deref()), (302, Some("/api/elsewhere")));
1033 assert_eq!(*seen.lock().unwrap(), ["POST /api/groups"]); }
1035
1036 #[test]
1037 fn method_preserving_redirects_are_followed() {
1038 let (url, seen) = serve(vec![
1039 reply("307 Temporary Redirect", "Location: /api/moved\r\n", ""),
1040 reply("200 OK", "", r#"{"data":1}"#),
1041 ]);
1042 let client = Client::new(&url, None).unwrap();
1043 let body = serde_json::json!({"name": "x"});
1044 let data: i64 = client.request_data(Method::Post, "/groups", &[], Some(&body)).unwrap();
1045 assert_eq!(data, 1);
1046 assert_eq!(*seen.lock().unwrap(), ["POST /api/groups", "POST /api/moved"]);
1047 }
1048
1049 #[test]
1050 fn base_url_gets_api_suffix_once() {
1051 for input in [
1052 "https://x.church.tools",
1053 "https://x.church.tools/",
1054 "https://x.church.tools/api",
1055 "https://x.church.tools/api/",
1056 ] {
1057 assert_eq!(normalize_base_url(input, false).unwrap(), "https://x.church.tools/api");
1058 }
1059 assert!(normalize_base_url("x.church.tools", false).is_err());
1060 assert_eq!(normalize_base_url(" https://X.Church.Tools ", false).unwrap(), "https://x.church.tools/api");
1061 assert_eq!(normalize_base_url("https://example.org/ct/", false).unwrap(), "https://example.org/ct/api");
1062 assert_eq!(normalize_base_url("https://example.org:8443/ct/api", false).unwrap(), "https://example.org:8443/ct/api");
1063 for bad in [
1064 "https://x.church.tools?a=b",
1065 "https://x.church.tools/#top",
1066 "https://user:pw@x.church.tools",
1067 "ftp://x.church.tools",
1068 "https://",
1069 ] {
1070 assert!(normalize_base_url(bad, false).is_err(), "{bad}");
1071 }
1072 }
1073
1074 #[test]
1075 fn plain_http_only_for_loopback_or_when_allowed() {
1076 for local in ["http://localhost:8080", "http://127.0.0.1:1", "http://[::1]:80", "http://LOCALHOST"] {
1077 assert!(normalize_base_url(local, false).is_ok(), "{local}");
1078 }
1079 let err = normalize_base_url("http://x.church.tools", false).unwrap_err();
1080 assert!(err.to_string().contains("unencrypted"), "{err}");
1081 assert!(normalize_base_url("http://localhost.evil.org", false).is_err());
1082 assert_eq!(
1083 normalize_base_url("http://ct.intern", true).unwrap(),
1084 "http://ct.intern/api"
1085 );
1086 let client = Client::builder("http://ct.intern").allow_insecure_http(true).build().unwrap();
1087 assert_eq!(client.api_url(), "http://ct.intern/api");
1088 }
1089
1090 #[test]
1091 fn pagination_stops_on_last_page_or_missing_meta() {
1092 let page = |c: u64, l: u64| {
1093 format!(r#"{{"data":[{{"id":1}}],"meta":{{"pagination":{{"current":{c},"lastPage":{l}}}}}}}"#)
1094 };
1095 assert_eq!(next_page_number(page(1, 3).as_bytes(), 1), Some(2));
1096 assert_eq!(next_page_number(page(3, 3).as_bytes(), 3), None);
1097 assert_eq!(next_page_number(page(1, 3).as_bytes(), 2), None);
1098 assert_eq!(next_page_number(br#"{"data":[1],"meta":{"count":3}}"#, 1), None);
1099 let empty = br#"{"data":[],"meta":{"pagination":{"current":1,"lastPage":1000000}}}"#;
1101 assert_eq!(next_page_number(empty, 1), None);
1102 let map = br#"{"data":{"a":1},"meta":{"pagination":{"current":1,"lastPage":2}}}"#;
1103 assert_eq!(next_page_number(map, 1), Some(2));
1104 }
1105
1106 #[test]
1107 fn collect_pages_decodes_each_page_once_and_follows_meta() {
1108 let page = |c: u64, items: &str| {
1109 reply("200 OK", "", &format!(r#"{{"data":[{items}],"meta":{{"pagination":{{"current":{c},"lastPage":3}}}}}}"#))
1110 };
1111 let (url, seen) = serve(vec![page(1, "1,2"), page(2, "3"), page(3, "4")]);
1112 let client = Client::new(&url, None).unwrap();
1113 let query = vec![("limit".into(), "2".into()), ("page".into(), "9".into())];
1114 let items: Vec<i64> = client.collect_pages("/x", query).unwrap();
1115 assert_eq!(items, [1, 2, 3, 4]);
1116 assert_eq!(seen.lock().unwrap().len(), 3);
1117 let (url, _) = serve(vec![reply("200 OK", "", r#"{"data":[1],"meta":[]}"#)]);
1119 let items: Vec<i64> = Client::new(&url, None).unwrap().collect_pages("/x", vec![]).unwrap();
1120 assert_eq!(items, [1]);
1121 }
1122
1123 #[test]
1124 fn items_fetch_pages_only_when_needed() {
1125 let page = |c: u64, items: &str| {
1126 reply("200 OK", "", &format!(r#"{{"data":[{items}],"meta":{{"pagination":{{"current":{c},"lastPage":3}}}}}}"#))
1127 };
1128 let (url, seen) = serve(vec![page(1, "1,2"), page(2, "3"), page(3, "4")]);
1129 let client = Client::new(&url, None).unwrap();
1130 let items = client.items("/x", vec![]).prefetch(false);
1131 let first: Vec<i64> = items.take(3).collect::<Result<_>>().unwrap();
1132 assert_eq!(first, [1, 2, 3]);
1133 assert_eq!(*seen.lock().unwrap(), ["GET /api/x?page=1", "GET /api/x?page=2"]);
1134 let (url, _) = serve(vec![reply("404 Not Found", "", "{}")]);
1136 let mut items = Client::new(&url, None).unwrap().items::<i64>("/x", vec![]);
1137 assert!(matches!(items.next(), Some(Err(Error::Api(_)))));
1138 assert!(items.next().is_none());
1139 }
1140
1141 #[test]
1142 fn prefetch_starts_after_the_second_page() {
1143 let page = |c: u64, items: &str| {
1144 reply("200 OK", "", &format!(r#"{{"data":[{items}],"meta":{{"pagination":{{"current":{c},"lastPage":4}}}}}}"#))
1145 };
1146 let (url, seen) = serve(vec![page(1, "1,2"), page(2, "3")]);
1148 let client = Client::new(&url, None).unwrap();
1149 let mut pages = client.pages("/x", vec![]);
1150 assert!(pages.next().unwrap().is_ok());
1151 drop(pages);
1152 std::thread::sleep(Duration::from_millis(50));
1153 assert_eq!(*seen.lock().unwrap(), ["GET /api/x?page=1"]);
1154 let (url, seen) = serve(vec![page(1, "1,2"), page(2, "3"), reply("404 Not Found", "", "{}")]);
1157 let client = Client::new(&url, None).unwrap();
1158 let mut items = client.items::<i64>("/x", vec![]);
1159 assert_eq!(items.by_ref().take(3).collect::<Result<Vec<_>>>().unwrap(), [1, 2, 3]);
1160 let deadline = Instant::now() + Duration::from_secs(5);
1161 while seen.lock().unwrap().len() < 3 && Instant::now() < deadline {
1162 std::thread::sleep(Duration::from_millis(5));
1163 }
1164 assert_eq!(seen.lock().unwrap().len(), 3);
1165 assert!(matches!(items.next(), Some(Err(Error::Api(_)))));
1166 assert!(items.next().is_none());
1167 }
1168
1169 #[test]
1170 fn uploads_are_sent_with_content_and_retried() {
1171 let (url, seen) = serve(vec![
1172 reply("429 Too Many Requests", "Retry-After: 0\r\n", ""),
1173 reply("200 OK", "", r#"{"data":[]}"#),
1174 ]);
1175 let client = Client::new(&url, None).unwrap();
1176 let file = Upload::new("brief.txt", b"Hallo Gemeinde".as_slice(), "text/plain");
1177 let copy = file.clone();
1178 assert!(Arc::ptr_eq(&file.content, ©.content)); let form = [("sortKey".to_owned(), "3".to_owned())];
1180 client.request_multipart(Method::Post, "/files/person/7", &[], &form, "files[]", &[file]).unwrap();
1181 assert_eq!(seen.lock().unwrap().len(), 2);
1182 }
1183
1184 #[test]
1185 fn json_bytes_are_sent_unchanged() {
1186 let (url, _) = serve(vec![reply("200 OK", "", r#"{"data":1}"#)]);
1187 let client = Client::new(&url, None).unwrap();
1188 let body = br#"{"firstName": "Ben"}"#;
1189 assert_eq!(client.request_json_bytes(Method::Post, "/x", &[], Some(body)).unwrap(), br#"{"data":1}"#);
1190 }
1191
1192 #[test]
1193 fn empty_body_is_none_for_optional_results() {
1194 assert_eq!(decode::<Option<i64>>(b"").unwrap(), None);
1195 assert_eq!(decode::<Option<i64>>(b"7").unwrap(), Some(7));
1196 assert!(decode::<i64>(b" ").is_err());
1197 }
1198
1199 #[test]
1200 fn retry_after_uses_header_or_backoff() {
1201 let mut headers = reqwest::header::HeaderMap::new();
1202 assert_eq!(retry_after(&headers, 1), Duration::from_secs(2));
1203 assert_eq!(retry_after(&headers, 3), Duration::from_secs(8));
1204 headers.insert(reqwest::header::RETRY_AFTER, "5".parse().unwrap());
1205 assert_eq!(retry_after(&headers, 1), Duration::from_secs(5));
1206 headers.insert(reqwest::header::RETRY_AFTER, "3600".parse().unwrap());
1207 assert_eq!(retry_after(&headers, 1), MAX_RETRY_WAIT);
1208 headers.insert(reqwest::header::RETRY_AFTER, "soon".parse().unwrap());
1209 assert_eq!(retry_after(&headers, 2), Duration::from_secs(4));
1210
1211 let now = "2026-10-21T07:28:00Z".parse().unwrap();
1212 assert_eq!(parse_retry_after("Wed, 21 Oct 2026 07:28:10 GMT", now), Some(Duration::from_secs(10)));
1213 assert_eq!(parse_retry_after("Wed, 21 Oct 2026 07:27:00 GMT", now), Some(Duration::ZERO));
1214 }
1215
1216 #[test]
1217 fn unavailable_server_is_retried_for_idempotent_methods_only() {
1218 let unavailable = || reply("503 Service Unavailable", "Retry-After: 0\r\n", "");
1219 let (url, seen) = serve(vec![unavailable(), reply("200 OK", "", r#"{"data":1}"#), unavailable()]);
1220 let client = Client::new(&url, None).unwrap();
1221 assert_eq!(client.request(Method::Get, "/x", &[], None).unwrap(), br#"{"data":1}"#);
1222 let err = client.request(Method::Post, "/x", &[], None).unwrap_err();
1223 assert!(matches!(&err, Error::Api(api) if api.status == 503), "{err}");
1224 assert_eq!(*seen.lock().unwrap(), ["GET /api/x", "GET /api/x", "POST /api/x"]);
1225 }
1226
1227 #[test]
1228 fn refused_connection_is_retried_once() {
1229 let port = std::net::TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port();
1231 let client = Client::new(&format!("http://127.0.0.1:{port}"), None).unwrap();
1232 let start = Instant::now();
1233 let err = client.request(Method::Post, "/x", &[], None).unwrap_err();
1234 assert!(matches!(&err, Error::Transport(e) if e.is_connect()), "{err}");
1235 assert!(start.elapsed() >= CONNECT_RETRY_WAIT);
1236 }
1237
1238 #[test]
1239 fn throttle_spaces_requests() {
1240 let throttle = Throttle {
1241 interval: Duration::from_millis(30),
1242 next: Mutex::new(Instant::now()),
1243 };
1244 let start = Instant::now();
1245 for _ in 0..4 {
1246 throttle.wait();
1247 }
1248 assert!(start.elapsed() >= Duration::from_millis(90));
1250 }
1251
1252 #[test]
1253 fn debug_output_hides_the_token() {
1254 let client = Client::new("https://x.church.tools", Some("geheim123".into())).unwrap();
1255 let debug = format!("{client:?}");
1256 assert!(!debug.contains("geheim123"), "{debug}");
1257 assert!(debug.contains("<redacted>") && debug.contains("https://x.church.tools/api"));
1258 }
1259
1260 #[test]
1261 fn dot_and_empty_segments_are_rejected() {
1262 let client = Client::new("http://127.0.0.1:9", None).unwrap();
1263 for id in ["..", ".", ""] {
1264 let path = format!("/groups/7/members/{}", encode_path_segment(id));
1265 let err = client.request(Method::Delete, &path, &[], None).unwrap_err();
1266 assert!(matches!(err, Error::InvalidPath(_)), "{id:?}: {err}");
1267 }
1268 assert!(check_path("/groups/7/members/%2e%2E").is_err());
1270 assert!(check_path("/groups/7/members/.%2e").is_err());
1271 assert!(check_path("persons").is_err());
1272 assert!(check_path("/persons/").is_err());
1273 assert!(check_path("/persons/a.b/..x").is_ok());
1274 assert_eq!(encode_path_segment("%2e%2e"), "%252e%252e");
1276 assert!(check_path("/files/%252e%252e").is_ok());
1277 }
1278
1279 #[test]
1280 fn path_segments_are_encoded() {
1281 assert_eq!(encode_path_segment("a b/c"), "a%20b%2Fc");
1282 assert_eq!(encode_path_segment(42), "42");
1283 }
1284}