cistern 0.5.4 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6c39b9ac9a702497cd0fd82279e908697d2d8e65
-  data.tar.gz: 7b9aae264e94c4dd5c5d883a697cf038659be657
+  metadata.gz: 83399a872cc26926353a8186ca5a2eeb5e35694f
+  data.tar.gz: a63f6fc98003b05aa829e18d976718a3698ba2e7
 SHA512:
-  metadata.gz: 8441ed13d9b55f0f1cf988ec91a47914174388bed261811fa9c4a5d65cea727c8252a65fc1af22b75187f5c044fa1a058c109ed9693efb4ef1606fbfa5039ad1
-  data.tar.gz: 258a085c417051866346609af569a7269d173d8652fae7906bb365884c4d60fb493a9d2d5f9feaab336566a5efc7f9dcc8c2749a5644be336381c28b858932b6
+  metadata.gz: 2a456bdd5e6b9578d3c56abe014e1dad0d8b1bb3371808198cb683797a95860997f17aabbea453a635462a25f71d0576181b02cb108d7bfd72521f717ea427dc
+  data.tar.gz: 094d70ac588adbf30f9430845e44ba80209149a96301822302d2f2bc044eb8e02cb2c569b8bd2c275b59adb01c1849331e228b2d664a55290992489b0236f6a5

data/README.md

@@ -11,172 +11,197 @@ Cistern helps you consistenly build your API clients and faciliates building moc
 
 This represents the remote service that you are wrapping. If the service name is 'foo' then a good name is 'Foo::Client'.
 
-Service initialization will only accept parameters enumerated by ```requires``` and ```recognizes```. ```model```, ```collection```, and ```request``` enumerate supported features and require them directly within the context of the ```model_path``` and ```request_path```.
+#### Requests
 
-```Mock.data``` is commonly used to store mock data.  It is often easiest to use identity to raw response mappings within the ```Mock.data``` hash.
+Requests are enumerated using the ```request``` method and required immediately via the relative path specified via ```request_path```.
 
-```ruby
+    class Foo::Client < Cistern::Service
+      request_path "my-foo/requests"
 
-class Foo::Client < Cistern::Service
+      request :get_bar  # require my-foo/requests/get_bar.rb
+      request :get_bars # require my-foo/requests/get_bars.rb
 
-  model_path "foo/models"
-  request_path "foo/requests"
+      class Real
+        def request(url)
+          Net::HTTP.get(url)
+        end
+      end
+    end
 
-  model :bar
-  collection :bars
-  request :create_bar
-  request :get_bar
-  request :get_bars
 
-  requires :hmac_id, :hmac_secret
-  recognizes :host
+<!--todo move to a request section-->
+A request is method defined within the context of service and mode (Real or Mock).  Defining requests within the service mock class is optional.
 
-  class Real
-    def initialize(options={})
-      # setup connection
-    end
-  end
+    # my-foo/requests/get_bar.rb
+    class Foo::Client
+      class Real
+        def get_bar(bar_id)
+          request("http://example.org/bar/#{bar_id}")
+        end
+      end # Real
 
-  class Mock
-    def self.data
-      @data ||= {
-                  :bars => {},
-                }
-    end
+      # optional, but encouraged
+      class Mock
+        def get_bars
+          # do some mock things
+        end
+      end # Mock
+    end # Foo::client
 
-    def self.reset!
-      @data = nil
-    end
+All declared requests can be listed via ```Cistern::Service#requests```.
 
-    def data
-      self.class.data
-    end
-    def initialize(options={})
-      # setup mock data
-    end
-  end
-end
+    Foo::Client.requests # => [:get_bar, :get_bars]
 
-```
+#### Models and Collections
 
-### Model
+Models and collections have declaration semantics similar to requests.  Models and collections are enumerated via ```model``` and ```collection``` respectively.
 
-```connection``` represents the associated ```Foo::Client``` instance.
+    class Foo::Client < Cistern::Service
+      model_path "my-foo/models"
 
-```ruby
+      model :bar       # require my-foo/models/bar.rb
+      collection :bars # require my-foo/models/bars.rb
+    end
 
-class Foo::Client::Bar < Cistern::Model
-  identity :id
+#### Initialization
 
-  attribute :flavor
-  attribute :keypair_id, aliases: "keypair",  squash: "id"
-  attribute :private_ips, type: :array
+Service initialization parameters are enumerated by ```requires``` and ```recognizes```.  ```recognizes``` parameters are optional.
 
-  def destroy
-    params  = {
-      "id" => self.identity
-    }
-    self.connection.destroy_bar(params).body["request"]
-  end
+    class Foo::Client < Cistern::Service
+      requires :hmac_id, :hmac_secret
+      recognizes :url
+    end
 
-  def save
-    requires :keypair_id
+    # Acceptable
+    Foo::Client.new(hmac_id: "1", hmac_secret: "2")                            # Foo::Client::Real
+    Foo::Client.new(hmac_id: "1", hmac_secret: "2", url: "http://example.org") # Foo::Client::Real
 
-    params = {
-      "keypair" => self.keypair_id,
-      "bar"     => {
-        "flavor" => self.flavor,
-      },
-    }
+    # ArgumentError
+    Foo::Client.new(hmac_id: "1", url: "http://example.org")
+    Foo::Client.new(hmac_id: "1")
 
-    if new_record?
-      merge_attributes(connection.create_bar(params).body["bar"])
-    else
-      requires :identity
 
-      merge_attributes(connection.update_bar(params).body["bar"])
-    end
-  end
-end
+#### Mocking
 
-```
+Cistern strongly encourages you to generate mock support for service. Mocking can be enabled using ```mock!```.
 
-### Collection
+    Foo::Client.mocking?          # falsey
+    real = Foo::Client.new        # Foo::Client::Real
+    Foo::Client.mock!
+    Foo::Client.mocking?          # true
+    fake = Foo::Client.new        # Foo::Client::Mock
+    Foo::Client.unmock!
+    Foo::Client.mocking?          # false
+    real.is_a?(Foo::Client::Real) # true
+    fake.is_a?(Foo::Client::Mock) # true
 
-```model``` tells Cistern which class is contained within the collection.  ```Cistern::Collection``` inherits from ```Array``` and lazy loads where applicable.
 
-```ruby
+### Model
 
-class Foo::Client::Bars < Cistern::Collection
+```connection``` represents the associated ```Foo::Client``` instance.
 
-  model Foo::Client::Bar
+    class Foo::Client::Bar < Cistern::Model
+      identity :id
 
-  def all(params = {})
-    response = connection.get_bars(params)
+      attribute :flavor
+      attribute :keypair_id, aliases: "keypair",  squash: "id"
+      attribute :private_ips, type: :array
 
-    data = response.body
+      def destroy
+        params  = {
+          "id" => self.identity
+        }
+        self.connection.destroy_bar(params).body["request"]
+      end
 
-    self.load(data["bars"])     # store bar records in collection
-    self.merge_attributes(data) # store any other attributes of the response on the collection
-  end
+      def save
+        requires :keypair_id
 
-  def discover(provisioned_id, options={})
-    params = {
-      "provisioned_id" => provisioned_id,
-    }
-    params.merge!("location" => options[:location]) if options.key?(:location)
+        params = {
+          "keypair" => self.keypair_id,
+          "bar"     => {
+            "flavor" => self.flavor,
+          },
+        }
 
-    connection.requests.new(connection.discover_bar(params).body["request"])
-  end
+        if new_record?
+          merge_attributes(connection.create_bar(params).body["bar"])
+        else
+          requires :identity
 
-  def get(id)
-    if data = connection.get_bar("id" => id).body["bar"]
-      new(data)
-    else
-      nil
+          merge_attributes(connection.update_bar(params).body["bar"])
+        end
+      end
     end
-  end
-end
 
-```
+### Collection
 
-### Request
+```model``` tells Cistern which class is contained within the collection.  ```Cistern::Collection``` inherits from ```Array``` and lazy loads where applicable.
 
-```ruby
-
-module Foo
-  class Client
-    class Real
-      def create_bar(options={})
-        request(
-          :body     => {"bar" => options},
-          :method   => :post,
-          :path     => '/bar'
-        )
-      end
-    end # Real
+    class Foo::Client::Bars < Cistern::Collection
 
-    class Mock
-      def create_bar(options={})
-        id = Foo.random_hex(6)
+      model Foo::Client::Bar
 
-        bar = {
-          "id" => id
-        }.merge(options)
+      def all(params = {})
+        response = connection.get_bars(params)
 
-        self.data[:bars][id]= bar
+        data = response.body
 
-        response(
-          :body   => {"bar" => bar},
-          :status => 201,
-          :path => '/bar',
-        )
+        self.load(data["bars"])     # store bar records in collection
+        self.merge_attributes(data) # store any other attributes of the response on the collection
       end
-    end # Mock
-  end # Client
-end # Foo
 
-```
+      def discover(provisioned_id, options={})
+        params = {
+          "provisioned_id" => provisioned_id,
+        }
+        params.merge!("location" => options[:location]) if options.key?(:location)
+
+        connection.requests.new(connection.discover_bar(params).body["request"])
+      end
+
+      def get(id)
+        if data = connection.get_bar("id" => id).body["bar"]
+          new(data)
+        else
+          nil
+        end
+      end
+    end
+
+### Request
+
+    module Foo
+      class Client
+        class Real
+          def create_bar(options={})
+            request(
+              :body     => {"bar" => options},
+              :method   => :post,
+              :path     => '/bar'
+            )
+          end
+        end # Real
+
+        class Mock
+          def create_bar(options={})
+            id = Foo.random_hex(6)
+
+            bar = {
+              "id" => id
+            }.merge(options)
+
+            self.data[:bars][id]= bar
+
+            response(
+              :body   => {"bar" => bar},
+              :status => 201,
+              :path => '/bar',
+            )
+          end
+        end # Mock
+      end # Client
+    end # Foo
 
 ## Examples
 

data/lib/cistern/attributes.rb

@@ -57,6 +57,17 @@ module Cistern::Attributes
     end
 
     def attribute(_name, options = {})
+      if defined? Cistern::Coverage
+        attribute_call = Cistern::Coverage.find_caller_before("cistern/attributes.rb")
+
+        # Only use DSL attribute calls from within a model
+        if attribute_call and attribute_call.label.start_with? "<class:"
+          options[:coverage_file] = attribute_call.absolute_path
+          options[:coverage_line] = attribute_call.lineno
+          options[:coverage_hits] = 0
+        end
+      end
+
       name = _name.to_s.to_sym
 
       parser = Cistern::Attributes.parsers[options[:type]] ||
@@ -66,6 +77,9 @@ module Cistern::Attributes
         Cistern::Attributes.default_transform
 
       self.send(:define_method, name) do
+        # record the attribute was accessed
+        self.class.attributes[name.to_s.to_sym][:coverage_hits] += 1 rescue  nil
+
         attributes[name.to_s.to_sym]
       end
 

data/lib/cistern/coverage.rb

@@ -0,0 +1,34 @@
+module Cistern::Coverage
+
+  unless Kernel.respond_to? :caller_locations
+    abort <<-ABORT
+Cannot enable Cistern coverage reporting
+
+Your ruby version ruby is: #{RUBY_VERSION rescue 'unknown'}
+`Kernel` does not have the required method `caller_locations`
+
+Try a newer ruby (should be > 2.0)
+    ABORT
+  end
+
+  # returns the first caller_locations entry before entries in `file`
+  def self.find_caller_before(file)
+    enum = caller_locations.each
+
+    call = nil
+
+    # seek to the first entry from within `file`
+    while(call = enum.next) do
+      break if call.path.end_with? file
+    end
+
+    # seek to the first entry thats not within `file`
+    while(call = enum.next) do
+      break unless call.path.end_with? file
+    end
+
+    # the call location that called in to `file`
+    call
+  end
+
+end

data/lib/cistern/formatter/awesome_print.rb

@@ -32,7 +32,7 @@ module AwesomePrint::Cistern
   # Format Cistern::Model
   #------------------------------------------------------------------------------
   def awesome_cistern_collection(object)
-    "#{object.class.name} " << awesome_hash(attributes: object.attributes, records: object.records)
+    "#{object.class.name} " << awesome_hash(attributes: object.attributes, records: object.to_a)
   end
 end
 

data/lib/cistern/service.rb

@@ -37,6 +37,10 @@ class Cistern::Service
       klass.send(:const_set, :Timeout, Class.new(Cistern::Error))
     end
 
+    def collection_path(collection_path)
+      @collection_path = collection_path
+    end
+
     def model_path(model_path)
       @model_path = model_path
     end
@@ -127,7 +131,14 @@ class Cistern::Service
           end
         end
         collections.each do |collection, options|
-          require File.join(@model_path, collection.to_s) unless options[:require] == false
+          unless options[:require] == false
+            if @collection_path
+              require File.join(@collection_path, collection.to_s)
+            else
+              require File.join(@model_path, collection.to_s)
+            end
+          end
+
           class_name = collection.to_s.split("_").map(&:capitalize).join
           self.const_get(:Collections).module_eval <<-EOS, __FILE__, __LINE__
             def #{collection}(attributes={})

data/lib/cistern/version.rb

@@ -1,3 +1,3 @@
 module Cistern
-  VERSION = "0.5.4"
+  VERSION = "0.5.6"
 end

data/lib/cistern/wait_for.rb

@@ -2,8 +2,8 @@ require 'timeout'
 
 module Cistern
   module WaitFor
-    DEFAULT_TIMEOUT       = 3 * 60 # 3 minutes
-    DEFAULT_POLL_INTERVAL = 10 # seconds
+    DEFAULT_TIMEOUT       = 180 # 3 minutes
+    DEFAULT_POLL_INTERVAL = 10  # 10 seconds
 
     def timeout; @timeout || DEFAULT_TIMEOUT; end
     def timeout=(timeout); @timeout = timeout; end

data/spec/model_spec.rb

@@ -129,4 +129,38 @@ describe "Cistern::Model" do
       end
     end
   end
+
+  context "attribute coverage info collecting", :coverage do
+    class CoverageSpec < Cistern::Model
+      identity :id
+
+      attribute :used, type: :string
+      attribute :unused, type: :string
+    end
+
+    let!(:obj) { CoverageSpec.new(used: "foo", unused: "bar") }
+
+    before(:each) do
+      CoverageSpec.attributes[:used][:coverage_hits] = 0
+      obj.used.should == "foo" # once
+      obj.used.should == "foo" # twice
+    end
+
+    it "should store the file path where the attribute was defined" do
+      CoverageSpec.attributes[:used][:coverage_file].should == __FILE__
+      CoverageSpec.attributes[:unused][:coverage_file].should == __FILE__
+    end
+
+    it "should store the line number where the attribute was defined" do
+      src_lines = File.read(__FILE__).lines
+
+      src_lines[CoverageSpec.attributes[:used][:coverage_line] - 1].should match(/attribute :used/)
+      src_lines[CoverageSpec.attributes[:unused][:coverage_line] - 1].should match(/attribute :unused/)
+    end
+
+    it "should store how many times an attribute's reader is called" do
+      CoverageSpec.attributes[:used][:coverage_hits].should == 2
+      CoverageSpec.attributes[:unused][:coverage_hits].should == 0
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -2,5 +2,12 @@ require File.expand_path('../../lib/cistern', __FILE__)
 
 Bundler.require(:test)
 
-RSpec.configure do
+RSpec.configure do |c|
+  c.treat_symbols_as_metadata_keys_with_true_values = true
+
+  if Kernel.respond_to?(:caller_locations)
+    require File.expand_path('../../lib/cistern/coverage', __FILE__)
+  else
+    c.filter_run_excluding(:coverage)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cistern
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.5.6
 platform: ruby
 authors:
 - Josh Lane
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-03 00:00:00.000000000 Z
+date: 2014-04-02 00:00:00.000000000 Z
 dependencies: []
 description: API client framework extracted from Fog
 email:
@@ -29,6 +29,7 @@ files:
 - lib/cistern.rb
 - lib/cistern/attributes.rb
 - lib/cistern/collection.rb
+- lib/cistern/coverage.rb
 - lib/cistern/formatter.rb
 - lib/cistern/formatter/awesome_print.rb
 - lib/cistern/formatter/formatador.rb
@@ -74,3 +75,4 @@ test_files:
 - spec/model_spec.rb
 - spec/spec_helper.rb
 - spec/wait_for_spec.rb
+has_rdoc: