io-webdav 0.1.0

WebDAV client library for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

//! Generic `PUT` coroutine (RFC 4918 §9.7).
//!
//! Sends a `PUT` against `path` with the caller-supplied body bytes
//! and content type. Stays byte-oriented: callers parse iCal/vCard
//! upstream.
//!
//! Supports the optional `If-Match` (RFC 9110 §13.1.1) and
//! `If-None-Match` (RFC 9110 §13.1.2) preconditions so callers can
//! gate the write on a known ETag.
//!
//! # Example
//!
//! ```rust,no_run
//! use std::{
//!     io::{Read, Write},
//!     net::TcpStream,
//! };
//!
//! use io_webdav::{
//!     coroutine::{WebdavCoroutine, WebdavCoroutineState, WebdavYield},
//!     rfc4918::{
//!         WebdavAuth,
//!         put::{Put, PutArgs},
//!     },
//! };
//! use url::Url;
//!
//! // Ready stream needed (TCP-connected, TLS-negociated)
//! let mut stream = TcpStream::connect("dav.example.org:443").unwrap();
//! let mut buf = [0u8; 4096];
//!
//! let base_url: Url = "https://dav.example.org/".parse().unwrap();
//! let auth = WebdavAuth::None;
//! let mut coroutine = Put::new(PutArgs {
//!     base_url: &base_url,
//!     auth: &auth,
//!     user_agent: "io-webdav",
//!     path: "/dav/calendars/personal/event-1.ics",
//!     content_type: "text/calendar; charset=utf-8",
//!     body: b"BEGIN:VCALENDAR\r\n...\r\nEND:VCALENDAR\r\n".to_vec(),
//!     if_match: None,
//!     if_none_match: Some("*"),
//! });
//! let mut arg = None;
//!
//! let ok = loop {
//!     match coroutine.resume(arg.take()) {
//!         WebdavCoroutineState::Yielded(WebdavYield::WantsWrite(bytes)) => {
//!             stream.write_all(&bytes).unwrap();
//!         }
//!         WebdavCoroutineState::Yielded(WebdavYield::WantsRead) => {
//!             let n = stream.read(&mut buf).unwrap();
//!             arg = Some(&buf[..n]);
//!         }
//!         WebdavCoroutineState::Complete(Ok(ok)) => break ok,
//!         WebdavCoroutineState::Complete(Err(err)) => panic!("{err}"),
//!     }
//! };
//!
//! println!("keep-alive: {}", ok.keep_alive);
//! ```

use alloc::vec::Vec;

use log::trace;
use url::Url;

use crate::{
    coroutine::*,
    rfc4918::{
        WebdavAuth,
        request::WebdavRequest,
        send::{SendError, SendOk, SendRaw},
    },
};

/// Build inputs for a [`Put`] coroutine.
///
/// Uses a struct rather than positional arguments so callers can
/// build the request literal-style and skip the two optional
/// precondition fields without juggling positional `None`s.
#[derive(Clone, Debug)]
pub struct PutArgs<'a> {
    /// Base URL the request path is resolved against.
    pub base_url: &'a Url,
    /// Authentication scheme for the `Authorization` header.
    pub auth: &'a WebdavAuth,
    /// Value emitted as the `User-Agent` header.
    pub user_agent: &'a str,
    /// Resource path to PUT to, relative to `base_url`.
    pub path: &'a str,
    /// MIME type emitted as the `Content-Type` header.
    pub content_type: &'a str,
    /// Raw request body bytes.
    pub body: Vec<u8>,
    /// Optional `If-Match` ETag (RFC 9110 §13.1.1).
    pub if_match: Option<&'a str>,
    /// Optional `If-None-Match` ETag (RFC 9110 §13.1.2).
    pub if_none_match: Option<&'a str>,
}

/// Coroutine that runs a `PUT`.
#[derive(Debug)]
pub struct Put {
    state: State,
}

impl Put {
    /// Builds a new `PUT` coroutine.
    pub fn new(args: PutArgs<'_>) -> Self {
        let mut builder = WebdavRequest::put(args.base_url, args.auth, args.user_agent, args.path)
            .content_type(args.content_type);

        if let Some(etag) = args.if_match {
            builder = builder.if_match(etag);
        }

        if let Some(etag) = args.if_none_match {
            builder = builder.if_none_match(etag);
        }

        let request = builder.body(args.body);
        Self {
            state: State::Send(SendRaw::new(request)),
        }
    }
}

impl WebdavCoroutine for Put {
    type Yield = WebdavYield;
    type Return = Result<SendOk<Vec<u8>>, SendError>;

    fn resume(&mut self, arg: Option<&[u8]>) -> WebdavCoroutineState<Self::Yield, Self::Return> {
        trace!("sending request");
        match &mut self.state {
            State::Send(send) => send.resume(arg),
        }
    }
}

#[derive(Debug)]
enum State {
    Send(SendRaw),
}