skippy-amazon-ec2 0.0.2

data/lib/EC2/responses.rb

@@ -0,0 +1,175 @@
+#--
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:grempe@rubyforge.org)
+# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
+# License::   Distributes under the same terms as Ruby
+# Home::      http://amazon-ec2.rubyforge.org
+#++
+
+module EC2
+
+  # The make_request() and ec2_error? methods, which are shared by all, will raise any
+  # exceptions encountered along the way as it converses with EC2.
+  #
+  # Exception Handling: If for some reason an error occurrs when executing a method
+  # (e.g. its arguments were incorrect, or it simply failed) then an exception will
+  # be thrown.  The exceptions are defined in exceptions.rb as individual classes and should
+  # match the exceptions that Amazon has defined for EC2.  If the exception raised cannot be
+  # identified then a more generic exception class will be thrown.
+  #
+  # The implication of this is that you need to be prepared to handle any exceptions that
+  # may be raised by this library in YOUR code with a 'rescue' clauses.  It is up to you
+  # how gracefully you want to handle these exceptions that are raised.
+
+  # Credits :
+  # I learned the magic of making an OpenStruct object able to respond as a fully Enumerable
+  # object (responds to .each, etc.) thanks to a great blog article on Struct and OpenStruct
+  # at http://errtheblog.com/post/30
+  #
+  # Thanks to Sean Knapp for the XmlSimple response patch which greatly simplified the response
+  # mechanism for the whole library while making it more accurate and much less brittle to boot!
+  #
+
+  require 'rubygems'
+  begin
+    require 'xmlsimple' unless defined? XmlSimple
+  rescue Exception => e
+    require 'xml-simple' unless defined? XmlSimple
+  end
+
+
+  class Response < OpenStruct
+
+    include Enumerable
+
+
+    def self.parse(options = {})
+      options = {
+        :xml => "",
+        :parse_options => { 'ForceArray' => ['item'], 'SuppressEmpty' => nil }
+      }.merge(options)
+      response = Response.new(XmlSimple.xml_in(options[:xml], options[:parse_options]))
+
+      # set the xml attribute of the response object to contain the original XML that was
+      # returned by amazon.  This allows anyone to bypass our parsing if desired and just
+      # get right at the raw XML response.
+      response.xml = options[:xml]
+      return response
+    end
+
+
+    # Every member of an OpenStruct object has getters and setters, the latter of which
+    # has a method ending in "=". Find all of these methods, excluding those defined on
+    # parent classes.
+    def members
+      methods(false).sort.grep(/=/).map { |m| m[0...-1] }
+    end
+
+
+    # Required by the Enumerable module. Iterate over each item in the members array
+    # and pass as a value the block passed to each using yield.
+    def each
+      members.each do |method|
+        yield send(method)
+      end
+      self
+    end
+
+
+    # Same as the each method, but with both key and value.
+    #
+    #Sample Use:
+    # obj.each_pair { |k,v| puts "key: #{k}, value: #{v}" }
+    def each_pair
+      members.each do |method|
+        yield method, send(method)
+      end
+      self
+    end
+
+
+    # Alternative method for getting members.
+    def [](member)
+      send(member)
+    end
+
+
+    # Alternative method for setting members.
+    def []=(member, value)
+      send("#{member}=", value)
+    end
+
+
+    # Helper for converting to string which support a long and short version
+    # to avoid recursion problems with parents.
+    def to_string(short=false)
+      s = "#<#{self.class}:0x#{(2 ** 32 + object_id).to_s(16).upcase}"
+      if (short)
+        s += " ..."
+      else
+        each_pair { |k,v|
+          if (v == self.parent && v.kind_of?(Response))
+            v = v.to_string(true)
+          elsif (v.kind_of?(String))
+            v = "\"#{v.gsub("\"", "\\\"")}\""
+          elsif (v.kind_of?(NilClass))
+            v = "nil"
+          end
+          s += " #{k}=#{v}"
+        }
+      end
+      s += ">"
+      return s
+    end
+
+
+    # Override of to string method.
+    def to_s
+      return to_string
+    end
+
+
+    private
+
+    # Initialize the object by passing data to the OpenStruct initialize method
+    # and then converting ourself to guarantee we have top-to-bottom data
+    # representation as a Response object.
+    def initialize(data, parent=nil)
+      super(data)
+      self.parent = parent
+      Response.convert(self, parent)
+    end
+
+
+    # The "brains" of our Response class. This method takes an arbitray object and
+    # depending on its class attempts to convert it.
+    def self.convert(obj, parent)
+      if (obj.kind_of?(Response))
+        # Recursively convert the object.
+        obj.each_pair { |k,v|
+          if (v != obj.parent)
+            obj[k] = convert(v, obj)
+          end
+        }
+        return obj
+      elsif (obj.kind_of?(Hash))
+        # Hashes make good Responses already thanks to OpenStruct.
+        return Response.new(obj, parent)
+      elsif (obj.kind_of?(Array))
+        # With arrays, make sure each element is appropriately converted.
+        new_arr = []
+        obj.each { |elem|
+          new_arr << convert(elem, parent)
+        }
+        return new_arr
+      else
+        # At this point we're out of ideas, so let's hope it is a string.
+        return obj
+      end
+    end
+
+  end  # class Response < OpenStruct
+
+end  # module EC2

data/lib/EC2/security_groups.rb

@@ -0,0 +1,232 @@
+#--
+# Amazon Web Services EC2 Query API Ruby library
+#
+# Ruby Gem Name::  amazon-ec2
+# Author::    Glenn Rempe  (mailto:grempe@rubyforge.org)
+# Copyright:: Copyright (c) 2007-2008 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 CreateSecurityGroup operation creates a new security group. Every instance is launched
+    # in a security group. If none is specified as part of the launch request then instances
+    # are launched in the default security group. Instances within the same security group have
+    # unrestricted network access to one another. Instances will reject network access attempts from other
+    # instances in a different security group. As the owner of instances you may grant or revoke specific
+    # permissions using the AuthorizeSecurityGroupIngress and RevokeSecurityGroupIngress operations.
+    #
+    #Required Arguments:
+    #
+    # :group_name => String (default : "")
+    # :group_description => String (default : "")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def create_security_group( options = {} )
+
+      options = {:group_name => "",
+                 :group_description => ""
+                 }.merge(options)
+
+      raise ArgumentError, "No :group_name provided" if options[:group_name].nil? || options[:group_name].empty?
+      raise ArgumentError, "No :group_description provided" if options[:group_description].nil? || options[:group_description].empty?
+
+      params = {
+        "GroupName" => options[:group_name],
+        "GroupDescription" => options[:group_description]
+      }
+
+      return response_generator(:action => "CreateSecurityGroup", :params => params)
+
+    end
+
+
+    #Amazon Developer Guide Docs:
+    #
+    # The DescribeSecurityGroups operation returns information about security groups owned by the
+    # user making the request.
+    #
+    # An optional list of security group names may be provided to request information for those security
+    # groups only. If no security group names are provided, information of all security groups will be
+    # returned. If a group is specified that does not exist a fault is returned.
+    #
+    #Required Arguments:
+    #
+    # none
+    #
+    #Optional Arguments:
+    #
+    # :group_name => Array (default : [])
+    #
+    def describe_security_groups( options = {} )
+
+      options = { :group_name => [] }.merge(options)
+
+      params = pathlist("GroupName", options[:group_name] )
+
+      return response_generator(:action => "DescribeSecurityGroups", :params => params)
+
+    end
+
+
+    #Amazon Developer Guide Docs:
+    #
+    # The DeleteSecurityGroup operation deletes a security group.
+    #
+    # If an attempt is made to delete a security group and any instances exist that are members of that group a
+    # fault is returned.
+    #
+    #Required Arguments:
+    #
+    # :group_name => String (default : "")
+    #
+    #Optional Arguments:
+    #
+    # none
+    #
+    def delete_security_group( options = {} )
+
+      options = { :group_name => "" }.merge(options)
+
+      raise ArgumentError, "No :group_name provided" if options[:group_name].nil? || options[:group_name].empty?
+
+      params = { "GroupName" => options[:group_name] }
+
+      return response_generator(:action => "DeleteSecurityGroup", :params => params)
+
+    end
+
+
+    #Amazon Developer Guide Docs:
+    #
+    # The AuthorizeSecurityGroupIngress operation adds permissions to a security group.
+    #
+    # Permissions are specified in terms of the IP protocol (TCP, UDP or ICMP), the source of the request (by
+    # IP range or an Amazon EC2 user-group pair), source and destination port ranges (for TCP and UDP),
+    # and ICMP codes and types (for ICMP). When authorizing ICMP, -1 may be used as a wildcard in the
+    # type and code fields.
+    #
+    # Permission changes are propagated to instances within the security group being modified as quickly as
+    # possible. However, a small delay is likely, depending on the number of instances that are members of
+    # the indicated group.
+    #
+    # When authorizing a user/group pair permission, GroupName, SourceSecurityGroupName and
+    # SourceSecurityGroupOwnerId must be specified. When authorizing a CIDR IP permission,
+    # GroupName, IpProtocol, FromPort, ToPort and CidrIp must be specified. Mixing these two types
+    # of parameters is not allowed.
+    #
+    #Required Arguments:
+    #
+    # :group_name => String (default : "")
+    #
+    #Optional Arguments:
+    #
+    # :ip_protocol => String (default : nil) : Required when authorizing CIDR IP permission
+    # :from_port => Integer (default : nil) : Required when authorizing CIDR IP permission
+    # :to_port => Integer (default : nil) : Required when authorizing CIDR IP permission
+    # :cidr_ip => String (default : nil): Required when authorizing CIDR IP permission
+    # :source_security_group_name => String (default : nil) : Required when authorizing user group pair permissions
+    # :source_security_group_owner_id => String (default : nil) : Required when authorizing user group pair permissions
+    #
+    def authorize_security_group_ingress( options = {} )
+
+      # defaults
+      options = { :group_name => nil,
+                  :ip_protocol => nil,
+                  :from_port => nil,
+                  :to_port => nil,
+                  :cidr_ip => nil,
+                  :source_security_group_name => nil,
+                  :source_security_group_owner_id => nil }.merge(options)
+
+      # lets not validate the rest of the possible permutations of required params and instead let
+      # EC2 sort it out on the server side.  We'll only require :group_name as that is always needed.
+      raise ArgumentError, "No :group_name provided" if options[:group_name].nil? || options[:group_name].empty?
+
+      params = { "GroupName" => options[:group_name],
+                 "IpProtocol" => options[:ip_protocol],
+                 "FromPort" => options[:from_port].to_s,
+                 "ToPort" => options[:to_port].to_s,
+                 "CidrIp" => options[:cidr_ip],
+                 "SourceSecurityGroupName" => options[:source_security_group_name],
+                 "SourceSecurityGroupOwnerId" => options[:source_security_group_owner_id]
+                 }
+
+      return response_generator(:action => "AuthorizeSecurityGroupIngress", :params => params)
+
+    end
+
+
+    #Amazon Developer Guide Docs:
+    #
+    # The RevokeSecurityGroupIngress operation revokes existing permissions that were previously
+    # granted to a security group. The permissions to revoke must be specified using the same values
+    # originally used to grant the permission.
+    #
+    # Permissions are specified in terms of the IP protocol (TCP, UDP or ICMP), the source of the request (by
+    # IP range or an Amazon EC2 user-group pair), source and destination port ranges (for TCP and UDP),
+    # and ICMP codes and types (for ICMP). When authorizing ICMP, -1 may be used as a wildcard in the
+    # type and code fields.
+    #
+    # Permission changes are propagated to instances within the security group being modified as quickly as
+    # possible. However, a small delay is likely, depending on the number of instances that are members of
+    # the indicated group.
+    #
+    # When revoking a user/group pair permission, GroupName, SourceSecurityGroupName and
+    # SourceSecurityGroupOwnerId must be specified. When authorizing a CIDR IP permission,
+    # GroupName, IpProtocol, FromPort, ToPort and CidrIp must be specified. Mixing these two types
+    # of parameters is not allowed.
+    #
+    #Required Arguments:
+    #
+    # :group_name => String (default : "")
+    #
+    #Optional Arguments:
+    #
+    # :ip_protocol => String (default : nil) : Required when revoking CIDR IP permission
+    # :from_port => Integer (default : nil) : Required when revoking CIDR IP permission
+    # :to_port => Integer (default : nil) : Required when revoking CIDR IP permission
+    # :cidr_ip => String (default : nil): Required when revoking CIDR IP permission
+    # :source_security_group_name => String (default : nil) : Required when revoking user group pair permissions
+    # :source_security_group_owner_id => String (default : nil) : Required when revoking user group pair permissions
+    #
+    def revoke_security_group_ingress( options = {} )
+
+      # defaults
+      options = { :group_name => nil,
+                  :ip_protocol => nil,
+                  :from_port => nil,
+                  :to_port => nil,
+                  :cidr_ip => nil,
+                  :source_security_group_name => nil,
+                  :source_security_group_owner_id => nil }.merge(options)
+
+      # lets not validate the rest of the possible permutations of required params and instead let
+      # EC2 sort it out on the server side.  We'll only require :group_name as that is always needed.
+      raise ArgumentError, "No :group_name provided" if options[:group_name].nil? || options[:group_name].empty?
+
+      params = { "GroupName" => options[:group_name],
+                 "IpProtocol" => options[:ip_protocol],
+                 "FromPort" => options[:from_port].to_s,
+                 "ToPort" => options[:to_port].to_s,
+                 "CidrIp" => options[:cidr_ip],
+                 "SourceSecurityGroupName" => options[:source_security_group_name],
+                 "SourceSecurityGroupOwnerId" => options[:source_security_group_owner_id]
+                 }
+
+      return response_generator(:action => "RevokeSecurityGroupIngress", :params => params)
+
+    end
+
+  end
+
+end

data/lib/EC2/snapshots.rb

@@ -0,0 +1,30 @@
+module EC2
+
+  class Base
+    def create_snapshot( options = {} )
+      options = { :volume_id => '' }.merge(options)
+      raise ArgumentError, "No ':volume_id' provided" if options[:volume_id].nil? || options[:volume_id].empty?
+
+      params = { "VolumeId" => options[:volume_id] }
+      return response_generator(:action => "CreateSnapshot", :params => params)      
+    end
+
+    def describe_snapshots( options = {} )
+      options = { :snapshot_id => [] }.merge(options)
+      params = pathlist("SnapshotId", options[:snapshot_id])
+
+      return response_generator(:action => "DescribeSnapshots", :params => params)
+    end
+
+    def delete_snapshot( options = {} )
+      options = { :snapshot_id => '' }.merge(options)
+      raise ArgumentError, "No ':snapshot_id' provided" if options[:snapshot_id].nil? || options[:snapshot_id].empty?
+
+      params = { "SnapshotId" => options[:snapshot_id] }
+      return response_generator(:action => "DeleteSnapshot", :params => params)      
+    end
+    
+    
+  end
+
+end

data/lib/EC2/volumes.rb

@@ -0,0 +1,39 @@
+module EC2
+
+  class Base
+
+    def describe_volumes( options = {} )
+      options = { :volume_id => [] }.merge(options)
+      params = pathlist("VolumeId", options[:volume_id])
+
+      return response_generator(:action => "DescribeVolumes", :params => params)
+    end
+
+    def attach_volumes( options = {} )
+      options = { :volume_id => '', :instance_id => '' }.merge(options)
+      raise ArgumentError, "No ':volume_id' provided" if options[:volume_id].nil? || options[:volume_id].empty?
+      raise ArgumentError, "No ':instance_id' provided" if options[:instance_id].nil? || options[:instance_id].empty?
+
+      params = { "VolumeId" => options[:volume_id], "InstanceId" => options[:instance_id] }
+      return response_generator(:action => "AttachVolume", :params => params)
+    end
+
+    def delete_volume( options = {} )
+      options = { :volume_id => '' }.merge(options)
+      raise ArgumentError, "No ':volume_id' provided" if options[:volume_id].nil? || options[:v].empty?
+
+      params = { "VolumeId" => options[:volume_id] }
+      return response_generator(:action => "DeleteVolume", :params => params)      
+    end
+    
+    def detach_volumes( options = {} )
+      options = { :volume_id => '', :instance_id => '', :device => '', :force => false }.merge(options)
+      raise ArgumentError, "No ':volume_id' provided" if options[:volume_id].nil? || options[:volume_id].empty?
+
+      params = { "VolumeId" => options[:volume_id], "InstanceId" => options[:instance_id], 'Device' => options[:device], 'Force' => options[:force] }
+      return response_generator(:action => "DetachVolume", :params => params)
+    end
+
+  end
+
+end