libdav/

carddav.rs

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

use std::ops::Deref;

use http::Response;
use hyper::body::Incoming;
use hyper::Uri;
use tower_service::Service;

use crate::common::{check_support, parse_find_multiple_collections, ServiceForUrlError};
use crate::dav::WebDavClient;
use crate::dav::{check_status, FoundCollection, WebDavError};
use crate::sd::{find_context_url, BootstrapError, DiscoverableService};
use crate::xmlutils::escape_xml_entities;
use crate::{names, Depth, FindHomeSetError};
use crate::{CheckSupportError, FetchedResource};

/// Client to communicate with a CardDAV server.
///
/// Instances are usually created via [`CardDavClient::new`]:
///
/// ```rust
/// # use libdav::CardDavClient;
/// # 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 https_client = Client::builder(TokioExecutor::new()).build(https_connector);
/// let https_client = AddAuthorization::basic(https_client, "user", "secret");
/// let webdav = WebDavClient::new(uri, https_client);
/// let client = CardDavClient::new(webdav);
/// # })
/// ```
///
/// If the real CardDAV server needs to be resolved via automated service discovery, use
/// [`CardDavClient::bootstrap_via_service_discovery`].
///
/// For setting the `Authorization` header or applying other changes to outgoing requests, see the
/// documentation on [`WebDavClient`].
#[derive(Debug)]
pub struct CardDavClient<C>
where
    C: Service<http::Request<String>, Response = Response<Incoming>> + Sync + Send + 'static,
{
    /// A WebDAV client used to send requests.
    pub webdav_client: WebDavClient<C>,
}

impl<C> Deref for CardDavClient<C>
where
    C: Service<http::Request<String>, Response = Response<Incoming>> + Sync + Send,
{
    type Target = WebDavClient<C>;

    fn deref(&self) -> &Self::Target {
        &self.webdav_client
    }
}

impl<C> CardDavClient<C>
where
    C: Service<http::Request<String>, Response = Response<Incoming>> + Sync + Send,
    <C as Service<http::Request<String>>>::Error: std::error::Error + Send + Sync,
{
    /// Create a new client instance.
    ///
    /// # See also
    ///
    /// [`CardDavClient::bootstrap_via_service_discovery`].
    pub fn new(webdav_client: WebDavClient<C>) -> CardDavClient<C> {
        CardDavClient { webdav_client }
    }

    /// Automatically bootstrap a new client instance.
    ///
    /// Creates a new client, with its `base_url` set to the context path retrieved using service
    /// discovery via [`find_context_url`].
    ///
    /// # Errors
    ///
    /// Returns an error if:
    ///
    /// - The URL has an invalid schema.
    /// - The underlying call to [`find_context_url`] returns an error.
    pub async fn bootstrap_via_service_discovery(
        mut webdav_client: WebDavClient<C>,
    ) -> Result<CardDavClient<C>, BootstrapError> {
        let service = service_for_url(&webdav_client.base_url)?;
        match find_context_url(&webdav_client, service).await {
            crate::sd::FindContextUrlResult::BaseUrl => {}
            crate::sd::FindContextUrlResult::Found(url) => webdav_client.base_url = url,
            crate::sd::FindContextUrlResult::NoneFound => return Err(BootstrapError::NoUsableUrl),
            crate::sd::FindContextUrlResult::Error(err) => return Err(err.into()),
        }
        Ok(CardDavClient { webdav_client })
    }

    /// Queries the server for the address book home set.
    ///
    /// See: <https://www.rfc-editor.org/rfc/rfc4791#section-6.2.1>
    ///
    /// # Errors
    ///
    /// If there are any network errors or the response could not be parsed.
    pub async fn find_address_book_home_set(
        &self,
        principal: &Uri,
    ) -> Result<Vec<Uri>, FindHomeSetError> {
        // If obtaining a principal fails, the specification says we should query the user. This
        // tries to use the `base_url` first, since the user might have provided it for a reason.
        self.find_home_sets(principal, &names::ADDRESSBOOK_HOME_SET)
            .await
            .map_err(FindHomeSetError)
    }

    /// Find address book collections under the given `url`.
    ///
    /// If `url` is not specified, this client's current `base_url` shall be used instead.  When
    /// using a client bootstrapped via automatic discovery, passing `None` will usually yield the
    /// expected results.
    ///
    /// # Errors
    ///
    /// If the HTTP call fails or parsing the XML response fails.
    pub async fn find_addressbooks(
        &self,
        address_book_home_set: &Uri,
    ) -> Result<Vec<FoundCollection>, WebDavError> {
        let props = [
            &names::RESOURCETYPE,
            &names::GETETAG,
            &names::SUPPORTED_REPORT_SET,
        ];
        let (head, body) = self
            .propfind(address_book_home_set, &props, Depth::One)
            .await?;
        check_status(head.status)?;

        parse_find_multiple_collections(&body, &names::ADDRESSBOOK)
    }

    /// Fetches existing vcard resources.
    ///
    /// If the `getetag` property is missing for an item, it will be reported as
    /// [`http::StatusCode::NOT_FOUND`]. This should not be an actual issue with in practice, since
    /// support for `getetag` is mandatory for CalDAV implementations.
    ///
    /// # Errors
    ///
    /// If there are any network errors or the response could not be parsed.
    pub async fn get_address_book_resources(
        &self,
        addressbook_href: &str,
        hrefs: impl IntoIterator<Item = impl AsRef<str>>,
    ) -> Result<Vec<FetchedResource>, WebDavError> {
        let mut body = String::from(
            r#"
            <C:addressbook-multiget xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:carddav">
                <D:prop>
                    <D:getetag/>
                    <C:address-data/>
                </D:prop>"#,
        );
        for href in hrefs {
            body.push_str("<D:href>");
            body.push_str(&escape_xml_entities(href.as_ref()));
            body.push_str("</D:href>");
        }
        body.push_str("</C:addressbook-multiget>");

        self.multi_get(addressbook_href.as_ref(), body, &names::ADDRESS_DATA)
            .await
    }

    /// Checks that the given URI advertises carddav support.
    ///
    /// See: <https://www.rfc-editor.org/rfc/rfc6352#section-6.1>
    ///
    /// # Known Issues
    ///
    /// - Nextcloud's implementation seems broken. [Bug report][nextcloud].
    ///
    /// [nextcloud]: https://github.com/nextcloud/server/issues/37374
    ///
    /// # Errors
    ///
    /// If there are any network issues or if the server does not explicitly advertise carddav
    /// support.
    pub async fn check_support(&self, url: &Uri) -> Result<(), CheckSupportError> {
        check_support(&self.webdav_client, url, "addressbook").await
    }

    /// Create an address book collection.
    ///
    /// # Errors
    ///
    /// Returns an error in case of network errors or if the server returns a failure status code.
    pub async fn create_addressbook(&self, href: &str) -> Result<(), WebDavError> {
        self.webdav_client
            .create_collection(href, &[&names::ADDRESSBOOK])
            .await
    }
}

/// Return the service type based on a URL's scheme.
///
/// # Errors
///
/// If `url` is missing a scheme or has a scheme invalid for CardDAV usage.
pub fn service_for_url(url: &Uri) -> Result<DiscoverableService, ServiceForUrlError> {
    match url
        .scheme()
        .ok_or(ServiceForUrlError::MissingScheme)?
        .as_ref()
    {
        "https" | "carddavs" => Ok(DiscoverableService::CardDavs),
        "http" | "carddav" => Ok(DiscoverableService::CardDav),
        _ => Err(ServiceForUrlError::UnknownScheme),
    }
}