amazon-ec2 0.1.0 → 0.2.0

data/lib/EC2/console.rb

@@ -0,0 +1,44 @@
+#--
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:glenn@elasticworkbench.com)
+# Copyright:: Copyright (c) 2007 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://amazon-ec2.rubyforge.org
+#++
+
+module EC2
+  
+  class Base
+    
+    #Amazon Developer Guide Docs:
+    #  
+    # The GetConsoleOutput operation retrieves console output that has been posted for the specified instance.
+    #
+    # Instance console output is buffered and posted shortly after instance boot, reboot and once the instance 
+    # is terminated. Only the most recent 64 KB of posted output is available. Console output is available for 
+    # at least 1 hour after the most recent post.
+    #
+    #Required Arguments:
+    #
+    # :instance_id => String (default : "")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def get_console_output( options ={} )
+      
+      options = {:instance_id => ""}.merge(options)
+      
+      raise ArgumentError, "No instance ID provided" if options[:instance_id].nil? || options[:instance_id].empty?
+      
+      params = { "InstanceId" => options[:instance_id] }
+      
+      return response_generator(:action => "GetConsoleOutput", :params => params)
+      
+    end
+  end
+  
+end

data/lib/EC2/exceptions.rb

@@ -0,0 +1,136 @@
+#--
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:glenn@elasticworkbench.com)
+# Copyright:: Copyright (c) 2007 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://amazon-ec2.rubyforge.org
+#++
+
+module EC2
+  
+  # OUR CUSTOM ERROR CODES
+  
+  # All of our errors are superclassed by Error < RuntimeError
+  class Error < RuntimeError #:nodoc:
+  end
+  
+  # A client side only argument error
+  class ArgumentError < Error #:nodoc:
+  end
+  
+  
+  # AWS EC2 CLIENT ERROR CODES
+  
+  # AWS EC2 can throw error exceptions that contain a '.' in them.
+  # since we can't name an exception class with that '.' I compressed
+  # each class name into the non-dot version.  This allows us to retain
+  # the granularity of the exception.
+  
+  # User not authorized.
+  class AuthFailure < Error #:nodoc:
+  end
+  
+  # Specified AMI has an unparsable manifest.
+  class InvalidManifest < Error #:nodoc:
+  end
+  
+  # Specified AMI ID is not valid.
+  class InvalidAMIIDMalformed < Error #:nodoc:
+  end
+  
+  # Specified AMI ID does not exist.
+  class InvalidAMIIDNotFound < Error #:nodoc:
+  end
+  
+  # Specified AMI ID has been deregistered and is no longer available.
+  class InvalidAMIIDUnavailable < Error #:nodoc:
+  end
+  
+  # Specified instance ID is not valid.
+  class InvalidInstanceIDMalformed < Error #:nodoc:
+  end
+  
+  # Specified instance ID does not exist.
+  class InvalidInstanceIDNotFound < Error #:nodoc:
+  end
+  
+  # Specified keypair name does not exist.
+  class InvalidKeyPairNotFound < Error #:nodoc:
+  end
+  
+  # Attempt to create a duplicate keypair.
+  class InvalidKeyPairDuplicate < Error #:nodoc:
+  end
+  
+  # Specified group name does not exist.
+  class InvalidGroupNotFound < Error #:nodoc:
+  end
+  
+  # Attempt to create a duplicate group.
+  class InvalidGroupDuplicate < Error #:nodoc:
+  end
+  
+  # Specified group can not be deleted because it is in use.
+  class InvalidGroupInUse < Error #:nodoc:
+  end
+  
+  # Specified group name is a reserved name.
+  class InvalidGroupReserved < Error #:nodoc:
+  end
+  
+  # Attempt to authorize a permission that has already been authorized.
+  class InvalidPermissionDuplicate < Error #:nodoc:
+  end
+  
+  # Specified permission is invalid.
+  class InvalidPermissionMalformed < Error #:nodoc:
+  end
+  
+  # Specified reservation ID is invalid.
+  class InvalidReservationIDMalformed < Error #:nodoc:
+  end
+  
+  # Specified reservation ID does not exist.
+  class InvalidReservationIDNotFound < Error #:nodoc:
+  end
+  
+  # User has reached max allowed concurrent running instances.
+  class InstanceLimitExceeded < Error #:nodoc:
+  end
+  
+  # An invalid set of parameters were passed as arguments
+  # e.g. RunInstances was called with minCount and maxCount set to 0 or minCount > maxCount.
+  class InvalidParameterCombination < Error #:nodoc:
+  end
+  
+  # An unknown parameter was passed as an argument
+  class UnknownParameter < Error #:nodoc:
+  end
+  
+  # The user ID is neither in the form of an AWS account ID or one 
+  # of the special values accepted by the owner or executableBy flags 
+  # in the DescribeImages call.
+  class InvalidUserIDMalformed < Error #:nodoc:
+  end
+  
+  # The value of an item added to, or removed from, an image attribute is invalid.
+  class InvalidAMIAttributeItemValue < Error #:nodoc:
+  end
+  
+  # AWS EC2 SERVER ERROR CODES
+  
+  # Internal AWS EC2 Error.
+  class InternalError < Error #:nodoc:
+  end
+  
+  # There are not enough available instances to satify your minimum request.
+  class InsufficientInstanceCapacity < Error #:nodoc:
+  end
+  
+  # The server is overloaded and cannot handle request.
+  class Unavailable < Error #:nodoc:
+  end
+  
+end

data/lib/EC2/image_attributes.rb

@@ -1,45 +1,153 @@
-# Amazon Web Services EC2 Query API Ruby Library
-# This library has been packaged as a Ruby Gem 
-# by Glenn Rempe ( grempe @nospam@ rubyforge.org ).
-# 
-# Source code and gem hosted on RubyForge
-# under the Ruby License as of 12/14/2006:
-# http://amazon-ec2.rubyforge.org
+#--
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:glenn@elasticworkbench.com)
+# Copyright:: Copyright (c) 2007 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://amazon-ec2.rubyforge.org
+#++
 
 module EC2
   
-  class AWSAuthConnection
+  class Base
     
-    # The ModifyImageAttribute operation modifies an attribute of an AMI.
-    #
-    # Currently the only attribute supported is launchPermission. By 
-    # modifying this attribute it is possible to make an AMI public or 
-    # to grant specific users launch permissions for the AMI. To make the 
-    # AMI public add the group=all attribute item. To grant launch permissions 
-    # for a specific user add a userId=<userid> attribute item.
-    def modify_image_attribute(imageId, attribute, operationType, attributeValueHash)
+    #Amazon Developer Guide Docs:
+    #  
+    # The ModifyImageAttribute operation modifies an attribute of an AMI. 
+    # Currently the only attribute supported is launchPermission. By modifying this attribute it is possible to 
+    # make an AMI public or to grant specific users launch permissions for the AMI. To make the AMI public 
+    # add the group=all attribute item. To grant launch permissions for a specific user add a 
+    # userId=<userid> attribute item.
+    #
+    #Required Arguments:
+    #
+    # :image_id => String (default : "")
+    # :attribute => String (default : "launchPermission")
+    # :operation_type => String (default : "add")
+    #
+    #Optional Arguments:
+    #
+    # :user_id => Array (default : [])
+    # :group => Array (default : [])
+    #
+    def modify_image_attribute( options = {} )
+      
+      # defaults
+      options = { :image_id => "", 
+                  :attribute => "launchPermission", 
+                  :operation_type => "add", 
+                  :user_id => [], 
+                  :group => [] }.merge(options)
+      
+      raise ArgumentError, "No ':image_id' provided" if options[:image_id].nil? || options[:image_id].empty?
+      raise ArgumentError, "No ':attribute' provided" if options[:attribute].nil? || options[:attribute].empty?
+      raise ArgumentError, "No ':operation_type' provided" if options[:operation_type].nil? || options[:operation_type].empty?
+      
       params = {
-        "ImageId" => imageId,
-        "Attribute" => attribute,
-        "OperationType" => operationType
+        "ImageId" => options[:image_id],
+        "Attribute" => options[:attribute],
+        "OperationType" => options[:operation_type]
       }
-      if attribute == "launchPermission"
-        params.merge!(pathlist("UserGroup", attributeValueHash[:userGroups])) if attributeValueHash.has_key? :userGroups
-        params.merge!(pathlist("UserId", attributeValueHash[:userIds])) if attributeValueHash.has_key? :userIds
+      
+      # test options provided and make sure they are valid
+      case options[:attribute]
+      when "launchPermission"
+        if (options[:user_id].nil? || options[:user_id].empty?) && (options[:group].nil? || options[:group].empty?)
+          raise ArgumentError, "Option :attribute=>'launchPermission' requires ':user_id' or ':group' options to also be specified"
+        end
+        
+        params.merge!(pathlist("UserId", options[:user_id])) unless options[:user_id].nil?
+        params.merge!(pathlist("Group", options[:group])) unless options[:group].nil?
+      else
+        raise ArgumentError, "attribute : #{options[:attribute].to_s} is not an known option."
+      end
+      
+      # test options provided and make sure they are valid
+      case options[:operation_type]
+      when "add", "remove"
+        # these args are ok
+      else
+        raise ArgumentError, ":operation_type was #{options[:operation_type].to_s} but must be 'add' or 'remove'"
       end
-      ModifyImageAttributeResponse.new(make_request("ModifyImageAttribute", params))
+      
+      return response_generator(:action => "ModifyImageAttribute", :params => params)
+      
     end
     
+    #Amazon Developer Guide Docs:
+    #
     # The DescribeImageAttribute operation returns information about an attribute of an AMI.
-    def describe_image_attribute(imageId, attribute)
-      params = { "ImageId" => imageId, "Attribute" => attribute }
-      DescribeImageAttributeResponse.new(make_request("DescribeImageAttribute", params))
+    #
+    #Required Arguments:
+    #
+    # :image_id => String (default : "")
+    # :attribute => String (default : "launchPermission")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def describe_image_attribute( options = {} )
+      
+      # defaults
+      options = {:image_id => "", 
+                 :attribute => "launchPermission"
+                 }.merge(options)
+      
+      raise ArgumentError, "No ':image_id' provided" if options[:image_id].nil? || options[:image_id].empty?
+      raise ArgumentError, "No ':attribute' provided" if options[:attribute].nil? || options[:attribute].empty?
+      
+      params = { "ImageId" => options[:image_id], "Attribute" => options[:attribute] }
+      
+      # test options provided and make sure they are valid
+      case options[:attribute]
+      when "launchPermission"
+        # these args are ok
+      else
+        raise ArgumentError, "attribute : #{options[:attribute].to_s} is not an known option."
+      end
+      
+      return response_generator(:action => "DescribeImageAttribute", :params => params)
+      
     end
     
+    
+    #Amazon Developer Guide Docs:
+    #
     # The ResetImageAttribute operation resets an attribute of an AMI to its default value.
-    def reset_image_attribute(imageId, attribute)
-      params = { "ImageId" => imageId, "Attribute" => attribute }
-      ResetImageAttributeResponse.new(make_request("ResetImageAttribute", params))
+    #
+    #Required Arguments:
+    #
+    # :image_id => String (default : "")
+    # :attribute => String (default : "launchPermission")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def reset_image_attribute( options = {} )
+      
+      # defaults
+      options = {:image_id => "",
+                 :attribute => "launchPermission"}.merge(options)
+      
+      raise ArgumentError, "No ':image_id' provided" if options[:image_id].nil? || options[:image_id].empty?
+      raise ArgumentError, "No ':attribute' provided" if options[:attribute].nil? || options[:attribute].empty?
+      
+      params = {"ImageId" => options[:image_id], 
+                "Attribute" => options[:attribute] }
+      
+      # test options provided and make sure they are valid
+      case options[:attribute]
+      when "launchPermission"
+        # these args are ok
+      else
+        raise ArgumentError, "attribute : #{options[:attribute].to_s} is not an known option."
+      end
+      
+      return response_generator(:action => "ResetImageAttribute", :params => params)
+      
     end
     
   end

data/lib/EC2/images.rb

@@ -1,85 +1,132 @@
-# Amazon Web Services EC2 Query API Ruby Library
-# This library has been packaged as a Ruby Gem 
-# by Glenn Rempe ( grempe @nospam@ rubyforge.org ).
-# 
-# Source code and gem hosted on RubyForge
-# under the Ruby License as of 12/14/2006:
-# http://amazon-ec2.rubyforge.org
+#--
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:glenn@elasticworkbench.com)
+# Copyright:: Copyright (c) 2007 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://amazon-ec2.rubyforge.org
+#++
 
 module EC2
   
-  class AWSAuthConnection
+  class Base
     
-    # The RegisterImage operation registers an AMI with Amazon EC2. 
-    # Images must be registered before they can be launched.  Each 
-    # AMI is associated with an unique ID which is provided by the 
-    # EC2 service via the Registerimage operation. As part of the 
-    # registration process, Amazon EC2 will retrieve the specified 
-    # image manifest from Amazon S3 and verify that the image is 
-    # owned by the user requesting image registration.  The image 
-    # manifest is retrieved once and stored within the Amazon EC2 
-    # network. Any modifications to an image in Amazon S3 invalidate 
-    # this registration. If you do have to make changes and upload 
-    # a new image deregister the previous image and register the new image.
-    def register_image(imageLocation)
-      params = { "ImageLocation" => imageLocation }
-      RegisterImageResponse.new(make_request("RegisterImage", params))
+    #Amazon Developer Guide Docs:
+    #
+    # The RegisterImage operation registers an AMI with Amazon EC2. Images must be registered before 
+    # they can be launched.  Each AMI is associated with an unique ID which is provided by the EC2 
+    # service via the Registerimage operation. As part of the registration process, Amazon EC2 will 
+    # retrieve the specified image manifest from Amazon S3 and verify that the image is owned by the 
+    # user requesting image registration.  The image manifest is retrieved once and stored within the 
+    # Amazon EC2 network. Any modifications to an image in Amazon S3 invalidate this registration. 
+    # If you do have to make changes and upload a new image deregister the previous image and register 
+    # the new image.
+    #
+    #Required Arguments:
+    #
+    # :image_location => String (default : "")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def register_image( options = {} )
+      
+      options = {:image_location => ""}.merge(options)
+      
+      raise ArgumentError, "No :image_location provided" if options[:image_location].nil? || options[:image_location].empty?
+      
+      params = { "ImageLocation" => options[:image_location] }
+      
+      return response_generator(:action => "RegisterImage", :params => params)
+      
     end
     
-    # The DescribeImages operation returns information about AMIs available 
-    # for use by the user. This includes both public AMIs (those available 
-    # for any user to launch) and private AMIs (those owned by the user 
-    # making the request and those owned by other users that the user 
-    # making the request has explicit launch permissions for).
-    #
-    # The list of AMIs returned can be modified via optional lists of AMI IDs, 
-    # owners or users with launch permissions. If all three optional lists 
-    # are empty all AMIs the user has launch permissions for are returned. 
-    # Launch permissions fall into three categories:
-    #
-    # Launch Permission	Description
-    #  * public	The all group has launch permissions for the AMI. All users have 
-    #    launch permissions for these AMIs.
-    #  * explicit	The owner of the AMIs has granted a specific user launch permissions for the AMI.
-    #  * implicit	A user has implicit launch permissions for all AMIs he or she owns.
-    #
-    # If one or more of the lists are specified the result set is the intersection 
-    # of AMIs matching the criteria of the individual lists.
-    #
-    # Providing the list of AMI IDs requests information for those AMIs only. 
-    # If no AMI IDs are provided, information of all relevant AMIs will be 
-    # returned. If an AMI is specified that does not exist a fault is returned. 
-    # If an AMI is specified that exists but the user making the request does 
-    # not have launch permissions for, then that AMI will not be included in 
-    # the returned results.
-    #
-    # Providing the list of owners requests information for AMIs owned 
-    # by the specified owners only. Only AMIs the user has launch permissions 
-    # for are returned. The items of the list may be account ids for AMIs 
-    # owned by users with those account ids, amazon for AMIs owned by Amazon 
-    # or self for AMIs owned by the user making the request.
+    #Amazon Developer Guide Docs:
+    #
+    # The DescribeImages operation returns information about AMIs available for use by the user. This 
+    # includes both public AMIs (those available for any user to launch) and private AMIs (those owned by 
+    # the user making the request and those owned by other users that the user making the request has explicit
+    # launch permissions for). 
+    # 
+    # The list of AMIs returned can be modified via optional lists of AMI IDs, owners or users with launch 
+    # permissions. If all three optional lists are empty all AMIs the user has launch permissions for are 
+    # returned. Launch permissions fall into three categories: 
+    # 
+    # Launch Permission Description
+    #
+    # public - The all group has launch permissions for the AMI. All users have launch permissions for these AMIs.
+    # explicit - The owner of the AMIs has granted a specific user launch permissions for the AMI.
+    # implicit - A user has implicit launch permissions for all AMIs he or she owns. 
+    # 
+    # If one or more of the lists are specified the result set is the intersection of AMIs matching the criteria of 
+    # the individual lists. 
+    # 
+    # Providing the list of AMI IDs requests information for those AMIs only. If no AMI IDs are provided, 
+    # information of all relevant AMIs will be returned. If an AMI is specified that does not exist a fault is 
+    # returned. If an AMI is specified that exists but the user making the request does not have launch 
+    # permissions for, then that AMI will not be included in the returned results. 
+    # 
+    # Providing the list of owners requests information for AMIs owned by the specified owners only. Only 
+    # AMIs the user has launch permissions for are returned. The items of the list may be account ids for 
+    # AMIs owned by users with those account ids, amazon for AMIs owned by Amazon or self for AMIs 
+    # owned by the user making the request. 
     # 
-    # The executable list may be provided to request information for AMIs 
-    # that only the specified users have launch permissions for. The items of 
-    # the list may be account ids for AMIs owned by the user making the request 
-    # that the users with the specified account ids have explicit launch permissions 
-    # for, self for AMIs the user making the request has explicit launch permissions 
-    # for or all for public AMIs.
-    #
-    # Deregistered images will be included in the returned results for an 
-    # unspecified interval subsequent to deregistration.
-    def describe_images(imageIds=[], owners=[], executableBy=[])
-      params = pathlist("ImageId", imageIds)
-      params.merge!(pathlist("Owner", owners))
-      params.merge!(pathlist("ExecutableBy", executableBy))
-      DescribeImagesResponse.new(make_request("DescribeImages", params))
+    # The executable list may be provided to request information for AMIs that only the specified users have 
+    # launch permissions for. The items of the list may be account ids for AMIs owned by the user making the 
+    # request that the users with the specified account ids have explicit launch permissions for, self for AMIs 
+    # the user making the request has explicit launch permissions for or all for public AMIs. 
+    # 
+    # Deregistered images will be included in the returned results for an unspecified interval subsequent to 
+    # deregistration. 
+    #
+    #Required Arguments:
+    #
+    # none
+    #
+    #Optional Arguments:
+    #
+    # :image_id => Array (default : [])
+    # :owner_id => Array (default : [])
+    # :executable_by => Array (default : [])
+    #
+    def describe_images( options = {} )
+      
+      options = { :image_id => [], :owner_id => [], :executable_by => [] }.merge(options)
+      
+      params = pathlist( "ImageId", options[:image_id] )
+      params.merge!(pathlist( "Owner", options[:owner_id] ))
+      params.merge!(pathlist( "ExecutableBy", options[:executable_by] ))
+      
+      return response_generator(:action => "DescribeImages", :params => params)
+      
     end
     
-    # The DeregisterImage operation deregisters an AMI. Once deregistered, 
-    # instances of the AMI may no longer be launched.
-    def deregister_image(imageId)
-      params = { "ImageId" => imageId }
-      DeregisterImageResponse.new(make_request("DeregisterImage", params))
+    #Amazon Developer Guide Docs:
+    #
+    # The DeregisterImage operation deregisters an AMI. Once deregistered, instances of the AMI may no 
+    # longer be launched.
+    #
+    #Required Arguments:
+    #
+    # :image_id => String (default : "")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def deregister_image( options = {} )
+      
+      # defaults
+      options = { :image_id => "" }.merge(options)
+      
+      raise ArgumentError, "No :image_id provided" if options[:image_id].nil? || options[:image_id].empty?
+      
+      params = { "ImageId" => options[:image_id] }
+      
+      return response_generator(:action => "DeregisterImage", :params => params)
+      
     end
     
   end