amazon-ec2 0.1.0 → 0.2.0

data/Rakefile

@@ -12,8 +12,8 @@ require 'hoe'
 include FileUtils
 require File.join(File.dirname(__FILE__), 'lib', 'EC2', 'version')
 
-AUTHOR = ["Amazon Web Services LLC", "Glenn Rempe"]  # can also be an array of Authors
-EMAIL = "grempe@rubyforge.org"
+AUTHOR = ["Glenn Rempe"]  # can also be an array of Authors
+EMAIL = "glenn@elasticworkbench.com"
 DESCRIPTION = "An interface library that allows Ruby or Ruby on Rails applications to easily connect to the HTTP 'Query API' for the Amazon Web Services Elastic Compute Cloud (EC2) and manipulate server instances."
 GEM_NAME = "amazon-ec2" # what ppl will type to install your gem
 
@@ -74,10 +74,13 @@ hoe = Hoe.new(GEM_NAME, VERS) do |p|
   
   # == Optional
   p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
-  #p.extra_deps = []     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
-  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  
+  # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
+  p.extra_deps = [['xml-simple', '>= 1.0.11'], ['mocha', '>= 0.4.0'], ['test-spec', '>= 0.3.0'], ['rcov', '>= 0.8.0.2'], ['syntax', '>= 1.0.0'], ['RedCloth', '>= 3.0.4']]
+  
+  # A hash of extra values to set in the gemspec.
   p.spec_extras = {
-    :extra_rdoc_files => ["README.txt", "History.txt"],
+    :extra_rdoc_files => ["README.txt", "History.txt", "License.txt"],
     :rdoc_options => RDOC_OPTS,
     :autorequire => "EC2"
   }
@@ -106,6 +109,9 @@ end
 desc 'Generate and upload website files'
 task :website => [:website_generate, :website_upload]
 
+desc 'Run all types of tests that we have defined'
+task :test_all => [:test, :test_deps, :test_coverage]
+
 desc 'Release the website and new gem version'
 task :deploy => [:check_version, :website, :release] do
   puts "Remember to create SVN tag:"
@@ -129,4 +135,8 @@ task :check_version do
   end
 end
 
+desc 'Runs RCOV and generates test coverage reports which are stored in coverage/ dir'
+task :test_coverage do
+  sh %{rcov -T test/*.rb}
+end
 

data/bin/ec2-gem-example.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+
+# 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
+#++
+
+require 'rubygems'
+require File.dirname(__FILE__) + '/../lib/EC2'
+
+# pull these from the local shell environment variables set in ~/.bash_login
+# or using appropriate methods specific to your login shell.
+# 
+# e.g. in ~/.bash_login
+# 
+#  # For amazon-ec2 and amazon s3 ruby gems
+#  export AMAZON_ACCESS_KEY_ID="FOO"
+#  export AMAZON_SECRET_ACCESS_KEY="BAR"
+
+ACCESS_KEY_ID = ENV['AMAZON_ACCESS_KEY_ID']
+SECRET_ACCESS_KEY = ENV['AMAZON_SECRET_ACCESS_KEY']
+
+if ACCESS_KEY_ID.nil? || ACCESS_KEY_ID.empty?
+  puts "Error : You must add the shell environment variables AMAZON_ACCESS_KEY_ID and AMAZON_SECRET_ACCESS_KEY before calling #{$0}!"
+  exit
+end
+
+ec2 = EC2::Base.new( :access_key_id => ACCESS_KEY_ID, :secret_access_key => SECRET_ACCESS_KEY )
+
+puts "----- GEM Version -----"
+puts EC2::VERSION::STRING
+
+puts "----- ec2.methods.sort -----"
+p ec2.methods.sort
+
+puts "----- listing images owned by 'amazon' -----"
+ec2.describe_images(:owner_id => "amazon").imagesSet.item.each do |image|
+  image.members.each do |member|
+    puts "#{member} => #{image[member]}" 
+  end
+end
+
+puts "----- listing all running instances -----"
+puts ec2.describe_instances()
+
+puts "----- creating a security group -----"
+puts ec2.create_security_group(:group_name => "ec2-example-rb-test-group", :group_description => "ec-example.rb test group description.")
+
+puts "----- listing security groups -----"
+puts ec2.describe_security_groups()
+
+puts "----- deleting a security group -----"
+puts ec2.delete_security_group(:group_name => "ec2-example-rb-test-group")
+
+puts "----- listing my keypairs (verbose mode) -----"
+puts ec2.describe_keypairs()
+

data/bin/ec2sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+
+# 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
+#++
+
+# CREDITS : Credit for this bit of shameful ripoff coolness 
+# goes to Marcel Molina and his AWS::S3 gem.  Thanks!
+
+# Usage : running this starts up an irb session and 
+# sets up the connection to EC2 as a class variable called
+# '@ec2'.  So just do something like the following on the 
+# shell command line:
+
+#   macbook-pro:~ glenn$ ec2sh 
+#   >> @ec2.describe_images
+#   => [#<EC2::Item image_location...
+
+ec2_lib   = File.dirname(__FILE__) + '/../lib/EC2'
+setup = File.dirname(__FILE__) + '/setup'
+irb_name = RUBY_PLATFORM =~ /mswin32/ ? 'irb.bat' : 'irb'
+
+if ( ENV['AMAZON_ACCESS_KEY_ID'] && ENV['AMAZON_SECRET_ACCESS_KEY'] )
+  
+  welcome_message = <<-MESSAGE
+  
+  'ec2sh' usage :
+  This is an interactive 'irb' command shell that allows you to use all 
+  commands available to the amazon-ec2 gem.  You'll find this to be a
+  great tool to help you debug issues and practice running commands
+  against the live EC2 servers prior to putting them in your code.
+  
+  The EC2 connection is wired to the class instance '@ec2'.  Make method calls 
+  on this to execute commands on EC2.  Adding a #to_s 
+  at the end of any command should give you a full String representation of the
+  response.  The #xml data is available for each response
+  which allows you to view the full and complete XML response returned by
+  EC2 without any parsing applied.  This is useful for viewing the 
+  hierarchy of an entire response in a friendly way (if XML is friendly
+  to you!).  Understanding the hierarchy of the XML response is critical
+  to making effective use of this library.
+    
+    Examples to try:
+      
+      returns : all ec2 public methods
+      >> @ec2.methods.sort
+      
+      returns : a string representation of ALL images
+      >> @ec2.describe_images.to_s
+      
+      returns : an Array of EC2::Response objects, each an EC2 image and its data
+      >> @ec2.describe_images.imagesSet.item
+      >> @ec2.describe_images.imagesSet.item[0] (an OpenStruct of a single item in that array)
+      >> @ec2.describe_images.imagesSet.item[0].to_s (a String representation of that OpenStruct item)
+      
+      returns : an XML representation of all images
+      >> puts @ec2.describe_images.xml
+      
+      returns : an XML representation of all images owned by Amazon
+      >> puts @ec2.describe_images(:owner_id => 'amazon').xml
+    
+  MESSAGE
+  
+  puts welcome_message
+  exec "#{irb_name} -r #{ec2_lib} -r #{setup} --simple-prompt"
+else
+  puts "You must define AMAZON_ACCESS_KEY_ID and AMAZON_SECRET_ACCESS_KEY as shell environment variables before running #{$0}!"
+end

data/bin/setup.rb

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+# 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
+#++
+
+if ENV['AMAZON_ACCESS_KEY_ID'] && ENV['AMAZON_SECRET_ACCESS_KEY']
+  @ec2 = EC2::Base.new( 
+    :access_key_id => ENV['AMAZON_ACCESS_KEY_ID'],
+    :secret_access_key => ENV['AMAZON_SECRET_ACCESS_KEY'] 
+  )
+end
+
+include EC2 

data/lib/EC2.rb

@@ -1,31 +1,17 @@
-# 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
+#++
 
-# Original Amazon Web Services Notice
-# This software code is made available "AS IS" without warranties of any
-# kind.  You may copy, display, modify and redistribute the software
-# code either by itself or as incorporated into your code; provided that
-# you do not remove any proprietary notices.  Your use of this software
-# code is at your own risk and you waive any claim against Amazon Web
-# Services LLC or its affiliates with respect to your use of this software
-# code. (c) 2006 Amazon Web Services LLC or its affiliates.  All rights
-# reserved.
-
-require 'base64'
-require 'cgi'
-require 'openssl'
-require 'digest/sha1'
-require 'net/https'
-require 'rexml/document'
-require 'time'
+%w[ base64 cgi openssl digest/sha1 net/https rexml/document time ostruct ].each { |f| require f }
 
 # Require any lib files that we have bundled with this Ruby Gem in the lib/EC2 directory.
-# Parts of the EC2 module and AWSAuthConnection class are broken out into separate
+# Parts of the EC2 module and Base class are broken out into separate
 # files for maintainability and are organized by the functional groupings defined 
 # in the EC2 API developers guide.
 Dir[File.join(File.dirname(__FILE__), 'EC2/**/*.rb')].sort.each { |lib| require lib }
@@ -35,11 +21,8 @@ module EC2
   # Which host FQDN will we connect to for all API calls to AWS?
   DEFAULT_HOST = 'ec2.amazonaws.com'
   
-  # Define the ports to use for SSL(true) or Non-SSL(false) connections.
-  PORTS_BY_SECURITY = { true => 443, false => 80 }
-  
   # This is the version of the API as defined by Amazon Web Services
-  API_VERSION = '2007-01-03'
+  API_VERSION = '2007-01-19'
   
   # This release version is passed in with each request as part
   # of the HTTP 'User-Agent' header.  Set this be the same value 
@@ -60,15 +43,15 @@ module EC2
     return buf
   end
   
-  # Encodes the given string with the aws_secret_access_key, by taking the
+  # Encodes the given string with the secret_access_key, by taking the
   # hmac-sha1 sum, and then base64 encoding it.  Optionally, it will also
   # url encode the result of that to protect the string if it's going to
   # be used as a query string parameter.
-  def EC2.encode(aws_secret_access_key, str, urlencode=true)
+  def EC2.encode(secret_access_key, str, urlencode=true)
     digest = OpenSSL::Digest::Digest.new('sha1')
     b64_hmac =
       Base64.encode64(
-        OpenSSL::HMAC.digest(digest, aws_secret_access_key, str)).strip
+        OpenSSL::HMAC.digest(digest, secret_access_key, str)).strip
         
     if urlencode
       return CGI::escape(b64_hmac)
@@ -78,27 +61,62 @@ module EC2
   end
   
   
-  # The library exposes one main interface class, 'AWSAuthConnection'.
-  # This class performs all the operations for using the EC2 service 
-  # including header signing.  This class uses Net::HTTP to interface 
-  # with EC2 Query API interface.
-  class AWSAuthConnection
+  #Introduction:
+  #
+  # The library exposes one main interface class, 'EC2::Base'.
+  # This class provides all the methods for using the EC2 service 
+  # including the handling of header signing and other security issues .  
+  # This class uses Net::HTTP to interface with the EC2 Query API interface.
+  #
+  #Required Arguments:
+  #
+  # :access_key_id => String (default : "")
+  # :secret_access_key => String (default : "")
+  #
+  #Optional Arguments:
+  #
+  # :use_ssl => Boolean (default : true)
+  # :server => String (default : 'ec2.amazonaws.com')
+  #
+  class Base
     
-    # Allow viewing, or turning on and off, the verbose mode of the connection class.
-    # If 'true' some 'puts' are done to view variable contents.
-    attr_accessor :verbose
+    attr_reader :use_ssl, :server, :port
     
-    def initialize(aws_access_key_id, aws_secret_access_key, is_secure=true,
-                   server=DEFAULT_HOST, port=PORTS_BY_SECURITY[is_secure])
+    def initialize( options = {} )
       
-      @aws_access_key_id = aws_access_key_id
-      @aws_secret_access_key = aws_secret_access_key
-      @http = Net::HTTP.new(server, port)
-      @http.use_ssl = is_secure
-      # Don't verify the SSL certificates.  Avoids SSL Cert warning on every GET.
-      @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      options = { :access_key_id => "",
+                  :secret_access_key => "",
+                  :use_ssl => true,
+                  :server => DEFAULT_HOST
+                  }.merge(options)
+                  
+      @server = options[:server]
+      @use_ssl = options[:use_ssl]
+      
+      raise ArgumentError, "No :access_key_id provided" if options[:access_key_id].nil? || options[:access_key_id].empty?
+      raise ArgumentError, "No :secret_access_key provided" if options[:secret_access_key].nil? || options[:secret_access_key].empty?
+      raise ArgumentError, "No :use_ssl value provided" if options[:use_ssl].nil?
+      raise ArgumentError, "Invalid :use_ssl value provided, only 'true' or 'false' allowed" unless options[:use_ssl] == true || options[:use_ssl] == false
+      raise ArgumentError, "No :server provided" if options[:server].nil? || options[:server].empty?
+      
+      
+      # based on the :use_ssl boolean, determine which port we should connect to
+      case @use_ssl
+      when true
+        # https
+        @port = 443
+      when false
+        # http
+        @port = 80
+      end
+      
+      @access_key_id = options[:access_key_id]
+      @secret_access_key = options[:secret_access_key]
+      @http = Net::HTTP.new(options[:server], @port)
+      @http.use_ssl = @use_ssl
       
-      @verbose = false
+      # Don't verify the SSL certificates.  Avoids SSL Cert warning in log on every GET.
+      @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
       
     end
     
@@ -126,20 +144,23 @@ module EC2
         
         @http.start do
           
-          params.merge!( {"Action"=>action, "SignatureVersion"=>"1", "AWSAccessKeyId"=>@aws_access_key_id,
-                           "Version"=>API_VERSION, "Timestamp"=>Time.now.getutc.iso8601,} )
-          p params if @verbose
+          # remove any keys that have nil or empty values
+          params.reject! { |key, value| value.nil? or value.empty?}
+          
+          params.merge!( {"Action" => action,
+                          "SignatureVersion" => "1",
+                          "AWSAccessKeyId" => @access_key_id,
+                          "Version" => API_VERSION,
+                          "Timestamp"=>Time.now.getutc.iso8601} )
           
           sigpath = "?" + params.sort_by { |param| param[0].downcase }.collect { |param| param.join("=") }.join("&")
           
-          sig = get_aws_auth_param(sigpath, @aws_secret_access_key)
+          sig = get_aws_auth_param(sigpath, @secret_access_key)
           
           path = "?" + params.sort.collect do |param|
             CGI::escape(param[0]) + "=" + CGI::escape(param[1])
           end.join("&") + "&Signature=" + sig
           
-          puts path if @verbose
-          
           req = Net::HTTP::Get.new("/#{path}")
           
           # Ruby will automatically add a random content-type on some verbs, so
@@ -149,20 +170,80 @@ module EC2
           req['Content-Type'] ||= ''
           req['User-Agent'] = "rubyforge-amazon-ec2-ruby-gem-query-api v-#{RELEASE_VERSION}"
           
-          data = nil unless req.request_body_permitted?
-          @http.request(req, data)
+          #data = nil unless req.request_body_permitted?
+          response = @http.request(req, nil)
+          
+          # Make a call to see if we need to throw an error based on the response given by EC2
+          # All error classes are defined in EC2/exceptions.rb
+          ec2_error?(response)
+          
+          return response
           
         end
         
       end
       
-      
       # Set the Authorization header using AWS signed header authentication
-      def get_aws_auth_param(path, aws_secret_access_key)
+      def get_aws_auth_param(path, secret_access_key)
         canonical_string =  EC2.canonical_string(path)
-        encoded_canonical = EC2.encode(aws_secret_access_key, canonical_string)
+        encoded_canonical = EC2.encode(secret_access_key, canonical_string)
       end
-    
+      
+      # allow us to have a one line call in each method which will do all of the work
+      # in making the actual request to AWS.
+      def response_generator( options = {} )
+        
+        options = {
+          :action => "",
+          :params => {}
+        }.merge(options)
+        
+        raise ArgumentError, ":action must be provided to response_generator" if options[:action].nil? || options[:action].empty?
+        
+        http_response = make_request(options[:action], options[:params])
+        http_xml = http_response.body
+        return Response.parse(:xml => http_xml)
+        
+      end
+      
+      # Raises the appropriate error if the specified Net::HTTPResponse object
+      # contains an Amazon EC2 error; returns +false+ otherwise.
+      def ec2_error?(response)
+        
+        # return false if we got a HTTP 200 code,
+        # otherwise there is some type of error (40x,50x) and
+        # we should try to raise an appropriate exception
+        # from one of our exception classes defined in
+        # exceptions.rb
+        return false if response.is_a?(Net::HTTPSuccess)
+
+        # parse the XML document so we can walk through it
+        doc = REXML::Document.new(response.body)
+        
+        # Check that the Error element is in the place we would expect.
+        # and if not raise a generic error exception
+        unless doc.root.elements['Errors'].elements['Error'].name == 'Error'
+          raise Error, "Unexpected error format. response.body is: #{response.body}"
+        end
+        
+        # An valid error response looks like this:
+        # <?xml version="1.0"?><Response><Errors><Error><Code>InvalidParameterCombination</Code><Message>Unknown parameter: foo</Message></Error></Errors><RequestID>291cef62-3e86-414b-900e-17246eccfae8</RequestID></Response>
+        # AWS EC2 throws some exception codes that look like Error.SubError.  Since we can't name classes this way
+        # we need to strip out the '.' in the error 'Code' and we name the error exceptions with this
+        # non '.' name as well.
+        error_code    = doc.root.elements['Errors'].elements['Error'].elements['Code'].text.gsub('.', '')
+        error_message = doc.root.elements['Errors'].elements['Error'].elements['Message'].text
+        
+        # Raise one of our specific error classes if it exists.
+        # otherwise, throw a generic EC2 Error with a few details.
+        if EC2.const_defined?(error_code)
+          raise EC2.const_get(error_code), error_message
+        else
+          raise Error, "This is an undefined error code which needs to be added to exceptions.rb : error_code => #{error_code} : error_message => #{error_message}"
+        end
+        
+      end
+      
   end
   
 end