BeeQ.FileStorage.GoogleCloud 1.0.0

BeeQ.FileStorage.GoogleCloud

A lightweight file storage adapter that integrates Google Cloud Storage with the BeeQ FileStorage abstractions.

This library provides a simple, opinionated implementation of IFileStorage backed by Google Cloud Storage. It exposes convenient methods for uploading, downloading, copying and listing objects, creating and managing buckets, and generating temporary signed URLs.

Features

• Pluggable configuration (credentials, encryption keys, custom path templates)
• Support for custom identifier types (generic <TId>)
• Helper methods for bucket and object management
• Generates temporary signed URLs for direct downloads

Installation

Install the NuGet package (publish name: BeeQ.FileStorage.GoogleCloud):

dotnet add package BeeQ.FileStorage.GoogleCloud

Quick start

Register the Google Cloud implementation using the provided builder extensions. The examples assume you are configuring a BeeQ file storage builder in your application startup code.

Using the default Guid identifier:

builder.UseGoogleCloud("my-schema", options =>
{
	options.BasePath = "files"; // optional if PathTemplate is provided
	options.Credentials = GoogleCredential.FromFile("path/to/service-account.json");
	// optional: options.EncryptionKey = new EncryptionKey(...);
});

Using a custom identifier type TId:

builder.UseGoogleCloud<long>("my-schema", options =>
{
	options.BasePath = "files";
	options.OnCreateId = async ctx => {
		// return new id for created object
		return await Task.FromResult(GenerateIdFrom(ctx.Filename));
	};
});

Common operations

• Upload a stream: Use the IFileStorage.Upload methods provided by the BeeQ abstractions. The adapter will use configured options to build object keys and upload using the Google Cloud client.
• Download a stream: Use IFileStorage.Get or the adapter's GetTemporalyUrl to generate a signed URL for direct download.
• Bucket management: CreateBucket, GetBucket, GetBuckets, DeleteBucket and DeleteBucketWithFiles are available on IGoogleCloudService to manage buckets programmatically.

Configuration details

• StorageClientBuilder: Provide a StorageClientBuilder to customize client creation (useful for emulators or custom endpoints).
• Credentials: Supply a GoogleCredential (for example from a service account JSON file) or rely on default application credentials.
• EncryptionKey: Optional customer-supplied encryption key for object-level encryption.
• BasePath vs PathTemplate: Either set a BasePath (string) or provide a PathTemplate function to control how object names are derived from file identifiers.
• OnCreateId: Required when using a non-Guid identifier type to generate ids for newly created objects.

Permissions and signing

To generate signed URLs (GetTemporalyUrl), the configured credentials must allow signing. For service accounts this normally requires permissions such as iam.serviceAccounts.signBlob or using a Storage client with signing enabled.

Notes

• This library is an adapter and depends on the Google Cloud Storage client libraries. Ensure your runtime environment has network access to Google Cloud or to the configured emulator.
• Exceptions thrown by the library are documented and represent configuration issues (for example, missing BasePath or missing OnCreateId for non-Guid TId).

Contributing

Contributions, bug reports and pull requests are welcome. Please follow the repository guidelines and keep changes focused and well-tested.

License

This project is licensed under the terms found in the repository LICENSE file.