aws-sdk 1.0.0

data/lib/aws/ec2/tagged_item.rb

@@ -0,0 +1,87 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/ec2/resource_tag_collection'
+
+module AWS
+  class EC2
+    module TaggedItem
+
+      # Adds a single tag with an optional tag value.
+      #
+      #   # adds a tag with the key production
+      #   resource.tag('production')
+      #
+      #   # adds a tag with the optional value set to production
+      #   resource.tag('role', :value => 'webserver')
+      #
+      # @param [String] key The name of the tag to add.
+      # @param [Hash] options
+      # @option options [String] :value An optional tag value.
+      # @return [Tag] The tag that was created.
+      def add_tag key, options = {}
+        client.create_tags({
+          :resources => [id], 
+          :tags => [{ :key => key, :value => options[:value].to_s }],
+        })
+        Tag.new(self, key, options.merge(:config => config))
+      end
+      alias_method :tag, :add_tag
+
+      # Deletes all tags associated with this EC2 resource.
+      # @return [nil]
+      def clear_tags
+        client.delete_tags(:resources => [self.id])
+        nil
+      end
+
+      # Returns a collection that represents only tags belonging to
+      # this resource.
+      #
+      # @example Manipulating the tags of an EC2 instance
+      #  i = ec2.instances["i-123"]
+      #  i.tags.to_h                  # => { "foo" => "bar", ... }
+      #  i.tags.clear
+      #  i.tags.stage = "production"
+      #  i.tags.stage                 # => "production"
+      #
+      # @return [ResourceTagCollection] A collection of tags that
+      #   belong to this resource.
+      #
+      def tags
+        ResourceTagCollection.new(self, :config => config)
+      end
+
+      # @private
+      def cached_tags
+        if cache = AWS.response_cache
+          cache.select(describe_call_name.to_sym).each do |resp|
+            if obj = find_in_response(resp)
+              return obj.tag_set.inject({}) do |hash, tag|
+                hash[tag.key] = tag.value
+                hash
+              end
+            end
+          end
+        end
+        nil
+      end
+
+      # @private
+      def tagging_resource_type
+        Inflection.ruby_name(self.class.to_s).tr("_","-")
+      end
+
+    end
+  end
+end

data/lib/aws/ec2/volume.rb

@@ -0,0 +1,190 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/ec2/resource'
+require 'aws/ec2/tagged_item'
+require 'aws/ec2/availability_zone'
+require 'aws/ec2/attachment'
+require 'aws/ec2/attachment_collection'
+
+module AWS
+  class EC2
+
+    # Represents an Amazon EBS volume.
+    #
+    # @example Create an empty 15GiB volume and attach it to an instance
+    #  volume = ec2.volumes.create(:size => 15,
+    #                              :availability_zone => "us-east-1a")
+    #  attachment = volume.attach_to(ec2.instances["i-123"], "/dev/sdf")
+    #  sleep 1 until attachment.status != :attaching
+    #
+    # @example Remove all attachments from a volume and then delete it
+    #  volume.attachments.each do |attachment|
+    #    attachment.delete(:force => true)
+    #  end
+    #  sleep 1 until volume.status == :available
+    #  volume.delete
+    #
+    # @attr_reader [Symbol] status The status of the volume.
+    #   Possible values:
+    #
+    #   * +:creating+
+    #   * +:available+
+    #   * +:in_use+
+    #   * +:deleting+
+    #   * +:deleted+
+    #   * +:error+
+    #
+    # @attr_reader [Integer] size The size of the volume in
+    #   gigabytes.
+    #
+    # @attr_reader [AvailabilityZone] availability_zone Availability
+    #   Zone in which the volume was created.
+    #
+    # @attr_reader [Time] create_time The time at which the volume
+    #   was created.
+    class Volume < Resource
+
+      include TaggedItem
+
+      attr_reader :id
+
+      # @private
+      def initialize(id, opts = {})
+        @id = id
+        super(opts)
+      end
+
+      # Deletes the volume.
+      def delete
+        client.delete_volume(:volume_id => id)
+      end
+
+      # @return [Snapshot] A new snapshot created from the volume.
+      #
+      # @param [String] description An optional description of the
+      #   snapshot.  May be up to 255 characters in length.
+      def create_snapshot(description = nil)
+        opts = { :volume => self }
+        opts[:description] = description if description
+        SnapshotCollection.new(:config => config).
+          create(opts)
+      end
+
+      # Attaches the volume to an instance.
+      #
+      # @param [Instance] instance The instance to which the volume
+      #   attaches. The volume and instance must be within the same
+      #   Availability Zone and the instance must be running.
+      #
+      # @param [String] device How the device is exposed to the
+      #   instance (e.g., /dev/sdh, or xvdh).
+      #
+      # @return [Attachment] An object representing the attachment,
+      #   which you can use to query the attachment status.
+      def attach_to(instance, device)
+        resp = client.attach_volume(:volume_id => id,
+                                    :instance_id => instance.id,
+                                    :device => device)
+        Attachment.new(self,
+                       Instance.new(resp.instance_id),
+                       resp.device,
+                       :config => config)
+      end
+      alias_method :attach, :attach_to
+
+      # Detaches the volume from an instance.
+      #
+      # @param [Instance] instance The instance to detach from.
+      #
+      # @param [String] device The device name.
+      #
+      # @param [Hash] opts Additional options for detaching the
+      #   volume.
+      #
+      # @option opts [Boolean] :force Forces detachment if the
+      #   previous detachment attempt did not occur cleanly (logging
+      #   into an instance, unmounting the volume, and detaching
+      #   normally). This option can lead to data loss or a
+      #   corrupted file system. Use this option only as a last
+      #   resort to detach a volume from a failed instance. The
+      #   instance will not have an opportunity to flush file system
+      #   caches or file system metadata. If you use this option,
+      #   you must perform file system check and repair procedures.
+      def detach_from(instance, device, opts = {})
+        a = Attachment.new(self,
+                           Instance.new(instance.id),
+                           device,
+                           :config => config)
+        a.delete
+        a
+      end
+
+      # @return [AttachmentCollection] The collection of attachments
+      #   that involve this volume.
+      def attachments
+        AttachmentCollection.new(self, :config => config)
+      end
+
+      # @return [Boolean] True if the volume exists.
+      def exists?
+        resp =
+          client.describe_volumes(:filters => [{ :name => 'volume-id',
+                                                 :values => [id] }]) and
+          resp.volume_index.key?(id)
+      end
+
+      describe_call_attribute :status, :to_sym => true
+      alias_method :state, :status
+
+      describe_call_attribute :snapshot_id
+
+      # @return [Snapshot] Snapshot from which the volume was created
+      #   (may be nil).
+      def snapshot;
+        if snapshot_id = self.snapshot_id
+          Snapshot.new(snapshot_id, :config => config)
+        end
+      end
+
+      describe_call_attribute :size do
+        translate_output { |value| value.to_i if value }
+      end
+
+      describe_call_attribute :availability_zone, :getter => :availability_zone_name
+
+      def availability_zone
+        if name = availability_zone_name
+          AvailabilityZone.new(name, :config => config)
+        end
+      end
+
+      describe_call_attribute :create_time
+
+      describe_call_attribute :attachment_set
+
+      populate_from :create_volume do |resp|
+        attributes_from_response_object(resp) if
+          resp.volume_id == id
+      end
+
+      # @private
+      protected
+      def find_in_response(resp)
+        resp.volume_index[id]
+      end
+
+    end
+
+  end
+end

data/lib/aws/ec2/volume_collection.rb

@@ -0,0 +1,95 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/ec2/collection'
+require 'aws/ec2/tagged_collection'
+require 'aws/ec2/volume'
+
+module AWS
+  class EC2
+
+    # Represents a collection of Amazon EBS volumes.  Typically you
+    # should get an instance of this class by calling {EC2#volumes}.
+    #
+    # @example Create an empty 15GiB volume
+    #  ec2.volumes.create(:size => 15,
+    #                     :availability_zone => "us-east-1a")
+    #
+    # @example Get a volume by ID
+    #  volume = ec2.volumes["vol-123"]
+    #  volume.exists?
+    #
+    # @example Get a map of volume IDs to volume status
+    #   ec2.volumes.inject({}) { |m, v| m[i.id] = v.status; m }
+    #   # => { "vol-12345678" => :available, "vol-87654321" => :in_use }
+    class VolumeCollection < Collection
+
+      include TaggedCollection
+
+      # @yield [Instance] Yields each volume in the collection.
+      # @return [nil]
+      def each(&block)
+        resp = filtered_request(:describe_volumes)
+        resp.volume_set.each do |v|
+          volume = Volume.new(v.volume_id, :config => config)
+          yield(volume)
+        end
+        nil
+      end
+
+      # Creates a new Amazon EBS volume that any Amazon EC2 instance
+      # in the same Availability Zone can attach to. For more
+      # information about Amazon EBS, go to the {Amazon Elastic
+      # Compute Cloud User
+      # Guide}[http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/index.html?using-ebs.html].
+      #
+      # @return [Volume] An object representing the new volume.
+      #
+      # @param [Hash] opts Options for creating the volume.
+      #   +:availability_zone+ and one of +:size+, +:snapshot+, or
+      #   +:snapshot_id+ is required.
+      #
+      # @option opts [Integer] :size The size of the volume, in
+      #   GiBs.  Valid values: 1 - 1024.  If +:snapshot+ or
+      #   +:snapshot_id+ is specified, this defaults to the size of
+      #   the specified snapshot.
+      #
+      # @option opts [Snapshot] :snapshot The snapshot from which to
+      #   create the new volume.
+      #
+      # @option opts [String] :snapshot_id The ID of the snapshot
+      #   from which to create the new volume.
+      #
+      # @option opts [String, AvailabilityZone] :availability_zone
+      #   The Availability Zone in which to create the new volume.
+      #   To get a list of the availability zones you can use, see
+      #   {EC2#availability_zones}.
+      # @return [Volume]
+      def create(opts = {})
+        if snapshot = opts.delete(:snapshot)
+          opts[:snapshot_id] = snapshot.id
+        end
+        resp = client.create_volume(opts)
+        Volume.new(resp.volume_id, :config => config)
+      end
+
+      # @private
+      protected
+      def member_class
+        Volume
+      end
+
+    end
+
+  end
+end

data/lib/aws/errors.rb

@@ -0,0 +1,129 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'thread'
+require 'aws/xml_grammar'
+
+module AWS
+  module Errors
+
+    # Base class for the two service error classes:
+    #
+    # * {ClientError}
+    # * {ServerError}
+    #
+    # When interacting with Amazon AWS services, you will sometimes 
+    # receive a non-200 level response.  These http responses are treated
+    # as errors.
+    # 
+    # == Client Errors
+    #
+    # Errors in the three and four hundreds are client errors ({ClientError}).
+    # A client error should not be resent without changes.  The body of the
+    # http response (the error #message) should give more information about
+    # the nature of the problem.
+    #
+    # == Server Errors
+    # 
+    # A 500 level error typically indicates the service is having an issue.
+    #
+    # Requests that generate service errors are automatically retried with
+    # an exponential backoff.  If the service still fails to respond with 
+    # a 200 after 3 retries the error is raised.
+    #
+    class Base < StandardError
+
+      # @return [Http::Request] The low level http request that caused the
+      #   error to be raised.
+      attr_reader :http_request
+
+      # @return [Http::Response] The low level http response from the service
+      #   that wrapped the service error.
+      attr_reader :http_response
+
+      def initialize http_request, http_response, message = http_response.body
+        @http_request = http_request
+        @http_response = http_response
+        super(message)
+      end
+
+    end
+
+    # @private
+    module ExceptionMixinClassMethods
+      def new(*args)
+        e = Base.new(*args)
+        e.extend(self)
+        e
+      end
+    end
+
+    # Raised when an error occurs as a result of bad client
+    # behavior, most commonly when the parameters passed to a method
+    # are somehow invalid.  Other common cases:
+    #
+    # * Throttling errors
+    # * Bad credentials
+    # * No permission to do the requested operation
+    # * Limits exceeded (e.g. too many buckets)
+    #
+    module ClientError
+      extend ExceptionMixinClassMethods
+    end
+
+    # Raised when an AWS service is unable to handle the request.  These
+    # are automatically retired.  If after 3 retries the request is still
+    # failing, then the error is raised.
+    module ServerError
+      extend ExceptionMixinClassMethods
+    end
+
+    # @private
+    module ModeledError
+
+      # @return [String] The error message given by the AWS service.
+      attr_accessor :message
+
+      # @return [Integer] The HTTP status code returned by the AWS service.
+      attr_reader :code
+
+      def initialize(req, resp)
+        super(req, resp, message)
+        include_error_type
+        parse_body(resp.body)
+      end
+
+      def include_error_type
+        if http_response.status >= 500
+          extend ServerError
+        else
+          extend ClientError
+        end
+      end
+
+      def parse_body(body)
+        error_grammar.parse(body, :context => self)
+      end
+
+      def extract_message(body)
+        error_grammar.parse(body).message
+      end
+
+      def error_grammar
+        self.class::BASE_ERROR_GRAMMAR
+      end
+
+    end
+
+  end
+end