aws-record 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76f3f70bc226f5e34e377328a8829db296bffa304238da8d7542a947ba0b7a9e
-  data.tar.gz: f22f14e087edf96717fbaffd03bc7b3917001fb5238597994143b50bc5e16894
+  metadata.gz: ded98837103b96b4599121d600cc139054de43637168121bae6a35302ba24ac8
+  data.tar.gz: 14c7d413a0b108fffd9c118aa05234b7e6d33852121e8b6828e88db6cadd45d7
 SHA512:
-  metadata.gz: 745aff26cc027c53552b456066b56900f1489c1aa4433b8e539d1ac6f093d0cbaa62dec5054b433d2f8f2f42220471cca55dcdb6fa0d6ae1d23f542318ccd296
-  data.tar.gz: 2e20c004f7ca252dfdff66eb4005137c74da60a964ce4862bb2390fceaf6ce2fe0f1c63bcdc00a1671f13c69dc6165b0488afc1ba4779b524ba1740c1d7f2591
+  metadata.gz: 722b31cd37b441f33cc9993596b7fb92dc360bc280a00d9da9f03419a792669419bd9fa58006e59f09a027bde88444d795951902e3181aa697644a89baf09b17
+  data.tar.gz: bd7399265054c4483039e432fb4804713428151b3cef0f8e661132e9cf30d0c6876ed5611b09fcd6063c50b0f1baa31976cbfede27aba042457a9df3ac6cdffa

data/lib/aws-record.rb

@@ -27,6 +27,7 @@ require_relative 'aws-record/record/secondary_indexes'
 require_relative 'aws-record/record/table_config'
 require_relative 'aws-record/record/table_migration'
 require_relative 'aws-record/record/version'
+require_relative 'aws-record/record/transactions'
 require_relative 'aws-record/record/marshalers/string_marshaler'
 require_relative 'aws-record/record/marshalers/boolean_marshaler'
 require_relative 'aws-record/record/marshalers/integer_marshaler'

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

@@ -54,6 +54,14 @@ module Aws
       class TableDoesNotExist < RuntimeError; end
 
       class MissingRequiredConfiguration < RuntimeError; end
+
+      # Raised when you attempt to combine your own condition expression with
+      # the auto-generated condition expression from a "safe put" from saving
+      # a new item in a transactional write operation. The path forward until
+      # this case is supported is to use a plain "put" call, and to include
+      # the key existance check yourself in your condition expression if you
+      # wish to do so.
+      class TransactionalSaveConditionCollision < RuntimeError; end
     end
   end
 end

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

@@ -329,6 +329,112 @@ module Aws
 
       module ItemOperationsClassMethods
 
+        # @example Usage Example
+        #   check_exp = Model.transact_check_expression(
+        #     key: { uuid: "foo" },
+        #     condition_expression: "size(#T) <= :v",
+        #     expression_attribute_names: {
+        #       "#T" => "body"
+        #     },
+        #     expression_attribute_values: {
+        #       ":v" => 1024
+        #     }
+        #   )
+        # 
+        # Allows you to build a "check" expression for use in transactional
+        # write operations.
+        #
+        # @param [Hash] opts Options matching the :condition_check contents in
+        #   the
+        #   {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#transact_write_items-instance_method Aws::DynamoDB::Client#transact_write_items}
+        #   API, with the exception that keys will be marshalled for you, and
+        #   the table name will be provided for you by the operation.
+        # @return [Hash] Options suitable to be used as a check expression when
+        #   calling the +#transact_write+ operation.
+        def transact_check_expression(opts)
+          # need to transform the key, and add the table name
+          opts = opts.dup
+          key = opts.delete(:key)
+          check_key = {}
+          @keys.keys.each_value do |attr_sym|
+            unless key[attr_sym]
+              raise Errors::KeyMissing.new(
+                "Missing required key #{attr_sym} in #{key}"
+              )
+            end
+            attr_name = attributes.storage_name_for(attr_sym)
+            check_key[attr_name] = attributes.attribute_for(attr_sym).
+              serialize(key[attr_sym])
+          end
+          opts[:key] = check_key
+          opts[:table_name] = table_name
+          opts
+        end
+
+        def tfind_opts(opts)
+          opts = opts.dup
+          key = opts.delete(:key)
+          request_key = {}
+          @keys.keys.each_value do |attr_sym|
+            unless key[attr_sym]
+              raise Errors::KeyMissing.new(
+                "Missing required key #{attr_sym} in #{key}"
+              )
+            end
+            attr_name = attributes.storage_name_for(attr_sym)
+            request_key[attr_name] = attributes.attribute_for(attr_sym).
+              serialize(key[attr_sym])
+          end
+          # this is a :get item used by #transact_get_items, with the exception
+          # of :model_class which needs to be removed before passing along
+          opts[:key] = request_key
+          opts[:table_name] = table_name
+          {
+            model_class: self,
+            get: opts
+          }
+        end
+
+        # @example Usage Example
+        #   class Table
+        #     include Aws::Record
+        #     string_attr :hk, hash_key: true
+        #     string_attr :rk, range_key: true
+        #   end
+        #   
+        #   results = Table.transact_find(
+        #     transact_items: [
+        #       {key: { hk: "hk1", rk: "rk1"}},
+        #       {key: { hk: "hk2", rk: "rk2"}}
+        #     ]
+        #   ) # => results.responses contains nil or instances of Table
+        #
+        # Provides a way to run a transactional find across multiple DynamoDB
+        # items, including transactions which get items across multiple actual
+        # or virtual tables.
+        #
+        # @param [Hash] opts Options to pass through to
+        #   {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#transact_get_items-instance_method Aws::DynamoDB::Client#transact_get_items},
+        #   with the exception of the :transact_items array, which uses the
+        #   +#tfind_opts+ operation on your model class to provide extra
+        #   metadata used to marshal your items after retrieval.
+        # @option opts [Array] :transact_items A set of options describing
+        #   instances of the model class to return.
+        # @return [OpenStruct] Structured like the client API response from
+        #   +#transact_get_items+, except that the +responses+ member contains
+        #   +Aws::Record+ items marshaled into the model class used to call
+        #   this method. See the usage example.
+        def transact_find(opts)
+          opts = opts.dup
+          transact_items = opts.delete(:transact_items)
+          global_transact_items = transact_items.map do |topts|
+            tfind_opts(topts)
+          end
+          opts[:transact_items] = global_transact_items
+          opts[:client] = dynamodb_client
+          Transactions.transact_find(opts)
+        end
+
         # @example Usage Example
         #   class MyModel
         #     include Aws::Record

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

@@ -0,0 +1,332 @@
+module Aws
+  module Record
+    module Transactions
+      class << self
+
+        # @example Usage Example
+        #   class TableOne
+        #     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" }),
+        #       TableTwo.tfind_opts(key: { hk: "hk1", rk: "rk1"}),
+        #       TableTwo.tfind_opts(key: { hk: "hk2", rk: "rk2"})
+        #     ]
+        #   ) # => results.responses contains nil or marshalled items
+        #   results.responses.map { |r| r.class } # [TableOne, TableTwo, TableTwo]
+        #
+        # Provides a way to run a transactional find across multiple DynamoDB
+        # items, including transactions which get items across multiple actual
+        # or virtual tables.
+        #
+        # @param [Hash] opts Options to pass through to
+        #   {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#transact_get_items-instance_method Aws::DynamoDB::Client#transact_get_items},
+        #   with the exception of the :transact_items array, which uses the
+        #   +#tfind_opts+ operation on your model class to provide extra
+        #   metadata used to marshal your items after retrieval.
+        # @option opts [Array] :transact_items A set of +#tfind_opts+ results,
+        #   such as those created by the usage example.
+        # @option opts [Aws::DynamoDB::Client] :client Optionally, you can pass
+        #   in your own client to use for the transaction calls.
+        # @return [OpenStruct] Structured like the client API response from
+        #   +#transact_get_items+, except that the +responses+ member contains
+        #   +Aws::Record+ items marshaled into the classes used to call
+        #   +#tfind_opts+ in each positional member. See the usage example.
+        def transact_find(opts)
+          opts = opts.dup
+          client = opts.delete(:client) || dynamodb_client
+          transact_items = opts.delete(:transact_items) # add nil check?
+          model_classes = []
+          client_transact_items = transact_items.map do |tfind_opts|
+            model_class = tfind_opts.delete(:model_class)
+            model_classes << model_class
+            tfind_opts
+          end
+          request_opts = opts
+          request_opts[:transact_items] = client_transact_items
+          client_resp = client.transact_get_items(
+            request_opts
+          )
+          responses = client_resp.responses
+          index = -1
+          ret = OpenStruct.new
+          ret.consumed_capacity = client_resp.consumed_capacity
+          ret.missing_items = []
+          ret.responses = client_resp.responses.map do |item|
+            index += 1
+            if item.nil? || item.item.nil?
+              missing_data = {
+                model_class: model_classes[index],
+                key: transact_items[index][:get][:key]
+              }
+              ret.missing_items << missing_data
+              nil
+            else
+              # need to translate the item keys
+              raw_item = item.item
+              model_class = model_classes[index]
+              new_item_opts = {}
+              raw_item.each do |db_name, value|
+                name = model_class.attributes.db_to_attribute_name(db_name)
+                new_item_opts[name] = value
+              end
+              item = model_class.new(new_item_opts)
+              item.clean!
+              item
+            end
+          end
+          ret
+        end
+
+        # @example Usage Example
+        #   class TableOne
+        #     include Aws::Record
+        #     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",
+        #     expression_attribute_names: {
+        #       "#T" => "body"
+        #     },
+        #     expression_attribute_values: {
+        #       ":v" => 1024
+        #     }
+        #   )
+        #   new_item = TableTwo.new(hk: "hk1", rk: "rk1", body: "Hello!")
+        #   update_item_1 = TableOne.find(uuid: "bar")
+        #   update_item_1.body = "Updated the body!"
+        #   put_item = TableOne.new(uuid: "foobar", body: "Content!")
+        #   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 },
+        #       { save: new_item },
+        #       { save: update_item_1 },
+        #       {
+        #          put: put_item,
+        #          condition_expression: "attribute_not_exists(#H)",
+        #          expression_attribute_names: { "#H" => "uuid" },
+        #          return_values_on_condition_check_failure: "ALL_OLD"
+        #       },
+        #       { update: update_item_2 },
+        #       { delete: delete_item }
+        #     ]
+        #   )
+        #
+        # Provides a way to pass in aws-record items into transactional writes,
+        # as well as adding the ability to run 'save' commands in a transaction
+        # while allowing aws-record to determine if a :put or :update operation
+        # is most appropriate. +#transact_write+ supports 5 different transact
+        # item modes:
+        # - save: Behaves much like the +#save+ operation on the item itself.
+        #   If the keys are dirty, and thus it appears to be a new item, will
+        #   create a :put operation with a conditional check on the item's
+        #   existance. Note that you cannot bring your own conditional
+        #   expression in this case. If you wish to force put or add your
+        #   own conditional checks, use the :put operation.
+        # - put: Does a force put for the given item key and model.
+        # - update: Does an upsert for the given item.
+        # - delete: Deletes the given item.
+        # - check: Takes the result of +#transact_check_expression+,
+        #   performing the specified check as a part of the transaction.
+        #
+        # @param [Hash] opts Options to pass through to
+        #   {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#transact_write_items-instance_method Aws::DynamoDB::Client#transact_write_items}
+        #   with the exception of :transact_items array, which is transformed
+        #   to use your item to populate the :key, :table_name, :item, and/or
+        #   :update_expression parameters as appropriate. See the usage example
+        #   for a comprehensive set of combinations.
+        # @option opts [Array] :transact_items An array of hashes, accepting
+        #   +:save+, +:put+, +:delete+, +:update+, and +:check+ as specified.
+        # @option opts [Aws::DynamoDB::Client] :client Optionally, you can
+        #   specify a client to use for this transaction call. If not
+        #   specified, the configured client for +Aws::Record::Transactions+
+        #   is used.
+        def transact_write(opts)
+          opts = opts.dup
+          client = opts.delete(:client) || dynamodb_client
+          dirty_items = []
+          delete_items = []
+          # fetch abstraction records
+          transact_items = _transform_transact_write_items(
+            opts.delete(:transact_items),
+            dirty_items,
+            delete_items
+          )
+          opts[:transact_items] = transact_items
+          resp = client.transact_write_items(opts)
+          # mark all items clean/destroyed as needed if we didn't raise an exception
+          dirty_items.each { |i| i.clean! }
+          delete_items.each { |i| i.instance_variable_get("@data").destroyed = true }
+          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|
+            # this code will assume users only provided one operation, and
+            # will fail down the line if that assumption is wrong
+            if save_record = item.delete(:save)
+              dirty_items << save_record
+              _transform_save_record(save_record, item)
+            elsif put_record = item.delete(:put)
+              dirty_items << put_record
+              _transform_put_record(put_record, item)
+            elsif delete_record = item.delete(:delete)
+              delete_items << delete_record
+              _transform_delete_record(delete_record, item)
+            elsif update_record = item.delete(:update)
+              dirty_items << update_record
+              _transform_update_record(update_record, item)
+            elsif check_record = item.delete(:check)
+              _transform_check_record(check_record, item)
+            else
+              raise ArgumentError.new(
+                "Invalid transact write item, must include an operation of "\
+                  "type :save, :update, :delete, :update, or :check - #{item}"
+              )
+            end
+          end
+        end
+
+        def _transform_save_record(save_record, opts)
+          # determine if record is considered a new item or not
+          # then create a put with conditions, or an update
+          if save_record.send(:expect_new_item?)
+            safety_expression = save_record.send(:prevent_overwrite_expression)
+            if opts.include?(:condition_expression)
+              raise Errors::TransactionalSaveConditionCollision.new(
+                "Transactional write includes a :save operation that would "\
+                  "result in a 'safe put' for the given item, yet a "\
+                  "condition expression was also provided. This is not "\
+                  "currently supported. You should rewrite this case to use "\
+                  "a :put transaction, adding the existence check to your "\
+                  "own condition expression if desired.\n"\
+                  "\tItem: #{JSON.pretty_unparse(save_record.to_h)}\n"\
+                  "\tExtra Options: #{JSON.pretty_unparse(opts)}"
+              )
+            else
+              opts = opts.merge(safety_expression)
+              _transform_put_record(save_record, opts)
+            end
+          else
+            _transform_update_record(save_record, opts)
+          end
+        end
+
+        def _transform_put_record(put_record, opts)
+          # convert to a straight put
+          opts[:table_name] = put_record.class.table_name
+          opts[:item] = put_record.send(:_build_item_for_save)
+          { put: opts }
+        end
+
+        def _transform_delete_record(delete_record, opts)
+          # extract the key from each record to perform a deletion
+          opts[:table_name] = delete_record.class.table_name
+          opts[:key] = delete_record.send(:key_values)
+          { delete: opts }
+        end
+
+        def _transform_update_record(update_record, opts)
+          # extract dirty attribute changes to perform an update
+          opts[:table_name] = update_record.class.table_name
+          dirty_changes = update_record.send(:_dirty_changes_for_update)
+          update_tuple = update_record.class.send(
+            :_build_update_expression,
+            dirty_changes
+          )
+          uex, exp_attr_names, exp_attr_values = update_tuple
+          opts[:key] = update_record.send(:key_values)
+          opts[:update_expression] = uex
+          # need to combine expression attribute names and values
+          if names = opts[:expression_attribute_names]
+            opts[:expression_attribute_names] = exp_attr_names.merge(names)
+          else
+            opts[:expression_attribute_names] = exp_attr_names
+          end
+          if values = opts[:expression_attribute_values]
+            opts[:expression_attribute_values] = exp_attr_values.merge(values)
+          else
+            opts[:expression_attribute_values] = exp_attr_values
+          end
+          { update: opts }
+        end
+
+        def _transform_check_record(check_record, opts)
+          # 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
+end

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

@@ -13,6 +13,6 @@
 
 module Aws
   module Record
-    VERSION = '2.2.0'
+    VERSION = '2.3.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-record
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Amazon Web Services
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-12-05 00:00:00.000000000 Z
+date: 2019-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-dynamodb
@@ -58,6 +58,7 @@ files:
 - lib/aws-record/record/secondary_indexes.rb
 - lib/aws-record/record/table_config.rb
 - 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
 licenses: