io_jmap/rfc8621/identity/
get.rs

1//! JMAP `Identity/get` coroutine (RFC 8621 §6.3): wraps the generic [`JmapGet`]
2//! with the Submission capability.
3//!
4//! # Example
5//!
6//! ```rust,no_run
7//! use std::{
8//!     io::{Read, Write},
9//!     net::TcpStream,
10//! };
11//!
12//! use io_jmap::{
13//!     coroutine::{JmapCoroutine, JmapCoroutineState, JmapYield},
14//!     rfc8620::session::JmapSession,
15//!     rfc8621::identity::get::{JmapIdentityGet, JmapIdentityGetOptions},
16//! };
17//! use secrecy::SecretString;
18//!
19//! // Ready stream needed (TCP-connected, TLS-negociated)
20//! let mut stream = TcpStream::connect("api.example.com:443").unwrap();
21//! let mut buf = [0u8; 4096];
22//!
23//! let session: JmapSession = serde_json::from_str(r#"{
24//!     "username": "",
25//!     "accounts": {},
26//!     "primaryAccounts": {"urn:ietf:params:jmap:mail": "a1"},
27//!     "capabilities": {},
28//!     "apiUrl": "https://api.example.com/jmap/",
29//!     "downloadUrl": "",
30//!     "uploadUrl": "",
31//!     "eventSourceUrl": "",
32//!     "state": ""
33//! }"#).unwrap();
34//! let auth = SecretString::from("Bearer xyz");
35//! let mut coroutine =
36//!     JmapIdentityGet::new(&session, &auth, JmapIdentityGetOptions::default()).unwrap();
37//! let mut arg = None;
38//!
39//! let out = loop {
40//!     match coroutine.resume(arg.take()) {
41//!         JmapCoroutineState::Yielded(JmapYield::WantsWrite(bytes)) => {
42//!             stream.write_all(&bytes).unwrap();
43//!         }
44//!         JmapCoroutineState::Yielded(JmapYield::WantsRead) => {
45//!             let n = stream.read(&mut buf).unwrap();
46//!             arg = Some(&buf[..n]);
47//!         }
48//!         JmapCoroutineState::Complete(Ok(out)) => break out,
49//!         JmapCoroutineState::Complete(Err(err)) => panic!("{err}"),
50//!     }
51//! };
52//!
53//! println!("{} identities", out.identities.len());
54//! ```
55
56use alloc::{string::String, vec, vec::Vec};
57
58use secrecy::SecretString;
59use thiserror::Error;
60
61use crate::{
62    coroutine::*,
63    jmap_try,
64    rfc8620::{JMAP_CORE_CAPABILITY, get::*, session::JmapSession},
65    rfc8621::{
66        JMAP_MAIL_CAPABILITY, email_submission::JMAP_SUBMISSION_CAPABILITY, identity::JmapIdentity,
67    },
68};
69
70/// Failure causes during a JMAP `Identity/get` flow.
71#[derive(Debug, Error)]
72pub enum JmapIdentityGetError {
73    /// The inner generic get coroutine failed.
74    #[error("JMAP Identity/get failed: {0}")]
75    Get(#[from] JmapGetError),
76}
77
78/// Options for [`JmapIdentityGet::new`].
79#[derive(Clone, Debug, Default)]
80pub struct JmapIdentityGetOptions {
81    /// Restrict the fetch to these identity IDs; `None` fetches all.
82    pub ids: Option<Vec<String>>,
83}
84
85/// Successful terminal output of [`JmapIdentityGet`].
86#[derive(Clone, Debug)]
87pub struct JmapIdentityGetOutput {
88    /// The fetched identities.
89    pub identities: Vec<JmapIdentity>,
90    /// The requested ids the server did not find.
91    pub not_found: Vec<String>,
92    /// The new server state after the call.
93    pub new_state: String,
94    /// Whether the server indicated the connection can be reused.
95    pub keep_alive: bool,
96}
97
98/// I/O-free coroutine for the JMAP `Identity/get` method.
99pub struct JmapIdentityGet {
100    state: State,
101}
102
103impl JmapIdentityGet {
104    /// Prepares the method call request and builds the coroutine.
105    pub fn new(
106        session: &JmapSession,
107        http_auth: &SecretString,
108        opts: JmapIdentityGetOptions,
109    ) -> Result<Self, JmapIdentityGetError> {
110        let account_id = session
111            .primary_accounts
112            .get(JMAP_MAIL_CAPABILITY)
113            .cloned()
114            .unwrap_or_default();
115        let api_url = &session.api_url;
116
117        Ok(Self {
118            state: State::Get(JmapGet::new(
119                account_id,
120                http_auth,
121                api_url,
122                "Identity/get",
123                vec![
124                    JMAP_CORE_CAPABILITY.into(),
125                    JMAP_MAIL_CAPABILITY.into(),
126                    JMAP_SUBMISSION_CAPABILITY.into(),
127                ],
128                JmapGetOptions {
129                    ids: opts.ids,
130                    properties: None,
131                },
132            )?),
133        })
134    }
135}
136
137impl JmapCoroutine for JmapIdentityGet {
138    type Yield = JmapYield;
139    type Return = Result<JmapIdentityGetOutput, JmapIdentityGetError>;
140
141    fn resume(&mut self, arg: Option<&[u8]>) -> JmapCoroutineState<Self::Yield, Self::Return> {
142        match &mut self.state {
143            State::Get(get) => {
144                let JmapGetOutput {
145                    list,
146                    not_found,
147                    state,
148                    keep_alive,
149                } = jmap_try!(get, arg);
150                JmapCoroutineState::Complete(Ok(JmapIdentityGetOutput {
151                    identities: list,
152                    not_found,
153                    new_state: state,
154                    keep_alive,
155                }))
156            }
157        }
158    }
159}
160
161enum State {
162    Get(JmapGet<JmapIdentity>),
163}
io_jmap/rfc8621/identity/get.rs

io_jmap/rfc8621/identity/
get.rs
