README
¶
simples3 : Simple no frills AWS S3 Library using REST with V4 Signing
Overview
![Zerodha Tech](https://zerodha.tech/static/images/github-badge.svg)
SimpleS3 is a golang library for uploading and deleting objects on S3 buckets using REST API calls or Presigned URLs signed using AWS Signature Version 4.
Install
go get github.com/JohnAnthony/simples3
Example
testTxt, _ := os.Open("testdata/test.txt")
defer testTxt.Close()
// Create an instance of the package
// You can either create by manually supplying credentials
// (preferably using Environment vars)
s3 := simples3.New(Region, AWSAccessKey, AWSSecretKey)
// or you can use this on an EC2 instance to
// obtain credentials from IAM attached to the instance.
s3, _ := simples3.NewUsingIAM(Region)
// You can also set a custom endpoint to a compatible s3 instance.
s3.SetEndpoint(CustomEndpoint)
// Note: Consider adding a testTxt.Seek(0, 0)
// in case you have read
// the body, as the pointer is shared by the library.
// File Upload is as simple as providing the following
// details.
resp, err := s3.FileUpload(textTxt, simples3.UploadInput{
Bucket: AWSBucket,
ObjectKey: "test.txt",
ContentType: "text/plain",
FileName: "test.txt",
})
// Similarly, Files can be deleted.
err := s3.FileDelete(simples3.DeleteInput{
Bucket: os.Getenv("AWS_S3_BUCKET"),
ObjectKey: "test.txt",
})
// You can also download the file.
file, _ := s3.FileDownload(simples3.DownloadInput{
Bucket: AWSBucket,
ObjectKey: "test.txt",
})
data, _ := ioutil.ReadAll(file)
file.Close()
// You can also use this library to generate
// Presigned URLs that can for eg. be used to
// GET/PUT files on S3 through the browser.
var time, _ = time.Parse(time.RFC1123, "Fri, 24 May 2013 00:00:00 GMT")
url := s.GeneratePresignedURL(PresignedInput{
Bucket: AWSBucket,
ObjectKey: "test.txt",
Method: "GET",
Timestamp: time,
ExpirySeconds: 86400,
})
Contributing
You are more than welcome to contribute to this project. Fork and make a Pull Request, or create an Issue if you see any problem or want to propose a feature.
Authors
John Anthony john@jo.hnanthony.com
Rohan Verma hello@rohanverma.net
License
BSD-2-Clause-FreeBSD
Documentation
¶
Index ¶
- type DeleteInput
- type DownloadInput
- type IAMResponse
- type PolicyJSON
- type PresignedInput
- type S3
- func (s3 *S3) CreateUploadPolicies(uploadConfig UploadConfig) (UploadPolicies, error)
- func (s3 *S3) FileDelete(u DeleteInput) error
- func (s3 *S3) FileDownload(u DownloadInput) (io.ReadCloser, error)
- func (s3 *S3) FileUpload(body io.ReadSeeker, u UploadInput) (UploadResponse, error)
- func (s3 *S3) FileUploadStream(body io.Reader, u UploadInput) (UploadResponse, error)
- func (s3 *S3) GeneratePresignedURL(in PresignedInput) string
- func (s3 *S3) SetClient(client *http.Client) *S3
- func (s3 *S3) SetEndpoint(uri string) *S3
- func (s3 *S3) SetToken(token string) *S3
- type UploadConfig
- type UploadInput
- type UploadPolicies
- type UploadResponse
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DeleteInput ¶
DeleteInput is passed to FileDelete as a parameter.
type DownloadInput ¶
DownloadInput is passed to FileUpload as a parameter.
type IAMResponse ¶
type IAMResponse struct { Code string `json:"Code"` LastUpdated string `json:"LastUpdated"` Type string `json:"Type"` AccessKeyID string `json:"AccessKeyId"` SecretAccessKey string `json:"SecretAccessKey"` Token string `json:"Token"` Expiration string `json:"Expiration"` }
IAMResponse is used by NewUsingIAM to auto detect the credentials
type PolicyJSON ¶
type PolicyJSON struct { Expiration string `json:"expiration"` Conditions []interface{} `json:"conditions"` }
PolicyJSON is policy rule
type PresignedInput ¶
type PresignedInput struct { Bucket string ObjectKey string Method string Timestamp time.Time ExtraHeaders map[string]string ExpirySeconds int Protocol string Endpoint string }
PresignedInput is passed to GeneratePresignedURL as a parameter.
type S3 ¶
type S3 struct { AccessKey string SecretKey string Region string Client *http.Client Token string Endpoint string URIFormat string }
S3 provides a wrapper around your S3 credentials.
func NewUsingIAM ¶
NewUsingIAM automatically generates an Instance of S3 using instance metatdata.
func (*S3) CreateUploadPolicies ¶
func (s3 *S3) CreateUploadPolicies(uploadConfig UploadConfig) (UploadPolicies, error)
CreateUploadPolicies creates amazon s3 sigv4 compatible policy and signing keys with the signature returns the upload policy. https://docs.aws.amazon.com/ja_jp/AmazonS3/latest/API/sigv4-authentication-HTTPPOST.html
func (*S3) FileDelete ¶
func (s3 *S3) FileDelete(u DeleteInput) error
FileDelete makes a DELETE call with the file written as multipart and on successful upload, checks for 204 No Content.
func (*S3) FileDownload ¶
func (s3 *S3) FileDownload(u DownloadInput) (io.ReadCloser, error)
FileDownload makes a GET call and returns a io.ReadCloser. After reading the response body, ensure closing the response.
func (*S3) FileUpload ¶
func (s3 *S3) FileUpload(body io.ReadSeeker, u UploadInput) (UploadResponse, error)
FileUpload makes a POST call with the file written as multipart and on successful upload, checks for 200 OK.
func (*S3) FileUploadStream ¶
func (s3 *S3) FileUploadStream(body io.Reader, u UploadInput) (UploadResponse, error)
FileUploadStream makes a POST call with the file written as multipart and on successful upload, checks for 200 OK. Differs from FileUpload in that a ReadSeeker isn't required, allowing an upload to use only a small in-memory buffer.
func (*S3) GeneratePresignedURL ¶
func (s3 *S3) GeneratePresignedURL(in PresignedInput) string
GeneratePresignedURL creates a Presigned URL that can be used for Authentication using Query Parameters. (https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html)
func (*S3) SetClient ¶
SetClient can be used to set the http client to be used by the package. If client passed is nil, http.DefaultClient is used.
func (*S3) SetEndpoint ¶
SetEndpoint can be used to the set a custom endpoint for using an alternate instance compatible with the s3 API. If no protocol is included in the URI, defaults to HTTPS.
type UploadConfig ¶
type UploadConfig struct { // Required BucketName string ObjectKey string ContentType string ContentDisposition string ACL string FileSize int64 // Optional UploadURL string Expiration time.Duration MetaData map[string]string }
UploadConfig generate policies from config for POST requests to S3 using Signing V4.
type UploadInput ¶
type UploadInput struct { // essential fields Bucket string ObjectKey string FileName string ContentType string // optional fields ContentDisposition string ACL string }
UploadInput is passed to FileUpload as a parameter.
type UploadPolicies ¶
UploadPolicies Amazon s3 upload policies
type UploadResponse ¶
type UploadResponse struct { Location string `xml:"Location"` Bucket string `xml:"Bucket"` Key string `xml:"Key"` ETag string `xml:"ETag"` }
UploadResponse receives the following XML in case of success, since we set a 201 response from S3. Sample response: <PostResponse>
<Location>https://s3.amazonaws.com/link-to-the-file</Location> <Bucket>s3-bucket</Bucket> <Key>development/8614bd40-691b-4668-9241-3b342c6cf429/image.jpg</Key> <ETag>"32-bit-tag"</ETag>
</PostResponse>