dynomite 1.2.7 → 2.0.0

data/lib/dynomite/item/read.rb

@@ -0,0 +1,90 @@
+class Dynomite::Item
+  module Read
+    extend ActiveSupport::Concern
+    include Find
+    include FindWithEvent
+    include Query
+
+    class_methods do
+      # Override Enumerable#first to limit to 1 item as optimization
+      def first
+        all.limit(1).first
+      end
+
+      # Adds very little wrapper logic to scan.
+      #
+      # * Automatically add table_name to options for convenience.
+      # * Decorates return value.  Returns Array of [MyModel.new] instead of the
+      #   dynamodb client response.
+      #
+      # Other than that, usage is same was using the dynamodb client scan method
+      # directly.  Example:
+      #
+      #   MyModel.scan(
+      #     expression_attribute_names: {"#updated_at"=>"updated_at"},
+      #     expression_attribute_values: {
+      #       ":start_time" => "2010-01-01T00:00:00",
+      #       ":end_time" => "2020-01-01T00:00:00"
+      #     },
+      #     filter_expression: "#updated_at between :start_time and :end_time",
+      #   )
+      #
+      # AWS Docs examples: http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStarted.Ruby.04.html
+      def scan(params={})
+        params = { table_name: table_name }.merge(params)
+        resp = client.scan(params)
+        logger.info("REQUEST: #{params}")
+        resp.items.map {|i| self.new(i) }
+      end
+
+      # Adds very little wrapper logic to query.
+      #
+      # * Automatically add table_name to options for convenience.
+      # * Decorates return value.  Returns Array of [MyModel.new] instead of the
+      #   dynamodb client response.
+      #
+      # Other than that, usage is same was using the dynamodb client query method
+      # directly.  Example:
+      #
+      #   MyModel.query(
+      #     index_name: 'category-index',
+      #     expression_attribute_names: { "#category_name" => "category" },
+      #     expression_attribute_values: { ":category_value" => "Entertainment" },
+      #     key_condition_expression: "#category_name = :category_value",
+      #   )
+      #
+      # AWS Docs examples: http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStarted.Ruby.04.html
+      def query(params={})
+        params = { table_name: table_name }.merge(params)
+        resp = client.query(params)
+        resp.items.map { |i| self.new(i) }
+      end
+
+      def count
+        if Dynomite.config.default_count_method.to_sym == :item_count
+          item_count
+        else
+          scan_count
+        end
+      end
+      alias_method :size, :count
+
+      def scan_count
+        warn_scan <<~EOL
+          WARN: Using scan to count. Though it is more accurate.
+          It can be slow and expensive. You can use item_count instead.
+          Note: item_count may be stale for about 6 hours.
+          You can set the Dynomite.config.default_count_method = :item_count to make it the default.
+        EOL
+        all.count
+      end
+
+      # https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Table.html#item_count-instance_method
+      # DynamoDB updates this value approximately every six hours.
+      def item_count
+        table = Aws::DynamoDB::Table.new(name: table_name, client: client)
+        table.item_count # fast but can be stale
+      end
+    end
+  end
+end

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