maleos3

Documentation

Index

• func NewS3Bucket(endpoint string, opts ...Option) (bucket.Bucket, error)
• func SimpleStaticClient(params SimpleStaticParams, opts ...func(options *config.LoadOptions) error) (*s3.Client, error)
• type Object
  • func NewObject(proto, endpoint, region, bucket, key string) Object
• type Option
  • func WithBucket(name string) Option
  • func WithClient(client *s3.Client) Option
  • func WithFilenameDynamicPretext(pretext func() string) Option
  • func WithFilenamePretext(pretext string) Option
  • func WithRegion(region string) Option
  • func WithSecure(secure bool) Option
  • func WithURLBuilder(builder URLBuilder) Option
• type OptionFunc
• type S3
  • func (s *S3) Upload(ctx context.Context, files []bucket.File) []bucket.UploadResult
• type SimpleStaticParams
• type StringerFunc
  • func (f StringerFunc) String() string
• type URLBuilder
• type URLBuilderFunc
  • func (f URLBuilderFunc) BuildURL(obj Object) string

Examples

• NewS3Bucket
• NewS3Bucket (Custom)
• NewS3Bucket (NonAws)
• NewS3Bucket (Static)

Functions

func NewS3Bucket

func NewS3Bucket(endpoint string, opts ...Option) (bucket.Bucket, error)

NewS3Bucket creates new S3 bucket. endpoint is basically the host of the bucket. e.g. mybucket.s3.amazonaws.com or localhost:9000. Do not include the protocol (http/https) in the endpoint. If the endpoint is empty, it will default to "s3.amazonaws.com".

The default options assumes the machine that is running contains AWS credentials.

If you wish to use a different or customized client or a client with custom logic, use WithClient option.

If your endpoint is like this:

<bucket>.s3.<region>.amazonaws.com

the bucket and region will be detected automatically.

If your endpoint is like this:

s3.<region>.amazonaws.com

the region will be detected automatically, but you must provide the bucket name via WithBucket option.

Non AWS endpoint will be treated as a custom endpoint, and will be treated as immutable hostname by the SDK. Also, you must provide the region via WithRegion option and the bucket name via WithBucket option.

You may also want to modify how the URL is built when using custom endpoints, use WithURLBuilder option to change those.

Example

bkt, err := maleos3.NewS3Bucket("my-bucket.s3.us-east-1.amazonaws.com")
if err != nil {
	return
}
f := strings.NewReader("hello world")
file := bucket.NewFile(f, "text/plain; charset=utf-8")
for _, result := range bkt.Upload(context.Background(), []bucket.File{file}) {
	if result.Error != nil {
		// handle error
		return
	}
}

Example (Custom)

client := s3.NewFromConfig(aws.Config{
	// set your custom config here
})
bkt, err := maleos3.NewS3Bucket("bucket.s3.us-east-1.amazonaws.com", maleos3.WithClient(client))
if err != nil {
	return
}
f := strings.NewReader("hello world")
file := bucket.NewFile(f, "text/plain; charset=utf-8")
for _, result := range bkt.Upload(context.Background(), []bucket.File{file}) {
	if result.Error != nil {
		// handle error
		return
	}
}

Example (NonAws)

client, err := maleos3.SimpleStaticClient(maleos3.SimpleStaticParams{
	AccessKeyID:     "access_key",
	SecretAccessKey: "secret_key",
	Endpoint:        "minio:9000",
	Region:          "us-east-1",
})
if err != nil {
	return
}
bkt, err := maleos3.NewS3Bucket("minio:9000", maleos3.WithClient(client))
if err != nil {
	return
}
f := strings.NewReader("hello world")
file := bucket.NewFile(f, "text/plain; charset=utf-8")
for _, result := range bkt.Upload(context.Background(), []bucket.File{file}) {
	if result.Error != nil {
		// handle error
		return
	}
}

Example (Static)

client, err := maleos3.SimpleStaticClient(maleos3.SimpleStaticParams{
	AccessKeyID:     "access_key",
	SecretAccessKey: "secret_key",
	SessionToken:    "", // Optional. Leave empty if not needed.

	// Endpoint is needed to be set for non-AWS S3, otherwise just leave empty.
	// It is needed as interoperability with other S3 compatible services.
	Endpoint: "",
	// Same reason as above
	Region: "",
	Secure: true, // Set false if you want to use HTTP instead of HTTPS.
})
if err != nil {
	return
}
bkt, err := maleos3.NewS3Bucket("my-bucket.s3.us-east-1.amazonaws.com", maleos3.WithClient(client))
if err != nil {
	return
}
f := strings.NewReader("hello world")
file := bucket.NewFile(f, "text/plain; charset=utf-8")
for _, result := range bkt.Upload(context.Background(), []bucket.File{file}) {
	if result.Error != nil {
		// handle error
		return
	}
}

func SimpleStaticClient

func SimpleStaticClient(params SimpleStaticParams, opts ...func(options *config.LoadOptions) error) (*s3.Client, error)

SimpleStaticClient creates a new S3 client from passed credentials.

Types

type Object

type Object struct {
	Endpoint string
	Bucket   string
	Key      string
	Region   string
	Proto    string
}

Object is a simple metadata of an object in S3.

func NewObject

func NewObject(proto, endpoint, region, bucket, key string) Object

NewObject is a constructor for Object.

type Option

type Option interface {
	// contains filtered or unexported methods
}

func WithBucket

func WithBucket(name string) Option

WithBucket sets the bucket name to use.

func WithClient

func WithClient(client *s3.Client) Option

WithClient sets the S3 client to use.

func WithFilenameDynamicPretext

func WithFilenameDynamicPretext(pretext func() string) Option

WithFilenameDynamicPretext sets the pretext to use for the filename to be uploaded to the bucket.

example of creating yearly folder in bucket:

WithFilenameDynamicPretext(func() string { return time.Now().Format("2006") + "/" })

func WithFilenamePretext

func WithFilenamePretext(pretext string) Option

WithFilenamePretext sets the pretext to use for the filename to be uploaded to the bucket.

func WithRegion

func WithRegion(region string) Option

WithRegion sets the region to use.

func WithSecure

func WithSecure(secure bool) Option

WithSecure sets to use https or not.

func WithURLBuilder

func WithURLBuilder(builder URLBuilder) Option

WithURLBuilder sets the url builder to use.

type OptionFunc

type OptionFunc func(*S3)

type S3

type S3 struct {
	*s3.Client
	// contains filtered or unexported fields
}

func (*S3) Upload

func (s *S3) Upload(ctx context.Context, files []bucket.File) []bucket.UploadResult

type SimpleStaticParams

type SimpleStaticParams struct {
	AccessKeyID     string
	SecretAccessKey string
	SessionToken    string
	Endpoint        string
	Region          string
	Secure          bool
}

type StringerFunc

type StringerFunc func() string

func (StringerFunc) String

func (f StringerFunc) String() string

type URLBuilder

type URLBuilder interface {
	BuildURL(obj Object) string
}

type URLBuilderFunc

type URLBuilderFunc func(obj Object) string

func (URLBuilderFunc) BuildURL

func (f URLBuilderFunc) BuildURL(obj Object) string