s3gopher

README

s3gopher

s3gopher is a light-weight S3 library using Go. It's built on top of Amazon's offical AWS SDK.

Why

Found the official SDK to require a lot of boilerplate if you just want to read / write a single or few files from a S3 bucket or list its content.

Caveats

• See AWS documentation for Region and ACL values.
• Listing is done in memory and not well suited for buckets with thousands or millions of files.

Example usage

import "github.com/datajet-io/s3gopher"

func main() {

config := s3gopher.Config{
		Bucket: "bucketname",
		ACL: "public-read",
		Region: "us-east-1",
		Credentials: s3gopher.Credentials{AccessKey: "yourAccessKey", SecretAccessKey:"yourSecretAccessKey"},
}

bucket, err := s3gopher.New(config)

// Are my credentials valid?

err := bucket.Test()

if err != nil {
	fmt.Printeln("Something bad happended when testing credentials.")
	return
}

// List content of the bucket, show latest additions first

fileList, err := o.List()

// Get the first file from the bucket

o, err := bucket.Get(fileList[0].Key)

if err != nil {
	fmt.Println("Something bad happended reading the data.")
	return
}

// When was the file last modified?

fmt.Println(o.LastModified)

// Output its []byte content

fmt.Println(o.Data)

/*

Do something with the file's data
	
*/

// Write the file back to S3


err := bucket.Put(o)

if err != nil {
	fmt.Println("Something bad happended when writing the data.")
	return
}

// We're done

}

To Do

• Delete

Documentation

Index

• type Bucket
  • func New(c Config) (*Bucket, error)
  • func (s *Bucket) Get(key string) (o *Object, err error)
  • func (s *Bucket) List() (obj []Object, err error)
  • func (s *Bucket) Put(o *Object) error
  • func (s *Bucket) Test() error
• type ByLastModified
  • func (a ByLastModified) Len() int
  • func (a ByLastModified) Less(i, j int) bool
  • func (a ByLastModified) Swap(i, j int)
• type Config
• type Credentials
• type Object
  • func (p Object) String() string

Types

type Bucket

type Bucket struct {
	Client *s3.S3
	Bucket string
	ACL    string
	Creds  Credentials
}

Bucket handler for a S3 bucket

func New

func New(c Config) (*Bucket, error)

New creates a new connection to a S3 bucket using the provided credentials. regions: eu-west-1, us-east-1, us-west-1 ACL private, public-read

func (*Bucket) Get

func (s *Bucket) Get(key string) (o *Object, err error)

Get data of an S3 object

func (*Bucket) List

func (s *Bucket) List() (obj []Object, err error)

List all objects in a bucket

func (*Bucket) Put

func (s *Bucket) Put(o *Object) error

Put stores an object into an S3 bucket

func (*Bucket) Test

func (s *Bucket) Test() error

Test tests the connection to the bucket using the provided credentials

type ByLastModified

type ByLastModified []Object

ByLastModified implements sort.Interface for []Object based on the LastModified field. Sort is descending by time

func (ByLastModified) Len

func (a ByLastModified) Len() int

func (ByLastModified) Less

func (a ByLastModified) Less(i, j int) bool

func (ByLastModified) Swap

func (a ByLastModified) Swap(i, j int)

type Config

type Config struct {
	Bucket      string
	ACL         string
	Region      string
	Credentials Credentials
}

Config for bucket

type Credentials

type Credentials struct {
	AccessKey       string
	SecretAccessKey string
}

Credentials represents a pair of AWS credentials

type Object

type Object struct {
	Key          string
	LastModified time.Time
	Data         []byte
}

Object in a S3 bucket

func (Object) String

func (p Object) String() string