grempe-amazon-ec2 0.2.9

data/Rakefile

@@ -0,0 +1,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

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:grempe@rubyforge.org)
+# Copyright:: Copyright (c) 2007-2008 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:grempe@rubyforge.org)
+# Copyright:: Copyright (c) 2007-2008 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:grempe@rubyforge.org)
+# Copyright:: Copyright (c) 2007-2008 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/config/hoe.rb

@@ -0,0 +1,76 @@
+require 'EC2/version'
+
+AUTHOR = 'Glenn Rempe'  # can also be an array of Authors
+EMAIL = "grempe@rubyforge.org"
+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
+RUBYFORGE_PROJECT = 'amazon-ec2' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "grempe"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil 
+# UNCOMMENT IF REQUIRED: 
+# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue nil
+VERS = EC2::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'amazon-ec2 documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README.txt",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' } 
+    @extra_deps
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+  
+  # == 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.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']]
+  
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  p.spec_extras = {
+    :extra_rdoc_files => ["README.txt", "History.txt", "License.txt"],
+    :rdoc_options => RDOC_OPTS,
+    :autorequire => "EC2"
+  }
+  
+end
+
+CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')

data/config/requirements.rb

@@ -0,0 +1,17 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))
+
+require 'EC2'

data/lib/EC2.rb

@@ -0,0 +1,254 @@
+#--
+# 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
+#++
+
+%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 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 }
+
+module EC2
+
+  # Which host FQDN will we connect to for all API calls to AWS?
+  DEFAULT_HOST = 'ec2.amazonaws.com'
+
+  # This is the version of the API as defined by Amazon Web Services
+  API_VERSION = '2008-02-01'
+
+  # This release version is passed in with each request as part
+  # of the HTTP 'User-Agent' header.  Set this be the same value
+  # as what is stored in the lib/EC2/version.rb module constant instead.
+  # This way we keep it nice and DRY and only have to define the
+  # version number in a single place.
+  RELEASE_VERSION = EC2::VERSION::STRING
+
+  # Builds the canonical string for signing. This strips out all '&', '?', and '='
+  # from the query string to be signed.
+  #   Note:  The parameters in the path passed in must already be sorted in
+  #   case-insensitive alphabetical order and must not be url encoded.
+  def EC2.canonical_string(path)
+    buf = ""
+    path.split('&').each { |field|
+      buf << field.gsub(/\&|\?/,"").sub(/=/,"")
+    }
+    return buf
+  end
+
+  # 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(secret_access_key, str, urlencode=true)
+    digest = OpenSSL::Digest::Digest.new('sha1')
+    b64_hmac =
+      Base64.encode64(
+        OpenSSL::HMAC.digest(digest, secret_access_key, str)).strip
+
+    if urlencode
+      return CGI::escape(b64_hmac)
+    else
+      return b64_hmac
+    end
+  end
+
+
+  #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')
+  # :proxy_server => String (default : nil)
+  #
+  class Base
+
+    attr_reader :use_ssl, :server, :proxy_server, :port
+
+    def initialize( options = {} )
+
+      options = { :access_key_id => "",
+                  :secret_access_key => "",
+                  :use_ssl => true,
+                  :server => DEFAULT_HOST,
+                  :proxy_server => nil
+                  }.merge(options)
+
+      @server = options[:server]
+      @proxy_server = options[:proxy_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]
+
+      # Use proxy server if defined
+      # Based on patch by Mathias Dalheimer.  20070217
+      proxy = @proxy_server ? URI.parse(@proxy_server) : OpenStruct.new
+      @http = Net::HTTP::Proxy( proxy.host,
+                                proxy.port,
+                                proxy.user,
+                                proxy.password).new(options[:server], @port)
+
+      @http.use_ssl = @use_ssl
+
+      # Don't verify the SSL certificates.  Avoids SSL Cert warning in log on every GET.
+      @http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+    end
+
+
+    private
+
+      # pathlist is a utility method which takes a key string and and array as input.
+      # It converts the array into a Hash with the hash key being 'Key.n' where
+      # 'n' increments by 1 for each iteration.  So if you pass in args
+      # ("ImageId", ["123", "456"]) you should get
+      # {"ImageId.1"=>"123", "ImageId.2"=>"456"} returned.
+      def pathlist(key, arr)
+        params = {}
+        arr.each_with_index do |value, i|
+          params["#{key}.#{i+1}"] = value
+        end
+        params
+      end
+
+
+      # Make the connection to AWS EC2 passing in our request.  This is generally called from
+      # within a 'Response' class object or one of its sub-classes so the response is interpreted
+      # in its proper context.  See lib/EC2/responses.rb
+      def make_request(action, params, data='')
+
+        @http.start do
+
+          # 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} )
+
+          sigquery = params.sort_by { |param| param[0].downcase }.collect { |param| param.join("=") }.join("&")
+
+          sig = get_aws_auth_param(sigquery, @secret_access_key)
+
+          query = params.sort.collect do |param|
+            CGI::escape(param[0]) + "=" + CGI::escape(param[1])
+          end.join("&") + "&Signature=" + sig
+
+          req = Net::HTTP::Post.new("/")
+          req.content_type = 'application/x-www-form-urlencoded'
+          req['User-Agent'] = "rubyforge-amazon-ec2-ruby-gem-query-api v-#{RELEASE_VERSION}"
+
+          response = @http.request(req, query)
+
+          # 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, secret_access_key)
+        canonical_string =  EC2.canonical_string(path)
+        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