I/O Vdir

Vdir client library for Rust

This library is composed of 2 feature-gated layers:

• Low-level I/O-free coroutines: no_std-compatible state machines containing the whole Vdir logic, usable anywhere
• Mid-level standard client: a blocking client that runs the coroutines against the local filesystem for you

Table of contents

• Features
• Specification coverage
• Usage
• Examples
• AI disclosure
• License
• Social
• Contributing
• Sponsoring

Features

• I/O-free core: state machines carrying the whole Vdir logic, with no filesystem calls and no async runtime, so the same operations drive blocking, async or test harnesses.
• Standard client: an optional blocking client that runs every operation against the local filesystem for you.
• Collections: create, delete, list, rename and update collection directories, including the optional display name, description and color metadata markers.
• Items: store, get, list, locate, copy, move and delete contact and calendar files, written atomically through a temporary file and a rename.

[!TIP] Each layer is toggled through a cargo feature; the default set is listed in Cargo.toml and on docs.rs.

Specification coverage

The library implements the Vdir storage format: collections are directories, items are files inside them, and metadata lives in a small set of marker files. Items are either contacts (vCard) or calendar objects (iCalendar); io-vdir treats them as opaque bytes and leaves parsing to the consumer.

Usage

The whole API is documented on docs.rs, including runnable snippets for every coroutine and for the standard client.

Examples

Complete runnable programs live in ./examples; the tests also demonstrate real usage.

AI disclosure

This project is developed with AI assistance. This section documents how, so users and downstream packagers can make informed decisions.

• Tools: Claude Code (Anthropic), invoked locally with a persistent project-scoped memory and a small set of repo-specific rules.
• Used for: Refactors, mechanical multi-file edits, boilerplate (feature gates, error enums, derive macros, trait impls), test scaffolding, doc polish, exploratory design conversations.
• Not used for: Engineering, critical code, git manipulation (commit, merge, rebase…), real-world tests.
• Verification: Every AI-assisted change is read, compiled, tested, and formatted before commit. Behavioural correctness is verified against the relevant RFC or upstream spec, not assumed from the model output. Tests are never adjusted to fit AI-generated code; the code is adjusted to fit correct behaviour.
• Limitations: AI models occasionally produce code that compiles and passes tests but is subtly wrong. The verification workflow catches most of this; it does not catch all of it. Bug reports are welcome and taken seriously.
• Last reviewed: 16/07/2026

License

This project is dual-licensed under the MIT and Apache 2.0 licenses.

Social

• Chat on Matrix
• News on Mastodon or RSS
• Mail at pimalaya.org@posteo.net

Contributing

Contributions are welcome: start with CONTRIBUTING.md, which opens with the Pimalaya-wide guides to read first.

Sponsoring

Special thanks to the NLnet foundation and the European Commission that have been financially supporting the project for years:

• 2022 → 2023: NGI Assure
• 2023 → 2024: NGI Zero Entrust
• 2024 → 2026: NGI Zero Core
• 2027 in preparation…

If you appreciate the project, feel free to donate using one of the following providers: