google-cloud-rust

The repository provides two tiers of bindings for interacting with Google APIs:

1. Raw Bindings (googleapis-raw): These are based on grpcio and provide direct access to the underlying service definitions. You can find usage examples in the googleapis-raw/examples directory.
2. High-level Bindings (googleapis): These are intended to provide a more ergonomic interface, but they are not ready for use yet.

Currently, only the Cloud Spanner client is considered in production. Clients for Cloud BigTable, Cloud Pub/Sub, and Cloud Storage are auto-generated and should be considered experimental.

To avoid compatibility issues, your calling code must use the exact same versions of protobuf and grpcio as this library. This requirement is due to an internal dependency constraint within grpcio.

Required versions:

• protobuf = 2.28.0
• grpcio = 0.13.0 (Note: The README mentions a lock to 0.12.0 in the disclaimer section, but specifies 0.13.0 in the dependency list. Always verify against the Cargo.toml of the specific version you are using.)

# Ensure your Cargo.toml matches these versions
protobuf = "=2.28.0"
grpcio = "0.13.0"

The mod_updater.py script is a utility used to synchronize local generated files with existing mod.rs files after a grpcio submodule update. This is useful when third-party APIs change radically, causing mismatches between generated code and the module declarations.

By default, the script presumes it is being run from within its own directory. To target a specific directory (such as googleapis-raw), use the MOD_UP_PATH environment variable.

MOD_UP_PATH=path/to/googleapis-raw python3 mod_updater.py

To run examples inside the Docker container, the environment variable GOOGLE_APPLICATION_CREDENTIALS must point to your Google credentials file.

The Docker image is configured to look for credentials at files/credentials.json. To make your credentials available, copy your JSON credentials file to that specific location within the project directory.

Warning: The files/credentials.json file is not under version control; ensure you do not commit it to your repository.

# Example: Copying your credentials to the expected location
cp /path/to/your/actual-credentials.json files/credentials.json

To pull the latest versions of the required libraries (grpc, protobuf, and googleapis), use the following commands to perform a targeted update of the submodules:

git submodule update --remote grpc
pushd grpc/third_party
git submodule update --remote protobuf
git submodule update --remote googleapis
popd

Important: It is recommended to update the grpc/third_party/googleapis submodule at least once per quarter, as it contains Protobuf declarations that may change without notice. Updating these may require manual corrections to mod.rs files to account for new or removed modules.

Before running examples or using the bindings, you must have the Google Cloud SDK configured in your environment.

Verification Steps:

1. Check SDK configuration: gcloud info
2. Verify credentials: echo $GOOGLE_APPLICATION_CREDENTIALS
3. Ensure you are logged in: gcloud auth login

For a pre-configured environment, refer to the Docker setup documentation in the ./docker folder of the repository.

If you are on an operating system like macOS where local setup is difficult, or if you want to avoid installing various programming languages and libraries on your host system, you can use the provided Docker setup. The Docker image includes a recent Rust toolchain and mounts the project repository into the container.

Prerequisites

• Install Docker (e.g., Docker Desktop on macOS).
• Install docker-compose.

# Build the Docker image
docker-compose build rust

# Start the container and open a bash shell
docker-compose run rust /bin/bash

The FieldBehavior enum is used to denote the behavior of specific fields within Google API protobuf messages. These annotations are used by API tooling to understand how to handle fields (e.g., whether a field is required in a request or only provided in a response).

Note: These annotations do not change the underlying protocol buffer behavior itself; they serve as metadata for API tooling and documentation.

The Distribution type uses a oneof field called bucket_option to allow different ways of defining buckets. You can choose one of the following three types:

1. linear_buckets: Uses Distribution_LinearBuckets for uniform bucket widths.
2. exponential_buckets: Uses Distribution_ExponentialBuckets for buckets that grow exponentially.
3. explicit_buckets: Uses Distribution_ExplicitBuckets for manually defined bucket boundaries.

Use the set_*_buckets methods to assign a specific bucket configuration to the Distribution instance.

// Example: Setting linear buckets
let mut dist = Distribution::new();
let mut linear = Distribution_LinearBuckets::new();
linear.set_num_finite_buckets(10);
linear.set_width(1.0);
linear.set_offset(0.0);

dist.set_linear_buckets(linear);