roar 1.0.0.beta2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 10476a18173be43334b532ee1d5d88c41de38244
-  data.tar.gz: 95912cb828884fec27f2c2a74b4c95821f217c07
+  metadata.gz: 9b58dcace50d4224e36f81444ce64ca73dfec11a
+  data.tar.gz: 419929c85da4aef8a13243364b1c918acfd5312c
 SHA512:
-  metadata.gz: 8db19659880efe5b15ea0ea19091529822a2afaf4977fcfd9a9f7d9440eee0d6d5656ef0020731aec024cd67682aee24de28c394630aeab7476d54a280ee29ae
-  data.tar.gz: 22502b9bb0e66fe182f95866825dc27cc92d1be702b94ebf9313600a12d793375fc804139bdc04ca076e0f33a5418d82e1a09c5b56144ebb4997f51be85f8582
+  metadata.gz: c090f6a70e513ab5ad28155a9c21a453f0e37a289acb2af3a7ade51484d8cc1a76d0c14a02cf6343b054fb9ef2dd392dcae2383b7d219c77e43513d370369c62
+  data.tar.gz: 3253825814038580793eebb22da120b3af1ce69723d81283b65953e5b30806a91b7627ebb370de30b46440b07b749465ec2db1a9235b884b5de132becf2d4c84

data/.travis.yml

@@ -3,7 +3,7 @@ rvm:
   - 2.0
   - 2.1
   - 2.2
-gemfiles:
+gemfile:
   - gemfiles/Gemfile.representable-2.0
   - gemfiles/Gemfile.representable-2.1
 notifications:

data/CHANGES.markdown

@@ -6,6 +6,7 @@
     * `Roar::Representer::Feature::Hypermedia` --> `Roar::Hypermedia`
     * `Roar::Representer::JSON` --> `Roar::JSON`
 * Removed positional arguments for `HttpVerbs#get` and friends.
+* `HttpVerbs#get` and friends will now raise an exception when the response code is not 2xx. You can get the original response via `Roar::Transport::Error#response`. Thanks to @paulccarey for all his inspiring work and patience!
 
 ## Added
 

data/README.markdown

@@ -470,6 +470,39 @@ compound do
 end
 ```
 
+### Meta Data
+
+Meta data can be included into the rendered collection document in two ways. Please note that parsing the `meta` field is not implemented, yet, as I wasn't sure if people need it.
+
+You can define meta data on your collection object and then let Roar compile it.
+
+```ruby
+module SongsRepresenter
+  # ..
+
+  meta do
+    property :page
+    property :total
+  end
+```
+
+Your collection object has to expose those methods.
+
+```ruby
+collection.page  #=> 1
+collection.total #=> 12
+```
+
+This will render the `{"meta": {"page": 1, "total": 12}}` hash into the JSON-API document.
+
+Another way is to provide the _complete_ meta data hash when rendering. You must not define any `meta` properties in the representer when using this approach.
+
+```ruby
+collection.to_json("meta" => {page: params["page"], total: collection.size})
+```
+
+If you need more functionality (and parsing), please let us know.
+
 ### Usage
 
 As JSON-API per definition can represent singular models and collections you have two entry points.
@@ -641,6 +674,16 @@ song.get(uri: "http://localhost:4567/songs/1") do |req|
 end
 ```
 
+### Error handling
+
+In case of a non-2xx response status, `#get` and friends raise a `Roar::Transport::Error` exception. The original response can be accessed as follows.
+
+```ruby
+  song.get(uri: "http://localhost/songs1") # not-existing.
+rescue Roar::Transport::Error => exception
+  exception.response.code #=> 404
+```
+
 ## XML
 
 Roar also comes with XML support.

data/lib/roar/json/json_api.rb

@@ -26,6 +26,7 @@ module Roar
             items extend: singular, :parse_strategy => :sync
 
             representable_attrs[:resource_representer] = singular.representable_attrs[:resource_representer]
+            representable_attrs[:meta_representer]     = singular.representable_attrs[:meta_representer] # DISCUSS: do we need that?
             representable_attrs[:_wrap] = singular.representable_attrs[:_wrap]
           end
         end
@@ -99,6 +100,10 @@ module Roar
           def compound(&block)
             nested(:linked, &block)
           end
+
+          def meta(&block)
+            representable_attrs[:meta_representer] = Class.new(Roar::Decorator, &block)
+          end
         end
       end
 
@@ -111,7 +116,7 @@ module Roar
           return res if options[:only_body]
           # this is the only "dirty" part: this module is always included in the Singular document representer, when used in collection, we don't want it to do the extra work. this mechanism here might be changed soon.
 
-          to_document(res)
+          to_document(res, options)
         end
 
         def from_hash(hash, options={})
@@ -122,8 +127,9 @@ module Roar
         end
 
       private
-        def to_document(res)
-          links    = representable_attrs[:resource_representer].new(represented).to_hash # creates links: section.
+        def to_document(res, options)
+          links = render_links
+          meta  = render_meta(options)
           # FIXME: provide two different #to_document
 
           if res.is_a?(Array)
@@ -134,7 +140,8 @@ module Roar
 
           {representable_attrs[:_wrap] => res}.tap do |doc|
             doc.merge!(links)
-            doc.merge!("linked" => compound) if compound && compound.size > 0
+            doc.merge!(meta)
+            doc.merge!("linked" => compound) if compound && compound.size > 0 # FIXME: make that like the above line.
           end
         end
 
@@ -173,13 +180,26 @@ module Roar
           compound
         end
 
+        def render_links
+          representable_attrs[:resource_representer].new(represented).to_hash # creates links: section.
+        end
+
+        def render_meta(options)
+          # TODO: this will call collection.page etc, directly on the collection. we could allow using a "meta"
+          # object to hold this data.
+          # `meta call_meta: true` or something
+          return {"meta" => options["meta"]} if options["meta"]
+          return {} unless representer = representable_attrs[:meta_representer]
+          {"meta" => representer.new(represented).extend(Representable::Hash).to_hash}
+        end
+
 
         module Collection
           include Document
 
           def to_hash(options={})
             res = super(options.merge(:only_body => true))
-            to_document(res)
+            to_document(res, options)
           end
 
           def from_hash(hash, options={})

data/lib/roar/transport/net_http.rb

@@ -30,28 +30,20 @@ module Roar
       end
 
     private
-      def call(what, *args, &block)
-        options = handle_deprecated_args(args)
+      def call(what, options, &block)
         # TODO: generically handle return codes.
         Request.new(options).call(what, &block)
       end
+    end
 
-      def handle_deprecated_args(args) # TODO: remove in 1.0.
-        if args.size > 1
-          warn %{DEPRECATION WARNING: #get_uri, #post_uri, #put_uri, #delete_uri and #patch_uri no longer accept positional arguments. Please call them as follows:
-   get_uri(uri: "http://localhost/songs", as: "application/json")
-  post_uri(uri: "http://localhost/songs", as: "application/json", body: "{'id': 1}")
-Thank you and have a lovely day.}
-          return {:uri => args[0], :as => args[1]} if args.size == 2
-          return {:uri => args[0], :as => args[2], :body => args[1]}
-        end
-
-        args.first
+    # Wraps the original response from NetHttp and provides it via #response.
+    class Error < RuntimeError # TODO: raise this from Faraday, too.
+      def initialize(response)
+        @response = response
+        super("Roar error: #{response}")
       end
 
-    end
-
-    class UnauthorizedError < RuntimeError # TODO: raise this from Faraday, too.
+      attr_reader :response
     end
   end
 end

data/lib/roar/transport/net_http/request.rb

@@ -37,7 +37,7 @@ module Roar
           yield req if block_given?
 
           http.request(req).tap do |res|
-            raise UnauthorizedError if res.is_a?(Net::HTTPUnauthorized) # FIXME: make this better. # DISCUSS: abstract all that crap here?
+            handle_error!(res)
           end
         end
 
@@ -66,6 +66,11 @@ module Roar
 
           @req.basic_auth(*options[:basic_auth])
         end
+
+        def handle_error!(res)
+          status = res.code.to_i
+          raise Error.new(res) unless status >= 200 and status < 300
+        end
       end
     end
   end

data/lib/roar/version.rb

@@ -1,3 +1,3 @@
 module Roar
-  VERSION = "1.0.0.beta2"
+  VERSION = "1.0.0"
 end

data/test/http_verbs_test.rb

@@ -58,11 +58,14 @@ class HttpVerbsTest < MiniTest::Spec
           end
         end
 
-        it 'performs no HTTP error handling with NetHttpTransport' do
+        it 'returns Roar::Transport::Error for NetHttpTransport in case of non 20x' do
           @band.transport_engine = Roar::Transport::NetHTTP
-          assert_raises(MultiJson::LoadError) do
+
+          exception = assert_raises(Roar::Transport::Error) do
             @band.get(uri: 'http://localhost:4567/bands/anthrax', as: "application/json")
           end
+
+          exception.response.code.must_equal "404"
         end
       end
     end

data/test/json_api_test.rb

@@ -334,4 +334,62 @@ class JSONAPITest < MiniTest::Spec
       )
     end
   end
+
+
+  class ExplicitMeta < self
+    module Representer
+      include Roar::JSON::JSONAPI
+
+      type :songs
+      property :id
+
+      meta do
+        property :page
+      end
+    end
+
+    module Page
+      def page
+        2
+      end
+    end
+
+    let (:song) { Struct.new(:id).new(1) }
+
+    subject { [song, song].extend(Representer.for_collection).extend(Page) }
+
+    # to_json
+    it do
+      subject.to_hash.must_equal(
+        {
+          "songs"=>[{"id"=>1}, {"id"=>1}],
+          "meta" =>{"page"=>2}
+        }
+      )
+    end
+  end
+
+
+  class ImplicitMeta < self
+    module Representer
+      include Roar::JSON::JSONAPI
+
+      type :songs
+      property :id
+    end
+
+    let (:song) { Struct.new(:id).new(1) }
+
+    subject { [song, song].extend(Representer.for_collection) }
+
+    # to_json
+    it do
+      subject.to_hash("meta" => {"page" => 2}).must_equal(
+        {
+          "songs"=>[{"id"=>1}, {"id"=>1}],
+          "meta" =>{"page"=>2}
+        }
+      )
+    end
+  end
 end

data/test/net_http_transport_test.rb

@@ -47,31 +47,25 @@ class NetHTTPTransportTest < MiniTest::Spec
 
   describe "basic auth" do
     it "raises when no credentials provided" do
-      assert_raises Roar::Transport::UnauthorizedError do
+      exception = assert_raises Roar::Transport::Error do
         transport.get_uri(:uri => "http://localhost:4567/protected/bands/bodyjar", :as => "application/json")
       end
+
+      exception.response.code.must_equal "401"
     end
 
     it "raises when wrong credentials provided" do
-      assert_raises Roar::Transport::UnauthorizedError do
+      exception = assert_raises Roar::Transport::Error do
         transport.get_uri(:uri => "http://localhost:4567/protected/bands/bodyjar", :as => "application/json", :basic_auth => ["admin", "wrong--!!!--password"])
       end
+
+      exception.response.code.must_equal "401"
     end
 
     it "what" do
       transport.get_uri(:uri => "http://localhost:4567/protected/bands/bodyjar", :as => "application/json", :basic_auth => ["admin", "password"])
     end
   end
-
-  describe "deprecations" do
-    it "old GET API still works" do
-      transport.get_uri(url, as).must_match_net_response :get, url, as
-    end
-
-    it "old POST API still works" do
-      transport.post_uri(url, body, as).must_match_net_response :post, url, as, body
-    end
-  end
 end
 
 module MiniTest::Assertions

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: roar
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta2
+  version: 1.0.0
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-28 00:00:00.000000000 Z
+date: 2014-12-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: representable
@@ -221,9 +221,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.2.2