remote-resource 0.1.0

data/lib/remote_resource/base.rb

@@ -0,0 +1,35 @@
+require 'active_support/descendants_tracker'
+
+module RemoteResource
+  # the base class for defining an api.
+  class Base
+    extend ActiveSupport::DescendantsTracker
+
+    extend RemoteResource::BaseClassMethods
+    extend RemoteResource::Dsl
+
+    include RemoteResource::Attributes
+    include RemoteResource::Rescue
+
+    attr_reader :scope
+
+    def initialize(**args)
+      @scope = args
+      create_attributes(self)
+      AttributeMethodAttacher.new(self.class).attach_to(self.class)
+    end
+
+    def client
+      self.class.client_proc.call(@scope)
+    end
+
+    def resource(name = :default, resource_client = nil)
+      if (attr_resource = self.class.resources[name])
+        attr_resource.call(resource_client || client, @scope)
+      else
+        msg = "there is no resource named `#{name}` on #{self.class.name}."
+        fail ArgumentError, msg
+      end
+    end
+  end
+end

data/lib/remote_resource/bridge.rb

@@ -0,0 +1,174 @@
+require 'remote_resource/attribute_method_attacher'
+
+module RemoteResource
+  # Extending a class with the HasRemote::Bridge module will bring in
+  # the has_remote and embed_remote method, and therefore all of the
+  # functionality of the has_remote gem. In Rails, ActiveRecord is
+  # automatically extended with Bridge, and you would use the has_remote call
+  # like a familiar 'has_one' association method. Outside of Rails, or if used
+  # in non ActiveRecord domain objects, extending your domain objects with
+  # Bridge is how to setup has_remote on those classes.
+  module Bridge
+    # Public: Setup the provided remote resource on this class. This creates a
+    # method on the class that returns the remote resource object that is
+    # associated with that record. The method shares the name with the first
+    # argument unless the `as` options is supplied to override this.
+    #
+    # which_class - A symbol representing a descendant class of
+    #               HasRemote::Resource. The symbol is the underscored
+    #               version of the class name.
+    #                 Ex: (class) GithubUser => (symbol) :github_user
+    # options     - A hash of options. (default: {}) Always use symbols for
+    #               keys. These options are also passed to the
+    #               AssociationBuilder and the AttributeMethodAttacher.
+    #               :as             - a symbol that defines the method name that
+    #                                 returns the association. By default, this
+    #                                 is the same name as the first argument
+    #                                 specifying the remote resource class.
+    #               :scope          - the scope option represents the context in
+    #                                 which this api resource is unique. It has
+    #                                 a similar meaning to ActiveRecord's
+    #                                 meaning of scope, as opposed the API
+    #                                 access meaning. The scope value can be a
+    #                                 Symbol, Array, or Hash. It is used to
+    #                                 build the scope argument, which is sent
+    #                                 into the client and resource blocks on the
+    #                                 Base attributes class. This argument to
+    #                                 these blocks is always a hash, whose
+    #                                 values were methods responses evaluated on
+    #                                 the target_class.
+    #               :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 resource. The
+    #                                 values are the overriding name of the
+    #                                 method.
+    #
+    # Examples
+    #
+    #   class Repo < ActiveRecord::Base
+    #     has_remote :github_repo
+    #
+    #     ...
+    #   end
+    #
+    #   The above `has_remote` call assumes that the following class
+    #   exists:
+    #
+    #   class GithubRepo < HasRemote::Resource
+    #     ...
+    #     attribute :description
+    #     ...
+    #   end
+    #
+    #   There is now an instance method on Repo that will return that instances
+    #   associated GithubRepo instance.
+    #
+    #   repo = Repo.find(1)
+    #   repo.github_repo #=> <class GithubRepo instance >
+    #   repo.github_repo.description #=> "A ruby gem for ruby gems."
+    #
+    #   as option:
+    #
+    #   has_remote :github_repo, as: :on_github
+    #
+    #   Specifying the 'as' option will override the created association method
+    #   name. The method will now be 'on_github' rather than 'github_user'.
+    #
+    #   repo = Repo.find(1)
+    #   repo.on_github #=> <class GithubRepo instance >
+    #   repo.on_github.description #=> "A ruby gem for ruby gems."
+    #
+    #   scope option:
+    #
+    #   has_remote :github_user, scope: { id: :gh_user_id }
+    #
+    #   The scope hash in this example will evaluate the 'gh_user_id' method on
+    #   this class and send it in as the :id on the scope Hash. This style scope
+    #   argument is especially useful when the same remote resource class is
+    #   mixed into multiple models, and therefore the multiple models are not
+    #   forced to use the same method names for the scope values. The scope hash
+    #   that is passed into the client and resource blocks will look like this:
+    #   { id: 2345987 }
+    #
+    #   has_remote :github_user, scope: [:id, :access_token]
+    #
+    #   This scope array will evaluate both the :id and :access_token methods on
+    #   this class. The scope hash that is passed into the client and resource
+    #   blocks will look like this: { id: 274346, access_token: '2ac4g3t7jf8'}
+    #
+    #   has_remote :github_user, scope: :github_login
+    #
+    #   This will evaluate the :github_login method on this class. The scope
+    #   hash that is passed into the client and resource blocks will look like
+    #   this: { github_login: 'mkcode' }
+    #
+    #   prefix and attribute_map options:
+    #
+    #   has_remote :github_user, prefix: :gh_user
+    #
+    #   All of the attribute methods defined on the association will be prefixed
+    #   with 'gh_user_'. If the Base attributes class defined attributes :login
+    #   and :email, this class would have the methods: :gh_user_login and
+    #   :gh_user_email.
+    #
+    #   has_remote :github_user, attributes_map: { email: :gh_email }
+    #
+    #   The attributes_map argument here will override the name of the :email
+    #   attribute. Instead of the method being named :email, it will now be
+    #   named :gh_email.
+    #
+    # Returns an instance of AssociationBuilder.
+    def has_remote(which_klass, options = {})
+      klass = RemoteResource::Base.find_descendant(which_klass)
+      fail BaseClassNotFound.new(which_klass) unless klass
+
+      builder = AssociationBuilder.new(klass, options)
+      builder.associated_with(self)
+    end
+
+    # Public: embed_remote takes takes the exact same options as 'has_remote'
+    # and completes the same behavior as well with one addition. It defines the
+    # attribute getter methods directly on the target class, in addition to on
+    # the association. This is similar in theory to the object oriented
+    # programming 'is_a' vs 'has_a', inheritance vs composition debate. By
+    # defining the attribute methods directly on the domain object, that domain
+    # object 'is' a remote resource. Note that this will only define the
+    # attribute getter methods on the target class. Additional methods defined
+    # on the Resource class will not be copied, but may still be accessed
+    # through the association method.
+    #
+    # Examples
+    #
+    #   class Repo < ActiveRecord::Base
+    #     embed_remote :github_repo
+    #
+    #     ...
+    #   end
+    #
+    #   class GithubRepo < HasRemote::Resource
+    #     ...
+    #     attribute :description
+    #     ...
+    #   end
+    #
+    #   repo = Repo.find(1)
+    #   repo.github_repo #=> <class GithubRepo instance >
+    #   repo.github_repo.description #=> "A ruby gem for ruby gems."
+    #
+    #   So far, this has been exactly the same as 'has_remote'. The addition:
+    #
+    #   repo.description #=> "A ruby gem for ruby gems."
+    #
+    #   Repo 'is' a GithubRepo.
+    #
+    # Returns nil
+    def embed_remote(which_klass, options = {})
+      assoc_builder = has_remote(which_klass, options)
+
+      attacher = AttributeMethodAttacher.new(assoc_builder.base_class, options)
+      attacher.attach_to(self, assoc_builder.options[:as].to_s)
+    end
+  end
+end

data/lib/remote_resource/configuration/logger.rb

@@ -0,0 +1,24 @@
+require 'logger'
+
+module RemoteResource
+  module Configuration
+    # Our humble logger
+    module Logger
+      def self.extended(klass)
+        klass.instance_variable_set(:@logger, nil)
+      end
+
+      def logger=(logger)
+        @logger = logger
+      end
+
+      def logger
+        @logger ||= default_logger
+      end
+
+      def default_logger
+        ::Logger.new(STDOUT)
+      end
+    end
+  end
+end

data/lib/remote_resource/configuration/lookup_method.rb

@@ -0,0 +1,24 @@
+require 'remote_resource/lookup/default'
+
+module RemoteResource
+  module Configuration
+    # Our humble storage
+    module LookupMethod
+      def self.extended(klass)
+        klass.instance_variable_set(:@lookup_method, nil)
+      end
+
+      def lookup_method=(lookup_method)
+        @lookup_method = lookup_method
+      end
+
+      def lookup_method
+        @lookup_method ||= default_lookup_method
+      end
+
+      def default_lookup_method
+        Lookup::Default.new
+      end
+    end
+  end
+end

data/lib/remote_resource/configuration/storage.rb

@@ -0,0 +1,24 @@
+require 'remote_resource/storage/memory'
+
+module RemoteResource
+  module Configuration
+    # Our humble storage
+    module Storage
+      def self.extended(klass)
+        klass.instance_variable_set(:@storages, nil)
+      end
+
+      def storages=(storages)
+        @storages = storages
+      end
+
+      def storages
+        @storages ||= default_storages
+      end
+
+      def default_storages
+        [RemoteResource::Storage::Memory.new]
+      end
+    end
+  end
+end

data/lib/remote_resource/errors.rb

@@ -0,0 +1,40 @@
+require 'active_support/core_ext/string/strip'
+
+module RemoteResource
+  class Error < StandardError; end
+
+  class ApiReadOnlyMethod < Error
+    def initialize(method_name)
+      @method_name = method_name
+      super(message)
+    end
+
+    def message
+      <<-MESSAGE.strip_heredoc
+
+        The `RemoteResource` gem creates read only methods which represent
+        API values. `#{@method_name}` was defined using this gem and this error
+        is raised to indicate that these attributes are read only, although you
+        may override this behavior by defining a `#{@method_name}=` setter
+        method on this class.
+      MESSAGE
+    end
+  end
+
+  class BaseClassNotFound < Error
+    def initialize(which_klass)
+      @which_klass = which_klass
+      super(message)
+    end
+
+    def message
+      <<-MESSAGE.strip_heredoc
+
+        A RemoteResource::Base class descendant named `#{@which_klass}`
+        could not be found. Descendant class names are generally suffixed with
+        'Attributes' and looked up without the attributes symbol. Example: A
+        base class named 'GithubUserAttributes' is looked up with :github_user.
+      MESSAGE
+    end
+  end
+end

data/lib/remote_resource/log_subscriber.rb

@@ -0,0 +1,39 @@
+require 'active_support/log_subscriber'
+
+module RemoteResource
+  class LogSubscriber < ActiveSupport::LogSubscriber
+    def logger
+      RemoteResource.logger
+    end
+
+    def find(event)
+      log_action('Find', event)
+    end
+
+    def storage_lookup(event)
+      log_action('Storage lookup', event) { |payload| payload[:attribute] }
+    end
+
+    def http_get(event)
+      log_action('HTTP GET', event) { |payload| payload[:attribute] }
+    end
+
+    # the optional block acts as a filter for the log description. The block is
+    # passed the payload and its return value is used as the log description.
+    # The whole payload is used as the description if the block is omitted.
+    def log_action(action, event, &block)
+      payload = event.payload
+      description = block ? block.call(payload) : payload
+
+      if (attribute = payload[:attribute])
+        subject = attribute[:location]
+        action = "#{subject} #{action} (#{event.duration.round(2)}ms)"
+      end
+
+      action = color(action, GREEN, true)
+      debug("#{action} #{description}")
+    end
+  end
+end
+
+RemoteResource::LogSubscriber.attach_to :remote_resource

data/lib/remote_resource/lookup/default.rb

@@ -0,0 +1,39 @@
+require 'active_support/core_ext/hash/reverse_merge'
+
+require 'remote_resource/attribute_storage_value'
+
+module RemoteResource
+  module Lookup
+    # Default lookup class. Top most level class used for looking up attributes
+    # across storages and remotely over http.
+    #
+    # Arguments:
+    #   options:
+    #     validate: 'cache_control', 'true', 'false' - Should values looked up
+    #     in storage be validated with the server. The default value
+    #     'cache_control', sets this according to the server returned
+    #     Cache-Control header. Values true and false override this.
+    class Default
+      def initialize(options = {})
+        @options = options.reverse_merge(validate: :cache_control)
+      end
+
+      def find(attribute)
+        store_value = AttributeStorageValue.new(attribute)
+        if store_value.data?
+          store_value.validate if should_validate?(store_value)
+        else
+          store_value.fetch
+        end
+        store_value
+      end
+
+      private
+
+      def should_validate?(store_value)
+        return @options[:validate] unless @options[:validate] == :cache_control
+        store_value.validateable? && store_value.expired?
+      end
+    end
+  end
+end

data/lib/remote_resource/notifications.rb

@@ -0,0 +1,17 @@
+require 'active_support/notifications'
+
+module RemoteResource
+  module Notifications
+    def instrument(*args, &block)
+      args[0] = args[0] + '.remote_resource' unless args[0].include?('.')
+      ActiveSupport::Notifications.instrument(*args, &block)
+    end
+
+    def instrument_attribute(*args, &block)
+      fail ArgumentError unless args[1].is_a? AttributeSpecification
+      args.push({}) unless args.last.is_a? Hash
+      args.last.merge!(attribute: args.delete_at(1).to_hash)
+      instrument(*args, &block)
+    end
+  end
+end

data/lib/remote_resource/railtie.rb

@@ -0,0 +1,21 @@
+module RemoteResource
+  class Railtie < Rails::Railtie
+    ns = 'remote_resource'
+
+    console do
+      RemoteResource.logger = Rails.logger
+    end
+
+    initializer "#{ns}.logger", after: 'active_record.logger' do
+      RemoteResource.logger = Rails.logger
+    end
+
+    initializer "#{ns}.extend_active_record", after: 'active_record.set_configs' do
+      ActiveRecord::Base.send(:extend, RemoteResource::Bridge)
+    end
+
+    initializer "#{ns}.add_to_eager_load_paths" do |app|
+      app.config.paths.add 'app/remote_resources', eager_load: true
+    end
+  end
+end