s3

Documentation

Overview

Package s3 provides an S3 integration block with a clean object storage API.

Index

• type Block
  • func New(name string, opts ...Option) *Block
  • func (b *Block) DeleteObject(ctx context.Context, key string) error
  • func (b *Block) GetObject(ctx context.Context, key string) (io.ReadCloser, ObjectMetadata, error)
  • func (b *Block) Init(ctx context.Context) error
  • func (b *Block) ListObjects(ctx context.Context, prefix string) ([]ObjectInfo, error)
  • func (b *Block) Name() string
  • func (b *Block) PresignGetURL(ctx context.Context, key string, expiry time.Duration) (string, error)
  • func (b *Block) PutObject(ctx context.Context, key string, body io.Reader, opts ...PutOption) error
  • func (b *Block) Shutdown(_ context.Context) error
• type ObjectInfo
• type ObjectMetadata
• type Option
  • func WithAWSConfig(cfg aws.Config) Option
  • func WithBucket(bucket string) Option
  • func WithEndpoint(endpoint string) Option
  • func WithKeyPrefix(prefix string) Option
  • func WithPathStyle() Option
  • func WithProfile(profile string) Option
  • func WithRegion(region string) Option
• type PutOption
  • func WithContentType(ct string) PutOption
  • func WithMetadata(m map[string]string) PutOption

Types

type Block

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

Block is an S3 integration block that exposes a clean object storage API.

func New

func New(name string, opts ...Option) *Block

New creates a new S3 Block.

block := s3.New("assets",
    s3.WithRegion("us-east-1"),
    s3.WithBucket("my-assets-bucket"),
    s3.WithKeyPrefix("uploads/"),
)

func (*Block) DeleteObject

func (b *Block) DeleteObject(ctx context.Context, key string) error

DeleteObject removes a single object by key.

func (*Block) GetObject

func (b *Block) GetObject(ctx context.Context, key string) (io.ReadCloser, ObjectMetadata, error)

GetObject retrieves an object by key. The caller is responsible for closing the returned ReadCloser.

func (*Block) Init

func (b *Block) Init(ctx context.Context) error

Init implements core.Block.

func (*Block) ListObjects

func (b *Block) ListObjects(ctx context.Context, prefix string) ([]ObjectInfo, error)

ListObjects returns all objects whose key starts with prefix (relative to the block's configured key prefix). Pagination is handled internally.

func (*Block) Name

func (b *Block) Name() string

Name implements core.Block.

func (*Block) PresignGetURL

func (b *Block) PresignGetURL(ctx context.Context, key string, expiry time.Duration) (string, error)

PresignGetURL generates a pre-signed GET URL that grants temporary access to an object without requiring AWS credentials.

func (*Block) PutObject

func (b *Block) PutObject(ctx context.Context, key string, body io.Reader, opts ...PutOption) error

PutObject uploads body under the given key. The key is automatically prefixed with the block's configured key prefix.

func (*Block) Shutdown

func (b *Block) Shutdown(_ context.Context) error

Shutdown implements core.Block.

type ObjectInfo

type ObjectInfo struct {
	Key          string
	Size         int64
	LastModified time.Time
	ETag         string
}

ObjectInfo represents a summary of an object returned by ListObjects.

type ObjectMetadata

type ObjectMetadata struct {
	ContentType   string
	ContentLength int64
	ETag          string
	LastModified  time.Time
}

ObjectMetadata holds selected metadata returned alongside a GetObject response.

type Option

type Option func(*blockConfig)

Option configures an S3 Block.

func WithAWSConfig

func WithAWSConfig(cfg aws.Config) Option

WithAWSConfig injects a pre-built aws.Config.

func WithBucket

func WithBucket(bucket string) Option

WithBucket sets the S3 bucket name.

func WithEndpoint

func WithEndpoint(endpoint string) Option

WithEndpoint overrides the S3 endpoint (e.g. "http://localhost:4566" for LocalStack). Automatically enables path-style addressing.

func WithKeyPrefix

func WithKeyPrefix(prefix string) Option

WithKeyPrefix sets an optional prefix prepended to every object key. Useful for namespacing objects within a shared bucket.

func WithPathStyle

func WithPathStyle() Option

WithPathStyle enables S3 path-style addressing. Required for MinIO and similar S3-compatible services.

func WithProfile

func WithProfile(profile string) Option

WithProfile selects a named AWS credentials profile.

func WithRegion

func WithRegion(region string) Option

WithRegion sets the AWS region.

type PutOption

type PutOption func(*putOptions)

PutOption configures a PutObject call.

func WithContentType

func WithContentType(ct string) PutOption

WithContentType sets the Content-Type header for uploaded objects.

func WithMetadata

func WithMetadata(m map[string]string) PutOption

WithMetadata attaches custom metadata key-value pairs to an uploaded object.