remote-resource 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8507134d807aaed5cbe3c9e7872bd1de23cb0470
-  data.tar.gz: b074f3e0ea07f224bdfc1dc0b366722935f5c7ac
+  metadata.gz: 0615325b89bdbae524b7e54dc0360774ba453e55
+  data.tar.gz: f9441fa6d760b8f0f4e49e038498cdc0b249ffb8
 SHA512:
-  metadata.gz: 1ce966ffea5435248135b873dfd0d8e22beb3af92d69a088562c6523de5bdd215e199daf716d397840f74f3edc19d683bb633f8f46280eab21d93b04bbcf497c
-  data.tar.gz: bc5cd692a7271389e86c5f096a174ec0d840e1a02565d03cb5b85d296f9029f1e1dc19fca8028ef85c14cb3c24bd67c771cec1c01f19da85a098d4996cc6963a
+  metadata.gz: 5b73cc3191733078a6589fdda37bf1c0e45d2eb2fcd13e990f53c66ace41860dcf7a001fa078e4e70031503633c5adf9ae1a49bab721192964a3c55459820ec0
+  data.tar.gz: 3b8e1950c93ea03a50b95d00e0a4f75ef3faf5f2528fdfc3db55b3a87878f2169306619f011709a165bed7ada0dca83a009d7e248f0dc83a8c1312d592558bc7

data/README.md

@@ -3,35 +3,36 @@
 [![Build Status](https://travis-ci.org/mkcode/remote-resource.svg?branch=master)](https://travis-ci.org/mkcode/remote-resource)
 [![Code Climate](https://codeclimate.com/github/mkcode/remote-resource/badges/gpa.svg)](https://codeclimate.com/github/mkcode/remote-resource)
 [![Test Coverage](https://codeclimate.com/github/mkcode/remote-resource/badges/coverage.svg)](https://codeclimate.com/github/mkcode/remote-resource/coverage)
-[![Inline docs](http://inch-ci.org/github/mkcode/remote_resource.svg?branch=master)](http://inch-ci.org/github/mkcode/remote_resource)
 
-Add resiliency, speed, and familiarity to the APIs your app relies on. Features:
+__RemoteResource__ allows you to easily create `ActiveRecord` style domain
+objects that represent a foreign API. These `remote resources` can be mixed into
+or associated with other ActiveRecord models in the same way you work with all
+your other models. Using these conventions yields some major performance gains
+through caching and fast and simple development through familiarity.
 
- * A simple DSL for resource oriented APIs.
- * Work with foreign APIs in the same way you work with ActiveRecord
-   associations.
- * Transparently caches API responses for major performance gains.
- * Don't fail when APIs your app relies on are momentarily down.
- * Respect your APIs Cache-Control header. Or don't. It's up to you.
- * Configurable logging and error reporting.
- * Trivial to add support for your new API client.
+## Why RemoteResource
 
-## Getting started
+ * Familiar - The DSL used to wrap foreign APIs is simple and intuitive. Using
+   the remote resource will be familiar to anyone who has worked with
+   ActiveRecord models.
 
-__RemoteResource__ allows you to easily create `ActiveRecord` style domain
-objects (or models) that represent a foreign API. These `remote_resources` can
-be mixed in and associated with other ActiveRecord models in the same way you
-work with all your other models. Using this pattern and these conventions yields
-some major performance gains through caching and fast and simple development
-through familiarity.
+ * Reusable - Write your API interface once. Associate it with an ActiveRecord
+   object, embed it into a value object, or instantiate it for use in a service.
 
-A few steps to get started:
+ * Performant - API responses are transparently cached. Subsequent calls move at
+   the speed of redis. Etag based cache expiring, which you may override. Makes
+   detailed list pages possible.
+
+ * Resiliant - Easy to configure error handling, just like ActionContoller. Use
+   cached values to rescue momentary network failures.
+
+## Getting started
 
 Create a `remote_resource`, such as:
 
 ```ruby
-# in `app/remote_resources/github_user.rb`
-class GithubUser < HasRemote::Resource
+# in app/remote_resources/github_user.rb
+class GithubUser < RemoteResource::Base
   client { Octokit::Client.new }
   resource { |client, scope| client.user(scope[:github_login]) }
 
@@ -45,7 +46,7 @@ end
 Associate it with your ActiveRecord `User` model:
 
 ```ruby
-# in `app/models/user.rb`
+# in app/models/user.rb
 class User < ActiveRecord::Base
   has_remote :github_user, scope: :github_login
 
@@ -59,7 +60,7 @@ local models.
 ```ruby
 user = User.find(1)
 
-user.github_user.login
+user.github_user.id
 user.github_user.avatar_url
 ```
 
@@ -81,7 +82,7 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install remote_resource
+    $ gem install remote-resource
 
 ## Defining an RemoteResource
 
@@ -90,7 +91,7 @@ This folder is automatically added to your Rails eager loaded paths.
 
 ```ruby
 # In `app/remote_resources/github_user.rb
-class GithubUserAttributes < RemoteResource::Base
+class GithubUser < RemoteResource::Base
   client { Octokit::Client.new }
 
   resource { |client, scope| client.user(scope[:github_login]) }
@@ -103,9 +104,11 @@ class GithubUserAttributes < RemoteResource::Base
 end
 ```
 
-The are 4 class methods that are available to help define an (API) remote resource. They are:
+The are 4 class methods that are available to help define an (API) remote
+resource. They are:
 
- * __client__: You return an instance of the web client that the API uses in a block. That block yields the scope. (More on scope later.)
+ * __client__: You return an instance of the web client that the API uses in a
+   block. That block yields the scope. (More on scope later.)
 
  * __resource__: Supply a block to the resource method that returns a a remote
    resource. For example, the 'show user' response (GET /user/:github_login)
@@ -117,10 +120,10 @@ The are 4 class methods that are available to help define an (API) remote resour
    This will be mapped to a method later. Optionally takes a second symbol
    argument referring to a non-default resource (with an argument).
 
- * __rescue_from__: Works in the same way that ActionContoller's rescue_from
+ * __rescue_from__: Works in the same way that ActionController's rescue_from
    works. It takes one or many Error class(es), and either a block of a `:with`
-   option that refers to an instance method on this class. The block and
-   instance method both receive the error and an additional context argument.
+   option that refers to an instance method on this class. The block or instance
+   method receive the error and an additional context hash as arguments.
 
 Remote resource allows you to define any instance method you like on it, which
 may be used by being instantiated itself or from an associated model.
@@ -144,7 +147,7 @@ The following instance methods are available within a RemoteResource::Base class
 
 ```ruby
 # In `app/remote_resources/github_user.rb
-class GithubUserAttributes < RemoteResource::Base
+class GithubUser < RemoteResource::Base
   client { Octokit::Client.new }
   resource { |client, scope| client.user(scope[:github_login]) }
   attribute :name
@@ -200,7 +203,7 @@ github_user.markdown_summary
 #=> "<h1>A big hello to Chris Ewald!!!</h1>"
 ```
 
-We also may call any of our defined attributes. Ex:
+We also may call any of our defined attributes.
 
 ```ruby
 github_user.name
@@ -238,19 +241,20 @@ Two methods are available for your model classes. `has_remote` and
 `embeds_remote`. They take all the same options and do mostly the same thing;
 create a method on the calling object, which returns that records associated
 RemoteResource instance. `embeds_remote` will go one step further and define all
-of the attribute getter methods on the model class as well. This can be used to
-create 'flat' domain objects which are backed by values from a remote API. This
-is largely related to Inhertance vs Composition programming theory which you are
-welcome to look up on your own time. RemoteResource supports both styles; 'Is'
-through `embeds_remote` and 'has' through `has_remote`. If unsure, you should
-prefer to use `has_remote` over `embeds_remote` to create a clear distinction
-between your local and remote domain.
+of the attribute getter methods on the calling class as well. This can be used
+to create flat domain objects, or possibly value_objects, which are backed by
+values from a remote API. This is largely related to Inhertance vs Composition
+in programming theory which you are welcome to look up on your own time.
+RemoteResource supports both styles; 'Is' through `embeds_remote` and 'has'
+through `has_remote`. If unsure, it is best to prefer composition and use
+`has_remote` over `embeds_remote` to create a clear distinction between your
+local and remote domain.
 
 ## Extending other domain objects
 
-If you do not use ActiveRecord in your app, you may still use remote_resource by
-simply extending the Bridge module onto what class you use as your domain. The
-`has_remote` and `embed_remote` methods will then be available. For example:
+If you do not use ActiveRecord in your app, you may still use remote-resource by
+simply extending the Bridge module onto whatever class you use. The `has_remote`
+and `embed_remote` methods will then be available. For example:
 
 ```ruby
 class MyPoro
@@ -261,54 +265,69 @@ end
 
 ## Configuration
 
-In a initializer, like `config/initializers/remote_resource.rb`, you may override the following options:
+In a initializer, like `config/initializers/remote_resource.rb`, you may
+override the following options:
 
 ```ruby
-# Setup global storages. For now there is only redis and memory. Default is one
-# Memory store.
-
-require 'remote_resource/storage/redis'
+# Setup global storages. For now there are Redis and Memory stores available.
+# Default is Memory store.
+
+# Storage::Redis takes an instance of redis client and the following options:
+#
+#   expires_in - Time in seconds for to keys ttl. (Default is 1 day)
+#   serializer - Instance of the serializer to load and dump the response.
+#                (Default is MarshalSerializer.new)
+#
 RemoteResource.storages = [
-  RemoteResource::Storage::Redis.new( Redis.new(url:nil) )
+  RemoteResource::Storage::Redis.new(Redis.new(url:nil), expires_in: 7.days)
 ]
 
-# Setup a logger
+# Specify the logger RemoteResource should use:
 
 RemoteResource.logger = Logger.new(STDOUT)
 
-# Setup a lookup method. Only default for now, but the `cache_control` option
+# Setup a lookup method. Only default for now, but the `validate` option
 # may be changed to true or false. True will always revalidate. False will never
 # revalidate. :cache_control respects the Cache-Control header.
 
-require 'remote_resource/lookup/default'
 RemoteResource.lookup_method = RemoteResource::Lookup::Default.new(validate: true)
 ```
 
 ## Notifications
 
-There are 4 ActiveSupport notifications that you may subscribe to, to do in depth profiling of this gem:
+There are 3 ActiveSupport notifications that you may subscribe to, to do in
+depth profiling of this gem:
 
   * find.remote_resource
   * storage_lookup.remote_resource
-  * http_head.remote_resource
   * http_get.remote_resource
 
+```ruby
 ActiveSupport::Notifications.subscribe('http_get.remote_resource') do |name, _start, _fin, _id, _payload|
   puts "HTTP_GET #{name}"
 end
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/remote_resource. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/[USERNAME]/remote_resource. This project is intended to be a
+safe, welcoming space for collaboration, and contributors are expected to adhere
+to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-
+The gem is available as open source under the terms of the
+[MIT License](http://opensource.org/licenses/MIT).

data/lib/remote-resource.rb

@@ -0,0 +1,4 @@
+# This file exists as shortcut; so that Bundler.require will properly require
+# this gem's project files without additional configuration.
+
+require 'remote_resource'

data/lib/remote_resource/association_builder.rb

@@ -29,6 +29,7 @@ module RemoteResource
 
     def define_association_method(method_name, target_class)
       scope = @options[:scope]
+      scope = ":#{@options[:scope]}" if @options[:scope].is_a?(Symbol)
       target_class.module_eval <<-RUBY, __FILE__, __LINE__ + 1
         def #{method_name}
           scope_evaluator = RemoteResource::ScopeEvaluator.new(#{scope})

data/lib/remote_resource/storage/redis.rb

@@ -1,12 +1,18 @@
-require 'remote_resource/storage/serializers/marshal'
+require 'active_support/core_ext/hash/reverse_merge'
+
+require 'remote_resource/storage/serializers/marshal_serializer'
 require 'remote_resource/storage/storage_entry'
 
 module RemoteResource
   module Storage
     class Redis
-      def initialize(redis, serializer = nil)
+      def initialize(redis, options = {})
         @redis = redis
-        @serializer = serializer || Serializers::MarshalSerializer.new
+        @options = options.reverse_merge(
+          serializer: Serializers::MarshalSerializer.new,
+          expires_in: 1 * (60 * 60 * 24)
+        )
+        @serializer = @options[:serializer]
       end
 
       def read_key(key)
@@ -20,7 +26,10 @@ module RemoteResource
         storage_entry.to_hash.each_pair do |key, value|
           write_args.concat([key, @serializer.dump(value)]) unless value.empty?
         end
-        @redis.hmset storage_key, *write_args
+        @redis.multi do |multi|
+          multi.hmset storage_key, *write_args
+          multi.expire storage_key, @options[:expires_in]
+        end
       end
     end
   end

data/lib/remote_resource/storage/serializers/{marshal.rb → marshal_serializer.rb}

@@ -1,4 +1,4 @@
-require_relative '../serializer'
+require 'remote_resource/storage/serializer'
 
 module RemoteResource
   module Storage

data/lib/remote_resource/version.rb

@@ -1,3 +1,3 @@
 module RemoteResource
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/lib/remote_resource.rb

@@ -31,4 +31,30 @@ module RemoteResource
   autoload :Bridge
   autoload :LogSubscriber
   autoload :ScopeEvaluator
+
+  module Lookup
+    extend ActiveSupport::Autoload
+
+    autoload :Default
+  end
+
+  autoload_under 'storage' do
+    autoload :CacheControl
+    autoload :NullStorageEntry
+    autoload :StorageEntry
+  end
+
+  module Storage
+    extend ActiveSupport::Autoload
+
+    autoload :Memory
+    autoload :Redis
+    autoload :Serializer
+
+    module Serializers
+      extend ActiveSupport::Autoload
+
+      autoload :MarshalSerializer
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: remote-resource
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Chris Ewald
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-25 00:00:00.000000000 Z
+date: 2016-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -114,6 +114,7 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- lib/remote-resource.rb
 - lib/remote_resource.rb
 - lib/remote_resource/association_builder.rb
 - lib/remote_resource/attribute_http_client.rb
@@ -137,13 +138,11 @@ files:
 - lib/remote_resource/railtie.rb
 - lib/remote_resource/scope_evaluator.rb
 - lib/remote_resource/storage/cache_control.rb
-- lib/remote_resource/storage/db_cache.rb
-- lib/remote_resource/storage/db_cache_factory.rb
 - lib/remote_resource/storage/memory.rb
 - lib/remote_resource/storage/null_storage_entry.rb
 - lib/remote_resource/storage/redis.rb
 - lib/remote_resource/storage/serializer.rb
-- lib/remote_resource/storage/serializers/marshal.rb
+- lib/remote_resource/storage/serializers/marshal_serializer.rb
 - lib/remote_resource/storage/storage_entry.rb
 - lib/remote_resource/version.rb
 - remote-resource.gemspec

data/lib/remote_resource/storage/db_cache.rb

@@ -1,36 +0,0 @@
-require 'remote_resource/storage/serializers/marshal'
-
-module RemoteResource
-  class DBCache
-    ADAPTERS = %i(active_record)
-
-    attr_reader :column_name
-    attr_accessor :target_instance
-
-    def initialize(_adapter, column_name, _serializer = :marshal)
-      @adapter = :active_record
-      @column_name = column_name.to_sym
-      @serializer = Serializers::MarshalSerializer.new
-    end
-
-    # always returns a hash
-    def read_column
-      raw = @target_instance.read_attribute(column_name)
-      raw ? @serializer.load(raw) : {}
-    end
-
-    def write_column(hash)
-      fail ArgumentError 'must be a hash!' unless hash.is_a? Hash
-      raw = @serializer.dump(hash)
-      @target_instance.update_attribute(column_name, raw)
-    end
-
-    def read_key(key)
-      read_column[key.to_sym]
-    end
-
-    def write_key(key, value)
-      write_column(read_column.merge(key.to_sym => value))
-    end
-  end
-end

data/lib/remote_resource/storage/db_cache_factory.rb

@@ -1,38 +0,0 @@
-require 'remote_resource/storage/db_cache'
-
-module RemoteResource
-  class UnsupportedDatabase < StandardError; end
-
-  class DBCacheFactory
-    def initialize(base_class, options)
-      @base_class = base_class
-      @options = options
-    end
-
-    def create_for_class(target_class)
-      db_cache_adapter = db_cache_adapter_for(target_class)
-      if db_cache_adapter
-        column_name = @options[:cache_column] ||
-                      default_or_magic_column_name_for(@base_class)
-        DBCache.new(db_cache_adapter, column_name)
-      else
-        fail UnsupportedDatabase
-      end
-    end
-
-    private
-
-    def default_or_magic_column_name_for(base_class)
-      "#{base_class.underscore}_cache"
-    end
-
-    def db_cache_adapter_for(klass)
-      DBCache::ADAPTERS.detect do |adapter_name|
-        klass.ancestors.any? do |parent_class|
-          next unless (class_name = parent_class.name)
-          class_name.split('::').first.underscore.to_sym == adapter_name
-        end
-      end
-    end
-  end
-end