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

origincloud_core/
lib.rs
