aws-record 2.9.0 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6316b0ad6349fdea29d10e1325b6044b54eb3f2696a9bd1692cc30881e5e2e02
-  data.tar.gz: 57c1d3c37435e3bc79eac488738c08f8ac6536bfbd5f493ac221f248bdf3e8c8
+  metadata.gz: e1d49110ed24d748680a2fe7c1d124e5faa40c1ee224b6f20059cc3252dc8b27
+  data.tar.gz: 4efe9261ad7642c172e267f4cec4b614f61f42e7c57970c7561b6eb51c6ac516
 SHA512:
-  metadata.gz: 8bdca623e0884f5cd2a704bf807be58687077e04f746e5c99a6e15ce2df4ad378afd6e3d6bdb74899d4a86521e921fd588a5fbdc5ba1c6b6c06e3daf08ad3d16
-  data.tar.gz: 2448123077cea61bf1ab263278ce1a2209d69d9a7ed53d8f665feb8bef2c7185c447378f3c4ae70a96a16ef4d62e4d2a3ffd1769f94bc367e8cd2e0c1733c4cd
+  metadata.gz: 9d2d80ea4671ab80debef324a8f80b40cb41034b2a426c69d95db48d436d86f1f7c4d1c8458da363595c28de3254c0755d9956f78f3e25dcacea83d695c8cede
+  data.tar.gz: ae7e17fb7b3fcd56a3e5f78c92da540bcceb5d4a3ec62ac70b95cf0eaefaedb89a5845b701d5b28eba0221294c6eb1f769800756017e04a812dd1a552dfd43ce

data/lib/aws-record/record/batch.rb

@@ -1,15 +1,4 @@
-# Copyright 2015-2021 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.
+# frozen_string_literal: true
 
 module Aws
   module Record
@@ -17,6 +6,28 @@ module Aws
       extend ClientConfiguration
 
       class << self
+        # Provides a thin wrapper to the
+        # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#batch_write_item-instance_method Aws::DynamoDB::Client#batch_write_item}
+        # method. Up to 25 +PutItem+ or +DeleteItem+ operations are supported.
+        # A single request may write up to 16 MB of data, with each item having a
+        # write limit of 400 KB.
+        #
+        # *Note*: this operation does not support dirty attribute handling,
+        # nor does it enforce safe write operations (i.e. update vs new record
+        # checks).
+        #
+        # This call may partially execute write operations. Failed operations
+        # are returned as {BatchWrite.unprocessed_items unprocessed_items} (i.e. the
+        # table fails to meet requested write capacity). Any unprocessed
+        # items may be retried by calling {BatchWrite.execute! .execute!}
+        # again. You can determine if the request needs to be retried by calling
+        # the {BatchWrite.complete? .complete?} method - which returns +true+
+        # when all operations have been completed.
+        #
+        # Please see
+        # {https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.Errors.html#Programming.Errors.BatchOperations Batch Operations and Error Handling}
+        # in the DynamoDB Developer Guide for more details.
+        #
         # @example Usage Example
         #   class Breakfast
         #     include Aws::Record
@@ -38,29 +49,7 @@ module Aws
         #   end
         #
         #   # unprocessed items can be retried by calling Aws::Record::BatchWrite#execute!
-        #   operation.execute! unless operation.complete?
-        #
-        # Provides a thin wrapper to the
-        # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#batch_write_item-instance_method Aws::DynamoDB::Client#batch_write_item}
-        # method. Up to 25 +PutItem+ or +DeleteItem+ operations are supported.
-        # A single rquest may write up to 16 MB of data, with each item having a
-        # write limit of 400 KB.
-        #
-        # *Note*: this operation does not support dirty attribute handling,
-        # nor does it enforce safe write operations (i.e. update vs new record
-        # checks).
-        #
-        # This call may partially execute write operations. Failed operations
-        # are returned as +Aws::Record::BatchWrite#unprocessed_items+ (i.e. the
-        # table fails to meet requested write capacity). Any unprocessed
-        # items may be retried by calling +Aws::Record::BatchWrite#execute!+
-        # again. You can determine if the request needs to be retried by calling
-        # the +Aws::Record::BatchWrite#complete?+ method - which returns +true+
-        # when all operations have been completed.
-        #
-        # Please see
-        # {https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.Errors.html#Programming.Errors.BatchOperations Batch Operations and Error Handling}
-        # in the DynamoDB Developer Guide for more details.
+        #   operation.execute! until operation.complete?
         #
         # @param [Hash] opts the options you wish to use to create the client.
         #  Note that if you include the option +:client+, all other options
@@ -76,6 +65,81 @@ module Aws
           block.call(batch)
           batch.execute!
         end
+
+        # Provides support for the
+        # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#batch_get_item-instance_method
+        # Aws::DynamoDB::Client#batch_get_item} for aws-record models.
+        #
+        # +Aws::Record::Batch+ is Enumerable and using Enumerable methods will handle
+        # paging through all requested keys automatically. Alternatively, a lower level
+        # interface is available. You can determine if there are any unprocessed keys by calling
+        # {BatchRead.complete? .complete?} and any unprocessed keys can be processed by
+        # calling {BatchRead.execute! .execute!}. You can access all processed items
+        # through {BatchRead.items .items}.
+        #
+        # The +batch_get_item+ supports up to 100 operations in a single call and a single
+        # operation can retrieve up to 16 MB of data.
+        #
+        # +Aws::Record::BatchRead+ can take more than 100 item keys. The first 100 requests
+        # will be processed and the remaining requests will be stored.
+        # When using Enumerable methods, any pending item keys will be automatically
+        # processed and the new items will be added to +items+.
+        # Alternately, use {BatchRead.execute! .execute!} to process any pending item keys.
+        #
+        # All processed operations can be accessed by {BatchRead.items items} - which is an
+        # array of modeled items from the response. The items will be unordered since
+        # DynamoDB does not return items in any particular order.
+        #
+        # If a requested item does not exist in the database, it is not returned in the response.
+        #
+        # If there is a returned item from the call and there's no reference model class
+        # to be found, the item will not show up under +items+.
+        #
+        # @example Usage Example
+        #   class Lunch
+        #     include Aws::Record
+        #     integer_attr :id,   hash_key: true
+        #     string_attr  :name, range_key: true
+        #   end
+        #
+        #   class Dessert
+        #     include Aws::Record
+        #     integer_attr :id,   hash_key: true
+        #     string_attr  :name, range_key: true
+        #   end
+        #
+        #   # batch operations
+        #   operation = Aws::Record::Batch.read do |db|
+        #     db.find(Lunch, id: 1, name: 'Papaya Salad')
+        #     db.find(Lunch, id: 2, name: 'BLT Sandwich')
+        #     db.find(Dessert, id: 1, name: 'Apple Pie')
+        #   end
+        #
+        #   # BatchRead is enumerable and handles pagination
+        #   operation.each { |item| item.id }
+        #
+        #   # Alternatively, BatchRead provides a lower level
+        #   # interface through: execute!, complete? and items.
+        #   # Unprocessed items can be processed by calling:
+        #   operation.execute! until operation.complete?
+        #
+        # @param [Hash] opts the options you wish to use to create the client.
+        #  Note that if you include the option +:client+, all other options
+        #  will be ignored. See the documentation for other options in the
+        #  {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#initialize-instance_method
+        #  AWS SDK for Ruby}.
+        # @option opts [Aws::DynamoDB::Client] :client allows you to pass in your
+        #  own pre-configured client.
+        # @return [Aws::Record::BatchRead] An instance that contains modeled items
+        #  from the +BatchGetItem+ result and stores unprocessed keys to be
+        #  manually processed later.
+        def read(opts = {}, &block)
+          batch = BatchRead.new(client: _build_client(opts))
+          block.call(batch)
+          batch.execute!
+          batch
+        end
+
       end
     end
   end

data/lib/aws-record/record/batch_read.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Aws
+  module Record
+    class BatchRead
+      include Enumerable
+
+      # @api private
+      BATCH_GET_ITEM_LIMIT = 100
+
+      # @param [Aws::DynamoDB::Client] client the DynamoDB SDK client.
+      def initialize(opts = {})
+        @client = opts[:client]
+      end
+
+      # Append the item keys to a batch read request.
+      #
+      # See {Batch.read} for example usage.
+      # @param [Aws::Record] klass a model class that includes {Aws::Record}
+      # @param [Hash] key attribute-value pairs for the key you wish to search for.
+      # @raise [Aws::Record::Errors::KeyMissing] if your option parameters
+      #  do not include all item keys defined in the model.
+      # @raise [ArgumentError] if the provided item keys is a duplicate request
+      #  in the same instance.
+      def find(klass, key = {})
+        unprocessed_key = format_unprocessed_key(klass, key)
+        store_unprocessed_key(klass, unprocessed_key)
+        store_item_class(klass, unprocessed_key)
+      end
+
+      # Perform a +batch_get_item+ request.
+      #
+      # This method processes the first 100 item keys and
+      # returns an array of new modeled items.
+      #
+      # See {Batch.read} for example usage.
+      # @return [Array] an array of unordered new items
+      def execute!
+        operation_keys = unprocessed_keys[0..BATCH_GET_ITEM_LIMIT - 1]
+        @unprocessed_keys = unprocessed_keys[BATCH_GET_ITEM_LIMIT..-1] || []
+
+        operations = build_operations(operation_keys)
+        result = @client.batch_get_item(request_items: operations)
+        new_items = build_items(result.responses)
+        items.concat(new_items)
+
+        unless result.unprocessed_keys.nil?
+          update_unprocessed_keys(result.unprocessed_keys)
+        end
+
+        new_items
+      end
+
+      # Provides an enumeration of the results from the +batch_get_item+ request
+      # and handles pagination.
+      #
+      # Any pending item keys will be automatically processed and be
+      # added to the {#items}.
+      #
+      # See {Batch.read} for example usage.
+      # @yieldparam [Aws::Record] item a modeled item
+      # @return [Enumerable<BatchRead>] an enumeration over the results of
+      #  +batch_get_item+ request.
+      def each
+        return enum_for(:each) unless block_given?
+
+        @items.each { |item| yield item }
+        until complete?
+          new_items = execute!
+          new_items.each { |new_item| yield new_item }
+        end
+      end
+
+      # Indicates if all item keys have been processed.
+      #
+      # See {Batch.read} for example usage.
+      # @return [Boolean] +true+ if all item keys has been processed, +false+ otherwise.
+      def complete?
+        unprocessed_keys.none?
+      end
+
+      # Returns an array of modeled items. The items are marshaled into classes used in {#find} method.
+      # These items will be unordered since DynamoDB does not return items in any particular order.
+      #
+      # See {Batch.read} for example usage.
+      # @return [Array] an array of modeled items from the +batch_get_item+ call.
+      def items
+        @items ||= []
+      end
+
+      private
+
+      def unprocessed_keys
+        @unprocessed_keys ||= []
+      end
+
+      def item_classes
+        @item_classes ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      def format_unprocessed_key(klass, key)
+        item_key = {}
+        attributes = klass.attributes
+        klass.keys.each_value do |attr_sym|
+          unless key[attr_sym]
+            raise Errors::KeyMissing, "Missing required key #{attr_sym} in #{key}"
+          end
+
+          attr_name = attributes.storage_name_for(attr_sym)
+          item_key[attr_name] = attributes.attribute_for(attr_sym)
+                                          .serialize(key[attr_sym])
+        end
+        item_key
+      end
+
+      def store_unprocessed_key(klass, unprocessed_key)
+        unprocessed_keys << { keys: unprocessed_key, table_name: klass.table_name }
+      end
+
+      def store_item_class(klass, key)
+        if item_classes.include?(klass.table_name)
+          item_classes[klass.table_name].each do |item|
+            if item[:keys] == key && item[:class] != klass
+              raise ArgumentError, 'Provided item keys is a duplicate request'
+            end
+          end
+        end
+        item_classes[klass.table_name] << { keys: key, class: klass }
+      end
+
+      def build_operations(keys)
+        operations = Hash.new { |h, k| h[k] = { keys: [] } }
+        keys.each do |key|
+          operations[key[:table_name]][:keys] << key[:keys]
+        end
+        operations
+      end
+
+      def build_items(item_responses)
+        new_items = []
+        item_responses.each do |table, unprocessed_items|
+          unprocessed_items.each do |item|
+            item_class = find_item_class(table, item)
+            if item_class.nil? && @client.config.logger
+              @client.config.logger.warn(
+                'Unexpected response from service.'\
+                "Received: #{item}. Skipping above item and continuing"
+              )
+            else
+              new_items << build_item(item, item_class)
+            end
+          end
+        end
+        new_items
+      end
+
+      def update_unprocessed_keys(keys)
+        keys.each do |table_name, table_values|
+          table_values.keys.each do |key|
+            unprocessed_keys << { keys: key, table_name: table_name }
+          end
+        end
+      end
+
+      def find_item_class(table, item)
+        selected_item = item_classes[table].find { |item_info| contains_keys?(item, item_info[:keys]) }
+        selected_item[:class] if selected_item
+      end
+
+      def contains_keys?(item, keys)
+        item.merge(keys) == item
+      end
+
+      def build_item(item, item_class)
+        new_item_opts = {}
+        item.each do |db_name, value|
+          name = item_class.attributes.db_to_attribute_name(db_name)
+          new_item_opts[name] = value
+        end
+        item = item_class.new(new_item_opts)
+        item.clean!
+        item
+      end
+    end
+  end
+end

data/lib/aws-record/record/batch_write.rb

@@ -15,12 +15,14 @@ module Aws
   module Record
     class BatchWrite
       # @param [Aws::DynamoDB::Client] client the DynamoDB SDK client.
-      def initialize(client:)
-        @client = client
+      def initialize(opts = {})
+        @client = opts[:client]
       end
 
       # Append a +PutItem+ operation to a batch write request.
       #
+      # See {Batch.write} for example usage.
+      #
       # @param [Aws::Record] record a model class that includes {Aws::Record}.
       def put(record)
         table_name, params = record_put_params(record)
@@ -30,6 +32,7 @@ module Aws
 
       # Append a +DeleteItem+ operation to a batch write request.
       #
+      # See {Batch.write} for example usage.
       # @param [Aws::Record] record a model class that includes {Aws::Record}.
       def delete(record)
         table_name, params = record_delete_params(record)
@@ -39,6 +42,7 @@ module Aws
 
       # Perform a +batch_write_item+ request.
       #
+      # See {Batch.write} for example usage.
       # @return [Aws::Record::BatchWrite] an instance that provides access to
       #   unprocessed items and allows for retries.
       def execute!
@@ -49,6 +53,7 @@ module Aws
 
       # Indicates if all items have been processed.
       #
+      # See {Batch.write} for example usage.
       # @return [Boolean] +true+ if +unprocessed_items+ is empty, +false+
       #   otherwise
       def complete?
@@ -58,6 +63,7 @@ module Aws
       # Returns all +DeleteItem+ and +PutItem+ operations that have not yet been
       # processed successfully.
       #
+      # See {Batch.write} for example usage.
       # @return [Hash] All operations that have not yet successfully completed.
       def unprocessed_items
         operations

data/lib/aws-record/record/item_collection.rb

@@ -54,7 +54,7 @@ module Aws
       # match your search.
       #
       # @return [Array<Aws::Record>] an array of the record items found in the
-      #   first page of reponses from the query or scan call.
+      #   first page of responses from the query or scan call.
       def page
         search_response = items
         @last_evaluated_key = search_response.last_evaluated_key

data/lib/aws-record/record/item_operations.rb

@@ -1,15 +1,4 @@
-# Copyright 2015-2016 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.
+# frozen_string_literal: true
 
 module Aws
   module Record
@@ -514,6 +503,43 @@ module Aws
           end
         end
 
+
+        # @example Usage Example
+        #   class MyModel
+        #     include Aws::Record
+        #     integer_attr :id,   hash_key: true
+        #     string_attr  :name, range_key: true
+        #   end
+        #
+        #   # returns a homogenous list of items
+        #   foo_items = MyModel.find_all(
+        #     [
+        #       {id: 1, name: 'n1'},
+        #       {id: 2, name: 'n2'}
+        #     ])
+        #
+        # Provides support for the
+        # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#batch_get_item-instance_method
+        # Aws::DynamoDB::Client#batch_get_item} for your model.
+        #
+        # This method will take a list of keys and return an instance of +Aws::Record::BatchRead+
+        #
+        # See {Batch.read} for more details.
+        # @param [Array] keys an array of item key hashes you wish to search for.
+        # @return [Aws::Record::BatchRead] An instance that contains modeled items
+        #  from the +BatchGetItem+ result and stores unprocessed keys to be
+        #  manually processed later.
+        # @raise [Aws::Record::Errors::KeyMissing] if your param hashes do not
+        #  include all the keys defined in model.
+        # @raise [ArgumentError] if the provided keys are a duplicate.
+        def find_all(keys)
+          Aws::Record::Batch.read do |db|
+            keys.each do |key|
+              db.find(self, key)
+            end
+          end
+        end
+
         # @example Usage Example
         #   class MyModel
         #     include Aws::Record

data/lib/aws-record.rb

@@ -1,15 +1,4 @@
-# Copyright 2015-2017 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.
+# frozen_string_literal: true
 
 require 'aws-sdk-dynamodb'
 require_relative 'aws-record/record/client_configuration'
@@ -30,6 +19,7 @@ require_relative 'aws-record/record/table_migration'
 require_relative 'aws-record/record/version'
 require_relative 'aws-record/record/transactions'
 require_relative 'aws-record/record/buildable_search'
+require_relative 'aws-record/record/batch_read'
 require_relative 'aws-record/record/batch_write'
 require_relative 'aws-record/record/batch'
 require_relative 'aws-record/record/marshalers/string_marshaler'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-record
 version: !ruby/object:Gem::Version
-  version: 2.9.0
+  version: 2.10.0
 platform: ruby
 authors:
 - Amazon Web Services
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-16 00:00:00.000000000 Z
+date: 2023-01-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-dynamodb
@@ -37,6 +37,7 @@ files:
 - lib/aws-record/record/attribute.rb
 - lib/aws-record/record/attributes.rb
 - lib/aws-record/record/batch.rb
+- lib/aws-record/record/batch_read.rb
 - lib/aws-record/record/batch_write.rb
 - lib/aws-record/record/buildable_search.rb
 - lib/aws-record/record/client_configuration.rb
@@ -65,7 +66,7 @@ files:
 - lib/aws-record/record/table_migration.rb
 - lib/aws-record/record/transactions.rb
 - lib/aws-record/record/version.rb
-homepage: http://github.com/aws/aws-sdk-ruby-record
+homepage: https://github.com/aws/aws-sdk-ruby-record
 licenses:
 - Apache 2.0
 metadata: {}