s3

Documentation

Index

• func New(opts ...Option) func(gas.ConfigProvider, gas.Logger) *Service
• type Config
  • func DefaultConfig() *Config
  • func (c *Config) Validate() error
• type Option
  • func WithConfig(cfg *Config) Option
• type Service
  • func (s *Service) CheckReady(ctx context.Context) error
  • func (s *Service) Client() *s3.Client
  • func (s *Service) Close() error
  • func (s *Service) Delete(ctx context.Context, key string, opts ...gas.StorageOption) error
  • func (s *Service) Download(ctx context.Context, key string, opts ...gas.StorageOption) (*gas.StorageObject, error)
  • func (s *Service) Head(ctx context.Context, key string, opts ...gas.StorageOption) (*gas.ObjectInfo, error)
  • func (s *Service) Init() error
  • func (s *Service) Name() string
  • func (s *Service) PresignDownloadURL(ctx context.Context, key string, expiry time.Duration, ...) (string, error)
  • func (s *Service) PresignUploadURL(ctx context.Context, key string, expiry time.Duration, ...) (string, error)
  • func (s *Service) Upload(ctx context.Context, key string, data io.Reader, opts ...gas.StorageOption) error
• type Settings

Functions

func New

func New(opts ...Option) func(gas.ConfigProvider, gas.Logger) *Service

New captures options and returns a DI-injectable constructor.

Types

type Config

type Config struct {
	env.WithGasEnv

	Storage Settings
}

Config holds S3 storage settings.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a Config with sensible defaults.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks the Config for correctness. Storage.Bucket is optional; when unset, callers must supply gas.InBucket() per operation.

type Option

type Option func(*Service)

Option configures a Service.

func WithConfig

func WithConfig(cfg *Config) Option

WithConfig sets a custom configuration.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service is an S3-backed storage implementing gas.Service and gas.StorageProvider.

func (*Service) CheckReady

func (s *Service) CheckReady(ctx context.Context) error

CheckReady reports whether the service can accept traffic. When a default bucket is configured, it issues a HeadBucket against it to verify that credentials are valid and the bucket is reachable from this pod.

IAM requirement: the caller's principal MUST have the s3:ListBucket permission on the configured bucket. Without it, HeadBucket returns 403 and the readiness probe will fail, preventing the pod from receiving traffic. If your deployment scopes S3 permissions narrowly (e.g. only s3:GetObject / s3:PutObject on specific prefixes), add s3:ListBucket on the bucket resource to the policy.

When no default bucket is configured (per-call bucket mode), readiness succeeds as soon as Init has completed — there is no single bucket to probe, and reachability is the caller's responsibility.

func (*Service) Client

func (s *Service) Client() *s3.Client

Client returns the underlying S3 client for advanced operations.

func (*Service) Close

func (s *Service) Close() error

Close marks the service as closed.

func (*Service) Delete

func (s *Service) Delete(ctx context.Context, key string, opts ...gas.StorageOption) error

Delete deletes an object from S3.

func (*Service) Download

func (s *Service) Download(ctx context.Context, key string, opts ...gas.StorageOption) (*gas.StorageObject, error)

Download downloads an object from S3. Returns storage.ErrKeyNotFound if the key does not exist.

func (*Service) Head

func (s *Service) Head(ctx context.Context, key string, opts ...gas.StorageOption) (*gas.ObjectInfo, error)

Head retrieves object metadata without downloading the body. Returns storage.ErrKeyNotFound if the key does not exist.

func (*Service) Init

func (s *Service) Init() error

Init validates the configuration and creates the S3 client.

func (*Service) Name

func (s *Service) Name() string

Name returns the service identifier.

func (*Service) PresignDownloadURL

func (s *Service) PresignDownloadURL(ctx context.Context, key string, expiry time.Duration, opts ...gas.StorageOption) (string, error)

PresignDownloadURL generates a presigned GET URL for the specified object key, valid for the given expiry duration.

func (*Service) PresignUploadURL

func (s *Service) PresignUploadURL(ctx context.Context, key string, expiry time.Duration, opts ...gas.StorageOption) (string, error)

PresignUploadURL generates a presigned PUT URL for the specified object key, valid for the given expiry duration.

func (*Service) Upload

func (s *Service) Upload(ctx context.Context, key string, data io.Reader, opts ...gas.StorageOption) error

Upload uploads an object to S3.

type Settings

type Settings struct {
	// Region is the AWS region for the S3 bucket.
	Region string

	// Bucket is the S3 bucket name.
	Bucket string

	// AccessKeyID is the AWS access key.
	AccessKeyID string

	// SecretAccessKey is the AWS secret access key.
	//nolint:gosec // intentional config field
	SecretAccessKey string

	// Endpoint is an optional custom S3 endpoint for S3-compatible
	// services (MinIO, LocalStack, DigitalOcean Spaces, etc.).
	// When set, path-style addressing is enabled automatically.
	Endpoint string
}

Settings represents the configuration for the S3 storage service.