awsum 0.5 → 0.5.1

data/Gemfile

@@ -5,7 +5,7 @@ gem "bundler", "~> 1.0.0"
 
 group :development do
   gem "jeweler"
-  gem "rspec", ">= 2.0.0.beta.22"
+  gem "rspec", ">= 2.0.0"
   gem "fakeweb"
 
   gem "shoulda"

data/Gemfile.lock

@@ -2,30 +2,24 @@ GEM
   remote: http://rubygems.org/
   specs:
     diff-lcs (1.1.2)
-    fakeweb (1.2.8)
-    gemcutter (0.6.1)
+    fakeweb (1.3.0)
     git (1.2.5)
-    jeweler (1.4.0)
-      gemcutter (>= 0.1.0)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
       git (>= 1.2.5)
-      rubyforge (>= 2.0.0)
-    json_pure (1.4.6)
-    mocha (0.9.8)
+      rake
+    mocha (0.9.10)
       rake
     rake (0.8.7)
     rcov (0.9.9)
-    rspec (2.0.0.beta.22)
-      rspec-core (= 2.0.0.beta.22)
-      rspec-expectations (= 2.0.0.beta.22)
-      rspec-mocks (= 2.0.0.beta.22)
-    rspec-core (2.0.0.beta.22)
-    rspec-expectations (2.0.0.beta.22)
-      diff-lcs (>= 1.1.2)
-    rspec-mocks (2.0.0.beta.22)
-      rspec-core (= 2.0.0.beta.22)
-      rspec-expectations (= 2.0.0.beta.22)
-    rubyforge (2.0.4)
-      json_pure (>= 1.1.7)
+    rspec (2.4.0)
+      rspec-core (~> 2.4.0)
+      rspec-expectations (~> 2.4.0)
+      rspec-mocks (~> 2.4.0)
+    rspec-core (2.4.0)
+    rspec-expectations (2.4.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.4.0)
     shoulda (2.11.3)
     timecop (0.3.5)
 
@@ -39,6 +33,6 @@ DEPENDENCIES
   mocha
   rake
   rcov
-  rspec (>= 2.0.0.beta.22)
+  rspec (>= 2.0.0)
   shoulda
   timecop

data/README.rdoc

@@ -16,7 +16,7 @@ allowing you to work with objects in a very natural way.
 
 ==Working with different Regions
 You can use blocks to wrap your calls for a specific Region
-  ec2.region('eu-west-1').use do
+  ec2.region('eu-west-1') do
     #Run an instance in the eu-west-1 region
     run_instance(...)
   end

data/Rakefile

@@ -43,7 +43,7 @@ end
 desc 'Start an IRB session with all necessary files required.'
 task :shell do |t|
   chdir File.dirname(__FILE__)
-  exec 'irb -I lib/ -I lib/awsum -r rubygems -r awsum'
+  exec 'irb -I lib/ -r rubygems -r awsum/ec2 -r awsum/s3'
 end
 
 desc 'Generate documentation.'
@@ -64,12 +64,12 @@ end
 
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new do |t|
-  t.pattern = "./spec/lib/**/*_spec.rb"
+  t.pattern = "./spec/**/*_spec.rb"
 end
 
 namespace :spec do
   desc "Run RSpec integration code examples (LIVE runs against Amazon AWS)"
   RSpec::Core::RakeTask.new(:integration) do |t|
-    t.pattern = "./spec/functional/**/*_spec.rb"
+    t.pattern = "./functional/**/*_spec.rb"
   end
 end

data/functional/ec2/instances_spec.rb

@@ -0,0 +1,46 @@
+require File.join(File.dirname(__FILE__), '../spec_helper')
+
+functional "Instances" do
+  let(:ec2) { Awsum::Ec2.new(access_key, secret_key) }
+
+  it "should succeed" do
+    image = run "retrieving an image" do
+      images = ec2.images(:filter => {:architecture => 'i386', :name => '*ubuntu*', 'image-type' => 'machine', :state => 'available'})
+      images[0]
+    end
+
+    instance = run "launching an instance of #{image.id}" do
+      instances = image.run :instance_type => 't1.micro', :tags => {'Name' => 'awsum.test'}
+      instances[0]
+    end
+
+    wait_for instance, 'running'
+
+    volume = run "attaching a volume to instance #{instance.id}" do
+      instance.create_volume(5, :device => '/dev/sdh', :tags => {'Name' => 'awsum.test'})
+    end
+    wait_for volume, 'in-use'
+
+    snapshot = run "taking a snapshot of volume #{volume.id}" do
+      volume.create_snapshot :tags => {'Name' => 'awsum.test'}
+    end
+    wait_for snapshot, 'completed'
+
+    run "deleting snapshot #{snapshot.id}" do
+      snapshot.delete
+    end
+
+    run "detaching volue #{volume.id}" do
+      volume.detach
+    end
+    wait_for volume, 'available'
+
+    run "deleting volue #{volume.id}" do
+      volume.delete
+    end
+
+    run "terminating instance #{instance.id}" do
+      instance.terminate
+    end
+  end
+end

data/functional/spec_helper.rb

@@ -0,0 +1,71 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'awsum/ec2'
+require 'awsum/s3'
+
+def functional(description, &block)
+  describe "Functional: #{description}" do
+    let(:keys) do
+      rc_file = File.join(File.expand_path('~'), '.awsumrc')
+      unless File.exists?(rc_file)
+        raise 'Unable to run functional specs with out access and secret keys. Place them in ~/.awsumrc'
+      end
+      YAML.load(File.read(rc_file))
+    end
+
+    let(:access_key) { keys['access_key'] }
+    let(:secret_key) { keys['secret_key'] }
+
+    instance_eval(&block)
+
+    after(:all) do
+      ec2.instances(:filter => {'instance-state-name' => ['running', 'stopped']},
+                    :tags => {'Name' => 'awsum.test'}).each do |instance|
+        begin
+          instance.terminate
+          wait_for instance, 'terminated'
+        rescue
+          puts "Could not terminate instance #{instance.id}"
+          puts $!.inspect
+          puts $!.backtrace
+        end
+      end
+
+      ec2.volumes(:filter => {'status' => ['available', 'in-use']},
+                  :tags => {'Name' => 'awsum.test'}).each do |volume|
+        begin
+          volume.delete!
+        rescue
+          puts "Could not delete volume #{volume.id}"
+          puts $!.inspect
+          puts $!.backtrace
+        end
+      end
+
+      ec2.snapshots(:filter => {'status' => ['pending', 'completed']},
+                  :tags => {'Name' => 'awsum.test'}).each do |snapshot|
+        begin
+          snapshot.delete
+        rescue
+          puts "Could not delete snapshot #{snapshot.id}"
+          puts $!.inspect
+          puts $!.backtrace
+        end
+      end
+    end
+  end
+end
+
+def run(description, &block)
+  puts description
+  yield
+end
+
+def wait_for(object, state = 'available')
+  print "waiting for #{state} on #{object.class}(#{object.id}) "
+  while (object.respond_to?(:state) ? object.state : object.status) != state
+    sleep 1
+    object.reload
+    print '.'
+  end
+  puts
+end

data/lib/awsum.rb

@@ -11,9 +11,9 @@ require 'awsum/requestable'
 require 'awsum/support'
 
 module Awsum
-  VERSION = "0.5"
+  VERSION = "0.5.1"
 
-  API_VERSION = '2010-06-15'
+  API_VERSION = '2010-08-31'
   SIGNATURE_VERSION = 2
 end
 

data/lib/awsum/ec2.rb

@@ -9,6 +9,8 @@ require 'awsum/ec2/reserved_instance'
 require 'awsum/ec2/reserved_instances_offering'
 require 'awsum/ec2/security_group'
 require 'awsum/ec2/snapshot'
+require 'awsum/ec2/state'
+require 'awsum/ec2/tag'
 require 'awsum/ec2/volume'
 
 module Awsum
@@ -68,6 +70,8 @@ module Awsum
     # * <tt>:image_ids</tt> - array of Image id's, default: []
     # * <tt>:owners</tt> - array of owner id's, default: []
     # * <tt>:executable_by</tt> - array of user id's who have executable permission, default: []
+    # * <tt>:filter</tt> - hash of filters (e.g. :filter => {:architecture => 'i386'})
+    # * <tt>:tags</tt> - hash of tags (e.g. :tags => {:name => 'Test'})
     def images(options = {})
       options = {:image_ids => [], :owners => [], :executable_by => []}.merge(options)
       action = 'DescribeImages'
@@ -78,6 +82,7 @@ module Awsum
       params.merge!(array_to_params(options[:image_ids], "ImageId"))
       params.merge!(array_to_params(options[:owners], "Owner"))
       params.merge!(array_to_params(options[:executable_by], "ExecutableBy"))
+      params.merge!(parse_filters(options[:filter], options[:tags]))
 
       response = send_query_request(params)
       parser = Awsum::Ec2::ImageParser.new(self)
@@ -85,8 +90,8 @@ module Awsum
     end
 
     # Retrieve all Image(s) owned by you
-    def my_images
-      images :owners => 'self'
+    def my_images(options = {})
+      images options.merge(:owners => 'self')
     end
 
     # Retrieve a single Image
@@ -160,17 +165,27 @@ module Awsum
 
       response = send_query_request(params)
       parser = Awsum::Ec2::InstanceParser.new(self)
-      parser.parse(response.body)
+      instances = parser.parse(response.body)
+      if options[:tags] && options[:tags].size > 0
+        create_tags instances.map{|i| i.id}, options[:tags]
+      end
+      instances
     end
     alias_method :launch_instances, :run_instances
 
     #Retrieve the information on a number of Instance(s)
+    #
+    # ===Options:
+    # * <tt>:filter</tt> - hash of filters (e.g. :filter => {:architecture => 'i386'})
+    # * <tt>:tags</tt> - hash of tags (e.g. :tags => {:name => 'Test'})
     def instances(*instance_ids)
+      options = instance_ids[-1].respond_to?(:keys) ? instance_ids.pop : {}
       action = 'DescribeInstances'
       params = {
         'Action' => action
       }
       params.merge!(array_to_params(instance_ids, 'InstanceId'))
+      params.merge!(parse_filters(options[:filter], options[:tags]))
 
       response = send_query_request(params)
       parser = Awsum::Ec2::InstanceParser.new(self)
@@ -219,13 +234,43 @@ module Awsum
       response.is_a?(Net::HTTPSuccess)
     end
 
+    def tags(filter = {})
+      action = 'DescribeTags'
+      params = {
+        'Action' => action
+      }
+      params.merge!(parse_filters(filter))
+
+      response = send_query_request(params)
+      parser = Awsum::Ec2::TagParser.new(self)
+      parser.parse(response.body)
+    end
+
+    def create_tags(resource_ids, tags)
+      action = 'CreateTags'
+      params = {
+        'Action' => action
+      }
+      params.merge!(array_to_params(resource_ids, 'ResourceId'))
+      params.merge!(parse_tag_keys(tags))
+
+      response = send_query_request(params)
+      response.is_a?(Net::HTTPSuccess)
+    end
+
     #Retrieve the information on a number of Volume(s)
+    #
+    # ===Options:
+    # * <tt>:filter</tt> - hash of filters (e.g. :filter => {'attachment.status' => 'attached'})
+    # * <tt>:tags</tt> - hash of tags (e.g. :tags => {:name => 'Test'})
     def volumes(*volume_ids)
+      options = volume_ids[-1].respond_to?(:keys) ? volume_ids.pop : {}
       action = 'DescribeVolumes'
       params = {
         'Action' => action
       }
       params.merge!(array_to_params(volume_ids, 'VolumeId'))
+      params.merge!(parse_filters(options[:filter], options[:tags]))
 
       response = send_query_request(params)
       parser = Awsum::Ec2::VolumeParser.new(self)
@@ -256,7 +301,11 @@ module Awsum
 
       response = send_query_request(params)
       parser = Awsum::Ec2::VolumeParser.new(self)
-      parser.parse(response.body)[0]
+      volume = parser.parse(response.body)[0]
+      if options[:tags] && options[:tags].size > 0
+        create_tags volume.id, options[:tags]
+      end
+      volume
     end
 
     # Attach a volume to an instance
@@ -306,25 +355,36 @@ module Awsum
     end
 
     # Create a Snapshot of a Volume
-    def create_snapshot(volume_id)
+    #
+    # ===Options:
+    # :description => A description for the stapshot
+    # :tags => A hash of tags to be associated with the snapshot
+    def create_snapshot(volume_id, options = {})
       action = 'CreateSnapshot'
       params = {
         'Action'   => action,
         'VolumeId' => volume_id
       }
+      params['Description'] = options[:description] unless options[:description].blank?
 
       response = send_query_request(params)
       parser = Awsum::Ec2::SnapshotParser.new(self)
-      parser.parse(response.body)[0]
+      snapshot = parser.parse(response.body)[0]
+      if options[:tags] && options[:tags].size > 0
+        create_tags snapshot.id, options[:tags]
+      end
+      snapshot
     end
 
     # List Snapshot(s)
     def snapshots(*snapshot_ids)
+      options = snapshot_ids[-1].respond_to?(:keys) ? snapshot_ids.pop : {}
       action = 'DescribeSnapshots'
       params = {
         'Action' => action
       }
       params.merge!(array_to_params(snapshot_ids, 'SnapshotId'))
+      params.merge!(parse_filters(options[:filter], options[:tags]))
 
       response = send_query_request(params)
       parser = Awsum::Ec2::SnapshotParser.new(self)
@@ -574,39 +634,21 @@ module Awsum
 
     # Authorize access on a specific security group
     #
-    # ===Options:
+    # ===Usage
     # ====User/Group access
-    # * <tt>:source_security_group_name</tt> - Name of the security group to authorize access to when operating on a user/group pair
-    # * <tt>:source_security_group_owner_id</tt> - Owner of the security group to authorize access to when operating on a user/group pair
+    # ec2.authorize_security_group_ingress('security_group', {:ip_protocol => :tcp, :from_port => 80, :to_port => 80, :groups => [{:group_name => :authorized_group}]})
     # ====CIDR IP access
-    # * <tt>:ip_protocol</tt> - IP protocol to authorize access to when operating on a CIDR IP (tcp, udp or icmp) (default: tcp)
-    # * <tt>:from_port</tt> - Bottom of port range to authorize access to when operating on a CIDR IP. This contains the ICMP type if ICMP is being authorized.
-    # * <tt>:to_port</tt> - Top of port range to authorize access to when operating on a CIDR IP. This contains the ICMP type if ICMP is being authorized.
-    # * <tt>:cidr_ip</tt> - CIDR IP range to authorize access to when operating on a CIDR IP. (default: 0.0.0.0/0)
-    def authorize_security_group_ingress(group_name, options = {})
-      got_at_least_one_user_group_option = !options[:source_security_group_name].nil? || !options[:source_security_group_owner_id].nil?
-      got_user_group_options = !options[:source_security_group_name].nil? && !options[:source_security_group_owner_id].nil?
-      got_at_least_one_cidr_option = !options[:ip_protocol].nil? || !options[:from_port].nil? || !options[:to_port].nil? || !options[:cidr_ip].nil?
-      #Add in defaults
-      options = {:cidr_ip => '0.0.0.0/0'}.merge(options) if got_at_least_one_cidr_option
-      options = {:ip_protocol => 'tcp'}.merge(options) if got_at_least_one_cidr_option
-      got_cidr_options = !options[:ip_protocol].nil? && !options[:from_port].nil? && !options[:to_port].nil? && !options[:cidr_ip].nil?
-      raise ArgumentError.new('Can only authorize user/group or CIDR IP, not both') if got_at_least_one_user_group_option && got_at_least_one_cidr_option
-      raise ArgumentError.new('Need all user/group options when authorizing user/group access') if got_at_least_one_user_group_option && !got_user_group_options
-      raise ArgumentError.new('Need all CIDR IP options when authorizing CIDR IP access') if got_at_least_one_cidr_option && !got_cidr_options
-      raise ArgumentError.new('ip_protocol can only be one of tcp, udp or icmp') if got_at_least_one_cidr_option && !%w(tcp udp icmp).detect{|p| p == options[:ip_protocol] }
+    # ec2.authorize_security_group_ingress('security_group', {:ip_protocol => :tcp, :from_port => 80, :to_port => 80, :ip_ranges => [{:cidr_ip => '0.0.0.0/0'}]})
+    def authorize_security_group_ingress(group_name, arguments)
+      raise ArgumentError.new('Can only authorize user/group or CIDR IP, not both') if [arguments].flatten.detect{|a| a.has_key?(:ip_ranges) && a.has_key?(:groups)}
+      raise ArgumentError.new('ip_protocol can only be one of tcp, udp or icmp') if [arguments].flatten.detect{|a| !%w(tcp udp icmp).detect{|p| p == a[:ip_protocol].to_s } }
 
       action = 'AuthorizeSecurityGroupIngress'
       params = {
         'Action'    => action,
         'GroupName' => group_name
       }
-      params['SourceSecurityGroupName'] = options[:source_security_group_name] unless options[:source_security_group_name].nil?
-      params['SourceSecurityGroupOwnerId'] = options[:source_security_group_owner_id] unless options[:source_security_group_owner_id].nil?
-      params['IpProtocol'] = options[:ip_protocol] unless options[:ip_protocol].nil?
-      params['FromPort'] = options[:from_port] unless options[:from_port].nil?
-      params['ToPort'] = options[:to_port] unless options[:to_port].nil?
-      params['CidrIp'] = options[:cidr_ip] unless options[:cidr_ip].nil?
+      params.merge!(array_to_params(arguments, 'IpPermissions'))
 
       response = send_query_request(params)
       response.is_a?(Net::HTTPSuccess)
@@ -614,39 +656,21 @@ module Awsum
 
     # Revoke access on a specific SecurityGroup
     #
-    # ===Options:
+    # ===Usage
     # ====User/Group access
-    # * <tt>:source_security_group_name</tt> - Name of the security group to authorize access to when operating on a user/group pair
-    # * <tt>:source_security_group_owner_id</tt> - Owner of the security group to authorize access to when operating on a user/group pair
+    # ec2.revoke_security_group_ingress('security_group', {:ip_protocol => :tcp, :from_port => 80, :to_port => 80, :groups => [{:group_name => :revoked_group}]})
     # ====CIDR IP access
-    # * <tt>:ip_protocol</tt> - IP protocol to authorize access to when operating on a CIDR IP (tcp, udp or icmp) (default: tcp)
-    # * <tt>:from_port</tt> - Bottom of port range to authorize access to when operating on a CIDR IP. This contains the ICMP type if ICMP is being authorized.
-    # * <tt>:to_port</tt> - Top of port range to authorize access to when operating on a CIDR IP. This contains the ICMP type if ICMP is being authorized.
-    # * <tt>:cidr_ip</tt> - CIDR IP range to authorize access to when operating on a CIDR IP. (default: 0.0.0.0/0)
-    def revoke_security_group_ingress(group_name, options = {})
-      got_at_least_one_user_group_option = !options[:source_security_group_name].nil? || !options[:source_security_group_owner_id].nil?
-      got_user_group_options = !options[:source_security_group_name].nil? && !options[:source_security_group_owner_id].nil?
-      got_at_least_one_cidr_option = !options[:ip_protocol].nil? || !options[:from_port].nil? || !options[:to_port].nil? || !options[:cidr_ip].nil?
-      #Add in defaults
-      options = {:cidr_ip => '0.0.0.0/0'}.merge(options) if got_at_least_one_cidr_option
-      options = {:ip_protocol => 'tcp'}.merge(options) if got_at_least_one_cidr_option
-      got_cidr_options = !options[:ip_protocol].nil? && !options[:from_port].nil? && !options[:to_port].nil? && !options[:cidr_ip].nil?
-      raise ArgumentError.new('Can only authorize user/group or CIDR IP, not both') if got_at_least_one_user_group_option && got_at_least_one_cidr_option
-      raise ArgumentError.new('Need all user/group options when revoking user/group access') if got_at_least_one_user_group_option && !got_user_group_options
-      raise ArgumentError.new('Need all CIDR IP options when revoking CIDR IP access') if got_at_least_one_cidr_option && !got_cidr_options
-      raise ArgumentError.new('ip_protocol can only be one of tcp, udp or icmp') if got_at_least_one_cidr_option && !%w(tcp udp icmp).detect{|p| p == options[:ip_protocol] }
+    # ec2.revoke_security_group_ingress('security_group', {:ip_protocol => :tcp, :from_port => 80, :to_port => 80, :ip_ranges => [{:cidr_ip => '0.0.0.0/0'}]})
+    def revoke_security_group_ingress(group_name, arguments)
+      raise ArgumentError.new('Can only authorize user/group or CIDR IP, not both') if [arguments].flatten.detect{|a| a.has_key?(:ip_ranges) && a.has_key?(:groups)}
+      raise ArgumentError.new('ip_protocol can only be one of tcp, udp or icmp') if [arguments].flatten.detect{|a| !%w(tcp udp icmp).detect{|p| p == a[:ip_protocol].to_s } }
 
       action = 'RevokeSecurityGroupIngress'
       params = {
         'Action'    => action,
         'GroupName' => group_name
       }
-      params['SourceSecurityGroupName'] = options[:source_security_group_name] unless options[:source_security_group_name].nil?
-      params['SourceSecurityGroupOwnerId'] = options[:source_security_group_owner_id] unless options[:source_security_group_owner_id].nil?
-      params['IpProtocol'] = options[:ip_protocol] unless options[:ip_protocol].nil?
-      params['FromPort'] = options[:from_port] unless options[:from_port].nil?
-      params['ToPort'] = options[:to_port] unless options[:to_port].nil?
-      params['CidrIp'] = options[:cidr_ip] unless options[:cidr_ip].nil?
+      params.merge!(array_to_params(arguments, 'IpPermissions'))
 
       response = send_query_request(params)
       response.is_a?(Net::HTTPSuccess)
@@ -686,29 +710,22 @@ module Awsum
     # Purchase reserved instances
     #
     # ===Options:
-    # * <tt>:reserved_instances_offering_ids</tt> - A single reserved instance offering id (or an array of instance ids)
-    # * <tt>:instance_counts</tt> - A number of reserved instances to purchase (or an array of counts per instance in the reserved_instances_offering_ids array)
+    # * <tt>:reserved_instances_offering_id</tt> - A single reserved instance offering id
+    # * <tt>:instance_count</tt> - A number of reserved instances to purchase
     #
     # ===Example
     #  ec2.purchase_reserved_instances_offering('reservation-123456', 1)
-    #  or
-    #  ec2.purchase_reserved_instances_offering(['reservation-123456', 'reservation-654321'], [1, 2])
-    def purchase_reserved_instances_offering(reserved_instances_offering_ids, instance_counts = 1)
+    def purchase_reserved_instances_offering(reserved_instances_offering_id, instance_count = 1)
       action = 'PurchaseReservedInstancesOffering'
       params = {
         'Action'        => action,
       }
-      params.merge!(array_to_params([instance_counts].flatten, 'InstanceCount'))
-      params.merge!(array_to_params([reserved_instances_offering_ids].flatten, 'ReservedInstancesOfferingId'))
+      params['ReservedInstancesOfferingId'] = reserved_instances_offering_id
+      params['InstanceCount']               = instance_count
 
       response = send_query_request(params)
       parser = Awsum::Ec2::PurchaseReservedInstancesOfferingParser.new(self)
       result = parser.parse(response.body)
-      if reserved_instances_offering_ids.is_a?(Array)
-        reserved_instances(*result)
-      else
-        reserved_instance(result)
-      end
     end
 
     def reserved_instances(*reserved_instances_ids)