libdav/

dav.rs

// Copyright 2023-2024 Hugo Osvaldo Barrera
//
// SPDX-License-Identifier: EUPL-1.2

//! Generic WebDAV implementation.
//!
//! This mostly implements the necessary bits for the CalDAV and CardDAV implementations. It should
//! not be considered a general purpose WebDAV implementation.
use std::{borrow::Cow, string::FromUtf8Error};

use http::{
    response::Parts, status::InvalidStatusCode, uri::PathAndQuery, Method, Request, Response,
    StatusCode, Uri,
};
use http_body_util::BodyExt;
use hyper::body::{Bytes, Incoming};
use log::debug;
use percent_encoding::percent_decode_str;
use tokio::sync::Mutex;
use tower::Service;

use crate::{
    names,
    sd::DiscoverableService,
    xmlutils::{
        check_multistatus, get_newline_corrected_text, get_unquoted_href, parse_statusline,
        quote_href, render_xml, render_xml_with_text,
    },
    FetchedResource, FetchedResourceContent, ItemDetails, PropertyName, ResourceType,
};

#[derive(thiserror::Error, Debug)]
pub enum RequestError {
    #[error("error executing http request: {0}")]
    Http(#[from] hyper::Error),

    #[error("client error executing request: {0}")]
    // TODO: remove dyn, make generic over client error type
    Client(Box<dyn std::error::Error + Send + Sync>),
}

/// Error for WebDAV operations.
#[derive(thiserror::Error, Debug)]
#[allow(clippy::module_name_repetitions)]
pub enum WebDavError {
    #[error("http client error: {0}")]
    Request(#[from] RequestError),

    #[error("missing field '{0}' in response XML")]
    MissingData(&'static str),

    #[error("invalid status code in response: {0}")]
    InvalidStatusCode(#[from] InvalidStatusCode),

    #[error("could not parse XML response: {0}")]
    Xml(#[from] roxmltree::Error),

    #[error("http request returned {0}")]
    BadStatusCode(http::StatusCode),

    #[error("failed to build URL with the given input: {0}")]
    InvalidInput(#[from] http::Error),

    #[error("the server returned an response with an invalid etag header: {0}")]
    InvalidEtag(#[from] FromUtf8Error),

    #[error("the server returned an invalid response: {0}")]
    InvalidResponse(Box<dyn std::error::Error + Send + Sync>),

    #[error("could not decode response as utf-8: {0}")]
    NotUtf8(#[from] std::str::Utf8Error),
}

impl From<StatusCode> for WebDavError {
    fn from(status: StatusCode) -> Self {
        WebDavError::BadStatusCode(status)
    }
}

#[derive(thiserror::Error, Debug)]
pub enum ResolveContextPathError {
    #[error("failed to create uri and request with given parameters: {0}")]
    BadInput(#[from] http::Error),

    #[error("error performing http request: {0}")]
    Request(#[from] RequestError),

    #[error("missing Location header in response")]
    MissingLocation,

    #[error("error building new Uri with Location from response: {0}")]
    BadLocation(#[from] http::uri::InvalidUri),
}

#[derive(thiserror::Error, Debug)]
pub enum FindCurrentUserPrincipalError {
    #[error("error performing webdav request: {0}")]
    RequestError(#[from] WebDavError),

    // XXX: This should not really happen, but the API for `http` won't let us validate this
    // earlier with a clear approach.
    #[error("cannot use base_url to build request uri: {0}")]
    InvalidInput(#[from] http::Error),
}

/// Generic WebDAV client.
///
/// A WebDAV client that uses a parametrised http client `C` to perform the underlying HTTP
/// requests.
///
/// An existing http client that can be used is `hyper_util::client::legacy::Client`, although any
/// client which implements the trait bounds is acceptable. Essentially an http clients needs to
/// implement [`tower::Service`], taking a [`Request<Service>`] as input and returning a
/// [`Response<Incoming>`].
///
/// This means that the provided http client can simply be one that wraps around an existing one.
/// These wrappers are called middleware in the Tower/Hyper ecosystem.
///
/// The most common and obvious example is one that adds an `Authorization` header to all outgoing
/// requests:
///
/// ```rust
/// # use libdav::dav::WebDavClient;
/// use http::Uri;
/// use hyper_rustls::HttpsConnectorBuilder;
/// use hyper_util::{client::legacy::Client, rt::TokioExecutor};
/// use tower_http::auth::AddAuthorization;
///
/// # tokio::runtime::Builder::new_current_thread().build().unwrap().block_on(async {
/// let uri = Uri::try_from("https://example.com").unwrap();
///
/// let https_connector = HttpsConnectorBuilder::new()
///     .with_native_roots()
///     .unwrap()
///     .https_or_http()
///     .enable_http1()
///     .build();
/// let http_client = Client::builder(TokioExecutor::new()).build(https_connector);
/// let auth_client = AddAuthorization::basic(http_client, "user", "secret");
/// let webdav = WebDavClient::new(uri, auth_client);
/// # })
/// ```
///
/// The concrete type of the client in the above example is somewhat complex. For this reason,
/// application code will usually want to use an alias for the concrete type being used, and use
/// this alias through all types and functions that handle the WebDAV client:
///
/// ```rust
/// # use hyper_rustls::HttpsConnector;
/// # use hyper_util::client::legacy::{connect::HttpConnector, Client};
/// # use libdav::dav::WebDavClient;
/// # use tower_http::auth::AddAuthorization;
/// type MyClient = WebDavClient<AddAuthorization<Client<HttpsConnector<HttpConnector>, String>>>;
/// ```
///
/// # Setting a custom User-Agent header
///
/// The following example uses a custom middleware  which sets a specific User-Agent on each
/// outgoing request:
///
/// ```rust
/// use std::task::{Context, Poll};
///
/// use hyper::{
///     header::{HeaderValue, USER_AGENT},
///     Request, Response,
/// };
/// use tower::Service;
///
/// #[derive(Debug, Clone)]
/// pub struct UserAgent<S> {
///     inner: S,
///     user_agent: HeaderValue,
/// }
///
/// impl<S> UserAgent<S> {
///     /// Add a custom User-Agent to outgoing requests.
///     pub fn new(inner: S, user_agent: HeaderValue) -> UserAgent<S> {
///         UserAgent { inner, user_agent }
///     }
/// }
///
/// impl<S, Tx, Rx> Service<Request<Tx>> for UserAgent<S>
/// where
///     S: Service<Request<Tx>, Response = Response<Rx>>,
/// {
///     type Response = S::Response;
///     type Error = S::Error;
///     type Future = S::Future;
///
///     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
///         self.inner.poll_ready(cx)
///     }
///
///     fn call(&mut self, mut req: Request<Tx>) -> Self::Future {
///         req.headers_mut()
///             .insert(USER_AGENT, self.user_agent.clone());
///         self.inner.call(req)
///     }
/// }
///
/// // Elsewhere in your codebase...
/// # use libdav::dav::WebDavClient;
/// use http::Uri;
/// use hyper_rustls::HttpsConnectorBuilder;
/// use hyper_util::{client::legacy::Client, rt::TokioExecutor};
/// use tower_http::auth::AddAuthorization;
///
/// # tokio::runtime::Builder::new_current_thread().build().unwrap().block_on(async {
/// let uri = Uri::try_from("https://example.com").unwrap();
///
/// let https_connector = HttpsConnectorBuilder::new()
///     .with_native_roots()
///     .unwrap()
///     .https_or_http()
///     .enable_http1()
///     .build();
/// let http_client = Client::builder(TokioExecutor::new()).build(https_connector);
/// let auth_client = UserAgent::new(http_client, "myapp/0.2.7".try_into().unwrap());
/// let webdav = WebDavClient::new(uri, auth_client);
/// # })
/// ```
///
/// For other generic middleware of this style, consult the [tower-http] crate.
///
/// [tower-http]: https://docs.rs/tower-http/
#[derive(Debug)]
pub struct WebDavClient<C>
where
    C: Service<http::Request<String>, Response = Response<Incoming>> + Sync + Send + 'static,
{
    /// Base URL to be used for all requests.
    ///
    /// This is composed of the domain+port used for the server, plus the context path where WebDAV
    /// requests are served.
    pub base_url: Uri,
    http_client: Mutex<C>,
}

impl<C> WebDavClient<C>
where
    C: Service<http::Request<String>, Response = Response<Incoming>> + Sync + Send,
    <C as Service<http::Request<String>>>::Error: std::error::Error + Send + Sync,
{
    /// Builds a new WebDAV client.
    pub fn new(base_url: Uri, http_client: C) -> WebDavClient<C> {
        WebDavClient {
            base_url,
            http_client: Mutex::from(http_client),
        }
    }

    /// Returns a URL pointing to the server's context path.
    pub fn base_url(&self) -> &Uri {
        &self.base_url
    }

    /// Returns a new URI relative to the server's root.
    ///
    /// # Errors
    ///
    /// If this client's `base_url` is invalid or the provided `path` is not an acceptable path.
    pub fn relative_uri(&self, path: impl AsRef<str>) -> Result<Uri, http::Error> {
        // XXX: Is escaping really necessary here? I can't find an example that breaks removing it.
        let href = quote_href(path.as_ref().as_bytes());
        let mut parts = self.base_url.clone().into_parts();
        parts.path_and_query = Some(PathAndQuery::try_from(href.as_ref())?);
        Uri::from_parts(parts).map_err(http::Error::from)
    }

    /// Resolves the current user's principal resource.
    ///
    /// First queries the `base_url`, then the root path on the same host.
    ///
    /// Returns `None` if the response's status code is 404 or if no principal was found.
    ///
    /// # Errors
    ///
    /// See [`FindCurrentUserPrincipalError`]
    ///
    /// # See also
    ///
    /// The `DAV:current-user-principal` property is defined in
    /// <https://www.rfc-editor.org/rfc/rfc5397#section-3>
    pub async fn find_current_user_principal(
        &self,
    ) -> Result<Option<Uri>, FindCurrentUserPrincipalError> {
        // Try querying the provided base url...
        let (head, body) = self
            .propfind(&self.base_url, &[&names::CURRENT_USER_PRINCIPAL], 0)
            .await?;
        check_status(head.status).map_err(WebDavError::BadStatusCode)?;
        let maybe_principal =
            extract_one_href(body, &self.base_url, &names::CURRENT_USER_PRINCIPAL);

        match maybe_principal {
            Err(WebDavError::BadStatusCode(StatusCode::NOT_FOUND)) | Ok(None) => {}
            Err(err) => return Err(FindCurrentUserPrincipalError::RequestError(err)),
            Ok(Some(p)) => return Ok(Some(p)),
        };
        debug!("User principal not found at base_url, trying root...");

        // ... Otherwise, try querying the root path.
        let root = self.relative_uri("/")?;
        let (head, body) = self
            .propfind(&root, &[&names::CURRENT_USER_PRINCIPAL], 0)
            .await?;
        check_status(head.status).map_err(WebDavError::BadStatusCode)?;
        extract_one_href(body, &root, &names::CURRENT_USER_PRINCIPAL)
            .map_err(FindCurrentUserPrincipalError::RequestError)

        // NOTE: If no principal is resolved, it needs to be provided interactively
        //       by the user. We use `base_url` as a fallback.
    }

    /// Internal helper to find multiple `href` properties.
    ///
    /// Very specific, but de-duplicates a few identical functions.
    pub(crate) async fn find_hrefs_prop_as_uri(
        &self,
        url: &Uri,
        property: &PropertyName<'_, '_>,
    ) -> Result<Vec<Uri>, WebDavError> {
        let (head, body) = self.propfind(url, &[property], 0).await?;
        check_status(head.status)?;
        extract_href_props(body, url, property)
    }

    /// Sends a `PROPFIND` request.
    ///
    /// This is a shortcut for simple `PROPFIND` requests.
    ///
    /// # Errors
    ///
    /// If there are any network errors.
    pub async fn propfind(
        &self,
        url: &Uri,
        properties: &[&PropertyName<'_, '_>],
        depth: u8,
    ) -> Result<(Parts, Bytes), WebDavError> {
        let mut body = String::from(r#"<propfind xmlns="DAV:"><prop>"#);
        for prop in properties {
            body.push_str(&render_xml(prop));
        }
        body.push_str("</prop></propfind>");

        let request = Request::builder()
            .method("PROPFIND")
            .uri(url)
            .header("Content-Type", "application/xml; charset=utf-8")
            .header("Depth", depth.to_string())
            .body(body)?;

        self.request(request).await.map_err(WebDavError::from)
    }

    /// Send a request to the server.
    ///
    /// Sends a request, applying any necessary authentication and logging the response.
    ///
    /// # Errors
    ///
    /// Returns an error if the underlying http request fails or if streaming the response fails.
    pub async fn request(&self, request: Request<String>) -> Result<(Parts, Bytes), RequestError> {
        // QUIRK: When trying to fetch a resource on a URL that is a collection, iCloud
        // will terminate the connection (which returns "unexpected end of file").

        let mut client = self.http_client.lock().await;
        let response_future = client.call(request);
        drop(client); // E.g.: unlock http_client.

        let response = response_future
            .await
            .map_err(|e| RequestError::Client(Box::from(e)))?;
        let (head, body) = response.into_parts();
        let body = body.collect().await?.to_bytes();

        log::trace!("Response ({}): {:?}", head.status, body);
        Ok((head, body))
    }

    /// Fetch a single property.
    ///
    /// # Common properties
    ///
    /// - [`names::ADDRESSBOOK_DESCRIPTION`]
    /// - [`names::CALENDAR_COLOUR`]
    /// - [`names::CALENDAR_DESCRIPTION`]
    /// - [`names::CALENDAR_ORDER`]
    /// - [`names::DISPLAY_NAME`]
    ///
    /// # Quirks
    ///
    /// The namespace of the value in the response from the server is ignored. This is a workaround
    /// for an [issue in `cyrus-imapd`][cyrus-issue].
    ///
    /// [cyrus-issue]: https://github.com/cyrusimap/cyrus-imapd/issues/4489
    ///
    /// # Errors
    ///
    /// - If there are any network errors or the response could not be parsed.
    /// - If the requested property is missing in the response.
    ///
    /// # See also
    ///
    /// - [`WebDavClient::set_property`]
    pub async fn get_property(
        &self,
        href: &str,
        property: &PropertyName<'_, '_>,
    ) -> Result<Option<String>, WebDavError> {
        let url = self.relative_uri(href)?;

        let (head, body) = self.propfind(&url, &[property], 0).await?;
        check_status(head.status)?;

        extract_one_prop(body, property)
    }

    /// Fetch multiple properties for a single resource.
    ///
    /// Values in the returned `Vec` are in the same order as the `properties` parameter.
    ///
    /// # Quirks
    ///
    /// Same as [`WebDavClient::get_property`].
    ///
    /// # Errors
    ///
    /// - If there are any network errors or the response could not be parsed.
    /// - If the requested property is missing in the response.
    ///
    /// # See also
    ///
    /// - [`WebDavClient::get_property`]
    /// - [`WebDavClient::set_property`]
    pub async fn get_properties<'ptr, 'p>(
        &self,
        href: &str,
        properties: &[&'ptr PropertyName<'p, 'p>],
    ) -> Result<Vec<(&'ptr PropertyName<'p, 'p>, Option<String>)>, WebDavError> {
        let url = self.relative_uri(href)?;

        let (head, body) = self.propfind(&url, properties, 0).await?;
        check_status(head.status)?;

        let body = std::str::from_utf8(body.as_ref())?;
        let doc = roxmltree::Document::parse(body)?;
        let root = doc.root_element();

        let mut results = Vec::with_capacity(properties.len());
        for property in properties {
            let prop = root
                .descendants()
                .find(|node| node.tag_name() == **property)
                // Hack to work around: https://github.com/cyrusimap/cyrus-imapd/issues/4489
                .or_else(|| {
                    root.descendants()
                        .find(|node| node.tag_name().name() == property.name())
                })
                // End hack
                .and_then(|p| p.text())
                .map(str::to_owned);

            results.push((*property, prop));
        }
        Ok(results)
    }

    /// Sends a `PROPUPDATE` query to the server.
    ///
    /// Setting the value to `None` will remove the property. Returns the new value as returned by
    /// the server.
    ///
    /// # Quirks
    ///
    /// Same as [`WebDavClient::get_property`].
    ///
    /// # Errors
    ///
    /// If there are any network errors or the response could not be parsed.
    ///
    /// # See also
    ///
    /// - [`WebDavClient::get_property`] (contains a list of some included well-known properties)
    // TODO: document whether the value needs to be escaped or not.
    pub async fn set_property(
        &self,
        href: &str,
        property: &PropertyName<'_, '_>,
        value: Option<&str>,
    ) -> Result<Option<String>, WebDavError> {
        let url = self.relative_uri(href)?;
        let action = match value {
            Some(_) => "set",
            None => "remove",
        };
        let inner = render_xml_with_text(property, value);
        let request = Request::builder()
            .method("PROPPATCH")
            .uri(url)
            .header("Content-Type", "application/xml; charset=utf-8")
            .body(format!(
                r#"<propertyupdate xmlns="DAV:">
                <{action}>
                    <prop>
                        {inner}
                    </prop>
                </{action}>
            </propertyupdate>"#
            ))?;

        let (head, body) = self.request(request).await?;
        check_status(head.status)?;

        extract_one_prop(body, property)
    }

    /// Resolve the default context path using a well-known path.
    ///
    /// This only applies for servers supporting WebDAV extensions like CalDAV or CardDAV. Returns
    /// `Ok(None)` if the well-known path does not redirect to another location.
    ///
    /// # Errors
    ///
    /// - If the provided scheme, host and port cannot be used to construct a valid URL.
    /// - If there are any network errors.
    /// - If the response is not an HTTP redirection.
    /// - If the `Location` header in the response is missing or invalid.
    ///
    /// # See also
    ///
    /// - <https://www.rfc-editor.org/rfc/rfc6764#section-5>
    /// - [`ResolveContextPathError`]
    #[allow(clippy::missing_panics_doc)] // panic condition is unreachable.
    pub async fn find_context_path(
        &self,
        service: DiscoverableService,
        host: &str,
        port: u16,
    ) -> Result<Option<Uri>, ResolveContextPathError> {
        let uri = Uri::builder()
            .scheme(service.scheme())
            .authority(format!("{host}:{port}"))
            .path_and_query(service.well_known_path())
            .build()?;

        let request = Request::builder()
            .method(Method::GET)
            .uri(uri)
            .body(String::new())?;

        // From https://www.rfc-editor.org/rfc/rfc6764#section-5:
        // > [...] the server MAY require authentication when a client tries to
        // > access the ".well-known" URI
        let (head, _body) = self.request(request).await?;
        log::debug!("Response finding context path: {}", head.status);

        if !head.status.is_redirection() {
            return Ok(None);
        }

        // TODO: multiple redirections...?
        let location = head
            .headers
            .get(hyper::header::LOCATION)
            .ok_or(ResolveContextPathError::MissingLocation)?
            .as_bytes();
        let uri = Uri::try_from(location)?;

        if uri.host().is_some() {
            return Ok(Some(uri)); // Uri is absolute.
        }

        let mut parts = uri.into_parts();
        if parts.scheme.is_none() {
            parts.scheme = Some(service.scheme());
        }
        if parts.authority.is_none() {
            parts.authority = Some(format!("{host}:{port}").try_into()?);
        }

        let uri = Uri::from_parts(parts).expect("uri parts are already validated");
        Ok(Some(uri))
    }

    /// Enumerates resources in a collection
    ///
    /// # Errors
    ///
    /// If there are any network errors or the response could not be parsed.
    pub async fn list_resources(
        &self,
        collection_href: &str,
    ) -> Result<Vec<ListedResource>, WebDavError> {
        let url = self.relative_uri(collection_href)?;

        let (head, body) = self
            .propfind(
                &url,
                &[
                    &names::RESOURCETYPE,
                    &names::GETCONTENTTYPE,
                    &names::GETETAG,
                ],
                1,
            )
            .await?;
        check_status(head.status)?;

        extract_listed_resources(body, collection_href)
    }

    /// Inner helper with common logic between `create` and `update`.
    async fn put(
        &self,
        href: impl AsRef<str>,
        data: Vec<u8>,
        etag: Option<impl AsRef<str>>,
        mime_type: impl AsRef<[u8]>,
    ) -> Result<Option<String>, WebDavError> {
        let mut builder = Request::builder()
            .method(Method::PUT)
            .uri(self.relative_uri(href)?)
            .header("Content-Type", mime_type.as_ref());

        builder = match etag {
            Some(etag) => builder.header("If-Match", etag.as_ref()),
            None => builder.header("If-None-Match", "*"),
        };

        let request = String::from_utf8(data)
            .map_err(|e| WebDavError::NotUtf8(e.utf8_error()))
            .map(|string| builder.body(string))??;

        let (head, _body) = self.request(request).await?;
        check_status(head.status)?;

        // TODO: check multi-response

        let new_etag = head
            .headers
            .get("etag")
            .map(|hv| String::from_utf8(hv.as_bytes().to_vec()))
            .transpose()?;
        Ok(new_etag)
    }

    /// Creates a new resource
    ///
    /// Returns an `Etag` if present in the response. If the `Etag` is not included, it must be
    /// requested in a follow-up request, and cannot be obtained race-free.
    ///
    /// # Errors
    ///
    /// If there are any network errors or the response could not be parsed.
    pub async fn create_resource(
        &self,
        href: impl AsRef<str>,
        data: Vec<u8>,
        mime_type: impl AsRef<[u8]>,
    ) -> Result<Option<String>, WebDavError> {
        self.put(href, data, Option::<&str>::None, mime_type).await
    }

    /// Updates an existing resource
    ///
    /// Returns an `Etag` if present in the response. If the `Etag` is not included, it must be
    /// requested in a follow-up request, and cannot be obtained race-free.
    ///
    /// # Errors
    ///
    /// If there are any network errors or the response could not be parsed.
    pub async fn update_resource(
        &self,
        href: impl AsRef<str>,
        data: Vec<u8>,
        etag: impl AsRef<str>,
        mime_type: impl AsRef<[u8]>,
    ) -> Result<Option<String>, WebDavError> {
        self.put(href, data, Some(etag.as_ref()), mime_type).await
    }

    /// Creates a collection under path `href`.
    ///
    /// This function executes an [Extended MKCOL](https://www.rfc-editor.org/rfc/rfc5689).
    ///
    /// Additional resource types may be specified via the `resourcetypes` argument. The
    /// `DAV:collection` resource type is implied and MUST NOT be specified.
    ///
    /// # Errors
    ///
    /// If there are any network errors or the response could not be parsed.
    pub async fn create_collection(
        &self,
        href: impl AsRef<str>,
        resourcetypes: &[&PropertyName<'_, '_>],
    ) -> Result<(), WebDavError> {
        let mut rendered_resource_types = String::new();
        for resource_type in resourcetypes {
            rendered_resource_types.push_str(&render_xml(resource_type));
        }

        let body = format!(
            r#"
            <mkcol xmlns="DAV:">
                <set>
                    <prop>
                        <resourcetype>
                            <collection/>
                            {rendered_resource_types}
                        </resourcetype>
                    </prop>
                </set>
            </mkcol>"#
        );

        let request = Request::builder()
            .method("MKCOL")
            .uri(self.relative_uri(href.as_ref())?)
            .header("Content-Type", "application/xml; charset=utf-8")
            .body(body)?;

        let (head, _body) = self.request(request).await?;
        // TODO: we should check the response body here, if present.
        // Some servers (e.g.: Fastmail) return an empty body.
        check_status(head.status)?;

        Ok(())
    }

    /// Deletes the resource at `href`.
    ///
    /// The resource MAY be a collection. Because the implementation for deleting resources and
    /// collections is identical, this same function is used for both cases.
    ///
    /// If the Etag does not match (i.e.: if the resource has been altered), the operation will
    /// fail and return an Error.
    ///
    /// # Errors
    ///
    /// If there are any network errors or the response could not be parsed.
    // TODO: document WHICH error is returned on Etag mismatch.
    pub async fn delete(
        &self,
        href: impl AsRef<str>,
        etag: impl AsRef<str>,
    ) -> Result<(), WebDavError> {
        let request = Request::builder()
            .method(Method::DELETE)
            .uri(self.relative_uri(href.as_ref())?)
            .header("Content-Type", "application/xml; charset=utf-8")
            .header("If-Match", etag.as_ref())
            .body(String::new())?;

        let (head, _body) = self.request(request).await?;

        check_status(head.status).map_err(WebDavError::BadStatusCode)
    }

    /// Force deletion of the resource at `href`.
    ///
    /// This function does not guarantee that a resource or collection has not been modified since
    /// it was last read. **Use this function with care**.
    ///
    /// The resource MAY be a collection. Because the implementation for deleting resources and
    /// collections is identical, this same function covers both cases.
    ///
    /// # Errors
    ///
    /// If there are any network errors or the response could not be parsed.
    pub async fn force_delete(&self, href: impl AsRef<str>) -> Result<(), WebDavError> {
        let request = Request::builder()
            .method(Method::DELETE)
            .uri(self.relative_uri(href.as_ref())?)
            .header("Content-Type", "application/xml; charset=utf-8")
            .body(String::new())?;

        let (head, _body) = self.request(request).await?;

        check_status(head.status).map_err(WebDavError::BadStatusCode)
    }

    pub(crate) async fn multi_get(
        &self,
        collection_href: &str,
        body: String,
        property: &PropertyName<'_, '_>,
    ) -> Result<Vec<FetchedResource>, WebDavError> {
        let request = Request::builder()
            .method("REPORT")
            .uri(self.relative_uri(collection_href)?)
            .header("Content-Type", "application/xml; charset=utf-8")
            .body(body)?;

        let (head, body) = self.request(request).await?;
        check_status(head.status)?;

        extract_fetched_resources(body, property)
    }
}

/// Make a new url using the schema and authority from `base` with the supplied `path`.
///
/// # Errors
///
/// If this client's `base_url` is invalid or the provided `path` is not an acceptable path.
fn make_relative_url(base: Uri, path: impl AsRef<[u8]>) -> Result<Uri, http::Error> {
    // TODO: should this escape anything? See comment in WebDavClient::relative_uri above.
    // let path = quote_href(path.as_ref());
    let mut parts = base.into_parts();
    parts.path_and_query = Some(PathAndQuery::try_from(path.as_ref())?);
    Uri::from_parts(parts).map_err(http::Error::from)
}

/// Checks if the status code is success. If it is not, return it as an error.
#[inline]
pub(crate) fn check_status(status: StatusCode) -> Result<(), StatusCode> {
    if status.is_success() {
        Ok(())
    } else {
        Err(status)
    }
}

pub mod mime_types {
    pub const CALENDAR: &[u8] = b"text/calendar";
    pub const ADDRESSBOOK: &[u8] = b"text/vcard";
}

/// Metadata for a resource.
///
/// This type is returned when listing resources. It contains metadata on
/// resources but no the resource data itself.
#[derive(Debug, PartialEq)]
pub struct ListedResource {
    pub details: ItemDetails,
    /// This value is not URL-encoded.
    pub href: String,
    /// Status code for this resource, as returned by the server.
    pub status: Option<StatusCode>,
}

/// Metadata for a collection.
///
/// This type is returned when listing collections. It contains metadata on
/// collection itself, but not the entires themselves.
#[derive(Debug)]
pub struct FoundCollection {
    /// This value is not URL-encoded.
    pub href: String,
    pub etag: Option<String>,
    /// From: <https://www.rfc-editor.org/rfc/rfc6578>
    pub supports_sync: bool,
    // TODO: query displayname by default too.
}

/// Extract an URL from a multi-response.
///
/// Extract the `href` property from a single property tag matching `property`.
/// Returned URLs are made relative to the provided URL.
pub(crate) fn extract_one_href(
    body: impl AsRef<[u8]>,
    url: &Uri,
    property: &PropertyName<'_, '_>,
) -> Result<Option<Uri>, WebDavError> {
    let body = std::str::from_utf8(body.as_ref())?;
    let doc = roxmltree::Document::parse(body)?;
    let root = doc.root_element();

    let props = root
        .descendants()
        .filter(|node| node.tag_name() == *property)
        .collect::<Vec<_>>();

    if props.len() == 1 {
        if let Some(href_node) = props[0]
            .children()
            .find(|node| node.tag_name() == names::HREF)
        {
            if let Some(href) = href_node.text().map(percent_decode_str) {
                let href = make_relative_url(url.clone(), Cow::from(href))
                    .map_err(|e| WebDavError::InvalidResponse(Box::from(e)))?;
                return Ok(Some(href));
            };
            return Ok(None);
        }
    }

    check_multistatus(root)?;

    Err(WebDavError::InvalidResponse(
        "missing property in response but no error".into(),
    ))
}

fn extract_one_prop(
    body: impl AsRef<[u8]>,
    property: &PropertyName<'_, '_>,
) -> Result<Option<String>, WebDavError> {
    let body = std::str::from_utf8(body.as_ref())?;
    let doc = roxmltree::Document::parse(body)?;
    let root = doc.root_element();

    let prop = root.descendants().find(|node| node.tag_name() == *property);

    if let Some(prop) = prop {
        return Ok(prop.text().map(str::to_string));
    }

    check_multistatus(root)?;

    Err(WebDavError::InvalidResponse(
        "Property is missing from response, but response is non-error.".into(),
    ))
}

fn extract_listed_resources(
    body: impl AsRef<[u8]>,
    collection_href: &str,
) -> Result<Vec<ListedResource>, WebDavError> {
    let body = std::str::from_utf8(body.as_ref())?;
    let doc = roxmltree::Document::parse(body)?;
    let root = doc.root_element();
    let responses = root
        .descendants()
        .filter(|node| node.tag_name() == names::RESPONSE);

    let mut items = Vec::new();
    for response in responses {
        let href = get_unquoted_href(&response)?.to_string();

        // Don't list the collection itself.
        // INVARIANT: href has been unquoted. collection_href parameter MUST NOT be URL-encoded.
        if href == collection_href {
            continue;
        }

        let status = response
            .descendants()
            .find(|node| node.tag_name() == names::STATUS)
            .and_then(|node| node.text().map(str::to_string))
            .map(parse_statusline)
            .transpose()?;
        let etag = response
            .descendants()
            .find(|node| node.tag_name() == names::GETETAG)
            .and_then(|node| node.text().map(str::to_string));
        let content_type = response
            .descendants()
            .find(|node| node.tag_name() == names::GETCONTENTTYPE)
            .and_then(|node| node.text().map(str::to_string));
        let resource_type = if let Some(r) = response
            .descendants()
            .find(|node| node.tag_name() == names::RESOURCETYPE)
        {
            ResourceType {
                is_calendar: r.descendants().any(|n| n.tag_name() == names::CALENDAR),
                is_collection: r.descendants().any(|n| n.tag_name() == names::COLLECTION),
                is_address_book: r.descendants().any(|n| n.tag_name() == names::ADDRESSBOOK),
            }
        } else {
            ResourceType::default()
        };

        items.push(ListedResource {
            details: ItemDetails {
                content_type,
                etag,
                resource_type,
            },
            href,
            status,
        });
    }

    Ok(items)
}

fn extract_fetched_resources(
    body: impl AsRef<[u8]>,
    property: &PropertyName<'_, '_>,
) -> Result<Vec<FetchedResource>, WebDavError> {
    let body = std::str::from_utf8(body.as_ref())?;
    let doc = roxmltree::Document::parse(body)?;
    let responses = doc
        .root_element()
        .descendants()
        .filter(|node| node.tag_name() == names::RESPONSE);

    let mut items = Vec::new();
    for response in responses {
        let status = match check_multistatus(response) {
            Ok(()) => None,
            Err(WebDavError::BadStatusCode(status)) => Some(status),
            Err(e) => return Err(e),
        };

        let has_propstat = response // There MUST be zero or one propstat.
            .descendants()
            .any(|node| node.tag_name() == names::PROPSTAT);

        if has_propstat {
            let href = get_unquoted_href(&response)?.to_string();

            if let Some(status) = status {
                items.push(FetchedResource {
                    href,
                    content: Err(status),
                });
                continue;
            }

            let etag = response
                .descendants()
                .find(|node| node.tag_name() == crate::names::GETETAG)
                .ok_or(WebDavError::InvalidResponse(
                    "missing etag in response".into(),
                ))?
                .text()
                .ok_or(WebDavError::InvalidResponse("missing text in etag".into()))?
                .to_string();
            let data = get_newline_corrected_text(&response, property)?;

            items.push(FetchedResource {
                href,
                content: Ok(FetchedResourceContent { data, etag }),
            });
        } else {
            let hrefs = response
                .descendants()
                .filter(|node| node.tag_name() == names::HREF);

            for href in hrefs {
                let href = href
                    .text()
                    .map(percent_decode_str)
                    .ok_or(WebDavError::InvalidResponse("missing text in href".into()))?
                    .decode_utf8()?
                    .to_string();
                let status = status.ok_or(WebDavError::InvalidResponse(
                    "missing props but no error status code".into(),
                ))?;
                items.push(FetchedResource {
                    href,
                    content: Err(status),
                });
            }
        }
    }

    Ok(items)
}

/// Extract URLs from a multi-response.
///
/// Extract the `href` property from each property tag matching `property`.
/// Returned URLs are made relative to the provided URL.
fn extract_href_props(
    body: impl AsRef<[u8]>,
    url: &Uri,
    property: &PropertyName<'_, '_>,
) -> Result<Vec<Uri>, WebDavError> {
    let body = std::str::from_utf8(body.as_ref())?;
    let doc = roxmltree::Document::parse(body)?;
    let root = doc.root_element();

    let props = root
        .descendants()
        .filter(|node| node.tag_name() == *property)
        .collect::<Vec<_>>();

    if props.len() == 1 {
        let mut hrefs = Vec::new();

        let href_nodes = props[0]
            .children()
            .filter(|node| node.tag_name() == names::HREF);

        for href_node in href_nodes {
            if let Some(href) = href_node.text().map(percent_decode_str) {
                let url = make_relative_url(url.clone(), Cow::from(href))
                    .map_err(|e| WebDavError::InvalidResponse(Box::from(e)))?;
                hrefs.push(url);
            };
        }

        return Ok(hrefs);
    }

    check_multistatus(root)?;

    Err(WebDavError::InvalidResponse(
        "missing property in response but no error".into(),
    ))
}

#[cfg(test)]
mod more_tests {

    use http::{StatusCode, Uri};

    use crate::{
        dav::{
            extract_fetched_resources, extract_listed_resources, extract_one_href,
            extract_one_prop, ListedResource,
        },
        names::{self, CALENDAR_COLOUR, CALENDAR_DATA, CURRENT_USER_PRINCIPAL, DISPLAY_NAME},
        FetchedResource, FetchedResourceContent, ItemDetails, ResourceType,
    };

    use super::extract_href_props;

    #[test]
    fn test_multi_get_parse() {
        let raw = br#"
<multistatus xmlns="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav" xmlns:CS="http://calendarserver.org/ns/">
  <response>
    <href>/dav/calendars/user/vdirsyncer@fastmail.com/cc396171-0227-4e1c-b5ee-d42b5e17d533/</href>
    <propstat>
      <prop>
        <resourcetype>
          <collection/>
          <C:calendar/>
        </resourcetype>
        <getcontenttype>text/calendar; charset=utf-8</getcontenttype>
        <getetag>"1591712486-1-1"</getetag>
      </prop>
      <status>HTTP/1.1 200 OK</status>
    </propstat>
  </response>
  <response>
    <href>/dav/calendars/user/vdirsyncer@fastmail.com/cc396171-0227-4e1c-b5ee-d42b5e17d533/395b00a0-eebc-40fd-a98e-176a06367c82.ics</href>
    <propstat>
      <prop>
        <resourcetype/>
        <getcontenttype>text/calendar; charset=utf-8; component=VEVENT</getcontenttype>
        <getetag>"e7577ff2b0924fe8e9a91d3fb2eb9072598bf9fb"</getetag>
      </prop>
      <status>HTTP/1.1 200 OK</status>
    </propstat>
  </response>
</multistatus>"#;

        let results = extract_listed_resources(
            raw,
            "/dav/calendars/user/vdirsyncer@fastmail.com/cc396171-0227-4e1c-b5ee-d42b5e17d533/",
        )
        .unwrap();

        assert_eq!(results, vec![ListedResource {
            details: ItemDetails {
                content_type: Some("text/calendar; charset=utf-8; component=VEVENT".into()),
                etag: Some("\"e7577ff2b0924fe8e9a91d3fb2eb9072598bf9fb\"".into()),
                resource_type: ResourceType {
                    is_collection: false,
                    is_calendar: false,
                    is_address_book: false
                },
            },
            href: "/dav/calendars/user/vdirsyncer@fastmail.com/cc396171-0227-4e1c-b5ee-d42b5e17d533/395b00a0-eebc-40fd-a98e-176a06367c82.ics".into(),
            status: Some(StatusCode::OK),
        }]);
    }

    #[test]
    fn test_list_resources_parse_404() {
        // As returned by Xandikos (over a Unix socket):
        let raw = br#"
<ns0:multistatus xmlns:ns0="DAV:">
    <ns0:response>
        <ns0:href>http%3A//2f746d702f736f636b6574/user/contacts/Default</ns0:href>
        <ns0:status>HTTP/1.1 404 Not Found</ns0:status>
    </ns0:response>
</ns0:multistatus>
"#;

        let results = extract_listed_resources(raw, "/user/contacts/Default").unwrap();

        assert_eq!(
            results,
            vec![ListedResource {
                details: ItemDetails {
                    content_type: None,
                    etag: None,
                    resource_type: ResourceType {
                        is_collection: false,
                        is_calendar: false,
                        is_address_book: false
                    }
                },
                href: "http://2f746d702f736f636b6574/user/contacts/Default".to_string(),
                status: Some(StatusCode::NOT_FOUND),
            }]
        );
    }

    #[test]
    fn test_multi_get_parse_with_err() {
        let raw = br#"
<ns0:multistatus xmlns:ns0="DAV:" xmlns:ns1="urn:ietf:params:xml:ns:caldav">
  <ns0:response>
    <ns0:href>/user/calendars/Q208cKvMGjAdJFUw/qJJ9Li5DPJYr.ics</ns0:href>
    <ns0:propstat>
      <ns0:status>HTTP/1.1 200 OK</ns0:status>
      <ns0:prop>
        <ns0:getetag>"adb2da8d3cb1280a932ed8f8a2e8b4ecf66d6a02"</ns0:getetag>
        <ns1:calendar-data>CALENDAR-DATA-HERE</ns1:calendar-data>
      </ns0:prop>
    </ns0:propstat>
  </ns0:response>
  <ns0:response>
    <ns0:href>/user/calendars/Q208cKvMGjAdJFUw/rKbu4uUn.ics</ns0:href>
    <ns0:status>HTTP/1.1 404 Not Found</ns0:status>
  </ns0:response>
</ns0:multistatus>
"#;

        let results = extract_fetched_resources(raw, &CALENDAR_DATA).unwrap();

        assert_eq!(
            results,
            vec![
                FetchedResource {
                    href: "/user/calendars/Q208cKvMGjAdJFUw/qJJ9Li5DPJYr.ics".into(),
                    content: Ok(FetchedResourceContent {
                        data: "CALENDAR-DATA-HERE".into(),
                        etag: "\"adb2da8d3cb1280a932ed8f8a2e8b4ecf66d6a02\"".into(),
                    })
                },
                FetchedResource {
                    href: "/user/calendars/Q208cKvMGjAdJFUw/rKbu4uUn.ics".into(),
                    content: Err(StatusCode::NOT_FOUND)
                }
            ]
        );
    }

    #[test]
    fn test_multi_get_parse_mixed() {
        let raw = br#"
<d:multistatus xmlns:d="DAV:" xmlns:cal="urn:ietf:params:xml:ns:caldav">
    <d:response>
        <d:href>/remote.php/dav/calendars/vdirsyncer/1678996875/</d:href>
        <d:propstat>
            <d:prop>
                <d:resourcetype>
                    <d:collection/>
                    <cal:calendar/>
                </d:resourcetype>
            </d:prop>
            <d:status>HTTP/1.1 200 OK</d:status>
        </d:propstat>
        <d:propstat>
            <d:prop>
                <d:getetag/>
            </d:prop>
            <d:status>HTTP/1.1 404 Not Found</d:status>
        </d:propstat>
    </d:response>
</d:multistatus>"#;

        let results = extract_fetched_resources(raw, &CALENDAR_DATA).unwrap();

        assert_eq!(
            results,
            vec![FetchedResource {
                href: "/remote.php/dav/calendars/vdirsyncer/1678996875/".into(),
                content: Err(StatusCode::NOT_FOUND)
            }]
        );
    }

    #[test]
    fn test_multi_get_parse_encoding() {
        let b = r#"<?xml version="1.0" encoding="utf-8"?>
<multistatus xmlns="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav">
  <response>
    <href>/dav/calendars/user/hugo@whynothugo.nl/2100F960-2655-4E75-870F-CAA793466105/0F276A13-FBF3-49A1-8369-65EEA9C6F891.ics</href>
    <propstat>
      <prop>
        <getetag>"4219b87012f42ce7c4db55599aa3b579c70d8795"</getetag>
        <C:calendar-data><![CDATA[BEGIN:VCALENDAR
CALSCALE:GREGORIAN
PRODID:-//Apple Inc.//iOS 17.0//EN
VERSION:2.0
BEGIN:VTODO
COMPLETED:20230425T155913Z
CREATED:20210622T182718Z
DTSTAMP:20230915T132714Z
LAST-MODIFIED:20230425T155913Z
PERCENT-COMPLETE:100
SEQUENCE:1
STATUS:COMPLETED
SUMMARY:Comidas: ñoquis, 西红柿
UID:0F276A13-FBF3-49A1-8369-65EEA9C6F891
X-APPLE-SORT-ORDER:28
END:VTODO
END:VCALENDAR
]]></C:calendar-data>
      </prop>
      <status>HTTP/1.1 200 OK</status>
    </propstat>
  </response>
</multistatus>"#;

        let resources = extract_fetched_resources(b, &names::CALENDAR_DATA).unwrap();
        let content = resources.into_iter().next().unwrap().content.unwrap();
        assert!(content.data.contains("ñoquis"));
        assert!(content.data.contains("西红柿"));
    }

    /// See: <https://github.com/RazrFalcon/roxmltree/issues/108>
    #[test]
    fn test_multi_get_parse_encoding_another() {
        let b = "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<multistatus xmlns=\"DAV:\" xmlns:C=\"urn:ietf:params:xml:ns:caldav\">\n  <response>\n    <href>/dav/calendars/user/hugo@whynothugo.nl/2100F960-2655-4E75-870F-CAA793466105/0F276A13-FBF3-49A1-8369-65EEA9C6F891.ics</href>\n    <propstat>\n      <prop>\n        <getetag>\"4219b87012f42ce7c4db55599aa3b579c70d8795\"</getetag>\n        <C:calendar-data><![CDATA[BEGIN(baño)END\r\n]]></C:calendar-data>\n      </prop>\n      <status>HTTP/1.1 200 OK</status>\n    </propstat>\n  </response>\n</multistatus>\n";
        let resources = extract_fetched_resources(b, &names::CALENDAR_DATA).unwrap();
        let content = resources.into_iter().next().unwrap().content.unwrap();
        assert!(content.data.contains("baño"));
    }

    #[test]
    fn test_parse_prop_href() {
        let raw = br#"
<multistatus xmlns="DAV:">
  <response>
    <href>/dav/calendars</href>
    <propstat>
      <prop>
        <current-user-principal>
          <href>/dav/principals/user/vdirsyncer@example.com/</href>
        </current-user-principal>
      </prop>
      <status>HTTP/1.1 200 OK</status>
    </propstat>
  </response>
</multistatus>"#;

        let results = extract_one_href(
            raw,
            &Uri::try_from("https://example.com/").unwrap(),
            &CURRENT_USER_PRINCIPAL,
        )
        .unwrap();

        assert_eq!(
            results,
            Some(
                Uri::try_from("https://example.com/dav/principals/user/vdirsyncer@example.com/")
                    .unwrap()
            )
        );
    }

    #[test]
    fn test_parse_prop_cdata() {
        let raw = br#"
            <multistatus xmlns="DAV:">
                <response>
                    <href>/path</href>
                    <propstat>
                        <prop>
                            <displayname><![CDATA[test calendar]]></displayname>
                        </prop>
                        <status>HTTP/1.1 200 OK</status>
                    </propstat>
                </response>
            </multistatus>
            "#;

        let results = extract_one_prop(raw, &DISPLAY_NAME).unwrap();

        assert_eq!(results, Some("test calendar".into()));
    }

    #[test]
    fn test_parse_prop_text() {
        let raw = br#"
<ns0:multistatus xmlns:ns0="DAV:" xmlns:ns1="http://apple.com/ns/ical/">
  <ns0:response>
    <ns0:href>/user/calendars/pxE4Wt4twPqcWPbS/</ns0:href>
    <ns0:propstat>
      <ns0:status>HTTP/1.1 200 OK</ns0:status>
      <ns0:prop>
        <ns1:calendar-color>#ff00ff</ns1:calendar-color>
      </ns0:prop>
    </ns0:propstat>
  </ns0:response>
</ns0:multistatus>"#;

        let results = extract_one_prop(raw, &CALENDAR_COLOUR).unwrap();
        assert_eq!(results, Some("#ff00ff".into()));

        extract_one_prop(raw, &DISPLAY_NAME).unwrap_err();
    }

    #[test]
    fn test_parse_prop() {
        // As returned by Fastmail.
        let body = concat!(
            "<?xml version=\"1.0\" encoding=\"utf-8\"?>",
            "<multistatus xmlns=\"DAV:\" xmlns:XB875=\"http://apple.com/ns/ical/\">",
            "<response>",
            "<href>/dav/calendars/user/vdirsyncer@fastmail.com/jEZCzRA0bV3DnRXD/</href>",
            "<propstat>",
            "<prop>",
            "<XB875:calendar-color><![CDATA[#ff00ff]]></XB875:calendar-color>",
            "</prop>",
            "<status>HTTP/1.1 200 OK</status>",
            "</propstat>",
            "</response>",
            "</multistatus>",
        );
        let parsed = extract_one_prop(body, &names::CALENDAR_COLOUR).unwrap();
        assert_eq!(parsed, Some(String::from("#ff00ff")));
    }

    #[test]
    fn test_find_hrefs_prop_as_uri() {
        // As returned by xandikos.
        let body = concat!(
            "<ns0:multistatus xmlns:ns0=\"DAV:\" xmlns:ns1=\"urn:ietf:params:xml:ns:carddav\">",
            "<ns0:response>",
            "<ns0:href>/user/</ns0:href>",
            "<ns0:propstat>",
            "<ns0:status>HTTP/1.1 200 OK</ns0:status>",
            "<ns0:prop>",
            "<ns1:addressbook-home-set>",
            "<ns0:href>/user/contacts/</ns0:href>",
            "</ns1:addressbook-home-set>",
            "</ns0:prop>",
            "</ns0:propstat>",
            "</ns0:response>",
            "</ns0:multistatus>",
        );
        let url = "http://localhost:8000/user/".parse().unwrap();
        let prop = names::ADDRESSBOOK_HOME_SET;

        let parsed = extract_href_props(body, &url, &prop).unwrap();
        let expected = "http://localhost:8000/user/contacts/"
            .parse::<Uri>()
            .unwrap();
        assert_eq!(parsed, vec![expected]);
    }
}