cistern 2.6.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2f58960f3c738abbdd7203d8973981f71c370a65
-  data.tar.gz: 94a23880c49416884ece0e3615ca7e170bba7234
+  metadata.gz: be9990e15cdccbe77ea1c27b5a6961fecd445129
+  data.tar.gz: d466f0e83e49c33fc9dce01eb713b9f1062e8f7e
 SHA512:
-  metadata.gz: 56fd5780ad10f6c44ff6704743cf927bb50600b3c45a00d1aa1afe8c2d4e237f5413bdc416e282255f924763c3fc19d2bc0afd11c52bcfb7ecf7e2f3e6c39fbd
-  data.tar.gz: aee0f212eb1923eb92131faa80a5a8fa1c8ae021e0fd1c485fb5b9ac653fba99558d71757d77fdd9baf9558dbdf27d24b72d11c5ce1cd55e52f6c2aee1fbc771
+  metadata.gz: dd4a3d7c95873a7fb999854846db84790273ad3366a018dc0e519d7708a13ec325a3a0d1b0bb4968f28cd6260dc4d72659c513513f56dfc2ec0b52ece8a9fb9d
+  data.tar.gz: 68ca70761102c30cca381a029184250a1750dc01d3c63626afe8b7ecd1929839497a8c6b55f995cef40ad8d5554b534987e1447f44eae567ae6c805cce82c2b5

data/CHANGELOG.md

@@ -1,8 +1,7 @@
 # Change Log
 
-## [Unreleased](https://github.com/lanej/cistern/tree/HEAD)
-
-[Full Changelog](https://github.com/lanej/cistern/compare/v2.5.0...HEAD)
+## [v2.6.0](https://github.com/lanej/cistern/tree/v2.6.0) (2016-07-26)
+[Full Changelog](https://github.com/lanej/cistern/compare/v2.5.0...v2.6.0)
 
 **Implemented enhancements:**
 

data/README.md

@@ -1,5 +1,6 @@
 # Cistern
 
+[![Join the chat at https://gitter.im/lanej/cistern](https://badges.gitter.im/lanej/cistern.svg)](https://gitter.im/lanej/cistern?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 [![Build Status](https://secure.travis-ci.org/lanej/cistern.png)](http://travis-ci.org/lanej/cistern)
 [![Dependencies](https://gemnasium.com/lanej/cistern.png)](https://gemnasium.com/lanej/cistern.png)
 [![Gem Version](https://badge.fury.io/rb/cistern.svg)](http://badge.fury.io/rb/cistern)
@@ -9,40 +10,11 @@ Cistern helps you consistently build your API clients and faciliates building mo
 
 ## Usage
 
-### Notice: Cistern 3.0
+### Client
 
-Cistern 3.0 will change the way Cistern interacts with your `Request`, `Collection` and `Model` classes.
+This represents the remote service that you are wrapping.  It defines the client's namespace and initialization parameters.
 
-Prior to 3.0, your `Request`, `Collection` and `Model` classes would have inherited from `<service>::Client::Request`, `<service>::Client::Collection` and `<service>::Client::Model` classes, respectively.
-
-In cistern `~> 3.0`, the default will be for `Request`, `Collection` and `Model` classes to instead include their respective `<service>::Client` modules.
-
-If you want to be forwards-compatible today, you can configure your client by using `Cistern::Client.with`
-
-```ruby
-class Blog
-  include Cistern::Client.with(interface: :module)
-end
-```
-
-Now request classes would look like:
-
-```ruby
-class Blog::GetPost
-  include Blog::Request
-
-  def real
-    "post"
-  end
-end
-```
-
-
-### Service
-
-This represents the remote service that you are wrapping. If the service name is `blog` then a good name is `Blog`.
-
-Service initialization parameters are enumerated by `requires` and `recognizes`. Parameters defined using `recognizes` are optional.
+Client initialization parameters are enumerated by `requires` and `recognizes`. Parameters defined using `recognizes` are optional.
 
 ```ruby
 # lib/blog.rb
@@ -62,8 +34,7 @@ Blog.new(hmac_id: "1", url: "http://example.org")
 Blog.new(hmac_id: "1")
 ```
 
-Cistern will define for you two classes, `Mock` and `Real`. Create the corresponding files and initialzers for your
-new service.
+Cistern will define for two namespaced classes, `Blog::Mock` and `Blog::Real`. Create the corresponding files and initialzers for your new service.
 
 ```ruby
 # lib/blog/real.rb
@@ -105,74 +76,69 @@ real.is_a?(Blog::Real) # true
 fake.is_a?(Blog::Mock) # true
 ```
 
-### Working with data
+### Requests
 
-`Cistern::Hash` contains many useful functions for working with data normalization and transformation.
+Requests are defined by subclassing `#{service}::Request`.
 
-**#stringify_keys**
+* `cistern` represents the associated `Blog` instance.
+* `#call` represents the primary entrypoint.  Invoked when calling `client#{request_method}`.
+* `#dispatch` determines which method to call. (`#mock` or `#real`)
+
+For example:
 
 ```ruby
-# anywhere
-Cistern::Hash.stringify_keys({a: 1, b: 2}) #=> {'a' => 1, 'b' => 2}
-# within a Resource
-hash_stringify_keys({a: 1, b: 2}) #=> {'a' => 1, 'b' => 2}
-```
+class Blog::UpdatePost
+  include Blog::Request
 
-**#slice**
+  def real(id, parameters)
+    cistern.connection.patch("/post/#{id}", parameters)
+  end
 
-```ruby
-# anywhere
-Cistern::Hash.slice({a: 1, b: 2, c: 3}, :a, :c) #=> {a: 1, c: 3}
-# within a Resource
-hash_slice({a: 1, b: 2, c: 3}, :a, :c) #=> {a: 1, c: 3}
-```
+  def mock(id, parameters)
+    post = cistern.data[:posts].fetch(id)
 
-**#except**
+    post.merge!(stringify_keys(parameters))
 
-```ruby
-# anywhere
-Cistern::Hash.except({a: 1, b: 2}, :a) #=> {b: 2}
-# within a Resource
-hash_except({a: 1, b: 2}, :a) #=> {b: 2}
+    response(post: post)
+  end
+end
 ```
 
+However, if you want to add some preprocessing to your request's arguments override `#call` and call `#dispatch`.  You
+can also alter the response method's signatures based on the arguments provided to `#dispatch`.
 
-**#except!**
 
 ```ruby
-# same as #except but modify specified Hash in-place
-Cistern::Hash.except!({:a => 1, :b => 2}, :a) #=> {:b => 2}
-# within a Resource
-hash_except!({:a => 1, :b => 2}, :a) #=> {:b => 2}
-```
+class Blog::UpdatePost
+  include Blog::Request
 
+  attr_reader :parameters
 
-### Requests
+  def call(post_id, parameters)
+    @parameters = stringify_keys(parameters)
+    dispatch(Integer(post_id))
+  end
 
-Requests are defined by subclassing `#{service}::Request`.
+  def real(id)
+    cistern.connection.patch("/post/#{id}", parameters)
+  end
 
-* `cistern` represents the associated `Blog` instance.
+  def mock(id)
+    post = cistern.data[:posts].fetch(id)
 
-```ruby
-class Blog::GetPost < Blog::Request
-  def real(params)
-    # make a real request
-    "i'm real"
-  end
+    post.merge!(parameters)
 
-  def mock(params)
-    # return a fake response
-    "imposter!"
+    response(post: post)
   end
 end
-
-Blog.new.get_post # "i'm real"
 ```
 
 The `#cistern_method` function allows you to specify the name of the generated method.
 
 ```ruby
-class Blog::GetPosts < Blog::Request
+class Blog::GetPosts
+  include Blog::Request
+
   cistern_method :get_all_the_posts
 
   def real(params)
@@ -264,7 +230,8 @@ Cistern attributes are designed to make your model flexible and developer friend
 For example:
 
 ```ruby
-class Blog::Post < Blog::Model
+class Blog::Post
+  include Blog::Model
   identity :id, type: :integer
 
   attribute :body
@@ -372,7 +339,8 @@ post.data.views #=> 3
 * `load` consumes an Array of data and constructs matching `model` instances
 
 ```ruby
-class Blog::Posts < Blog::Collection
+class Blog::Posts
+  include Blog::Collection
 
   attribute :count, type: :integer
 
@@ -415,7 +383,9 @@ There are two types of associations available.
 * `has_many` references a collection of resources and defines a reader / writer.
 
 ```ruby
-class Blog::Tag < Blog::Model
+class Blog::Tag
+  include Blog::Model
+
   identity :id
   attribute :author_id
 
@@ -435,7 +405,8 @@ tag.creator = blogs.author.get(name: 'phil')
 tag.attributes[:creator] #=> { 'id' => 2, 'name' => 'phil' }
 ```
 
-Foreign keys can be updated with association writing by overwriting the writer.
+Foreign keys can be updated with with the association writer by aliasing the original writer and accessing the
+underlying attributes.
 
 ```ruby
 Blog::Tag.class_eval do
@@ -505,6 +476,48 @@ class Blog
 end
 ```
 
+### Working with data
+
+`Cistern::Hash` contains many useful functions for working with data normalization and transformation.
+
+**#stringify_keys**
+
+```ruby
+# anywhere
+Cistern::Hash.stringify_keys({a: 1, b: 2}) #=> {'a' => 1, 'b' => 2}
+# within a Resource
+hash_stringify_keys({a: 1, b: 2}) #=> {'a' => 1, 'b' => 2}
+```
+
+**#slice**
+
+```ruby
+# anywhere
+Cistern::Hash.slice({a: 1, b: 2, c: 3}, :a, :c) #=> {a: 1, c: 3}
+# within a Resource
+hash_slice({a: 1, b: 2, c: 3}, :a, :c) #=> {a: 1, c: 3}
+```
+
+**#except**
+
+```ruby
+# anywhere
+Cistern::Hash.except({a: 1, b: 2}, :a) #=> {b: 2}
+# within a Resource
+hash_except({a: 1, b: 2}, :a) #=> {b: 2}
+```
+
+
+**#except!**
+
+```ruby
+# same as #except but modify specified Hash in-place
+Cistern::Hash.except!({:a => 1, :b => 2}, :a) #=> {:b => 2}
+# within a Resource
+hash_except!({:a => 1, :b => 2}, :a) #=> {:b => 2}
+```
+
+
 #### Storage
 
 Currently supported storage backends are:
@@ -588,10 +601,75 @@ class Blog::GetPost
 end
 ```
 
+## ~> 3.0
+
+### Request Dispatch
+
+Default request interface passes through `#_mock` and `#_real` depending on the client mode.
+
+```ruby
+class Blog::GetPost
+  include Blog::Request
+
+  def setup(post_id, parameters)
+    [post_id, stringify_keys(parameters)]
+  end
+
+  def _mock(*args)
+    mock(*setup(*args))
+  end
+
+  def _real(post_id, parameters)
+    real(*setup(*args))
+  end
+end
+```
+
+In cistern 3, requests pass through `#call` in both modes. `#dispatch` is responsible for determining the mode and
+calling the appropriate method.
+
+```ruby
+class Blog::GetPost
+  include Blog::Request
+
+  def call(post_id, parameters)
+    normalized_parameters = stringify_keys(parameters)
+    dispatch(post_id, normalized_parameters)
+  end
+end
+```
+
+### Client definition
+
+Default resource definition is done by inheritance.
+
+```ruby
+class Blog::Post < Blog::Model
+end
+```
+
+In cistern 3, resource definition is done by module inclusion.
+
+```ruby
+class Blog::Post
+  include Blog::Post
+end
+```
+
+Prepare for cistern 3 by using `Cistern::Client.with(interface: :module)` when defining the client.
+
+```ruby
+class Blog
+  include Cistern::Client.with(interface: :module)
+end
+```
+
 ## Examples
 
 * [zendesk2](https://github.com/lanej/zendesk2)
 * [you_track](https://github.com/lanej/you_track)
+* [ey-core](https://github.com/engineyard/core-client-rb)
+
 
 ## Releasing
 

data/lib/cistern/client.rb

@@ -44,7 +44,7 @@ module Cistern::Client
 
     if interface == :class
       Cistern.deprecation(
-        %q{class' interface is deprecated. Use `include Cistern::Client.with(interface: :module). See https://github.com/lanej/cistern#custom-architecture},
+        %q{'class' interface is deprecated. Use `include Cistern::Client.with(interface: :module). See https://github.com/lanej/cistern#custom-architecture},
         caller[2],
       )
     end
@@ -85,11 +85,19 @@ module Cistern::Client
       class Real
         def initialize(options={})
         end
+
+        def mocking?
+          false
+        end
       end
 
       class Mock
         def initialize(options={})
         end
+
+        def mocking?
+          true
+        end
       end
 
       #{interface} #{model_class}
@@ -184,14 +192,6 @@ module Cistern::Client
 
           super
         end
-
-        def _mock(*args)
-          mock(*args)
-        end
-
-        def _real(*args)
-          real(*args)
-        end
       end
     EOS
 

data/lib/cistern/request.rb

@@ -1,22 +1,35 @@
 module Cistern::Request
   include Cistern::HashSupport
 
+  module ClassMethods
+    # @deprecated Use {#cistern_method} instead
+    def service_method(name = nil)
+      Cistern.deprecation(
+        '#service_method is deprecated.  Please use #cistern_method',
+        caller[0]
+      )
+      @_cistern_method ||= name
+    end
+
+    def cistern_method(name = nil)
+      @_cistern_method ||= name
+    end
+  end
+
   def self.cistern_request(cistern, klass, name)
     unless klass.name || klass.cistern_method
       fail ArgumentError, "can't turn anonymous class into a Cistern request"
     end
 
-    cistern::Mock.module_eval <<-EOS, __FILE__, __LINE__
+    method = <<-EOS
       def #{name}(*args)
-        #{klass}.new(self)._mock(*args)
+        #{klass}.new(self).call(*args)
       end
     EOS
 
-    cistern::Real.module_eval <<-EOS, __FILE__, __LINE__
-      def #{name}(*args)
-        #{klass}.new(self)._real(*args)
-      end
-    EOS
+
+    cistern::Mock.module_eval method, __FILE__, __LINE__
+    cistern::Real.module_eval method, __FILE__, __LINE__
   end
 
   def self.service_request(*args)
@@ -41,18 +54,35 @@ module Cistern::Request
     @cistern = cistern
   end
 
-  module ClassMethods
-    # @deprecated Use {#cistern_method} instead
-    def service_method(name = nil)
+  def call(*args)
+    dispatch(*args)
+  end
+
+  def real(*)
+    raise NotImplementedError
+  end
+
+  def mock(*)
+    raise NotImplementedError
+  end
+
+  protected
+
+  # @fixme remove _{mock,real} methods and call {mock,real} directly before 3.0 release.
+  def dispatch(*args)
+    to = cistern.mocking? ? :mock : :real
+
+    legacy_method = :"_#{to}"
+
+    if respond_to?(legacy_method)
       Cistern.deprecation(
-        '#service_method is deprecated.  Please use #cistern_method',
+        '#_mock is deprecated.  Please use #mock and/or #call. See https://github.com/lanej/cistern#request-dispatch',
         caller[0]
       )
-      @_cistern_method ||= name
-    end
 
-    def cistern_method(name = nil)
-      @_cistern_method ||= name
+      public_send(legacy_method, *args)
+    else
+      public_send(to, *args)
     end
   end
 end

data/lib/cistern/singular.rb

@@ -15,6 +15,7 @@ module Cistern::Singular
     klass.send(:extend, Cistern::Attributes::ClassMethods)
     klass.send(:include, Cistern::Attributes::InstanceMethods)
     klass.send(:extend, Cistern::Model::ClassMethods)
+    klass.send(:extend, Cistern::Associations)
   end
 
   def collection

data/lib/cistern/version.rb

@@ -1,3 +1,3 @@
 module Cistern
-  VERSION = '2.6.0'
+  VERSION = '2.7.0'
 end

data/spec/request_spec.rb

@@ -1,57 +1,79 @@
 require 'spec_helper'
 
 describe 'Cistern::Request' do
-  class RequestService
-    include Cistern::Client
-
-    recognizes :key
+  before {
+    Sample.class_eval do
+      recognizes :key
+    end
 
-    class Real
+    Sample::Real.class_eval do
       attr_reader :service_args
 
       def initialize(*args)
         @service_args = args
       end
     end
-  end
+  }
 
-  # @todo Sample::Service.request
-  class ListSamples < RequestService::Request
-    cistern_method :list_all_samples
+  describe '#cistern_method' do
+    it 'remaps the client request method' do
+      class ListSamples < Sample::Request
+        cistern_method :list_all_samples
+      end
 
-    def real(*args)
-      cistern.service_args + args + ['real']
+      expect(Sample.new).to respond_to(:list_all_samples)
+      expect(Sample.new).not_to respond_to(:list_samples)
     end
+  end
 
-    def mock(*args)
-      args + ['mock']
+  it 'calls the appropriate method' do
+    class GetSamples < Sample::Request
+      def real(*args)
+        cistern.service_args + args + ['real']
+      end
+
+      def mock(*args)
+        args + ['mock']
+      end
     end
-  end
 
-  it 'should execute a new-style request' do
-    expect(RequestService.new.list_all_samples('sample1')).to eq([{}, 'sample1', 'real'])
-    expect(RequestService::Real.new.list_all_samples('sample2')).to eq(%w(sample2 real))
-    expect(RequestService::Mock.new.list_all_samples('sample3')).to eq(%w(sample3 mock))
+    expect(Sample.new.get_samples('sample1')).to eq([{}, 'sample1', 'real'])
+    expect(Sample::Real.new.get_samples('sample2')).to eq(%w(sample2 real))
+    expect(Sample::Mock.new.get_samples('sample3')).to eq(%w(sample3 mock))
 
     # service access
-    expect(RequestService.new(key: 'value').list_all_samples('stat')).to eq([{ key: 'value' }, 'stat', 'real'])
+    expect(Sample.new(key: 'value').get_samples('stat')).to eq([{ key: 'value' }, 'stat', 'real'])
   end
 
   describe 'deprecation', :deprecated do
-    class DeprecatedRequestService
-      include Cistern::Client
+    it 'calls _mock and _real if present' do
+      class Sample::ListDeprecations < Sample::Request
+        def _mock
+          :_mock
+        end
+
+        def real
+          :real
+        end
+      end
+
+      actual = Sample.new.list_deprecations
+      expect(actual).to eq(:real)
+
+      Sample.mock!
+
+      actual = Sample.new.list_deprecations
+      expect(actual).to eq(:_mock)
     end
 
     it 'responds to #service' do
-      class ListDeprecations < DeprecatedRequestService::Request
-        service_method :list_deprecations
-
+      class Sample::ListDeprecations < Sample::Request
         def real
           self
         end
       end
 
-      sample = DeprecatedRequestService.new.list_deprecations
+      sample = Sample.new.list_deprecations
       expect(sample.service).to eq(sample.cistern)
     end
   end

data/spec/singular_spec.rb

@@ -6,6 +6,8 @@ describe 'Cistern::Singular' do
       attribute :name, type: :string
       attribute :count, type: :number
 
+      belongs_to :entity, -> { cistern.settings(name: '1') }
+
       def save
         result = @@settings = attributes.merge(dirty_attributes)
 
@@ -32,6 +34,10 @@ describe 'Cistern::Singular' do
     end
   end
 
+  it 'allows associations' do
+    expect(service.settings.load.entity.name).to eq('1')
+  end
+
   it 'reloads' do
     singular = service.settings(count: 0)
 

data/spec/spec_helper.rb

@@ -16,6 +16,7 @@ RSpec.configure do |rspec|
   else
     rspec.filter_run_excluding(:coverage)
   end
+
   rspec.around(:each, :deprecated) do |example|
     original_value = Cistern.deprecation_warnings?
     Cistern.deprecation_warnings = false

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cistern
 version: !ruby/object:Gem::Version
-  version: 2.6.0
+  version: 2.7.0
 platform: ruby
 authors:
 - Josh Lane
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-26 00:00:00.000000000 Z
+date: 2016-08-10 00:00:00.000000000 Z
 dependencies: []
 description: API client framework extracted from Fog
 email: