clarify 1.1.1 → 2.0.0.alpha.1

data/lib/clarify/collection_iterator.rb

@@ -0,0 +1,27 @@
+
+module Clarify
+  # Iterate over a paginated collection
+  class CollectionIterator
+    include Enumerable
+
+    def initialize(restclient, collection)
+      @restclient = restclient
+      @collection = collection
+    end
+
+    def each
+      collections.each { |collection| collection.each { |*i| yield(*i) } }
+    end
+
+    def collections
+      Enumerator.new do |y|
+        current = @collection
+        loop do
+          y << current
+          break unless current.more?
+          current = @restclient.get(current.next)
+        end
+      end
+    end
+  end
+end

data/lib/clarify/configuration.rb

@@ -1,16 +1,38 @@
+
 module Clarify
+  # A Configuration class represents the server to communicate with, and the
+  # credentials to consume. You can use multiple Configuration objects with
+  # multiple RestClient objects to support multiple accounts in the same
+  # application.
   class Configuration
-    
-    attr_accessor :api_key, :version_name, :version
+    attr_reader :api_key
+    attr_reader :server
+
+    def initialize(conf = {})
+      @api_key = conf.fetch(:api_key)
+      @server = conf.fetch(:server, 'https://api.clarify.io')
+    end
+
+    def api_key?
+      return false unless api_key
+      return false if api_key.empty?
+      true
+    end
+
+    def ssl?
+      uri.scheme == 'https'
+    end
 
-    def initialize 
-      @api_key = 'api key here'
-      @version = '1'  # latest version is default
+    def host
+      uri.host
     end
 
-    def version_name
-      "v#{@version}"
+    def port
+      uri.port
     end
 
+    def uri
+      URI(server)
+    end
   end
 end

data/lib/clarify/errors.rb

@@ -0,0 +1,22 @@
+
+module Clarify
+  class StandardError < Exception
+  end
+
+  # This Response error is to be raised when a particular Response has a status
+  # code of 401
+  class UnauthenticatedError < Clarify::StandardError
+    def initialize(response)
+      @response = response
+
+      super 'Response had code 401'
+    end
+  end
+
+  # Handles errors where we are unable to understand the response from the API.
+  class UnrecognizedResponseError < Clarify::StandardError
+    def initialize(type)
+      super "Unrecognized response class #{type}"
+    end
+  end
+end

data/lib/clarify/response.rb

@@ -0,0 +1,29 @@
+module Clarify
+  # A general purpose response which handles status code access and accessing
+  # link relations.
+  class Response
+    attr_reader :body
+    attr_reader :response
+
+    def initialize(body, response)
+      @body = body
+      @response = response
+    end
+
+    def http_status_code
+      response.code.to_i
+    end
+
+    def relation!(link)
+      url = relation(link)
+
+      fail ArgumentError, "Link '#{link}' not present" if url.nil?
+
+      url
+    end
+
+    def relation(link)
+      body.fetch('_links', {}).fetch(link, {}).fetch('href', nil)
+    end
+  end
+end

data/lib/clarify/response_factory.rb

@@ -0,0 +1,34 @@
+
+module Clarify
+  # Handles the HTTP response and returns responses. Also raises exceptions
+  # around API failures.
+  class ResponseFactory
+    def make_result(response)
+      raise_on_code!(response)
+
+      return Clarify::Responses::NoBody.new(response) if response.body.nil?
+
+      data = JSON.parse(response.body || '')
+      klass_for_class(data['_class']).new(data, response)
+    rescue KeyError
+      raise Clarify::UnrecognizedResponseError, data['_class']
+    end
+
+    def raise_on_code!(response)
+      return unless response.code.to_i == 401
+      fail Clarify::UnauthenticatedError, response
+    end
+
+    def klass_for_class(name)
+      klasses = {
+        'Collection' => Clarify::Responses::Collection,
+        'SearchCollection' => Clarify::Responses::SearchCollection,
+        'Bundle' => Clarify::Responses::Bundle,
+        'Tracks' => Clarify::Responses::Tracks,
+        'Ref' => Clarify::Response
+      }
+
+      klasses.fetch name
+    end
+  end
+end

data/lib/clarify/responses/bundle.rb

@@ -0,0 +1,11 @@
+
+module Clarify
+  module Responses
+    # Represents an individual bundle.
+    class Bundle < Clarify::Response
+      def name
+        body['name']
+      end
+    end
+  end
+end

data/lib/clarify/responses/collection.rb

@@ -0,0 +1,31 @@
+
+require 'json'
+
+module Clarify
+  module Responses
+    # A Collection represents a list of results from the API, primarily used in
+    # the Bundle list and the Search results (a SearchCollection.)
+    #
+    # A collection can be paged through using next / prev / first / last link
+    # relations.
+    class Collection < Clarify::Response
+      include Enumerable
+
+      def each
+        items.each { |i| yield i['href'] }
+      end
+
+      def items
+        body['_links']['items']
+      end
+
+      def more?
+        !self.next.nil?
+      end
+
+      def next
+        relation('next')
+      end
+    end
+  end
+end

data/lib/clarify/responses/no_body.rb

@@ -0,0 +1,13 @@
+
+module Clarify
+  module Responses
+    # The Tracks class represents a collection of tracks within a bundle. A
+    # bundle may have zero or more tracks. Iterating over a Tracks object will
+    # yield each track in the tracks resource.
+    class NoBody < Clarify::Response
+      def initialize(response)
+        super response, nil
+      end
+    end
+  end
+end

data/lib/clarify/responses/search_collection.rb

@@ -0,0 +1,18 @@
+
+module Clarify
+  module Responses
+    # A SearchCollection represents a list of search results from the API.
+    #
+    # A collection can be paged through using next / prev / first / last link
+    # relations.
+    class SearchCollection < Clarify::Responses::Collection
+      def each
+        items.each { |result, ref| yield result, ref['href'] }
+      end
+
+      def items
+        body['item_results'].zip(body['_links']['items'])
+      end
+    end
+  end
+end

data/lib/clarify/responses/tracks.rb

@@ -0,0 +1,15 @@
+
+module Clarify
+  module Responses
+    # The Tracks class represents a collection of tracks within a bundle. A
+    # bundle may have zero or more tracks. Iterating over a Tracks object will
+    # yield each track in the tracks resource.
+    class Tracks < Clarify::Response
+      include Enumerable
+
+      def each
+        body['tracks'].each { |i| yield i }
+      end
+    end
+  end
+end

data/lib/clarify/rest_client.rb

@@ -0,0 +1,129 @@
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Clarify
+  # Implement the HTTP layer. All the communication in this restclient goes over
+  # the one HTTP connection for performance. The connection is created by the
+  # input of the Configuration object which is passed in by default.
+  #
+  # This is a bit over complex, but deals with:
+  #
+  #  1. Authenticating and identifying (via UserAgent) requests ("blessing")
+  #  2. Actually calling the API over HTTP
+  #  3. Converting the resulting responses into Response objects
+  #
+  # In other words, this does too many things, but it is a start.
+  class RestClient
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+      @cached = {}
+    end
+
+    def get(url, params = {})
+      request(get_request(url, params))
+    end
+
+    def post(url, params = {})
+      request(post_request(url, params))
+    end
+
+    def put(url, params = {})
+      request(put_request(url, params))
+    end
+
+    def delete(url, params = {})
+      request(delete_request(url, params))
+    end
+
+    def get_request(url, params = {})
+      url = make_get_url(url, params)
+      Net::HTTP::Get.new(url)
+    end
+
+    def post_request(url, body = {})
+      request = Net::HTTP::Post.new(url)
+      request.set_form_data(body)
+      request
+    end
+
+    def put_request(url, body = {})
+      request = Net::HTTP::Put.new(url)
+      request.set_form_data(body)
+      request
+    end
+
+    def delete_request(url, body = {})
+      request = Net::HTTP::Delete.new(url)
+      request.set_form_data(body)
+      request
+    end
+
+    def make_get_url(url, parameters)
+      # Convert the URL to a URI object we can manipulate
+      uri = URI.parse(url)
+
+      # Code a=b to [['a', 'b']] -- this array of arrays format is used
+      # so you can represent (valid) URLs which look like:
+      # a=b&a=c via [['a', 'b'], ['a', 'c']]
+      original_params = URI.decode_www_form(uri.query.to_s)
+
+      # Now we convert the incoming URL parameters which could either look like:
+      # 1. { b: 'c' }
+      # 2. { b: ['c', 'd'] }
+      # 3. { b: :c }
+      # 4. [['b', 'c']]
+      # to consistently be in the fourth format by encoding (flexible on input)
+      # and decoding again (which always produces the fourth format.)
+      new_params = URI.decode_www_form(URI.encode_www_form(parameters))
+
+      # Merge the two arrays [['b', 'c']] and [['a', 'b']] into
+      # [['a', 'b'], ['b', 'c']] and put it into the uri object for returning
+      uri.query = URI.encode_www_form(original_params + new_params)
+
+      # Set the query to nil if the query is empty, otherwise the generated URL
+      # will have a trailing ?.
+      uri.query = nil if uri.query.empty?
+
+      uri.to_s
+    end
+
+    def request(request)
+      request = bless_request(request)
+      response = connection.request(request)
+      make_result(response)
+    end
+
+    def bless_request(request)
+      request['Authorization'] = "Bearer #{config.api_key}" if config.api_key?
+      request['User-Agent'] = user_agent
+
+      request
+    end
+
+    def user_agent
+      ruby_version = "#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}"
+      "clarify-ruby/#{Clarify::VERSION}/#{ruby_version}"
+    end
+
+    def make_result(response)
+      response_factory.make_result(response)
+    end
+
+    def response_factory
+      @response_factory ||= Clarify::ResponseFactory.new
+    end
+
+    def connection
+      unless @connection
+        @connection ||= Net::HTTP.new(config.host, config.port)
+        @connection.use_ssl = config.ssl?
+      end
+
+      @connection
+    end
+  end
+end

data/lib/clarify/version.rb

@@ -1,3 +1,5 @@
+
+# Stub for the gemspec, tick the version on each release.
 module Clarify
-  VERSION = "1.1.1"
+  VERSION = '2.0.0.alpha.1'
 end

data/spec/clarify/bundle_repository_spec.rb

@@ -0,0 +1,37 @@
+
+describe Clarify::BundleRepository do
+  let(:restclient) { double(:restclient) }
+  let(:repo) { Clarify::BundleRepository.new(restclient) }
+
+  describe '#fetch' do
+    it 'performs a get on the restclient' do
+      expect(restclient).to receive(:get).with('/v1/bundles')
+      repo.fetch
+    end
+  end
+
+  describe '#search' do
+    it 'performs a get on the restclient' do
+      expect(restclient).to receive(:get).with('/v1/search', query: 'abc')
+      repo.search 'abc'
+    end
+  end
+
+  describe '#create!' do
+    it 'performs a post on the restclient' do
+      body = { hey: :there }
+      expect(restclient).to receive(:post).with('/v1/bundles', body)
+      repo.create! body
+    end
+  end
+
+  describe '#delete!' do
+    it 'performs a delete on the restclient' do
+      bundle = double(:bundle)
+      expect(bundle).to receive(:relation!)
+        .with('self').and_return('/v1/bundle/thisone')
+      expect(restclient).to receive(:delete).with('/v1/bundle/thisone')
+      repo.delete! bundle
+    end
+  end
+end

data/spec/clarify/client_spec.rb

@@ -0,0 +1,93 @@
+
+describe Clarify::Client do
+  let(:opts) { {} }
+  let(:config) { { api_key: 'abc123' } }
+  let(:client) { Clarify::Client.new(config, opts) }
+
+  context 'with a fake restclient' do
+    let(:url) { double(:url) }
+    let(:params) { double(:params) }
+    let(:restclient) { double(:restclient) }
+    before(:each) do
+      allow(client).to receive(:restclient).and_return(restclient)
+    end
+    describe '#get' do
+      it 'calls get on the restclient' do
+        expect(restclient).to receive(:get).with(url, params)
+        client.get(url, params)
+      end
+    end
+
+    describe '#put' do
+      it 'calls put on the restclient' do
+        expect(restclient).to receive(:put).with(url, params)
+        client.put(url, params)
+      end
+    end
+
+    describe '#post' do
+      it 'calls post on the restclient' do
+        expect(restclient).to receive(:post).with(url, params)
+        client.post(url, params)
+      end
+    end
+
+    describe '#delete' do
+      it 'calls delete on the restclient' do
+        expect(restclient).to receive(:delete).with(url, params)
+        client.delete(url, params)
+      end
+    end
+  end
+
+  describe '#pager' do
+    let(:collection) { double(:collection) }
+    let(:restclient) { double(:restclient) }
+    let(:iterator_klass) { double(:iterator_klass) }
+    let(:opts) { { iterator: iterator_klass } }
+    it 'creates an iterator with the restclient' do
+      expect(client).to receive(:restclient).and_return(restclient)
+      expect(iterator_klass).to receive(:new).with(restclient, collection)
+      client.pager(collection)
+    end
+  end
+
+  describe '#bundles' do
+    let(:repo) { double(:repo) }
+    it 'calls the bundle_repository method' do
+      expect(client).to receive(:bundle_repository).and_return(repo)
+      expect(client.bundles).to eq(repo)
+    end
+  end
+
+  describe '#bundle_repository' do
+    let(:restclient) { double(:restclient) }
+    let(:bundle_klass) { double(:bundle_klass) }
+    let(:opts) { { bundle_repository: bundle_klass } }
+    it 'creates a bundle repository with the restclient' do
+      expect(client).to receive(:restclient).and_return(restclient)
+      expect(bundle_klass).to receive(:new).with(restclient)
+      client.bundle_repository
+    end
+  end
+
+  describe '#restclient' do
+    let(:configuration) { double(:configuration) }
+    let(:restclient_klass) { double(:restclient_klass) }
+    let(:opts) { { rest_client: restclient_klass } }
+    it 'creates a new restclient with the configuration' do
+      expect(client).to receive(:configuration).and_return(configuration)
+      expect(restclient_klass).to receive(:new).with(configuration)
+      client.restclient
+    end
+  end
+
+  describe '#configuration' do
+    let(:config_klass) { double(:config_klass) }
+    let(:opts) { { configuration: config_klass } }
+    it 'should create a new Configuration from the opts' do
+      expect(config_klass).to receive(:new).with(config)
+      client.configuration
+    end
+  end
+end