aws-record 2.6.1 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 613ebc2bb79fb30645f69fc831911f4fb269e9fe1e0d69bb064e5cc0b6c3294c
-  data.tar.gz: 6012bd27fd72dd5b8702e9833d302c57df7d9c44834ac37a6f347735328898ff
+  metadata.gz: 67f48531ca8b917f680a1d9a5d21afd1611aba0eb96916a5783addaf7939cda8
+  data.tar.gz: 7f6cbb16271455ada17a61f32106800b65d3b4103a5254e7686e06d5cf715cca
 SHA512:
-  metadata.gz: e524df13f1433045d958466a377672f28a9c5cb7765f1d365ba856ff51ad8b78d7ab60bf55bd4b36d36ed4d880f7452ee5f09aff9cf0f7ec67f1096dbb3ccc2a
-  data.tar.gz: 34bb9db197f9f6b825b1b4296aace9df35f1e72f9e814bc530b25e36117500ab52b2710730ebf3dd712381fb7d85415f36a52a61c1c32420922492d3ebf21729
+  metadata.gz: 5bb474f4d13e469b9af991e061b10a54279f37d7390b9cb1bffafd40d039c649c12ca5423140d4a232a08536ec715df89db2e07f6670ef0242732cbe78d1d890
+  data.tar.gz: 9b61d0d93ce9b657989fefde1201aab35253e656035ffb87ccbebfbafe4ea423883146dd4dec510dfdf5deec74b274784f6490d86804cf76b09aeee58f41cdfb

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

@@ -0,0 +1,82 @@
+# 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.
+
+module Aws
+  module Record
+    class Batch
+      extend ClientConfiguration
+
+      class << self
+        # @example Usage Example
+        #   class Breakfast
+        #     include Aws::Record
+        #     integer_attr :id,   hash_key: true
+        #     string_attr  :name, range_key: true
+        #     string_attr  :body
+        #   end
+        #
+        #   # setup
+        #   eggs = Breakfast.new(id: 1, name: "eggs").save!
+        #   waffles = Breakfast.new(id: 2, name: "waffles")
+        #   pancakes = Breakfast.new(id: 3, name: "pancakes")
+        #
+        #   # batch operations
+        #   operation = Aws::Record::Batch.write(client: Breakfast.dynamodb_client) do |db|
+        #     db.put(waffles)
+        #     db.delete(eggs)
+        #     db.put(pancakes)
+        #   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.
+        #
+        # @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::BatchWrite] An instance that contains any
+        #   unprocessed items and allows for a retry strategy.
+        def write(opts = {}, &block)
+          batch = BatchWrite.new(client: _build_client(opts))
+          block.call(batch)
+          batch.execute!
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# 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.
+
+module Aws
+  module Record
+    class BatchWrite
+      # @param [Aws::DynamoDB::Client] client the DynamoDB SDK client.
+      def initialize(client:)
+        @client = client
+      end
+
+      # Append a +PutItem+ operation to a batch write request.
+      #
+      # @param [Aws::Record] record a model class that includes {Aws::Record}.
+      def put(record)
+        table_name, params = record_put_params(record)
+        operations[table_name] ||= []
+        operations[table_name] << { put_request: params }
+      end
+
+      # Append a +DeleteItem+ operation to a batch write request.
+      #
+      # @param [Aws::Record] record a model class that includes {Aws::Record}.
+      def delete(record)
+        table_name, params = record_delete_params(record)
+        operations[table_name] ||= []
+        operations[table_name] << { delete_request: params }
+      end
+
+      # Perform a +batch_write_item+ request.
+      #
+      # @return [Aws::Record::BatchWrite] an instance that provides access to
+      #   unprocessed items and allows for retries.
+      def execute!
+        result = @client.batch_write_item(request_items: operations)
+        @operations = result.unprocessed_items
+        self
+      end
+
+      # Indicates if all items have been processed.
+      #
+      # @return [Boolean] +true+ if +unprocessed_items+ is empty, +false+
+      #   otherwise
+      def complete?
+        unprocessed_items.values.none?
+      end
+
+      # Returns all +DeleteItem+ and +PutItem+ operations that have not yet been
+      # processed successfully.
+      #
+      # @return [Hash] All operations that have not yet successfully completed.
+      def unprocessed_items
+        operations
+      end
+
+      private
+
+      def operations
+        @operations ||= {}
+      end
+
+      def record_delete_params(record)
+        [record.class.table_name, { key: record.key_values }]
+      end
+
+      def record_put_params(record)
+        [record.class.table_name, { item: record.save_values }]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# 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.
+
+module Aws
+  module Record
+    module ClientConfiguration
+      # Configures the Amazon DynamoDB client used by this class and all
+      # instances of this class.
+      #
+      # Please note that this method is also called internally when you first
+      # attempt to perform an operation against the remote end, if you have not
+      # already configured a client. As such, please read and understand the
+      # documentation in the AWS SDK for Ruby around
+      # {http://docs.aws.amazon.com/sdkforruby/api/index.html#Configuration configuration}
+      # to ensure you understand how default configuration behavior works. When
+      # in doubt, call this method to ensure your client is configured the way
+      # you want it to be configured.
+      #
+      # @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.
+      def configure_client(opts = {})
+        @dynamodb_client = _build_client(opts)
+      end
+
+      # Gets the
+      # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html}
+      # instance that Transactions use. When called for the first time, if
+      # {#configure_client} has not yet been called, will configure a new
+      # client for you with default parameters.
+      #
+      # @return [Aws::DynamoDB::Client] the Amazon DynamoDB client instance.
+      def dynamodb_client
+        @dynamodb_client ||= configure_client
+      end
+
+      private
+
+      def _build_client(opts = {})
+        provided_client = opts.delete(:client)
+        opts[:user_agent_suffix] = _user_agent(opts.delete(:user_agent_suffix))
+        provided_client || Aws::DynamoDB::Client.new(opts)
+      end
+
+      def _user_agent(custom)
+        custom || " aws-record/#{VERSION}"
+      end
+    end
+  end
+end

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

@@ -97,13 +97,13 @@ module Aws
       #   model.age    # => 4
       #   model.height # => 70.5
       #   model.save
-      #   model.dirty? # => false  
-      # 
+      #   model.dirty? # => false
+      #
       #   model.assign_attributes(age: 5, height: 150.75)
       #   model.age    # => 5
       #   model.height # => 150.75
       #   model.dirty? # => true
-      #   
+      #
       #
       # @param [Hash] opts
       def assign_attributes(opts)
@@ -137,14 +137,14 @@ module Aws
       #   model.age    # => 4
       #   model.height # => 70.5
       #   model.save
-      #   model.dirty? # => false  
-      # 
+      #   model.dirty? # => false
+      #
       #   model.update(age: 5, height: 150.75)
       #   model.age    # => 5
       #   model.height # => 150.75
       #   model.dirty? # => false
       #
-      # 
+      #
       # @param [Hash] new_param, contains the new parameters for the model
       #
       # @param [Hash] opts
@@ -167,7 +167,7 @@ module Aws
       # Note that aws-record allows you to change your model's key values,
       # but this will be interpreted as persisting a new item to your DynamoDB
       # table
-      # 
+      #
       # @param [Hash] new_param, contains the new parameters for the model
       #
       # @param [Hash] opts
@@ -195,6 +195,28 @@ module Aws
         self.instance_variable_get("@data").destroyed = true
       end
 
+      # Validates and generates the key values necessary for API operations such as the
+      # {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html#delete_item-instance_method Aws::DynamoDB::Client#delete_item}
+      # operation.
+      def key_values
+        validate_key_values
+        attributes = self.class.attributes
+        self.class.keys.values.each_with_object({}) do |attr_name, hash|
+          db_name = attributes.storage_name_for(attr_name)
+          hash[db_name] = attributes
+            .attribute_for(attr_name)
+            .serialize(@data.raw_value(attr_name))
+        end
+      end
+
+      # Validates key values and returns a hash consisting of the parameters
+      # to save the record using 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}
+      # operation.
+      def save_values
+        _build_item_for_save
+      end
+
       private
       def _invalid_record?(opts)
         if self.respond_to?(:valid?)
@@ -265,17 +287,6 @@ module Aws
         @data.build_save_hash
       end
 
-      def key_values
-        validate_key_values
-        attributes = self.class.attributes
-        self.class.keys.inject({}) do |acc, (_, attr_name)|
-          db_name = attributes.storage_name_for(attr_name)
-          acc[db_name] = attributes.attribute_for(attr_name).
-            serialize(@data.raw_value(attr_name))
-          acc
-        end
-      end
-
       def validate_key_values
         missing = missing_key_values
         unless missing.empty?
@@ -339,7 +350,7 @@ module Aws
         #       ":v" => 1024
         #     }
         #   )
-        # 
+        #
         # Allows you to build a "check" expression for use in transactional
         # write operations.
         #
@@ -400,7 +411,7 @@ module Aws
         #     string_attr :hk, hash_key: true
         #     string_attr :rk, range_key: true
         #   end
-        #   
+        #
         #   results = Table.transact_find(
         #     transact_items: [
         #       {key: { hk: "hk1", rk: "rk1"}},

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

@@ -1,6 +1,8 @@
 module Aws
   module Record
     module Transactions
+      extend ClientConfiguration
+
       class << self
 
         # @example Usage Example
@@ -8,13 +10,13 @@ module Aws
         #     include Aws::Record
         #     string_attr :uuid, hash_key: true
         #   end
-        #   
+        #
         #   class TableTwo
         #     include Aws::Record
         #     string_attr :hk, hash_key: true
         #     string_attr :rk, range_key: true
         #   end
-        #   
+        #
         #   results = Aws::Record::Transactions.transact_find(
         #     transact_items: [
         #       TableOne.tfind_opts(key: { uuid: "uuid1234" }),
@@ -93,14 +95,14 @@ module Aws
         #     string_attr :uuid, hash_key: true
         #     string_attr :body
         #   end
-        #   
+        #
         #   class TableTwo
         #     include Aws::Record
         #     string_attr :hk, hash_key: true
         #     string_attr :rk, range_key: true
         #     string_attr :body
         #   end
-        #   
+        #
         #   check_exp = TableOne.transact_check_expression(
         #     key: { uuid: "foo" },
         #     condition_expression: "size(#T) <= :v",
@@ -118,7 +120,7 @@ module Aws
         #   update_item_2 = TableTwo.find(hk: "hk2", rk: "rk2")
         #   update_item_2.body = "Update!"
         #   delete_item = TableOne.find(uuid: "to_be_deleted")
-        #   
+        #
         #   Aws::Record::Transactions.transact_write(
         #     transact_items: [
         #       { check: check_exp },
@@ -183,44 +185,6 @@ module Aws
           resp
         end
 
-        # Configures the Amazon DynamoDB client used by global transaction
-        # operations.
-        #
-        # Please note that this method is also called internally when you first
-        # attempt to perform an operation against the remote end, if you have
-        # not already configured a client. As such, please read and understand
-        # the documentation in the AWS SDK for Ruby V3 around
-        # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/#Configuration configuration}
-        # to ensure you understand how default configuration behavior works.
-        # When in doubt, call this method to ensure your client is configured
-        # the way you want it to be configured.
-        #
-        # @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 V3}.
-        # @option opts [Aws::DynamoDB::Client] :client allows you to pass in
-        #  your own pre-configured client.
-        def configure_client(opts = {})
-          provided_client = opts.delete(:client)
-          opts[:user_agent_suffix] = _user_agent(
-            opts.delete(:user_agent_suffix)
-          )
-          client = provided_client || Aws::DynamoDB::Client.new(opts)
-          @@dynamodb_client = client
-        end
-
-        # Gets the
-        # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html}
-        # instance that Transactions use. When called for the first time, if
-        # {#configure_client} has not yet been called, will configure a new
-        # client for you with default parameters.
-      #
-      # @return [Aws::DynamoDB::Client] the Amazon DynamoDB client instance.
-        def dynamodb_client
-          @@dynamodb_client ||= configure_client
-        end
-
         private
         def _transform_transact_write_items(transact_items, dirty_items, delete_items)
           transact_items.map do |item|
@@ -317,15 +281,6 @@ module Aws
           # check records are a pass-through
           { condition_check: opts.merge(check_record) }
         end
-
-        def _user_agent(custom)
-          if custom
-            custom
-          else
-            " aws-record/#{VERSION}"
-          end
-        end
-
       end
     end
   end

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

@@ -13,6 +13,6 @@
 
 module Aws
   module Record
-    VERSION = '2.4.0'
+    VERSION = '2.7.0'
   end
 end

data/lib/aws-record/record.rb

@@ -50,6 +50,7 @@ module Aws
     #     # Attribute definitions go here...
     #   end
     def self.included(sub_class)
+      sub_class.send(:extend, ClientConfiguration)
       sub_class.send(:extend, RecordClassMethods)
       sub_class.send(:include, Attributes)
       sub_class.send(:include, ItemOperations)
@@ -75,12 +76,12 @@ module Aws
       #   class MyTable
       #     include Aws::Record
       #   end
-      #   
+      #
       #   class MyTableTest
       #     include Aws::Record
       #     set_table_name "test_MyTable"
       #   end
-      #   
+      #
       #   MyTable.table_name      # => "MyTable"
       #   MyOtherTable.table_name # => "test_MyTable"
       def table_name
@@ -99,12 +100,12 @@ module Aws
       #     include Aws::Record
       #     set_table_name "prod_MyTable"
       #   end
-      #   
+      #
       #   class MyTableTest
       #     include Aws::Record
       #     set_table_name "test_MyTable"
       #   end
-      #   
+      #
       #   MyTable.table_name      # => "prod_MyTable"
       #   MyOtherTable.table_name # => "test_MyTable"
       def set_table_name(name)
@@ -147,42 +148,6 @@ module Aws
         end
       end
 
-      # Configures the Amazon DynamoDB client used by this class and all
-      # instances of this class.
-      #
-      # Please note that this method is also called internally when you first
-      # attempt to perform an operation against the remote end, if you have not
-      # already configured a client. As such, please read and understand the
-      # documentation in the AWS SDK for Ruby V2 around
-      # {http://docs.aws.amazon.com/sdkforruby/api/index.html#Configuration configuration}
-      # to ensure you understand how default configuration behavior works. When
-      # in doubt, call this method to ensure your client is configured the way
-      # you want it to be configured.
-      #
-      # @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
-      #  {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html#initialize-instance_method AWS SDK for Ruby V2}.
-      # @option opts [Aws::DynamoDB::Client] :client allows you to pass in your
-      #  own pre-configured client.
-      def configure_client(opts = {})
-        provided_client = opts.delete(:client)
-        opts[:user_agent_suffix] = _user_agent(opts.delete(:user_agent_suffix))
-        client = provided_client || Aws::DynamoDB::Client.new(opts)
-        @dynamodb_client = client
-      end
-
-      # Gets the
-      # {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html Aws::DynamoDB::Client}
-      # instance that this model uses. When called for the first time, if
-      # {#configure_client} has not yet been called, will configure a new client
-      # for you with default parameters.
-      #
-      # @return [Aws::DynamoDB::Client] the Amazon DynamoDB client instance.
-      def dynamodb_client
-        @dynamodb_client ||= configure_client
-      end
-
       # Turns off mutation tracking for all attributes in the model.
       def disable_mutation_tracking
         @track_mutations = false
@@ -212,15 +177,6 @@ module Aws
           raise Errors::InvalidModel.new("Table models must include a hash key")
         end
       end
-
-      private
-      def _user_agent(custom)
-        if custom
-          custom
-        else
-          " aws-record/#{VERSION}"
-        end
-      end
     end
   end
 end

data/lib/aws-record.rb

@@ -12,6 +12,7 @@
 # and limitations under the License.
 
 require 'aws-sdk-dynamodb'
+require_relative 'aws-record/record/client_configuration'
 require_relative 'aws-record/record'
 require_relative 'aws-record/record/attribute'
 require_relative 'aws-record/record/attributes'
@@ -29,6 +30,8 @@ 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_write'
+require_relative 'aws-record/record/batch'
 require_relative 'aws-record/record/marshalers/string_marshaler'
 require_relative 'aws-record/record/marshalers/boolean_marshaler'
 require_relative 'aws-record/record/marshalers/integer_marshaler'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-record
 version: !ruby/object:Gem::Version
-  version: 2.6.1
+  version: 2.7.0
 platform: ruby
 authors:
 - Amazon Web Services
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-08-10 00:00:00.000000000 Z
+date: 2021-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-dynamodb
@@ -36,7 +36,10 @@ files:
 - lib/aws-record/record.rb
 - lib/aws-record/record/attribute.rb
 - lib/aws-record/record/attributes.rb
+- lib/aws-record/record/batch.rb
+- lib/aws-record/record/batch_write.rb
 - lib/aws-record/record/buildable_search.rb
+- lib/aws-record/record/client_configuration.rb
 - lib/aws-record/record/dirty_tracking.rb
 - lib/aws-record/record/errors.rb
 - lib/aws-record/record/item_collection.rb