io_webdav/lib.rs
1#![no_std]
2#![deny(missing_docs)]
3#![cfg_attr(docsrs, feature(doc_cfg))]
4
5//! # io-webdav
6//!
7//! I/O-free WebDAV client coroutines built on io-http: every network
8//! exchange is a resumable state machine emitting read and write
9//! requests instead of performing I/O itself. The caller owns the
10//! socket and pumps the coroutine with the bytes it read, whatever the
11//! runtime (blocking, async, in-memory tests). The `client` feature
12//! ships a ready-made std-blocking pump for callers who just want a
13//! working client.
14//!
15//! ## Layout: one folder per RFC
16//!
17//! The source tree mirrors how the WebDAV specifications are split,
18//! one module per RFC. [`rfc4918`] implements the WebDAV core: the
19//! PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, DELETE, GET, PUT, OPTIONS
20//! and REPORT requests, the multistatus response parser, the
21//! [`rfc4918::WebdavAuth`] modes and the low-level send coroutine every
22//! higher request builds on. [`rfc4791`] covers CalDAV: calendar
23//! collections and calendar object resources (items), with calendar
24//! home-set discovery. [`rfc6352`] covers CardDAV: address book
25//! collections and contact cards, with address book home-set
26//! discovery, batch multiget and ETag-only enumeration. [`rfc5397`]
27//! discovers the current user principal, the entry point of the
28//! discovery flow. [`rfc6578`] adds collection synchronization: the
29//! sync-collection REPORT and its sync tokens.
30//!
31//! Two modules span the RFC modules and therefore live at the crate
32//! root: [`coroutine`] defines the coroutine contract every state
33//! machine implements, and the optional [`client`] module (`client`
34//! feature) is the std-blocking pump: a light client wrapping any
35//! stream you opened yourself, or a full client opening the TCP/TLS
36//! connection itself when one of the TLS features is enabled.
37//!
38//! ## The coroutine contract
39//!
40//! Every coroutine implements [`coroutine::WebdavCoroutine`]: a resume
41//! method taking the bytes read since the last step and returning
42//! either an intermediate yield or a terminal completion. Standard
43//! coroutines yield the shared read and write requests of
44//! [`coroutine::WebdavYield`]; the redirect-aware discovery coroutines
45//! declare their own [`rfc4918::coroutine::WebdavRedirectYield`],
46//! surfacing a 3xx response to the caller as a redirect request instead
47//! of following it, so the caller decides whether to reconnect to the
48//! new authority and retry. The [`webdav_try`] macro chains an inner
49//! coroutine step inside an outer resume, re-yielding and
50//! short-circuiting like the question mark operator.
51//!
52//! ## Conventions
53//!
54//! The crate is no_std with alloc; std only enters behind the `client`
55//! feature. Every public item carries the bare `Webdav` prefix, the
56//! protocol not being version-scoped. Logging follows the library
57//! rules: state changes at debug level, in-process steps and data dumps
58//! at trace level.
59
60extern crate alloc;
61#[cfg(feature = "client")]
62extern crate std;
63
64#[cfg(feature = "client")]
65pub mod client;
66pub mod coroutine;
67pub mod rfc4791;
68pub mod rfc4918;
69pub mod rfc5397;
70pub mod rfc6352;
71pub mod rfc6578;