Crate vstorage

source ·
Expand description

Implementation of a common API for reading and writing items on different underlying storage implementations.

Storages can contain icalendar components, vcard entries, or content types where items are either immutable or have unique ids.


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 caldav 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.

A potential ImapStorage could be implemented a single IMAP account, where each collection is a mailbox and each item is an individual email message.

The Storage type and the logic for synchronisation of storages is 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.


See Item.


Storages expose properties. Property types vary depending on a Storage’s items. E.g.: Calendars have a Colour, Description, DisplayName and Order, whereas Address Books have DisplayName and Description. In both of these examples, only collections have properties, and items have no properties.

Synchronising Storages with custom Item types where items have properties is not yet supported. This limitation means that an implementation trying to synchronise email will synchronise messages but not their properties (e.g.: Seen, Flagged, etc).

§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.


  • Traits and common implementations shared by different storages.
  • A CalDavStorage is a single caldav repository, as specified in rfc4791.
  • A CardDavStorage is a single carddav repository, as specified in rfc6352.
  • Types related to collection discovery.
  • Wrappers for using storages in read-only mode.
  • Components used for synchronising storages.
  • Implements reading/writing entries from a local vdir.
  • Implements reading entries from a remote webcal resource.


  • An identifier for a collection.
  • A common error type used by all Storage implementations.
  • An identifier for a specific version of a resource.


Type Aliases§

  • The path to the item inside the collection.