s3

Documentation

Index

• Constants
• func IsBucketExistsErr(err error) bool
• func IsBucketNotFoundErr(err error) bool
• func IsNotFoundErr(err error) bool
• func IsObjectNotFoundErr(err error) bool
• type Client
  • func NewClient(region string) *Client
  • func NewClientFromEnv() *Client
  • func NewClientWithConfig(cfg *aws.Config) *Client
  • func (c *Client) AWSClient() *s3.S3
  • func (c *Client) AWSSession() *session.Session
  • func (c *Client) CheckBucket(ctx context.Context, bucket string) error
  • func (c *Client) CreateBucket(ctx context.Context, bucket string) error
  • func (c *Client) DeleteBucket(ctx context.Context, bucket string) error
  • func (c *Client) DeleteObjectSet(ctx context.Context, bucket string, keys []string) error
  • func (c *Client) EmptyBucket(ctx context.Context, bucket string) error
  • func (c *Client) GetObject(bucket, key string) ([]byte, bool, error)
  • func (c *Client) GetObjectFromURL(ctx context.Context, signedURL string) ([]byte, error)
  • func (c *Client) GetObjectToStruct(ctx context.Context, bucket, key string, dataStruct any) (bool, error)
  • func (c *Client) GetObjectWithContext(ctx context.Context, bucket, key string) ([]byte, bool, error)
  • func (c *Client) GetSignedObjectURL(ctx context.Context, bucket, key string) (string, error)
  • func (c *Client) GetSignedObjectURLWithDuration(ctx context.Context, bucket, key string, duration time.Duration) (string, error)
  • func (c *Client) GetSignedPutUploadURL(ctx context.Context, bucket, key string, metadata map[string]*string) (string, error)
  • func (c *Client) GetSignedPutUploadURLWithDuration(ctx context.Context, bucket, key string, metadata map[string]*string, ...) (string, error)
  • func (c *Client) HasObject(bucket, key string) (bool, error)
  • func (c *Client) ListBuckets(ctx context.Context) ([]string, error)
  • func (c *Client) ListObjects(ctx context.Context, bucket, prefix, cursor string, limit int) ([]*ObjectInfo, string, error)
  • func (c *Client) ListPageObjects(ctx context.Context, bucket, prefix, cursor string, count int64) ([]*ObjectInfo, string, error)
  • func (c *Client) PutObject(ctx context.Context, bucket, key string, body io.Reader, ...) error
  • func (c *Client) ReadObject(ctx context.Context, bucket, key string, wa io.WriterAt) (bool, error)
  • func (c *Client) Region() string
  • func (c *Client) RenameObject(bucket, oldKey, newKey string) (bool, error)
  • func (c *Client) SaveObjectData(ctx context.Context, bucket, key string, data []byte) error
  • func (c *Client) SaveObjectFile(ctx context.Context, bucket, key, filePath string) error
  • func (c *Client) SaveObjectFileWithMetadata(ctx context.Context, bucket, key, filePath string, metadata map[string]string) error
  • func (c *Client) SaveObjectStream(ctx context.Context, bucket, key string, r io.Reader) error
  • func (c *Client) StreamObject(bucket, key string, w io.Writer) (bool, error)
  • func (c *Client) UploadObjectToURL(ctx context.Context, signedURL string, objectData []byte) error
• type ObjectInfo
• type SyncWriterAt
  • func (a SyncWriterAt) WriteAt(p []byte, offset int64) (n int, err error)

Constants

const (
	BatchSize            = 1000
	DefaultDurationLimit = 30 * time.Minute
)

Constants for default configurations.

const (
	NotFoundErr      = "NotFound"
	AlreadyExistsErr = "AlreadyExists"
)

Helper Functions

Functions

func IsBucketExistsErr

func IsBucketExistsErr(err error) bool

IsBucketExistsErr checks if the error returned by AWS SDK indicates that the bucket already exists.

func IsBucketNotFoundErr

func IsBucketNotFoundErr(err error) bool

IsBucketNotFoundErr checks if the given error is a "Bucket Not Found" error, including AWS S3 specific "NoSuchBucket" error. It returns true if the error is a "Bucket Not Found" error, otherwise false.

func IsNotFoundErr

func IsNotFoundErr(err error) bool

IsNotFoundErr checks if the error returned by AWS SDK is a NotFound error.

func IsObjectNotFoundErr

func IsObjectNotFoundErr(err error) bool

IsObjectNotFoundErr checks if the given error is an "Object Not Found" error, including AWS S3 specific "NoSuchKey" error. It returns true if the error is an "Object Not Found" error, otherwise false.

Types

type Client

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

Client is a wrapper around AWS S3 client providing additional utility methods.

func NewClient

func NewClient(region string) *Client

NewClient creates a new S3 client with the specified AWS region. If no region is provided, it defaults to "us-east-1".

func NewClientFromEnv

func NewClientFromEnv() *Client

NewClientFromEnv creates a new S3 client using AWS SDK configuration from environment variables.

func NewClientWithConfig

func NewClientWithConfig(cfg *aws.Config) *Client

NewClientWithConfig creates a new S3 client with a custom AWS configuration.

func (*Client) AWSClient

func (c *Client) AWSClient() *s3.S3

AWSClient returns the underlying AWS S3 client.

func (*Client) AWSSession

func (c *Client) AWSSession() *session.Session

AWSSession returns the underlying AWS session.

func (*Client) CheckBucket

func (c *Client) CheckBucket(ctx context.Context, bucket string) error

CheckBucket verifies if the specified bucket exists and is accessible.

func (*Client) CreateBucket

func (c *Client) CreateBucket(ctx context.Context, bucket string) error

CreateBucket creates a new S3 bucket. If the bucket already exists, it does not return an error.

func (*Client) DeleteBucket

func (c *Client) DeleteBucket(ctx context.Context, bucket string) error

DeleteBucket deletes the specified S3 bucket after emptying its contents.

func (*Client) DeleteObjectSet

func (c *Client) DeleteObjectSet(ctx context.Context, bucket string, keys []string) error

DeleteObjectSet deletes multiple objects from the specified bucket. It ignores "NoSuchKey" errors.

func (*Client) EmptyBucket

func (c *Client) EmptyBucket(ctx context.Context, bucket string) error

EmptyBucket removes all objects from the specified S3 bucket.

func (*Client) GetObject

func (c *Client) GetObject(bucket, key string) ([]byte, bool, error)

GetObject retrieves the object data from the specified bucket and key. It returns the data, a boolean indicating if the object was found, and an error if any.

func (*Client) GetObjectFromURL

func (c *Client) GetObjectFromURL(ctx context.Context, signedURL string) ([]byte, error)

GetObjectFromURL retrieves an object using a pre-signed URL. It returns the object data and an error if any.

func (*Client) GetObjectToStruct

func (c *Client) GetObjectToStruct(ctx context.Context, bucket, key string, dataStruct any) (bool, error)

GetObjectToStruct retrieves the object data and unmarshals it into the provided struct. It returns a boolean indicating if the object was found and an error if any.

func (*Client) GetObjectWithContext

func (c *Client) GetObjectWithContext(ctx context.Context, bucket, key string) ([]byte, bool, error)

GetObjectWithContext retrieves the object data with a provided context. It returns the data, a boolean indicating if the object was found, and an error if any.

func (*Client) GetSignedObjectURL

func (c *Client) GetSignedObjectURL(ctx context.Context, bucket, key string) (string, error)

GetSignedObjectURL generates a pre-signed URL for accessing an object. It uses the default duration limit of 30 minutes.

func (*Client) GetSignedObjectURLWithDuration

func (c *Client) GetSignedObjectURLWithDuration(ctx context.Context, bucket, key string, duration time.Duration) (string, error)

GetSignedObjectURLWithDuration generates a pre-signed URL with a specified duration.

func (*Client) GetSignedPutUploadURL

func (c *Client) GetSignedPutUploadURL(ctx context.Context, bucket, key string, metadata map[string]*string) (string, error)

GetSignedPutUploadURL generates a pre-signed URL for uploading an object with optional metadata. It uses the default duration limit of 30 minutes.

func (*Client) GetSignedPutUploadURLWithDuration

func (c *Client) GetSignedPutUploadURLWithDuration(ctx context.Context, bucket, key string, metadata map[string]*string, duration time.Duration) (string, error)

GetSignedPutUploadURLWithDuration generates a pre-signed URL for uploading with a specified duration.

func (*Client) HasObject

func (c *Client) HasObject(bucket, key string) (bool, error)

HasObject checks if an object exists in the specified bucket and key.

func (*Client) ListBuckets

func (c *Client) ListBuckets(ctx context.Context) ([]string, error)

ListBuckets retrieves all S3 buckets accessible by the client.

func (*Client) ListObjects

func (c *Client) ListObjects(ctx context.Context, bucket, prefix, cursor string, limit int) ([]*ObjectInfo, string, error)

ListObjects retrieves objects from an S3 bucket with optional prefix and pagination. It returns a slice of ObjectInfo, the next continuation token, and an error if any.

func (*Client) ListPageObjects

func (c *Client) ListPageObjects(ctx context.Context, bucket, prefix, cursor string, count int64) ([]*ObjectInfo, string, error)

ListPageObjects retrieves a single page of objects from an S3 bucket with optional prefix. It returns a slice of ObjectInfo, the next continuation token, and an error if any.

func (*Client) PutObject

func (c *Client) PutObject(ctx context.Context, bucket, key string, body io.Reader, metadata map[string]*string) error

PutObject uploads an object to the specified bucket and key with optional metadata.

func (*Client) ReadObject

func (c *Client) ReadObject(ctx context.Context, bucket, key string, wa io.WriterAt) (bool, error)

ReadObject downloads an object and writes its content to the provided io.WriterAt. It returns a boolean indicating if the object was found and an error if any.

func (*Client) Region

func (c *Client) Region() string

Region returns the AWS region of the client.

func (*Client) RenameObject

func (c *Client) RenameObject(bucket, oldKey, newKey string) (bool, error)

RenameObject renames an object by copying it to a new key and deleting the old one. It returns a boolean indicating if the operation was successful and an error if any.

func (*Client) SaveObjectData

func (c *Client) SaveObjectData(ctx context.Context, bucket, key string, data []byte) error

SaveObjectData uploads raw byte data to the specified bucket and key.

func (*Client) SaveObjectFile

func (c *Client) SaveObjectFile(ctx context.Context, bucket, key, filePath string) error

SaveObjectFile uploads a file from the local filesystem to the specified bucket and key.

func (*Client) SaveObjectFileWithMetadata

func (c *Client) SaveObjectFileWithMetadata(ctx context.Context, bucket, key, filePath string, metadata map[string]string) error

SaveObjectFileWithMetadata uploads a file with additional metadata.

func (*Client) SaveObjectStream

func (c *Client) SaveObjectStream(ctx context.Context, bucket, key string, r io.Reader) error

SaveObjectStream uploads data from an io.Reader to the specified bucket and key.

func (*Client) StreamObject

func (c *Client) StreamObject(bucket, key string, w io.Writer) (bool, error)

StreamObject streams an S3 object directly to an io.Writer. It returns a boolean indicating if the object was found and an error if any.

func (*Client) UploadObjectToURL

func (c *Client) UploadObjectToURL(ctx context.Context, signedURL string, objectData []byte) error

UploadObjectToURL uploads data to an S3 object using a pre-signed URL. It returns an error if the upload fails.

type ObjectInfo

type ObjectInfo struct {
	Key        string    `json:"key"`
	Size       int64     `json:"size"`
	UpdateTime time.Time `json:"updateTime"`
}

ObjectInfo contains metadata about an S3 object.

type SyncWriterAt

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

SyncWriterAt wraps an io.Writer to implement io.WriterAt interface.

func (SyncWriterAt) WriteAt

func (a SyncWriterAt) WriteAt(p []byte, offset int64) (n int, err error)

WriteAt writes len(p) bytes from p to the underlying data stream at offset. It returns the number of bytes written and any error encountered that caused the write to stop early.