origincloud_core/lib.rs
1//! What every service crate of the Origin Cloud SDK shares: credentials,
2//! endpoints, retries, errors, long-running operations and
3//! read-your-writes.
4//!
5//! A program creates one [`Client`] and hands it to the clients of the
6//! services it uses:
7//!
8//! ```no_run
9//! # fn main() -> Result<(), origincloud_core::Error> {
10//! let client = origincloud_core::Client::new()?;
11//! // let volumes = origincloud_pvs::v1beta1::VolumeClient::new(&client);
12//! # Ok(())
13//! # }
14//! ```
15//!
16//! # Credentials
17//!
18//! Unless [`ClientBuilder::credentials`] names them, [`Client::new`] takes
19//! the first of:
20//!
21//! 1. `ORIGINCLOUD_ACCESS_TOKEN`: an access token, sent as it is.
22//! 2. `ORIGINCLOUD_CLIENT_ID` and `ORIGINCLOUD_CLIENT_SECRET`: a service
23//! account's credential, exchanged for access tokens as they expire.
24//! 3. The session the `origin` CLI stored at its last login
25//! (`origin id login`).
26//!
27//! # Endpoints
28//!
29//! Every service answers at `{service}.origincloudapis.eu`, which serves
30//! every resource wherever it lives. [`ClientBuilder::region`], or
31//! `ORIGINCLOUD_REGION`, picks a region's front door instead,
32//! `{service}.{region}.origincloudapis.eu`, for the services that have
33//! regional ones.
34//!
35//! # Retries
36//!
37//! A call the API answers as retryable is sent again, after the delay the
38//! answer asks for or a growing one, as long as sending it again is safe: a
39//! read, or a mutation with a request id. The client fills in a mutation's
40//! request id when it is empty, so that a retry can't apply it twice.
41//!
42//! # Read-your-writes
43//!
44//! The API answers reads from replicas that can be a moment behind a write
45//! that just succeeded. The client keeps the consistency token each
46//! mutation and each finished operation answers with, and sends it with
47//! every later call, so that a read through the same client shows the
48//! client's own writes. The token answered last replaces the one held: for
49//! writes made one after another, it covers them all; of writes made
50//! concurrently, it covers the one answered last (see
51//! [`Client::set_consistency_token`]).
52//!
53//! # Errors
54//!
55//! A call the API refuses returns an [`Error::Api`]: branch on
56//! [`Error::reason`], the platform's error code.
57//!
58//! # Runtime
59//!
60//! The clients are `async` and send their calls with
61//! [reqwest](https://docs.rs/reqwest), on [Tokio](https://tokio.rs).
62
63#![warn(missing_docs)]
64
65mod client;
66pub mod credentials;
67mod error;
68pub mod longrunning;
69mod operation;
70mod pages;
71pub mod protobuf;
72pub mod rpc;
73mod transport;
74
75pub use client::{Client, ClientBuilder, Service, VERSION};
76pub use credentials::{AccessToken, CliSession, Credentials, ServiceAccount, default_credentials};
77pub use error::{ApiError, Error, FieldViolation};
78pub use operation::Operation;
79pub use pages::Pages;
80pub use transport::{
81 CONSISTENCY_TOKEN_HEADER, Method, Query, Request, json_body, new_request_id, path_value, query,
82};