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//! 4. On an instance that runs as a service account, its credential from
27//!    the instance's metadata service. `ORIGINCLOUD_METADATA_DISABLED=true`
28//!    leaves this step out.
29//!
30//! # Endpoints
31//!
32//! Every service answers at `{service}.origincloudapis.eu`, which serves
33//! every resource wherever it lives. [`ClientBuilder::region`], or
34//! `ORIGINCLOUD_REGION`, picks a region's front door instead,
35//! `{service}.{region}.origincloudapis.eu`, for the services that have
36//! regional ones.
37//!
38//! # Retries
39//!
40//! A call the API answers as retryable is sent again, after the delay the
41//! answer asks for or a growing one, as long as sending it again is safe: a
42//! read, or a mutation with a request id. The client fills in a mutation's
43//! request id when it is empty, so that a retry can't apply it twice.
44//!
45//! # Read-your-writes
46//!
47//! The API answers reads from replicas that can be a moment behind a write
48//! that just succeeded. The client keeps the consistency token each
49//! mutation and each finished operation answers with, and sends it with
50//! every later call, so that a read through the same client shows the
51//! client's own writes. The token answered last replaces the one held: for
52//! writes made one after another, it covers them all; of writes made
53//! concurrently, it covers the one answered last (see
54//! [`Client::set_consistency_token`]).
55//!
56//! # Errors
57//!
58//! A call the API refuses returns an [`Error::Api`]: branch on
59//! [`Error::reason`], the platform's error code. [`ApiError::metadata`]
60//! says more about some reasons, such as the name of the resource a
61//! `CONFLICT` is about.
62//!
63//! # Runtime
64//!
65//! The clients are `async` and send their calls with
66//! [reqwest](https://docs.rs/reqwest), on [Tokio](https://tokio.rs).
67
68#![warn(missing_docs)]
69
70mod client;
71pub mod credentials;
72mod error;
73pub mod longrunning;
74mod operation;
75mod pages;
76pub mod protobuf;
77pub mod rpc;
78mod transport;
79
80pub use client::{Client, ClientBuilder, Service, VERSION};
81pub use credentials::{
82    AccessToken, CliSession, Credentials, InstanceMetadata, ServiceAccount, default_credentials,
83};
84pub use error::{ApiError, Error, FieldViolation};
85pub use operation::Operation;
86pub use pages::Pages;
87pub use transport::{
88    CONSISTENCY_TOKEN_HEADER, Method, Query, Request, json_body, new_request_id, path_value, query,
89};
origincloud_core/lib.rs

origincloud_core/
lib.rs
