Documentation
¶
Overview ¶
Package gcs implements blob.Store on Google Cloud Storage.
Authentication uses Application Default Credentials (Workload Identity, Cloud Run / GCE metadata, GOOGLE_APPLICATION_CREDENTIALS, gcloud user credentials) unless a credentials file is configured. An endpoint override targets emulators (fake-gcs-server); plain-http endpoints are used without authentication, and presigning is then unavailable.
ETags are derived from the object generation, which changes on every write, so Get, GetRange, Stat, List and Put report identical ETags for the same object version.
Presigned URLs are V4 signed URLs: with a service-account key they are signed locally, otherwise (Cloud Run, GCE, GKE Workload Identity) through the IAM Credentials SignBlob API as cfg.SignerEmail (or the detected default service account), which needs roles/iam.serviceAccountTokenCreator on that account.
Presigned uploads sign Content-Type and, when the size is known, x-goog-content-length-range: <size>,<size>, so GCS rejects a body of any other size. GCS cannot verify a SHA-256 digest (it only checks MD5 and CRC32C), so PresignPutOptions.SHA256 is not enforced.
Index ¶
- type Option
- type Store
- func (s *Store) Client() *storage.Client
- func (s *Store) Close() error
- func (s *Store) Delete(ctx context.Context, key string) error
- func (s *Store) DeletePrefix(ctx context.Context, prefix string) error
- func (s *Store) Describe() blob.Description
- func (s *Store) Get(ctx context.Context, key string) (io.ReadCloser, *blob.ObjectInfo, error)
- func (s *Store) GetRange(ctx context.Context, key string, offset, length int64) (io.ReadCloser, *blob.ObjectInfo, error)
- func (s *Store) List(ctx context.Context, prefix, delimiter string) (*blob.ListResult, error)
- func (s *Store) Ping(ctx context.Context) error
- func (s *Store) PresignGet(_ context.Context, key string, ttl time.Duration) (*blob.PresignedRequest, error)
- func (s *Store) PresignPut(_ context.Context, key string, opts blob.PresignPutOptions, ttl time.Duration) (*blob.PresignedRequest, error)
- func (s *Store) Put(ctx context.Context, key string, r io.Reader, size int64, contentType string) (*blob.ObjectInfo, error)
- func (s *Store) Stat(ctx context.Context, key string) (*blob.ObjectInfo, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*options)
Option configures a Store.
func WithClientOptions ¶
func WithClientOptions(opts ...option.ClientOption) Option
WithClientOptions adds Google API client options (applied last).
func WithLogger ¶
WithLogger sets the logger (default slog.Default()).
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is a blob.Store backed by a GCS bucket (optionally under a key prefix). It is safe for concurrent use.
func New ¶
New creates a Store from configuration. It does not contact GCS; use Ping to verify access.
func (*Store) DeletePrefix ¶
DeletePrefix removes every object whose key starts with prefix (deletes run concurrently). An empty prefix is rejected.
func (*Store) Describe ¶
func (s *Store) Describe() blob.Description
Describe returns the public storage description.
func (*Store) Get ¶
func (s *Store) Get(ctx context.Context, key string) (io.ReadCloser, *blob.ObjectInfo, error)
Get opens an object for reading.
func (*Store) GetRange ¶
func (s *Store) GetRange(ctx context.Context, key string, offset, length int64) (io.ReadCloser, *blob.ObjectInfo, error)
GetRange reads length bytes from offset (length < 0 = to the end). The returned ObjectInfo describes the whole object; ranges past the end yield an empty body.
func (*Store) List ¶
List returns all objects under prefix, sorted by key. With delimiter "/", keys below the next "/" are folded into Prefixes.
func (*Store) Ping ¶
Ping checks bucket access: bucket metadata, falling back to listing one object when the identity may read objects but not bucket metadata (e.g. roles/storage.objectAdmin).
func (*Store) PresignGet ¶
func (s *Store) PresignGet(_ context.Context, key string, ttl time.Duration) (*blob.PresignedRequest, error)
PresignGet returns a V4 signed download URL.
func (*Store) PresignPut ¶
func (s *Store) PresignPut(_ context.Context, key string, opts blob.PresignPutOptions, ttl time.Duration) (*blob.PresignedRequest, error)
PresignPut returns a V4 signed URL accepting a PUT of the object's bytes. Headers carries the signed headers, which must be sent verbatim: Content-Type and, when opts.Size >= 0, x-goog-content-length-range pinning the body to exactly that size. opts.SHA256 cannot be enforced by GCS.
Source Files