mara 0.1.0

data/lib/mara/model/dsl.rb

@@ -0,0 +1,208 @@
+require_relative '../error'
+
+module Mara
+  module Model
+    ##
+    # An error raised if the index requested in
+    # {Dsl::ClassMethods.global_secondary_index} or
+    # {Dsl::ClassMethods.global_secondary_index} are not found.
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
+    class IndexError <  Mara::Error; end
+
+    ##
+    # Represents a DynamoDB Local Secondary Index.
+    #
+    # @see  Mara::Model::Dsl::ClassMethods#add_lsi
+    #
+    # @!attribute [rw] name
+    #   The name of the index.
+    #
+    #   @return [String]
+    #
+    # @!attribute [rw] key_name
+    #   The name of the LSI sort_key.
+    #
+    #   @return [String]
+    LocalSecondaryIndex = Struct.new(:name, :key_name)
+
+    ##
+    # Represents a DynamoDB Global Secondary Index.
+    #
+    # @see  Mara::Model::Dsl::ClassMethods#add_gsi
+    #
+    # @!attribute [rw] name
+    #   The name of the index.
+    #
+    #   @return [String]
+    #
+    # @!attribute [rw] partition_key
+    #   The name of the GSI partion key.
+    #
+    #   @return [String]
+    #
+    # @!attribute [rw] sort_key
+    #   The name of the GSI sort_key.
+    #
+    #   @return [String, nil]
+    GlobalSecondaryIndex = Struct.new(:name, :partition_key, :sort_key)
+
+    ##
+    # Helper DSL methods for Base class.
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
+    module Dsl
+      ##
+      # @private
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      ##
+      # Helper method added at the class level.
+      #
+      # @author Maddie Schipper
+      # @since 1.0.0
+      module ClassMethods
+        ##
+        # Set a partion_key and sort_key for a model.
+        #
+        # @see #partition_key
+        #
+        # @see #sort_key
+        #
+        # @example Setting the partition_key & sort_key
+        #   class Person <  Mara::Model::Base
+        #     primary_key('PartionKeyName', 'SortKeyName')
+        #     # ...
+        #
+        # @param partition_key [#to_s] The name of the DynamoDB table's partion
+        #   key.
+        #
+        # @param sort_key [#to_s, nil] The name of the DynamoDB table's sort
+        #   key.
+        #
+        # @return [void]
+        def primary_key(partition_key, sort_key = nil)
+          partition_key(partition_key)
+          sort_key(sort_key)
+        end
+
+        ##
+        # Set the partion key name for the model. This value is required.
+        #
+        # @param partition_key [#to_s] The name of the partion key.
+        #
+        # @return [String]
+        def partition_key(partition_key = nil)
+          unless partition_key.nil?
+            @partition_key = partition_key.to_s
+            validates_presence_of :partition_key
+          end
+          @partition_key
+        end
+
+        ##
+        # Set the sort key name for the model.
+        #
+        # @param sort_key [#to_s] The name of the sort key.
+        #
+        # @return [String]
+        def sort_key(sort_key = nil)
+          unless sort_key.nil?
+            @sort_key = sort_key.to_s
+            validates_presence_of :sort_key
+          end
+
+          @sort_key
+        end
+
+        ##
+        # Add a local secondary index definition.
+        #
+        # @note This is only required for querying.
+        #
+        # @param name [String] The name of the index.
+        #
+        # @param key_name [String] The name of the LSI sort key.
+        #
+        # @return [void]
+        def add_lsi(name, key_name)
+          local_secondary_indices[name.to_s] = LocalSecondaryIndex.new(name.to_s, key_name.to_s)
+        end
+
+        ##
+        # @private
+        #
+        # All registered local secondary indices
+        #
+        # @return [Hash<String, LocalSecondaryIndex>]
+        def local_secondary_indices
+          @local_secondary_indices ||= {}
+        end
+
+        ##
+        # Get a defined local secondary index by name.
+        #
+        # @param name [#to_s] The name of the LSI to get.
+        #
+        # @raise [IndexError] The index is not registered on the model.
+        #
+        # @return [LocalSecondaryIndex]
+        def local_secondary_index(name)
+          index = local_secondary_indices[name.to_s]
+          if index.nil?
+            raise  Mara::Model::IndexError, "Can't find a LSI with the name `#{name}`"
+          end
+
+          index
+        end
+
+        ##
+        # Add a global secondary index definition.
+        #
+        # @note This is only required for querying.
+        #
+        # @param name [#to_s] The name of the index.
+        #
+        # @param partition_key [#to_s] The name of the GSI partition key.
+        #
+        # @param sort_key [String, nil] The name of the GSI sort key.
+        #
+        # @return [void]
+        def add_gsi(name, partition_key, sort_key = nil)
+          global_secondary_indices[name.to_s] = GlobalSecondaryIndex.new(name.to_s, partition_key.to_s, sort_key)
+        end
+
+        ##
+        # @private
+        #
+        # All registered global secondary indices
+        #
+        # @return [Hash<String, GlobalSecondaryIndex>]
+        def global_secondary_indices
+          @global_secondary_indices ||= {}
+        end
+
+        ##
+        # Get a defined global secondary index by name.
+        #
+        # @param name [#to_s] The name of the GSI to get.
+        #
+        # @raise [IndexError] The index is not registered on the model.
+        #
+        # @return [GlobalSecondaryIndex]
+        def global_secondary_index(name)
+          index = global_secondary_indices[name.to_s]
+          if index.nil?
+            raise  Mara::Model::IndexError, "Can't find a GSI with the name `#{name}`"
+          end
+
+          index
+        end
+      end
+    end
+  end
+end

data/lib/mara/model/persistence.rb

@@ -0,0 +1,120 @@
+require_relative '../attribute_formatter'
+require_relative '../batch'
+require_relative '../instrument'
+
+module Mara
+  module Model
+    ##
+    # Methods that save/update/delete a model.
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
+    module Persistence
+      ##
+      # @private
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      ##
+      # Helper method added at the class level.
+      #
+      # @author Maddie Schipper
+      # @since 1.0.0
+      module ClassMethods
+      end
+
+      ##
+      # @private
+      #
+      # Converts the attributes into a DynamoDB compatable hash.
+      #
+      # @return [Hash]
+      def to_dynamo
+        {}.tap do |formatted|
+          attributes.each do |key, value|
+            formatted[key] =  Mara::AttributeFormatter.format(value)
+          end
+        end
+      end
+
+      ##
+      # @private
+      #
+      # Get a primary key attribute for the item.
+      #
+      # @return [Hash]
+      def primary_key
+        {}.tap do |base|
+          base[self.class.partition_key] =  Mara::AttributeFormatter.format(partition_key)
+
+          unless self.class.sort_key.blank?
+            base[self.class.sort_key] =  Mara::AttributeFormatter.format(sort_key)
+          end
+        end
+      end
+
+      ##
+      # @private
+      #
+      # Create a DynamoDB representation of the model.
+      #
+      # @return [Hash]
+      def to_item
+        to_dynamo.merge(primary_key)
+      end
+
+      ##
+      # Perform validation and save the model.
+      #
+      # @return [true, false]
+      def save
+         Mara.instrument('model.save', model: self) do
+          next false unless valid?
+
+           Mara::Batch.save_model(to_item)
+        end
+      end
+
+      ##
+      # Perform validation and save the model.
+      #
+      # @see #save
+      #
+      # @note Same as {#save} but will raise an error on validation faiure and
+      #   save failure
+      #
+      # @return [void]
+      def save!
+         Mara.instrument('model.save', model: self) do
+          validate!
+           Mara::Batch.save_model!(to_item)
+        end
+      end
+
+      ##
+      # Perform a destroy on the model.
+      #
+      # @return [true, false]
+      def destroy
+         Mara.instrument('model.destroy', model: self) do
+           Mara::Batch.delete_model(primary_key)
+        end
+      end
+
+      ##
+      # Perform a destroy on the model.
+      #
+      # @see #destroy
+      #
+      # @note Same as {#destroy} but will raise an error on delete failure.
+      #
+      # @return [void]
+      def destroy!
+         Mara.instrument('model.destroy', model: self) do
+           Mara::Batch.delete_model!(primary_key)
+        end
+      end
+    end
+  end
+end

data/lib/mara/model/query.rb

@@ -0,0 +1,97 @@
+require_relative '../error'
+require_relative '../query'
+require_relative '../attribute_formatter'
+require_relative '../instrument'
+
+module Mara
+  module Model
+    ##
+    # Error raised when a find method fails to find the requested object.
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
+    class NotFoundError < Error; end
+
+    ##
+    # Methods to query for a model.
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
+    module Query
+      ##
+      # @private
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      ##
+      # Helper methods defined on the class.
+      #
+      # @author Maddie Schipper
+      # @since 1.0.0
+      module ClassMethods
+        ##
+        # Find a single object with the matching partition_key and sort key.
+        #
+        # @param partition_key [#to_s] The value for the partition key.
+        #
+        # @param sort_key [#to_s, nil] The value for the sort key.
+        #
+        # @raise [NotFoundError] If the object doesn't exist in the table for
+        #   the requested primary key.
+        #
+        # @raise [ArgumentError] If the +partition_key+ is blank, or the
+        #   +sort_key+ is blank and the class defines a sort_key name.
+        #
+        # @return [ Mara::Model::Base]
+        def find(partition_key, sort_key = nil)
+           Mara.instrument('model.find', class_name: name, partition_key: partition_key, sort_key: sort_key) do
+            _find(partition_key, sort_key)
+          end
+        end
+
+        ##
+        # @private
+        #
+        # @see #find
+        def _find(partition_key, sort_key = nil)
+          if partition_key.blank?
+            raise ArgumentError, 'Must specify a valid partition key value'
+          end
+
+          if sort_key.nil? && !self.sort_key.blank?
+            raise ArgumentError, "#{self.class.name} specifies a sort key, but no sort key value was given."
+          end
+
+          key_params = {}
+          key_params[self.partition_key] =  Mara::AttributeFormatter.format(partition_key)
+          if self.sort_key.present?
+            key_params[self.sort_key] =  Mara::AttributeFormatter.format(sort_key)
+          end
+
+          response =  Mara::Query.get_item(key: key_params)
+
+          if response.nil? || response.items.empty?
+            raise NotFoundError, "Can't find item with pk=#{partition_key} sk=#{sort_key}"
+          end
+
+          item = response.items[0]
+
+          construct(item)
+        end
+      end
+
+      ##
+      # Checks if a the model exists in the table?
+      #
+      # @return [true, false]
+      def exist?
+        pk = partition_key
+        sk = conditional_sort_key
+        self.class.find(pk, sk).present?
+      rescue  Mara::Model::NotFoundError
+        false
+      end
+    end
+  end
+end

data/lib/mara/null_value.rb

@@ -0,0 +1,13 @@
+module Mara
+  ##
+  # @private
+  #
+  # The null value placeholder
+  class NullValue; end
+
+  ##
+  # @private
+  #
+  # Default NULL value
+  NULL = NullValue.new.freeze
+end

data/lib/mara/persistence.rb

@@ -0,0 +1,204 @@
+require_relative 'error'
+require_relative 'client'
+require_relative 'configure'
+require_relative 'instrument'
+require_relative 'dynamo_helpers'
+
+module Mara
+  ##
+  # @private
+  #
+  # Perform calls to DynamoDB for saving/updating/deleting
+  #
+  # @author Maddie Schipper
+  # @since 1.0.0
+  class Persistence
+    include DynamoHelpers
+
+    ##
+    # @private
+    #
+    # A wrapper for a create request.
+    #
+    # @!attribute [rw] record
+    #   The record hash to be created.
+    #
+    #   @return [Hash]
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
+    CreateRequest = Struct.new(:record) do
+      ##
+      # Converts the CreateRequest to JSON
+      #
+      # @return [Hash]
+      def as_json
+        {
+          put_request: {
+            item: record
+          }
+        }
+      end
+    end
+
+    ##
+    # @private
+    #
+    # A wrapper for a destroy request.
+    #
+    # @!attribute [rw] record
+    #   The record hash to be destroyed.
+    #
+    #   @return [Hash]
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
+    DestroyRequest = Struct.new(:record) do
+      ##
+      # Converts the DestroyRequest to JSON
+      #
+      # @return [Hash]
+      def as_json
+        {
+          delete_request: {
+            key: record
+          }
+        }
+      end
+    end
+
+    ##
+    # @private The response for a save operation.
+    #
+    # @!attribute [r] consumed_capacity
+    #   The total consumed capacity for the request.
+    #
+    #   @return [Float]
+    #
+    # @!attribute [r] operation_count
+    #   The total number of API calls required to perform the operation.
+    #
+    #   @return [Integer]
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
+    Response = Struct.new(:consumed_capacity, :operation_count)
+
+    ##
+    # @private
+    #
+    # Error thrown by Persistence calls.
+    #
+    # @author Maddie Schipper
+    # @since 1.0.0
+    class Error <  Mara::Error; end
+
+    class << self
+      ##
+      # Perform a save on a item.
+      #
+      # @param item [Hash] The item to be saved.
+      #
+      # @return [true, false]
+      def save_model(item)
+        create = CreateRequest.new(item)
+        response = perform_requests(
+           Mara::Client.shared,
+           Mara.config.dynamodb.table_name,
+          [create]
+        )
+        !response.nil?
+      end
+
+      ##
+      # Perform a save on the a item.
+      #
+      # @see .save_model
+      #
+      # @param item [Hash] The item to be saved.
+      #
+      # @raise Error If the save operation fails.
+      #
+      # @return [void]
+      def save_model!(item)
+        return if save_model(item)
+
+        raise Error, 'Failed to save!'
+      end
+
+      ##
+      # Delete an item.
+      #
+      # @param item [Hash] The item to be deleted.
+      #
+      # @return [true, false]
+      def delete_model(item)
+        delete = DestroyRequest.new(item)
+        response = perform_requests(
+           Mara::Client.shared,
+           Mara.config.dynamodb.table_name,
+          [delete]
+        )
+        !response.nil?
+      end
+
+      ##
+      # Delete an item.
+      #
+      # @see .delete_model
+      #
+      # @param item [Hash] The item to be deleted.
+      #
+      # @raise Error If the delete operation fails.
+      #
+      # @return [void]
+      def delete_model!(item)
+        return if delete_model(item)
+
+        raise Error, 'Failed to delete!'
+      end
+
+      ##
+      # Perform a batch of save requests.
+      def perform_requests(client, table_name, requests, group_size = 10)
+        results =  Mara.instrument('save_batch_records', requests: requests, table_name: table_name) do
+          requests.each_slice(group_size).map do |sub_requests|
+            _perform_requests(client, table_name, sub_requests)
+          end
+        end
+        Response.new(
+          results.map(&:consumed_capacity).sum,
+          results.map(&:operation_count).sum
+        )
+      end
+
+      private
+
+      def _base_batch_write_item_params(table_name)
+        params = {
+          return_consumed_capacity: 'TOTAL',
+          return_item_collection_metrics: 'SIZE',
+          request_items: {}
+        }
+        if block_given?
+          params[:request_items][table_name] = yield
+        end
+        params
+      end
+
+      def _perform_requests(client, table_name, requests)
+        params = _base_batch_write_item_params(table_name) { requests.map(&:as_json) }
+        response =  Mara.instrument('save_batch_record_operation', requests: requests, table_name: table_name) do
+          client.batch_write_item(params)
+        end
+
+        cc = calculate_consumed_capacity(response.consumed_capacity, table_name)
+
+        Response.new(
+          cc,
+          1
+        )
+      end
+    end
+  end
+end