Crate origincloud_core 

What every service crate of the Origin Cloud SDK shares: credentials, endpoints, retries, errors, long-running operations and read-your-writes.

A program creates one Client and hands it to the clients of the services it uses:

let client = origincloud_core::Client::new()?;
// let volumes = origincloud_pvs::v1beta1::VolumeClient::new(&client);

Credentials

Unless ClientBuilder::credentials names them, Client::new takes the first of (natively; in a browser there are none of these, see credentials):

1. ORIGINCLOUD_ACCESS_TOKEN: an access token, sent as it is.
2. ORIGINCLOUD_CLIENT_ID and ORIGINCLOUD_CLIENT_SECRET: a service account’s credential, exchanged for access tokens as they expire.
3. A CI job’s OIDC token, exchanged at the security token service for a WORKLOAD service account’s access tokens (Federated): from the file ORIGINCLOUD_OIDC_TOKEN_FILE names, from ORIGINCLOUD_OIDC_TOKEN, which holds the token itself, or in a GitHub Actions job granted permissions: id-token: write. ORIGINCLOUD_OIDC_DISABLED=true leaves this step out.
4. The session the origin CLI stored at its last login (origin id login).
5. On an instance that runs as a service account, its credential from the instance’s metadata service. ORIGINCLOUD_METADATA_DISABLED=true leaves this step out.

Endpoints

Every service answers at {service}.origincloudapis.eu, which serves every resource wherever it lives. ClientBuilder::region, or ORIGINCLOUD_REGION, picks a region’s front door instead, {service}.{region}.origincloudapis.eu, for the services that have regional ones.

Retries

A call the API answers as retryable is sent again, after the delay the answer asks for or a growing one, as long as sending it again is safe: a read, or a mutation with a request id. The client fills in a mutation’s request id when it is empty, so that a retry can’t apply it twice. ClientBuilder::max_attempts bounds the attempts of every call; CallOptions those of the calls through one service client, such as a mutation that must not be sent twice at all.

Read-your-writes

The API answers reads from replicas that can be a moment behind a write that just succeeded. The client keeps the consistency token each mutation and each finished operation answers with, and sends it with every later call, so that a read through the same client shows the client’s own writes. The token answered last replaces the one held: for writes made one after another, it covers them all; of writes made concurrently, it covers the one answered last (see Client::set_consistency_token). The token is kept per client, and shared by its clones; clients given one store share it (ClientBuilder::consistency_token_store). A call the API refuses because its token isn’t one is sent again once without it, and the token is dropped.

Names

A resource’s name is its relative name; its full resource name, //{service}.origincloudapis.eu/{name}, is what references carry (FullName). A request’s path fields take either. A full name is checked against the type the field refers to (the client’s own service for its own resources, resourcemanager for a project or an organization as a parent) and sent as its relative name; one on any other host is refused before anything is sent.

Errors

A call the API refuses returns an Error::Api: branch on Error::reason, the platform’s error code. ApiError::metadata says more about some reasons, such as the name of the resource a CONFLICT is about.

Runtime

The clients are async and send their calls with reqwest, on Tokio.

They also build for the browser, wasm32-unknown-unknown, where reqwest sends calls with the browser’s fetch, retries wait on setTimeout, and no Tokio runtime is needed: run the futures with the UI framework’s executor, such as wasm-bindgen-futures. There, the futures the SDK returns aren’t Send (MaybeSend), the credentials are the page’s own (see credentials), and the per-call ClientBuilder::timeout is the only one, as a browser’s fetch has no connect timeout.

Re-exports

pub use consistency::ConsistencyTokenCell;

pub use consistency::ConsistencyTokenStore;

pub use credentials::ServiceAccount;

pub use credentials::AccessToken;

pub use credentials::Credentials;

pub use credentials::CliSession;

pub use credentials::Federated;

pub use credentials::InstanceMetadata;

pub use credentials::default_credentials;

pub use names::FullName;

pub use names::FullNameError;

Modules

consistency

Where a Client keeps the consistency token it sends with its calls and replaces with the one each answer carries.

credentials

Credentials: where the access token each call is sent with comes from.

longrunning

Long-running operations: what a service’s creates, updates and deletes answer with, until their resource settles.

names

Full resource names (AIP-122), the platform’s identifiers: //{service}.origincloudapis.eu/{relative name}, such as //pvs.origincloudapis.eu/projects/p/zones/eu-central1-az1/volumes/vol-1.

protobuf

The well-known types (google.protobuf), with their proto3 JSON mapping: FieldMask, Timestamp, Duration, Empty and the others.

rpc

google.rpc.Status and google.protobuf.Any in their JSON form: what a failed operation carries, and the details of an error.

types

The common types (google.type) the API uses, with their proto3 JSON mapping: Date.

Structs

ApiError

A call the API refused, or an operation that failed.

CallOptions

How the calls of one service client are sent, where that differs from the Client’s settings: give it to a generated client’s with_options, such as ProjectClient::with_options, for the calls made through the client it returns. Waiting on an operation such a call answers with follows the client’s settings again.

Client

What the clients of every service share: credentials, endpoints, an HTTP client and the consistency token’s store. Cloning it is cheap, and the clones share all of it.

ClientBuilder

Configures a Client.

FieldViolation

One request field the API refused.

HttpBody

What a method answering with a file rather than JSON returns (google.api.HttpBody): the file’s bytes, as the server sent them, and their media type.

Method

The HTTP method of a Request. The Request Method (VERB)

Operation

A mutation the API accepted and carries out after answering. Its result, a T, is the resource it acted on, or Empty for a delete.

Pages

Everything a list method lists, page by page: a Stream that fetches the next page as it is reached. A page that fails ends it with its error.

Request

One call of a service’s method, as its HTTP binding sends it. The generated clients build it.

Service

The endpoint of one service, which its generated clients send calls to, and how they send them.

Enums

Error

What a call, or waiting on an operation, failed with.

Constants

CONSISTENCY_TOKEN_HEADER

The header carrying the consistency token, in responses and in requests.

VERSION

This SDK’s version, sent in the User-Agent header.

Traits

MaybeSend

Send natively; nothing in a browser, where futures holding JavaScript values aren’t Send. The bound the SDK puts on the futures and values it boxes.

Functions

json_body

message as a JSON body. The generated clients call it.

new_request_id

A new random request id, a UUID, for a mutation whose caller left its request id empty. The generated clients call it.

path_value

value, a relative resource name, as the path segments of a request, checking it has the form pattern, such as projects/*/zones/*/volumes/*, gives it. field names it in the error. Service::path_value also takes a full resource name of its service.

query

The fields of message as query parameters, by their JSON paths, leaving out the fields skip names and fields at their default value. A nested field is sent by its dotted path, a repeated one as one parameter per element. The generated clients send the fields their method’s path and body don’t carry this way.

Type Aliases

MaybeSendFuture

A boxed future: Send natively, not in a browser. (Named apart from futures::future::BoxFuture, which is always Send.)

Query

Query parameters, by their JSON paths.