s4 0.0.1 → 0.0.2

data/Rakefile

@@ -1,5 +1,5 @@
 task :default => :test
 
 task :test do
-  system "cutest test/*.rb"
+  system "ruby test/*.rb"
 end

data/lib/s4.rb

@@ -5,7 +5,7 @@ require "time"
 
 # Simpler AWS S3 library
 class S4
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 
   # sub-resource names which may appear in the query string and also must be
   # signed against.
@@ -16,8 +16,42 @@ class S4
   HeaderValues = %w( response-content-type response-content-language response-expires reponse-cache-control response-content-disposition response-content-encoding )
 
   attr_reader :connection, :access_key_id, :secret_access_key, :bucket, :host
-
-  def initialize(s3_url = ENV["S3_URL"])
+  
+  class << self
+    # Connect to an S3 bucket.
+    # 
+    # Pass your S3 connection parameters as URL, or read from ENV["S3_URL"] if
+    # none is passed.
+    # 
+    # S3_URL format is s3://<access key id>:<secret access key>@s3.amazonaws.com/<bucket>
+    # 
+    # i.e.
+    #   bucket = S4.connect #=> Connects to ENV["S3_URL"]
+    #   bucket = S4.connect("s3://0PN5J17HBGZHT7JJ3X82:k3nL7gH3+PadhTEVn5EXAMPLE@s3.amazonaws.com/bucket")
+    def connect(s3_url=ENV["S3_URL"])
+      new(s3_url).tap do |s4|
+        s4.connect
+      end
+    end
+    
+    # Create an S3 bucket.
+    # 
+    # See #connect for S3_URL parameters.
+    # 
+    # Will create the bucket on S3 and connect to it, or just connect if the
+    # bucket already exists and is owned by you.
+    # 
+    # i.e.
+    #   bucket = S4.create
+    def create(s3_url=ENV["S3_URL"])
+      new(s3_url).tap do |s4|
+        s4.create
+      end
+    end
+  end
+  
+  # Initialize a new S3 bucket connection.
+  def initialize(s3_url=ENV["S3_URL"])
     raise ArgumentError, "No S3 URL provided. You can set ENV['S3_URL'], too." if s3_url.nil? || s3_url.empty?
 
     begin
@@ -27,23 +61,38 @@ class S4
       raise e
     end
 
-    @access_key_id     = url.user
+    @access_key_id = url.user
     @secret_access_key = URI.unescape(url.password || "")
-    @host              = url.host
-    @bucket            = url.path[1..-1]
+    @host = url.host
+    @bucket = url.path[1..-1]
   end
-
-  def connection
-    @connection ||= Net::HTTP::Persistent.new("aws-s3/#{bucket}")
+  
+  # Connect to the S3 bucket.
+  # 
+  # Since S3 doesn't really require a persistent connection this really just
+  # makes sure that it *can* connect (i.e. the bucket exists and you own it).
+  def connect
+    raise NoSuchBucket.new(bucket) if request(uri("/", query: "location")).nil?
+  end
+  
+  # Create the S3 bucket.
+  def create
+    uri = URI::HTTP.build(host: host, path: "/#{bucket}")
+    request uri, Net::HTTP::Put.new(uri.request_uri)
   end
 
   # Lower level object get which just yields the successful S3 response to the
   # block. See #download if you want to simply copy a file from S3 to local.
   def get(name, &block)
     request(uri(name), &block)
+  rescue S4::Error => e
+    raise e if e.status != "404"
   end
 
   # Download the file with the given filename to the given destination.
+  # 
+  # i.e.
+  #   bucket.download("images/palm_trees.jpg", "./palm_trees.jpg")
   def download(name, destination=nil)
     get(name) do |response|
       File.open(destination || File.join(Dir.pwd, File.basename(name)), "wb") do |io|
@@ -59,13 +108,18 @@ class S4
     request(uri = uri(name), Net::HTTP::Delete.new(uri.request_uri))
   end
 
-  # Upload the file with the given filename to the given destination in your
-  # S3 bucket. If no destination is given then uploads it with the same
-  # filename to the root of your bucket.
+  # Upload the file with the given filename to the given destination in your S3
+  # bucket.
+  # 
+  # If no destination is given then uploads it with the same filename to the
+  # root of your bucket.
+  # 
+  # i.e.
+  #   bucket.upload("./images/1996_animated_explosion.gif", "website_background.gif")
   def upload(name, destination=nil)
     put File.open(name, "rb"), destination || File.basename(name)
   end
-
+  
   def put(io, name)
     uri = uri(name)
     req = Net::HTTP::Put.new(uri.request_uri)
@@ -77,38 +131,40 @@ class S4
     request(URI::HTTP.build(host: host, path: "/#{bucket}/#{name}"), req)
   end
 
-  # List bucket contents
+  # List bucket contents.
+  # 
+  # Optionally pass a prefix to list from (useful for paths).
+  # 
+  # i.e.
+  #   bucket.list("images/") #=> [ "birds.jpg", "bees.jpg" ]
   def list(prefix = "")
     REXML::Document.new(request(uri("", query: "prefix=#{prefix}"))).elements.collect("//Key", &:text)
   end
-
+  
   private
-
+  
+  def connection
+    @connection ||= Net::HTTP::Persistent.new("aws-s3/#{bucket}")
+  end
+  
   def uri(path, options={})
-    URI::HTTP.build(options.merge(host: host, path: "/#{bucket}/#{CGI.escape(path.sub(/^\//, ""))}"))
+    URI::HTTP.build(options.merge(host: host, path: "/#{bucket}/#{URI.escape(path.sub(/^\//, ""))}"))
   end
 
   # Makes a request to the S3 API.
-  def request(uri, request = nil)
-    # TODO: Possibly use SAX parsing for large request bodies (?)
-
+  def request(uri, request=nil)
     request ||= Net::HTTP::Get.new(uri.request_uri)
-
+    
     connection.request(uri, sign(uri, request)) do |response|
       case response
-        when Net::HTTPNotFound
-          return nil
-
-        when Net::HTTPSuccess
-          if block_given?
-            yield(response)
-          else
-            return response.body
-          end
-
+      when Net::HTTPSuccess
+        if block_given?
+          yield(response)
         else
-          raise Error.from_xml(response.body)
-
+          return response.body
+        end
+      else
+        raise Error.from_response(response)
       end
     end
   end
@@ -123,22 +179,47 @@ class S4
   end
 
   def signature(uri, request)
+    query = signed_params(uri.query) if uri.query
+    
     Base64.encode64(
       OpenSSL::HMAC.digest(
         OpenSSL::Digest::Digest.new("sha1"),
         secret_access_key,
-        "#{request.class::METHOD}\n\n#{request["Content-Type"]}\n#{request.fetch("Date")}\n#{uri.path}"
+        "#{request.class::METHOD}\n\n#{request["Content-Type"]}\n#{request.fetch("Date")}\n" + uri.path + (query ? "?#{query}"  : "")
       )
     ).chomp
   end
-
+  
+  # Returns the given query string consisting only of query parameters which
+  # need to be signed against, or nil if there are none in the query string.
+  def signed_params(query)
+    signed = query.
+      split("&").
+      collect{ |param| param.split("=") }.
+      reject{ |pair| !SubResources.include?(pair[0]) }.
+      collect{ |pair| pair.join("=") }.
+      join("&")
+      
+    signed unless signed.empty?
+  end
+  
   # Base class of all S3 Errors
   class Error < ::RuntimeError
-    def self.from_xml(xml)
-      doc = REXML::Document.new(xml).elements["//Error"]
+    attr_reader :code, :status
+    
+    def self.from_response(response)
+      doc = REXML::Document.new(response.body).elements["//Error"]
       code = doc.elements["Code"].text
       message = doc.elements["Message"].text
-      new("#{code}: #{message}")
+      
+      new response.code, code, message
     end
-  end
+    
+    def initialize(status, code, message)
+      @status = status
+      @code = code
+      
+      super "#{@code}: #{message}"
+    end
+  end  
 end

data/s4.gemspec

@@ -1,13 +1,13 @@
 require "./lib/s4"
 
 Gem::Specification.new do |s|
-  s.name              = "s4"
-  s.version           = S4::VERSION
-  s.summary           = "Simple API for AWS S3"
-  s.description       = "Simple API for AWS S3"
-  s.authors           = ["Ben Alavi"]
-  s.email             = ["ben.alavi@citrusbyte.com"]
-  s.homepage          = "http://github.com/benalavi/s4"
+  s.name = "s4"
+  s.version = S4::VERSION
+  s.summary = "Simple API for AWS S3"
+  s.description = "Simple API for AWS S3"
+  s.authors = ["Ben Alavi"]
+  s.email = ["ben.alavi@citrusbyte.com"]
+  s.homepage = "http://github.com/benalavi/s4"
 
   s.files = Dir[
     "LICENSE",

data/test/s4_test.rb

@@ -0,0 +1,151 @@
+require "contest"
+require "timecop"
+require "fileutils"
+
+begin
+  require "ruby-debug"
+rescue LoadError
+end
+
+require File.expand_path("../lib/s4", File.dirname(__FILE__))
+
+def fixture(filename="")
+  File.join(File.dirname(__FILE__), "fixtures", filename)
+end
+
+def output(filename="")
+  File.join(File.dirname(__FILE__), "output", filename)
+end
+
+NewBucket = "s4-bucketthatdoesntexist"
+TestBucket = "s4-test-bucket"
+
+class S4Test < Test::Unit::TestCase
+  setup do
+    FileUtils.rm_rf(output)
+    FileUtils.mkdir_p(output)
+  end
+  
+  context "connecting to S3" do
+    should "return connected bucket if can connect" do
+      s4 = S4.connect
+    end
+    
+    should "raise error if cannot connect" do
+      `s3cmd rb 's3://#{NewBucket}' 2>&1`
+      
+      assert_raise(S4::Error) do
+        S4.connect ENV["S3_URL"].sub(TestBucket, NewBucket)
+      end
+    end
+  end
+
+  context "when S3 errors occur" do
+    # foo is taken bucket, will cause 409 Conflict on create
+    
+    should "raise on S3 errors" do
+      assert_raise(S4::Error) do
+        S4.create(ENV["S3_URL"].sub(TestBucket, "foo"))
+      end
+    end
+  
+    should "capture code of S3 error" do
+      begin
+        S4.create(ENV["S3_URL"].sub(TestBucket, "foo"))
+      rescue S4::Error => e
+        assert_equal "409", e.status
+      end
+    end
+  end
+  
+  context "creating a bucket" do    
+    setup do
+      `s3cmd rb 's3://#{NewBucket}' 2>&1`
+    end
+    
+    should "create a bucket" do
+      assert_equal "ERROR: Bucket '#{NewBucket}' does not exist", `s3cmd ls 's3://#{NewBucket}' 2>&1`.chomp
+      s4 = S4.create ENV["S3_URL"].sub(TestBucket, NewBucket)
+      assert_equal "", `s3cmd ls 's3://#{NewBucket}' 2>&1`.chomp
+    end
+  end
+
+  context "when connected" do
+    setup do
+      @s4 = S4.connect
+    end
+    
+    should "download foo.txt" do
+      `s3cmd put #{fixture("foo.txt")} s3://#{@s4.bucket}/foo.txt`
+      @s4.download("foo.txt", output("foo.txt"))
+
+      assert_equal "abc123", File.read(output("foo.txt"))
+    end
+
+    should "not download non-existent files" do
+      `s3cmd del 's3://#{@s4.bucket}/foo.txt'`
+      @s4.download("foo.txt", output("foo.txt"))
+
+      assert !File.exists?(output("foo.txt"))
+    end
+    
+    should "return false when downloading non-existent files" do
+      `s3cmd del 's3://#{@s4.bucket}/foo.txt'`
+      assert_equal nil, @s4.download("foo.txt", output("foo.txt"))
+    end
+
+    should "yield raw response from get of foo.txt" do
+      `s3cmd put #{fixture("foo.txt")} s3://#{@s4.bucket}/foo.txt`
+
+      @s4.get("foo.txt") do |response|
+        assert_equal "abc123", response.body
+      end
+    end
+
+    should "delete object" do
+      `s3cmd put #{fixture("foo.txt")} s3://#{@s4.bucket}/foo.txt`
+      @s4.get("foo.txt") { |response| assert_equal "abc123", response.body }
+      @s4.delete("foo.txt")
+
+      assert_equal nil, @s4.get("foo.txt")
+    end
+
+    should "return list of items in bucket" do
+      `s3cmd del 's3://#{@s4.bucket}/abc/*'`
+      `s3cmd del 's3://#{@s4.bucket}/boom.txt'`
+      `s3cmd del 's3://#{@s4.bucket}/foo\ bar+baz.txt'`
+      `s3cmd put #{fixture("foo.txt")} s3://#{@s4.bucket}/foo.txt`
+      `s3cmd put #{fixture("foo.txt")} s3://#{@s4.bucket}/bar.txt`
+      `s3cmd put #{fixture("foo.txt")} s3://#{@s4.bucket}/baz.txt`
+
+      assert_equal %w( bar.txt baz.txt foo.txt ), @s4.list
+    end
+
+    should "return list of keys starting with prefix" do
+      `s3cmd put #{fixture("foo.txt")} s3://#{@s4.bucket}/abc/bing.txt`
+      `s3cmd put #{fixture("foo.txt")} s3://#{@s4.bucket}/abc/bang.txt`
+      `s3cmd put #{fixture("foo.txt")} s3://#{@s4.bucket}/boom.txt`
+
+      assert_equal %w( abc/bang.txt abc/bing.txt ), @s4.list("abc/")
+    end
+
+    should "get content with special chars in it" do
+      `s3cmd put #{fixture("foo.txt")} 's3://#{@s4.bucket}/foo bar+baz.txt'`
+
+      @s4.get("foo bar+baz.txt") { |response| assert_equal "abc123", response.body }
+    end
+
+    should "upload foo.txt" do
+      `s3cmd del 's3://#{@s4.bucket}/foo.txt'`
+      @s4.upload(fixture("foo.txt"))
+      @s4.get("foo.txt") { |response| assert_equal "abc123", response.body }
+    end
+
+    should "bark when no URL is provided" do
+      assert_raise(ArgumentError) { S4.connect("") }
+      assert_raise(ArgumentError) { S4.connect(nil) }
+
+      assert_raise(URI::InvalidURIError) { S4.connect("s3://foo:bar/baz") }
+    end
+  end
+end

metadata

@@ -2,7 +2,7 @@
 name: s4
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Ben Alavi
@@ -10,8 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-20 00:00:00 -03:00
-default_executable: 
+date: 2011-09-01 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: net-http-persistent
@@ -59,8 +58,7 @@ files:
 - Rakefile
 - lib/s4.rb
 - s4.gemspec
-- test/s3_test.rb
-has_rdoc: true
+- test/s4_test.rb
 homepage: http://github.com/benalavi/s4
 licenses: []
 
@@ -84,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Simple API for AWS S3

data/test/s3_test.rb

@@ -1,108 +0,0 @@
-require "cutest"
-require "timecop"
-require "fileutils"
-
-begin
-  require "ruby-debug"
-rescue LoadError
-end
-
-require File.expand_path("../lib/s3", File.dirname(__FILE__))
-
-def fixture(filename="")
-  File.join(File.dirname(__FILE__), "fixtures", filename)
-end
-
-def output(filename="")
-  File.join(File.dirname(__FILE__), "output", filename)
-end
-
-Bucket = URI(ENV["S3_URL"]).path[1..-1]
-
-scope do
-  setup do
-    FileUtils.rm_rf(output)
-    FileUtils.mkdir_p(output)
-    @s3 = S3.new
-  end
-
-  test "should download foo.txt" do
-    `s3cmd put #{fixture("foo.txt")} s3://#{Bucket}/foo.txt`
-    @s3.download("foo.txt", output("foo.txt"))
-
-    assert_equal "abc123", File.read(output("foo.txt"))
-  end
-
-  test "should not download non-existent files" do
-    `s3cmd del 's3://#{Bucket}/foo.txt'`
-    @s3.download("foo.txt", output("foo.txt"))
-
-    assert !File.exists?(output("foo.txt"))
-  end
-
-  test "should yield raw response from get of foo.txt" do
-    `s3cmd put #{fixture("foo.txt")} s3://#{Bucket}/foo.txt`
-
-    @s3.get("foo.txt") do |response|
-      assert_equal "abc123", response.body
-    end
-  end
-
-  test "should delete object" do
-    `s3cmd put #{fixture("foo.txt")} s3://#{Bucket}/foo.txt`
-    @s3.get("foo.txt") { |response| assert_equal "abc123", response.body }
-    @s3.delete("foo.txt")
-
-    assert_equal nil, @s3.get("foo.txt")
-  end
-
-  test "should return list of items in bucket" do
-    `s3cmd del 's3://#{Bucket}/abc/*'`
-    `s3cmd del 's3://#{Bucket}/boom.txt'`
-    `s3cmd del 's3://#{Bucket}/foo\ bar+baz.txt'`
-    `s3cmd put #{fixture("foo.txt")} s3://#{Bucket}/foo.txt`
-    `s3cmd put #{fixture("foo.txt")} s3://#{Bucket}/bar.txt`
-    `s3cmd put #{fixture("foo.txt")} s3://#{Bucket}/baz.txt`
-
-    assert_equal %w( bar.txt baz.txt foo.txt ), @s3.list
-  end
-
-  test "should return list of keys starting with prefix" do
-    `s3cmd put #{fixture("foo.txt")} s3://#{Bucket}/abc/bing.txt`
-    `s3cmd put #{fixture("foo.txt")} s3://#{Bucket}/abc/bang.txt`
-    `s3cmd put #{fixture("foo.txt")} s3://#{Bucket}/boom.txt`
-
-    assert_equal %w( abc/bang.txt abc/bing.txt ), @s3.list("abc/")
-  end
-
-  test "should get content with special chars in it" do
-    `s3cmd put #{fixture("foo.txt")} 's3://#{Bucket}/foo bar+baz.txt'`
-
-    @s3.get("foo bar+baz.txt") { |response| assert_equal "abc123", response.body }
-  end
-
-  test "should upload foo.txt" do
-    `s3cmd del 's3://#{Bucket}/foo.txt'`
-
-    s3 = S3.new
-
-    s3.upload(fixture("foo.txt"))
-
-    s3.get("foo.txt") { |response| assert_equal "abc123", response.body }
-  end
-
-  test "barks when no URL is provided" do
-    assert_raise(ArgumentError) { S3.new("") }
-    assert_raise(ArgumentError) { S3.new(nil) }
-
-    assert_raise(URI::InvalidURIError) { S3.new("s3://foo:bar/baz") }
-  end
-
-  test "raises on S3 errors" do
-    s3 = S3.new(ENV["S3_URL"].sub(/.@/, "@")) # Break the password
-
-    assert_raise(S3::Error) do
-      s3.upload(fixture("foo.txt"))
-    end
-  end
-end