io_msgraph/lib.rs
1#![no_std]
2#![deny(missing_docs)]
3#![cfg_attr(docsrs, feature(doc_cfg))]
4
5//! # io-msgraph
6//!
7//! I/O-free coroutines for the [Microsoft Graph API], built on
8//! [io-http] (HTTP/1.1) and pumped by any stream the caller owns.
9//!
10//! [Microsoft Graph API]: https://learn.microsoft.com/en-us/graph/api/overview
11//! [io-http]: https://docs.rs/io-http
12//!
13//! io-msgraph is the Microsoft Graph sibling of [io-gmail]: same shape
14//! (JSON over HTTP), different vendor. Unlike io-gmail, which is scoped
15//! to Gmail's mail API, io-msgraph represents the whole Microsoft Graph
16//! API: the mail, contacts, calendar and To Do surfaces are covered
17//! today, and sibling resources will be added under the same tree over
18//! time.
19//!
20//! [io-gmail]: https://docs.rs/io-gmail
21//!
22//! ## Layers and features
23//!
24//! The crate has two of the three standard Pimalaya layers; there is no
25//! CLI. The always-present no_std core holds the I/O-free coroutines,
26//! the whole Microsoft Graph REST logic. The `client` feature adds
27//! [`v1::client::MsgraphClientStd`], a std blocking client over any
28//! stream, whose `connect` constructor opens the TCP/TLS connection
29//! itself behind a TLS feature (`rustls-ring` by default, `rustls-aws`,
30//! `native-tls`).
31//!
32//! ## Everything lives under v1
33//!
34//! The Microsoft Graph API is versioned (`/v1.0/`), so the crate is
35//! too: the version-agnostic [`coroutine`] contract stays at the crate
36//! root, everything else lives under [`v1`]. The day a breaking Graph
37//! version ships, a sibling module slots in without breaking `v1`
38//! consumers.
39//!
40//! ## The coroutine contract
41//!
42//! Every exchange implements [`coroutine::MsgraphCoroutine`]: `resume`
43//! takes the bytes read since the last yield and either requests I/O
44//! ([`coroutine::MsgraphYield`] `WantsRead` / `WantsWrite`) or
45//! completes. The [`msgraph_try!`] macro is the coroutine equivalent
46//! of `?`.
47//!
48//! A Graph call is a single HTTP request/response, so every REST
49//! coroutine is a thin wrapper around one shared primitive,
50//! [`v1::send::MsgraphSend`]: it builds the authorized request (bearer
51//! token, JSON in and out) and parses either the 2xx body or Graph's
52//! error envelope into [`v1::send::MsgraphSendError`]. Redirects are
53//! never followed. The terminal [`v1::send::MsgraphSendOutput`] carries
54//! the parsed response plus a keep-alive flag so pumps can reuse the
55//! connection across the many small requests a Graph session makes.
56//! Empty 2xx bodies (DELETE, sendMail, send draft) deserialize into the
57//! [`v1::send::MsgraphNoResponse`] unit marker. The two `$value`
58//! endpoints (raw message MIME and raw attachment content) return bytes
59//! rather than JSON: they run the HTTP send directly and yield the
60//! response body.
61//!
62//! ## Naming
63//!
64//! Public items follow `<Domain><Target><Verb><Ext>`: the domain is
65//! `Msgraph`, the target-verb pair mirrors the REST operation
66//! (`MsgraphMailFolderCreate` for creating a mail folder,
67//! `MsgraphContactsList` for listing contacts) and the extension
68//! distinguishes companions (`Params`, `Response`, `Error`, `Yield`).
69//! Pure data resources omit the verb (`MsgraphMessage`,
70//! `MsgraphContact`); the target is omitted when the verb applies to
71//! the whole exchange ([`v1::send::MsgraphSend`]).
72//!
73//! ## Module layout
74//!
75//! [`v1::rest`] mirrors the Graph reference. The mail, contacts,
76//! calendar and To Do surfaces hang off the users resource, so they live
77//! under [`v1::rest::users`], with each sub-resource a directory and each
78//! operation a file named after it: mail_folders (list, get, create,
79//! update, delete, move, copy, child_folders), messages (list, get,
80//! get_raw, create, create_mime, update, delete, move, copy, send,
81//! delta, attachments), contact_folders (list, get, create, update,
82//! delete, child_folders), contacts (list, get, create, update,
83//! delete, delta), calendars (list, get, create, update, delete), events
84//! (list, get, create, update, delete, instances, calendar_view, delta),
85//! todo lists (list, get, create, update, delete, delta) and their tasks
86//! (list, get, create, update, delete, delta, checklist_items), and the
87//! sendMail action (JSON and MIME form). JSON batching lives at
88//! the API root, under [`v1::rest::batch`]. A reader who knows the
89//! reference knows where to look.
90//!
91//! Domain types mirror the Graph schema. Full-resource bodies double as
92//! create and update bodies thanks to `skip_serializing_if` on every
93//! optional field; contact fields use the [`v1::field::MsgraphField`]
94//! tri-state to distinguish a field left out of a PATCH body from one
95//! explicitly cleared. List operations take borrowed `*Params` structs
96//! whose fields rename to the OData system query options (`$top`,
97//! `$select`, `$filter` among others), flattened into query pairs by
98//! [`v1::query::to_query_pairs`], a tiny no_std serde serializer.
99//!
100//! ## Authentication
101//!
102//! io-msgraph does no OAuth itself: the Graph API only accepts OAuth
103//! 2.0 bearer tokens, so the credential is exactly a bare access token,
104//! and minting or refreshing it is the caller's responsibility. The
105//! base URL is fixed ([`v1::send::MSGRAPH_API_BASE`]); the mailbox
106//! owner is addressed by [`v1::send::user_path`], which yields `me` for
107//! the authenticated user or `users/{id}` for an explicit user id or
108//! principal name (Graph rejects `users/me`).
109//!
110//! ## Logging
111//!
112//! Coroutines pair a `debug!` lifecycle line with one `trace!` per
113//! input variable in `new()`, and a `debug!` plus `trace!("out: ...")`
114//! when `resume` completes; the crate never logs above `debug!`.
115//!
116//! ## Example
117//!
118//! Running a coroutine against a caller-owned TLS stream:
119//!
120//! ```rust,no_run
121//! use std::{
122//! io::{Read, Write},
123//! net::TcpStream,
124//! sync::Arc,
125//! };
126//!
127//! use io_http::rfc6750::bearer::HttpAuthBearer;
128//! use io_msgraph::{coroutine::*, v1::rest::users::get::MsgraphUserGet};
129//! use rustls::{ClientConfig, ClientConnection, StreamOwned};
130//! use rustls_platform_verifier::ConfigVerifierExt;
131//!
132//! let config = ClientConfig::with_platform_verifier().unwrap();
133//! let server_name = "graph.microsoft.com".try_into().unwrap();
134//! let conn = ClientConnection::new(Arc::new(config), server_name).unwrap();
135//! let tcp = TcpStream::connect(("graph.microsoft.com", 443)).unwrap();
136//! let mut stream = StreamOwned::new(conn, tcp);
137//!
138//! let auth = HttpAuthBearer::new("token");
139//! let mut coroutine = MsgraphUserGet::new(&auth, "me").unwrap();
140//!
141//! let mut arg: Option<&[u8]> = None;
142//! let mut buf = [0u8; 8192];
143//! let mut read = Vec::new();
144//!
145//! let out = loop {
146//! match coroutine.resume(arg.take()) {
147//! MsgraphCoroutineState::Complete(Ok(out)) => break out,
148//! MsgraphCoroutineState::Complete(Err(err)) => panic!("{err}"),
149//! MsgraphCoroutineState::Yielded(MsgraphYield::WantsRead) => {
150//! let n = stream.read(&mut buf).unwrap();
151//! read.clear();
152//! read.extend_from_slice(&buf[..n]);
153//! arg = Some(&read);
154//! }
155//! MsgraphCoroutineState::Yielded(MsgraphYield::WantsWrite(bytes)) => {
156//! stream.write_all(&bytes).unwrap();
157//! }
158//! }
159//! };
160//!
161//! println!("user principal name: {:?}", out.response.user_principal_name);
162//! ```
163
164extern crate alloc;
165#[cfg(feature = "client")]
166extern crate std;
167
168pub mod coroutine;
169pub mod v1;