s3

README

s3-client

This client is a wrapper around minio-go.

Installation

go get github.com/Clarilab/s3-client/v3

Importing

import "github.com/Clarilab/s3-client/v3"

Features

// Client holds all callable methods.
type Client interface {
	// AddLifeCycleRule adds a lifecycle rule to the given folder.
	AddLifeCycleRule(ctx context.Context, ruleID, folderPath string, daysToExpiry int) error

	// UploadFile uploads data under a given s3 path.
	UploadFile(ctx context.Context, path, contentType string, data io.Reader, objectSize *int64) error

	// UploadJSONFileWithLink uploads a file with content type "application/json" to the given s3 path.
	UploadJSONFileWithLink(ctx context.Context, path string, data io.Reader, linkExpiration time.Duration) (*url.URL, error)

	// GetFileURL creates a link with expiration for a document under the given path.
	GetFileURL(ctx context.Context, path string, expiration time.Duration) (*url.URL, error)

	// GetDocumentsInPath returns a list of names of all files under the given path.
	// The recursive option also lists all files from sub folders.
	GetDocumentsInPath(ctx context.Context, path string, recursive bool) ([]string, error)

	// DownloadFile returns the Document from given s3 path.
	DownloadFile(ctx context.Context, path string) (*Document, error)

	// DownloadDirectory returns a list of Documents from given s3 folder.
	DownloadDirectory(ctx context.Context, path string) ([]*Document, error)

	// DownloadFileToPath downloads the requested file to the file system under given localPath.
	DownloadFileToPath(ctx context.Context, path, localPath string) error

	// DownloadDirectoryToPath downloads the requested folder to the file system.
	// The recursive option also downloads all sub folders.
	DownloadDirectoryToPath(ctx context.Context, path, localPath string, recursive bool) error

	// RemoveFile deletes the file under given s3 path.
	RemoveFile(ctx context.Context, path string) error
}

TODO

• add examples to documentation

Documentation

Index

• Variables
• type BucketDoesNotExistError
  • func (e *BucketDoesNotExistError) Error() string
• type Client
  • func NewClient(ctx context.Context, s3URL, accessKey, accessSecret, bucketName string, ...) (Client, error)
• type DownloadingFilesFailedError
  • func (e *DownloadingFilesFailedError) Error() string
• type File
• type GetOption
  • func WithGetOptionClientGetOptions(options minio.GetObjectOptions) GetOption
  • func WithGetOptionDownloadContent(downloadContent bool) GetOption
• type Option
  • func WithHealthCheck(interval time.Duration) Option

Variables

var ErrNotFound = errors.New("file under specified filepath does not exist")

ErrNotFound indicates that the requested file does not exist.

Types

type BucketDoesNotExistError

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

BucketDoesNotExistError occurs when the given bucket does not exist.

func (*BucketDoesNotExistError) Error

func (e *BucketDoesNotExistError) Error() string

Error implements the error interface.

type Client

type Client interface {
	// Close closes the s3 client.
	Close()

	// IsOnline reports true if the client is online. If the health-check has not been enabled this will always return true.
	IsOnline() bool

	// AddLifeCycleRule adds a lifecycle rule to the given folder.
	AddLifeCycleRule(ctx context.Context, ruleID, folderPath string, daysToExpiry int) error

	// UploadFile uploads data under a given s3 path.
	UploadFile(ctx context.Context, path, contentType string, data io.Reader, objectSize *int64) (*minio.UploadInfo, error)

	// UploadFileWithOptions uploads data under a given s3 path with options.
	UploadFileWithOptions(ctx context.Context, path string, data io.Reader, objectSize *int64, options minio.PutObjectOptions) (*minio.UploadInfo, error)

	// GetFileURL creates a link with expiration for a file under the given path.
	GetFileURL(ctx context.Context, path string, expiration time.Duration) (*url.URL, error)

	// GetFileNamesInPath returns a list of names of all files under the given path.
	// The recursive option also lists all files from sub folders.
	GetFileNamesInPath(ctx context.Context, path string, recursive bool) ([]string, error)

	// GetFile returns the file from given s3 path.
	GetFile(ctx context.Context, path string) (*File, error)

	// GetFileWithOptions returns the file from given s3 path with options
	GetFileWithOptions(ctx context.Context, path string, options ...GetOption) (*File, error)

	// GetDirectory returns a list of files from given s3 folder.
	GetDirectory(ctx context.Context, path string) ([]*File, error)

	// GetDirectoryWithOptions returns a list of files from given s3 folder with options.
	GetDirectoryWithOptions(ctx context.Context, path string, options ...GetOption) ([]*File, error)

	// DownloadFile downloads the requested file to the file system under given localPath.
	DownloadFile(ctx context.Context, path, localPath string) error

	// DownloadFileWithOptions downloads the requested file to the file system under given localPath with minio options.
	DownloadFileWithOptions(ctx context.Context, path, localPath string, options minio.GetObjectOptions) error

	// DownloadDirectory downloads the requested folder to the file system.
	// The recursive option also downloads all sub folders.
	DownloadDirectory(ctx context.Context, path, localPath string, recursive bool) error

	// DownloadDirectoryWithOptions downloads the requested folder to the file system with options.
	// The recursive option also downloads all sub folders.
	DownloadDirectoryWithOptions(ctx context.Context, path, localPath string, recursive bool, options minio.GetObjectOptions) error

	// RemoveFile deletes the file under given s3 path.
	RemoveFile(ctx context.Context, path string) error

	// RemoveFileWithOptions deletes the file under given s3 path with minio options.
	RemoveFileWithOptions(ctx context.Context, path string, options minio.RemoveObjectOptions) error

	// GetObject returns an minio.Object for the given s3 path.
	// Don't forget to close the Object.
	GetObject(ctx context.Context, path string) (*minio.Object, error)

	// GetObjectInfo returns an minio.ObjectInfo for the given s3 path.
	GetObjectInfo(ctx context.Context, path string) (*minio.ObjectInfo, error)

	// GetObjectWithOptions returns an minio.Object for the given s3 path with minio options.
	// Don't forget to close the Object.
	GetObjectWithOptions(ctx context.Context, path string, options ...GetOption) (*minio.Object, error)
}

Client holds all callable methods.

func NewClient

func NewClient(ctx context.Context, s3URL, accessKey, accessSecret, bucketName string, secure bool, options ...Option) (Client, error)

NewClient instantiates a s3.

type DownloadingFilesFailedError

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

DownloadingFilesFailedError occurs when downloading files from s3 failed.

func (*DownloadingFilesFailedError) Error

func (e *DownloadingFilesFailedError) Error() string

DownloadingFilesFailedError implements the error interface.

type File

type File struct {
	Content      []byte            `json:"content,omitempty"`
	Length       int64             `json:"length,omitempty"`
	ModifiedDate time.Time         `json:"modifiedDate,omitempty"`
	ContentType  string            `json:"contentType,omitempty"`
	Name         string            `json:"name,omitempty"`
	MetaData     map[string]string `json:"metadata,omitempty"`
	Checksum     string            `json:"checksum,omitempty"` // empty if not requested via options
}

File holds the file content and some meta data.

type GetOption

type GetOption func(*getOption)

GetOption is an option for getting a file.

func WithGetOptionClientGetOptions

func WithGetOptionClientGetOptions(options minio.GetObjectOptions) GetOption

WithGetOptionClientGetOptions sets client options for the get request.

func WithGetOptionDownloadContent

func WithGetOptionDownloadContent(downloadContent bool) GetOption

WithGetOptionDownloadContent enables or disables downloading the content of the file.

Default is enabled.

When disabled, the Content field of the returned File struct will be nil.

type Option

type Option func(*client) error

Option is an option for the s3 client.

func WithHealthCheck

func WithHealthCheck(interval time.Duration) Option

WithHealthCheck enables the health check for the s3 client.