s3

Documentation

Overview

Package s3 implements a generic Amazon S3 client, not specific to Perkeep.

Index

• func IsValidBucket(bucket string) bool
• type Auth
  • func (a *Auth) SignRequest(req *http.Request)
• type Bucket
• type Client
  • func (c *Client) BucketLocation(ctx context.Context, bucket string) (location string, err error)
  • func (c *Client) Buckets(ctx context.Context) ([]*Bucket, error)
  • func (c *Client) Delete(ctx context.Context, bucket, key string) error
  • func (c *Client) Get(ctx context.Context, bucket, key string) (body io.ReadCloser, size int64, err error)
  • func (c *Client) GetPartial(ctx context.Context, bucket, key string, offset, length int64) (rc io.ReadCloser, err error)
  • func (c *Client) ListBucket(ctx context.Context, bucket string, startAt string, maxKeys int) (items []*Item, err error)
  • func (c *Client) PutObject(ctx context.Context, key, bucket string, md5 hash.Hash, size int64, ...) error
  • func (c *Client) Stat(ctx context.Context, key, bucket string) (size int64, reterr error)
• type Error
  • func (e *Error) Error() string
• type Item

Functions

func IsValidBucket

func IsValidBucket(bucket string) bool

IsValidBucket reports whether bucket is a valid bucket name, per Amazon's naming restrictions.

See http://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html

Types

type Auth

type Auth struct {
	AccessKey       string
	SecretAccessKey string

	// Hostname is the S3 hostname to use.
	// If empty, the standard US region of "s3.amazonaws.com" is
	// used.
	Hostname string
}

func (*Auth) SignRequest

func (a *Auth) SignRequest(req *http.Request)

type Bucket

type Bucket struct {
	Name         string
	CreationDate string // 2006-02-03T16:45:09.000Z
}

type Client

type Client struct {
	*Auth
	Transport http.RoundTripper // or nil for the default
	// PutGate limits the number of concurrent PutObject calls, because
	// apparently S3 throttles us if there are too many. No limit if nil.
	// Default in S3 blobserver is 5.
	PutGate *syncutil.Gate
	NoSSL   bool // disable SSL. For testing against fake-s3.
}

Client is an Amazon S3 client.

func (*Client) BucketLocation

func (c *Client) BucketLocation(ctx context.Context, bucket string) (location string, err error)

BucketLocation returns the S3 hostname to be used with the given bucket.

func (*Client) Buckets

func (c *Client) Buckets(ctx context.Context) ([]*Bucket, error)

func (*Client) Delete

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

func (*Client) Get

func (c *Client) Get(ctx context.Context, bucket, key string) (body io.ReadCloser, size int64, err error)

func (*Client) GetPartial

func (c *Client) GetPartial(ctx context.Context, bucket, key string, offset, length int64) (rc io.ReadCloser, err error)

GetPartial fetches part of the s3 key object in bucket. If length is negative, the rest of the object is returned. The caller must close rc.

func (*Client) ListBucket

func (c *Client) ListBucket(ctx context.Context, bucket string, startAt string, maxKeys int) (items []*Item, err error)

ListBucket returns 0 to maxKeys (inclusive) items from the provided bucket. Keys before startAt will be skipped. (This is the S3 'marker' value). If the length of the returned items is equal to maxKeys, there is no indication whether or not the returned list is truncated.

func (*Client) PutObject

func (c *Client) PutObject(ctx context.Context, key, bucket string, md5 hash.Hash, size int64, body io.Reader) error

func (*Client) Stat

func (c *Client) Stat(ctx context.Context, key, bucket string) (size int64, reterr error)

Stat returns 0, os.ErrNotExist if not on S3, otherwise reterr is real.

type Error

type Error struct {
	Op     string
	Code   int         // HTTP status code
	Body   []byte      // response body
	Header http.Header // response headers

	// UsedEndpoint and AmazonCode are the XML response's Endpoint and
	// Code fields, respectively.
	UseEndpoint string // if a temporary redirect (wrong hostname)
	AmazonCode  string
}

Error is the type returned by some API operations.

TODO: it should be more/all of them.

func (*Error) Error

func (e *Error) Error() string

type Item

type Item struct {
	Key  string
	Size int64
}