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.
• 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 the generic I parameter, which implements the necessary operations for a specific content type of a given storage instance.

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.

Modules

• base
  Traits and common implementations shared by different storages.
• caldav
  A CalDavStorage is a single caldav repository, as specified in rfc4791.
• carddav
  A CardDavStorage is a single carddav repository, as specified in rfc6352.
• disco
  Types related to collection discovery.
• 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.

Type Aliases

• Href
  Path to the item inside the collection.