CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/golang-cloud-google-com--go

Google Cloud Client Libraries for Go providing documentation, authentication patterns, and utility packages for civil time types and HTTP/gRPC recording/replay functionality

Overview
Eval results
Files

index.mddocs/

cloud.google.com/go

Google Cloud Client Libraries for Go provides the foundational package for interacting with Google Cloud Platform services. This package serves as documentation and includes utility packages for civil time handling and HTTP/gRPC recording and replay functionality.

Package Information

  • Package Name: cloud.google.com/go
  • Package Type: golang
  • Language: Go
  • Installation: go get cloud.google.com/go@v0.123.0
  • Minimum Go Version: 1.24

Overview

The cloud.google.com/go package is the root of the Google Cloud Go client libraries. The root package itself contains comprehensive documentation about using Google Cloud client libraries, while actual functionality is provided through sub-packages.

This package provides:

  1. Documentation: Best practices for authentication, configuration, error handling, and common patterns
  2. civil: Time-zone-independent date/time types
  3. httpreplay: HTTP request/response recording and replay for testing
  4. rpcreplay: gRPC request/response recording and replay for testing

Core Imports

import (
    "cloud.google.com/go/civil"
    "cloud.google.com/go/httpreplay"
    "cloud.google.com/go/rpcreplay"
)

Basic Usage

package main

import (
    "context"
    "fmt"
    "time"

    "cloud.google.com/go/civil"
    "google.golang.org/api/option"
)

func main() {
    // Using civil time types
    today := civil.DateOf(time.Now())
    fmt.Printf("Today is %s\n", today)

    tomorrow := today.AddDays(1)
    fmt.Printf("Tomorrow is %s\n", tomorrow)

    // Parse a date
    date, _ := civil.ParseDate("2024-01-15")
    fmt.Printf("Parsed date: %s\n", date)
}

Authentication Patterns

All Google Cloud client libraries in sub-modules follow these authentication patterns:

Application Default Credentials (Recommended)

// ADC is used automatically when no credentials are specified
client, err := someservice.NewClient(ctx)

Service Account Key File

// Using environment variable
// Set GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

client, err := someservice.NewClient(ctx)

// Or programmatically
client, err := someservice.NewClient(ctx,
    option.WithCredentialsFile("/path/to/key.json"))

Programmatic Credentials

import "cloud.google.com/go/auth/credentials"

creds, err := credentials.DetectDefault(&credentials.DetectOptions{
    Scopes: someservice.DefaultAuthScopes(),
})
client, err := someservice.NewClient(ctx,
    option.WithAuthCredentials(creds))

Common Configuration Patterns

Endpoint Override

// For regional endpoints or testing
endpoint := "us-central1-aiplatform.googleapis.com:443"
client, err := someservice.NewClient(ctx,
    option.WithEndpoint(endpoint))

Timeouts and Cancellation

import "context"
import "time"

// Timeout using context
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

response, err := client.SomeOperation(ctx, request)

Connection Pooling (gRPC)

// Configure connection pool for gRPC clients
client, err := someservice.NewClient(ctx,
    option.WithGRPCConnectionPool(4))

Custom Headers

import "github.com/googleapis/gax-go/v2/callctx"

// Set custom headers
ctx := callctx.SetHeaders(context.Background(), "key", "value")
response, err := client.GetSomething(ctx, request)

Error Handling

import (
    "errors"
    "github.com/googleapis/gax-go/v2/apierror"
)

// Inspect API errors
if err != nil {
    var ae *apierror.APIError
    if errors.As(err, &ae) {
        // Get error details
        reason := ae.Reason()
        helpLinks := ae.Details().Help.GetLinks()

        // Get gRPC status if applicable
        grpcStatus := ae.GRPCStatus()
        code := grpcStatus.Code()
    }
}

Capabilities

Civil Time Types

Time-zone-independent date and time representations for use with storage APIs and databases.

// Date represents a calendar date
type Date struct {
    Year  int
    Month time.Month
    Day   int
}

// DateTime combines date and time
type DateTime struct {
    Date Date
    Time Time
}

// Time represents time of day
type Time struct {
    Hour       int
    Minute     int
    Second     int
    Nanosecond int
}

Civil Time Documentation

HTTP Recording and Replay

Record and replay HTTP interactions for testing HTTP-based Google API clients.

type Recorder struct {
    // Has unexported fields.
}

func NewRecorder(filename string, initial []byte) (*Recorder, error)

type Replayer struct {
    // Has unexported fields.
}

func NewReplayer(filename string) (*Replayer, error)

HTTP Replay Documentation

gRPC Recording and Replay

Record and replay gRPC interactions for testing gRPC-based Google API clients.

type Recorder struct {
    BeforeFunc func(string, proto.Message) error
    // Has unexported fields.
}

func NewRecorder(filename string, initial []byte) (*Recorder, error)

type Replayer struct {
    BeforeFunc func(string, proto.Message) error
    // Has unexported fields.
}

func NewReplayer(filename string) (*Replayer, error)

gRPC Replay Documentation

Important Notes

Client Library Locations

Individual Google Cloud service client libraries (Storage, Firestore, BigQuery, Pub/Sub, etc.) are provided as separate sub-modules with independent versioning. For example:

  • cloud.google.com/go/storage - Cloud Storage client
  • cloud.google.com/go/firestore - Firestore client
  • cloud.google.com/go/bigquery - BigQuery client

These are not part of the root cloud.google.com/go package but follow the patterns documented here.

Experimental Packages

The httpreplay and rpcreplay packages are marked as EXPERIMENTAL and subject to change or removal without notice.

Container Environments

Minimal container images (like Alpine) lack CA certificates, which can cause RPCs to hang. Install CA certificates in your container images when using these libraries.

Supported Go Versions

The libraries support the two most recent major Go releases (currently Go 1.24 and 1.25).

Install with Tessl CLI

npx tessl i tessl/golang-cloud-google-com--go

docs

civil.md

httpreplay.md

index.md

rpcreplay.md

tile.json