lurch 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 41ee4ddf20b095a7e02065c4e5a7f6d4fc1d1dbc
+  data.tar.gz: 915497d9093ad580cc406a0c236fcd4b27029378
+SHA512:
+  metadata.gz: 42109bc7dda4b0b912b50176a90c8c2519b1e0978a5e7588144a261cff7bd42f078c2ce368d05246d7a77d266cced02f1db37399a867fa9ca0e694200b3b466c
+  data.tar.gz: ee3fb80f1f7b6ca88b62ae469348356db96ebd33a3558a1b1badf038624648950ee7e27e089128f9507bdb2cb83c0ae3e0b97beefc0943e9f1f0def3c8e91b88

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-pro

data/.gitignore

@@ -0,0 +1,4 @@
+Gemfile.lock
+*.gem
+spec/examples.txt
+coverage

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,29 @@
+AllCops:
+  TargetRubyVersion: 2.1
+  Exclude:
+    - 'test/**/*'
+    - 'vendor/**/*'
+
+Layout/AccessModifierIndentation:
+  EnforcedStyle: outdent
+
+Documentation:
+  Enabled: false
+
+Metrics/LineLength:
+  Max: 160
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/DoubleNegation:
+  Enabled: false
+
+Style/ParallelAssignment:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 2.1
+  - 2.2
+  - 2.3
+  - 2.4
+cache: bundler

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## [Unreleased][]
+
+## 0.1.0 - 2017-10-30
+### Initial public release
+
+[Unreleased]: https://github.com/peek-travel/cocktail/compare/0.1.0...HEAD

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright 2017 Peek Travel, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,229 @@
+# Lurch
+[![Build Status](https://travis-ci.org/peek-travel/lurch.svg?branch=master)](https://travis-ci.org/peek-travel/lurch) [![Code Coverage](https://codecov.io/gh/peek-travel/lurch/branch/master/graph/badge.svg)](https://codecov.io/gh/peek-travel/lurch) [![Gem Version](https://img.shields.io/gem/v/lurch.svg)](https://rubygems.org/gems/lurch)
+
+![lurch](./lurch.gif)
+
+A simple Ruby [JSON API](http://jsonapi.org/) client.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```
+gem 'lurch'
+```
+
+And then execute:
+
+```
+$ bundle
+```
+
+Or install it yourself:
+
+```
+$ gem install lurch
+```
+
+## Basic Usage
+
+Start by creating a store:
+
+```ruby
+store = Lurch::Store.new("http://example.com/api")
+```
+
+### Fetch resources from the server
+
+GET individual resources from the server by id:
+
+```ruby
+person = store.from(:people).find("1")
+#=> #<Lurch::Resource[Person] id: "1", name: "Bob">
+```
+
+Or GET all of them at once:
+
+```ruby
+people = store.from(:people).all
+#=> [#<Lurch::Resource[Person] id: "1", name: "Bob">, #<Lurch::Resource[Person] id: "2", name: "Alice">]
+```
+
+`Lurch::Resource` objects have easy accessors for all attributes returned from the server:
+
+```ruby
+person.name
+#=> "Bob"
+person[:name]
+#=> "Bob"
+person.attributes[:name]
+#=> "Bob"
+```
+
+But, `Lurch::Resource` objects are immutable:
+
+```ruby
+person.name = "Robert"
+#=> NoMethodError: undefined method `name=' for #<Lurch::Resource:0x007fe62c848fb8>
+```
+
+### Update existing resources
+
+To update an existing resource, create a changeset from the resource, then PATCH it to the server using the store:
+
+```ruby
+changeset = Lurch::Changeset.new(person, name: "Robert")
+store.save(changeset)
+#=> #<Lurch::Resource[Person] id: "1", name: "Robert">
+```
+
+Existing references to the resource will be updated:
+
+```ruby
+person.name
+#=> "Robert"
+```
+
+### Create new resources
+
+To create new resources, first create a changeset, then POST it to the server using the store:
+
+```ruby
+changeset = Lurch::Changeset.new(:person, name: "Carol")
+new_person = store.insert(changeset)
+#=> #<Lurch::Resource[Person] id: "3", name: "Carol">
+```
+
+## Filtering
+
+You can add filters to your request if your server supports them:
+
+```ruby
+people = store.from(:people).filter(name: "Alice").all
+#=> [#<Lurch::Resource[Person] id: "2", name: "Alice">]
+```
+
+## Relationships
+
+Lurch can fetch *has-many* and *has-one* relationships from the server when they are provided as *related links*:
+
+```ruby
+person = store.from(:people).find("1")
+
+person.hobbies
+#=> #<Lurch::Relationship::Linked href: "http://example.com/api/people/1/friends">
+person.hobbies.fetch
+#=> #<Lurch::Collection[Hobby] size: 2, pages: 1>
+
+person.best_friend
+#=> #<Lurch::Relationship::Linked href: "http://example.com/api/people/1/best-friend">
+person.best_friend.fetch
+#=> #<Lurch::Resource[Person] id: "2", name: "Alice">
+```
+
+If the server provides the relationships as *resource identifiers* instead of links, you can get some information about the relationships without having to load them:
+
+```ruby
+person = store.from(:people).find("1")
+
+person.hobbies
+#=> [#<Lurch::Resource[Hobby] id: "1", not loaded>, ...]
+person.hobbies.count
+#=> 3
+person.hobbies.map(&id)
+#=> ["1", "2", "3"]
+person.hobbies.map(&:name)
+#=> Lurch::Errors::ResourceNotLoaded: Resource (Hobby) not loaded, try calling #fetch first.
+
+person.best_friend
+#=> #<Lurch::Resource[Person] id: "2", not loaded>
+person.best_friend.id
+#=> "2"
+person.best_friend.name
+#=> Lurch::Errors::ResourceNotLoaded: Resource (Person) not loaded, try calling #fetch first.
+```
+
+Regardless of what kind of relationship it is, it can be fetched from the server:
+
+```ruby
+person.best_friend.id
+#=> "2"
+person.best_friend.loaded?
+#=> false
+person.best_friend.fetch
+#=> #<Lurch::Resource[Person] id: "2", name: "Alice">
+person.best_friend.loaded?
+#=> true
+person.best_friend.name
+#=> "Alice"
+```
+
+## Pagination
+
+Lurch supports traversing and requesting paginated results if the server implements pagination:
+
+```ruby
+people = store.from(:people).all
+#=> #<Lurch::Collection[Person] size: 1000, pages: 100>
+```
+
+If the server responded with meta data about the resources, you can get some information about them without loading them all:
+
+```ruby
+people.size
+#=> 1000
+people.page_count
+#=> 100
+```
+
+*NOTE: This data comes from the top-level `meta` key in the jsonapi response document.  It assumes by default the keys are "record-count" and "page-count" respectively, but can be configured in the store.*
+
+To request a specific page, use the page query method:
+
+```ruby
+people = store.from(:people).page(number: 12, size: 50).all
+#=> #<Lurch::Collection[Person] size: 1000, pages: 20>
+```
+
+If you'd like to traverse the whole set, you can do that using the collection enumerator or the page enumerator:
+
+```ruby
+people.map(&:name)
+# ...many HTTP requests later...
+#=> ["Summer Brakus", "Katharina Orn", "Mr. Angus Hickle", "Collin Lowe PhD", "Kaylie Larson", ...]
+
+people.each_page.map(&:size)
+# ...many HTTP requests later...
+#=> [10, 10, 10, 10, ...]
+```
+
+*NOTE: These enumerators can cause many HTTP requests to the server, since when it runs out of the first page of resources, it will automatically request the next page to continue.*
+
+*TIP: Don't use `#count` on a collection to get its size.  Use `#size` instead.  `#count` causes the entire collection to be traversed, whereas `#size` will try and get the information from the collection meta data.*
+
+You can also just get the resources from the current page as an array:
+
+```ruby
+people.resources
+#=> [#<Lurch::Resource[Person] id: "2", name: "Summer Brakus", email: "summerb2b@kiehnhirthe.info", twitter: "@summerb2b">, ...]
+```
+
+## Authentication
+
+You can add an *Authorization* header to all your requests by configuring the store:
+
+```ruby
+store = Lurch::Store.new("...", authorization: "Bearer eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJzdWIiOjEsIm5hbWUiOiJCb2IifQ.")
+```
+
+## Contributing
+
+1.  Fork it (<https://github.com/peek-travel/lurch/fork>)
+2.  Create your feature branch (`git checkout -b my-new-feature`)
+3.  Commit your changes (`git commit -am 'Add some feature'`)
+4.  Push to the branch (`git push origin my-new-feature`)
+5.  Create a new Pull Request
+
+## License
+
+[MIT](LICENSE.md)

data/Rakefile

@@ -0,0 +1,12 @@
+require "rake/testtask"
+require "rubocop/rake_task"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/lurch/test*.rb"]
+  t.warning = false
+end
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/TODO.md

@@ -0,0 +1,22 @@
+# TODO list
+
+* [x] Modify relationships using changesets
+* [x] Changeset error reporting
+* [x] Specify include params in a query
+* [x] Specify pagination params in a query
+* [x] Specify sorting params in a query
+* [x] Specify sparse fields in a query
+* ~~Configurable HTTP adapter (don't assume faraday with typhoeus)~~
+* [x] Configurable field and path adapters (dasherized vs underscored vs ~~camelcased~~)
+* [x] Configurable pluralization/singularization (don't assume urls and types are always plural)
+* [x] Handle paginated results
+* [ ] Allow arbitrary headers
+* [ ] Allow arbitrary query params
+* [ ] Singleton resources
+* [ ] Handle links better?
+* [x] >= 90% test coverage
+* [ ] Yardoc documentation
+* [x] Add license
+* [x] Add changelog
+* [ ] Release 0.1.0 open source
+* [x] Switch to codecov.io

data/lib/lurch/changeset.rb

@@ -0,0 +1,32 @@
+module Lurch
+  class Changeset
+    attr_reader :id, :type
+    attr_accessor :attributes, :relationships, :errors
+
+    def initialize(type, attributes = {})
+      is_resource = type.is_a?(Resource)
+      @type = is_resource ? type.type : Inflector.decode_type(type)
+      @id = is_resource ? type.id : nil
+      @attributes = attributes
+      @relationships = {}
+    end
+
+    def set(key, value)
+      attributes[key.to_sym] = value
+      self
+    end
+
+    def set_related(relationship_key, related_resources)
+      @relationships[relationship_key.to_sym] = related_resources
+      self
+    end
+
+    def inspect
+      attrs = ["id: #{id.inspect}"]
+      attrs = attrs.concat(attributes.map { |name, value| "#{name}: #{value.inspect}" })
+      attrs = attrs.concat(relationships.map { |name, value| "#{name}: #{value.inspect}" })
+      inspection = attrs.join(", ")
+      "#<#{self.class}[#{Inflector.classify(type)}] #{inspection}>"
+    end
+  end
+end

data/lib/lurch/client.rb

@@ -0,0 +1,92 @@
+module Lurch
+  class Client
+    AUTHORIZATION = "Authorization".freeze
+
+    STATUS_EXCEPTIONS = {
+      400 => Errors::BadRequest,
+      401 => Errors::Unauthorized,
+      403 => Errors::Forbidden,
+      404 => Errors::NotFound,
+      409 => Errors::Conflict,
+      422 => Errors::UnprocessableEntity,
+      500 => Errors::ServerError
+    }.freeze
+
+    def initialize(url, config)
+      @url = url
+      @config = config
+    end
+
+    def get(path)
+      response = timed_request("GET", path) { client.get(path) }
+      catch_errors(response).body
+    end
+
+    def post(path, payload)
+      response = timed_request("POST", path, payload) { client.post(path, payload) }
+      # TODO: if 204 is returned, use payload as return body (http://jsonapi.org/format/#crud-creating-responses-204)
+      catch_errors(response).body
+    end
+
+    def patch(path, payload)
+      response = timed_request("PATCH", path, payload) { client.patch(path, payload) }
+      catch_errors(response).body
+    end
+
+    def delete(path, payload = nil)
+      response = timed_request("DELETE", path, payload) do
+        client.delete do |req|
+          req.url path
+          req.body = payload unless payload.nil?
+        end
+      end
+      catch_errors(response).body
+    end
+
+  private
+
+    attr_reader :url, :config
+
+    def timed_request(method, path, payload = nil)
+      log_request(method, path, payload)
+      start_time = Time.now.to_f
+      response = yield
+      end_time = Time.now.to_f
+      time_in_ms = ((end_time - start_time) * 1000).to_i
+      log_response(response, time_in_ms)
+      response
+    end
+
+    def log_request(method, path, payload)
+      Logger.debug { "-> #{method} #{path}" }
+      Logger.debug { "-> #{payload}" } if payload && Lurch.configuration.log_payloads
+    end
+
+    def log_response(response, time_in_ms)
+      Logger.debug { "<- #{response.status} in #{time_in_ms}ms" }
+      Logger.debug { "<- #{response.body}" } if Lurch.configuration.log_payloads
+    end
+
+    def catch_errors(response)
+      raise STATUS_EXCEPTIONS[response.status], response.body if STATUS_EXCEPTIONS[response.status]
+      raise Errors::ServerError, response.body unless (200..299).cover?(response.status)
+
+      response
+    end
+
+    def client
+      @client ||= Faraday.new(url: url) do |conn|
+        conn.headers[AUTHORIZATION] = authorization unless authorization.nil?
+
+        conn.request :jsonapi
+        conn.response :jsonapi
+
+        conn.adapter :typhoeus
+      end
+    end
+
+    def authorization
+      config.authorization
+    end
+  end
+end

data/lib/lurch/collection.rb

@@ -0,0 +1,111 @@
+module Lurch
+  class Collection
+    include Enumerable
+
+    attr_reader :resources
+
+    def initialize(resources, paginator)
+      @resources = resources
+      @paginator = paginator
+    end
+
+    def loaded?
+      true
+    end
+
+    def fetch
+      self
+    end
+
+    def each(&block)
+      block_given? ? enum.each(&block) : enum
+    end
+
+    def each_page(&block)
+      block_given? ? page_enum.each(&block) : page_enum
+    end
+
+    def size
+      @paginator ? @paginator.record_count : @resources.size
+    end
+
+    def page_size
+      @resources.size
+    end
+
+    def page_count
+      @paginator.page_count if @paginator
+    end
+
+    def next_collection
+      return @next_collection if defined?(@next_collection)
+      @next_collection = @paginator ? @paginator.next_collection : nil
+    end
+
+    def prev_collection
+      return @prev_collection if defined?(@prev_collection)
+      @prev_collection = @paginator ? @paginator.prev_collection : nil
+    end
+
+    def first_collection
+      return @first_collection if defined?(@first_collection)
+      @first_collection = @paginator ? @paginator.first_collection : nil
+    end
+
+    def last_collection
+      return @last_collection if defined?(@last_collection)
+      @last_collection = @paginator ? @paginator.last_collection : nil
+    end
+
+    def next?
+      @paginator ? @paginator.next? : false
+    end
+
+    def prev?
+      @paginator ? @paginator.prev? : false
+    end
+
+    def first?
+      @paginator ? @paginator.first? : false
+    end
+
+    def last?
+      @paginator ? @paginator.last? : false
+    end
+
+    def inspect
+      suffix = @resources.first ? "[#{Inflector.classify(@resources.first.type)}]" : ""
+      inspection = size ? ["size: #{size}"] : []
+      inspection << ["pages: #{page_count}"] if page_count
+      "#<#{self.class}#{suffix} #{inspection.join(', ')}>"
+    end
+
+  private
+
+    def enum
+      Enumerator.new(-> { size }) do |yielder|
+        @resources.each do |resource|
+          yielder.yield(resource)
+        end
+
+        if next_collection
+          next_collection.each do |resource|
+            yielder.yield(resource)
+          end
+        end
+      end
+    end
+
+    def page_enum
+      Enumerator.new(-> { page_count }) do |yielder|
+        yielder.yield(@resources)
+
+        if next_collection
+          next_collection.each_page do |page|
+            yielder.yield(page)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lurch/configuration.rb

@@ -0,0 +1,14 @@
+require "logger"
+
+module Lurch
+  class Configuration
+    attr_accessor :logger, :log_payloads
+
+    def initialize
+      @logger = ::Logger.new(STDOUT)
+      @logger.level = ::Logger::INFO
+
+      @log_payloads = false
+    end
+  end
+end

data/lib/lurch/error.rb

@@ -0,0 +1,13 @@
+module Lurch
+  class Error
+    JSON_API_ERROR_FIELDS = %w[id links about status code title detail source meta].freeze
+
+    attr_reader(*JSON_API_ERROR_FIELDS)
+
+    def initialize(error_object)
+      JSON_API_ERROR_FIELDS.each do |field|
+        instance_variable_set("@#{field}", error_object[field])
+      end
+    end
+  end
+end

data/lib/lurch/errors/bad_request.rb

@@ -0,0 +1,6 @@
+module Lurch
+  module Errors
+    class BadRequest < JSONApiError
+    end
+  end
+end

data/lib/lurch/errors/conflict.rb

@@ -0,0 +1,6 @@
+module Lurch
+  module Errors
+    class Conflict < JSONApiError
+    end
+  end
+end

data/lib/lurch/errors/forbidden.rb

@@ -0,0 +1,6 @@
+module Lurch
+  module Errors
+    class Forbidden < JSONApiError
+    end
+  end
+end

data/lib/lurch/errors/json_api_error.rb

@@ -0,0 +1,29 @@
+module Lurch
+  module Errors
+    class JSONApiError < StandardError
+      def initialize(document)
+        @document = document
+      end
+
+      def message
+        return @document unless errors_document?
+        @document["errors"].map { |error| message_from_document_error(error) }.join(", ")
+      end
+
+      def errors
+        return [] unless errors_document?
+        @document["errors"].map { |error| Lurch::Error.new(error) }
+      end
+
+    private
+
+      def errors_document?
+        @document.is_a?(Hash) && @document["errors"]
+      end
+
+      def message_from_document_error(error)
+        [*error["status"], *error["detail"]].join(": ")
+      end
+    end
+  end
+end

data/lib/lurch/errors/not_found.rb

@@ -0,0 +1,6 @@
+module Lurch
+  module Errors
+    class NotFound < JSONApiError
+    end
+  end
+end