s3

README

Documentation

Index

• Constants
• Variables
• func BucketKey(address *url.URL) (bucket, key string)
• func EndpointRegionBucketKey(address *url.URL) (endpoint, region, bucket, key string)
• func NewPresignedGet(options ...Option) (string, error)
• func NewRequest(method string, options ...Option) (*http.Request, error)
• func Nop(_ *inputModel)
• func TrimKey(key string) string
• type Option
  • func AmbientCredentials() Option
  • func Bucket(value string) Option
  • func CompositeOption(options ...Option) Option
  • func ConditionalOption(option Option, condition bool) Option
  • func Content(value io.ReadSeeker) Option
  • func ContentBytes(value []byte) Option
  • func ContentEncoding(value string) Option
  • func ContentLength(value int64) Option
  • func ContentMD5(value string) Option
  • func ContentString(value string) Option
  • func ContentType(value string) Option
  • func Credentials(access, secret string) Option
  • func Endpoint(value string) Option
  • func EnvironmentCredentials() Option
  • func ExpireTime(value time.Time) Option
  • func ExpiresIn(value time.Duration) Option
  • func IAMRoleCredentials() Option
  • func IfNoneMatch(etag string) Option
  • func Key(value string) Option
  • func Region(value string) Option
  • func STSCredentials(access, secret, token string, expiration time.Time) Option
  • func ServerSideEncryption(value ServerSideEncryptionValue) Option
  • func StorageAddress(value *url.URL) Option
  • func Timestamp(value time.Time) Option
• type ServerSideEncryptionValue

Constants

const (
	HEAD = "HEAD"
	GET  = "GET"
	PUT  = "PUT"
)

Variables

var (
	ErrInvalidRequestMethod = errors.New("invalid method")
	ErrBucketMissing        = errors.New("bucket is required")
	ErrKeyMissing           = errors.New("key is required")
	ErrContentMissing       = errors.New("content is required")
)

Functions

func BucketKey

func BucketKey(address *url.URL) (bucket, key string)

BucketKey returns the S3 bucket and key embedded in an S3 URL. For details on how s3 urls are formed, please see the S3 docs: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html

func EndpointRegionBucketKey

func EndpointRegionBucketKey(address *url.URL) (endpoint, region, bucket, key string)

EndpointRegionBucketKey returns the S3 endpoint, region, bucket, and key embedded in a URL. For details on how S3 urls are formed, please see the S3 docs: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html

S3 URL examples showing optional placement of bucket and region (whitespace added for alignment):

virtual-style bucket, no region: http://bucket.s3 .amazonaws.com virtual-style bucket, with region: http://bucket.s3-aws-region.amazonaws.com path-style bucket, no region: http:// s3 .amazonaws.com/bucket path-style bucket, with region: http:// s3-aws-region.amazonaws.com/bucket path-style bucket, custom endpoint: http:// 42.43.44.45/bucket

func NewPresignedGet

func NewPresignedGet(options ...Option) (string, error)

func NewRequest

func NewRequest(method string, options ...Option) (*http.Request, error)

func Nop

func Nop(_ *inputModel)

Nop is a no-op. Useful as a placeholder in certain situations.

func TrimKey

func TrimKey(key string) string

TrimKey removes leading and trailing slashes from the value. Generally, S3 keys don't have leading and trailing slashes so this serves as a convenient sanitization function.

Types

type Option

type Option func(in *inputModel)

Option defines a callback for configuring the service and subsequent requests. It's important that this remain an exported name so that users can create slices of custom/conditional options.

func AmbientCredentials

func AmbientCredentials() Option

AmbientCredentials loads credentials first from the environment, then from any configured IAM role (on EC2).

func Bucket

func Bucket(value string) Option

Bucket allows the user to specify the bucket for sending requests.

func CompositeOption

func CompositeOption(options ...Option) Option

CompositeOption allows multiple options to appear as one. This is handy when some options are unchanging (like credentials or a bucket name). Bundle them together in a single option to leave more room for the dynamic options.

func ConditionalOption

func ConditionalOption(option Option, condition bool) Option

ConditionalOption returns the option if condition == true, otherwise returns nil (nop).

func Content

func Content(value io.ReadSeeker) Option

Content specifies the PUT request payload from an io.ReadSeeker.

func ContentBytes

func ContentBytes(value []byte) Option

ContentBytes specifies the PUT request payload from a slice of bytes.

func ContentEncoding

func ContentEncoding(value string) Option

ContentEncoding specifies the content encoding of the payload/blob. This option only applies to SignedPutRequest.

func ContentLength

func ContentLength(value int64) Option

ContentLength specifies the Content Length in bytes of the payload/blob. This option only applies to SignedPutRequest.

func ContentMD5

func ContentMD5(value string) Option

ContentMD5 specifies the MD5 checksum of the payload/blob. This option only applies to SignedPutRequest.

func ContentString

func ContentString(value string) Option

ContentString specifies the PUT request payload from a string.

func ContentType

func ContentType(value string) Option

ContentType specifies the Content Type of the payload/blob. This option only applies to SignedPutRequest.

func Credentials

func Credentials(access, secret string) Option

Credentials allows the user to specify hard-coded credential values for sending requests.

func Endpoint

func Endpoint(value string) Option

Endpoint allows the user to specify an alternate s3-compatible endpoint/URL to use for signed requests.

func EnvironmentCredentials

func EnvironmentCredentials() Option

EnvironmentCredentials loads credentials from common variations of environment variables.

func ExpireTime

func ExpireTime(value time.Time) Option

ExpireTime specifies an expiration for the generated input.

func ExpiresIn

func ExpiresIn(value time.Duration) Option

ExpiresIn specifies a validity period for PresignedGet (only).

func IAMRoleCredentials

func IAMRoleCredentials() Option

IAMRoleCredentials loads credentials from the EC2 instance's configured IAM role. Only applicable when running on EC2.

func IfNoneMatch

func IfNoneMatch(etag string) Option

IfNoneMatch specifies the "If-None-Match" header. See the docs for details: https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGET.html#RESTObjectGET-requests-in-headers This option only applies to GET requests.

func Key

func Key(value string) Option

Key allows the user to specify the key for sending requests.

func Region

func Region(value string) Option

Region allows the user to specify the region for sending requests.

func STSCredentials

func STSCredentials(access, secret, token string, expiration time.Time) Option

STSCredentials allows the user to specify hard-coded credential values from AWS STS for sending requests.

func ServerSideEncryption

func ServerSideEncryption(value ServerSideEncryptionValue) Option

ServerSideEncryption specifies the server-side encryption algorithm to use. This option only applies to SignedPutRequest.

func StorageAddress

func StorageAddress(value *url.URL) Option

StorageAddress allows the user to specify the region, bucket, and/or key for sending requests from the provided S3 URL.

func Timestamp

func Timestamp(value time.Time) Option

Timestamp specifies the timestamp to be included as the X-Amz-Date as well as for use in time based calculations. Helpful for testing.

type ServerSideEncryptionValue

type ServerSideEncryptionValue string

const (
	ServerSideEncryptionAES256 ServerSideEncryptionValue = "AES256"
	ServerSideEncryptionAWSKMS ServerSideEncryptionValue = "aws:kms"
)