frenetic 0.0.20.alpha.1 → 0.0.20.alpha.2

data/README.md

@@ -91,10 +91,17 @@ the API contains, it can't navigate around it or parse any of it's responses.
 This response will be requested by Frenetic whenever a call to
 `YourAPI.description` is made.
 
-**Note:** It is highly advised that you implement some sort of caching in both
-your API server as well as your API client. Refer to the [Caching][caching] section for
-more information.
+**Note:** It is highly advised that your API return Cache-Control headers in
+this response. Frenetic needs to frequently refer to the API description to see
+what is possible. This will result in lots of HTTP requests if you don't tell
+it how long to wait before checking again.
 
+If the API does return Cache-Control headers, Frenetic will always cache this
+response regardless of which caching middleware you have configured or even if
+you have caching disabled.
+
+If you have no control over the API, refer to the
+[Default Root Cache Age][root_cache] section.
 
 
 
@@ -250,6 +257,17 @@ Frenetic.new( url:url, adapter:Faraday::Adapter::Patron )
 ```
 
 
+#### Default Root Cache Age
+
+If you have no control over the API, you can explicitly tell Frenetic how long
+to cache the API description for:
+
+```ruby
+Frenetic.new( url:url, default_root_cache_age:1.hour )
+```
+
+
+
 #### Faraday Middleware
 
 Frenetic will yield its internal Faraday connection during initialization:
@@ -341,6 +359,7 @@ ideas on how to support other Hypermedia formats like [Collection+JSON][coll_jso
 [spire.io]: http://api.spire.io/
 [caching]: #response-caching
 [faraday]: https://github.com/technoweenie/faraday
+[root_cache]: #default-root-cache-age
 [adapters]: https://github.com/lostisland/faraday/blob/c26a060acdd9eae356409c2ca79f1c22f8263de9/lib/faraday/adapter.rb#L7-L17
 [rack_cache]: https://github.com/rtomayko/rack-cache
 [coll_json]: http://amundsen.com/media-types/collection/

data/frenetic.gemspec

@@ -24,4 +24,5 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'rspec',               '~> 2.13.0'
   gem.add_development_dependency 'rack-cache',          '~> 1.2'
   gem.add_development_dependency 'webmock',             '~> 1.11.0'
+  gem.add_development_dependency 'timecop',             '~> 0.6.1'
 end

data/lib/frenetic.rb

@@ -4,6 +4,7 @@ require 'faraday_middleware'
 
 require 'frenetic/version'
 require 'frenetic/concerns/configurable'
+require 'frenetic/concerns/briefly_memoizable'
 require 'frenetic/middleware/hal_json'
 require 'frenetic/resource'
 require 'frenetic/resource_collection'
@@ -11,6 +12,7 @@ require 'frenetic/resource_collection'
 class Frenetic
   extend Forwardable
   include Configurable
+  include BrieflyMemoizable
 
   def_delegators :connection, :get, :put, :post, :delete
 
@@ -39,16 +41,35 @@ class Frenetic
     end
   end
 
-  # It is highly advised that the server responds with some cache headers and
-  # the API Client is configured to use a Faraday caching strategy
+  # Since Frenetic needs to frequently refer to the API design, the result of
+  # this method is essentially cached, regardless of what caching middleware it
+  # is configured with.
+  #
+  # It fully honors the HTTP Cache-Control headers that are returned by the API.
+  #
+  # If no Cache-Control header is returned, then the results are not memoized.
   def description
     if response = get( config.url.to_s ) and response.success?
+      @description_age = cache_control_age( response.headers )
+
       response.body
     end
   end
+  briefly_memoize :description
 
   def schema
     description['_embedded']['schema']
   end
 
+private
+
+  def cache_control_age( headers )
+    if cache_age = headers['Cache-Control']
+      age = cache_age.match(%r{max-age=(?<max_age>\d+)})[:max_age]
+
+      Time.now + age.to_i
+    else
+      config.default_root_cache_age
+    end
+  end
 end

data/lib/frenetic/concerns/briefly_memoizable.rb

@@ -0,0 +1,30 @@
+require 'active_support/concern'
+
+# Memoizes method calls, but only for a specific period of time.
+# Useful for supporting HTTP Cache-Control without an external caching layer
+# like Rack::Cache
+module BrieflyMemoizable
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    def briefly_memoize( symbol )
+      original_method = "_unmemoized_#{symbol}".to_sym
+      memoized_ivar   = "@#{symbol}"
+      age_ivar        = "@#{symbol}_age"
+
+      class_eval <<-EOS
+        if method_defined?(:#{original_method})                                  # if method_defined?(:_unmemoized_mime_type)
+          raise "Already memoized #{symbol}"                                     #   raise "Already memoized mime_type"
+        end                                                                      # end
+        alias #{original_method} #{symbol}                                       # alias _unmemoized_mime_type mime_type
+
+        def #{symbol}(*args)                                                     # def mime_type(*args)
+          #{memoized_ivar} = nil if #{age_ivar} && Time.now > #{age_ivar}        #   @mime_type = nil if @mime_type_age && Time.now > @mime_type_age
+                                                                                 #
+          #{memoized_ivar} ||= #{original_method}(*args)                         #   @mime_type ||= _unmemoized_mime_type(*args)
+        end                                                                      # end
+      EOS
+    end
+  end
+
+end

data/lib/frenetic/configuration.rb

@@ -28,6 +28,7 @@ class Frenetic
         adapter:   adapter,
         api_token: api_token,
         cache:     cache,
+        default_root_cache_age: default_root_cache_age,
         headers:   headers,
         password:  password,
         url:       url,
@@ -47,6 +48,10 @@ class Frenetic
       end
     end
 
+    def default_root_cache_age
+      @_cfg[:default_root_cache_age]
+    end
+
     def headers
       @@defaults[:headers].merge( @_cfg[:headers] || {} )
     end

data/lib/frenetic/version.rb

@@ -1,3 +1,3 @@
 class Frenetic
-  VERSION = '0.0.20.alpha.1'
+  VERSION = '0.0.20.alpha.2'
 end

data/spec/concerns/breifly_memoizable_spec.rb

@@ -0,0 +1,59 @@
+require 'spec_helper'
+
+describe BrieflyMemoizable do
+  let(:my_class) { Class.new }
+
+  before do
+    stub_const 'MyClass', my_class
+
+    MyClass.send :include, described_class
+    MyClass.class_eval do
+      def fetch
+        @fetch_age = Time.now + 3600
+
+        external_call
+      end
+      briefly_memoize :fetch
+
+      def external_call
+        true
+      end
+    end
+  end
+
+  let(:instance) { MyClass.new }
+
+  describe '.briefly_memoize' do
+    context 'for an expensive method' do
+      before do
+        Timecop.freeze
+
+        instance.fetch
+      end
+
+      context 'which is called again outside the memoize window' do
+        before do
+          Timecop.travel Time.now + 5400
+        end
+
+        it 'should be called' do
+          instance.should_receive(:external_call).once.and_call_original
+
+          instance.fetch
+        end
+      end
+
+      context 'which is called again within the memoize window' do
+        before do
+          Timecop.travel Time.now + 1800
+        end
+
+        it 'should not be called' do
+          instance.should_receive(:external_call).never.and_call_original
+
+          instance.fetch
+        end
+      end
+    end
+  end
+end

data/spec/configuration_spec.rb

@@ -15,6 +15,7 @@ describe Frenetic::Configuration do
     it { should include :adapter }
     it { should include :api_token }
     it { should include :cache }
+    it { should include :default_root_cache_age }
     it { should include :headers }
     it { should include :password }
     it { should include :url }
@@ -47,6 +48,16 @@ describe Frenetic::Configuration do
     end
   end
 
+  describe '#default_root_cache_age' do
+    let(:cfg) do
+      { default_root_cache_age:3600 }
+    end
+
+    subject { instance.default_root_cache_age }
+
+    it { should == 3600 }
+  end
+
   describe '#headers' do
     let(:cfg) do
       { headers:{ accept:'MIME', x_foo:'BAR' } }

data/spec/fixtures/test_api_requests.rb

@@ -15,7 +15,12 @@ class HttpStubs
   end
 
   def response( params = {} )
-    defaults.merge( params ).tap do |p|
+    defs    = defaults.dup
+    headers = params.delete :headers
+
+    defs[:headers].merge! headers || {}
+
+    defs.merge( params ).tap do |p|
       p[:body] = p[:body].to_json
     end
   end
@@ -36,7 +41,7 @@ class HttpStubs
 
   def api_description
     @rspec.stub_request( :any, 'example.com/api' )
-      .to_return response( body:schema )
+      .to_return response( body:schema, headers:{ 'Cache-Control' => 'max-age=3600, public' } )
   end
 
   def unknown_resource

data/spec/support/timecop.rb

@@ -0,0 +1 @@
+require 'timecop'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: frenetic
 version: !ruby/object:Gem::Version
-  version: 0.0.20.alpha.1
+  version: 0.0.20.alpha.2
   prerelease: 7
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-11 00:00:00.000000000 Z
+date: 2013-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -139,6 +139,22 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 1.11.0
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.6.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.6.1
 description: An opinionated Ruby-based Hypermedia API client.
 email:
 - dlindahl@customink.com
@@ -156,6 +172,7 @@ files:
 - Rakefile
 - frenetic.gemspec
 - lib/frenetic.rb
+- lib/frenetic/concerns/briefly_memoizable.rb
 - lib/frenetic/concerns/collection_rest_methods.rb
 - lib/frenetic/concerns/configurable.rb
 - lib/frenetic/concerns/hal_linked.rb
@@ -166,6 +183,7 @@ files:
 - lib/frenetic/resource.rb
 - lib/frenetic/resource_collection.rb
 - lib/frenetic/version.rb
+- spec/concerns/breifly_memoizable_spec.rb
 - spec/concerns/configurable_spec.rb
 - spec/concerns/hal_linked_spec.rb
 - spec/concerns/member_rest_methods_spec.rb
@@ -178,6 +196,7 @@ files:
 - spec/resource_spec.rb
 - spec/spec_helper.rb
 - spec/support/rspec.rb
+- spec/support/timecop.rb
 - spec/support/webmock.rb
 homepage: http://dlindahl.github.com/frenetic/
 licenses: []
@@ -193,7 +212,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3155215012815263773
+      hash: -863323542650757064
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -208,6 +227,7 @@ specification_version: 3
 summary: Here lies a Ruby-based Hypermedia API client that expects HAL+JSON and makes
   a lot of assumptions about your API.
 test_files:
+- spec/concerns/breifly_memoizable_spec.rb
 - spec/concerns/configurable_spec.rb
 - spec/concerns/hal_linked_spec.rb
 - spec/concerns/member_rest_methods_spec.rb
@@ -220,4 +240,5 @@ test_files:
 - spec/resource_spec.rb
 - spec/spec_helper.rb
 - spec/support/rspec.rb
+- spec/support/timecop.rb
 - spec/support/webmock.rb