s3

README

Simple S3 API for Go. Docs here.

S3 Config

The configuration contains you credentials and bucket info.

s3c := &s3.S3{
  Bucket:    os.Getenv("S3_BUCKET"),
  AccessKey: os.Getenv("S3_KEY"),
  Secret:    os.Getenv("S3_SECRET"),
  Path:      os.Getenv("S3_PATH"),
}

Object

Object(path) returns a new S3 object handle bound to the configuration it was created from.

obj := s3c.Object("path/to/hello.txt")

Upload

Writing to the WriteAbortCloser returned by Writer() allows you to upload objects.

w := obj.Writer()
io.Copy(w, bytes.NewBufferString("hello world!"))
w.Close()

// NOTE: You can abort uploads with w.Abort()

Download

Reading from the ReadCloser returned by Reader() allows you to download objects.

r, headers, err := obj.Reader()
b, err := ioutil.ReadAll(r)

Existence

Check if an object exists.

exists, err := obj.Exists()

Delete

Delete the object.

err := obj.Delete()

Generate Signed Form Upload URLs

o := s3c.Object("hello.txt")

p := make(s3.Policy)
p.SetExpiration(3600)
p.Conditions().Bucket(s3c.Bucket)
p.Conditions().ACL(s3.PublicRead)
p.Conditions().StartsWith("$key", "hello.txt")

url, err := o.FormURL(s3.PublicRead, p)

Generate Pre-Signed Expiring URLs

url, err := o.ExpiringURL(time.Second*60)

Documentation

Index

• Constants
• type ACL
• type Header
  • func (h Header) ContentLength() (int64, error)
  • func (h Header) ContentType() string
  • func (h Header) Date() (time.Time, error)
  • func (h Header) ETag() string
  • func (h Header) LastModified() (time.Time, error)
• type Object
• type Policy
  • func (p Policy) Conditions() *PolicyConditions
  • func (p Policy) SetExpiration(seconds uint)
• type PolicyConditions
  • func (c *PolicyConditions) ACL(acl ACL)
  • func (c *PolicyConditions) Bucket(bucket string)
  • func (c *PolicyConditions) ContentLengthRange(from, to int)
  • func (c *PolicyConditions) Equals(cond, match string)
  • func (c *PolicyConditions) Redirect(url string)
  • func (c *PolicyConditions) StartsWith(cond, match string)
  • func (c *PolicyConditions) SuccessActionRedirect(url string)
• type S3
  • func (s3 *S3) Object(key string) Object
• type Writer

Constants

const (
	MaxObjectSize = 5 * 1024 * 1024 * 1024 * 1024
	MinPartSize   = 5 * 1024 * 1024
	MaxPartSize   = 1<<31 - 1
	MaxNumParts   = 10000
)

Types

type ACL

type ACL string

const (
	Private           ACL = "private"
	PublicRead        ACL = "public-read"
	PublicReadWrite   ACL = "public-read-write"
	AuthenticatedRead ACL = "authenticated-read"
	BucketOwnerRead   ACL = "bucket-owner-read"
	BucketOwnerFull   ACL = "bucket-owner-full-control"
)

type Header

type Header http.Header

func (Header) ContentLength

func (h Header) ContentLength() (int64, error)

func (Header) ContentType

func (h Header) ContentType() string

func (Header) Date

func (h Header) Date() (time.Time, error)

func (Header) ETag

func (h Header) ETag() string

func (Header) LastModified

func (h Header) LastModified() (time.Time, error)

type Object

type Object interface {
	// Key returns the object key. If a path was specified in the S3 configuration
	// it will be prepended to the key.
	Key() string

	// S3 returns the configuration this object is bound to.
	S3() S3

	// Writer returns a new upload io.Writer
	Writer() Writer

	// Reader returns a new ReadCloser to read the file
	Reader() (io.ReadCloser, http.Header, error)

	// Exists checks if an object with the specified key already exists
	Exists() (bool, error)

	// Delete deletes an object
	Delete() error

	// Head does a HEAD request and returns the header
	Head() (Header, error)

	// ExpiringURL returns a signed, expiring URL for the object
	ExpiringURL(expiresIn time.Duration) (*url.URL, error)

	// FormURL returns a signed URL for multipart form uploads
	FormURL(acl ACL, policy Policy, query ...url.Values) (*url.URL, error)
}

type Policy

type Policy policyMap

func (Policy) Conditions

func (p Policy) Conditions() *PolicyConditions

func (Policy) SetExpiration

func (p Policy) SetExpiration(seconds uint)

type PolicyConditions

type PolicyConditions []interface{}

func (*PolicyConditions) ACL

func (c *PolicyConditions) ACL(acl ACL)

func (*PolicyConditions) Bucket

func (c *PolicyConditions) Bucket(bucket string)

func (*PolicyConditions) ContentLengthRange

func (c *PolicyConditions) ContentLengthRange(from, to int)

func (*PolicyConditions) Equals

func (c *PolicyConditions) Equals(cond, match string)

func (*PolicyConditions) Redirect

func (c *PolicyConditions) Redirect(url string)

func (*PolicyConditions) StartsWith

func (c *PolicyConditions) StartsWith(cond, match string)

func (*PolicyConditions) SuccessActionRedirect

func (c *PolicyConditions) SuccessActionRedirect(url string)

type S3

type S3 struct {
	// Bucket is the S3 bucket to use
	Bucket string

	// AccessKey is the S3 access key
	AccessKey string

	// Secret is the S3 secret
	Secret string

	// Path is the path to prepend to all keys
	Path string
}

S3 holds the S3 configuration

func (*S3) Object

func (s3 *S3) Object(key string) Object

type Writer

type Writer interface {
	io.WriteCloser

	// Abort aborts the current write/upload operation
	Abort() error
}