.yardopts @@ -2,5 +2,7 @@ .DS_Store coverage rdoc +doc +.yardoc pkg .gitignore @@ -1,3 +1,6 @@ +=== 0.5.2 2009-08-20 + * Converted to YardDoc documentation format. See : http://yard.soen.ca/getting_started + === 0.5.0 2009-08-11 * Major re-factor by Kris Rasmussen (krisr) to add support for the AWS Elastic Load Balancer API. Kudos Kris! ChangeLog @@ -1,4 +1,4 @@ -Copyright (c) 2007-2008 Glenn Rempe +Copyright (c) 2007-2009 Glenn Rempe This software is distributed under the Ruby License. A copy of which is provided below. LICENSE @@ -305,12 +305,24 @@ So, for example, if you wanted to get the image ID of the third image listed in EC2 will typically return sets of things (imagesSet, reservationSet, etc.) which we map to ruby Arrays (.imagesSet.item in the example above). If you want to iterate over a response set you will need to iterate over this array. The Arrays will typically contain additional AWS::Response objects that represent each individual item. You'll find that you can use the 'ec2sh' to help you understand the structure more completely if you try issuing commands there as a way to practice seeing what will be returned and making sure you get exactly what you want. +=== Handling Exceptions +If for some reason an error occurs 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 +AWS has defined in the API. 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' clause. It is up to you +to determine how you want to handle these exceptions in your code. + == Additional Resources === Project Websites * Project Home : http://github.com/grempe/amazon-ec2/tree/master +* API Documentation : http://rdoc.info/projects/grempe/amazon-ec2 * Discussion Group : http://groups.google.com/group/amazon-ec2 * Report Bugs / Request Features : http://github.com/grempe/amazon-ec2/issues * Amazon Web Services : http://aws.amazon.com @@ -321,7 +333,7 @@ The original code for this library was provided by Amazon Web Services, LLC as s == Contact -Comments, patches, Git pull requests and bug reports are welcome. Send an email to mailto:glenn@rempe.us or use the Google Groups forum for this project. +Comments, patches, Git pull requests and bug reports are welcome. Send an email to mailto:glenn@rempe.us or join the Google Groups forum. Enjoy! README.rdoc @@ -1,5 +1,6 @@ require 'rubygems' require 'rake' +require 'yard' require 'jeweler' Jeweler::Tasks.new do |gem| @@ -47,19 +48,8 @@ end task :default => :test -require 'rake/rdoctask' -Rake::RDocTask.new do |rdoc| - if File.exist?('VERSION.yml') - config = YAML.load(File.read('VERSION.yml')) - version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}" - else - version = "" - end - - rdoc.rdoc_dir = 'rdoc' - rdoc.title = "amazon-ec2 #{version}" - rdoc.rdoc_files.include('README*') - rdoc.rdoc_files.include('lib/**/*.rb') +YARD::Rake::YardocTask.new do |t| + #t.files = ['lib/**/*.rb'] end begin @@ -70,15 +60,15 @@ begin task :release => ["rubyforge:release:gem", "rubyforge:release:docs"] namespace :release do - desc "Publish RDoc to RubyForge." - task :docs => [:rdoc] do + desc "Publish YARD docs to RubyForge." + task :docs => [:doc] do config = YAML.load( File.read(File.expand_path('~/.rubyforge/user-config.yml')) ) host = "#{config['username']}@rubyforge.org" remote_dir = "/var/www/gforge-projects/amazon-ec2/" - local_dir = 'rdoc' + local_dir = 'doc' Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload end Rakefile @@ -1,16 +1,47 @@ -# Require any lib files that we have bundled with this Ruby Gem in the lib/AWS directory. -# Parts of the AWS module and Base class are broken out into separate -# files for maintainability and are organized by the functional groupings defined -# in the AWS API developers guide. - +#-- +# Amazon Web Services EC2 + ELB API Ruby library +# +# Ruby Gem Name:: amazon-ec2 +# Author:: Glenn Rempe (mailto:glenn@rempe.us) +# Copyright:: Copyright (c) 2007-2009 Glenn Rempe +# License:: Distributes under the same terms as Ruby +# Home:: http://github.com/grempe/amazon-ec2/tree/master +#++ %w[ base64 cgi openssl digest/sha1 net/https rexml/document time ostruct ].each { |f| require f } +begin + require 'xmlsimple' unless defined? XmlSimple +rescue Exception => e + require 'xml-simple' unless defined? XmlSimple +end + + +# A custom implementation of Hash that allows us to access hash values using dot notation +# +# @example Access the hash keys in the standard way or using dot notation +# foo[:bar] => "baz" +# foo.bar => "baz" +class Hash + def method_missing(meth, *args, &block) + if args.size == 0 + self[meth.to_s] || self[meth.to_sym] + end + end +end + + module AWS - # 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. + + # Builds the canonical string for signing requests. This strips out all '&', '?', and '=' + # from the query string to be signed. The parameters in the path passed in must already + # be sorted in case-insensitive alphabetical order and must not be url encoded. + # + # @param [String] params the params that will be sorted and encoded as a canonical string. + # @param [String] host the hostname of the API endpoint. + # @param [String] method the HTTP method that will be used to submit the params. + # @param [String] base the URI path that this information will be submitted to. + # @return [String] the canonical request description string. def AWS.canonical_string(params, host, method="POST", base="/") # Sort, and encode parameters into a canonical string. sorted_params = params.sort {|x,y| x[0] <=> y[0]} @@ -31,10 +62,15 @@ module AWS end - # Encodes the given string with the 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. + # + # @param [String] secret_access_key the user's secret access key for signing. + # @param [String] str the string to be hashed and encoded. + # @param [Boolean] urlencode whether or not to url encode the result., true or false + # @return [String] the signed and encoded string. def AWS.encode(secret_access_key, str, urlencode=true) digest = OpenSSL::Digest::Digest.new('sha1') b64_hmac = @@ -48,10 +84,21 @@ module AWS end end + # This class provides all the methods for using the EC2 or ELB service + # including the handling of header signing and other security concerns. + # This class uses the Net::HTTP library to interface with the AWS Query API + # interface. You should not instantiate this directly, instead + # you should setup an instance of 'AWS::EC2::Base' or 'AWS::ELB::Base'. class Base attr_reader :use_ssl, :server, :proxy_server, :port + # @option options [String] :access_key_id ("") The user's AWS Access Key ID + # @option options [String] :secret_access_key ("") The user's AWS Secret Access Key + # @option options [Boolean] :use_ssl (true) Connect using SSL? + # @option options [String] :server ("ec2.amazonaws.com") The server API endpoint host + # @option options [String] :proxy_server (nil) An HTTP proxy server FQDN + # @return [Object] the object. def initialize( options = {} ) options = { :access_key_id => "", @@ -242,4 +289,5 @@ module AWS end end -Dir[File.join(File.dirname(__FILE__), 'AWS/*.rb')].sort.each { |lib| require lib } \ No newline at end of file +Dir[File.join(File.dirname(__FILE__), 'AWS/**/*.rb')].sort.each { |lib| require lib } + lib/AWS.rb @@ -1,58 +1,23 @@ -#-- -# Amazon Web Services EC2 Query API Ruby library -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Glenn Rempe (mailto:glenn@rempe.us) -# Copyright:: Copyright (c) 2007-2008 Glenn Rempe -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master -#++ - -# 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 AWS module EC2 # Which host FQDN will we connect to for all API calls to AWS? - # If EC2_URL is defined in the users ENV we can use that. It is - # expected that this var is set with something like: - # export EC2_URL='https://ec2.amazonaws.com' + # If EC2_URL is defined in the users ENV we can override the default with that. # + # @example + # export EC2_URL='https://ec2.amazonaws.com' if ENV['EC2_URL'] EC2_URL = ENV['EC2_URL'] VALID_HOSTS = ['https://ec2.amazonaws.com', 'https://us-east-1.ec2.amazonaws.com', 'https://eu-west-1.ec2.amazonaws.com'] raise ArgumentError, "Invalid EC2_URL environment variable : #{EC2_URL}" unless VALID_HOSTS.include?(EC2_URL) DEFAULT_HOST = URI.parse(EC2_URL).host else - # default US host + # Default US API endpoint DEFAULT_HOST = 'ec2.amazonaws.com' end - # This is the version of the API as defined by Amazon Web Services API_VERSION = '2008-12-01' - #Introduction: - # - # The library exposes one main interface class, 'AWS::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 < AWS::Base def api_version API_VERSION @@ -64,4 +29,5 @@ module AWS end end -end \ No newline at end of file +end + lib/AWS/EC2.rb @@ -1,43 +1,21 @@ -#-- -# Amazon Web Services EC2 Query API Ruby library -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Glenn Rempe (mailto:glenn@rempe.us) -# Copyright:: Copyright (c) 2007-2008 Glenn Rempe -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master -#++ - module AWS module EC2 - class Base < AWS::Base - #Amazon Developer Guide Docs: - # # The DescribeAvailabilityZones operation describes availability zones that are currently # available to the account and their states. # # An optional list of zone names can be passed. # - #Required Arguments: - # - # none + # @option options [optional, String] :zone_name ([]) an Array of zone names # - #Optional Arguments: - # - # :zone_name => Array (default : []) - # - def describe_availability_zones( options = {} ) - options = { :zone_name => [] }.merge(options) - params = pathlist("ZoneName", options[:zone_name] ) - return response_generator(:action => "DescribeAvailabilityZones", :params => params) - end + end end -end \ No newline at end of file +end + lib/AWS/EC2/availability_zones.rb @@ -1,46 +1,23 @@ -#-- -# Amazon Web Services EC2 Query API Ruby library -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Glenn Rempe (mailto:glenn@rempe.us) -# Copyright:: Copyright (c) 2007-2008 Glenn Rempe -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master -#++ - module AWS module EC2 - class Base < AWS::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 : "") + # @option options [String] :instance_id ("") an Instance ID # - #Optional Arguments: - # - # none - # - def get_console_output( options ={} ) - + 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 end -end \ No newline at end of file +end + lib/AWS/EC2/console.rb @@ -1,60 +1,23 @@ -#-- -# Amazon Web Services EC2 Query API Ruby library -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Glenn Rempe (mailto:glenn@rempe.us) -# Copyright:: Copyright (c) 2007-2008 Glenn Rempe -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master -#++ - module AWS module EC2 class Base < AWS::Base - - #Amazon Developer Guide Docs: - # # The AllocateAddress operation acquires an elastic IP address for use with your account. # - #Required Arguments: - # - # none - # - #Optional Arguments: - # - # none - # def allocate_address - return response_generator(:action => "AllocateAddress") - end - #Amazon Developer Guide Docs: - # # The DescribeAddresses operation lists elastic IP addresses assigned to your account. # - #Required Arguments: - # - # :public_ip => Array (default : [], can be empty) - # - #Optional Arguments: - # - # none + # @option options [Array] :public_ip ([]) an IP address to be described # def describe_addresses( options = {} ) - options = { :public_ip => [] }.merge(options) - params = pathlist("PublicIp", options[:public_ip]) - return response_generator(:action => "DescribeAddresses", :params => params) - end - #Amazon Developer Guide Docs: - # # The ReleaseAddress operation releases an elastic IP address associated with your account. # # If you run this operation on an elastic IP address that is already released, the address @@ -68,87 +31,51 @@ module AWS # to update your DNS records and any servers or devices that communicate # with the address. # - #Required Arguments: - # - # :public_ip => String (default : '') - # - #Optional Arguments: - # - # none + # @option options [String] :public_ip ('') an IP address to be released. # def release_address( options = {} ) - options = { :public_ip => '' }.merge(options) - raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty? - params = { "PublicIp" => options[:public_ip] } - return response_generator(:action => "ReleaseAddress", :params => params) - end - #Amazon Developer Guide Docs: - # # The AssociateAddress operation associates an elastic IP address with an instance. # # If the IP address is currently assigned to another instance, the IP address # is assigned to the new instance. This is an idempotent operation. If you enter # it more than once, Amazon EC2 does not return an error. # - #Required Arguments: - # - # :instance_id => String (default : '') - # :public_ip => String (default : '') - # - #Optional Arguments: - # - # none + # @option options [String] :instance_id ('') the instance ID to associate an IP with. + # @option options [String] :public_ip ('') the public IP to associate an instance with. # def associate_address( options = {} ) - options = { :instance_id => '', :public_ip => '' }.merge(options) - raise ArgumentError, "No ':instance_id' provided" if options[:instance_id].nil? || options[:instance_id].empty? raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty? - params = { "InstanceId" => options[:instance_id], "PublicIp" => options[:public_ip] } - return response_generator(:action => "AssociateAddress", :params => params) - end - #Amazon Developer Guide Docs: - # # The DisassociateAddress operation disassociates the specified elastic IP # address from the instance to which it is assigned. This is an idempotent # operation. If you enter it more than once, Amazon EC2 does not return # an error. # - #Required Arguments: - # - # :public_ip => String (default : '') - # - #Optional Arguments: - # - # none + # @option options [String] :public_ip ('') the public IP to be dis-associated. # def disassociate_address( options = {} ) - options = { :public_ip => '' }.merge(options) - raise ArgumentError, "No ':public_ip' provided" if options[:public_ip].nil? || options[:public_ip].empty? - params = { "PublicIp" => options[:public_ip] } - return response_generator(:action => "DisassociateAddress", :params => params) - end end end -end \ No newline at end of file +end + lib/AWS/EC2/elastic_ips.rb @@ -1,20 +1,7 @@ -#-- -# Amazon Web Services EC2 Query API Ruby library -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Glenn Rempe (mailto:glenn@rempe.us) -# Copyright:: Copyright (c) 2007-2008 Glenn Rempe -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master -#++ - module AWS module EC2 - class Base < AWS::Base - #Amazon Developer Guide Docs: - # # The ModifyImageAttribute operation modifies an attribute of an AMI. The following attributes may # currently be modified: # @@ -25,17 +12,12 @@ module AWS # for using the AMIs. productCodes is a write once attribute - once it has been set it can not be # changed or removed. Currently only one product code is supported per AMI. # - #Required Arguments: - # - # :image_id => String (default : "") - # :attribute => String ('launchPermission' or 'productCodes', default : "launchPermission") - # :operation_type => String (default : "") - # - #Optional Arguments: - # - # :user_id => Array (default : []) - # :group => Array (default : []) - # :product_code => Array (default : []) + # @option options [String] :image_id ("") + # @option options [String] :attribute ("launchPermission") An attribute to modify, "launchPermission" or "productCodes" + # @option options [String] :operation_type ("") + # @option options [optional, Array] :user_id ([]) + # @option options [optional, Array] :group ([]) + # @option options [optional, Array] :product_code ([]) # def modify_image_attribute( options = {} ) @@ -87,18 +69,10 @@ module AWS end - #Amazon Developer Guide Docs: - # # The DescribeImageAttribute operation returns information about an attribute of an AMI. # - #Required Arguments: - # - # :image_id => String (default : "") - # :attribute => String ("launchPermission" or "productCodes", default : "launchPermission") - # - #Optional Arguments: - # - # none + # @option options [String] :image_id ("") + # @option options [String] :attribute ("launchPermission") An attribute to describe, "launchPermission" or "productCodes" # def describe_image_attribute( options = {} ) @@ -125,18 +99,10 @@ module AWS end - #Amazon Developer Guide Docs: - # # The ResetImageAttribute operation resets an attribute of an AMI to its default value. # - #Required Arguments: - # - # :image_id => String (default : "") - # :attribute => String (default : "launchPermission") - # - #Optional Arguments: - # - # none + # @option options [String] :image_id ("") + # @option options [String] :attribute ("launchPermission") An attribute to reset # def reset_image_attribute( options = {} ) @@ -163,6 +129,5 @@ module AWS end end - end end \ No newline at end of file lib/AWS/EC2/image_attributes.rb @@ -1,20 +1,8 @@ -#-- -# Amazon Web Services EC2 Query API Ruby library -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Glenn Rempe (mailto:glenn@rempe.us) -# Copyright:: Copyright (c) 2007-2008 Glenn Rempe -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master -#++ - module AWS module EC2 class Base < AWS::Base - #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 @@ -24,13 +12,7 @@ module AWS # 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 + # @option options [String] :image_location ("") # def register_image( options = {} ) @@ -44,8 +26,6 @@ module AWS end - #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 @@ -82,15 +62,9 @@ module AWS # 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 : []) + # @option options [Array] :image_id ([]) + # @option options [Array] :owner_id ([]) + # @option options [Array] :executable_by ([]) # def describe_images( options = {} ) @@ -104,22 +78,13 @@ module AWS end - #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 + # @option options [String] :image_id ("") # 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? lib/AWS/EC2/images.rb @@ -1,20 +1,8 @@ -#-- -# Amazon Web Services EC2 Query API Ruby library -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Glenn Rempe (mailto:glenn@rempe.us) -# Copyright:: Copyright (c) 2007-2008 Glenn Rempe -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master -#++ - module AWS module EC2 class Base < AWS::Base - #Amazon Developer Guide Docs: - # # The RunInstances operation launches a specified number of instances. # # Note : The Query version of RunInstances only allows instances of a single AMI to be launched in @@ -52,22 +40,17 @@ module AWS # If any of the AMIs have product codes attached for which the user has not subscribed, # the RunInstances call will fail. # - #Required Arguments: - # - # :image_id => String (Default : "") - # :min_count => Integer (default : 1 ) - # :max_count => Integer (default : 1 ) - # - #Optional Arguments: - # - # :key_name => String (default : nil) - # :group_id => Array (default : []) - # :user_data => String (default : nil) - # :addressing_type => String (default : "public") - # :instance_type => String (default : "m1.small") - # :kernel_id => String (default : nil) - # :availability_zone => String (default : nil) - # :base64_encoded => Boolean (default : false) + # @option options [String] :image_id ("") + # @option options [Integer] :min_count (1) + # @option options [Integer] :max_count (1) + # @option options [optional, String] :key_name (nil) + # @option options [optional, Array] :group_id ([]) + # @option options [optional, String] :user_data (nil) + # @option options [optional, String] :addressing_type ("public") + # @option options [optional, String] :instance_type ("m1.small") + # @option options [optional, String] :kernel_id (nil) + # @option options [optional, String] :availability_zone (nil) + # @option options [optional, Boolean] :base64_encoded (false) # def run_instances( options = {} ) @@ -113,7 +96,7 @@ module AWS # If :user_data is passed in then URL escape and Base64 encode it # as needed. Need for URL Escape + Base64 encoding is determined # by :base64_encoded param. - def extract_user_data(options) + def extract_user_data( options = {} ) return unless options[:user_data] if options[:user_data] if options[:base64_encoded] @@ -125,8 +108,6 @@ module AWS end - #Amazon Developer Guide Docs: - # # The DescribeInstances operation returns information about instances owned by the user # making the request. # @@ -138,13 +119,7 @@ module AWS # Recently terminated instances will be included in the returned results for a small interval subsequent to # their termination. This interval is typically of the order of one hour # - #Required Arguments: - # - # none - # - #Optional Arguments: - # - # :instance_id => Array (default : []) + # @option options [Array] :instance_id ([]) # def describe_instances( options = {} ) @@ -157,19 +132,11 @@ module AWS end - #Amazon Developer Guide Docs: - # # The RebootInstances operation requests a reboot of one or more instances. This operation is # asynchronous; it only queues a request to reboot the specified instance(s). The operation will succeed # provided the instances are valid and belong to the user. Terminated instances will be ignored. # - #Required Arguments: - # - # :instance_id => Array (default : []) - # - #Optional Arguments: - # - # none + # @option options [Array] :instance_id ([]) # def reboot_instances( options = {} ) @@ -185,20 +152,12 @@ module AWS end - #Amazon Developer Guide Docs: - # # The TerminateInstances operation shuts down one or more instances. This operation is idempotent # and terminating an instance that is in the process of shutting down (or already terminated) will succeed. # Terminated instances remain visible for a short period of time (approximately one hour) after # termination, after which their instance ID is invalidated. # - #Required Arguments: - # - # :instance_id => Array (default : []) - # - #Optional Arguments: - # - # none + # @option options [Array] :instance_id ([]) # def terminate_instances( options = {} ) lib/AWS/EC2/instances.rb @@ -1,35 +1,16 @@ -#-- -# Amazon Web Services EC2 Query API Ruby library -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Glenn Rempe (mailto:glenn@rempe.us) -# Copyright:: Copyright (c) 2007-2008 Glenn Rempe -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master -#++ - module AWS module EC2 class Base < AWS::Base - #Amazon Developer Guide Docs: - # # The CreateKeyPair operation creates a new 2048 bit RSA keypair and returns a unique ID that can be # used to reference this keypair when launching new instances. # - #Required Arguments: - # - # :key_name => String (default : "") - # - #Optional Arguments: - # - # none + # @option options [String] :key_name ("") # def create_keypair( options = {} ) - # defaults options = { :key_name => "" }.merge(options) raise ArgumentError, "No :key_name provided" if options[:key_name].nil? || options[:key_name].empty? @@ -41,19 +22,11 @@ module AWS end - #Amazon Developer Guide Docs: - # # The DescribeKeyPairs operation returns information about keypairs available for use by the user # making the request. Selected keypairs may be specified or the list may be left empty if information for # all registered keypairs is required. # - #Required Arguments: - # - # :key_name => Array (default : []) - # - #Optional Arguments: - # - # none + # @option options [Array] :key_name ([]) # def describe_keypairs( options = {} ) @@ -66,17 +39,9 @@ module AWS end - #Amazon Developer Guide Docs: - # # The DeleteKeyPair operation deletes a keypair. # - #Required Arguments: - # - # :key_name => String (default : "") - # - #Optional Arguments: - # - # none + # @option options [String] :key_name ("") # def delete_keypair( options = {} ) lib/AWS/EC2/keypairs.rb @@ -1,45 +1,21 @@ -#-- -# Amazon Web Services EC2 Query API Ruby library -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Glenn Rempe (mailto:glenn@rempe.us) -# Copyright:: Copyright (c) 2007-2008 Glenn Rempe -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master -#++ - module AWS module EC2 - class Base < AWS::Base - #Amazon Developer Guide Docs: - # # The ConfirmProductInstance operation returns true if the given product code is attached to the instance # with the given instance id. False is returned if the product code is not attached to the instance. # - #Required Arguments: - # - # :product_code => String (default : "") - # :instance_id => String (default : "") - # - #Optional Arguments: - # - # none + # @option options [String] :product_code ("") + # @option options [String] :instance_id ("") # def confirm_product_instance( options ={} ) - options = {:product_code => "", :instance_id => ""}.merge(options) - raise ArgumentError, "No product code provided" if options[:product_code].nil? || options[:product_code].empty? raise ArgumentError, "No instance ID provided" if options[:instance_id].nil? || options[:instance_id].empty? - params = { "ProductCode" => options[:product_code], "InstanceId" => options[:instance_id] } - return response_generator(:action => "ConfirmProductInstance", :params => params) - end - end + end end end \ No newline at end of file lib/AWS/EC2/products.rb @@ -1,21 +1,7 @@ -#-- -# Amazon Web Services EC2 Query API Ruby library -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Glenn Rempe (mailto:glenn@rempe.us) -# Copyright:: Copyright (c) 2007-2008 Glenn Rempe -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master -#++ - module AWS module EC2 - class Base < AWS::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 @@ -23,14 +9,8 @@ module AWS # 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 + # @option options [String] :group_name ("") + # @option options [String] :group_description ("") # def create_security_group( options = {} ) @@ -51,22 +31,14 @@ module AWS 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: + # returned. If a group is specified that does not exist an exception is returned. # - # none - # - #Optional Arguments: - # - # :group_name => Array (default : []) + # @option options [optional, Array] :group_name ([]) # def describe_security_groups( options = {} ) @@ -79,20 +51,12 @@ module AWS 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 + # @option options [String] :group_name ("") # def delete_security_group( options = {} ) @@ -107,8 +71,6 @@ module AWS 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 @@ -125,18 +87,13 @@ module AWS # 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 + # @option options [String] :group_name ("") + # @option options [optional, String] :ip_protocol (nil) Required when authorizing CIDR IP permission + # @option options [optional, Integer] :from_port (nil) Required when authorizing CIDR IP permission + # @option options [optional, Integer] :to_port (nil) Required when authorizing CIDR IP permission + # @option options [optional, String] :cidr_ip (nil) Required when authorizing CIDR IP permission + # @option options [optional, String] :source_security_group_name (nil) Required when authorizing user group pair permissions + # @option options [optional, String] :source_security_group_owner_id (nil) Required when authorizing user group pair permissions # def authorize_security_group_ingress( options = {} ) @@ -167,8 +124,6 @@ module AWS 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. @@ -187,18 +142,13 @@ module AWS # 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 + # @option options [String] :group_name ("") + # @option options [optional, String] :ip_protocol (nil) Required when revoking CIDR IP permission + # @option options [optional, Integer] :from_port (nil) Required when revoking CIDR IP permission + # @option options [optional, Integer] :to_port (nil) Required when revoking CIDR IP permission + # @option options [optional, String] :cidr_ip (nil) Required when revoking CIDR IP permission + # @option options [optional, String] :source_security_group_name (nil) Required when revoking user group pair permissions + # @option options [optional, String] :source_security_group_owner_id (nil) Required when revoking user group pair permissions # def revoke_security_group_ingress( options = {} ) @@ -229,6 +179,5 @@ module AWS end end - end end \ No newline at end of file lib/AWS/EC2/security_groups.rb @@ -1,31 +1,12 @@ -#-- -# Amazon Web Services EC2 Query API Ruby library, EBS snaphshots support -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Yann Klis (mailto:yann.klis@novelys.com) -# Copyright:: Copyright (c) 2008 Yann Klis -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master -#++ - module AWS module EC2 class Base < AWS::Base - #Amazon Developer Guide Docs: - # # The DescribeSnapshots operation describes the status of Amazon EBS snapshots. # - #Required Arguments: - # - # none - # - #Optional Arguments: - # - # :snapshot_id => Array (default : []) + # @option options [Array] :snapshot_id ([]) # - def describe_snapshots( options = {} ) options = { :snapshot_id => [] }.merge(options) @@ -36,22 +17,12 @@ module AWS end - #Amazon Developer Guide Docs: - # # The CreateSnapshot operation creates a snapshot of an Amazon EBS volume and stores it in Amazon S3. You can use snapshots for backups, to launch instances from identical snapshots, and to save data before shutting down an instance. # - #Required Arguments: - # - # :volume_id => String (default : '') - # - #Optional Arguments: + # @option options [String] :volume_id ('') # - # none - # - def create_snapshot( options = {} ) - # defaults options = { :volume_id => '' }.merge(options) raise ArgumentError, "No :volume_id provided" if options[:volume_id].nil? || options[:volume_id].empty? @@ -64,19 +35,11 @@ module AWS end - #Amazon Developer Guide Docs: - # + # The DeleteSnapshot operation deletes a snapshot of an Amazon EBS volume that is stored in Amazon S3. # - #Required Arguments: + # @option options [String] :snapshot_id ('') # - # :snapshot_id => String (default : '') - # - #Optional Arguments: - # - # none - # - def delete_snapshot( options = {} ) options = { :snapshot_id => '' }.merge(options) lib/AWS/EC2/snapshots.rb @@ -1,55 +1,23 @@ -#-- -# Amazon Web Services EC2 Query API Ruby library, EBS volumes support -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Yann Klis (mailto:yann.klis@novelys.com) -# Copyright:: Copyright (c) 2008 Yann Klis -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master -#++ - module AWS module EC2 - class Base < AWS::Base - #Amazon Developer Guide Docs: - # # The DescribeVolumes operation lists one or more Amazon EBS volumes that you own, If you do not specify any volumes, Amazon EBS returns all volumes that you own. # - #Required Arguments: - # - # none - # - #Optional Arguments: + # @option options [optional, String] :volume_id ([]) # - # :volume_id => Array (default : []) - # - def describe_volumes( options = {} ) - options = { :volume_id => [] }.merge(options) - params = pathlist("VolumeId", options[:volume_id] ) - return response_generator(:action => "DescribeVolumes", :params => params) - end - #Amazon Developer Guide Docs: - # # The CreateVolume operation creates a new Amazon EBS volume that you can mount from any Amazon EC2 instance. # - #Required Arguments: - # - # :availability_zone => String (default : '') + # @option options [String] :availability_zone ('') + # @option options [optional, String] :size ('') + # @option options [optional, String] :snapshot_id ('') # - #Optional Arguments: - # - # :size => String (default : '') - # :snapshot_id => String (default : '') - # - def create_volume( options = {} ) # defaults @@ -70,19 +38,10 @@ module AWS end - #Amazon Developer Guide Docs: - # # The DeleteVolume operation deletes an Amazon EBS volume. # - #Required Arguments: + # @option options [String] :volume_id ('') # - # :volume_id => String (default : '') - # - #Optional Arguments: - # - # none - # - def delete_volume( options = {} ) options = { :volume_id => '' }.merge(options) @@ -97,21 +56,12 @@ module AWS end - #Amazon Developer Guide Docs: - # # The AttachVolume operation attaches an Amazon EBS volume to an instance. # - #Required Arguments: + # @option options [String] :volume_id ('') + # @option options [String] :instance_id ('') + # @option options [String] :device ('') # - # :volume_id => String (default : '') - # :instance_id => String (default : '') - # :device => String (default : '') - # - #Optional Arguments: - # - # none - # - def attach_volume( options = {} ) options = { :volume_id => '' }.merge(options) @@ -132,21 +82,13 @@ module AWS end - #Amazon Developer Guide Docs: - # # The DetachVolume operation detaches an Amazon EBS volume from an instance. # - #Required Arguments: - # - # :volume_id => String (default : '') - # - #Optional Arguments: - # - # :instance_id => String (default : '') - # :device => String (default : '') - # :force => Boolean (default : '') + # @option options [String] :volume_id ('') + # @option options [optional, String] :instance_id ('') + # @option options [optional, String] :device ('') + # @option options [optional, Boolean] :force ('') # - def detach_volume( options = {} ) options = { :volume_id => '' }.merge(options) @@ -165,8 +107,9 @@ module AWS } return response_generator(:action => "DetachVolume", :params => params) - end + end end -end \ No newline at end of file +end + lib/AWS/EC2/volumes.rb @@ -1,58 +1,23 @@ -#-- -# Amazon Web Services EC2 Query API Ruby library -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Glenn Rempe (mailto:glenn@rempe.us) -# Copyright:: Copyright (c) 2007-2008 Glenn Rempe -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master -#++ - -# 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__), 'ELB/**/*.rb')].sort.each { |lib| require lib } - module AWS module ELB # Which host FQDN will we connect to for all API calls to AWS? - # If ELB_URL is defined in the users ENV we can use that. It is - # expected that this var is set with something like: - # export ELB_URL='https://ec2.amazonaws.com' - # + # If ELB_URL is defined in the users ENV we can override the default with that. + # + # @example + # export ELB_URL='https://elasticloadbalancing.amazonaws.com' if ENV['ELB_URL'] ELB_URL = ENV['ELB_URL'] VALID_HOSTS = ['elasticloadbalancing.amazonaws.com'] raise ArgumentError, "Invalid ELB_URL environment variable : #{ELB_URL}" unless VALID_HOSTS.include?(ELB_URL) DEFAULT_HOST = URI.parse(ELB_URL).host else - # default US host + # Default US API endpoint DEFAULT_HOST = 'elasticloadbalancing.amazonaws.com' end - # This is the version of the API as defined by Amazon Web Services API_VERSION = '2009-05-15' - #Introduction: - # - # The library exposes one main interface class, 'AWS::ELB::Base'. - # This class provides all the methods for using the ELB service - # including the handling of header signing and other security issues . - # This class uses Net::HTTP to interface with the ELB 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 : 'elasticloadbalancing.amazonaws.com') - # :proxy_server => String (default : nil) - # class Base < AWS::Base def api_version API_VERSION lib/AWS/ELB.rb @@ -1,8 +1,7 @@ module AWS module ELB class Base < AWS::Base - # Amazon Developer Guide Docs: - # + # This API creates a new LoadBalancer. Once the call has completed # successfully, a new LoadBalancer will be created, but it will not be # usable until at least one instance has been registered. When the @@ -10,12 +9,10 @@ module AWS # by using the DescribeInstanceHealth API. The LoadBalancer is usable as # soon as any registered instance is InService. # - # Required Arguments: - # - # :load_balancer_name => String - # :availability_zones => Array - # :listeners => Array of Hashes (:protocol, :load_balancer_port, :instance_port) - # :availability_zones => Array of Strings + # @option options [String] :load_balancer_name (nil) the name of the load balancer + # @option options [Array] :availability_zones (nil) + # @option options [Array] :listeners (nil) An Array of Hashes (:protocol, :load_balancer_port, :instance_port) + # @option options [Array] :availability_zones (nil) An Array of Strings # def create_load_balancer( options = {} ) raise ArgumentError, "No :availability_zones provided" if options[:availability_zones].nil? || options[:availability_zones].empty? @@ -35,8 +32,6 @@ module AWS return response_generator(:action => "CreateLoadBalancer", :params => params) end - # Amazon Developer Guide Docs: - # # This API deletes the specified LoadBalancer. On deletion, all of the # configured properties of the LoadBalancer will be deleted. If you # attempt to recreate the LoadBalancer, you need to reconfigure all the @@ -47,20 +42,14 @@ module AWS # get the same DNS name even if you create a new LoadBalancer with same # LoadBalancerName. # - # Required Arguments: - # - # :load_balancer_name => String + # @option options [String] :load_balancer_name the name of the load balancer # def delete_load_balancer( options = {} ) raise ArgumentError, "No :load_balancer_name provided" if options[:load_balancer_name].nil? || options[:load_balancer_name].empty? - params = { 'LoadBalancerName' => options[:load_balancer_name] } - return response_generator(:action => "DeleteLoadBalancer", :params => params) end - # Amazon Developer Guide Docs: - # # This API returns detailed configuration information for the specified # LoadBalancers, or if no LoadBalancers are specified, then the API # returns configuration information for all LoadBalancers created by the @@ -71,20 +60,14 @@ module AWS # this API, you must provide the same account credentials as those that # were used to create the LoadBalancer. # - # Optional Arguments: - # - # :load_balancer_names => String + # @option options [Array<String>] :load_balancer_names ([]) An Array of names of load balancers to describe. # def describe_load_balancers( options = {} ) options = { :load_balancer_names => [] }.merge(options) - params = pathlist("LoadBalancerName.member", options[:load_balancer_names]) - return response_generator(:action => "DescribeLoadBalancers", :params => params) end - # Amazon Developer Guide Docs: - # # This API adds new instances to the LoadBalancer. # # Once the instance is registered, it starts receiving traffic and @@ -102,25 +85,18 @@ module AWS # completed. Rather, it means that the request has been registered and # the changes will happen shortly. # - # Required Arguments: - # - # :instances => Array of Strings - # :load_balancer_name => String + # @option options [Array<String>] :instances An Array of instance names to add to the load balancer. + # @option options [String] :load_balancer_name The name of the load balancer. # def register_instances_with_load_balancer( options = {} ) raise ArgumentError, "No :instances provided" if options[:instances].nil? || options[:instances].empty? raise ArgumentError, "No :load_balancer_name provided" if options[:load_balancer_name].nil? || options[:load_balancer_name].empty? - params = {} - params.merge!(pathlist('Instances.member', [options[:instances]].flatten)) params['LoadBalancerName'] = options[:load_balancer_name] - return response_generator(:action => "RegisterInstancesWithLoadBalancer", :params => params) end - # Amazon Developer Guide Docs: - # # This API deregisters instances from the LoadBalancer. Trying to # deregister an instance that is not registered with the LoadBalancer # does nothing. @@ -132,34 +108,25 @@ module AWS # Once the instance is deregistered, it will stop receiving traffic from # the LoadBalancer. # - # Required Arguments: - # - # :instances => Array of Strings - # :load_balancer_name => String + # @option options [Array<String>] :instances An Array of instance names to remove from the load balancer. + # @option options [String] :load_balancer_name The name of the load balancer. # def deregister_instances_from_load_balancer( options = {} ) raise ArgumentError, "No :instances provided" if options[:instances].nil? || options[:instances].empty? raise ArgumentError, "No :load_balancer_name provided" if options[:load_balancer_name].nil? || options[:load_balancer_name].empty? - params = {} - params.merge!(pathlist('Instances.member', [options[:instances]].flatten)) params['LoadBalancerName'] = options[:load_balancer_name] - return response_generator(:action => "DeregisterInstancesFromLoadBalancer", :params => params) end - # Amazon Developer Guide Docs: - # # This API enables you to define an application healthcheck for the # instances. # # Note: Completion of this API does not guarantee that operation has completed. Rather, it means that the request has been registered and the changes will happen shortly. # - # Required Arguments - # - # :health_check => Hash (:timeout, :interval, :unhealthy_threshold, :healthy_threshold) - # :load_balancer_name => String + # @option options [Hash] :health_check A Hash with the keys (:timeout, :interval, :unhealthy_threshold, :healthy_threshold) + # @option options [String] :load_balancer_name The name of the load balancer. # def configure_health_check( options = {} ) raise ArgumentError, "No :health_check provided" if options[:health_check].nil? || options[:health_check].empty? @@ -182,17 +149,30 @@ module AWS return response_generator(:action => "ConfigureHealthCheck", :params => params) end - def describe_intance_health( options = {} ) + # Not yet implemented + # + # @todo Implement this method + # + def describe_instance_health( options = {} ) raise "Not yet implemented" end + # Not yet implemented + # + # @todo Implement this method + # def disable_availability_zones_for_load_balancer( options = {} ) raise "Not yet implemented" end + # Not yet implemented + # + # @todo Implement this method + # def enable_availability_zones_for_load_balancer( options = {} ) raise "Not yet implemented" end + end end end \ No newline at end of file lib/AWS/ELB/load_balancers.rb @@ -1,166 +1,122 @@ #-- -# Amazon Web Services EC2 Query API Ruby library -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Glenn Rempe (mailto:glenn@rempe.us) -# Copyright:: Copyright (c) 2007-2008 Glenn Rempe -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master +# 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. #++ module AWS - # OUR CUSTOM ERROR CODES - # All of our errors are superclassed by Error < RuntimeError - class Error < RuntimeError #:nodoc: - end + # All AWS errors are superclassed by Error < RuntimeError + class Error < RuntimeError; end - # A client side only argument error - class ArgumentError < Error #:nodoc: - end + # CLIENT : A client side argument error + class ArgumentError < Error; end + # EC2 : User not authorized. + class AuthFailure < Error; end - # AWS EC2 CLIENT ERROR CODES + # EC2 : Invalid AWS Account + class InvalidClientTokenId < Error; end - # 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. + # EC2 : Invalid Parameters for Value + class InvalidParameterValue < Error; end - # User not authorized. - class AuthFailure < Error #:nodoc: - end + # EC2 : Specified AMI has an unparsable manifest. + class InvalidManifest < Error; end - # Invalid AWS Account - class InvalidClientTokenId < Error #:nodoc: - end + # EC2 : Specified AMI ID is not valid. + class InvalidAMIIDMalformed < Error; end - # Invalid Parameters for Value - class InvalidParameterValue < Error #:nodoc: - end + # EC2 : Specified AMI ID does not exist. + class InvalidAMIIDNotFound < Error; end - # Specified AMI has an unparsable manifest. - class InvalidManifest < Error #:nodoc: - end + # EC2 : Specified AMI ID has been deregistered and is no longer available. + class InvalidAMIIDUnavailable < Error; end - # Specified AMI ID is not valid. - class InvalidAMIIDMalformed < Error #:nodoc: - end + # EC2 : Specified instance ID is not valid. + class InvalidInstanceIDMalformed < Error; end - # Specified AMI ID does not exist. - class InvalidAMIIDNotFound < Error #:nodoc: - end + # EC2 : Specified instance ID does not exist. + class InvalidInstanceIDNotFound < Error; end - # Specified AMI ID has been deregistered and is no longer available. - class InvalidAMIIDUnavailable < Error #:nodoc: - end + # EC2 : Specified keypair name does not exist. + class InvalidKeyPairNotFound < Error; end - # Specified instance ID is not valid. - class InvalidInstanceIDMalformed < Error #:nodoc: - end + # EC2 : Attempt to create a duplicate keypair. + class InvalidKeyPairDuplicate < Error; end - # Specified instance ID does not exist. - class InvalidInstanceIDNotFound < Error #:nodoc: - end + # EC2 : Specified group name does not exist. + class InvalidGroupNotFound < Error; end - # Specified keypair name does not exist. - class InvalidKeyPairNotFound < Error #:nodoc: - end + # EC2 : Attempt to create a duplicate group. + class InvalidGroupDuplicate < Error; end - # Attempt to create a duplicate keypair. - class InvalidKeyPairDuplicate < Error #:nodoc: - end + # EC2 : Specified group can not be deleted because it is in use. + class InvalidGroupInUse < Error; end - # Specified group name does not exist. - class InvalidGroupNotFound < Error #:nodoc: - end + # EC2 : Specified group name is a reserved name. + class InvalidGroupReserved < Error; end - # Attempt to create a duplicate group. - class InvalidGroupDuplicate < Error #:nodoc: - end + # EC2 : Attempt to authorize a permission that has already been authorized. + class InvalidPermissionDuplicate < Error; end - # Specified group can not be deleted because it is in use. - class InvalidGroupInUse < Error #:nodoc: - end + # EC2 : Specified permission is invalid. + class InvalidPermissionMalformed < Error; end - # Specified group name is a reserved name. - class InvalidGroupReserved < Error #:nodoc: - end + # EC2 : Specified reservation ID is invalid. + class InvalidReservationIDMalformed < Error; end - # Attempt to authorize a permission that has already been authorized. - class InvalidPermissionDuplicate < Error #:nodoc: - end + # EC2 : Specified reservation ID does not exist. + class InvalidReservationIDNotFound < Error; end - # Specified permission is invalid. - class InvalidPermissionMalformed < Error #:nodoc: - end + # EC2 : User has reached max allowed concurrent running instances. + class InstanceLimitExceeded < Error; end - # Specified reservation ID is invalid. - class InvalidReservationIDMalformed < Error #:nodoc: - end + # EC2 : An invalid set of parameters were passed as arguments + class InvalidParameterCombination < Error; end - # Specified reservation ID does not exist. - class InvalidReservationIDNotFound < Error #:nodoc: - end + # EC2 : An unknown parameter was passed as an argument + class UnknownParameter < Error; 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 + # EC2 : 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 + class InvalidUserIDMalformed < Error; end - # The value of an item added to, or removed from, an image attribute is invalid. - class InvalidAMIAttributeItemValue < Error #:nodoc: - end + # EC2 : The value of an item added to, or removed from, an image attribute is invalid. + class InvalidAMIAttributeItemValue < Error; end - # ELB ERRORS + # ELB : The Load balancer specified was not found. + class LoadBalancerNotFound < Error; end - class LoadBalancerNotFound < Error #:nodoc: - end + # ELB : + class ValidationError < Error; end - class ValidationError < Error #:nodoc: - end + # ELB : + class DuplicateLoadBalancerName < Error; end - class DuplicateLoadBalancerName < Error #:nodoc: - end + # ELB : + class TooManyLoadBalancers < Error; end - class TooManyLoadBalancers < Error #:nodoc: - end + # ELB : + class InvalidInstance < Error; end - class InvalidInstance < Error #:nodoc: - end + # ELB : + class InvalidConfigurationRequest < Error; end - class InvalidConfigurationRequest < Error #:nodoc: - end + # Server : Internal AWS EC2 Error. + class InternalError < Error; end - # AWS EC2 SERVER ERROR CODES + # Server : There are not enough available instances to satisfy your minimum request. + class InsufficientInstanceCapacity < Error; end - # Internal AWS EC2 Error. - class InternalError < Error #:nodoc: - end + # Server : The server is overloaded and cannot handle the request. + class Unavailable < Error; 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 - - class SignatureDoesNotMatch < Error #:nodoc: - end + # Server : The provided signature does not match. + class SignatureDoesNotMatch < Error; end end + lib/AWS/exceptions.rb @@ -1,61 +1,21 @@ -#-- -# Amazon Web Services EC2 Query API Ruby library -# -# Ruby Gem Name:: amazon-ec2 -# Author:: Glenn Rempe (mailto:glenn@rempe.us) -# Copyright:: Copyright (c) 2007-2008 Glenn Rempe -# License:: Distributes under the same terms as Ruby -# Home:: http://github.com/grempe/amazon-ec2/tree/master -#++ - -# This allows us to access hash values as if they were methods -# e.g. foo[:bar] can be accessed as foo.bar - -class Hash - def method_missing(meth, *args, &block) - if args.size == 0 - self[meth.to_s] || self[meth.to_sym] - end - end -end - module AWS - # The make_request() and aws_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. - - begin - require 'xmlsimple' unless defined? XmlSimple - rescue Exception => e - require 'xml-simple' unless defined? XmlSimple - end - class Response + # Parse the XML response from AWS + # + # @option options [String] :xml The XML response from AWS that we want to parse + # @option options [Hash] :parse_options Override the options for XmlSimple. + # @return [Hash] the input :xml converted to a custom Ruby Hash by XmlSimple. def self.parse(options = {}) options = { :xml => "", :parse_options => { 'forcearray' => ['item', 'member'], 'suppressempty' => nil, 'keeproot' => false } }.merge(options) - - # NOTE: Parsing the response as a nested set of Response objects was extremely - # memory intensive and appeared to leak (the memory was not freed on subsequent requests). - # It was changed to return the raw XmlSimple response. response = XmlSimple.xml_in(options[:xml], options[:parse_options]) - - return response end end # class Response end # module AWS + lib/AWS/responses.rb @@ -8,6 +8,9 @@ # Home:: http://github.com/grempe/amazon-ec2/tree/master #++ +require 'rubygems' +gem 'test-unit' + %w[ test/unit test/spec mocha ].each { |f| begin require f @@ -17,3 +20,4 @@ } require File.dirname(__FILE__) + '/../lib/AWS' + test/test_helper.rb 25639d2eb99dd3e4bd76ebe09baa5e824dab5491 Glenn Rempe glenn@rempe.us http://github.com/grempe/amazon-ec2/commit/ffc499d124a3f9799de9ab98ef469ca3be44a019 ffc499d124a3f9799de9ab98ef469ca3be44a019 2009-08-20T19:32:44-07:00 2009-08-20T19:32:44-07:00 Updated all docs to use YARD doc generator and meta tags. 280a9659b4dc4456a803e1f18c6b4c12ffb01ce2 Glenn Rempe glenn@rempe.us