Experimental Features

/**
 * Enables bi-directional gRPC for downloads (private preview).
 * Improves download performance with streaming reads.
 * Only applicable for gRPC clients.
 * @returns option.ClientOption
 */
func WithGRPCBidiReads() option.ClientOption

/**
 * Enables zonal bucket APIs and appendable objects (private preview).
 * Allows use of Writer.Append functionality.
 * Only applicable for gRPC clients.
 * @returns option.ClientOption
 */
func WithZonalBucketAPIs() option.ClientOption

/**
 * Configures dynamic read stall timeout.
 * Automatically retries stalled downloads with dynamic timeout adjustment.
 * @param config - Stall timeout configuration
 * @returns option.ClientOption
 */
func WithReadStallTimeout(config *ReadStallTimeoutConfig) option.ClientOption

/**
 * Sets a custom OpenTelemetry meter provider.
 * Enables custom metrics collection for gRPC operations.
 * @param mp - MeterProvider from go.opentelemetry.io/otel/metric
 * @returns option.ClientOption
 */
func WithMeterProvider(mp metric.MeterProvider) option.ClientOption

/**
 * Sets a custom metric exporter.
 * @param ex - Metric reader from go.opentelemetry.io/otel/sdk/metric
 * @returns option.ClientOption
 */
func WithMetricExporter(ex metric.Reader) option.ClientOption

/**
 * Sets the metric emission interval.
 * @param d - Interval duration
 * @returns option.ClientOption
 */
func WithMetricInterval(d time.Duration) option.ClientOption

/**
 * ReadStallTimeoutConfig configures dynamic stall timeout for reads.
 * Automatically adjusts timeout based on observed latencies.
 */
type ReadStallTimeoutConfig struct {
    // Min is the minimum timeout duration
    // Default: 500ms
    Min time.Duration

    // TargetPercentile is the target percentile for dynamic adjustment
    // Range: 0.0 to 1.0
    // Default: 0.99 (99th percentile)
    TargetPercentile float64
}

import (
    "context"
    "time"
    "cloud.google.com/go/storage"
    "cloud.google.com/go/storage/experimental"
    "go.opentelemetry.io/otel/metric"
    "go.opentelemetry.io/otel/sdk/metric"
)

// Enable bi-directional gRPC reads
ctx := context.Background()
client, err := storage.NewGRPCClient(ctx,
    experimental.WithGRPCBidiReads(),
)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Download with bidi streaming
obj := client.Bucket("my-bucket").Object("large-file.dat")
r, err := obj.NewReader(ctx)
if err != nil {
    log.Fatal(err)
}
defer r.Close()

data, err := io.ReadAll(r)
if err != nil {
    log.Fatal(err)
}

// Enable zonal bucket APIs and appendable objects
client, err = storage.NewGRPCClient(ctx,
    experimental.WithZonalBucketAPIs(),
)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Use appendable object semantics
obj = client.Bucket("my-bucket").Object("append-log.txt")
w := obj.NewWriter(ctx)
w.Append = true              // Enable append mode
w.FinalizeOnClose = false    // Don't finalize on close

// First append
if _, err := w.Write([]byte("Log entry 1\n")); err != nil {
    log.Fatal(err)
}
if err := w.Flush(); err != nil {
    log.Fatal(err)
}

// Second append
if _, err := w.Write([]byte("Log entry 2\n")); err != nil {
    log.Fatal(err)
}
if err := w.Flush(); err != nil {
    log.Fatal(err)
}

// Finalize the object
w.FinalizeOnClose = true
if err := w.Close(); err != nil {
    log.Fatal(err)
}

// Configure read stall timeout
stallConfig := &experimental.ReadStallTimeoutConfig{
    Min:              1 * time.Second,
    TargetPercentile: 0.95, // 95th percentile
}

client, err = storage.NewClient(ctx,
    experimental.WithReadStallTimeout(stallConfig),
)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Downloads will automatically retry on stall with dynamic timeout
obj = client.Bucket("my-bucket").Object("data.bin")
r, err = obj.NewReader(ctx)
if err != nil {
    log.Fatal(err)
}
defer r.Close()

data, err = io.ReadAll(r)
// Automatically retries if read stalls

// Custom OpenTelemetry metrics
exporter := metric.NewManualReader()
meterProvider := metric.NewMeterProvider(
    metric.WithReader(exporter),
)

client, err = storage.NewGRPCClient(ctx,
    experimental.WithMeterProvider(meterProvider),
    experimental.WithMetricInterval(10*time.Second),
)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Perform operations - metrics are collected
obj = client.Bucket("my-bucket").Object("file.txt")
w = obj.NewWriter(ctx)
w.Write([]byte("Hello"))
w.Close()

// Read metrics
var rm metricdata.ResourceMetrics
exporter.Collect(ctx, &rm)
fmt.Printf("Metrics: %+v\n", rm)

// Use custom metric exporter
reader := metric.NewPeriodicReader(
    // Your custom exporter
    metric.WithInterval(30*time.Second),
)

client, err = storage.NewGRPCClient(ctx,
    experimental.WithMetricExporter(reader),
)
if err != nil {
    log.Fatal(err)
}
defer client.Close()