Introduction

This is a first pass at a Ruby library for talking to Amazon’s S3 service.

It is less complete than my previous effort (townx.org/blog/elliot/s3_rails), but more solid, more elegant, and with a test suite (which uses RSpec - see rubyforge.org/projects/rspec).

To use it from inside your Ruby script:

  require 's33r'

By the way, I’ve tested this on Linux, but not on Windows or Mac.

Requirements

To get the most from s33r, you will need:

• Ruby 1.8.4 (this is what I developed with, but it may work OK with older versions)
• openssl (you can use s33r without this, but obviously you won’t be able to encrypt connections)
• libxml (s33r relies on this for parsing responses from S3)
• rspec (if you want to run the unit tests)
• fakeweb (to run tests)

Usage

• Set up an Amazon S3 account at amazon.com/s3.
• Checkout the s33r from the repository using svn checkout svn://rubyforge.org/var/svn/s33r/trunk s33r.
• Connect into the new directory made by checking out the code (s33r).
• Copy the sample configuration file (test/files/client_config.yml) to somewhere on your machine (e.g. /home/you/.s33r).
• Edit the file, replacing the sample aws_access_key and aws_secret_access_key with your settings.
• Fire up irb.
• Try the following code:

    require 'lib/s33r'
    include S33r
    # initialise a client instance from a config file
    client = Client.init('/home/you/.s33r')
    # create a bucket called 'some-outlandish-name'
    client.create_bucket('some-outlandish-name')
    # show the contents of the bucket
    client.list_buckets.body
    # put something into the bucket
    c.put_file('somefile.jpg', 'some-outlandish-name')
  

Note that the simple Client class is not sophisticated and returns raw requests (list_buckets returns a HTTPResponse object with attached body, for example). I tend to use NamedBucket instead, which provides a simplified interface to a single bucket. This saves having to pass the bucket name to every method call, and parses bucket listings into an object representation.

If you want to see a full example program which uses the library, have a look at bin/s3cli.rb. This is a simple command line client which you can use to post a file to S3 and email a link to the file to someone. Useful for sending big files to people without clogging their email inbox with enormous files. It is also intended as a demonstration of how to use the library. Full instructions are included at the top of the file.

Credits

Thanks for bug reports to: Keaka (keakaj.com/products.htm)