io-jmap 0.2.1

JMAP 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

//! Generator-shape coroutine contract.
//!
//! Mirrors `core::ops::Coroutine`: a `Yield` associated type for intermediate
//! progress, a `Return` for terminal output, and a two-variant
//! [`JmapCoroutineState`].
//!
//! Most coroutines pick the standard [`JmapYield`] (I/O-only); redirect-aware
//! ones declare their own (e.g. [`JmapRedirectYield`]).
//!
//! [`JmapRedirectYield`]: crate::rfc8620::coroutine::JmapRedirectYield

use alloc::vec::Vec;

/// State yielded by a [`JmapCoroutine::resume`] step.
#[derive(Debug)]
pub enum JmapCoroutineState<Y, R> {
    /// Intermediate yield: the caller reacts and resumes.
    Yielded(Y),
    /// Terminal yield. By convention `R = Result<Output, Error>`.
    Complete(R),
}

/// Standard-shape JMAP coroutine.
pub trait JmapCoroutine {
    /// Intermediate value handed back on every step.
    type Yield;
    /// Terminal value. By convention `Result<Output, Error>`.
    type Return;

    /// Advances the coroutine one step.
    ///
    /// Pass [`None`] on the initial call or after a [`JmapYield::WantsWrite`].
    /// Pass `Some(data)` after a [`JmapYield::WantsRead`]; `Some(&[])` signals
    /// EOF.
    fn resume(&mut self, arg: Option<&[u8]>) -> JmapCoroutineState<Self::Yield, Self::Return>;
}

/// Standard I/O-only Yield for coroutines that only read/write socket bytes.
#[derive(Debug)]
pub enum JmapYield {
    /// The caller reads more bytes and feeds them back on the next resume.
    WantsRead,
    /// The caller writes these bytes; the next resume typically takes `None`.
    WantsWrite(Vec<u8>),
}

/// Coroutine `?`: forwards `Yielded` (via `Into`), short-circuits on
/// `Err` (via `Into`), evaluates to the inner `Ok` value.
#[macro_export]
macro_rules! jmap_try {
    ($coroutine:expr, $arg:expr $(,)?) => {
        match $crate::coroutine::JmapCoroutine::resume($coroutine, $arg) {
            $crate::coroutine::JmapCoroutineState::Yielded(y) => {
                return $crate::coroutine::JmapCoroutineState::Yielded(y.into());
            }
            $crate::coroutine::JmapCoroutineState::Complete(Err(err)) => {
                return $crate::coroutine::JmapCoroutineState::Complete(Err(err.into()));
            }
            $crate::coroutine::JmapCoroutineState::Complete(Ok(value)) => value,
        }
    };
}