mara 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c8a17c4c4d301602b87a18e8c682297d1cd24c9c5085d2b0aa2115d70b819d40
+  data.tar.gz: e31b906856bc625c4630661a6867cdbdd65c0cb1c22627859f217173eab83cb1
+SHA512:
+  metadata.gz: 5fb35cfd11fec4f646e2b2ea6cc632526dee9eb550ac5e79f4655cb0bdf7d81580f8e48068bc8cf17551ff388c90de6f12fe4d0a00dea45fed2188af5de5b7d9
+  data.tar.gz: ef06b2d073323d716031c97a20e5c71d53b20099916154b48e2f507b0ba1bb2277a7eea3684a94a186e809175cb323371efddf62c54b44ff34229f7d4df42b57

data/README.md

@@ -0,0 +1,3 @@
+# Mara
+
+DynamoDB client.

data/Rakefile

@@ -0,0 +1,26 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+namespace :docs do
+  desc 'Generate docs'
+  task :generate do
+    YARD::CLI::Yardoc.run
+  end
+
+  desc 'Get docs stats'
+  task :stats do
+    YARD::CLI::Stats.run('--list-undoc')
+  end
+
+  desc 'View docs'
+  task :view do
+    # Viewing should always generate the freshest
+    Rake::Task['docs:generate'].invoke
+    exec("open #{File.expand_path('./doc/index.html', __dir__)}")
+  end
+end

data/lib/mara.rb

@@ -0,0 +1,13 @@
+require 'mara/batch'
+require 'mara/client'
+require 'mara/configure'
+require 'mara/error'
+require 'mara/model'
+require 'mara/table'
+require 'mara/version'
+
+##
+# Mara is a wrapper around DynamoDB that adds a model layer and a bunch of
+# convenience functions.
+module Mara
+end

data/lib/mara/attribute_formatter.rb

@@ -0,0 +1,161 @@
+require 'aws-sdk-dynamodb'
+
+require_relative 'error'
+require_relative 'null_value'
+
+module Mara
+  ##
+  # Helper class that provides Attribute Formatting for DynamoDB values.
+  #
+  # @author Maddie Schipper
+  # @since 1.0.0
+  class AttributeFormatter
+    ##
+    # The error that is raised if an attribute value fails to be converted into
+    # a valid DynamoDB value.
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
+    class Error <  Mara::Error; end
+
+    class << self
+      ##
+      # @private
+      #
+      # Format a value into a DynamoDB valid format.
+      #
+      # @param value [Object] The value to be formatted.
+      #
+      # @return [Hash]
+      def format(value)
+        case value
+        when true, false
+          { bool: value }
+        when nil,  Mara::NullValue
+          { null: true }
+        when String
+          { s: value }
+        when Symbol
+          { s: value.to_s }
+        when Numeric
+          { n: value.to_s }
+        when Time
+          { n: value.utc.to_i.to_s }
+        when DateTime, Date
+          format(value.to_time)
+        when Hash
+          format_hash(value)
+        when Array
+          format_array(value)
+        when Set
+          format_set(value)
+        else
+          raise Error, "Unexpected value type #{value.class.name} <#{value}>"
+        end
+      end
+
+      ##
+      # @private
+      #
+      # Convert a Aws::DynamoDB::Types::AttributeValue to a raw value
+      #
+      # @param value [Aws::DynamoDB::Types::AttributeValue] The value to convert
+      #
+      # @return [Object]
+      def flatten(value)
+        unless value.is_a?(Aws::DynamoDB::Types::AttributeValue)
+          raise ArgumentError, 'Not an attribute type'
+        end
+
+        if value.s.present?
+          value.s
+        elsif value.n.present?
+          format_number(value.n)
+        elsif value.ss.present?
+          Set.new(value.ss)
+        elsif value.ns.present?
+          Set.new(value.ns.map { |v| format_number(v) })
+        elsif value.m.present?
+          flatten_hash(value.m)
+        elsif value.l.present?
+          flatten_array(value.l)
+        elsif value.null
+           Mara::NULL
+        elsif !value.bool.nil?
+          value.bool
+        else
+          raise Error, 'Unexpected value type from DynamoDB'
+        end
+      end
+
+      private
+
+      def format_number(number)
+        if number.include?('.')
+          number.to_f
+        else
+          number.to_i
+        end
+      end
+
+      def flatten_hash(hash)
+        hash.each_with_object({}) do |(key, value), object|
+          object[key] = flatten(value)
+        end
+      end
+
+      def flatten_array(array)
+        array.map { |value| flatten(value) }
+      end
+
+      def format_array(array)
+        value = Array(array)
+        if value.empty?
+          return format(nil)
+        end
+
+        values = value.map do |val|
+          format(val)
+        end
+
+        { l: values }
+      end
+
+      def format_hash(hash)
+        value = Hash(hash)
+        if value.empty?
+          return format(nil)
+        end
+
+        formatted = value.each_with_object({}) do |(key, sub_value), object|
+          next unless value.present?
+
+          object[key.to_s] = format(sub_value)
+        end
+
+        { m: formatted }
+      end
+
+      def format_set(set)
+        value = Set.new(set.to_a)
+        if value.empty?
+          return format(nil)
+        end
+
+        kind = value.map(&:class).uniq
+
+        if kind.count != 1 && kind.to_a.reject { |v| v.ancestors.include?(Numeric) }.any?
+          raise Error, "Set type must only contain 1 type #{value.class.name}"
+        end
+
+        if kind.first == String || kind.first == Symbol
+          { ss: value.to_a.map(&:to_s) }
+        elsif kind.first.ancestors.include?(Numeric)
+          { ns: value.to_a.map(&:to_s) }
+        else
+          raise Error, "Unexpected Set type #{kind.first.class.name}"
+        end
+      end
+    end
+  end
+end

data/lib/mara/batch.rb

@@ -0,0 +1,223 @@
+require_relative 'persistence'
+require_relative 'instrument'
+
+module Mara
+  ##
+  # Raise this within a { Mara::Batch#in_batch} to quietly rollback the batch.
+  #
+  # @note All current operations will be dropped.
+  #
+  # @author Maddie Schipper
+  # @since 1.0.0
+  class Rollback < StandardError; end
+
+  ##
+  # Perform operations in batches.
+  #
+  # @note This is not the same as a transaction. It only saves on the number
+  #   of API calls to DynamoDB.
+  #
+  # @example Saving Multiple Records
+  #   Mara::Batch.in_batch do
+  #     person1.save
+  #     person2.save
+  #   end
+  #
+  # @author Maddie Schipper
+  # @since 1.0.0
+  class Batch
+    ##
+    # @private
+    #
+    # The name of the thread variable that holds the current batch spec.
+    BATCH_STACK_VAR_NAME = 'mara_batch'.freeze
+
+    class << self
+      ##
+      # Perform in a batch.
+      #
+      # All save/destroy calls on a model will be routed into the current batch.
+      #
+      # If there is a error raised all operations will be dropped.
+      #
+      # If the error is a { Mara::Rollback} the batch will silently rollback.
+      # If not, it will be re-thrown after the rollback.
+      #
+      # @yield The batch operation.
+      def in_batch
+        begin_new_batch
+        begin
+          yield
+        rescue  Mara::Rollback
+          abort_current_batch
+        # rubocop:disable Lint/RescueException
+        rescue Exception => exception
+          # rubocop:enable Lint/RescueException
+          abort_current_batch
+          raise exception
+        else
+          commit_current_batch
+        end
+      end
+
+      ##
+      # @private
+      #
+      # Perform a save model. If there is a current batch it is added to the
+      # operation queue. If there is no current batch, this will be forwarded
+      # directly to the { Mara::Persistence}.
+      #
+      # @param item [Hash] The model to perform the action with.
+      def save_model(item)
+        perform_for_model(:save_model, item)
+      end
+
+      ##
+      # @private
+      #
+      # Perform a save model. If there is a current batch it is added to the
+      # operation queue. If there is no current batch, this will be forwarded
+      # directly to the { Mara::Persistence}.
+      #
+      # @param item [Hash] The model to perform the action with.
+      def save_model!(item)
+        perform_for_model(:save_model!, item)
+      end
+
+      ##
+      # @private
+      #
+      # Perform a delete model. If there is a current batch it is added to the
+      # operation queue. If there is no current batch, this will be forwarded
+      # directly to the { Mara::Persistence}.
+      #
+      # @param item [Hash] The model to perform the action with.
+      def delete_model(item)
+        perform_for_model(:delete_model, item)
+      end
+
+      ##
+      # @private
+      #
+      # Perform a delete model. If there is a current batch it is added to the
+      # operation queue. If there is no current batch, this will be forwarded
+      # directly to the { Mara::Persistence}.
+      #
+      # @param item [Hash] The model to perform the action with.
+      def delete_model!(item)
+        perform_for_model(:delete_model!, item)
+      end
+
+      private
+
+      def perform_for_model(action_name, item)
+        if (batch = current_batch)
+          batch.add(action_name, item)
+        else
+           Mara::Persistence.send(action_name, item)
+        end
+      end
+
+      def current_batch
+        batch_stack.first
+      end
+
+      def batch_stack
+        Thread.current[BATCH_STACK_VAR_NAME] ||= []
+      end
+
+      def begin_new_batch
+        batch_stack <<  Mara::Batch.new
+      end
+
+      def commit_current_batch
+        batch_stack.pop.commit_batch
+      end
+
+      def abort_current_batch
+        batch_stack.pop.abort_batch
+      end
+    end
+
+    ##
+    # @private
+    #
+    # The queue of operations to perform on commit.
+    #
+    # @return [Array<Array<Symbol, Hash>>]
+    attr_reader :operations
+
+    ##
+    # The current batch id.
+    #
+    # @return [String]
+    attr_reader :batch_id
+
+    ##
+    # @private
+    #
+    # Create a new batch.
+    def initialize
+      @batch_id = SecureRandom.uuid
+      @operations = []
+    end
+
+    ##
+    # @private
+    #
+    # Add an item to the operation queue.
+    #
+    # @param action_name [Symbol] The action to perform for the item.
+    # @param item [Hash] The hash of data for the action.
+    #
+    # @return [void]
+    def add(action_name, item)
+       Mara.instrument('batch.add_item', batch_id: batch_id, action: action_name, item: item) do
+        operations << [action_name, item]
+      end
+    end
+
+    ##
+    # @private
+    #
+    # Perform all the operations in the queue.
+    #
+    # @return [void]
+    def commit_batch
+       Mara.instrument('batch.commit', batch_id: batch_id) do
+        execute_commit
+      end
+    end
+
+    ##
+    # @private
+    #
+    # Abort the batch and clear the current batch operations.
+    #
+    # @return [void]
+    def abort_batch
+      @operations = []
+       Mara.instrument('batch.abort', batch_id: batch_id)
+    end
+
+    private
+
+    def execute_commit
+      ops = operations.map do |action_name, item|
+        case action_name
+        when :save_model, :save_model!
+           Mara::Persistence::CreateRequest.new(item)
+        when :delete_model, :delete_model!
+           Mara::Persistence::DestroyRequest.new(item)
+        else
+          raise "Unexpected operation action name #{action_name}"
+        end
+      end
+       Mara::Persistence.perform_requests(
+         Mara::Client.shared,
+         Mara.config.dynamodb.table_name,
+        ops
+      )
+    end
+  end
+end

data/lib/mara/client.rb

@@ -0,0 +1,43 @@
+require 'aws-sdk-dynamodb'
+
+require_relative 'configure'
+
+module Mara
+  ##
+  # @private
+  #
+  # Internal DynamoDB client.
+  #
+  # @author Maddie Schipper
+  # @since 1.0.0
+  class Client
+    class << self
+      ##
+      # @private
+      #
+      # Create a new DynamoDB client.
+      #
+      # @return [Aws::DynamoDB::Client]
+      def create_client
+        params = {
+          region:  Mara.config.aws.region,
+          simple_attributes: false
+        }
+        if (endpoint =  Mara.config.dynamodb.endpoint)
+          params[:endpoint] = endpoint
+        end
+        Aws::DynamoDB::Client.new(params)
+      end
+
+      ##
+      # @private
+      #
+      # The shared client.
+      #
+      # @return [Aws::DynamoDB::Client]
+      def shared
+        @shared ||= create_client
+      end
+    end
+  end
+end