Skip to main content

churchtools_api/
client.rs

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
12/// Query parameters as sent on the wire; array parameters appear once per value
13/// (`ids[]=1&ids[]=2`).
14pub type Query = Vec<(String, String)>;
15
16/// Default for [`ClientBuilder::max_response_size`]: 256 MiB.
17pub const DEFAULT_MAX_RESPONSE_SIZE: u64 = 256 * 1024 * 1024;
18
19const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
20
21/// How often a request answered with a retryable status is repeated.
22const MAX_RETRIES: u32 = 3;
23/// Statuses after which an idempotent request is repeated: the gateway or
24/// the server was briefly unavailable. `429` is repeated for every method.
25const RETRY_STATUSES: [u16; 3] = [502, 503, 504];
26/// Wait before repeating a request whose connection could not be established.
27const CONNECT_RETRY_WAIT: Duration = Duration::from_secs(1);
28/// Upper bound for waiting on a `Retry-After` header.
29const MAX_RETRY_WAIT: Duration = Duration::from_secs(60);
30
31/// HTTP method of a request.
32#[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    /// The method name as sent on the wire, e.g. `GET`.
44    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    /// Whether a request may be repeated after the server was briefly
55    /// unavailable: all but POST and PATCH.
56    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/// Error of [`Method::from_str`](std::str::FromStr): not one of the supported methods.
78#[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    /// Parses the method name, case-insensitively.
93    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/// Synchronous ChurchTools API client.
106///
107/// Cloning is cheap: the connection pool and the rate limit are shared.
108///
109/// The client blocks (it uses `reqwest::blocking`) and panics when created,
110/// used or dropped inside an async runtime such as Tokio. From async code,
111/// call it in `tokio::task::spawn_blocking`.
112#[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    // Hand-written so the token never ends up in logs.
125    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/// A file for an upload endpoint.
138///
139/// The content is shared: cloning an `Upload` or retrying the request does
140/// not copy it.
141#[derive(Debug, Clone, PartialEq, Eq)]
142pub struct Upload {
143    pub filename: String,
144    pub content: Arc<[u8]>,
145    /// MIME type, e.g. `application/pdf`.
146    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    /// Reads a file; the MIME type is guessed from the extension.
159    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/// Options for a [`Client`], created with [`Client::builder`].
185#[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    /// Reads the instance URL from `CT_URL` and the login token from `CT_TOKEN`,
197    /// leaving the other options to be set before [`build`](Self::build).
198    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    /// The login token, sent as `Authorization: Login <token>`.
204    pub fn token(mut self, token: impl Into<Option<String>>) -> Self {
205        self.token = token.into();
206        self
207    }
208
209    /// Timeout for a whole request including reading the body (default 30 s).
210    ///
211    /// Raise it for large downloads, uploads or slow exports.
212    pub fn timeout(mut self, timeout: Duration) -> Self {
213        self.timeout = timeout;
214        self
215    }
216
217    /// Timeout for establishing the connection (default 10 s, at most
218    /// [`timeout`](Self::timeout)), so an unreachable host fails fast even
219    /// with a long request timeout.
220    pub fn connect_timeout(mut self, timeout: Duration) -> Self {
221        self.connect_timeout = Some(timeout);
222        self
223    }
224
225    /// Largest response body that is read (default
226    /// [`DEFAULT_MAX_RESPONSE_SIZE`]); larger ones fail with
227    /// [`Error::ResponseTooLarge`] instead of filling the memory.
228    pub fn max_response_size(mut self, bytes: u64) -> Self {
229        self.max_response_size = bytes;
230        self
231    }
232
233    /// Allows `http://` for hosts other than `localhost` and loopback addresses.
234    ///
235    /// The token then travels unencrypted; only for instances in a trusted network.
236    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
260/// The common settings of every HTTP client this crate creates.
261fn http_client() -> reqwest::blocking::ClientBuilder {
262    // reqwest is built without a default crypto provider (`rustls-no-provider`),
263    // so rustls does not pull in aws-lc-rs; `ring` is installed here instead,
264    // unless the application has already chosen a provider.
265    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
273/// Follows only redirects that keep method and body (307, 308).
274///
275/// On 301/302/303 reqwest would repeat a POST/PUT/DELETE as GET and drop the
276/// body, so a write would look successful without having happened. Those are
277/// reported as [`Error::Redirect`] instead.
278fn 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/// Spaces requests at least `interval` apart, across all clones of a client.
293#[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    /// Creates a client for `base_url`, e.g. `https://meinegemeinde.church.tools`.
314    ///
315    /// A trailing `/api` is optional. See [`Client::builder`] for more options.
316    pub fn new(base_url: &str, token: Option<String>) -> Result<Self> {
317        Self::builder(base_url).token(token).build()
318    }
319
320    /// Starts configuring a client for `base_url`.
321    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    /// Limits this client (and its clones) to one request per `min_interval`.
333    ///
334    /// Useful for bulk jobs and tests, so the instance is not flooded. Independent
335    /// of this, a `429 Too Many Requests` answer is retried after the time the
336    /// server asks for (`Retry-After`, at most 60 s, up to 3 times); so are
337    /// `502`/`503`/`504` for idempotent methods (GET, HEAD, PUT, DELETE,
338    /// OPTIONS). A failed connection is retried once after 1 s.
339    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    /// Logs in with username (or email) and password and returns a client that
348    /// uses the login token of that person.
349    ///
350    /// Keeps the rate limit of `self`. Prefer a stored token for scripts; this is
351    /// meant for tests and interactive tools.
352    ///
353    /// The token is the person's persistent login token: ChurchTools creates one
354    /// if there is none, and it stays valid after this client is dropped, until
355    /// it is revoked with `client.persons().delete_login_token(person_id)`. The
356    /// password session used to fetch it is not reused; the API has no logout,
357    /// so it ends when the server expires it.
358    pub fn login_with_password(&self, username: &str, password: &str) -> Result<Self> {
359        // The password login answers with a session cookie, which is only needed
360        // to fetch the token.
361        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    /// Reads the instance URL from `CT_URL` and the login token from `CT_TOKEN`.
391    ///
392    /// For other options use [`ClientBuilder::from_env`].
393    pub fn from_env() -> Result<Self> {
394        ClientBuilder::from_env()?.build()
395    }
396
397    /// The API root, always ending in `/api`.
398    pub fn api_url(&self) -> &str {
399        &self.api_url
400    }
401
402    /// Sends a request and returns the raw body of a successful response.
403    ///
404    /// `path` starts with `/` and is relative to the API root; path parameters
405    /// must already be encoded (see [`encode_path_segment`]).
406    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    /// Like [`request`](Self::request), with a body that is already encoded
420    /// JSON; it is sent as is, without parsing it again.
421    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    /// Sends a `multipart/form-data` request: the text fields of `form` plus one
437    /// part named `file_field` (e.g. `files[]`) per file.
438    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            // Sending consumes a form, so it is rebuilt for every attempt.
449            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                // A reader over the shared content: no copy per attempt.
455                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    /// Common part of all requests: rate limit, auth, retries, error mapping.
467    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                // Keeps the token out of reqwest's own debug output.
490                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                // Not connected means the request did not reach the server, so
496                // repeating it is safe for every method.
497                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    /// Sends a request and decodes the `data` field of the response envelope.
527    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    /// Sends a request and decodes the whole response body.
538    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    /// Iterates over the raw bodies of all pages of a paginated GET endpoint.
549    ///
550    /// Any `page` entry in `query` is replaced. Iteration stops after the page
551    /// whose `meta.pagination.current` reaches `lastPage`, after an empty page,
552    /// or after the first page if the response carries no pagination info.
553    ///
554    /// Pages are fetched one by one with offsets: if entries are added or
555    /// removed meanwhile, an entry can show up twice or be skipped. From the
556    /// second page on, the next page is requested in a background thread while
557    /// the current one is being used, see [`Pages::prefetch`].
558    pub fn pages(&self, path: &str, query: Query) -> Pages {
559        Pages { fetcher: PageFetcher::new(self, path, query) }
560    }
561
562    /// Fetches all pages and concatenates their `data` arrays.
563    pub fn collect_pages<T: DeserializeOwned>(&self, path: &str, query: Query) -> Result<Vec<T>> {
564        self.items(path, query).collect()
565    }
566
567    /// Iterates over the items of all pages, fetching each page only when the
568    /// previous one is used up. Stopping early saves the remaining requests.
569    ///
570    /// Ends after the first error; the same rules as for [`Client::pages`] apply.
571    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
576/// Requests the pages of a paginated GET endpoint one after another; the
577/// shared part of [`Pages`] and [`Items`].
578struct PageFetcher {
579    client: Client,
580    path: String,
581    query: Query,
582    /// The page to hand out next, or `None` after the last page.
583    pending: Option<Pending>,
584    /// Pages handed out so far.
585    handed_out: u64,
586    prefetch: bool,
587}
588
589enum Pending {
590    /// Not requested yet.
591    Page(u64),
592    /// Being requested in a background thread.
593    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    /// Number and body of the next page, or `None` after the last one. The
609    /// caller decides with [`PageFetcher::advance`] which page follows.
610    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    /// Sets the page that follows. From the second page on it is requested
622    /// right away in a background thread, so that the network wait overlaps
623    /// with the use of the current page. After the first page it is not, so
624    /// that taking only the first page costs a single request.
625    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                // Without a thread the page is simply requested when it is needed.
635                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
647/// Iterator returned by [`Client::items`] and the generated `…_iter` methods.
648pub struct Items<T> {
649    fetcher: PageFetcher,
650    buffer: std::vec::IntoIter<T>,
651}
652
653impl<T> Items<T> {
654    /// Whether the next page is requested in the background while the current
655    /// one is being used (the default); see [`Pages::prefetch`].
656    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            // Kept loose: an unexpected `meta` only ends the pagination.
670            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            // One pass over the body for both the items and the page info.
678            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                // Nothing is pending any more: the iteration ends after an error.
685                Err(e) => return Some(Err(e)),
686            }
687        }
688    }
689}
690
691/// Iterator returned by [`Client::pages`].
692pub struct Pages {
693    fetcher: PageFetcher,
694}
695
696impl Pages {
697    /// Whether the next page is requested in a background thread while the
698    /// current one is being used (the default), so that the network wait
699    /// overlaps with decoding and processing.
700    ///
701    /// The first page is always requested on its own, so that taking only the
702    /// first page costs a single request. From the second page on, stopping
703    /// early can leave one more request in flight; it finishes in the
704    /// background and its response is discarded. With `false`, every page is
705    /// requested only when it is needed.
706    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
724/// Reads the whole body, but at most `limit` bytes.
725fn 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    // Reserve what the server announces, but not more than 1 MiB up front.
733    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
753/// Page number after `requested`, or `None` on the last page.
754fn next_page(meta: Option<Meta>, has_items: bool, requested: u64) -> Option<u64> {
755    let pagination = meta?.pagination?;
756    // Guard against servers that echo a page number we did not ask for, and
757    // against a `lastPage` that never comes (an empty page ends the list).
758    (has_items && pagination.current == requested && pagination.current < pagination.last_page)
759        .then_some(requested + 1)
760}
761
762/// [`next_page`] for a raw body; skips over `data` without decoding it.
763fn 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
774/// Whether `data` is anything but an empty list, without keeping its items.
775struct 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
824/// Wait time before a retry: the server's `Retry-After` (seconds or an HTTP
825/// date), or an exponential backoff (2, 4, 8 s) when the header is missing.
826fn 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    // `Wed, 21 Oct 2026 07:28:00 GMT`; a date in the past means no wait.
840    let at = chrono::DateTime::parse_from_rfc2822(value).ok()?;
841    Some((at.to_utc() - now).to_std().unwrap_or_default())
842}
843
844/// Decodes the `data` field of a response envelope.
845pub fn decode_data<T: DeserializeOwned>(bytes: &[u8]) -> Result<T> {
846    if bytes.trim_ascii().is_empty() {
847        return decode(bytes); // no envelope without a body
848    }
849    decode::<Envelope<T>>(bytes).map(|e| e.data).or_else(|err| {
850        // PHP encodes an empty associative array as `[]`; retry as `{}` for map results.
851        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
865/// Decodes a whole response body.
866pub fn decode<T: DeserializeOwned>(bytes: &[u8]) -> Result<T> {
867    if bytes.trim_ascii().is_empty() {
868        // 204 No Content: only an `Option` result (or `()`) accepts this.
869        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
880/// Parses the instance URL and returns the API root ending in `/api`.
881///
882/// Accepts a path prefix (`https://example.org/ct` becomes
883/// `https://example.org/ct/api`) and an existing `/api` suffix.
884fn 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
913/// Rejects paths the URL parser would rewrite or that address a different
914/// endpoint: `.` and `..` segments (also percent-encoded, which the parser
915/// resolves as well) and empty segments, e.g. from an ID `".."` or `""`.
916fn 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
938/// Percent-encodes a value for use as a single path segment.
939pub 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    /// Answers each connection with the next of `responses` (raw HTTP) and
950    /// records method and path of each request, e.g. `"POST /api/x"`.
951    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        // A blackholed address fails after the connect timeout, not after 600 s.
1003        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        // Without Content-Length the body ends when the connection closes.
1014        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"]); // no GET afterwards
1034    }
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        // An empty page ends the list even if `lastPage` says otherwise.
1100        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        // `meta` that is not an object only ends the pagination.
1118        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        // An error ends the iteration.
1135        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        // Only the first page is used: nothing else is requested.
1147        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        // Page 3 is requested in the background once page 2 is handed out, and
1155        // an error there shows up in its place.
1156        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, &copy.content)); // cloning shares the bytes
1179        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        // Nothing listens on the port: both attempts are refused, after one wait.
1230        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        // First call is immediate, the next three wait one interval each.
1249        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        // Raw paths: the URL parser treats percent-encoded dots as dots, too.
1269        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        // An ID `%2e%2e` is encoded to `%252e%252e` and reaches the server literally.
1275        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}