lurch 0.1.0

data/lib/lurch/store.rb

@@ -0,0 +1,149 @@
+module Lurch
+  class Store
+    def initialize(url, options = {})
+      @config = StoreConfiguration.new(options)
+      @client = Client.new(url, @config)
+      @store = Hash.new { |hash, key| hash[key] = {} }
+    end
+
+    def from(type)
+      query.type(type)
+    end
+    alias to from
+
+    def peek(type, id)
+      stored_resource = resource_from_store(type, id.to_s)
+      return nil if stored_resource.nil?
+      Resource.new(self, stored_resource.type, stored_resource.id)
+    end
+
+    def save(changeset, query = {})
+      return insert(changeset) if changeset.id.nil?
+      url = uri_builder.resource_uri(changeset.type, changeset.id, query)
+
+      document = @client.patch(url, payload_builder.build(changeset))
+      process_document(document)
+    rescue Errors::JSONApiError => err
+      changeset.errors = err.errors
+      raise err
+    end
+
+    def insert(changeset, query = {})
+      return save(changeset) unless changeset.id.nil?
+      url = uri_builder.resources_uri(changeset.type, query)
+
+      document = @client.post(url, payload_builder.build(changeset))
+      process_document(document)
+    rescue Errors::JSONApiError => err
+      changeset.errors = err.errors
+      raise err
+    end
+
+    def delete(resource, query = {})
+      url = uri_builder.resource_uri(resource.type, resource.id, query)
+      @client.delete(url)
+
+      remove(resource)
+      true
+    end
+
+    # add resource(s) to a has many relationship
+    def add_related(resource, relationship_key, related_resources)
+      modify_relationship(:post, resource, relationship_key, related_resources)
+    end
+
+    # remove resource(s) from a has many relationship
+    def remove_related(resource, relationship_key, related_resources)
+      modify_relationship(:delete, resource, relationship_key, related_resources)
+    end
+
+    # replace resource(s) for a has many or has one relationship
+    def update_related(resource, relationship_key, related_resources)
+      modify_relationship(:patch, resource, relationship_key, related_resources)
+    end
+
+    # @private
+    def load_from_url(url)
+      document = @client.get(url)
+      process_document(document)
+    end
+
+    # @private
+    def resource_from_store(type, id)
+      normalized_type = Inflector.decode_type(type)
+      @store[normalized_type][id]
+    end
+
+    # @private
+    def query
+      Query.new(self, inflector)
+    end
+
+  private
+
+    def inflector
+      @inflector ||= Inflector.new(@config.inflection_mode, @config.types_mode)
+    end
+
+    def uri_builder
+      @uri_builder ||= URIBuilder.new(inflector)
+    end
+
+    def payload_builder
+      @payload_builder ||= PayloadBuilder.new(inflector)
+    end
+
+    def process_document(document)
+      stored_resources = store_resources(document)
+      resources = stored_resources.map do |stored_resource|
+        Resource.new(self, stored_resource.type, stored_resource.id)
+      end
+
+      if document["data"].is_a?(Array)
+        paginator = pagination_links?(document) ? Paginator.new(self, document, inflector, @config) : nil
+        Collection.new(resources, paginator)
+      else
+        resources.first
+      end
+    end
+
+    def push(stored_resource)
+      @store[stored_resource.type][stored_resource.id] = stored_resource
+    end
+
+    def remove(resource)
+      @store[resource.type].delete(resource.id)
+    end
+
+    def store_resources(document)
+      primary_data = Lurch.to_a(document["data"])
+
+      primary_stored_resources = primary_data.map do |resource_object|
+        push(StoredResource.new(self, resource_object))
+      end
+
+      Lurch.to_a(document["included"]).each do |resource_object|
+        push(StoredResource.new(self, resource_object))
+      end
+
+      primary_stored_resources
+    end
+
+    def modify_relationship(method, resource, relationship_key, related_resources)
+      url = uri_builder.relationship_uri(resource.type, resource.id, relationship_key)
+      payload = payload_builder.build(related_resources, true)
+      @client.send(method, url, payload)
+      true
+    end
+
+    def pagination_links?(document)
+      links = document["links"]
+      links && (
+        links["first"] ||
+        links["last"] ||
+        links["next"] ||
+        links["prev"]
+      )
+    end
+  end
+end

data/lib/lurch/store_configuration.rb

@@ -0,0 +1,27 @@
+module Lurch
+  class StoreConfiguration
+    def initialize(options)
+      @options = options
+    end
+
+    def authorization
+      @options[:authorization]
+    end
+
+    def inflection_mode
+      @options[:inflection_mode] || :dasherize
+    end
+
+    def types_mode
+      @options[:types_mode] || :pluralize
+    end
+
+    def pagination_record_count_key
+      @options[:pagination_record_count_key] || :record_count
+    end
+
+    def pagination_page_count_key
+      @options[:pagination_page_count_key] || :page_count
+    end
+  end
+end

data/lib/lurch/stored_resource.rb

@@ -0,0 +1,63 @@
+module Lurch
+  class StoredResource
+    def initialize(store, resource_object)
+      @store = store
+      @resource_object = resource_object
+    end
+
+    def id
+      @id ||= @resource_object["id"]
+    end
+
+    def type
+      @type ||= Inflector.decode_type(@resource_object["type"])
+    end
+
+    def attributes
+      fixed_attributes
+    end
+
+    def relationships
+      fixed_relationships
+    end
+
+    def attribute?(name)
+      fixed_attributes.key?(name.to_sym)
+    end
+
+    def attribute(name)
+      fixed_attributes[name.to_sym]
+    end
+
+    def relationship?(name)
+      fixed_relationships.key?(name.to_sym)
+    end
+
+    def relationship(name)
+      fixed_relationships[name.to_sym]
+    end
+
+  private
+
+    def fixed_attributes
+      @fixed_attributes ||= resource_attributes.each_with_object({}) do |(key, value), hash|
+        hash[Inflector.decode_key(key)] = value
+      end
+    end
+
+    def fixed_relationships
+      @fixed_relationships ||= resource_relationships.each_with_object({}) do |(key, value), hash|
+        relationship_key = Inflector.decode_key(key)
+        hash[relationship_key] = Relationship.from_document(@store, relationship_key, value)
+      end
+    end
+
+    def resource_attributes
+      @resource_object["attributes"] || {}
+    end
+
+    def resource_relationships
+      @resource_object["relationships"] || []
+    end
+  end
+end

data/lib/lurch/uri_builder.rb

@@ -0,0 +1,32 @@
+module Lurch
+  class URIBuilder
+    def initialize(inflector)
+      @inflector = inflector
+    end
+
+    def resources_uri(type, query = "")
+      resource = inflector.encode_type(type)
+      uri = ::URI.parse(resource)
+      uri.query = query unless query.empty?
+      uri.to_s
+    end
+
+    def resource_uri(type, id, query = "")
+      resource = inflector.encode_type(type)
+      uri = ::URI.parse("#{resource}/#{id}")
+      uri.query = query unless query.empty?
+      uri.to_s
+    end
+
+    def relationship_uri(type, id, relationship_key)
+      resource = inflector.encode_type(type)
+      relationship = inflector.encode_key(relationship_key)
+      uri = ::URI.parse("#{resource}/#{id}/relationships/#{relationship}")
+      uri.to_s
+    end
+
+  private
+
+    attr_reader :inflector
+  end
+end

data/lib/lurch/version.rb

@@ -0,0 +1,3 @@
+module Lurch
+  VERSION = "0.1.0".freeze
+end

data/lib/lurch.rb

@@ -0,0 +1,65 @@
+require "uri"
+
+require "inflecto"
+require "faraday"
+require "typhoeus"
+require "typhoeus/adapters/faraday"
+
+require "lurch/configuration"
+require "lurch/logger"
+require "lurch/inflector"
+
+require "lurch/middleware/json_api_request"
+require "lurch/middleware/json_api_response"
+
+require "lurch/error"
+require "lurch/errors/json_api_error"
+require "lurch/errors/bad_request"
+require "lurch/errors/unauthorized"
+require "lurch/errors/forbidden"
+require "lurch/errors/not_found"
+require "lurch/errors/conflict"
+require "lurch/errors/unprocessable_entity"
+require "lurch/errors/server_error"
+require "lurch/errors/not_loaded"
+require "lurch/errors/relationship_not_loaded"
+require "lurch/errors/resource_not_loaded"
+
+require "lurch/stored_resource"
+require "lurch/paginator"
+require "lurch/collection"
+require "lurch/relationship"
+require "lurch/relationship/linked"
+require "lurch/relationship/has_one"
+require "lurch/relationship/has_many"
+require "lurch/resource"
+
+require "lurch/uri_builder"
+require "lurch/query_builder"
+require "lurch/payload_builder"
+require "lurch/query"
+require "lurch/changeset"
+require "lurch/client"
+require "lurch/store_configuration"
+require "lurch/store"
+
+require "lurch/railtie" if defined?(Rails)
+
+module Lurch
+  def self.to_a(value)
+    return [] if value.nil?
+    value.is_a?(Array) ? value : [value]
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.reset_configuration
+    @configuration = Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+end

data/lurch.gemspec

@@ -0,0 +1,26 @@
+require File.expand_path("../lib/lurch/version", __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name          = "lurch"
+  gem.version       = Lurch::VERSION
+  gem.summary       = "A simple Ruby JSON API client"
+  gem.description   = "A client library for interacting with JSON API servers, based on http://jsonapi.org/ version 1.0."
+  gem.homepage      = "https://github.com/peek-travel/lurch"
+  gem.authors       = ["Chris Dosé"]
+  gem.email         = "chris@peek.com"
+  gem.license       = "MIT"
+
+  gem.files         = `git ls-files`.split($RS)
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency("faraday", "< 1.0")
+  gem.add_dependency("inflecto", "~> 0.0")
+  gem.add_dependency("typhoeus", "< 2.0")
+
+  gem.add_development_dependency("codecov", "~> 0.1")
+  gem.add_development_dependency("minitest", "~> 5.9")
+  gem.add_development_dependency("pry", "~> 0.10")
+  gem.add_development_dependency("rake", "~> 12.2")
+  gem.add_development_dependency("rubocop", "~> 0.43")
+  gem.add_development_dependency("webmock", "~> 3.1")
+end

data/test/helpers/lurch_test.rb

@@ -0,0 +1,40 @@
+module LurchTest
+  def setup
+    # TODO: figure out how to run test suite multiple times with different setup, so we don't randomize like this
+    inflection_mode = [:dasherize, :underscore].sample
+    types_mode = [:pluralize, :singularize].sample
+
+    @url = "http://example.com/api"
+    @store = Lurch::Store.new(@url, inflection_mode: inflection_mode, types_mode: types_mode)
+    @inflector = Lurch::Inflector.new(inflection_mode, types_mode)
+    @response_factory = ResponseFactory.new(@inflector, @url)
+  end
+
+  def person_type
+    @inflector.encode_type(:person)
+  end
+
+  def phone_number_type
+    @inflector.encode_type(:phone_number)
+  end
+
+  def stub_get(path, response)
+    stub_req(:get, path, response)
+  end
+
+  def stub_patch(path, response)
+    stub_req(:patch, path, response)
+  end
+
+  def stub_post(path, response)
+    stub_req(:post, path, response)
+  end
+
+  def stub_delete(path, response)
+    stub_req(:delete, path, response)
+  end
+
+  def stub_req(method, path, response)
+    stub_request(method, "#{@url}/#{path}").to_return(response)
+  end
+end

data/test/helpers/response_factory.rb

@@ -0,0 +1,193 @@
+class ResponseFactory
+  def initialize(inflector, url)
+    @inflector = inflector
+    @url = url
+  end
+
+  def no_content_response
+    header(:no_content)
+  end
+
+  def unauthorized_response
+    header(:unauthorized) + errors_document([401, "Unauthorized"])
+  end
+
+  def forbidden_response
+    header(:forbidden) + errors_document([403, "Forbidden"])
+  end
+
+  def not_found_response
+    header(:not_found) + errors_document([404, "Not Found"])
+  end
+
+  def unprocessable_entity_response(message)
+    header(:unprocessable_entity) + errors_document([422, message])
+  end
+
+  def server_error_response
+    header(:server_error) + errors_document([500, "Internal Server Error"])
+  end
+
+  def person_response(id, name, phone_numbers_args = nil, code: :ok, include_phone_numbers: true)
+    included = phone_numbers_args && include_phone_numbers ? phone_numbers_args.map { |args| phone_number_data(*args) } : []
+    phone_number_ids = phone_numbers_args ? phone_numbers_args.map(&:first) : nil
+    header(code) + document(person(id, name, phone_number_ids), included)
+  end
+
+  def people_response(*params, code: :ok)
+    header(code) + document(people(*params))
+  end
+
+  def paginated_people_response(per_page, page, pages)
+    first = per_page * (page - 1) + 1
+    last = first - 1 + per_page
+    params = (first..last).map { |i| [i.to_s, "Person#{i}"] }
+
+    meta = {record_count: pages * per_page, page_count: pages}
+
+    links = {
+      first: "#{@url}/#{@inflector.encode_type(:person)}?page[number]=1&page[size]=#{per_page}",
+      last: "#{@url}/#{@inflector.encode_type(:person)}?page[number]=#{pages}&page[size]=#{per_page}"
+    }
+    links[:next] = "#{@url}/#{@inflector.encode_type(:person)}?page[number]=#{page + 1}&page[size]=#{per_page}" if page < pages
+    links[:prev] = "#{@url}/#{@inflector.encode_type(:person)}?page[number]=#{page - 1}&page[size]=#{per_page}" if page > 1
+
+    header(:ok) + document(people(*params), [], meta, links)
+  end
+
+  def phone_number_response(id, name, number, contact_args = nil, code: :ok)
+    included = contact_args ? [person_data(*contact_args)] : []
+    contact_id = contact_args ? contact_args.first : nil
+    header(code) + document(phone_number(id, name, number, contact_id), included)
+  end
+
+  def phone_numbers_response(*params, code: :ok)
+    header(code) + document(phone_numbers(*params))
+  end
+
+private
+
+  def person(*args)
+    data(person_data(*args))
+  end
+
+  def people(*params)
+    data(params.map { |args| person_data(*args) })
+  end
+
+  def person_data(id, name, phone_number_ids = nil)
+    {
+      id: id,
+      type: @inflector.encode_type(:person),
+      attributes: {
+        name: name,
+        email_address: "#{name.downcase}@example.com"
+      },
+      relationships: {
+        phone_numbers: if phone_number_ids
+          {
+            data: ids(:phone_number, phone_number_ids)
+          }
+        else
+          {
+            links: {
+              related: "#{@url}/#{@inflector.encode_type(:person)}/#{id}/#{@inflector.encode_key(:phone_numbers)}"
+            }
+          }
+        end
+      }
+    }
+  end
+
+  def phone_number(*args)
+    data(phone_number_data(*args))
+  end
+
+  def phone_numbers(*params)
+    data(params.map { |args| phone_number_data(*args) })
+  end
+
+  def phone_number_data(id, name, phone_number, contact_id = nil)
+    {
+      id: id,
+      type: @inflector.encode_type(:phone_number),
+      attributes: {
+        name: name,
+        phone_number: phone_number
+      },
+      relationships: {
+        contact: if contact_id
+          {
+            data: id(:person, contact_id)
+          }
+        else
+          {
+            links: {
+              related: "#{@url}/#{@inflector.encode_type(:phone_number)}/#{id}/contact"
+            }
+          }
+        end
+      }
+    }
+  end
+
+  def id(type, id)
+    {type: @inflector.encode_type(type), id: id.to_s}
+  end
+
+  def ids(type, ids)
+    ids.map { |i| id(type, i) }
+  end
+
+  def document(doc, included = [], meta = nil, links = nil)
+    out = {jsonapi: {version: "1.0"}}
+    out[:meta] = encode_value(meta) if meta
+    out[:links] = links if links
+    out = out.merge(doc)
+    out[:included] = included unless included.empty?
+
+    JSON.dump(out)
+  end
+
+  def errors_document(*args)
+    JSON.dump(
+      errors: args.map do |(status, detail)|
+        {
+          status: status,
+          detail: detail
+        }
+      end
+    )
+  end
+
+  def data(data)
+    {data: encode_value(data)}
+  end
+
+  CODES = {
+    ok: "200 OK".freeze,
+    created: "201 Created".freeze,
+    no_content: "204 No Content".freeze,
+    unauthorized: "401 Unauthorized".freeze,
+    forbidden: "403 Forbidden".freeze,
+    not_found: "404 Not Found".freeze,
+    unprocessable_entity: "422 Unprocessable Entity".freeze,
+    server_error: "500 Internal Server Error".freeze
+  }.freeze
+
+  def header(code)
+    "HTTP/1.1 #{CODES[code]}\nContent-Type: application/vnd.api+json\n\n"
+  end
+
+  def encode_value(value)
+    if value.is_a?(Hash)
+      value.each_with_object({}) do |(k, v), obj|
+        obj[@inflector.encode_key(k)] = encode_value(v)
+      end
+    elsif value.is_a?(Array)
+      value.map { |v| encode_value(v) }
+    else
+      value
+    end
+  end
+end

data/test/lurch/test_configuration.rb

@@ -0,0 +1,20 @@
+require_relative "../test_helper"
+
+class TestConfiguration < Minitest::Test
+  include LurchTest
+
+  def test_configuration
+    assert_kind_of Logger, Lurch.configuration.logger
+    refute Lurch.configuration.log_payloads
+
+    Lurch.configure do |config|
+      config.log_payloads = true
+    end
+
+    assert Lurch.configuration.log_payloads
+
+    Lurch.reset_configuration
+
+    refute Lurch.configuration.log_payloads
+  end
+end

data/test/lurch/test_create_resources.rb

@@ -0,0 +1,55 @@
+require_relative "../test_helper"
+
+class TestCreateResources < Minitest::Test
+  include LurchTest
+
+  def test_post_new_resource_to_server_using_store
+    stub_post(person_type, @response_factory.person_response("3", "Carol", code: :created))
+
+    changeset = Lurch::Changeset.new(:person, name: "Carol")
+    person = @store.insert(changeset)
+
+    assert_requested :post, "#{@url}/#{person_type}", body: "{\"data\":{\"type\":\"#{person_type}\",\"attributes\":{\"name\":\"Carol\"}}}"
+    assert_equal "3", person.id
+    assert_equal "Carol", person.name
+  end
+
+  def test_post_new_resource_to_server_using_query
+    stub_post(person_type, @response_factory.person_response("3", "Carol", code: :created))
+
+    changeset = Lurch::Changeset.new(:person, name: "Carol")
+    person = @store.to(:people).insert(changeset)
+
+    assert_requested :post, "#{@url}/#{person_type}", body: "{\"data\":{\"type\":\"#{person_type}\",\"attributes\":{\"name\":\"Carol\"}}}"
+    assert_equal "3", person.id
+    assert_equal "Carol", person.name
+  end
+
+  def test_post_new_resource_to_server_with_relationship_to_existing_resources
+    stub_get("#{phone_number_type}/1", @response_factory.phone_number_response("1", "Cell", "111-222-3344"))
+    stub_post(person_type, @response_factory.person_response("3", "Carol", code: :created))
+
+    phone_number = @store.from(:phone_numbers).find("1")
+
+    changeset = Lurch::Changeset.new(:person, name: "Carol")
+    changeset.set_related(:phone_numbers, [phone_number])
+    person = @store.insert(changeset)
+
+    assert_requested :post, "#{@url}/#{person_type}", body: "{\"data\":{\"type\":\"#{person_type}\",\"attributes\":{\"name\":\"Carol\"},\"relationships\":{\"#{@inflector.encode_key(:phone_numbers)}\":{\"data\":[{\"id\":\"1\",\"type\":\"#{phone_number_type}\"}]}}}}"
+    assert_equal "3", person.id
+    assert_equal "Carol", person.name
+  end
+
+  def test_validation_errors_when_posting_new_resource
+    stub_post(person_type, @response_factory.unprocessable_entity_response("name - can't be blank"))
+
+    changeset = Lurch::Changeset.new(:person, name: "")
+
+    err = assert_raises(Lurch::Errors::UnprocessableEntity) { @store.insert(changeset) }
+
+    assert_requested :post, "#{@url}/#{person_type}", body: "{\"data\":{\"type\":\"#{person_type}\",\"attributes\":{\"name\":\"\"}}}"
+    assert_equal "422: name - can't be blank", err.message
+    assert_equal 422, changeset.errors.first.status
+    assert_equal "name - can't be blank", changeset.errors.first.detail
+  end
+end