mss-sdk 1.0.0

data/lib/mss/errors.rb

@@ -0,0 +1,161 @@
+# Copyright 2011-2013 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
+#
+#
+# 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.
+
+module MSS
+
+  # # Errors
+  #
+  # There are two basic types of errors:
+  #
+  # * {ClientError}
+  # * {ServerError}
+  #
+  # ## 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.
+  #
+  module Errors
+
+    # Base class for all errors returned by the service.
+    class Base < StandardError
+
+      # @overload new(error_message)
+      #   @param [String] error_message The body of the error message
+      #
+      # @overload new(http_request, http_response, code = nil, message = nil)
+      #   @param [Http::Request] http_request
+      #   @param [Http::Response] http_response
+      #   @param [String] code (nil)
+      #   @param [String] message (nil)
+      #
+      def initialize req = nil, resp = nil, code = nil, message = nil
+        if req.is_a?(String) or req.nil?
+          super(req)
+        else
+          @http_request = req
+          @http_response = resp
+          @code = code
+          include_error_type
+          super(message || http_response.body)
+        end
+      end
+
+      # @return [String] The response code given by the service.
+      attr_reader :code
+
+      # @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
+
+      protected
+
+      # Extends the error object with {ServerError} or {ClientError}.
+      # This indicates if the request should be retried (server errors)
+      # or not (client errors).
+      def include_error_type
+        if http_response.status >= 500
+          extend ServerError
+        else
+          extend ClientError
+        end
+      end
+
+    end
+
+    # Provides the ability to instantiate instances of {ServerError} and
+    # {ClientError}.
+    # @api 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 MSS 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
+
+    # Raised when MSS credentials could not be found.
+    class MissingCredentialsError < StandardError
+
+      def initialize msg = nil
+        msg ||= <<-MSG
+
+Missing Credentials.
+
+Unable to find MSS credentials.  You can configure your MSS credentials
+a few different ways:
+
+* Call MSS.config with :access_key_id and :secret_access_key
+
+* Export MSS_ACCESS_KEY_ID and MSS_SECRET_ACCESS_KEY to ENV
+
+* On EC2 you can run instances with an IAM instance profile and credentials
+  will be auto loaded from the instance metadata service on those
+  instances.
+
+* Call MSS.config with :credential_provider.  A credential provider should
+  either include MSS::Core::CredentialProviders::Provider or respond to
+  the same public methods.
+
+= Ruby on Rails
+
+In a Ruby on Rails application you may also specify your credentials in
+the following ways:
+
+* Via a config initializer script using any of the methods mentioned above
+  (e.g. RAILS_ROOT/config/initializers/mss-sdk.rb).
+
+* Via a yaml configuration file located at RAILS_ROOT/config/mss.yml.
+  This file should be formated like the default RAILS_ROOT/config/database.yml
+  file.
+
+MSG
+        super(msg)
+      end
+    end
+
+  end
+end

data/lib/mss/rails.rb

@@ -0,0 +1,194 @@
+# Copyright 2011-2013 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
+#
+#
+# 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 'yaml'
+
+module MSS
+
+  if Object.const_defined?(:Rails) and Rails.const_defined?(:Railtie)
+
+    # @api private
+    class Railtie < Rails::Railtie
+
+      # configure our plugin on boot. other extension points such
+      # as configuration, rake tasks, etc, are also available
+      initializer "mss-sdk.initialize" do |app|
+        MSS::Rails.setup
+      end
+    end
+
+  end
+
+  # A handful of useful Rails integration methods.
+  #
+  # If you require this gem inside a Rails application (via config.gem
+  # for rails 2 and bundler for rails 3) then {setup} is called
+  # automatically.
+  module Rails
+
+    # Adds extra functionality to Rails.
+    #
+    # Normally this method is invoked automatically when you require this
+    # gem in a Rails Application:
+    #
+    # Rails 3+ (RAILS_ROOT/Gemfile)
+    #
+    #     gem 'mss-sdk'
+    #
+    # Rails 2.1 - 2.3 (RAILS_ROOT/config/environment.rb)
+    #
+    #     config.gem 'mss-sdk'
+    #
+    # @return [nil]
+    def self.setup
+      load_yaml_config
+      add_action_mailer_delivery_method
+      log_to_rails_logger
+      nil
+    end
+
+    # Loads MSS configuration options from `RAILS_ROOT/config/mss.yml`.
+    #
+    # This configuration file is optional.  You can omit this file and instead
+    # use ruby to configure MSS inside a configuration initialization script
+    # (e.g. RAILS_ROOT/config/intializers/mss.rb).
+    #
+    # If you have a yaml configuration file it should be formatted like the
+    # standard `database.yml` file in a Rails application.  This means there
+    # should be one section for Rails environment:
+    #
+    #     development:
+    #       access_key_id: YOUR_ACCESS_KEY_ID
+    #       secret_access_key: YOUR_SECRET_ACCESS_KEY
+    #       simple_db_consistent_reads: false
+    #
+    #     production:
+    #       access_key_id: YOUR_ACCESS_KEY_ID
+    #       secret_access_key: YOUR_SECRET_ACCESS_KEY
+    #       simple_db_consistent_reads: true
+    #
+    # You should also consider DRYing up your configuration file using
+    # YAML references:
+    #
+    #     development:
+    #       access_key_id: YOUR_ACCESS_KEY_ID
+    #       secret_access_key: YOUR_SECRET_ACCESS_KEY
+    #       simple_db_consistent_reads: false
+    #
+    #     production:
+    #       <<: *development
+    #       simple_db_consistent_reads: true
+    #
+    # The yaml file will also be ERB parsed so you can use ruby inside of it:
+    #
+    #     development:
+    #       access_key_id: YOUR_ACCESS_KEY_ID
+    #       secret_access_key: <%= read_secret_from_a_secure_location %>
+    #       simple_db_consistent_reads: false
+    #
+    #     production:
+    #       <<: *development
+    #       simple_db_consistent_reads: true
+    #
+    def self.load_yaml_config
+
+      path = Pathname.new("#{rails_root}/config/mss.yml")
+
+      if File.exist?(path)
+        cfg = YAML::load(ERB.new(File.read(path)).result)
+        unless cfg[rails_env]
+          raise "config/mss.yml is missing a section for `#{rails_env}`"
+        end
+        MSS.config(cfg[rails_env])
+      end
+
+    end
+
+    # Adds a delivery method to ActionMailer that uses
+    # {MSS::SimpleEmailService}.
+    #
+    # Once you have an SES delivery method you can configure Rails to
+    # use this for ActionMailer in your environment configuration
+    # (e.g.  RAILS_ROOT/config/environments/production.rb)
+    #
+    #     config.action_mailer.delivery_method = :amazon_ses
+    #
+    # ### Defaults
+    #
+    # Normally you don't need to call this method.  By default a delivery method
+    # named `:amazon_ses` is added to ActionMailer::Base.  This delivery method
+    # uses your default configuration (#{MSS.config}).
+    #
+    # ### Custom SES Options
+    #
+    # If you need to supply configuration values for SES that are different than
+    # those in {MSS.config} then you can pass those options:
+    #
+    #     MSS::Rails.add_action_mailer_delivery_method(:ses, custom_options)
+    #
+    # @param [Symbol] name (:amazon_ses) The name of the delivery
+    #   method.  The name used here should be the same as you set in
+    #   your environment config.  If you name the delivery method
+    #   `:amazon_ses` then you could do something like this in your
+    #   config/environments/ENV.rb file:
+    #
+    #       config.action_mailer.delivery_method = :amazon_ses
+    #
+    # @param [Hash] options A hash of options that are passes to
+    #   {MSS::SimpleEmailService#new} before delivering email.
+    #
+    # @return [nil]
+    #
+    def self.add_action_mailer_delivery_method name = :amazon_ses, options = {}
+
+      if ::Rails.version.to_s >= '3.0'
+        ActiveSupport.on_load(:action_mailer) do
+          self.add_delivery_method(name, MSS::SimpleEmailService, options)
+        end
+      elsif defined?(::ActionMailer)
+        amb = ::ActionMailer::Base
+        amb.send(:define_method, "perform_delivery_#{name}") do |mail|
+          MSS::SimpleEmailService.new(options).send_raw_email(mail)
+        end
+      end
+
+      nil
+
+    end
+
+    # Configures MSS to log to the Rails default logger.
+    # @return [nil]
+    def self.log_to_rails_logger
+      MSS.config(:logger => rails_logger)
+      nil
+    end
+
+    # @api private
+    protected
+    def self.rails_env
+      ::Rails.respond_to?(:env) ? ::Rails.env : RAILS_ENV
+    end
+
+    # @api private
+    protected
+    def self.rails_root
+      ::Rails.respond_to?(:root) ? ::Rails.root.to_s : RAILS_ROOT
+    end
+
+    # @api private
+    protected
+    def self.rails_logger
+      ::Rails.respond_to?(:logger) ? ::Rails.logger : ::RAILS_DEFAULT_LOGGER
+    end
+
+  end
+end

data/lib/mss/s3/access_control_list.rb

@@ -0,0 +1,262 @@
+# Copyright 2011-2013 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
+#
+#
+# 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.
+
+module MSS
+  class S3
+
+    # Represents an access control list for S3 objects and buckets.  For example:
+    #
+    #     acl = AccessControlList.new
+    #     acl.grant(:full_control).
+    #       to(:canonical_user_id => "8a6925ce4adf588a4f21c32aa379004fef")
+    #     acl.to_xml                   # => '<AccessControlPolicy>...'
+    #
+    # You can also construct an AccessControlList from a hash:
+    #
+    #     AccessControlList.new(
+    #       :owner => { :id => "8a6925ce4adf588a4f21c32aa379004fef" },
+    #       :grants => [{
+    #         :grantee => { :canonical_user_id => "8a6925ce4adf588a4f21c32aa379004fef" },
+    #         :permission => :full_control,
+    #       }]
+    #     )
+    #
+    # @see ACLObject
+    #
+    # @attr [AccessControlList::Owner] owner The owner of the access
+    #   control list.  You can set this as a hash, for example:
+    #    acl.owner = { :id => '8a6925ce4adf588a4f21c32aa379004fef' }
+    #   This attribute is required when setting an ACL.
+    #
+    # @attr [list of AccessControlList::Grant] grants The list of
+    #   grants.  You can set this as a list of hashes, for example:
+    #
+    #       acl.grants = [{
+    #         :grantee => { :canonical_user_id => "8a6925ce4adf588a4f21c32aa379004fef" },
+    #         :permission => :full_control,
+    #       }]
+    class AccessControlList
+
+      # Represents an ACL owner.  In the default ACL, this is the
+      # bucket owner.
+      #
+      # @attr [String] id The canonical user ID of the ACL owner.
+      #   This attribute is required when setting an ACL.
+      #
+      # @attr [String] display_name The display name of the ACL
+      #   owner.  This value is ignored when setting an ACL.
+      class Owner
+        include ACLObject
+
+        string_attr "ID", :required => true
+        string_attr "DisplayName"
+      end
+
+      # Represents a user who is granted some kind of permission
+      # through a Grant.  There are three ways to specify a grantee:
+      #
+      # * You can specify the canonical user ID, for example.  When
+      #   you read an ACL from S3, all grantees will be identified
+      #   this way, and the display_name attribute will also be provided.
+      #
+      #       Grantee.new(:canonical_user_id => "8a6925ce4adf588a4f21c32aa379004fef")
+      #
+      # * You can specify the e-mail address of an MSS customer, for example:
+      #
+      #       Grantee.new(:amazon_customer_email => 'foo@example.com')
+      #
+      # * You can specify a group URI, for example:
+      #
+      #        Grantee.new(:group_uri => 'http://acs.amazonmss.com/groups/global/AllUsers')
+      #
+      #   For more details about group URIs, see:
+      #
+      # When constructing a grantee, you must provide a value for
+      # exactly one of the following attributes:
+      #
+      # * `amazon_customer_email`
+      # * `canonical_user_id`
+      # * `group_uri`
+      #
+      # @attr [String] amazon_customer_email The e-mail address of
+      #   an MSS customer.
+      #
+      # @attr [String] canonical_user_id The canonical user ID of an
+      #   MSS customer.
+      #
+      # @attr [String] group_uri A URI that identifies a particular
+      #   group of users.
+      #
+      # @attr [String] display_name The display name associated with
+      #   the grantee.  This is provided by S3 when reading an ACL.
+      class Grantee
+        include ACLObject
+
+        SIGNAL_ATTRIBUTES = [
+          :amazon_customer_email,
+          :canonical_user_id,
+          :group_uri,
+          :uri,
+        ]
+
+        string_attr "EmailAddress", :method_name => "amazon_customer_email"
+        string_attr "ID", :method_name => "canonical_user_id"
+        string_attr "URI", :method_name => "group_uri"
+        string_attr "URI", :method_name => "uri"
+        string_attr "DisplayName"
+
+        # (see ACLObject#validate!)
+        def validate!
+          attr = signal_attribute
+          raise "missing amazon_customer_email, canonical_user_id, "+
+            "or group_uri" unless attr
+          raise "display_name is invalid with #{attr}" if
+            attr != :canonical_user_id and display_name
+        end
+
+        # @api private
+        def stag
+          if attr = signal_attribute
+            super + " xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"" +
+              " xsi:type=\"#{type_for_attr(attr)}\""
+          else
+            super
+          end
+        end
+
+        # @api private
+        def signal_attribute
+          SIGNAL_ATTRIBUTES.find { |att| send(att) }
+        end
+
+        # @api private
+        def type_for_attr(attr)
+          {
+            :amazon_customer_email => "AmazonCustomerByEmail",
+            :canonical_user_id => "CanonicalUser",
+            :group_uri => "Group",
+            :uri => "Group",
+          }[attr]
+        end
+
+      end
+
+      # Represents the permission being granted in a Grant object.
+      # Typically you will not need to construct an instance of this
+      # class directly.
+      # @see Grant#permission
+      class Permission
+        include ACLObject
+
+        # The permission expressed as a symbol following Ruby
+        # conventions.  For example, S3's FULL_CONTROL permission
+        # will be returned as `:full_control`.
+        attr_reader :name
+
+        # @api private
+        def initialize(name)
+          raise "expected string or symbol" unless
+            name.respond_to?(:to_str) or name.respond_to?(:to_sym)
+          @name = name.to_sym
+        end
+
+        def body_xml
+          name.to_s.upcase
+        end
+
+      end
+
+      # Represents a single grant in an ACL.  Both `grantee` and
+      # `permission` are required for each grant when setting an
+      # ACL.
+      #
+      # See
+      # for more information on how grantees and permissions are
+      # interpreted by S3.
+      #
+      # @attr [Grantee] grantee The user or users who are granted
+      #   access according to this grant.  You can specify this as a
+      #   hash:
+      #
+      #       grant.grantee = { :amazon_customer_email => "foo@example.com" }
+      #
+      # @attr [Permission or Symbol] permission The type of
+      #   permission that is granted by this grant.  Valid values are:
+      #   * `:read`
+      #   * `:write`
+      #   * `:read_acp`
+      #   * `:write_acp`
+      #   * `:full_control`
+      class Grant
+
+        include ACLObject
+
+        object_attr Grantee, :required => true
+        object_attr Permission, :required => true, :cast => Symbol
+
+      end
+
+      include ACLObject
+
+      # @api private
+      def stag
+        super()+" xmlns=\"http://s3.amazonmss.com/doc/2006-03-01/\""
+      end
+
+      # @api private
+      def element_name
+        "AccessControlPolicy"
+      end
+
+      class GrantBuilder
+
+        # @api private
+        def initialize(acl, grant)
+          @acl = acl
+          @grant = grant
+        end
+
+        # Specifies the grantee.
+        #
+        # @param [Grantee or Hash] grantee A Grantee object or hash;
+        #   for example:
+        #
+        #       acl.grant(:full_control).to(:amazon_customer_email => "foo@example.com")
+        def to(grantee)
+          @grant.grantee = grantee
+          @acl.grants << @grant
+        end
+
+      end
+
+      # Convenience method for constructing a new grant and adding
+      # it to the ACL.
+      #
+      # @example
+      #
+      #   acl.grants.size # => 0
+      #   acl.grant(:full_control).to(:canonical_user_id => "8a6925ce4adf588a4f21c32aa379004fef")
+      #   acl.grants.size # => 1
+      #
+      # @return [GrantBuilder]
+      def grant(permission)
+        GrantBuilder.new(self, Grant.new(:permission => permission))
+      end
+
+      object_attr Owner, :required => true
+      object_list_attr("AccessControlList", Grant,
+                       :required => true, :method_name => :grants)
+
+    end
+
+  end
+end