aws-sdk-resources 2.0.0.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2258aa532dd93701acb1dd469ef9d45c2ffac526
+  data.tar.gz: 6d2aacfaae954de3f151c22a5da7455922519f5d
+SHA512:
+  metadata.gz: a319ba138c25889d126981b916917f7a11eb02d2445074f74b81d722d2ecaff841fadfa6722153a4aa8c28855da2f50d46de4e2b9dae7d2ddd544da4ccaf78a6
+  data.tar.gz: 9508bad7873f5f233c91eff4dac292c99aead6dc3c4748f1f0312e39139464125256457d61090cad9aa0d5d139044a110f4679a76f9f8992315dd8eaa2de16ef

data/lib/aws-sdk-resources.rb

@@ -0,0 +1,36 @@
+require 'aws-sdk-core'
+
+module Aws
+  module Resources
+
+    autoload :Batch, 'aws-sdk-resources/batch'
+    autoload :Builder, 'aws-sdk-resources/builder'
+    autoload :BuilderSources, 'aws-sdk-resources/builder_sources'
+    autoload :Collection, 'aws-sdk-resources/collection'
+    autoload :Definition, 'aws-sdk-resources/definition'
+    autoload :Documenter, 'aws-sdk-resources/documenter'
+    autoload :Errors, 'aws-sdk-resources/errors'
+    autoload :Operations, 'aws-sdk-resources/operations'
+    autoload :OperationMethods, 'aws-sdk-resources/operation_methods'
+    autoload :Options, 'aws-sdk-resources/options'
+    autoload :Request, 'aws-sdk-resources/request'
+    autoload :RequestParams, 'aws-sdk-resources/request_params'
+    autoload :Resource, 'aws-sdk-resources/resource'
+    autoload :Source, 'aws-sdk-resources/source'
+    autoload :Validator, 'aws-sdk-resources/validator'
+
+  end
+
+  service_added do |_, svc_module, options|
+    definition = options[:resources]
+    definition = case definition
+      when nil then Resources::Definition.new({})
+      when Resources::Definition then definition
+      when Hash then Resources::Definition.new(definition)
+      when String then Resources::Definition.new(Aws.load_json(definition), source_path: definition)
+      else raise ArgumentError, "invalid resource definition #{definition}"
+    end
+    definition.apply(svc_module)
+  end
+
+end

data/lib/aws-sdk-resources/batch.rb

@@ -0,0 +1,100 @@
+module Aws
+  module Resources
+
+    # A batch provides array like access to a list of resources. Batches
+    # also provide the ability to invoke certain operations against
+    # the entire batch.
+    #
+    # ## Getting a Batch
+    #
+    # You should normally not need to construct a batch. Anywhere a list
+    # of resources is returned, they are returned as a batch:
+    #
+    #     # security_groups is a batch
+    #     security_groups = ec2.instance('i-12345678').security_groups
+    #
+    # When the possible number of resources is unknown or large, the
+    # resources will be returned in a collection. Collections can enumerate
+    # individual resources or batches. They manage paging over the
+    # AWS request/responses to produce batches.
+    #
+    #     # objects is a collection
+    #     objects = s3.bucket('aws-sdk').objects
+    #
+    # You can invoke batch operations against collections and they will
+    # invoke them on each batch.
+    #
+    #     # delets all all objects in this bucket in batches of 1k
+    #     objects = s3.bucket('aws-sdk').objects
+    #     objects.delete
+    #
+    # ## Batch Operations
+    #
+    # Batches provide operations that operate on the entire batch. These
+    # operations are only defined for resources where the AWS API accepts
+    # multiple inputs. This means a batch operation for n elements will
+    # only make one request.
+    #
+    # Resource classes document each of their own batch operations.
+    # See {S3::Object} for an example.
+    #
+    class Batch
+
+      include Enumerable
+      extend OperationMethods
+
+      # @param [Array<Resource>] resources
+      # @option options [Seahorse::Client::Response] :response
+      def initialize(resources, options = {})
+        @resources = resources
+        @options = options
+      end
+
+      # @return [Seahorse::Client::Response, nil]
+      def response
+        @options[:response]
+      end
+
+      # @return [Integer]
+      def size
+        @resources.size
+      end
+
+      alias count size
+
+      # @param [Integer] index
+      # @return [Resource]
+      def [](index)
+        @resources[index]
+      end
+
+      # Yields each resource of the batch, one at a time.
+      def each(&block)
+        enum = @resources.to_enum
+        enum.each(&block) if block_given?
+        enum
+      end
+
+      # @param [Integer] count
+      # @return [Resource, Batch]
+      def first(count = nil)
+        if count
+          self.class.new(@resources.first(count), @options)
+        else
+          @resources.first
+        end
+      end
+
+      # @return [Boolean]
+      def empty?
+        @resources.empty?
+      end
+
+      # @api private
+      def inspect
+        "#<#{self.class.name} resources=#{@resources}>"
+      end
+
+    end
+  end
+end

data/lib/aws-sdk-resources/builder.rb

@@ -0,0 +1,86 @@
+require 'jamespath'
+
+module Aws
+  module Resources
+
+    # A {Builder} construct resource objects.  It extracts resource identifiers
+    # for the objects it builds from another resource object and/or an
+    # AWS response.
+    class Builder
+
+      include Options
+
+      # @option options [required, Class<Resource>] resource_class
+      # @option options [Array<BuilderSources::Source>] :sources ([])
+      def initialize(options = {})
+        @resource_class = options[:resource_class]
+        @sources = options[:sources] || []
+      end
+
+      # @return [Class<Resource>]
+      attr_reader :resource_class
+
+      # @return [Array<BuilderSources::Source>] A list of resource
+      #   identifier sources.
+      attr_reader :sources
+
+      # @return [Boolean] Returns `true` if this builder returns an array
+      #   of resource objects from {#build}.
+      def plural?
+        @sources.any?(&:plural?)
+      end
+
+      # @option [Resource] :resource
+      # @option [Seahorse::Client::Response] :response
+      # @return [Resource, Array<Resource>] Returns a resource object or an
+      #   array of resource objects if {#plural?}.
+      def build(options = {})
+        identifier_map = @sources.each.with_object({}) do |source, hash|
+          hash[source.target] = source.extract(options)
+        end
+        if plural?
+          build_batch(identifier_map, options)
+        else
+          build_one(identifier_map, options)
+        end
+      end
+
+      private
+
+      def build_batch(identifier_map, options, &block)
+        resources = (0...resource_count(identifier_map)).collect do |n|
+          identifiers = @sources.each.with_object({}) do |source, identifiers|
+            identifiers[source.target] = source.plural? ?
+              identifier_map[source.target][n] :
+              identifier_map[source.target]
+          end
+          resource = build_one(identifiers, options)
+          yield(resource) if block_given?
+          resource
+        end
+        resource_class::Batch.new(resources, options)
+      end
+
+      def build_one(identifiers, options)
+        if identifiers.values.any?(&:nil?)
+          nil
+        else
+          @resource_class.new(identifiers.merge(
+            client: client(options)
+          ))
+        end
+      end
+
+      def resource_count(identifier_map)
+        identifier_map.values.inject(0) do |max, values|
+          [max, values.is_a?(Array) ? values.size : 0].max
+        end
+      end
+
+      def client(options)
+        Array(options[:resource]).first.client
+      end
+
+    end
+  end
+end

data/lib/aws-sdk-resources/builder_sources.rb

@@ -0,0 +1,136 @@
+require 'jamespath'
+
+module Aws
+  module Resources
+    module BuilderSources
+
+      # Used by a {Builder} to extract resource identifiers from an AWS
+      # response or from another resource object.
+      #
+      # This is the base class of each of the builder sources.  Each
+      # source is responsible for extracting a single identifier.
+      #
+      # @see {Argument}
+      # @see {Identifier}
+      # @see {DataMember}
+      # @see {RequestParameter}
+      # @see {ResponsePath}
+      #
+      class Base
+
+        include Options
+
+        # @param [String] source
+        # @param [Symbol] target
+        def initialize(source, target)
+          @source = source
+          @target = target.to_sym
+        end
+
+        # @return [String]
+        attr_reader :source
+
+        # @return [Symbol]
+        attr_reader :target
+
+        # @return [Boolean]
+        def plural?
+          source.include?('[')
+        end
+
+        # @param [Hash] options
+        # @return [String, Array<String>]
+        def extract(options)
+          raise NotImplementedError, 'must be defined in subclasses'
+        end
+
+      end
+
+      class Argument < Base
+
+        def initialize(target)
+          super(target.to_s, target)
+        end
+
+        # @option [required, String] :argument
+        def extract(options)
+          (options[:args] || []).first
+        end
+
+      end
+
+      # Extracts an identifier from a parent resource identifier.  Used
+      # when building a {Resource} from the context of another resource.
+      class Identifier < Base
+
+        # @option [required, Resource] :resource
+        def extract(options)
+          resource(options).identifiers[source.to_sym]
+        end
+
+        private
+
+        def resource(options)
+          option(:resource, options)
+        end
+
+      end
+
+      # Extracts an identifier from the data of a parent resource.  Used
+      # when building a {Resource} from the context of another resource.
+      class DataMember < Base
+
+        # @option [required, Resource] :resource
+        def extract(options)
+          Jamespath.search(source, resource(options).data)
+        end
+
+        private
+
+        def resource(options)
+          option(:resource, options)
+        end
+
+      end
+
+      # Extracts an identifier from the request parameters used to generate
+      # a response.  Used when building a {Resource} object from the response
+      # of an operation.
+      class RequestParameter < Base
+
+        # @option [required, Seahorse::Client::Response] :response
+        def extract(options)
+          response(options).context.params[source.to_sym]
+        end
+
+        private
+
+        def response(options)
+          option(:response, options)
+        end
+
+      end
+
+      # Extracts an identifier from the data of a response.  Used when
+      # building a {Resource} object from the response of an operation.
+      class ResponsePath < Base
+
+        # @option [required, Seahorse::Client::Response] :response
+        def extract(options)
+          if source == '$'
+            response(options).data
+          else
+            Jamespath.search(source, response(options).data)
+          end
+        end
+
+        private
+
+        def response(options)
+          option(:response, options)
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-resources/collection.rb

@@ -0,0 +1,137 @@
+module Aws
+  module Resources
+    class Collection
+
+      include Enumerable
+
+      # @param [EnumerateResourceOperation] operation
+      # @option (see EnumerateResourceOperation#call)
+      # @api private
+      def initialize(operation, options)
+        @operation = operation
+        @options = options
+        reject_limit_param(options)
+      end
+
+      # @return [Enumerator<Resource>]
+      def each(&block)
+        if block_given?
+          batches.each { |batch| batch.each(&block) }
+        else
+          self
+        end
+      end
+
+      # @return [Enumerator<Batch>]
+      def batches(&block)
+        @operation.batches(@options)
+      end
+
+      # Specifies the maximum number of items to enumerate.
+      #
+      #     collection.limit(10).each do |resource|
+      #       # yields at most 10 times
+      #     end
+      #
+      # @param [Integer] limit The maximum number of items to yield
+      #   via {#each} or {#batches}.
+      # @return [Collection]
+      def limit(limit)
+        self.class.new(@operation, @options.merge(limit: limit))
+      end
+
+      # Specifies max size of each batch. Some services may return fewer
+      # than `size` number of items per request.
+      #
+      # @example Enumerate the collection in batches with a max size
+      #
+      #   collection.batch_size(10).batches.each do |batch|
+      #     # batch has at most 10 items
+      #   end
+      #
+      # @param [Integer] size
+      # @return [Collection]
+      def batch_size(size)
+        if limit_key
+          self.class.new(@operation, @options.merge(batch_size: size))
+        else
+          resource = resource_class.name
+          method_name = @operation.request.method_name
+          msg = "batch size not supported by #{resource}##{method_name}"
+          raise NotImplementedError, msg
+        end
+      end
+
+      # Returns the first resource from the collection.
+      #
+      #     resource = collection.first
+      #
+      # If you pass a count, then the first `count` resources are returned in
+      # a single batch. See the resource specific batch documentation for
+      # a list of supported batch methods.
+      #
+      #     resources = collection.first(10)
+      #     resources.delete
+      #
+      # @return [Resource, Batch]
+      def first(count = 1)
+        if count == 1
+          limit(1).to_a.first
+        else
+          resource_class::Batch.new(limit(count).to_a)
+        end
+      end
+
+      # @api private
+      def respond_to?(method_name, *args)
+        if resource_class::Batch.instance_methods.include?(method_name.to_sym)
+          true
+        else
+          super
+        end
+      end
+
+      # @api private
+      def method_missing(method_name, *args, &block)
+        if respond_to?(method_name)
+          batches.each do |batch|
+            batch.send(method_name, *args, &block)
+          end
+        else
+          super
+        end
+      end
+
+      # @api private
+      def inspect
+        parts = {}
+        parts[:type] = resource_class.name
+        parts[:limit] = @options[:limit]
+        parts[:batch_size] = @options[:batch_size] if limit_key
+        parts[:params] = @options[:params] || {}
+        parts = parts.inject("") {|s,(k,v)| s << " #{k}=#{v.inspect}" }
+        ['#<', self.class.name, parts, '>'].join
+      end
+
+      private
+
+      # @api private
+      def limit_key
+        @operation.limit_key
+      end
+
+      def reject_limit_param(options)
+        if options[:params] && options[:params][limit_key]
+          msg = "invalid option :#{limit_key}, call #limit or #batch_size "
+          msg << "on the returned Aws::Resources::Collection instead"
+          raise ArgumentError, msg
+        end
+      end
+
+      def resource_class
+        @operation.builder.resource_class
+      end
+
+    end
+  end
+end