the86-client 0.0.8 → 1.0.0

data/.gitignore

@@ -15,3 +15,6 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+
+# Exuberant ctags
+/tags

data/lib/the86-client.rb

@@ -3,6 +3,7 @@
   connection
   errors
   oauth_bearer_authorization
+  response
 
   resource
   resource_collection

data/lib/the86-client/connection.rb

@@ -24,6 +24,7 @@ module The86
         end
       end
 
+      # Insert a Faraday middleware at the top of the chain.
       def prepend(*parameters)
         @faraday.builder.insert(0, *parameters)
       end
@@ -43,6 +44,11 @@ module The86
         dispatch(:post, options)
       end
 
+      private
+
+      # Dispatch the HTTP request.
+      # Returns the The86::Client::Response which contains the
+      # HTTP status code, headers and decoded response body.
       def dispatch(method, options)
         path = options.fetch(:path)
         parameters = options[:parameters]
@@ -50,17 +56,21 @@ module The86
 
         if parameters
           path = Addressable::URI.parse(path).tap do |uri|
-            uri.query_values = parameters
+            uri.query_values = (uri.query_values || {}).merge(parameters)
           end.to_s
         end
 
         headers = @faraday.headers.merge(options[:headers] || {})
         response = @faraday.run_request(method, path, data, headers)
+
         assert_http_status(response, options[:status])
-        response.body
-      end
 
-      private
+        ::The86::Client::Response.new(
+          response.status,
+          response.headers,
+          response.body
+        )
+      end
 
       def url
         "%s://%s/api/v1" % [ Client.scheme, Client.domain ]

data/lib/the86-client/conversation.rb

@@ -3,6 +3,7 @@ module The86::Client
 
     attribute :id, Integer
     attribute :content, String # For creating new Conversation.
+    attribute :bumped_at, DateTime
     attribute :created_at, DateTime
     attribute :updated_at, DateTime
 

data/lib/the86-client/errors.rb

@@ -16,5 +16,8 @@ module The86
     class ValidationFailed < Error
     end
 
+    class PaginationError < Error
+    end
+
   end
 end

data/lib/the86-client/resource.rb

@@ -78,7 +78,7 @@ module The86
         self.attributes = connection.get(
           path: resource_path,
           status: 200
-        )
+        ).data
         self
       end
 
@@ -87,7 +87,7 @@ module The86
           path: resource_path,
           data: attributes,
           status: 200
-        )
+        ).data
       end
 
       def sendable_attributes
@@ -112,7 +112,7 @@ module The86
           path: self.class.collection_path(@parent),
           data: sendable_attributes,
           status: 201
-        )
+        ).data
       end
 
       def save_existing
@@ -120,7 +120,7 @@ module The86
           path: resource_path,
           data: sendable_attributes,
           status: 200
-        )
+        ).data
       end
 
       def connection

data/lib/the86-client/resource_collection.rb

@@ -1,3 +1,5 @@
+require "addressable/uri"
+
 module The86::Client
   class ResourceCollection
 
@@ -6,9 +8,7 @@ module The86::Client
     # Connection is a The86::Client::Connection instance.
     # Path is the API-relative path, e.g. "users".
     # Klass is class of each record in the collection, e.g. User
-    # Attributes is a Hash of attributes common to all items in collection,
-    #   and not fetched in HTTP response, e.g. parent items.
-    #   e.g. for conversations: { site: Site.new(slug: "...") }
+    # Parent is the parent resource of this collection and its items.
     # Records is an array of hashes, for pre-populating the collection.
     #   e.g. when an API response contains collections of child resources.
     def initialize(connection, path, klass, parent, records = nil)
@@ -30,7 +30,12 @@ module The86::Client
     attr_writer :parameters
 
     def with_parameters(parameters)
-      dup.tap do |collection|
+      self.class.new(
+        @connection,
+        @path,
+        @klass,
+        @parent
+      ).tap do |collection|
         collection.parameters = parameters
       end
     end
@@ -54,10 +59,31 @@ module The86::Client
       end
     end
 
+    # Load the next page of records, based on the pagination header, e.g.
+    # Link: <http://example.org/api/v1/sites/a/conversations?bumped_before=time>; rel="next"
+    def more
+      if more?
+        self.class.new(
+          @connection,
+          Addressable::URI.parse(http_response.links[:next]).request_uri,
+          @klass,
+          @parent
+        )
+      else
+        raise PaginationError, %{Collection has no 'Link: <url>; rel="next"' header}
+      end
+    end
+
+    # Whether there are more resources on a subsequent page.
+    # See documentation for #more method.
+    def more?
+      http_response.links.key? :next
+    end
+
     # Cache array representation.
     # Save building Resources for each record multiple times.
     def to_a
-      @_to_a = super
+      @_to_a ||= super
     end
 
     def [](index)
@@ -66,13 +92,17 @@ module The86::Client
 
     private
 
-    def records
-      @records ||= @connection.get(
+    def http_response
+      @_http_response ||= @connection.get(
         path: @path,
         parameters: @parameters,
         status: 200
       )
     end
 
+    def records
+      @records || http_response.data
+    end
+
   end
 end

data/lib/the86-client/response.rb

@@ -0,0 +1,31 @@
+module The86::Client
+
+  # Representation of an HTTP response.
+  class Response
+
+    # status: The numeric HTTP status.
+    # headers: Hash of HTTP response headers.
+    # data: The decoded body of the response.
+    def initialize(status, headers, data)
+      @status = status
+      @headers = headers
+      @data = data
+    end
+
+    attr_reader :status
+    attr_reader :headers
+    attr_reader :data
+
+    # See: http://tools.ietf.org/html/rfc5988
+    def links
+      @_links ||= {}.tap do |links|
+        Array(headers["Link"] || headers["link"]).map do |link|
+          link.match %r{\A<([^>]+)>;\s*rel="([^"]+)"\z}
+        end.compact.each do |match|
+          links[match[2].downcase.to_sym] = match[1]
+        end
+      end
+    end
+
+  end
+end

data/lib/the86-client/version.rb

@@ -1,5 +1,5 @@
 module The86
   module Client
-    VERSION = "0.0.8"
+    VERSION = "1.0.0"
   end
 end

data/spec/conversations_spec.rb

@@ -36,6 +36,28 @@ module The86::Client
         c.id.must_equal 10
         c.site.must_equal site
       end
+
+      it "handles pagination headers" do
+        url = "#{conversations_url}?limit=2"
+        next_url = "#{url}&bumped_before=timestamp"
+        expect_get_conversations(
+          url: basic_auth_url(url),
+          response_body: [{id: 1}, {id: 2}],
+          response_headers: {"Link" => %{<#{next_url}>; rel="next"}}
+        )
+        expect_get_conversations(
+          url: basic_auth_url(next_url),
+          response_body: [{id: 3}, {id: 4}],
+        )
+        page1 = site.conversations.with_parameters(limit: 2)
+        page1.more?.must_equal true
+
+        page2 = page1.more
+        page2.more?.must_equal false
+
+        page1.map(&:id).must_equal([1,2])
+        page2.map(&:id).must_equal([3,4])
+      end
     end
 
     describe "creating conversations" do
@@ -64,7 +86,7 @@ module The86::Client
     describe "finding a conversation" do
       it "gets the conversation, loads data into the resource" do
         expect_request(
-          url: "https://user:pass@example.org/api/v1/sites/test/conversations/4",
+          url: basic_auth_url("https://example.org/api/v1/sites/test/conversations/4"),
           method: :get,
           status: 200,
           response_body: {id: 4, posts: [{id: 8, content: "A post."}]},
@@ -77,8 +99,9 @@ module The86::Client
 
     describe "hiding and unhiding a conversation" do
       let(:conversation) { site.conversations.build(id: 2) }
-      let(:oauth_url) { "#{conversations_url}/2" }
-      let(:basic_auth_url) { oauth_url.sub("//", "//user:pass@") }
+      let(:user_auth_url) { "#{conversations_url}/2" }
+      let(:site_auth_url) { user_auth_url.sub("//", "//user:pass@") }
+      let(:site_auth_url) { basic_auth_url(user_auth_url) }
       let(:headers) { Hash.new }
       def expectation(url, hidden_param)
         {
@@ -92,20 +115,20 @@ module The86::Client
       end
       describe "without oauth" do
         it "patches the conversation as hidden_by_site when no oauth_token" do
-          expect_request(expectation(basic_auth_url, hidden_by_site: true))
+          expect_request(expectation(site_auth_url, hidden_by_site: true))
           conversation.hide
 
-          expect_request(expectation(basic_auth_url, hidden_by_site: false))
+          expect_request(expectation(site_auth_url, hidden_by_site: false))
           conversation.unhide
         end
       end
       describe "with oauth" do
         let(:headers) { {"Authorization" => "Bearer secret"} }
         it "patches the conversation as hidden_by_user when oauth_token present" do
-          expect_request(expectation(oauth_url, hidden_by_user: true))
+          expect_request(expectation(user_auth_url, hidden_by_user: true))
           conversation.hide(oauth_token: "secret")
 
-          expect_request(expectation(oauth_url, hidden_by_user: false))
+          expect_request(expectation(user_auth_url, hidden_by_user: false))
           conversation.unhide(oauth_token: "secret")
         end
       end
@@ -113,12 +136,15 @@ module The86::Client
 
     def expect_get_conversations(options)
       expect_request({
-        url: conversations_url.sub("//", "//user:pass@"),
+        url: basic_auth_url(conversations_url),
         method: :get,
         status: 200,
       }.merge(options))
     end
 
+    def basic_auth_url(url)
+      url.sub("//", "//user:pass@")
+    end
   end
 
 end

data/spec/response_spec.rb

@@ -0,0 +1,28 @@
+require_relative "spec_helper"
+
+module The86::Client
+  describe Response do
+
+    it "stores status, headers, data" do
+      r = Response.new(201, {"X-Test" => "test"}, {id: 4})
+      r.status.must_equal 201
+      r.headers.must_equal("X-Test" => "test")
+      r.data.must_equal(id: 4)
+    end
+
+    describe "#links" do
+      let(:response) { Response.new(200, {"Link" => links}, nil) }
+      let(:links) { [
+        %{<https://example.org/page3>; rel="next"},
+        %{<http://example.org/page1?a=b>; rel="prev"},
+      ] }
+
+      it "exposes RFC 5988 link headers" do
+        response.links[:next].must_equal "https://example.org/page3"
+        response.links[:prev].must_equal "http://example.org/page1?a=b"
+        response.links[:test].must_equal nil
+      end
+    end
+
+  end
+end

data/spec/support/webmock.rb

@@ -26,8 +26,9 @@ module RequestExpectations
     parameters = options[:parameters]
     method = options.fetch(:method)
     request_body = options[:request_body]
-    response_body = options[:response_body]
     request_headers = options[:request_headers]
+    response_body = options[:response_body]
+    response_headers = options[:response_headers]
 
     if parameters
       url = Addressable::URI.parse(url).tap do |url|
@@ -41,6 +42,7 @@ module RequestExpectations
 
     response = {status: options[:status] || 200}
     response[:body] = JSON.generate(response_body) if response_body
+    response[:headers] = response_headers if response_headers
 
     stub_and_assert_request(method, url).
       with(request).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: the86-client
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-09 00:00:00.000000000 Z
+date: 2012-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -227,6 +227,7 @@ files:
 - lib/the86-client/post.rb
 - lib/the86-client/resource.rb
 - lib/the86-client/resource_collection.rb
+- lib/the86-client/response.rb
 - lib/the86-client/site.rb
 - lib/the86-client/user.rb
 - lib/the86-client/version.rb
@@ -235,6 +236,7 @@ files:
 - spec/post_spec.rb
 - spec/posts_spec.rb
 - spec/resource_spec.rb
+- spec/response_spec.rb
 - spec/spec_helper.rb
 - spec/support/webmock.rb
 - spec/user_spec.rb
@@ -270,6 +272,7 @@ test_files:
 - spec/post_spec.rb
 - spec/posts_spec.rb
 - spec/resource_spec.rb
+- spec/response_spec.rb
 - spec/spec_helper.rb
 - spec/support/webmock.rb
 - spec/user_spec.rb