garage_client 2.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 648321b65499a513c8305e6aac962afb10bf99f6
+  data.tar.gz: 17c99e87555fadc63de66ac384d09a354feeb00b
+SHA512:
+  metadata.gz: dc3e8ea2288e52f6ec2e9d9ef1b9f92318478ea543852cf77706ca53665f20d5d63e6445d88496ad0a415733772241addb8a67ffc4529e54415883ccab20e6d4
+  data.tar.gz: 57c200a989fc68dcd096ced3dc853ca92eb4d03246e2d26afec236c60fd3d06332d284ed642723b8f3e396b3f6fd643f15c0e0c105ba275579009ea347d006a6

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+coverage/
+coverage.vim
+.ruby-version
+gemfiles/*.lock

data/.rspec

@@ -0,0 +1 @@
+--color

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+## 2.1.0
+- Access token is now embedded in authorization header as a bearer token, instead of embedding in query parameter, to avoid logging and exposing access token value.
+  Before: access token is embedded in both query parameter (`?access_token=XXX`) and in authorization header (`Authorization: Token token="XXX"`).
+  After: access tok is embedded in authorization header as a bearer token (`Authorization: Bearer XXX`).
+
+## 2.0.0
+- Remove `user_agent` configuration, use `headers` option instead.
+
+## 1.3.0
+- Provide a convenient way to cache HTTP response
+
+## 1.2.4
+- Raise GarageClient::InvalidResponseType when receives invalid response (e.g. String)
+
+## 1.2.3
+- Fixed response.respond_to?(:name)
+
+## 1.2.2
+- GarageClient::Response supports Link header parsing
+
+## 1.2.1
+- Set Content-Type with multipart/form-data when multipart params are detected
+
+## 1.2.0
+- `:headers` option will overwrite the entire headers
+- `:default_headers` will be deprecated. Please use `:headers`
+- `Garage.version` was deprecated. Please use `Garage::VERSION`
+- `Garage.configuration` was added to configure settings
+
+## 1.1.2
+- Remove needless empty module clause (7f5e13)
+- Change gemspec dependency (`hashie ~> 1.2.0` to `hashie >= 1.2.0`) (632ea1)
+
+## 1.1.1
+- GarageClient::Error accepts no argument initialization
+
+## 1.1.0
+- Add ``:default_headers`` option
+- Verbose exception message
+- Resource#links does not raise error when _links is not existed

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem "simplecov-vim", :platform => :mri_19
+  gem "simplecov-rcov", :platform => :mri_19
+end

data/Guardfile

@@ -0,0 +1,7 @@
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb})
+  watch(%r{^lib/(.+)\.rb}) { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb') { "spec" }
+end
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Cookpad Inc.
+
+MIT License
+
+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,196 @@
+# GarageClient
+GarageClient is a simple Ruby library to provide a primitive client interface to the Garage application API.
+
+## Install
+Install from rake command:
+
+```
+$ bundle install
+$ rake install
+```
+
+or modify Gemfile in your application and invoke `bundle install`.
+
+```ruby
+# Gemfile
+gem "garage_client"
+```
+
+## Usage
+Here are quick examples.
+
+### Client initialization
+```ruby
+require "garage_client"
+
+# First, you have to create a GarageClient::Client with an access token.
+# You can get `YOUR_ACCESS_TOKEN` with OAuth 2.0 flow.
+client = GarageClient::Client.new(access_token: YOUR_ACCESS_TOKEN)
+```
+
+### Read from Garage application
+```ruby
+# GET https://garage.example.com/v1/recipes
+client.get("/recipes")
+
+# GET https://garage.example.com/v1/recipes?fields=id,name,ingredients
+client.get("/recipes", fields: "id,name,ingredients")
+
+# GET https://garage.example.com/v1/me
+user = client.get("/me")
+
+# GET https://garage.example.com/v1/users/:user_id/recipes?fields=__default__,user[id,name]
+client.get("/users/#{user.id}/recipes", fields: "__default__,user[id,name]")
+```
+
+### Write to Garage application
+```ruby
+# POST https://garage.example.com/v1/suggestions
+client.post("/suggestions", message: "suggestion message")
+
+# POST https://garage.example.com/v1/users/:user_id/bookmark_tags with JSON {"name":"tag name"}
+bookmark_tag = client.post("/users/#{user.id}/bookmark_tags", name: "tag name")
+
+# PUT https://garage.example.com/v1/bookmark_tags/:id with JSON {"name":"new tag name"}
+client.put("/bookmark_tags/#{bookmark_tag.id}", name: "new tag name")
+
+# DELETE https://garage.example.com/v1/bookmark_tags/:id
+client.delete("/bookmark_tags/#{bookmark_tag.id}")
+```
+
+### Response
+```ruby
+# `.get` method returns a GarageClient::Response of a resource.
+user = client.get("/me")
+user.id
+user.url
+user.name
+
+# `.get` method also returns a GarageClient::Response of an array of resources.
+# In this case, the response object can respond to `.total_count` method.
+recipes = client.get("/recipes")
+recipes.total_count
+recipes[0].id
+recipes[0].name
+
+# While Garage application API returns all default properties, some additional properties are not included in them.
+# You can specify the returned properties by `?fields=...` URI query parameters.
+recipes = client.get("/recipes", fields: "__default__,user")
+recipes[0].id
+recipes[0].name
+recipes[0].user.id
+recipes[0].user.url
+recipes[0].user.name
+
+# `.post` method also returns a GarageClient::Response of the newly created resource.
+suggestion = client.post("/suggestions", message: "suggestion message")
+suggestion.message
+```
+
+## Configuration
+There are the following options:
+
+- `adapter` - faraday adapter for http client (default: `:net_http`)
+- `cacher` - take a cacher class in which caching logic is defined (default: nil)
+- `headers` - default http headers (default: `{ "Accept" => "application/json", "User-Agent" => "garage_client #{VERSION}" }`)
+- `endpoint` - Garage application API endpoint (default: nil)
+- `path_prefix` - API path prefix (default: `'/v1'`)
+- `verbose` - Enable verbose http log (default: `false`)
+
+You can configure the global settings:
+
+```ruby
+GarageClient.configure do |c|
+  c.endpoint = "http://localhost:3000"
+  c.verbose = true
+end
+```
+
+or each GarageClient::Client settings:
+
+```ruby
+client = GarageClient::Client.new(
+  adapter: :test,
+  headers: { "Host" => "garage.example.com" },
+  endpoint: "http://localhost:3000",
+  path_prefix: "/v2",
+  verbose: true,
+)
+```
+
+## Exceptions
+GarageClient raises one of the following exceptions upon an error.
+Make sure to always look out for these in your code.
+
+```ruby
+GarageClient::Unauthorized
+GarageClient::Forbidden
+GarageClient::NotFound
+GarageClient::NotAcceptable
+GarageClient::Conflict
+GarageClient::UnsupportedMediaType
+GarageClient::UnprocessableEntity
+GarageClient::InternalServerError
+GarageClient::ServiceUnavailable
+```
+
+## Utility
+`.properties` returns a list of properties of the resource.
+
+```ruby
+user = client.get("/me")
+user.properties #=> [:id, :url, :name, :_links]
+```
+
+`.links` returns a list of link names related to the resource.
+
+```ruby
+user = client.get("/me")
+user.properties #=> [:self, :bookmarks, :recipes, ...]
+user.links.recipes #=> "https://garage.example.com/v1/users/:user_id/recipes"
+```
+
+## Caching
+Define a cacher class with your custom caching logic to let it cache response, inheriting GarageClient::Cachers::Base.
+It must override `read_from_cache?`, `written_to_cache?`, `key`, and `store` to compose your caching logic.
+
+```ruby
+class MyCacher < GarageClient::Cachers::Base
+  private
+
+  def read_from_cache?
+    has_get_method? && has_cached_path?
+  end
+
+  def written_to_cache?
+    read_from_cache?
+  end
+
+  def key
+    @env[:url].to_s
+  end
+
+  def store
+    Rails.cache
+  end
+
+  def options
+    { expires_in: 5.minutes }
+  end
+
+  def has_get_method?
+    @env[:method] == :get
+  end
+
+  def has_cached_path?
+    case @env[:url].path
+    when %r<^/v1/searches>
+      true
+    when %r<^/v1/recipes/\d+>
+      true
+    end
+  end
+end
+
+GarageClient::Client.new(cacher: MyCacher)
+```

data/Rakefile

@@ -0,0 +1,8 @@
+#!/usr/bin/env rake
+require 'rubygems'
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec
+task :test    => :spec

data/garage_client.gemspec

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+$:.unshift File.expand_path("../lib", __FILE__)
+require 'garage_client/version'
+
+Gem::Specification.new do |s|
+  s.version       = GarageClient::VERSION
+  s.name          = "garage_client"
+  s.homepage      = "https://github.com/cookpad/garage_client"
+  s.summary       = "Ruby client library for the Garage API"
+  s.description   = s.summary
+
+  s.files         = `git ls-files`.split($\)
+  s.executables   = s.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths = ['lib']
+  s.authors       = ['Cookpad Inc.']
+  s.email         = ['kaihatsu@cookpad.com']
+
+  s.add_dependency 'activesupport', '> 3.2.0'
+  s.add_dependency 'faraday', '>= 0.8.0'
+  s.add_dependency 'faraday_middleware'
+  s.add_dependency 'hashie', '>= 1.2.0'
+  s.add_dependency 'link_header'
+  s.add_dependency 'mime-types', '~> 1.16'
+
+  s.add_dependency 'system_timer' if RUBY_VERSION < '1.9'
+
+  s.add_development_dependency "rake", ">= 0.9.2"
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "json"
+  s.add_development_dependency "guard-rspec"
+  s.add_development_dependency "webmock"
+  s.add_development_dependency "pry"
+  # Until bug fixed: https://github.com/colszowka/simplecov/issues/281
+  s.add_development_dependency "simplecov", "~> 0.7.1"
+end

data/gemfiles/Gemfile.faraday-0.8.x

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gem 'faraday', '~> 0.8.0'
+gemspec path: '../'

data/lib/garage_client.rb

@@ -0,0 +1,33 @@
+require 'active_support/all'
+require 'faraday'
+require 'faraday_middleware'
+
+require 'garage_client/version'
+require 'garage_client/cachers/base'
+require 'garage_client/configuration'
+require 'garage_client/error'
+require 'garage_client/request'
+require 'garage_client/request/json_encoded'
+require 'garage_client/response'
+require 'garage_client/response/cacheable'
+require 'garage_client/response/raise_http_exception'
+require 'garage_client/resource'
+require 'garage_client/client'
+
+module GarageClient
+  class << self
+    GarageClient::Configuration.keys.each do |key|
+      delegate key, "#{key}=", to: :configuration
+    end
+
+    delegate 'default_headers', 'default_headers=', to: :configuration
+
+    def configuration
+      @configuration ||= GarageClient::Configuration.new
+    end
+
+    def configure(&block)
+      configuration.instance_eval(&block)
+    end
+  end
+end

data/lib/garage_client/cachers/base.rb

@@ -0,0 +1,44 @@
+# Inherit this abstract class and pass it to garage_client client to cache its responses.
+module GarageClient
+  module Cachers
+    class Base
+      def initialize(env)
+        @env = env
+      end
+
+      def call
+        response = read_from_cache? && store.read(key, options) || yield
+        store.write(key, response, options) if written_to_cache?
+        response
+      end
+
+      private
+
+      # Return boolean to tell if we need to cache the response or not.
+      def allowed_to_read_cache?
+        raise NotImplementedError, "You must implement #{self.class}##{__method__}"
+      end
+
+      # Return boolean to tell if we can try to check cache or not.
+      def allowed_to_write_cache?
+        raise NotImplementedError, "You must implement #{self.class}##{__method__}"
+      end
+
+      # Return string to cache key to store a given HTTP response.
+      def key
+        raise NotImplementedError, "You must implement #{self.class}##{__method__}"
+      end
+
+      # Return store-object to get or write response (e.g. Rails.cache).
+      # This store-object must respond to `fetch(key, options)` method signature.
+      def store
+        raise NotImplementedError, "You must implement #{self.class}##{__method__}"
+      end
+
+      # Return hash table to be used as store's options.
+      def options
+        {}
+      end
+    end
+  end
+end

data/lib/garage_client/client.rb

@@ -0,0 +1,93 @@
+module GarageClient
+  class Client
+    include GarageClient::Request
+
+    def self.property(key)
+      define_method(key) do
+        options.fetch(key, GarageClient.configuration.send(key))
+      end
+
+      define_method("#{key}=") do |value|
+        options[key] = value
+      end
+    end
+
+    attr_reader :options
+
+    property :adapter
+    property :cacher
+    property :endpoint
+    property :path_prefix
+    property :verbose
+
+    def initialize(options = {})
+      require_necessaries(options)
+      @options = options
+    end
+
+    def headers
+      @headers ||= GarageClient.configuration.headers.merge(given_headers.stringify_keys)
+    end
+    alias :default_headers :headers
+
+    def headers=(value)
+      @headers = value
+    end
+    alias :default_headers= :headers=
+
+    def access_token
+      options[:access_token]
+    end
+
+    def access_token=(value)
+      options[:access_token] = value
+    end
+
+    def me(params = {}, options = {})
+      get('/me', params, options)
+    end
+
+    def conn
+      @conn ||= connection
+    end
+
+    def apply_auth_middleware(faraday_builder)
+      faraday_builder.authorization :Bearer, access_token if access_token
+    end
+
+    def connection
+      Faraday.new(headers: headers, url: endpoint) do |builder|
+        # Response Middlewares
+        builder.use Faraday::Response::Logger if verbose
+        builder.use FaradayMiddleware::Mashify
+        builder.use Faraday::Response::ParseJson, :content_type => /\bjson$/
+        builder.use GarageClient::Response::Cacheable, cacher: cacher if cacher
+        builder.use GarageClient::Response::RaiseHttpException
+
+        # Request Middlewares
+        builder.use Faraday::Request::Multipart
+        builder.use GarageClient::Request::JsonEncoded
+
+        # Low-level Middlewares
+        apply_auth_middleware builder
+        builder.adapter(*adapter)
+      end
+    end
+
+    private
+
+    def given_headers
+      options[:headers] || options[:default_headers] || {}
+    end
+
+    def require_necessaries(options)
+      if !options[:endpoint] && !default_options.endpoint
+        raise "Missing endpoint configuration"
+      end
+    end
+
+    def default_options
+      GarageClient.configuration
+    end
+  end
+end