Skip to content

GEMINI.md

Latest commit

 

History

History
195 lines (138 loc) · 5.68 KB

GEMINI.md

File metadata and controls

195 lines (138 loc) · 5.68 KB

Gemini Code Understanding

Project Overview

This project provides idiomatic Rust client libraries for Google Cloud Platform (GCP) services. The goal is to offer a natural and familiar API for Rust developers to interact with GCP. The libraries are under active development, and the APIs are subject to change.

The project is structured as a Rust workspace, containing numerous crates. Most of the client libraries are auto-generated from Protobuf service specifications. The core components include:

  • Generated Libraries: Located in src/generated, these are the auto-generated client libraries for various GCP services.
  • Authentication: The src/auth crate handles authentication with Google Cloud.
  • GAX (Google API Extensions): The src/gax crate provides common components for all clients, including error handling, retry policies, and backoff strategies. src/gax-internal contains implementation details shared across clients.
  • Long-Running Operations (LRO): The src/lro crate provides support for handling long-running operations.
  • Well-Known Types (WKT): The src/wkt crate contains shared types used across the libraries.
  • Cloud Storage: The src/storage crate contains a client library for Google Cloud Storage.
  • Pub/Sub: The src/pubsub crate contains a client library for Google Cloud Pub/Sub.

Building and Running

The project uses Cargo, the Rust build tool and package manager.

Building the Project

To build the entire workspace, run the following command from the root directory:

cargo build

Running Tests

To run the tests for the entire workspace, use the following command:

cargo test

To run the tests for a particular crate, use the following command:

cargo test -p ${crate_name}

For example:

cargo test -p google-cloud-storage

Running Integration Tests

Integration tests are located in the tests directory (e.g., tests/integration, tests/integration-auth). They are often disabled by default because they run against live GCP services.

To run integration tests, you typically need to:

  1. Authenticate: Run gcloud auth application-default login to set up credentials.
  2. Set Environment Variables: Many tests require specific environment variables to be set (e.g., GOOGLE_CLOUD_PROJECT).

To run integration tests for a specific suite, you need to enable the corresponding feature.

For example, to run the general integration tests with required environment variables:

GOOGLE_CLOUD_PROJECT="$(gcloud config get project)"
env \
    GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT} \
    GOOGLE_CLOUD_RUST_TEST_SERVICE_ACCOUNT=rust-sdk-test@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com \
    GOOGLE_CLOUD_RUST_TEST_STORAGE_KMS_RING=us-central1 \
  cargo test -p integration-tests --features run-integration-tests

See doc/contributor/howto-guide-set-up-development-environment.md for more details on setting up resources for integration tests.

Linter

Our CI runs clippy with --deny warnings in different configurations to ensure full coverage. It is recommended to run both of the following commands locally:

To check the default build (which catches issues in #[cfg(not(test))] code paths):

cargo clippy --all-targets -- -D warnings

To check the build with tests enabled (includes #[cfg(test)] and test files):

cargo clippy --profile test -- -D warnings

To run the linter for a particular crate, use the following command:

cargo clippy -p ${crate_name} --all-targets -- -D warnings
cargo clippy -p ${crate_name} --profile test -- -D warnings

For example:

cargo clippy -p google-cloud-storage --profile test -- -D warnings

Code Formatter

To format the code for the entire workspace, use the following command:

cargo fmt

To format a crate use:

cargo fmt -p ${crate_name}

For example:

cargo fmt -p google-cloud-storage

Development Conventions

Setting up the Development Environment

  • Install rustc, rustfmt, clippy, and cargo using rustup.
  • Run cargo build and cargo test to verify the setup.

Forks and Pull Requests

  • Create a fork of the google-cloud-rust repository.
  • Create a branch for your changes.
  • Make your changes and commit them with a descriptive message.
  • The commit message should follow the "Conventional Commits" specification.
  • Push your changes to your fork.
  • Create a pull request from your fork to the main branch of the google-cloud-rust repository.
  • The PR body should include a detailed description of the changes.
  • The PR will be reviewed by the maintainers.

Generated Code Maintenance

  • Most of the code is generated by the librarian tool.
  • Do not edit the generated code directly.
  • To update the generated code, you need to modify the generator templates or the service definitions. See doc/contributor/howto-guide-generated-code-maintenance.md for details.

Asynchronous Programming

All remote procedure calls (RPCs) are asynchronous and are designed to work with the Tokio runtime.

Error Handling

The libraries provide robust error handling, with a focus on providing clear and actionable error messages.

Retry and Polling Policies

The libraries include configurable policies for retrying failed requests and for polling the status of long-running operations. These policies can be customized by the application.

Contribution Guidelines

Contributions are welcome. The CONTRIBUTING.md file provides detailed instructions for contributors. Key documents for contributors include:

  • doc/contributor/howto-guide-set-up-development-environment.md
  • ARCHITECTURE.md