mss-sdk 1.0.0

data/lib/mss/core/options/json_serializer.rb

@@ -0,0 +1,81 @@
+# 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 'json'
+require 'base64'
+
+module MSS
+  module Core
+    module Options
+
+      # Given a hash of serialization rules, a JSONSerializer can convert
+      # a hash of request options into a JSON document.  The request options
+      # are validated before returning JSON.
+      class JSONSerializer
+
+        # @param [Hash] rules A hash of option rules to validate against.
+        # @param [String,nil] payload_param
+        def initialize rules, payload_param
+          @payload_param = payload_param
+          @rules = @payload_param ? rules[@payload_param][:members] : rules
+        end
+
+        # @return [String] Returns the name of the API operation.
+        attr_reader :operation_name
+
+        # @return [String]
+        attr_reader :namespace
+
+        # @return [Hash]
+        attr_reader :rules
+
+        # @overload serialize!(request_options)
+        #   @param [Hash] request_options A hash of already validated
+        #     request options with normalized values.
+        #   @return [String] Returns an string of the request parameters
+        #     serialized into XML.
+        def serialize request_options
+          request_options = request_options[@payload_param] if @payload_param
+          data = normalize_keys(request_options, rules)
+          if rules.any?{|k,v| v[:location] == 'body' }
+            data = data.values.first
+          end
+          JSON.pretty_generate(data)
+        end
+
+        protected
+
+        def normalize_keys values, rules
+          values.inject({}) do |h,(k,v)|
+            child_rules = rules[k]
+            child_name = child_rules[:name] || Inflection.class_name(k.to_s)
+            h.merge(child_name => normalize_value(v, child_rules))
+          end
+        end
+
+        def normalize_value value, rules
+          case rules[:type]
+          when :hash then normalize_keys(value, rules[:members])
+          when :array then value.map{|v| normalize_value(v, rules[:members]) }
+          when :map
+            value.inject({}) do |h,(k,v)|
+              h.merge(k => normalize_value(v, rules[:members]))
+            end
+          when :blob then Base64.encode64(value.read).strip
+          else value
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/mss/core/options/validator.rb

@@ -0,0 +1,154 @@
+# 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
+  module Core
+    module Options
+
+      # Given a hash of validation rules, a validator validate request
+      # options.  Validations support:
+      #
+      #   * rejecting unknown options
+      #   * ensuring presence of required options
+      #   * validating expected option types (e.g. hash, array, string,
+      #     integer, etc).
+      #
+      # After validating, a hash of request options is returned with
+      # with normalized values (with converted types).
+      class Validator
+
+        # @param [Hash] rules A hash of option rules to validate against.
+        def initialize rules
+          @rules = rules
+        end
+
+        # @return [Hash]
+        attr_reader :rules
+
+        # @overload validate!(request_options)
+        #   @param [Hash] request_options The hash of options to validate.
+        #   @raise [ArgumentError] Raised when the options do not validate.
+        #   @return [Hash]
+        def validate! request_options, rules = @rules
+
+          # Verify all required options are present.
+          rules.each_pair do |opt_name, opt_rules|
+            if opt_rules[:required]
+              unless request_options.key?(opt_name)
+                raise ArgumentError, "missing required option #{opt_name.inspect}"
+              end
+            end
+          end
+
+          request_options.inject({}) do |options, (opt_name, value)|
+
+            # Ensure this is a valid/accepted option
+            unless rules.key?(opt_name)
+              raise ArgumentError, "unexpected option #{opt_name.inspect}"
+            end
+
+            # Validate and convert the value
+            valid_value = validate_value(rules[opt_name], value, opt_name)
+
+            options.merge(opt_name => valid_value)
+
+          end
+        end
+
+        protected
+
+        # Proxies calls to the correct validation method based on the
+        # rules[:type].
+        def validate_value *args
+          send("validate_#{args.first[:type]}", *args)
+        end
+
+        # Ensures the value is a hash and validates the hash context.
+        def validate_hash rules, value, opt_name, context = nil
+          unless value.respond_to?(:to_hash)
+            format_error('hash value', opt_name, context)
+          end
+          validate!(value.to_hash, rules[:members])
+        end
+
+        def validate_map rules, value, opt_name, context = nil
+          unless value.respond_to?(:to_hash)
+            format_error('hash value', opt_name, context)
+          end
+          value.inject({}) do |values,(k,v)|
+            context = "member #{k.inspect} of :#{opt_name}"
+            values[k] = validate_value(rules[:members], v, opt_name, context)
+            values
+          end
+        end
+
+        # Ensures the value is an array (or at least enumerable) and
+        # that the yielded values are valid.
+        def validate_array rules, value, opt_name, context = nil
+          unless value.respond_to?(:each)
+            format_error('enumerable value', opt_name, context)
+          end
+          values = []
+          value.each do |v|
+            context = "member #{values.size} of :#{opt_name}"
+            values << validate_value(rules[:members], v, opt_name, context)
+          end
+          values
+        end
+
+        # Ensures the value is a string.
+        def validate_string rules, value, opt_name, context = nil
+
+          unless value.respond_to?(:to_str)
+            format_error('string value', opt_name, context)
+          end
+
+          rules[:lstrip] ?
+            value.to_str.sub(/^#{rules[:lstrip]}/, '') :
+            value.to_str
+        end
+
+        # Ensures the value is a boolean.
+        def validate_boolean rules, value, opt_name, context = nil
+          unless [true, false].include?(value)
+            format_error('true or false', opt_name, context)
+          end
+          value
+        end
+
+        # Ensures the value is an integer.
+        def validate_integer rules, value, opt_name, context = nil
+          unless value.respond_to?(:to_int)
+            format_error('integer value', opt_name, context)
+          end
+          value.to_int
+        end
+
+        # Ensures the value is a timestamp.
+        def validate_timestamp rules, value, opt_name, context = nil
+          # TODO : add validation to timestamps values
+          value.to_s
+        end
+
+        def validate_blob rules, value, opt_name, context = nil
+          value
+        end
+
+        def format_error description, opt_name, context
+          context = context || "option :#{opt_name}"
+          raise ArgumentError, "expected #{description} for #{context}"
+        end
+
+      end
+    end
+  end
+end

data/lib/mss/core/options/xml_serializer.rb

@@ -0,0 +1,117 @@
+# 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 'nokogiri'
+
+module MSS
+  module Core
+    module Options
+
+      # Given a hash of serialization rules, an XMLSerializer can convert
+      # a hash of request options into XML.  The request options are
+      # validated before returning XML.
+      class XMLSerializer
+
+        # @param [String] namespace
+        # @param [String] operation_name
+        # @param [Hash] operation
+        def initialize namespace, operation_name, operation
+          @namespace = namespace
+          @operation_name = operation_name
+          @rules = operation[:inputs]
+          @http = operation[:http]
+          @validator = Validator.new(rules)
+        end
+
+        # @return [String] Returns the name of the API operation.
+        attr_reader :operation_name
+
+        # @return [String]
+        attr_reader :namespace
+
+        # @return [Hash]
+        attr_reader :rules
+
+        # @return [Hash,nil]
+        attr_reader :http
+
+        # @return [Validator]
+        attr_reader :validator
+
+        # @overload serialize!(request_options)
+        #   @param [Hash] request_options A hash of already validated
+        #     request options with normalized values.
+        #   @return [String] Returns an string of the request parameters
+        #     serialized into XML.
+        def serialize request_options
+          if http && http[:request_payload]
+            payload = http[:request_payload]
+            root_node_name = rules[payload][:name]
+            params = request_options[payload]
+            rules = self.rules[payload][:members]
+          else
+            root_node_name = "#{operation_name}Request"
+            params = request_options
+            rules = self.rules
+          end
+          xml = Nokogiri::XML::Builder.new
+          xml.send(root_node_name, :xmlns => namespace) do |xml|
+            hash_members_xml(params, rules, xml)
+          end
+          xml.doc.root.to_xml
+        end
+
+        protected
+
+        def to_xml builder, opt_name, rules, value
+
+          xml_name = rules[:name]
+          xml_name ||= opt_name.is_a?(String) ?
+            opt_name : Inflection.class_name(opt_name.to_s)
+
+          case value
+          when Hash
+
+            builder.send(xml_name) do |builder|
+              hash_members_xml(value, rules[:members], builder)
+            end
+
+          when Array
+            builder.send(xml_name) do
+              value.each do |member_value|
+                to_xml(builder, 'member', rules[:members], member_value)
+              end
+            end
+          else builder.send(xml_name, value)
+          end
+
+        end
+
+        def hash_members_xml hash, rules, builder
+          xml_ordered_members(rules).each do |member_name|
+            if hash.key?(member_name)
+              value = hash[member_name]
+              to_xml(builder, member_name, rules[member_name], value)
+            end
+          end
+        end
+
+        def xml_ordered_members members
+          members.inject([]) do |list,(member_name, member)|
+            list << [member[:position] || 0, member_name]
+          end.sort_by(&:first).map(&:last)
+        end
+
+      end
+    end
+  end
+end

data/lib/mss/core/page_result.rb

@@ -0,0 +1,74 @@
+# 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
+  module Core
+    class PageResult < Array
+
+      # @return [Collection] Returns the collection that was used to
+      #   populated this page of results.
+      attr_reader :collection
+
+      # @return [Integer] Returns the maximum number of results per page.
+      #   The final page in a collection may return fewer than `:per_page`
+      #   items (e.g. `:per_page` is 10 and there are only 7 items).
+      attr_reader :per_page
+
+      # @return [String] An opaque token that can be passed the #page method
+      #   of the collection that returned this page of results.  This next
+      #   token behaves as a pseudo offset.  If `next_token` is `nil` then
+      #   there are no more results for the collection.
+      attr_reader :next_token
+
+      # @param [Collection] collection The collection that was used to
+      #   request this page of results.  The collection should respond to
+      #   #page and accept a :next_token option.
+      #
+      # @param [Array] items An array of result items that represent a
+      #   page of results.
+      #
+      # @param [Integer] per_page The number of requested items for this
+      #   page of results.  If the count of items is smaller than `per_page`
+      #   then this is the last page of results.
+      #
+      # @param [String] next_token (nil) A token that can be passed to the
+      #
+      def initialize collection, items, per_page, next_token
+        @collection = collection
+        @per_page = per_page
+        @next_token = next_token
+        super(items)
+      end
+
+      # @return [PageResult]
+      # @raise [RuntimeError] Raises a runtime error when called against
+      #   a collection that has no more results (i.e. #last_page? == true).
+      def next_page
+        if last_page?
+          raise 'unable to get the next page, already at the last page'
+        end
+        collection.page(:per_page => per_page, :next_token => next_token)
+      end
+
+      # @return [Boolean] Returns `true` if this is the last page of results.
+      def last_page?
+        next_token.nil?
+      end
+
+      # @return [Boolean] Returns `true` if there are more pages of results.
+      def more?
+        !!next_token
+      end
+
+    end
+  end
+end