frenetic 0.0.1 → 0.0.2.alpha1

data/README.md

@@ -5,6 +5,122 @@
 
 An opinionated Ruby-based Hypermedia API (HAL+JSON) client.
 
+
+
+
+## About
+
+fre&bull;net&bull;ic |frəˈnetik|<br/>
+adjective<br/>
+fast and energetic in a rather wild and uncontrolled way : *a frenetic pace of activity.*
+
+So basically, this is a crazy way to interact with your Hypermedia HAL+JSON API.
+
+Get it? *Hypermedia*?
+
+*Hyper*?
+
+...
+
+If you have not implemented a HAL+JSON API, then this will not work very well for you.
+
+
+
+
+## Opinions
+
+Like I said, it is opinionated. It is so opinionated, it is probably the biggest
+a-hole you've ever met.
+
+Maybe in time, if you teach it, it will become more open-minded.
+
+
+
+### HAL+JSON Content Type
+
+Frenetic expects all responses to be in [HAL+JSON][hal_json]. It chose that
+standard because it is trying to make JSON API's respond in a predictable
+manner, which it thinks is an awesome idea.
+
+
+
+### Authentication
+
+Frenetic is going to try and use Basic Auth whether you like it or not. If
+that is not required, nothing will probably happen. But its going to send the
+header anyway.
+
+
+
+### API Description
+
+The API's root URL must respond with a description, much like the
+[Spire.io][spire.io] API. This is crucial in order for Frenetic to work. If
+Frenetic doesn't know what the API contains, it can't parse any resource
+responses.
+
+It is expected that any subclasses of `Frenetic::Resource` will adhere to the
+schema defined here.
+
+Example:
+
+```js
+{
+  "_links":{
+    "self":{"href":"/api/"},
+    "inkers":{"href":"/api/inkers"},
+  },
+  "_embedded":{
+    "schema":{
+      "_links":{
+        "self":{"href":"/api/schema"}
+      },
+      "order":{
+        "description":"A widget order",
+        "type":"object",
+        "properties":{
+          "id":{"type":"integer"},
+          "first_name":{"type":"string"},
+          "last_name":{"type":"string"},
+        }
+      }
+    }
+  }
+}
+```
+
+This response will be requested by Frenetic whenever a call to
+`YourAPI.description` is made. The response is memoized so any future calls
+will not trigger another API request.
+
+
+
+### API Resources
+
+While HAL+JSON is awesome, not all implementations are perfect. Frenetic
+assumes a HAL+JSON response as built by [Roar], which may not be in 100%
+compliance.
+
+Example:
+
+```js
+{
+  "id":1,
+  "first_name":"Foo",
+  "last_name":"Bar",
+  "_links":{
+    "self":{"href":"/order/1"},
+    "next":{"href":"/order/2"}
+  }
+}
+```
+
+The problem here is that the entire response really should be wrapped in
+`"_embedded"` and `"order"` keys.
+
+So until that is fixed, Frenetic will continue to be pig headed and continue
+to do the "wrong" thing.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -19,9 +135,128 @@ Or install it yourself as:
 
     $ gem install frenetic
 
+
+
+
 ## Usage
 
-Your guess is as good as mine. (*TODO*)
+
+
+### Client Initialization
+
+```ruby
+MyAPI = Frenetic.new(
+  'url'          => 'https://api.yoursite.com',
+  'username'     => 'yourname',
+  'password'     => 'yourpassword',
+  'headers' => {
+    'accept' => 'application/vnd.yoursite-v1.hal+json'
+    # Optional
+    'user-agent' => 'Your Site's API Client', # Optional custom User Agent, just 'cuz
+  }
+)
+```
+
+
+### Response Caching
+
+If configured to do so, Frenetic will autotmatically cache appropriate responses
+through [Rack::Cache][rach_cache]. Only on-disk stores are supported right now.
+
+Add the following `Rack::Cache` configuration options when initializing Frenetic:
+
+```ruby
+MyAPI = Frenetic.new(
+  ...
+  'cache' => {
+    'metastore'   => 'file:/path/to/where/you/want/to/store/files/meta',
+    'entitystore' => 'file:/path/to/where/you/want/to/store/files/meta'
+  }
+)
+```
+
+The `cache` options are passed directly to `Rack::Cache`, so anything it
+supports can be added to the Hash.
+
+
+
+### Making Requests
+
+Once you have created a client instance, you are free to use it however you'd
+like.
+
+A Frenetic instance supports any HTTP verb that [Faraday][faraday] has
+impletented. This includes GET, POST, PUT, PATCH, and DELETE.
+
+
+
+#### Frenetic::Resource
+
+An easier way to make requests for a resource is to have your model inherit from
+`Frenetic::Resource`. This makes it a bit easier to encapsulate all of your
+resource's API requests into one place.
+
+```ruby
+class Order < Frenetic::Resource
+
+  api_client { MyAPI }
+
+  class << self
+    def find( id )
+      if response = api.get( api.description.links.order.href.gsub('{id}', id.to_s) ) and response.success?
+        self.new( response.body )
+      else
+        raise OrderNotFound, "No Order found for #{id}"
+      end
+    end
+  end
+end
+```
+
+The `api_client` class method merely tells `Frenetic::Resource` which API Client
+instance to use. If you lazily instantiate your client, then you should pass a
+block as demonstrated above.
+
+Otherwise, you may pass by reference:
+
+```ruby
+class Order < Frenetic::Resource
+  api_client MyAPI
+end
+```
+
+When your model is initialized, it will contain attribute readers for every
+property defined in your API's schema or description. In theory, this allows an
+API to add, remove, or change properties without the need to directly update
+your model.
+
+
+
+### Interpretting Responses
+
+Any response body returned by a Frenetic generated API call will be returned as
+an OpenStruct-like object. This object responds to dot-notation as well as Hash
+keys and is enumerable.
+
+```ruby
+response.body.resources.orders.first
+```
+
+or
+
+```ruby
+response.body['_embedded']['orders'][0]
+```
+
+For your convenience, certain HAL+JSON keys have been aliased by methods a bit
+more readable:
+
+  * `_embedded` can be referenced as `resources`
+  * `_links` can be referenced as `links`
+  * `href` can be referenced as `url`
+
+
+
 
 ## Contributing
 
@@ -30,3 +265,9 @@ Your guess is as good as mine. (*TODO*)
 3. Commit your changes (`git commit -am 'Added some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+[hal_json]: http://stateless.co/hal_specification.html
+[spire.io]: http://api.spire.io/
+[roar]: https://github.com/apotonick/roar
+[faraday]: https://github.com/technoweenie/faraday
+[rack_cache]: https://github.com/rtomayko/rack-cache

data/frenetic.gemspec

@@ -15,14 +15,16 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = Frenetic::VERSION
 
-  gem.add_dependency             'faraday',       '~> 0.8.0.rc2'
-  gem.add_dependency             'addressable',   '~> 2.2.7'
-  gem.add_dependency             'patron',        '~> 0.4.18'
+  gem.add_dependency             'faraday',             '~> 0.8.0.rc2'
+  gem.add_dependency             'faraday_middleware',  '~> 0.8.6'
+  gem.add_dependency             'rack-cache',          '~> 1.1'
+  gem.add_dependency             'addressable',         '~> 2.2.7'
+  gem.add_dependency             'patron',              '~> 0.4.18'
 
-  gem.add_development_dependency 'guard-spork',   '~> 0.6.0'
-  gem.add_development_dependency 'guard-rspec',   '~> 0.7.0'
-  gem.add_development_dependency 'rspec',         '~> 2.9.0'
-  gem.add_development_dependency 'bourne',        '~> 1.1.2'
-  gem.add_development_dependency 'webmock',       '~> 1.8.6'
-  gem.add_development_dependency 'vcr',           '~> 2.0.1'
+  gem.add_development_dependency 'guard-spork',         '~> 0.6.0'
+  gem.add_development_dependency 'guard-rspec',         '~> 0.7.0'
+  gem.add_development_dependency 'rspec',               '~> 2.9.0'
+  gem.add_development_dependency 'bourne',              '~> 1.1.2'
+  gem.add_development_dependency 'webmock',             '~> 1.8.6'
+  gem.add_development_dependency 'vcr',                 '~> 2.0.1'
 end

data/lib/frenetic.rb

@@ -1,5 +1,8 @@
 require 'addressable/uri'
+require 'patron' # Needed to prevent https://github.com/technoweenie/faraday/issues/140
 require 'faraday'
+require 'faraday_middleware'
+require 'rack-cache'
 
 require "frenetic/configuration"
 require "frenetic/hal_json"
@@ -25,6 +28,11 @@ class Frenetic
     @connection = Faraday.new( config ) do |builder|
       builder.use HalJson
       builder.request :basic_auth, config[:username], config[:password]
+
+      if config[:cache]
+        builder.use FaradayMiddleware::RackCompatible, Rack::Cache::Context, config[:cache]
+      end
+
       builder.adapter :patron
     end
   end

data/lib/frenetic/configuration.rb

@@ -15,11 +15,7 @@ class Frenetic
       config[:headers]  ||= {}
       config[:request]  ||= {}
 
-      if config[:"content-type"]
-        config[:headers][:accepts] = config[:"content-type"]
-      else
-        config[:headers][:accepts] = "application/hal+json"
-      end
+      config[:headers][:accept] ||= "application/hal+json"
 
       # Copy the config into this Configuration instance.
       config.each { |k, v| self[k] = v }
@@ -27,6 +23,7 @@ class Frenetic
       super()
 
       configure_user_agent
+      configure_cache
 
       validate
     end
@@ -43,12 +40,35 @@ class Frenetic
       end
     end
 
+    def configure_cache
+      if self[:cache]
+        ignore_headers = (self[:cache][:ignore_headers] || '').split(' ')
+
+        self[:cache][:ignore_headers] = (ignore_headers + %w[Set-Cookie X-Content-Digest]).uniq
+      end
+    end
+
     def validate
       unless self[:url]
         raise ConfigurationError, "No API URL defined!"
       end
+      if self[:cache]
+        raise( ConfigurationError, "No cache :metastore defined!" )               if self[:cache][:metastore].to_s == ""
+        raise( ConfigurationError, "No cache :entitystore defined!" )             if self[:cache][:entitystore].to_s == ""
+        raise( ConfigurationError, "Required cache header filters are missing!" ) if missing_required_headers?
+      end
+    end
+
+    def missing_required_headers?
+      return true if self[:cache][:ignore_headers].empty?
+
+      header_set     = self[:cache][:ignore_headers]
+      custom_headers = header_set - %w[Set-Cookie X-Content-Digest]
+
+      header_set == custom_headers
     end
 
+    # TODO: Is this even being used?
     def config_file
       config_path = File.join( 'config', 'frenetic.yml' )
 

data/lib/frenetic/version.rb

@@ -1,3 +1,3 @@
 class Frenetic
-  VERSION = "0.0.1"
+  VERSION = "0.0.2.alpha1"
 end

data/spec/lib/frenetic/configuration_spec.rb

@@ -4,7 +4,9 @@ describe Frenetic::Configuration do
     { 'test' => {
         'url'          => 'http://example.org',
         'api_key'      => '1234567890',
-        'content-type' => content_type,
+        'headers' => {
+          'accept' => content_type,
+        },
         'request' => {
           'timeout' => 10000
         }
@@ -37,16 +39,16 @@ describe Frenetic::Configuration do
         subject[:headers][:user_agent].should =~ %r{Frenetic v.+; \S+$}
       end
 
-      context "with a specified Content-Type" do
-        it "should set an Accepts request header" do
-          subject[:headers].should include(:accepts => 'application/vnd.frenetic-v1-hal+json')
+      context "with a specified Accept header" do
+        it "should set an Accept request header" do
+          subject[:headers].should include(:accept => 'application/vnd.frenetic-v1-hal+json')
         end
       end
-      context "without a specified Content-Type" do
+      context "without a specified Accept header" do
         let(:content_type) { nil }
 
-        it "should set an Accepts request header" do
-          subject[:headers].should include(:accepts => 'application/hal+json')
+        it "should set an Accept request header" do
+          subject[:headers].should include(:accept => 'application/hal+json')
         end
       end
     end
@@ -63,11 +65,45 @@ describe Frenetic::Configuration do
         it { should be_a( Hash ) }
         it { should_not be_empty }
         it "should set an Accepts request header" do
-          subject[:headers].should include(:accepts => 'application/hal+json')
+          subject[:headers].should include(:accept => 'application/hal+json')
         end
         it "should set a User Agent request header" do
           subject[:headers][:user_agent].should =~ %r{Frenetic v.+; \S+$}
         end
+
+        context "which includes incorrect cache settings" do
+          before { Frenetic::Configuration.any_instance.stubs(:configure_cache).returns(nil) }
+
+          it "should raise a configuration error for a missing :metastore" do
+            expect {
+              Frenetic::Configuration.new('url' => 'http://example.org', 'cache' => {} )
+            }.to raise_error(
+              Frenetic::Configuration::ConfigurationError, "No cache :metastore defined!"
+            )
+          end
+
+          it "should raise a configuration error for a missing :entitystore" do
+            expect {
+              Frenetic::Configuration.new('url' => 'http://example.org', 'cache' => { 'metastore' => 'foo' } )
+            }.to raise_error(
+              Frenetic::Configuration::ConfigurationError, "No cache :entitystore defined!"
+            )
+          end
+
+          it "should raise a configuration error for missing required header filters" do
+            cache_cfg = {
+              'metastore'      => 'foo',
+              'entitystore'    => 'bar',
+              'ignore_headers' => ['baz'] # `configure_cache` method is skipped to create a bad state
+            }
+
+            expect {
+              Frenetic::Configuration.new('url' => 'http://example.org', 'cache' => cache_cfg )
+            }.to raise_error(
+              Frenetic::Configuration::ConfigurationError, "Required cache header filters are missing!"
+            )
+          end
+        end
       end
     end
   end

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: frenetic
 version: !ruby/object:Gem::Version
-  version: 0.0.1
-  prerelease: 
+  version: 0.0.2.alpha1
+  prerelease: 6
 platform: ruby
 authors:
 - Derek Lindahl
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-11 00:00:00.000000000Z
+date: 2012-04-18 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
-  requirement: &2157361220 !ruby/object:Gem::Requirement
+  requirement: &2156329760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,32 @@ dependencies:
         version: 0.8.0.rc2
   type: :runtime
   prerelease: false
-  version_requirements: *2157361220
+  version_requirements: *2156329760
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: &2156328980 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.6
+  type: :runtime
+  prerelease: false
+  version_requirements: *2156328980
+- !ruby/object:Gem::Dependency
+  name: rack-cache
+  requirement: &2156328220 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2156328220
 - !ruby/object:Gem::Dependency
   name: addressable
-  requirement: &2157360720 !ruby/object:Gem::Requirement
+  requirement: &2156327400 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +54,10 @@ dependencies:
         version: 2.2.7
   type: :runtime
   prerelease: false
-  version_requirements: *2157360720
+  version_requirements: *2156327400
 - !ruby/object:Gem::Dependency
   name: patron
-  requirement: &2157360240 !ruby/object:Gem::Requirement
+  requirement: &2156326620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +65,10 @@ dependencies:
         version: 0.4.18
   type: :runtime
   prerelease: false
-  version_requirements: *2157360240
+  version_requirements: *2156326620
 - !ruby/object:Gem::Dependency
   name: guard-spork
-  requirement: &2157359780 !ruby/object:Gem::Requirement
+  requirement: &2156325900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +76,10 @@ dependencies:
         version: 0.6.0
   type: :development
   prerelease: false
-  version_requirements: *2157359780
+  version_requirements: *2156325900
 - !ruby/object:Gem::Dependency
   name: guard-rspec
-  requirement: &2157359320 !ruby/object:Gem::Requirement
+  requirement: &2156325160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,10 +87,10 @@ dependencies:
         version: 0.7.0
   type: :development
   prerelease: false
-  version_requirements: *2157359320
+  version_requirements: *2156325160
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2157358860 !ruby/object:Gem::Requirement
+  requirement: &2156324300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -76,10 +98,10 @@ dependencies:
         version: 2.9.0
   type: :development
   prerelease: false
-  version_requirements: *2157358860
+  version_requirements: *2156324300
 - !ruby/object:Gem::Dependency
   name: bourne
-  requirement: &2157358400 !ruby/object:Gem::Requirement
+  requirement: &2156322980 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -87,10 +109,10 @@ dependencies:
         version: 1.1.2
   type: :development
   prerelease: false
-  version_requirements: *2157358400
+  version_requirements: *2156322980
 - !ruby/object:Gem::Dependency
   name: webmock
-  requirement: &2157357940 !ruby/object:Gem::Requirement
+  requirement: &2156322340 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -98,10 +120,10 @@ dependencies:
         version: 1.8.6
   type: :development
   prerelease: false
-  version_requirements: *2157357940
+  version_requirements: *2156322340
 - !ruby/object:Gem::Dependency
   name: vcr
-  requirement: &2157357480 !ruby/object:Gem::Requirement
+  requirement: &2156321440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -109,7 +131,7 @@ dependencies:
         version: 2.0.1
   type: :development
   prerelease: false
-  version_requirements: *2157357480
+  version_requirements: *2156321440
 description: An opinionated Ruby-based Hypermedia API client.
 email:
 - dlindahl@customink.com
@@ -155,9 +177,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>='
+  - - ! '>'
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.10