mss-sdk 1.0.0

data/lib/mss/s3/acl_object.rb

@@ -0,0 +1,263 @@
+# 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 'rexml/text'
+
+module MSS
+  class S3
+
+    # Common methods for AccessControlList and related objects.
+    module ACLObject
+
+      # @api private
+      def initialize(opts = {}); end
+
+      # @api private
+      def body_xml; ""; end
+
+      # @api private
+      def stag
+        element_name
+      end
+
+      # @api private
+      def element_name
+        self.class.name[/::([^:]*)$/, 1]
+      end
+
+      # Returns the XML representation of the object.  Generally
+      # you'll want to call this on an AccessControlList object,
+      # which will yield an XML representation of the ACL that you
+      # can send to S3.
+      def to_s
+        if body_xml.empty?
+          "<#{stag}/>"
+        else
+          "<#{stag}>#{body_xml}</#{element_name}>"
+        end
+      end
+
+      # (see #to_s)
+      def to_xml
+        to_s
+      end
+
+      # Returns true if and only if this object is valid according
+      # to S3's published ACL schema.  In particular, this will
+      # check that all required attributes are provided and that
+      # they are of the correct type.
+      def valid?
+        validate!
+      rescue => e
+        false
+      else
+        true
+      end
+
+      # Raises an exception unless this object is valid according to
+      # S3's published ACL schema.
+      # @see #valid?
+      def validate!; end
+
+      # @api private
+      def validate_input(name, value, context = nil)
+        send("validate_#{name}_input!", value, context)
+      end
+
+      # @api private
+      module ClassMethods
+
+        def string_attr(element_name, options = {})
+          method_name = options[:method_name] ||
+            Core::Inflection.ruby_name(element_name)
+
+          attr_accessor(method_name)
+          setter_option(method_name)
+          string_input_validator(method_name)
+          validate_string(method_name) if options[:required]
+          body_xml_string_content(element_name, method_name)
+        end
+
+        def object_attr(klass, options = {})
+          base_name = klass.name[/::([^:]*)$/, 1]
+          method_name = Core::Inflection.ruby_name(base_name)
+          cast = options[:cast] || Hash
+
+          attr_reader(method_name)
+          setter_option(method_name)
+          object_setter(klass, method_name, cast)
+          object_input_validator(klass, base_name, method_name, cast)
+          validate_object(method_name) if options[:required]
+          body_xml_content(method_name)
+        end
+
+        def object_list_attr(list_element, klass, options = {})
+          base_name = klass.name[/::([^:]*)$/, 1]
+          method_name = Core::Inflection.ruby_name(options[:method_name].to_s || list_element)
+          default_value = nil
+          default_value = [] if options[:required]
+
+          attr_reader(method_name)
+          setter_option(method_name) { [] if options[:required] }
+          object_list_setter(klass, method_name)
+          object_list_input_validator(klass, base_name, method_name)
+          validate_list(method_name)
+          body_xml_list_content(list_element, method_name)
+        end
+
+        def setter_option(method_name)
+          Core::MetaUtils.class_extend_method(self, :initialize) do |*args|
+            opts = args.last || {}
+            instance_variable_set("@#{method_name}", yield) if block_given?
+            key = method_name.to_sym
+
+            if opts.has_key?(key)
+              value = opts[key]
+              validate_input(method_name, value, "for #{method_name} option")
+              self.send("#{method_name}=", value)
+            end
+            super(opts)
+          end
+        end
+
+        def string_input_validator(method_name)
+          input_validator(method_name) do |value, context|
+            raise ArgumentError.new("expected string"+context) unless
+              value.respond_to?(:to_str)
+          end
+        end
+
+        def object_input_validator(klass, base_name, method_name, cast)
+          input_validator(method_name) do |value, context|
+            if value.kind_of?(cast)
+              klass.new(value).validate!
+            else
+              raise ArgumentError.new("expected #{base_name} object or hash"+context) unless
+                value.nil? or value.kind_of? klass
+            end
+          end
+        end
+
+        def object_list_input_validator(klass, base_name, method_name)
+          input_validator(method_name) do |value, context|
+            raise ArgumentError.new("expected array"+context) unless value.kind_of?(Array)
+            value.each do |member|
+              if member.kind_of?(Hash)
+                klass.new(member).validate!
+              else
+                raise ArgumentError.new("expected array#{context} "+
+                                        "to contain #{base_name} objects "+
+                                        "or hashes") unless
+                  member.kind_of? klass
+              end
+            end
+          end
+        end
+
+        def input_validator(method_name, &blk)
+          validator = "__validator__#{blk.object_id}"
+          Core::MetaUtils.class_extend_method(self, validator, &blk)
+          Core::MetaUtils.class_extend_method(self, "validate_#{method_name}_input!") do |*args|
+            (value, context) = args
+            context = " "+context if context
+            context ||= ""
+            send(validator, value, context)
+          end
+        end
+
+        def object_setter(klass, method_name, cast)
+          define_method("#{method_name}=") do |value|
+            validate_input(method_name, value)
+            if value.kind_of?(cast)
+              value = klass.new(value)
+            end
+            instance_variable_set("@#{method_name}", value)
+          end
+        end
+
+        def object_list_setter(klass, method_name)
+          define_method("#{method_name}=") do |value|
+            validate_input(method_name, value)
+            list = value.map do |member|
+              if member.kind_of?(Hash)
+                klass.new(member)
+              else
+                member
+              end
+            end
+            instance_variable_set("@#{method_name}", list)
+          end
+        end
+
+        def validate_string(method_name)
+          Core::MetaUtils.class_extend_method(self, :validate!) do
+            super()
+            raise "missing #{method_name}" unless send(method_name)
+          end
+        end
+
+        def validate_object(method_name)
+          Core::MetaUtils.class_extend_method(self, :validate!) do
+            super()
+            raise "missing #{method_name}" unless send(method_name)
+            send(method_name).validate!
+          end
+        end
+
+        def validate_list(method_name)
+          Core::MetaUtils.class_extend_method(self, :validate!) do
+            super()
+            raise "missing #{method_name}" unless send(method_name)
+            send(method_name).each { |member| member.validate! }
+          end
+        end
+
+        def body_xml_string_content(element_name, method_name)
+          add_xml_child(method_name) do |value|
+            normalized = REXML::Text.normalize(value.to_s)
+            "<#{element_name}>#{normalized}</#{element_name}>"
+          end
+        end
+
+        def body_xml_content(method_name)
+          add_xml_child(method_name) { |value| value.to_s }
+        end
+
+        def body_xml_list_content(list_element, method_name)
+          add_xml_child(method_name) do |list|
+            list_content = list.map { |member| member.to_s }.join
+            if list_content.empty?
+              "<#{list_element}/>"
+            else
+              "<#{list_element}>#{list_content}</#{list_element}>"
+            end
+          end
+        end
+
+        def add_xml_child(method_name)
+          Core::MetaUtils.class_extend_method(self, :body_xml) do
+            xml = super()
+            value = send(method_name)
+            xml += yield(value) if value
+            xml
+          end
+        end
+
+      end
+
+      def self.included(m)
+        m.extend(ClassMethods)
+      end
+
+    end
+  end
+end

data/lib/mss/s3/acl_options.rb

@@ -0,0 +1,200 @@
+# 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 'rexml/document'
+
+module MSS
+  class S3
+
+    # Provides a method to {Bucket} and {S3Object} that parses a wide
+    # range of ACL options.
+    # @api private
+    module ACLOptions
+
+      protected
+
+      # @param [Symbol,String,Hash,AccessControlList] acl Accepts an ACL
+      #   description in one of the following formats:
+      #
+      #   ==== Canned ACL
+      #
+      #   S3 supports a number of canned ACLs for buckets and
+      #   objects.  These include:
+      #
+      #   * `:private`
+      #   * `:public_read`
+      #   * `:public_read_write`
+      #   * `:authenticated_read`
+      #   * `:bucket_owner_read` (object-only)
+      #   * `:bucket_owner_full_control` (object-only)
+      #   * `:log_delivery_write` (bucket-only)
+      #
+      #   Here is an example of providing a canned ACL to a bucket:
+      #
+      #       s3.buckets['bucket-name'].acl = :public_read
+      #
+      #   ==== ACL Grant Hash
+      #
+      #   You can provide a hash of grants.  The hash is composed of grants (keys)
+      #   and grantees (values).  Accepted grant keys are:
+      #
+      #   * `:grant_read`
+      #   * `:grant_write`
+      #   * `:grant_read_acp`
+      #   * `:grant_write_acp`
+      #   * `:grant_full_control`
+      #
+      #   Grantee strings (values) should be formatted like some of the
+      #   following examples:
+      #
+      #       id="8a6925ce4adf588a4532142d3f74dd8c71fa124b1ddee97f21c32aa379004fef"
+      #       uri="http://acs.amazonmss.com/groups/global/AllUsers"
+      #
+      #   You can provide a comma delimited list of multiple grantees in a single
+      #   string.  Please note the use of quotes inside the grantee string.
+      #   Here is a simple example:
+      #
+      #       { :grant_full_control => "emailAddress=\"foo@bar.com\", id=\"abc..mno\"" }
+      #
+      #   See the S3 API documentation for more information on formatting
+      #   grants.
+      #
+      #   ==== AcessControlList Object
+      #
+      #   You can build an ACL using the {AccessControlList} class and
+      #   pass this object.
+      #
+      #       acl = MSS::S3::AccessControlList.new
+      #       acl.grant(:full_control).to(:canonical_user_id => "8a6...fef")
+      #       acl #=> this is acceptible
+      #
+      #   ==== ACL XML String
+      #
+      #   Lastly you can build your own ACL XML document and pass it as a string.
+      #
+      #       <<-XML
+      #         <AccessControlPolicy xmlns="http://s3.amazonmss.com/doc/2006-03-01/">
+      #           <Owner>
+      #             <ID>8a6...fef</ID>
+      #             <DisplayName>owner-display-name</DisplayName>
+      #           </Owner>
+      #           <AccessControlList>
+      #             <Grant>
+      #               <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Canonical User">
+      #                 <ID>8a6...fef</ID>
+      #                 <DisplayName>owner-display-name</DisplayName>
+      #               </Grantee>
+      #               <Permission>FULL_CONTROL</Permission>
+      #             </Grant>
+      #           </AccessControlList>
+      #         </AccessControlPolicy>
+      #       XML
+      #
+      # @return [Hash] Returns a hash of options suitable for
+      #   passing to {Client#put_bucket_acl} and {Client#put_object_acl}
+      #   with a mixture of ACL options.
+      #
+      def acl_options acl
+        case acl
+        when Symbol
+          { :acl => acl.to_s.tr('_', '-') }
+        when String
+          # Strings are either access control policies (xml strings)
+          # or they are canned acls
+          xml?(acl) ?
+            { :access_control_policy => acl } :
+            { :acl => acl }
+        when AccessControlList
+            { :access_control_policy => acl.to_xml }
+        when Hash
+          # Hashes are either grant hashes or constructor args for an
+          # access control list (deprecated)
+          grant_hash?(acl) ?
+            format_grants(acl) :
+            { :access_control_policy => AccessControlList.new(acl).to_xml }
+        else
+          # failed to parse the acl option
+          msg = "expected a canned ACL, AccessControlList object, ACL "
+                "XML string or a grants hash"
+          raise ArgumentError, msg
+        end
+      end
+
+      # @param [Hash] acl_hash
+      # @return [Boolean] Retursn `true` if this hash is a hash of grants.
+      def grant_hash? acl_hash
+        grant_keys = [
+          :grant_read,
+          :grant_write,
+          :grant_read_acp,
+          :grant_write_acp,
+          :grant_full_control,
+        ]
+        acl_hash.keys.all?{|key| grant_keys.include?(key) }
+      end
+
+      # @param [String] acl_string
+      # @return [Boolean] Returns `true` if this string is an xml document.
+      def xml? acl_string
+        begin
+          REXML::Document.new(acl_string).has_elements?
+        rescue
+          false
+        end
+      end
+
+      # @param [Hash] acl_hash
+      # @return [Hash] Returns a hash of grant options suitable for
+      #   passing to the various S3 client methods that accept ACL grants.
+      def format_grants acl_hash
+        grants = {}
+        acl_hash.each_pair do |grant,grantees|
+          grantees = [grantees] unless grantees.is_a?(Array)
+          grants[grant] = grantees.map{|g| format_grantee(g) }.join(', ')
+        end
+        grants
+      end
+
+      def format_grantee grantee
+        case grantee
+        when String then grantee
+        when Hash
+
+          if grantee.keys.count != 1
+            msg = "grantee hashes must have exactly 1 key"
+            raise ArgumentError, msg
+          end
+
+          # A granee hash looks like:
+          #
+          #     { :id => 'abc...fec' }
+          #     { :uri => 'http://abc.com/foo' }
+          #
+          # It needs to look like
+          #
+          #     'id="abc...fec"'
+          #     'uri="http://abc.com/foo"'
+          type, token = grantee.to_a.flatten
+          type = type.to_s.split('_').map{|part| ucfirst(part) }.join
+          "#{type[0,1].downcase}#{type[1..-1]}=\"#{token}\""
+        else
+          raise ArgumentError, "grantees must be a string or a hash"
+        end
+      end
+
+      def ucfirst str
+        str[0,1].upcase + str[1..-1]
+      end
+
+    end
+  end
+end