remote-resource 0.1.0

data/lib/remote_resource/attribute_http_client.rb

@@ -0,0 +1,41 @@
+require 'remote_resource/notifications'
+
+module RemoteResource
+  class AttributeHttpClient
+    include RemoteResource::Notifications
+
+    def initialize(attribute, client = nil)
+      @attribute = attribute
+      @client = client || @attribute.client
+      @resource_name = @attribute.resource_name
+    end
+
+    def get(headers = {})
+      instrument_attribute('http_get', @attribute) do
+        if headers && headers.size > 0
+          with_headers_for_method(:get, headers) do |client|
+            @attribute.resource(client)
+          end
+        else
+          @attribute.resource(@client)
+        end
+      end
+      @client.last_response
+    end
+
+    private
+
+    # Internal: yield a client with headers bound on the supplied method.
+    def with_headers_for_method(method, headers)
+      old_method = "orig_#{method}".to_sym
+      client_class = @client.singleton_class
+      client_class.send(:alias_method, old_method, method)
+      client_class.send(:define_method, method) do |url, _|
+        send(old_method, url, headers: headers)
+      end
+      yield @client
+      client_class.send(:alias_method, method, old_method)
+      client_class.send(:remove_method, old_method)
+    end
+  end
+end

data/lib/remote_resource/attribute_key.rb

@@ -0,0 +1,26 @@
+module RemoteResource
+  class AttributeKey
+    attr_reader :prefix, :named_resource, :method
+
+    def initialize(prefix, named_resource, scope, method)
+      @prefix = prefix
+      @named_resource = named_resource
+      @scope = scope || {}
+      @method = method
+    end
+
+    def scope_string
+      @scope.map { |k, v| "#{k}=#{v}" }.join('&')
+    end
+
+    def for_resource
+      [@prefix, scope_string, @named_resource].compact.join('/')
+    end
+    alias_method :for_storage, :for_resource
+
+    def for_attribute
+      [@prefix, scope_string, @named_resource, @method].compact.join('/')
+    end
+    alias_method :to_s, :for_attribute
+  end
+end

data/lib/remote_resource/attribute_method_attacher.rb

@@ -0,0 +1,117 @@
+module RemoteResource
+  # non-anonymous namespace for our generated methods. Mixed into the target
+  # class so that introspection shows where the methods came from.
+  class AttributeMethods < Module; end
+
+  # Public: Creates an instance of the AttributeMethodAttacher, which is
+  # responsible for setting up and attaching methods onto a target class which
+  # are used to lookup cached attributes.
+  class AttributeMethodAttacher
+    attr_accessor :options
+    # Public: Creates an instance of the AttributeMethodAttacher, which is
+    # responsible for setting up and attaching methods onto a target class which
+    # are used to lookup cached attributes.
+    #
+    # base_class - the class which will have methods attached to.
+    # options - options hash with the following keys (default: {}). Generally,
+    #           prefix should be used when overriding the names of all the
+    #           methods is desired and attributes_map should be used when
+    #           overriding only a few method names is desired.
+    #     :prefix - prefix for the names of the newly created methods.
+    #     :attributes_map - a hash for overriding method names to create. The
+    #                       keys in this hash represent an attribute defined on
+    #                       the base_class. The values are the overriding name
+    #                       of the method to be defined on the target_class.
+    #
+    # Returns a new instance.
+    def initialize(base_class, options = {})
+      @base_class = base_class
+      @options = ensure_options(options)
+    end
+
+    # Public: Set the base_classes' attribute methods on the given target class.
+    # Sets a MethodResolver instance on the target_class as well. Logs warnings
+    # if any methods on the target class are overwritten.
+    #
+    # target_class  - The class upon which the base_classes' attribute methods
+    #                 should be set.
+    # path_to_attrs - A string representing a line of ruby code that will be
+    #                 evaluated. This line is the relative path from a
+    #                 target_class instance to the object that holds the
+    #                 attributes and where the `get_attribute` is defined. If
+    #                 path_to_attrs is (default: self), that implies that this
+    #                 is defining methods on the Base class, because that object
+    #                 contains the `get_attribute` method.
+    #
+    # Returns the target_class
+    def attach_to(target_class, path_to_attrs = 'self')
+      overwrite_method_warnings(target_class) unless path_to_attrs == 'self'
+      target_class.send(:include, make_attribute_methods_module(path_to_attrs))
+    end
+
+    private
+
+    # Internal: Returns a module with the base_classes' attributes defined as
+    # getter and setter methods.
+    def make_attribute_methods_module(path_to_attrs)
+      attribute_methods_module = AttributeMethods.new
+
+      @base_class.attributes.keys.each do |attributes_method|
+        method_name = @options[:attributes_map][attributes_method]
+        method_name = "#{@options[:prefix]}_#{method_name}" if @options[:prefix]
+        attribute_methods_module.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{method_name}
+            #{path_to_attrs}.get_attribute(:#{attributes_method})
+          end
+
+          def #{method_name}=(other)
+            fail ApiReadOnlyMethod.new('#{method_name}')
+          end
+        RUBY
+      end
+      attribute_methods_module
+    end
+
+    # Internal: Populate the attributes map. If no attributes_map arg is given,
+    # then attributes_map is a 1 to 1 map (the default_attributes_map below).
+    def ensure_options(options)
+      options[:attributes_map] = default_attributes_map
+                                 .merge(options[:attributes_map] || {})
+      options
+    end
+
+    # Internal: Create a basic 1 to 1 (key to value) Hash map of the attribute
+    # names. This is intended to be overridden by the attributes_map argument.
+    def default_attributes_map
+      {}.tap do |attr_map|
+        @base_class.attributes.keys.each do |method|
+          attr_map[method.to_sym] = method.to_sym
+        end
+      end
+    end
+
+    # Internal: Log warning methods when this attacher will overwrite methods on
+    # the target class.
+    def overwrite_method_warnings(target_class)
+      @options[:attributes_map].values.each do |method|
+        method = "#{@options[:prefix]}_#{method}" if @options[:prefix]
+        if present_and_future_public_methods(target_class).include? method
+          log_msg =  "#{@base_class.name} is overwriting the "
+          log_msg += "#{method} method on #{target_class.name}"
+          RemoteResource.logger.warn log_msg
+        end
+      end
+    end
+
+    # Internal: ActiveRecord objects do not define a model's column methods
+    # until the instance is created. In this context, we have the class, so we
+    # lookup the 'future methods' on the `column_names` class method.
+    def present_and_future_public_methods(target_class)
+      conflicts = target_class.public_instance_methods
+      if target_class.respond_to? :column_names
+        conflicts += target_class.column_names.map(&:to_sym)
+      end
+      conflicts
+    end
+  end
+end

data/lib/remote_resource/attribute_specification.rb

@@ -0,0 +1,51 @@
+require 'remote_resource/attribute_key'
+
+module RemoteResource
+  # A value object representing an attribute defined in
+  # RemoteResource::Base. An AttributeSpecification contains the
+  # attributes' method name, its resource, and its API client that is used for
+  # lookup. It also calculates its `key` which is used to lookup its value in
+  # storage.
+  #
+  # scope is evaluated outside of this object and should remain unchanged
+  # throughout its life cycle. scope is used in building the attribute's key and
+  # its equality. target_object on the other hand is just a reference to the
+  # object that scope was evaluated on. It may change throughout the attribute's
+  # life cycle and is not used in determining equality.
+  class AttributeSpecification
+    attr_reader :name, :base_class
+    delegate :client, :with_error_handling, to: :@base_class
+
+    def initialize(name, base_class)
+      @name = name
+      @base_class = base_class
+    end
+    alias_method :method, :name
+
+    def to_hash
+      {
+        name: @name,
+        resource: resource_name,
+        base_class: @base_class.class.symbol_name,
+        location: location
+      }
+    end
+
+    def resource_name
+      @base_class.class.attributes[@name]
+    end
+
+    def resource(resource_client = nil)
+      @base_class.send(:resource, resource_name, resource_client)
+    end
+
+    def location
+      "#{@base_class.class.name}##{@name}"
+    end
+
+    def key
+      @key ||= AttributeKey.new(@base_class.class.underscore, resource_name,
+                                @base_class.scope, @name)
+    end
+  end
+end

data/lib/remote_resource/attribute_storage_value.rb

@@ -0,0 +1,63 @@
+require 'active_support/core_ext/module/delegation'
+
+require 'remote_resource/attribute_http_client'
+require 'remote_resource/storage/storage_entry'
+require 'remote_resource/storage/null_storage_entry'
+require 'remote_resource/notifications'
+
+module RemoteResource
+  class AttributeStorageValue
+    include RemoteResource::Notifications
+
+    delegate :data?, :exists?, :expired?, :headers_for_validation,
+             :validateable?, to: :storage_entry
+
+    def initialize(attribute)
+      @attribute = attribute
+      @storage_entry = nil
+    end
+
+    def value
+      storage_entry.data[@attribute.name]
+    end
+
+    def storages
+      RemoteResource.storages
+    end
+
+    def fetch
+      @attribute.with_error_handling action: :fetch do
+        attr_client = AttributeHttpClient.new(@attribute)
+        write(StorageEntry.from_response(attr_client.get))
+      end
+    end
+
+    def validate
+      @attribute.with_error_handling action: :validate do
+        attr_client = AttributeHttpClient.new(@attribute)
+        response = attr_client.get(headers_for_validation)
+        write(StorageEntry.from_response(response))
+        response.headers['status'] == '304 Not Modified'
+      end
+    end
+
+    def write(storage_entry)
+      @storage_entry = nil
+      storages.each do |storage|
+        storage.write_key(@attribute.key.for_storage, storage_entry)
+      end
+    end
+
+    def storage_entry
+      return @storage_entry if @storage_entry
+      instrument_attribute('storage_lookup', @attribute) do
+        storages.each do |storage|
+          if (storage_entry = storage.read_key(@attribute.key.for_storage))
+            return (@storage_entry = storage_entry)
+          end
+        end
+        return (@storage_entry = NullStorageEntry.new)
+      end
+    end
+  end
+end

data/lib/remote_resource/base/attributes.rb

@@ -0,0 +1,44 @@
+module RemoteResource
+  # Defines attribute related methods for Base class instances.
+  module Attributes
+    include RemoteResource::Notifications
+
+    # Public: Creates and returns an array of cached attributes for the provided
+    # base_instance. The base_instance is stored in each attribute and is used
+    # for lookup.
+    #
+    # base_instance - an instance of base_class. The instance means that the
+    # scope has already been applied to it.
+    #
+    # Returns an array a AttributeSpecifications.
+    def create_attributes(base_instance)
+      @attributes = base_instance.class.attributes.map do |method, _value|
+        AttributeSpecification.new(method, base_instance)
+      end
+    end
+
+    # Public: Returns the value of the provided attribute. It uses the
+    # application configured lookup_method to do so.
+    #
+    # name - a Symbol representing an attribute name
+    #
+    # Returns the value of the attribute as a String.
+    def get_attribute(name)
+      attribute = find_attribute(name)
+
+      attr_lookup = RemoteResource.lookup_method
+      lookup_name = attr_lookup.class.name
+      instrument_attribute('find', attribute, lookup_method: lookup_name) do
+        attr_lookup.find(attribute).value
+      end
+    end
+
+    private
+
+    # Internal: Returns the already created AttributeSpecification with the
+    # provided name.
+    def find_attribute(name)
+      @attributes.detect { |attr| attr.name == name }
+    end
+  end
+end

data/lib/remote_resource/base/base_class_methods.rb

@@ -0,0 +1,23 @@
+module RemoteResource
+  # Methods that help with loading and naming the Base class.
+  module BaseClassMethods
+    def find_descendant(which_class)
+      ensure_loaded(which_class)
+      descendants.detect do |descendant|
+        descendant.symbol_name == which_class.to_sym
+      end
+    end
+
+    def ensure_loaded(which_class)
+      which_class.to_s.camelize.safe_constantize
+    end
+
+    def underscore
+      name.underscore
+    end
+
+    def symbol_name
+      underscore.to_sym
+    end
+  end
+end

data/lib/remote_resource/base/dsl.rb

@@ -0,0 +1,27 @@
+module RemoteResource
+  # Our humble DSL
+  module Dsl
+    attr_reader :client_proc, :resources
+
+    def client(&block)
+      @client_proc = block if block
+    end
+
+    def resource(name = :default, &block)
+      if block
+        @resources ||= {}
+        @resources[name] = block
+      else
+        fail ArgumentError, 'must supply a block'
+      end
+    end
+
+    def attribute(method, named_resource = :default)
+      attributes[method] = named_resource
+    end
+
+    def attributes
+      @attributes ||= {}
+    end
+  end
+end

data/lib/remote_resource/base/rescue.rb

@@ -0,0 +1,43 @@
+require 'active_support/concern'
+require 'active_support/rescuable'
+
+module RemoteResource
+  # Methods that help with loading and naming the Base class.
+  module Rescue
+    extend ActiveSupport::Concern
+    include ActiveSupport::Rescuable
+
+    # Public: Use the with_error_handling method to use the error handling
+    # behavior defined in the rescue_from calls on the class. Take a block,
+    # whose body will error rescued.
+    #
+    # Note that it is typically 'wrong' in Ruby to rescue Exception. In this
+    # case it is OK because we re raise the error if it is not handled. Inspired
+    # by ActiveController.
+    # rubocop:disable Lint/RescueException
+    #
+    # Returns the last executed statement value.
+    def with_error_handling(context = {})
+      yield
+    rescue Exception => exception
+      rescue_with_handler(exception, context) || raise(exception)
+    end
+    # rubocop:enable Lint/RescueException
+
+    private
+    # Internal: Override the default ActiveSupport::Rescuable behavior to allow
+    # for additional context argument to be supplied as well. These error
+    # handlers are reused in different situations, and the context argument
+    # allows one to change the behavior depending on which situation.
+    def rescue_with_handler(exception, context = {})
+      if (handler = handler_for_rescue(exception))
+        case handler.arity
+        when 2 then handler.call(exception, context)
+        when 1 then handler.call(exception)
+        when 0 then handler.call
+        end
+        true # don't rely on the return value of the handler
+      end
+    end
+  end
+end