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. [`ApiError::metadata`]
57//! says more about some reasons, such as the name of the resource a
58//! `CONFLICT` is about.
59//!
60//! # Runtime
61//!
62//! The clients are `async` and send their calls with
63//! [reqwest](https://docs.rs/reqwest), on [Tokio](https://tokio.rs).
64
65#![warn(missing_docs)]
66
67mod client;
68pub mod credentials;
69mod error;
70pub mod longrunning;
71mod operation;
72mod pages;
73pub mod protobuf;
74pub mod rpc;
75mod transport;
76
77pub use client::{Client, ClientBuilder, Service, VERSION};
78pub use credentials::{AccessToken, CliSession, Credentials, ServiceAccount, default_credentials};
79pub use error::{ApiError, Error, FieldViolation};
80pub use operation::Operation;
81pub use pages::Pages;
82pub use transport::{
83    CONSISTENCY_TOKEN_HEADER, Method, Query, Request, json_body, new_request_id, path_value, query,
84};
origincloud_core/lib.rs

origincloud_core/
lib.rs
