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

origincloud_core/
lib.rs
