Easier Than S3?

The Ruby S3 Gem is already easy, what's this all about? Its true, the standard gem is great, but I usually use it the same way every time and only do a few things with it. Like, I almost always use the same bucket for everything an app does. And I never use more than one S3 account in one app. So, I was always writing the same few bits of code to support my use case and I decided to cut a gem to make this easier.

Install

Just use the gem command:

gem install easy_s3

If you don't have aws-s3, rubygems will install it for you.

Setup

EasyS3 must be instantiated before you can use it and there are a couple ways you can do this. The most straightforward way is to simply pass it three string parameters:

easy_s3 = EasyS3.new('bucket', 'key', 'secret')

This will create a new instance of EasyS3 that you can then use later (see Methods and Usage below).

Another approach is to set ENV variables for the gem to use. If you set ENV['EASY_S3_KEY'] and ENV['EASY_S3_SECRET'], then you can leave those parameters off, like this:

easy_s3 = EasyS3.new('bucket')

But make sure you name your ENV variables as above so the gem can find them.

I like the second approach best because it keeps sensitive things out of your repo. In development, I'll have a handful of apps using this gem and they all use the same S3 account, so setting these variables once in my .profile file works great. But when I do have a project that uses a different S3 account, then I'll use the first approach, but still use EVN variables, just ones that are specific to the app I'm working with, like this:

easy_s3 = EasyS3.new('bucket', ENV['MYAPP_EASY_S3_KEY'], ENV['MYAPP_EASY_S3_SECRET'])

Whichever way you go about setting up your instance, the main thing you're setting is the bucket and that's my main assumption here: that you'll do all your work in one bucket. If that's not how you use S3, this gem ain't for you. If that is how you use S3, then I think you'll like convenience of not having to specify this over and over again.

Methods

Once you've got your EasyS3 instance, you can call five main methods on it:

easy_s3.write(path, data) => writes the data its given to the file at path
easy_s3.file(path) => gets the AWS::S3::S3Object found at path
easy_s3.exists?(path) => check if a file exists at path and returns a boolean
easy_s3.append(path, data) => appends data to the end of the file found at path (uses write)
easy_s3.read(path) => returns a string of the value of the file found at path (uses file)

Remember: these are all being called in the context of your EasyS3 instance, so the S3 account and bucket are coming from your setup above.

Usage

I wrote this to support five use cases.

--Create a file and write some data to it:

easy_s3.write('path/to/file.txt', 'blah, blah, blah')

--Append a message to a log file:

easy_s3.append('path/to/log/file.txt', 'ack, the program asploded!')

--See if a file exists

puts 'our file is there!' if easy_s3.exists?('path/to/file.txt')

--Get the value of a file

data = easy_s3.read('path/to/file.txt')

--Get the actual S3Object (and then do something with it)

file = easy_s3.file('path/to/file.txt')