s3

README

awsutils/s3

The s3 package is a collection of utility functions designed to simplify common s3 tasks.

---

Table of contents

• Functions
• Installation
• Usage
• Tests
• Contributing
• License

---

Functions

CreateBucket(*s3.S3, string)

CreateBucket(*s3.S3, string) error

CreateBucket creates a bucket with the input bucketName.

Parameters:

client: An AWS S3 client. bucketName: The name of the bucket to create.

Returns:

error: An error if the bucket could not be created.

---

CreateConnection()

CreateConnection() Connection

CreateConnection creates a connection with S3 and returns it.

Returns:

An s3.Connection struct containing the AWS S3 client and AWS session.

---

DestroyBucket(*s3.S3, string)

DestroyBucket(*s3.S3, string) error

DestroyBucket destroys a bucket with the input bucketName.

Parameters:

client: An AWS S3 client. bucketName: The name of the bucket to destroy.

Returns:

error: An error if the bucket could not be destroyed.

---

DownloadBucketFile(*session.Session, string, string, string)

DownloadBucketFile(*session.Session, string, string, string) string, error

DownloadBucketFile downloads a file found at the object key specified with the input objectKey from the bucket specified by bucketName, and writes it to downloadFP.

Parameters:

sess: An AWS session. bucketName: The name of the bucket to download from. objectKey: The key of the object to download. downloadFP: The file path to write the downloaded file to.

Returns:

string: The name of the downloaded file. error: An error if the file could not be downloaded.

---

EmptyBucket(*s3.S3, string)

EmptyBucket(*s3.S3, string) error

EmptyBucket deletes everything found in the input bucketName.

Parameters:

client: An AWS S3 client. bucketName: The name of the bucket to empty.

Returns:

error: An error if the bucket could not be emptied.

---

GetBuckets(*s3.S3)

GetBuckets(*s3.S3) []*s3.Bucket, error

GetBuckets returns all s3 buckets that the input client has access to.

Parameters:

client: An AWS S3 client.

Returns:

[]*s3.Bucket: A slice of pointers to AWS S3 bucket structs that the client has access to. error: An error if the buckets could not be listed.

---

UploadBucketDir(*session.Session, string, string)

UploadBucketDir(*session.Session, string, string) error

UploadBucketDir uploads a directory specified by dirPath to the bucket specified by bucketName.

Parameters:

sess: An AWS session. bucketName: The name of the bucket to upload to. dirPath: The file path of the directory to upload.

Returns:

error: An error if the directory could not be uploaded.

---

UploadBucketFile(*session.Session, string, string)

UploadBucketFile(*session.Session, string, string) error

UploadBucketFile uploads a file found at the file path specified with (uploadFP) to the input bucketName.

Parameters:

sess: An AWS session. bucketName: The name of the bucket to upload to. uploadFP: The file path of the file to upload.

Returns:

error: An error if the file could not be uploaded.

---

Installation

To use the awsutils/s3 package, you first need to install it. Follow the steps below to install via go get.

go get github.com/l50/awsutils/s3

---

Usage

After installation, you can import the package in your Go project using the following import statement:

import "github.com/l50/awsutils/s3"

---

Tests

To ensure the package is working correctly, run the following command to execute the tests for awsutils/s3:

go test -v

---

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

• func CreateBucket(client *s3.S3, bucketName string) error
• func DestroyBucket(client *s3.S3, bucketName string) error
• func DownloadBucketFile(sess *session.Session, bucketName string, objectKey string, downloadFP string) (string, error)
• func EmptyBucket(client *s3.S3, bucketName string) error
• func GetBuckets(client *s3.S3) ([]*s3.Bucket, error)
• func UploadBucketDir(sess *session.Session, bucketName string, dirPath string) error
• func UploadBucketFile(sess *session.Session, bucketName string, uploadFP string) error
• type Connection
  • func CreateConnection() Connection
• type Params

Examples

• GetBuckets

Functions

func CreateBucket

func CreateBucket(client *s3.S3, bucketName string) error

CreateBucket creates a bucket with the input bucketName.

**Parameters:**

client: An AWS S3 client. bucketName: The name of the bucket to create.

**Returns:**

error: An error if the bucket could not be created.

func DestroyBucket

func DestroyBucket(client *s3.S3, bucketName string) error

DestroyBucket destroys a bucket with the input bucketName.

**Parameters:**

client: An AWS S3 client. bucketName: The name of the bucket to destroy.

**Returns:**

error: An error if the bucket could not be destroyed.

func DownloadBucketFile

func DownloadBucketFile(sess *session.Session, bucketName string, objectKey string, downloadFP string) (string, error)

DownloadBucketFile downloads a file found at the object key specified with the input objectKey from the bucket specified by bucketName, and writes it to downloadFP.

**Parameters:**

sess: An AWS session. bucketName: The name of the bucket to download from. objectKey: The key of the object to download. downloadFP: The file path to write the downloaded file to.

**Returns:**

string: The name of the downloaded file. error: An error if the file could not be downloaded.

func EmptyBucket

func EmptyBucket(client *s3.S3, bucketName string) error

EmptyBucket deletes everything found in the input bucketName.

**Parameters:**

client: An AWS S3 client. bucketName: The name of the bucket to empty.

**Returns:**

error: An error if the bucket could not be emptied.

func GetBuckets

func GetBuckets(client *s3.S3) ([]*s3.Bucket, error)

GetBuckets returns all s3 buckets that the input client has access to.

**Parameters:**

client: An AWS S3 client.

**Returns:**

[]*s3.Bucket: A slice of pointers to AWS S3 bucket structs that the client has access to. error: An error if the buckets could not be listed.

Example

package main

import (
	"fmt"

	"github.com/aws/aws-sdk-go/aws"
	"github.com/l50/awsutils/s3"
)

func main() {
	s3Connection := s3.CreateConnection()

	buckets, _ := s3.GetBuckets(s3Connection.Client)
	for _, b := range buckets {
		fmt.Printf("* %s created on %s\n",
			aws.StringValue(b.Name), aws.TimeValue(b.CreationDate))
	}
}

func UploadBucketDir

func UploadBucketDir(sess *session.Session, bucketName string, dirPath string) error

UploadBucketDir uploads a directory specified by dirPath to the bucket specified by bucketName.

**Parameters:**

sess: An AWS session. bucketName: The name of the bucket to upload to. dirPath: The file path of the directory to upload.

**Returns:**

error: An error if the directory could not be uploaded.

func UploadBucketFile

func UploadBucketFile(sess *session.Session, bucketName string, uploadFP string) error

UploadBucketFile uploads a file found at the file path specified with (uploadFP) to the input bucketName.

**Parameters:**

sess: An AWS session. bucketName: The name of the bucket to upload to. uploadFP: The file path of the file to upload.

**Returns:**

error: An error if the file could not be uploaded.

Types

type Connection

type Connection struct {
	Client  *s3.S3
	Session *session.Session
	Params  Params
}

Connection is a struct that contains all of the relevant information to maintain an S3 connection.

**Attributes:**

Client: An AWS S3 client that can be used to interact with an S3 service. Session: An AWS session that is used to create the S3 client. Params: Parameters that are used when interacting with the S3 service.

func CreateConnection

func CreateConnection() Connection

CreateConnection creates a connection with S3 and returns it.

**Returns:**

An s3.Connection struct containing the AWS S3 client and AWS session.

type Params

type Params struct {
	BucketName string
	Created    time.Time
	Modified   time.Time
}

Params is a struct that provides parameter options for an S3 bucket.

**Attributes:**

BucketName: The name of the bucket. Created: The time the bucket was created. Modified: The last modified time of the bucket.