Crate vstorage 

Interact with and synchronise with storages with different underlying implementations.

Storages contain collections which can themselves contain icalendar components, vcard entries, or other similar content types where items have an internal unique ids.

This crates contains the underlying logic for pimsync. pimsync is a command line tool to synchronise storages with calendars and contacts. This crate implements the actual logic for comparing and synchronising storages, and can be used to write alternative interfaces for the same synchronisation implementation.

Storage types

A Storage contains a set of collections, where each collection can contain many items, but not other collections. This restriction matches the semantics of CalDAV/CardDAV and also object stores like S3.

This crate currently includes the following implementations:

• CalDavStorage: a CalDAV server, where each collection is an individual calendar, and each item is an individual event or todo in a calendar.
• CardDavStorage: a CardDAV server, where each collection is an individual address book, and each item is an individual contact card.
• JmapStorage: (optional, requires jmap feature) a JMAP server, where each collection is an individual address book, and each item is an individual contact card.
• ReadOnlyStorage: wraps around another Storage instance, returning an error of kind ErrorKind::ReadOnly for any write operation.
• VdirStorage a local directory, where each collection is a directory and each item is a file.
• WebCal: An icalendar file loaded via HTTP(s). This storage is implicitly read-only.

The Storage type and the logic for synchronisation of storages is agnostic to the content type inside collections, and can synchronise collections with any type of content. When synchronising two storages, items with the same UID on both sides are synchronised with each other. Interpreting content of items in order to extract these UIDs is done via a minimal and permissive parser.

Collections, Hrefs and Collections Ids

As mentioned above, collections cannot be nested (note for IMAP: having an INBOX collection and an INBOX/Feeds collection is perfectly valid).

A collection has an href and usually has an id.

The href attribute is the path to an item inside a storage instance. Its value is storage dependant, meaning that when a collection is synchronised to another storage, it may have a different href on each side.

The id for a collection is not storage-specific. When synchronising two storages, the default approach is to synchronise items across collections with the same id. The id of a collection is entirely dependant on its href, and should never change.

The Href alias is used to refer to hrefs to avoid ambiguity. Href instances should be treated as an opaque value and not given any special meaning outside of this crate.

See also: CollectionId.

Items

See Item.

Properties

Storages expose properties for collections. Property types vary depending on a Storage’s items, although items themselves cannot have properties.

Calendars have a Colour, Description, DisplayName and Order

Address Books have DisplayName and Description.

Entity tags

An Etag is a value that changes whenever an item has changed in a collection. It is inspired on the HTTP header with the same name (used extensively in WebDAV). See Etag.

Storage builders

Storages all use a Builder type for instantiation. The builder takes the minimal set of mandatory arguments, while other constructor argument may be passed via associated functions. This pattern allows extending builders with new initialisation parameters without introducing backwards-incompatible changes. It also allows keeping a reference to a would-be Storage without performing the I/O which might be necessary to initialise it.

Re-exports

This library re-exports libdav and libjmap (if JMAP is enabled). Prefer using the re-exported reference instead of using libdav directly to avoid having to track matching releases.

Re-exports

pub use libdav;

pub use libjmap;

Modules

addressbook

Types and functions specific to address books and contacts.

base

Traits and common implementations shared by different storages.

caldav

A CalDavStorage is a single caldav repository, as specified in rfc4791.

calendar

Types and functions specific to calendars and events.

carddav

A CardDavStorage is a single carddav repository, as specified in rfc6352.

disco

Types related to collection discovery.

hash

Produce normalise hash of items.

jmap

JMAP storage implementation.

readonly

Wrappers for using storages in read-only mode.

sync

Components used for synchronising storages.

vdir

Implements reading/writing entries from a local vdir.

watch

Monitor a storage for changes as they occur.

webcal

Implements reading entries from a remote webcal resource.

Structs

CollectionId

Identifier for a collection.

Error

Common error type used by all Storage implementations.

Etag

Identifier for a specific version of a resource.

Enums

CollectionIdError

Error type when creating a new CollectionId.

ErrorKind

Variants used to categorise Error instances.

ItemKind

Kind of items allowed inside this vdir.

Type Aliases

Href

Path to the item inside the collection.