README
¶
Blob Storage Factory
This package provides a factory for creating blob storage buckets with provider-specific initialization, particularly for features like signed URLs.
Overview
The BucketFactory handles provider-specific initialization (like GCS signed URL support) and returns standard gocloud *blob.Bucket instances. No wrappers, no custom interfaces - just properly configured buckets.
Design
Simple Factory Pattern
// Create factory with configuration
factory, err := blobstorage.NewBucketFactory(ctx, blobstorage.Config{
BucketURL: "gs://my-bucket/",
GCSServiceAccount: "svc@project.iam.gserviceaccount.com",
})
// Get a standard blob.Bucket with all initialization done
bucket, err := factory.OpenBucket(ctx)
defer bucket.Close()
// Use the bucket - signed URLs work because factory configured it
url, _ := bucket.SignedURL(ctx, "file.pack", &blob.SignedURLOptions{
Expiry: time.Hour,
})
What It Does
- Detects Provider: Automatically detects provider from URL scheme (gs://, s3://, etc.)
- Handles Initialization: Performs provider-specific setup (like GCS IAM for signed URLs)
- Returns Standard Bucket: Returns plain
*blob.Bucket- no wrappers needed
Supported Providers
Google Cloud Storage (GCS)
URL Scheme: gs://
Service Account: Required for GCS buckets
factory, err := blobstorage.NewBucketFactory(ctx, blobstorage.Config{
BucketURL: "gs://my-bucket/",
GCSServiceAccount: "service-account@project.iam.gserviceaccount.com",
})
Requirements:
- Service account email must be provided
- Service account must have "Service Account Token Creator" role
- IAM Credentials API must be enabled
- Default application credentials must be configured
Note: The factory will return an error if GCSServiceAccount is not provided for gs:// URLs.
Amazon S3
URL Scheme: s3://
Signed URL Support: Works automatically with default AWS credentials
factory, err := blobstorage.NewBucketFactory(ctx, blobstorage.Config{
BucketURL: "s3://my-bucket/",
})
No additional configuration needed - signed URLs work out of the box.
Azure Blob Storage
URL Scheme: azblob://
Signed URL Support: Uses default Azure credentials from environment
factory, err := blobstorage.NewBucketFactory(ctx, blobstorage.Config{
BucketURL: "azblob://my-container/",
})
File System / In-Memory
URL Schemes: file://, mem://
Use Case: Local development and testing
factory, err := blobstorage.NewBucketFactory(ctx, blobstorage.Config{
BucketURL: "mem://test-bucket/",
})
How It Works
GCS Signed URL Implementation
For GCS buckets with GCSServiceAccount configured:
- Factory creates GCP HTTP client with default credentials
- Factory creates IAM credentials service
- When opening bucket, factory configures:
GoogleAccessID(service account email)MakeSignBytescallback (uses IAM API to sign)
- Returns standard
*blob.Bucketwith signing configured
Other Providers
For S3, Azure, file://, mem://, etc.:
- Factory calls
blob.OpenBucket(ctx, bucketURL)directly - Provider's default behavior handles everything
- Returns standard
*blob.Bucket
References
Documentation
¶
Overview ¶
Package blobstorage provides a factory for creating blob storage buckets with provider-specific initialization.
The factory handles provider-specific configuration such as signed URL support for GCS, then returns standard gocloud blob.Bucket instances.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrBucketURLRequired is returned when bucket URL is not provided. ErrBucketURLRequired = errors.New("bucket URL is required") // ErrGCSServiceAccountRequired is returned when GCS service account is not provided for gs:// URLs. // See scripts/create-dev-service-account.sh for details of what permissions the SA needs. ErrGCSServiceAccountRequired = errors.New("GCS service account is required for gs:// bucket URLs") )
Functions ¶
This section is empty.
Types ¶
type BucketFactory ¶
type BucketFactory struct {
// contains filtered or unexported fields
}
BucketFactory creates blob storage buckets with provider-specific initialization.
func NewBucketFactory ¶
func NewBucketFactory(ctx context.Context, config Config) (*BucketFactory, error)
NewBucketFactory creates a new bucket factory with the given configuration. For GCS buckets, a service account is required for signed URL support.
func (*BucketFactory) GetBucketURL ¶
func (f *BucketFactory) GetBucketURL() string
GetBucketURL returns the configured bucket URL.
func (*BucketFactory) OpenBucket ¶
OpenBucket opens a bucket with provider-specific configuration. Returns a standard gocloud blob.Bucket with all initialization done.
type Config ¶
type Config struct {
// BucketURL is the full bucket URL (e.g., "gs://bucket-name/", "s3://bucket-name/")
BucketURL string
// GCS-specific configuration for signed URL support
GCSServiceAccount string // Service account email (required for gs:// URLs)
}
Config holds configuration for creating blob storage buckets.
Source Files