vstorage 0.6.0

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

//! Traits and common implementations shared by different storages.
//!
//! When writing code that should deal with different storage implementations, these traits should
//! be used as input / outputs, rather than concrete per-store types.
//!
//! See [`Storage`] as an entry point to this module.

use std::{str::FromStr, sync::Arc, time::Duration};

use async_trait::async_trait;
use libdav::PropertyName;
use sha2::{Digest as _, Sha256};
use vparser::Parser;

use crate::{
    CollectionId, ErrorKind, Etag, Href, ItemKind, Result,
    addressbook::AddressBookProperty,
    calendar::CalendarProperty,
    disco::Discovery,
    hash::hash_normalized,
    watch::{IntervalMonitor, StorageMonitor},
};

/// A storage is the highest level abstraction where items can be stored. It can be a remote CalDAV
/// account, a local filesystem, etc.
///
/// Each storage may contain one or more **collections** (e.g.: calendars or address books).
///
/// # Note for implementors
///
/// The auto-generated documentation for this trait is rather hard to read due to the usage of
/// [`#[async_trait]`](mod@async_trait) macro. You might want to consider clicking on the
/// `source` link and reading the documentation from the raw code for this trait.
#[async_trait]
pub trait Storage: Sync + Send {
    // TODO: Some calendar instances only allow a single item type (e.g.: events but not todos).

    /// Return the kind of item this storage can handle.
    fn item_kind(&self) -> ItemKind;

    /// Checks that the storage works. This includes validating credentials, and reachability.
    ///
    /// # Errors
    ///
    /// Returns an error if the storage is not reachable and usable.
    async fn check(&self) -> Result<()>;

    /// Finds existing collections for this storage.
    async fn discover_collections(&self) -> Result<Discovery>;

    /// Creates a new collection with a specified `href`.
    async fn create_collection(&self, href: &str) -> Result<Collection>;

    /// Deletes an existing collection.
    ///
    /// A collection must be empty for deletion to succeed.
    async fn delete_collection(&self, href: &str) -> Result<()>;

    /// List all properties of a collection.
    async fn list_properties(&self, collection_href: &str) -> Result<Vec<FetchedProperty>> {
        // TODO: should run concurrency (requires storage implementations to handle throughput).
        let properties = Property::known_properties(self.item_kind());
        let mut result = Vec::with_capacity(properties.len());
        for &property in properties {
            if let Some(value) = self.get_property(collection_href, property).await? {
                result.push(FetchedProperty { property, value });
            }
        }
        Ok(result)
    }

    /// Returns the value of a property for a given collection.
    async fn get_property(&self, href: &str, property: Property) -> Result<Option<String>>;

    /// Sets the value of a property for a given collection.
    async fn set_property(&self, href: &str, property: Property, value: &str) -> Result<()>;

    /// Unsets a property for a given collection.
    async fn unset_property(&self, href: &str, property: Property) -> Result<()>;

    /// Enumerates items in a given collection.
    async fn list_items(&self, collection_href: &str) -> Result<Vec<ItemVersion>>;

    /// Fetches a single item from given collection.
    ///
    /// Storages never cache data locally. For reading items in bulk, prefer
    /// [`Storage::get_many_items`].
    async fn get_item(&self, href: &str) -> Result<(Item, Etag)>;

    /// Fetches multiple items.
    ///
    /// Similar to [`Storage::get_item`], but optimised to minimise the amount of IO required.
    /// Duplicate `href`s are ignored.
    ///
    /// All requested items MUST belong to the same collection.
    ///
    /// # Note for implementers
    ///
    /// The default implementation is usually not optimal, and implementations of this trait should
    /// override it.
    async fn get_many_items(&self, hrefs: &[&str]) -> Result<Vec<FetchedItem>> {
        // TODO: should run concurrency (requires storage implementations to handle throughput).
        let mut items = Vec::with_capacity(hrefs.len());
        for href in hrefs {
            let item = self.get_item(href).await?;
            items.push(FetchedItem {
                href: (*href).to_owned(),
                item: item.0,
                etag: item.1,
            });
        }
        Ok(items)
    }

    /// Fetch all items from a given collection.
    ///
    /// # Note for implementers
    ///
    /// The default implementation is usually not optimal, and implementations of this trait should
    /// override it.
    async fn get_all_items(&self, collection: &str) -> Result<Vec<FetchedItem>> {
        // TODO: should run concurrency (requires storage implementations to handle throughput).
        let item_vers = self.list_items(collection).await?;
        let mut items = Vec::with_capacity(item_vers.len());
        for item_ver in item_vers {
            let item = self.get_item(&item_ver.href).await?;
            items.push(FetchedItem {
                href: item_ver.href,
                item: item.0,
                etag: item.1,
            });
        }
        Ok(items)
    }

    /// Saves a new item into a given collection
    async fn create_item(
        &self,
        collection: &str,
        item: &Item,
        opts: CreateItemOptions,
    ) -> Result<ItemVersion>;

    /// Updates the contents of an existing item.
    async fn update_item(&self, href: &str, etag: &Etag, item: &Item) -> Result<Etag>;

    /// Deletes an existing item.
    async fn delete_item(&self, href: &str, etag: &Etag) -> Result<()>;

    /// Return the `href` for a collection that is expected to have `id`.
    ///
    /// Creating a collection under `href` SHOULD result in the collection being available via
    /// discovery with the provided `id`.
    ///
    /// # Errors
    ///
    /// Returns an error if no collection can exist such that it is available via discovery AND its
    /// `CollectionId` matches the input.
    fn href_for_collection_id(&self, id: &CollectionId) -> Result<Href>;

    /// Monitor the storage for changes.
    ///
    /// Returns a future that resolves into a [`StorageMonitor`] instance, which can be polled for
    /// new events on the underlying storage.
    ///
    /// # Errors
    ///
    /// If an error occurs setting up the monitor. In cases where monitoring is not possible due to
    /// limitations in the underlying storage, the `interval` should be used instead.
    async fn monitor(&self, interval: Duration) -> Result<Box<dyn StorageMonitor>> {
        Ok(Box::new(IntervalMonitor::new(interval)) as Box<dyn StorageMonitor>)
    }

    /// Fetched items that changed since the given sync token.
    ///
    /// Enables efficient incremental synchronisation for backends that support collection-level
    /// change tracking. Some storages may not support this operation; callers must have a fallback
    /// for such situations.
    ///
    /// When `since_state` is `None`, returns all current items as "changed" along with the
    /// initial sync token.
    ///
    /// # Errors
    ///
    /// Returns [`ErrorKind::Unsupported`] if the storage type doesn't implement state-based
    /// change tracking at all (e.g., filesystem, webcal).
    ///
    /// Returns [`ErrorKind::Unavailable`] if the storage type supports this feature but the
    /// specific server doesn't have it enabled.
    ///
    /// Returns other error variants in case of any other error.
    async fn changed_since(
        &self,
        _collection: &str,
        _since_state: Option<&str>,
    ) -> Result<CollectionChanges> {
        Err(ErrorKind::Unsupported.into())
    }
}

/// Options for [`Storage::create_item`].
#[derive(Default, Clone)]
pub struct CreateItemOptions {
    /// Create the new item with resource name.
    ///
    /// Use this name as the last component in the item's path, if possible.
    pub href: Option<Href>,
}

/// Path to a collection (an address book or a calendar) inside a storage.
///
/// Collections contain zero or more items (e.g.: an address book contains events). Each item is
/// addressed by its own [`Href`].
///
/// This type wraps around the `href` for a collection on a given storage. The same `Collection`
/// instance should not be shared across different storages.
#[derive(Debug)]
pub struct Collection {
    href: Href,
}

impl Collection {
    /// The path to this collection inside the storage.
    ///
    /// An href must not change over time, and should be associated with an immutable property of the
    /// collection, like a URL path component, or the path to a directory.
    ///
    /// The exact meaning of this value is storage-specific, but should be remain consistent within
    /// a storage.
    #[must_use]
    pub fn href(&self) -> &Href {
        &self.href
    }

    /// Return the inner [`Href`] instance.
    #[must_use]
    pub fn into_href(self) -> Href {
        self.href
    }

    pub(crate) fn new(href: String) -> Collection {
        Collection { href }
    }
}

/// Reference to a specific version of an [`Item`] inside a collection.
#[derive(PartialEq, Debug, Clone)]
pub struct ItemVersion {
    /// Path to the item.
    pub href: Href,
    /// Etag for the item. See [`Etag`].
    pub etag: Etag,
}

impl ItemVersion {
    /// Create a new instance with the given values.
    #[must_use]
    pub fn new(href: Href, etag: Etag) -> ItemVersion {
        ItemVersion { href, etag }
    }
}

/// Changes to a collection since a known sync state.
///
/// Returned by [`Storage::changed_since`].
#[derive(Debug, Clone)]
pub struct CollectionChanges {
    /// New/current sync token for this collection.
    ///
    /// May be `None` if the collection is empty and has no state yet.
    pub new_state: Option<String>,
    /// Items that were created or updated since the previous state.
    pub changed: Vec<Href>,
    /// Items that were deleted since the previous state.
    pub deleted: Vec<Href>,
}

/// Property which can be read, written or unset for collections.
///
/// These were known as "metadata" in the original vdirsyncer implementation.
///
/// See also [`Storage::get_property`] and [`Storage::set_property`].
#[derive(Clone, Copy, std::fmt::Debug, std::hash::Hash, PartialEq, Eq)]
pub enum Property {
    AddressBook(AddressBookProperty),
    Calendar(CalendarProperty),
}

impl Property {
    /// Return a friendly name for this property.
    #[must_use]
    pub fn name(&self) -> &str {
        match self {
            Property::AddressBook(p) => p.name(),
            Property::Calendar(p) => p.name(),
        }
    }

    /// Return all known properties of a given kind.
    #[must_use]
    pub fn known_properties(item_kind: ItemKind) -> &'static [Self]
    where
        Self: Sized,
    {
        match item_kind {
            ItemKind::AddressBook => AddressBookProperty::known_properties(),
            ItemKind::Calendar => CalendarProperty::known_properties(),
        }
    }

    /// Returns the name of the corresponding DAV property.
    #[must_use]
    pub fn dav_propname(&self) -> &PropertyName<'_, '_> {
        match self {
            Property::AddressBook(p) => p.dav_propname(),
            Property::Calendar(p) => p.dav_propname(),
        }
    }
}

/// Immutable item which may be stored in a [`Storage`].
///
/// The inner data is either a `VCALENDAR` or `VCARD`.
///
/// This type defines how to extract the basic information that is required to synchronise
/// storages. It is not a fully validating parser for icalendar or vcard; it is a permissive
/// implementation with the sole purpose of extracting a UID.
///
/// Proper parsing of components is out of scope, since supporting potentially invalid items is
/// required. Additional parsing should be done by inspecting the raw data inside an item via
/// [`Item::as_str`].
#[derive(Debug, Clone, PartialEq)]
pub struct Item {
    raw: String,
}

impl Item {
    /// Parse the item and return the value of its `UID` property, if defined..
    ///
    /// The `uid` does not change when the item is modified. The `uid` remains the same when the
    /// item is copied across storages and storage types.
    #[must_use]
    pub fn uid(&self) -> Option<String> {
        let mut lines = self.as_str().split_terminator("\r\n");
        let mut uid = lines
            .find_map(|line| line.strip_prefix("UID:"))
            .map(String::from)?;

        // If the following lines start with a space or tab, they're a continuation of the UID.
        // See: https://www.rfc-editor.org/rfc/rfc5545#section-3.1
        lines
            .map_while(|line| line.strip_prefix(' ').or_else(|| line.strip_prefix('\t')))
            .for_each(|part| uid.push_str(part));

        Some(uid)
    }

    /// Return the SHA256 hash of an icalendar or vcard.
    ///
    /// The content shall be normalised before hashing to ensure that two semantically equivalent
    /// items return the same hash.
    ///
    /// The output of the function shall remain the same across different versions, platforms and
    /// architectures.
    ///
    /// This value is used as a fallback when a storage backend doesn't provide [`Etag`] values, or
    /// when an item's [`Item::uid`] returns `None`.
    #[must_use]
    pub fn hash(&self) -> ItemHash {
        let mut hasher = Sha256::new();
        hash_normalized(&self.raw, &mut hasher);
        ItemHash(Arc::from(<[u8; 32]>::from(hasher.finalize())))
    }

    /// A unique identifier for this item. Is either the UID (if any), or the hash of its contents.
    #[must_use]
    pub fn ident(&self) -> String {
        self.uid().unwrap_or_else(|| self.hash().to_string())
    }

    /// Returns a new copy of this Item with the supplied UID.
    #[must_use]
    pub fn with_uid(&self, new_uid: &str) -> Self {
        let mut inside_component = false;
        let mut new = String::new();

        for line in Parser::new(self.as_str()) {
            if line.name() == "BEGIN"
                && ["VEVENT", "VTODO", "VJOURNAL", "VCARD"].contains(&line.value().as_ref())
            {
                inside_component = true;
            }
            if line.name() == "END"
                && ["VEVENT", "VTODO", "VJOURNAL", "VCARD"].contains(&line.value().as_ref())
            {
                inside_component = false;
            }
            if inside_component && line.name() == "UID" {
                new.push_str("UID:");
                new.push_str(new_uid);
                new.push_str("\r\n");
            } else {
                new.push_str(line.raw());
                new.push_str("\r\n");
            }
        }
        Self::from(new)
    }

    #[must_use]
    /// Returns the raw contents of this item.
    pub fn as_str(&self) -> &str {
        &self.raw
    }
}

/// The hash of an item. See [`Item::hash`].
#[derive(Default, PartialEq, Clone)]
pub struct ItemHash(Arc<[u8; 32]>);

// TODO: must confirm that this matches previous impl to ensure statusDb makes sense.
impl std::fmt::Display for ItemHash {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        for byte in self.0.iter() {
            write!(f, "{byte:02X}")?;
        }
        Ok(())
    }
}

impl std::fmt::Debug for ItemHash {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "ItemHash(")?;
        for byte in self.0.iter() {
            write!(f, "{byte:02X}")?;
        }
        write!(f, ")")
    }
}

/// Error returned by [`ItemHash::from_str`].
#[derive(Debug, thiserror::Error)]
pub enum ItemHashError {
    #[error("Hash must be exactly 64 characters long")]
    InvalidLength,
    #[error("Invalid character in hash representation")]
    InvalidCharacter,
}

impl FromStr for ItemHash {
    type Err = ItemHashError;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        if value.len() != 64 {
            return Err(ItemHashError::InvalidLength);
        }

        let mut bytes = [0u8; 32];
        for (byte, chunk) in bytes.iter_mut().zip(value.as_bytes().chunks(2)) {
            let hex = std::str::from_utf8(chunk).map_err(|_| ItemHashError::InvalidCharacter)?;
            *byte = u8::from_str_radix(hex, 16).map_err(|_| ItemHashError::InvalidCharacter)?;
        }

        Ok(ItemHash(Arc::new(bytes)))
    }
}

impl From<String> for Item {
    /// Creates a new instance from valid iCalendar data.
    fn from(value: String) -> Self {
        Item { raw: value }
    }
}

/// Item fetched from a storage plus its metadata.
#[derive(Debug)]
pub struct FetchedItem {
    /// See [`Href`]
    pub href: Href,
    /// The actual content of this item. See [`Item`].
    pub item: Item,
    /// See [`Etag`]
    pub etag: Etag,
}

/// Property and its value fetched from a storage.
pub struct FetchedProperty {
    /// The kind of property.
    pub property: Property,
    /// The value of the property.
    pub value: String,
}

#[cfg(test)]
mod test {
    use crate::base::Item;

    #[test]
    fn test_single_line_uid() {
        let raw = ["BEGIN:VCARD", "UID:hello", "END:VCARD"].join("\r\n");
        let item = Item::from(raw);
        assert_eq!(item.uid(), Some(String::from("hello")));
        assert_eq!(item.ident(), String::from("hello"));

        let raw = ["BEGIN:VCARD", "UID:hel", "lo", "END:VCARD"].join("\r\n");
        let item = Item::from(raw);
        assert_eq!(item.uid(), Some(String::from("hel")));
        assert_eq!(item.ident(), String::from("hel"));

        let raw = [
            "BEGIN:VCARD",
            "UID:hello",
            "REV:20210307T195614Z\tthere",
            "END:VCARD",
        ]
        .join("\r\n");
        let item = Item::from(raw);
        assert_eq!(item.uid(), Some(String::from("hello")));
        assert_eq!(item.ident(), String::from("hello"));
    }

    #[test]
    fn test_multi_line_uid() {
        let raw = ["BEGIN:VCARD", "UID:hello", "\tthere", "END:VCARD"].join("\r\n");
        let item = Item::from(raw);
        assert_eq!(item.uid(), Some(String::from("hellothere")));
        assert_eq!(item.ident(), String::from("hellothere"));

        let raw = [
            "BEGIN:VCARD",
            "UID:hello",
            "\tthere",
            "REV:20210307T195614Z",
            "\tnope",
            "END:VCARD",
        ]
        .join("\r\n");
        let item = Item::from(raw);
        assert_eq!(item.uid(), Some(String::from("hellothere")));
        assert_eq!(item.ident(), String::from("hellothere"));
    }

    #[test]
    fn test_missing_uid() {
        let raw = [
            "BEGIN:VCARD",
            "UIDX:hello",
            "REV:20210307T195614Z\tthere",
            "END:VCARD",
        ]
        .join("\r\n");
        let item = Item::from(raw);
        assert_eq!(item.uid(), None);
        assert_eq!(item.ident(), item.hash().to_string());
    }

    #[test]
    fn test_with_uid() {
        let raw = ["BEGIN:VCARD", "UID:hello", "END:VCARD"].join("\r\n");
        let item = Item::from(raw);
        let item2 = item.with_uid("goodbye");
        assert_eq!(item2.uid(), Some(String::from("goodbye")));
        assert_eq!(item2.ident(), String::from("goodbye"));
    }

    #[test]
    fn test_with_uid_without_uid() {
        let raw = ["BEGIN:VCARD", "SUMMARY:hello", "END:VCARD"].join("\r\n");
        let item = Item::from(raw);
        let item2 = item.with_uid("goodbye");
        assert_eq!(item2.uid(), None);
    }
}