Integration CloudStorage Extension

Integration: Google Cloud Storage Extension

Track Google Cloud Storage operations in your test diagrams using the Kronikol.Extensions.CloudStorage NuGet package. This extension intercepts GCS HTTP traffic via the Google APIs HttpClientFactory pipeline and logs operations for diagram generation.

Using a shared library or abstraction layer? If your code doesn't use the GCS SDK directly — e.g. it goes through a shared storage library, wrapper, or custom abstraction — this extension won't be able to intercept the underlying calls. See Tracking Custom Dependencies for alternative approaches including RequestResponseLogger.LogPair(), TrackingProxy<T>, and MessageTracker.

Installation

dotnet add package Kronikol.Extensions.CloudStorage

Quick Start

using Google.Cloud.Storage.V1;
using Kronikol.Extensions.CloudStorage;

var client = new StorageClientBuilder()
    .WithTestTracking(new CloudStorageTrackingMessageHandlerOptions
    {
        ServiceName = "CloudStorage",
        CallerName = "OrdersApi",
        Verbosity = CloudStorageTrackingVerbosity.Detailed,
        CurrentTestInfoFetcher = () => (TestContext.CurrentTestName, TestContext.CurrentTestId)
    })
    .Build();

How It Works

The extension uses the same Google APIs HttpClientFactory pattern as the BigQuery extension. WithTestTracking() sets a TrackingCloudStorageHttpClientFactory on the StorageClientBuilder, which inserts a CloudStorageTrackingMessageHandler into the HTTP pipeline.

The handler:

1. Classifies each request by URL path pattern using CloudStorageOperationClassifier
2. Logs request/response pairs via RequestResponseLogger
3. No body reading needed for classification — operations are determined entirely from URL path and HTTP method

GCS REST API Pattern

GCS uses a JSON-based REST API with predictable URL patterns:

HTTP Method	Path Pattern	Operation
POST	/upload/storage/v1/b/{bucket}/o	Upload
PUT	/storage/v1/b/{bucket}/o/{object}	Upload (simple)
GET	/storage/v1/b/{bucket}/o/{object}?alt=media	Download
GET	/storage/v1/b/{bucket}/o/{object}	GetMetadata
DELETE	/storage/v1/b/{bucket}/o/{object}	Delete
GET	/storage/v1/b/{bucket}/o	ListObjects
PATCH	/storage/v1/b/{bucket}/o/{object}	UpdateMetadata
POST	.../o/{object}/copyTo/...	Copy
POST	.../o/{object}/compose	Compose
GET/POST/DELETE	/storage/v1/b[/{bucket}]	Bucket operations

Supported Operations

Operation	Enum Value
Upload	CloudStorageOperation.Upload
Download	CloudStorageOperation.Download
Delete	CloudStorageOperation.Delete
ListObjects	CloudStorageOperation.ListObjects
GetMetadata	CloudStorageOperation.GetMetadata
UpdateMetadata	CloudStorageOperation.UpdateMetadata
Copy	CloudStorageOperation.Copy
Compose	CloudStorageOperation.Compose
CreateBucket	CloudStorageOperation.CreateBucket
DeleteBucket	CloudStorageOperation.DeleteBucket
GetBucket	CloudStorageOperation.GetBucket
ListBuckets	CloudStorageOperation.ListBuckets

Unrecognised operations (e.g. API discovery requests) are classified as CloudStorageOperation.Other.

Download vs GetMetadata

The classifier distinguishes between Download and GetMetadata by checking for the alt=media query parameter:

• GET .../o/file.txt?alt=media → Download (returns object content)
• GET .../o/file.txt → GetMetadata (returns JSON metadata)

Verbosity Levels

CloudStorageTrackingVerbosity.Summarised

Minimal output for clean diagrams:

• Method label: Operation name (e.g. Upload)
• URI: gcs:///my-bucket
• Content: Omitted
• Headers: Omitted
• Other operations: Skipped entirely

CloudStorageTrackingVerbosity.Detailed

Balanced output for debugging:

• Method label: Operation with context (e.g. Upload → my-bucket/file.txt)
• URI: gcs:///my-bucket/file.txt
• Content: Included
• Headers: Included (with default exclusions)

CloudStorageTrackingVerbosity.Raw

Full HTTP-level output:

• Method: HTTP method (e.g. POST)
• URI: Original Google API URL
• Content: Full request/response bodies
• Headers: All headers (with default exclusions)
• Other operations: Included

Configuration Options

new CloudStorageTrackingMessageHandlerOptions
{
    // Display name in diagrams
    ServiceName = "CloudStorage",

    // Calling service name in diagrams
    CallerName = "OrdersApi",

    // Verbosity level (default: Detailed)
    Verbosity = CloudStorageTrackingVerbosity.Detailed,

    // Required: provides test context for log correlation
    CurrentTestInfoFetcher = () => (testName, testId),

    // Headers excluded from logging (defaults below)
    ExcludedHeaders = new HashSet<string>
    {
        "Authorization", "x-goog-api-client", "User-Agent"
    }
}

CloudStorageTrackingMessageHandlerOptions

Property	Type	Default	Description
ServiceName	string	"CloudStorage"	Display name in diagrams for the Cloud Storage service
CallerName	string	"Caller"	Calling service name in diagrams
Verbosity	CloudStorageTrackingVerbosity	Detailed	Verbosity level (Raw, Detailed, Summarised)
CurrentTestInfoFetcher	Func<(string Name, string Id)>?	null	Required: provides test context for log correlation
CurrentStepTypeFetcher	Func<string?>?	null	Optional — returns the current BDD step type (Given/When/Then)
HttpContextAccessor	IHttpContextAccessor?	null	Optional — enables dual-resolution of test identity from HTTP headers. Auto-resolved by DI extensions (v2.26.3+). See HTTP Tracking Setup#Dual-Resolution Test Identity (v2.23.0+)
ExcludedHeaders	HashSet<string>	See above	Headers excluded from logging
SetupVerbosity	CloudStorageTrackingVerbosity?	null	Verbosity override for the Setup phase. See Phase-Aware Tracking
ActionVerbosity	CloudStorageTrackingVerbosity?	null	Verbosity override for the Action phase. See Phase-Aware Tracking
TrackDuringSetup	bool	true	When false, tracking is suppressed during Setup. See Phase-Aware Tracking
TrackDuringAction	bool	true	When false, tracking is suppressed during Action. See Phase-Aware Tracking

v2.23.0+ Dual-Resolution: CloudStorageTrackingMessageHandler accepts an optional IHttpContextAccessor? httpContextAccessor constructor parameter for resolving test identity from HTTP request headers when running inside the SUT's request pipeline. v2.26.3+: Set HttpContextAccessor on CloudStorageTrackingMessageHandlerOptions instead — the tracker reads it automatically. See HTTP Tracking Setup#Dual-Resolution Test Identity (v2.23.0+) for details.

ITrackingComponent

CloudStorageTrackingMessageHandler implements ITrackingComponent and auto-registers with TrackingComponentRegistry on construction. This provides:

• ComponentName: "CloudStorageTrackingMessageHandler ({ServiceName})"
• WasInvoked: true after first request
• InvocationCount: Total requests processed

URI Scheme

Classified requests use the gcs:/// URI scheme:

gcs:///my-bucket/file.txt       (object operations)
gcs:///my-bucket                (bucket operations)
gcs:///                         (global operations like ListBuckets)

The path-based format (three slashes) preserves bucket and object name casing.

See Also

• Integration: BigQuery Extension
• Integration: BlobStorage Extension
• Integration: Amazon S3 Extension