dynomite 1.2.7 → 2.0.1

data/lib/dynomite/item/sti.rb

@@ -0,0 +1,43 @@
+class Dynomite::Item
+  module Sti
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :inheritance_field_name
+    end
+
+    class_methods do
+      def enable_sti(field_name='type')
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def self.inherited(subclass)
+            field :#{field_name} # IE: field_name :type
+            subclass.table_name(sti_base_table_name) # IE: subclass: Car base_table: vehicles
+            subclass.inheritance_field_name = :#{field_name}
+
+            before_save :set_type
+            super
+          end
+        RUBY
+      end
+      alias inheritance_field enable_sti
+
+      def sti_base_table_name
+        klass = self
+        table_name = nil
+        until klass.abstract? # IE: ApplicationItem
+          table_name = klass.name.pluralize.gsub('::','_').underscore # vehicles
+          klass = klass.superclass
+        end
+        table_name
+      end
+
+      def sti_enabled?
+        inheritance_field_name.present?
+      end
+    end
+
+    def set_type
+      self[self.class.inheritance_field_name] = self.class.name
+    end
+  end
+end

data/lib/dynomite/item/table_namespace.rb

@@ -0,0 +1,43 @@
+class Dynomite::Item
+  module TableNamespace
+    def table_name(*args)
+      case args.size
+      when 0
+        get_table_name
+      when 1
+        set_table_name(args[0])
+      end
+    end
+
+    def set_table_name(value)
+      @table_name = value
+    end
+
+    def get_table_name
+      @table_name ||= self.name.pluralize.gsub('::','_').underscore
+      [namespace, @table_name].reject {|s| s.nil? || s.empty?}.join(namespace_separator)
+    end
+
+    def namespace(*args)
+      case args.size
+      when 0
+        get_namespace
+      when 1
+        set_namespace(args[0])
+      end
+    end
+
+    def get_namespace
+      return @namespace if defined?(@namespace)
+      @namespace = Dynomite.config.namespace || Dynomite.config.default_namespace
+    end
+
+    def set_namespace(value)
+      @namespace = value
+    end
+
+    def namespace_separator
+      Dynomite.config.namespace_separator || '_'
+    end
+  end
+end

data/lib/dynomite/item/typecaster.rb

@@ -0,0 +1,106 @@
+require "time"
+
+# aws-sdk-dynamodb handles typecast heavy-lifting. Adds typecasting support for DateTime objects.
+class Dynomite::Item
+  class Typecaster
+    def initialize(model)
+      @model = model
+    end
+
+    def dump(data, depth=0)
+      case data
+      when Array
+        data.map! { |v| dump(v, depth+1) }
+      when Hash
+        data.each_with_object({}) do |(k,v), dumped|
+          if depth == 0
+            v = cast_to_attribute_type(k, v) # cast to attribute type if defined
+          end
+          dumped[k] = dump(v, depth+1)
+          dumped
+        end
+      else
+        data # pass through
+      end
+    end
+
+    # IE: field :price, type: :integer
+    # For most cases, we rely on aws-sdk-dynamodb to do the typecasting by inference.
+    #
+    # The method also helps keep track of where we cast_to_type
+    # It's only a few spots this provides an easy to search for it.
+    # See: https://rubyonjets.com/docs/database/dynamodb/model/typecasting/
+    FALSEY = [false, 'false', 'FALSE', 0, '0', 'f', 'F', 'off', 'OFF']
+    def cast_to_type(type, value, on: :read)
+      case type
+      when :integer
+        value.to_i
+      when :boolean
+        !FALSEY.include?(value)
+      when :time
+        cast_to_time(value, on: on)
+      when :string
+        value.to_s # force to string
+      else # :infer
+        value # passthrough and let aws-sdk-dynamodb handle it
+      end
+    end
+
+    # datetime to string
+    def cast_to_time(value, on: :read)
+      if on == :read
+        if value.is_a?(String)
+          Time.parse(value) # 2023-08-26T14:35:37Z
+        elsif value.respond_to?(:to_datetime) # time-like object already Time or DateTime
+          value
+        end
+      else # write or raw (for querying)
+        if value.respond_to?(:to_datetime) && !value.is_a?(String)
+          value.utc.strftime('%Y-%m-%dT%TZ') # Timestamp format iso8601 from AWS docs: http://amzn.to/2z98Bdc
+        else
+          value # passthrough string
+        end
+      end
+    end
+
+    # string to float if attribute_type is N
+    # number to string if attribute_type is S
+    def cast_to_attribute_type(attribute_name, attribute_value)
+      definition = @model.attribute_definitions.find { |d| d[:attribute_name] == attribute_name.to_s }
+      if definition
+        case definition[:attribute_type]
+        when "N"  # Number
+          attribute_value.to_f
+        when "S"  # String
+          attribute_value.to_s
+        when "BOOL" # Boolean
+          attribute_value == true
+        else
+          attribute_value # passthrough
+        end
+      else
+        attribute_value # passthrough
+      end
+    end
+
+    def load(data)
+      case data
+      when Array
+        data.map! { |v| load(v) }
+      when Hash
+        data.each_with_object({}) do |(k,v), loaded|
+          loaded[k] = load(v)
+          loaded
+        end
+      else
+        load_item(data)
+      end
+    end
+
+    REGEXP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/
+    def load_item(obj)
+      return obj unless obj.is_a?(String)
+      obj.match(REGEXP) ? Time.parse(obj) : obj
+    end
+  end
+end

data/lib/dynomite/item/waiter_methods.rb

@@ -0,0 +1,18 @@
+class Dynomite::Item
+  module WaiterMethods
+    extend ActiveSupport::Concern
+
+    def waiter
+      self.class.waiter
+    end
+
+    class_methods do
+      extend Memoist
+
+      def waiter
+        Dynomite::Waiter.new
+      end
+      memoize :waiter
+    end
+  end
+end

data/lib/dynomite/item/write/base.rb

@@ -0,0 +1,15 @@
+module Dynomite::Item::Write
+  class Base
+    include Dynomite::Client
+
+    # The attributes are in model.attrs and are held by reference
+    # The options are the client.delete_item or client.put_item options.
+    def self.call(model, options={})
+      new(model, options).call
+    end
+
+    def initialize(model, options={})
+      @model, @options = model, options
+    end
+  end
+end

data/lib/dynomite/item/write/delete_item.rb

@@ -0,0 +1,14 @@
+module Dynomite::Item::Write
+  class DeleteItem < Base
+    def call
+      key = @model.attrs.slice(@model.class.partition_key_field, @model.class.sort_key_field)
+      params = {
+        table_name: @model.class.table_name,
+        key: key
+      }
+      # In case you want to specify condition_expression or expression_attribute_values
+      params = params.merge(@options)
+      client.delete_item(params) # resp
+    end
+  end
+end

data/lib/dynomite/item/write/put_item.rb

@@ -0,0 +1,99 @@
+module Dynomite::Item::Write
+  class PutItem < Base
+    def call
+      # typecaster will convert the attrs to the correct types for saving to DynamoDB
+      item = Dynomite::Item::Typecaster.new(@model).dump(permitted_attrs)
+      @params = {
+        table_name: @model.class.table_name,
+        item: item
+      }
+      @params.merge!(check_unique_params)
+      @params.merge!(locking_params)
+
+      # put_item replaces the item fully. The resp does not contain the attrs.
+      log_debug(@params)
+      begin
+        client.put_item(@params)
+      rescue Aws::DynamoDB::Errors::ConditionalCheckFailedException => e
+        handle_conditional_check_failed_exception(e)
+      rescue Aws::DynamoDB::Errors::ValidationException => e
+        @model.reset_lock_version_was if @model.class.locking_enabled?
+        raise
+      end
+
+      @model.new_record = false
+      @model
+    end
+
+    def permitted_attrs
+      field_names = @model.class.field_names.map(&:to_sym)
+      assigned_fields = @model.attrs.keys.map(&:to_sym)
+      undeclared_fields = assigned_fields - field_names
+      declared_fields = field_names - assigned_fields
+
+      case Dynomite.config.undeclared_field_behavior.to_sym
+      when :allow
+        @model.attrs # allow
+      when :silent
+        @model.attrs.slice(*field_names)
+      when :error
+        unless undeclared_fields.empty?
+          raise Dynomite::Error::UndeclaredFields.new("ERROR: Saving undeclared fields not allowed: #{undeclared_fields} for #{@model.class}")
+        end
+      else # warn
+        unless undeclared_fields.empty?
+          logger.info "WARNING: Not saving undeclared fields: #{undeclared_fields}. Saving declared fields only: #{declared_fields} for #{@model.class}"
+        end
+        @model.attrs.slice(*field_names)
+      end
+    end
+
+    def handle_conditional_check_failed_exception(exception)
+      if @params[:condition_expression] == check_unique_condition
+        raise Dynomite::Error::RecordNotUnique.new(not_unique_message)
+      else # currently only other case is locking
+        raise Dynomite::Error::StaleObject.new(exception.message)
+      end
+    end
+
+    def not_unique_message
+      primary_key_attrs = permitted_attrs.stringify_keys.slice(@model.partition_key_field, @model.sort_key_field).symbolize_keys
+      primary_key_found = primary_key_attrs.keys.map(&:to_s)
+      "A #{@model.class.name} with the primary key #{primary_key_attrs} already exists"
+    end
+
+    def check_unique_params
+      if @model.new_record? && !@options[:put]
+        @params.merge!(condition_expression: check_unique_condition)
+      else
+        {}
+      end
+    end
+
+    # https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html#Expressions.ConditionExpressions.PreventingOverwrites
+    # Examples:
+    #   attribute_not_exists(id)
+    #   attribute_not_exists(category) AND attribute_not_exists(sku)
+    def check_unique_condition
+      condition_expression = @model.primary_key_fields.map do |field|
+        "attribute_not_exists(#{field})"
+      end.join(" AND ")
+    end
+
+    def locking_params
+      return {} if @params[:condition_expression] # already set from check_unique_params
+      return {} unless @model.class.locking_enabled?
+      return {} if @model._touching
+      field = @model.class.locking_field_name
+      current_version = @model.send(field) # must use send, since it was set by send. fixes .touch method
+      return {} if current_version == 1
+
+      previous_version = current_version - 1 # since before_save increments it
+      {
+        condition_expression: "#lock_version = :lock_version",
+        expression_attribute_names: {"#lock_version" => "lock_version"},
+        expression_attribute_values: {":lock_version" => previous_version}
+      }
+    end
+  end
+end

data/lib/dynomite/item/write/update_item.rb

@@ -0,0 +1,73 @@
+module Dynomite::Item::Write
+  class UpdateItem < Base
+    def initialize(model, options={})
+      super
+      @attrs = {}
+      @count_changes = {}
+    end
+
+    # Note: fields assigned directly with brackets are not tracked as changed
+    # IE: post[:title] = "test"
+    def call
+      changed_fields = @model.changed_attributes.keys
+      return if changed_fields.empty? # no changes to save
+      @attrs = @model.attrs.slice(*changed_fields)
+      log_debug(params)
+      client.update_item(params)
+    end
+
+    # Allows updates to specific attributes and counters
+    def save_changes(changes={})
+      @attrs = changes[:attrs] || {}
+      @count_changes = changes[:count_changes] || {}
+      log_debug(params)
+      client.update_item(params)
+    end
+
+    def params
+      {
+        expression_attribute_names: expression_attribute_names, # { "##{attribute}" => attribute },
+        expression_attribute_values: expression_attribute_values, # { ':attribute' => value } or { ':by' => by }
+        update_expression: update_expression, # "SET ##{attribute} = ##{attribute}" or "SET ##{attribute} = ##{attribute} + :by"
+        key: @model.primary_key,
+        table_name: @model.class.table_name
+      }
+    end
+    alias to_params params
+
+    def expression_attribute_names
+      attr_names = @attrs.inject({}) do |names, (name,_)|
+        names.merge!("##{name}" => name)
+      end
+      count_names = @count_changes.inject({}) do |names, (name,_)|
+        names.merge!("##{name}" => name)
+      end
+      attr_names.merge(count_names)
+    end
+
+    def expression_attribute_values
+      typecaster = Dynomite::Item::Typecaster.new(@model)
+      attr_values = @attrs.inject({}) do |values, (name,value)|
+        meta = @model.class.fields_meta[name.to_sym] # can be nil if field is not defined
+        type = meta ? meta[:type] : :infer
+        value = typecaster.cast_to_type(type, value, on: :write)
+        values.merge!(":#{name}" => value)
+      end
+      count_values = @count_changes.inject({}) do |values, (name,value)|
+        values.merge!(":#{name}" => value)
+      end
+      attr_values.merge(count_values)
+    end
+
+    def update_expression
+      expressions = []
+      @attrs.inject([]) do |exp, (name,_)|
+        expressions << "##{name} = :#{name}"
+      end
+      @count_changes.inject([]) do |exp, (name,_)|
+        expressions << "##{name} = ##{name} + :#{name}"
+      end
+      "SET " + expressions.join(', ')
+    end
+  end
+end

data/lib/dynomite/item/write.rb

@@ -0,0 +1,204 @@
+class Dynomite::Item
+  module Write
+    extend ActiveSupport::Concern
+
+    # Not using method_missing to allow usage of dot notation and assign
+    # @attrs because it might hide actual missing methods errors.
+    # DynamoDB attrs can go many levels deep so it makes less make sense to
+    # use to dot notation.
+
+    def save(options={})
+      options.reverse_merge!(validate: true)
+      return self if options[:validate] && !valid?
+
+      action = new_record? ? :create : :update
+      run_callbacks(:save) do
+        run_callbacks(action) do
+          if action == :create
+            PutItem.call(self, options)
+          else # :update
+            call_update_strategy(options)
+          end
+        end
+      end
+    end
+
+    # Similar to save, but raises an error on failed validation.
+    def save!(options={})
+      raise_error_if_invalid
+      save(options)
+    end
+
+    # post.update(title: "test", body: "body")
+    # post.update({title: "test", body: "body"}, {validate: false})
+    def update(attrs={}, options={})
+      self.attrs.merge!(attrs)
+      options.reverse_merge!(validate: true)
+      return false if options[:validate] && !valid?
+
+      run_callbacks(:save) do
+        run_callbacks(:update) do
+          call_update_strategy(options)
+        end
+      end
+    end
+
+    def call_update_strategy(options)
+      if Dynomite.config.update_strategy == :update_item
+        # Note: fields assigned directly with brackets are not tracked as changed
+        # IE: post[:title] = "test"
+        UpdateItem.call(self, options)
+      else # default
+        PutItem.call(self, options)
+      end
+    end
+
+    # Similar to update, but raises an error on failed validation.
+    def update!(attrs={}, options={})
+      raise_error_if_invalid
+      update(attrs, options)
+    end
+
+    # When you add an item, the primary key attributes are the only required attributes.
+    # https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#put_item-instance_method
+    def put(options={})
+      found_primary_keys = self.attrs.keys.map(&:to_s) & primary_key_fields
+      unless primary_key_fields.sort == found_primary_keys
+        raise Dynomite::Error::InvalidPut.new("Invalid put. The primary key fields #{primary_key_fields} must be present in the attrs #{attrs}")
+      end
+
+      options.reverse_merge!(validate: true)
+      return self if options[:validate] && !valid? # return self so can grab errors in invalid. save does the same thing
+
+      # Run callbacks for put so id is also set
+      run_callbacks(:save) do
+        run_callbacks(:update) do
+          PutItem.call(self, options.merge(put: true))
+        end
+      end
+    end
+    alias replace put
+
+    def put!(options={})
+      raise_error_if_invalid
+      put(options)
+    end
+    alias replace! put!
+
+    def destroy(options={})
+      run_callbacks(:destroy) do
+        DeleteItem.call(self, options)
+      end
+    end
+
+    def delete(options={})
+      DeleteItem.call(self, options)
+    end
+
+    attr_reader :_touching
+    def touch(*names, **options)
+      if new_record?
+        raise Dynomite::Error, 'cannot touch on a new item'
+      end
+
+      time_to_assign = options.delete(:time) || Time.now
+
+      self.updated_at = time_to_assign
+      names.each do |name|
+        attrs.send("#{name}=", time_to_assign)
+      end
+
+      @_touching = true
+      run_callbacks :touch do
+        UpdateItem.call(self, options)
+      end
+
+      self
+    end
+
+    # Examples:
+    #   user.increment(:likes)
+    #   user.increment(:likes, 2)
+    def increment(attribute, by = 1)
+      self[attribute] ||= 0
+      self[attribute] += by
+      self
+    end
+
+    # Increment counter. Validations and callbacks are skipped.
+    #
+    # Examples:
+    #
+    #   user.increment!(:likes)
+    #   user.increment!(:likes, 2)
+    #   user.increment!(:likes, touch: true)
+    #   user.increment!(:likes, touch: :created_at)
+    #   user.increment!(:likes, touch: [:viewed_at, :created_at])
+    #
+    def increment!(attribute, by = 1, touch: nil)
+      increment(attribute, by)
+
+      now = Time.now
+      attrs = Array(touch).inject({}) do |attrs, field|
+        attrs.merge!(field => now)
+      end if touch
+
+      run_callbacks :touch do
+        UpdateItem.new(self).save_changes(attrs: attrs, count_changes: { attribute => by })
+      end
+
+      self
+    end
+
+    # Example:
+    #
+    #   user = User.first
+    #   user.banned? # => false
+    #   user.toggle(:banned)
+    #   user.banned? # => true
+    #
+    def toggle(attribute)
+      self[attribute] = !public_send("#{attribute}?")
+      self
+    end
+
+    def toggle!(attribute)
+      toggle(attribute).update_attribute(attribute, self[attribute])
+    end
+
+    def raise_error_if_invalid
+      raise Dynomite::Error::Validation, "Validation failed: #{errors.full_messages.join(', ')}" unless valid?
+    end
+
+    class_methods do
+      def put(attrs={}, &block)
+        new(attrs, &block).put
+      end
+
+      def put!(attrs={}, &block)
+        new(attrs, &block).put!
+      end
+
+      def create(attrs={}, &block)
+        new(attrs, &block).save
+      end
+      alias create_with create
+
+      def create!(attrs={}, &block)
+        new(attrs, &block).save!
+      end
+
+      def find_or_create_by(attrs={})
+        find_by(attrs) || create(attrs)
+      end
+
+      def find_or_create_by!(attrs={})
+        find_by(attrs) || create!(attrs)
+      end
+
+      def find_or_initialize_by(attrs)
+        find_by(attrs) || new(attrs)
+      end
+    end
+  end
+end