lhc 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bac9f0ada28e8054aa6f8e01de35451970dd478b
+  data.tar.gz: b457597aba0d084e762f599b8a42680c2126cc47
+SHA512:
+  metadata.gz: 076b39d8fc0003520cd64ae221bc7f7efaf2b671a684699b3092566065f3490a85d54464447576179460715934b6350cc8cc0c8a57bf43cc2a7876ab745594fc
+  data.tar.gz: 6cb6e105b87af256708c9552a13aa1b935e59e500535bbb77197ba7e3a402ffd2f45fc1fdd84f3dc4c0b8ce67f3c9c6ead3dc09195f3ca7b99223a42e52b63c4

data/.gitignore

@@ -0,0 +1,36 @@
+*.rbc
+capybara-*.html
+.rspec
+.DS_Store
+/log
+/tmp
+/db/*.sqlite3
+/public/system
+/coverage/
+/spec/tmp
+**.orig
+rerun.txt
+pickle-email-*.html
+*.log
+pkg/
+
+# TODO Comment out these rules if you are OK with secrets being uploaded to the repo
+config/initializers/secret_token.rb
+config/secrets.yml
+
+## Environment normalisation:
+/.bundle
+/vendor/bundle
+
+# these should all be checked in to normalise the environment:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# if using bower-rails ignore default bower_components path bower.json files
+/vendor/assets/bower_components
+*.bowerrc
+bower.json

data/Gemfile

@@ -0,0 +1,11 @@
+source 'https://GemInAbox:e3XRBgVJRNUmwJ5y@gembox-vm-inx01.intra.local.ch/'
+
+# Declare your gem's dependencies in lhc.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
+gemspec
+
+# Declare any dependencies that are still in development here instead of in
+# your gemspec. These might include edge Rails or gems from your path or
+# Git. Remember to move these dependencies to your gemspec before releasing
+# your gem to rubygems.org.

data/README.md

@@ -0,0 +1,116 @@
+LHC
+===
+
+LHC uses [typhoeus](https://github.com/typhoeus/typhoeus) for http communication.
+
+See [LHS](https://github.com/local-ch/LHS), if you are searching for something more **high level** that can query webservices easily and provides easy data access.
+
+## Quick Start Guide
+
+```ruby
+  response = LHC.get('http://datastore.lb-service/v2/feedbacks')
+  response.data.items[0]
+  response.data.items[0].recommended
+  response.body     # String
+  response.headers  # Hash
+```
+
+## Basic methods
+
+Available are `get`, `post`, `put` & `delete`.
+
+Other methods are available using `LHC.request(options)`.
+
+## A request from scratch
+
+```ruby
+  response = LHC.request(url: 'http://local.ch', method: :options)
+  response.headers
+
+  response = LHC.request(url: 'http://datastore.lb-service/v2/feedbacks', method: :get)
+  response.data
+```
+
+→ [Read more about the request object](docs/request.md)
+
+→ [Read more about the response object](docs/response.md)
+
+## Parallel requests
+
+If you pass an array of requests to `LHC.request`, it will perform those requests in parallel.
+You will get back an array of LHC::Response objects.
+
+```ruby
+  options = []
+  options << { url: 'http://datastore.lb-service/v2/feedbacks' }
+  options << { url: 'http://datastore.lb-service/v2/content-ads/123/feedbacks' }
+  responses = LHC.request(options)
+```
+
+## Transfer data through the body
+
+Data that is transfered using the HTTP request body is transfered as you provide it.
+Also consider setting the http header for content-type.
+
+```ruby
+  LHC.post('http://datastore.lb-service/v2/feedbacks',
+    body: feedback.to_json,
+    headers: { 'Content-Type' => 'application/json' }
+  )
+```
+
+## Configuration
+
+You can configure global endpoints, placeholders and interceptors.
+
+```ruby
+  LHC.configure do |c|
+    c.placeholder :datastore, 'http://datastore.lb-service/v2'
+    c.endpoint :feedbacks, ':datastore/feedbacks', params: { has_reviews: true }
+    c.interceptors = [CacheInterceptor]
+  end
+```
+
+→ [Read more about configuration](docs/configuration.md)
+
+## URL-Templates
+
+Instead of using concrete urls you can also use url-templates that contain placeholders.
+This is especially handy for configuring an endpoint once and generate the url from the params when doing the request.
+
+```ruby
+  url = 'http://datastore.lb-service/v2/feedbacks/:id'
+  LHC.config.endpoint(:find_feedback, url, options)
+  LHC.get(:find_feedback, params:{ id: 123 })
+  # GET http://datastore.lb-service/v2/feedbacks/123
+```
+
+This also works in place without configuring an endpoint.
+
+```ruby
+  LHC.get('http://datastore-stg.lb-service/v2/feedbacks/:id', params:{ id: 123 })
+  # GET http://datastore-stg.lb-service/v2/feedbacks/123
+```
+
+If you miss to provide a parameter that is part of the url-template, it will raise an exception.
+
+## Exception handling
+
+Anything but a response code indicating success (2**) throws an exception.
+
+→ [Read more about exceptions](docs/exceptions.md)
+
+## Interceptors
+
+To monitor and manipulate the http communication done with LHC, you can define interceptors.
+
+```ruby
+  class TrackingIdInterceptor < LHC::Interceptor
+
+    def before_request(request)
+      request.params[:tid] = 123
+    end
+  end
+```
+
+→ [Read more about interceptors](docs/interceptors.md)

data/Rakefile

@@ -0,0 +1,25 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'LHC'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+  task :default => :spec
+rescue LoadError
+  # no rspec available
+end
+
+Bundler::GemHelper.install_tasks

data/docs/configuration.md

@@ -0,0 +1,57 @@
+Configuration
+===
+
+## Configure LHC on initialisation
+
+If you want to configure LHC on initialisation (like in a Rails initializer, environment.rb or application.rb), you could run into the problem that certain configurations can only be set once.
+You can use `LHC.configure` to prevent the initialisation problem.
+Take care that you only use `LHC.configure` once, because it is actually reseting previously made configurations and applies the new once.
+
+```ruby
+
+  LHC.configure do |c|
+    c.placeholder :datastore, 'http://datastore.lb-service/v2'
+    c.endpoint :feedbacks, ':datastore/feedbacks'
+    c.interceptors = [CachingInterceptor, MonitorInterceptor, TrackingIdInterceptor]
+  end
+
+```
+
+## Endpoints
+
+You can configure endpoints, for later use, by giving them a name, an url and some parameters (optional).
+
+```ruby
+  url = 'http://datastore.lb-service/v2/feedbacks'
+  options = { params: { has_reviews: true } }
+  LHC.config.endpoint(:feedbacks, url, options)
+  LHC.get(:feedbacks)
+```
+
+Explicit request options override configured options.
+
+```ruby
+  LHC.get(:feedbacks, params: { has_reviews: false }) # Overrides configured params
+```
+
+## Placeholders
+
+You can configure global placeholders, that are used when generating urls from url-templates.
+
+```ruby
+  LHC.config.placeholder(:datastore, 'http://datastore.lb-service/v2')
+  options = { params: { has_reviews: true } }
+  LHC.config.endpoint(:feedbacks, url, options)
+  LHC.get(:feedbacks)
+```
+
+## Interceptors
+
+To enable interceptors you have to configure LHC's interceptors for http communication.
+The global default interceptors are processed in the order you provide them.
+
+```ruby
+  LHC.config.interceptors = [CachingInterceptor, MonitorInterceptor, TrackingIdInterceptor]
+```
+
+You can only set the list of global interceptors once and you can not alter it after you set it.

data/docs/exceptions.md

@@ -0,0 +1,68 @@
+Exceptions
+===
+
+Anything but a response code indicating success (2**) raises an exception.
+
+```ruby
+
+  LHC.get('localhost') # UnknownError: 0
+  LHC.get('http://localhost:3000') # LHC::Timeout: 0
+
+```
+
+You can access the response object that was causing the error.
+
+```ruby
+LHC.get('local.ch')
+rescue => e
+  e.response #<LHC:Response>
+  e.response.code # 403
+  e.response.timeout? # false
+  Rails.logger.error e
+  # LHC::UnknownError: get http://local.cac
+  # Params: {:url=>"http://local.cac", :method=>:get}
+  # Response Code: 0
+  # <Response Body>
+```
+
+All errors that are raise by LHC inherit from `LHC::Error`.
+They are divided into `LHC::ClientError`, `LHC::ServerError`, `LHC::Timeout` and `LHC::UnkownError` and mapped arcording to the following status code.
+
+```ruby
+400 => LHC::BadRequest
+401 => LHC::Unauthorized
+402 => LHC::PaymentRequired
+403 => LHC::Forbidden
+403 => LHC::Forbidden
+404 => LHC::NotFound
+405 => LHC::MethodNotAllowed
+406 => LHC::NotAcceptable
+407 => LHC::ProxyAuthenticationRequired
+408 => LHC::RequestTimeout
+409 => LHC::Conflict
+410 => LHC::Gone
+411 => LHC::LengthRequired
+412 => LHC::PreconditionFailed
+413 => LHC::RequestEntityTooLarge
+414 => LHC::RequestUriToLong
+415 => LHC::UnsupportedMediaType
+416 => LHC::RequestedRangeNotSatisfiable
+417 => LHC::ExpectationFailed
+422 => LHC::UnprocessableEntity
+423 => LHC::Locked
+424 => LHC::FailedDependency
+426 => LHC::UpgradeRequired
+
+500 => LHC::InternalServerError
+501 => LHC::NotImplemented
+502 => LHC::BadGateway
+503 => LHC::ServiceUnavailable
+504 => LHC::GatewayTimeout
+505 => LHC::HttpVersionNotSupported
+507 => LHC::InsufficientStorage
+510 => LHC::NotExtended
+
+timeout? => LHC::Timeout
+
+anything_else => LHC::UnknownError
+```

data/docs/interceptors.md

@@ -0,0 +1,90 @@
+Interceptors
+===
+
+## Quick Start Guide
+
+```ruby
+  class TrackingIdInterceptor < LHC::Interceptor
+
+    def before_request(request)
+      request.params[:tid] = 123
+    end
+  end
+```
+
+```ruby
+  LHC.config.interceptors = [TrackingIdInterceptor] # global list of default interceptors
+```
+
+```ruby
+  LHC.request({url: 'http://local.ch', interceptors: []}) # no interceptor for this request
+```
+
+## Basic Interceptors
+
+There are some interceptors available, that cover some basic usecases:
+[lhc-core-interceptors](https://github.com/local-ch/lhc-core-interceptors)
+
+## Callbacks
+
+`before_request(request)` is called when the request is prepared and about to be executed.
+
+`after_request(request)` is called after request was started.
+
+`before_response(request)` is called when response started to arrive.
+
+`after_response(response)` is called after the response arrived completely.
+
+→ [Read more about the request object](request.md)
+
+→ [Read more about the response object](response.md)
+
+## Global default interceptors
+
+Set the list of global default interceptors.
+The global default interceptors are processed in the order you provide them.
+
+```ruby
+  LHC.config.interceptors = [CachingInterceptor, MonitorInterceptor, TrackingIdInterceptor]
+```
+
+You can only set the list of global interceptors once and you cannot alter them later.
+
+## Interceptors on request level
+
+You can override the global default interceptors on request level:
+
+```ruby
+  interceptors = LHC.config.interceptors
+  interceptors -= [CachingInterceptor] # remove caching
+  interceptors += [RetryInterceptor] # add retry
+  LHC.request({url: 'http://local.ch', retry: 2, interceptors: interceptors})
+```
+
+## Provide Response
+
+Inside an interceptor, you are able to provide a response, rather then doing a real request.
+This is usefull for implementing an interceptor for caching.
+
+```ruby
+class CacheInterceptor < LHC::Interceptor
+
+  def before_request(request)
+    cached_response = Rails.cache.fetch(request.url)
+    return LHC::Response.new(cached_response) if cached_response
+  end
+end
+```
+
+Take care that having more than one interceptor trying to return a response will cause an exception.
+You can access the request.response to identify if a response was already provided by another interceptor.
+
+```ruby
+  class RemoteCacheInterceptor < LHC::Interceptor
+
+    def before_request(request)
+      return unless request.response.nil?
+      return LHC::Response.new(remote_cache)
+    end
+  end
+```

data/docs/request.md

@@ -0,0 +1,24 @@
+Request
+===
+
+The request class handles the http request,
+implements the interceptor pattern,
+loads configured endpoints,
+generates urls from url-templates
+and raises exceptions for any response code that is not indicating success (2**).
+
+→ [Read more about exceptions](exceptions.md)
+
+```ruby
+  request.response #<LHC::Response> the associated response.
+
+  request.options #<Hash> the options used for creating the request.
+
+  request.params # access request params
+
+  request.headers # access request headers
+
+  request.url #<String> URL that is used for doing the request
+
+  request.method #<Symbol> provides the used http-method
+```