lhs 0.3.0

data/docs/services.md

@@ -0,0 +1,191 @@
+Services
+===
+
+A LHS::Service makes data available using multiple endpoints.
+
+![Service](service.jpg)
+
+## Endpoints
+
+You setup a service by configure one or multiple backend endpoints.
+You can also add request options for an endpoint (see following example).
+
+```ruby
+class Feedback < LHS::Service
+
+  endpoint ':datastore/v2/content-ads/:campaign_id/feedbacks'
+  endpoint ':datastore/v2/feedbacks', cache: true, cache_expires_in: 1.day
+
+end
+```
+
+If you try to setup a service with clashing endpoints it will immediately raise an exception.
+
+```ruby
+class Feedback < LHS::Service
+
+  endpoint ':datastore/v2/reviews'
+  endpoint ':datastore/v2/feedbacks'
+
+end
+# raises: Clashing endpoints.
+
+```
+
+## Find multiple records
+
+You can query the services by using `where`.
+
+```ruby
+  Feedback.where(has_reviews: true) #<LHS::Data @_proxy=#<LHS::Collection>>
+```
+
+This uses the `:datastore/v2/feedbacks` endpoint, cause `:campaign_id` was not provided.
+In addition it would add `?has_reviews=true` to the get parameters.
+
+```ruby
+  Feedback.where(campaign_id: 'fq-a81ngsl1d') #<LHS::Data @_proxy=#<LHS::Collection>>
+```
+Uses the `:datastore/v2/content-ads/:campaign_id/feedbacks` endpoint.
+
+→ [Read more about collections](collections.md)
+
+## Find single records
+
+`find` finds a unique item by uniqe identifier (usualy id).
+
+If no record is found an error is raised.
+
+```ruby
+  Feedback.find('z12f-3asm3ngals') #<LHS::Data @_proxy=#<LHS::Item>>
+```
+
+`find` can also be used to find a single uniqe item with parameters:
+
+```ruby
+  Feedback.find(campaign_id: 123, id: 456)
+```
+
+`find_by` finds the first record matching the specified conditions.
+
+If no record is found, `nil` is returned.
+
+`find_by!` raises LHC::NotFound if nothing was found.
+
+```ruby
+  Feedback.find_by(id: 'z12f-3asm3ngals') #<LHS::Data @_proxy=#<LHS::Item>>
+  Feedback.find_by(id: 'doesntexist') # nil
+```
+
+`first` is a alias for finding the first of a service without parameters.
+
+```ruby
+  Feedback.first
+```
+
+If no record is found, `nil` is returned.
+
+`first!` raises LHC::NotFound if nothing was found.
+
+→ [Read more about items](items.md)
+
+## Batch processing
+
+** Be carefull using methods for batch processing. They could result in a lot of HTTP requests! **
+
+`all` fetches all records from the backend by doing multiple requests if necessary.
+
+```ruby
+data = Feedback.all #<LHS::Data @_proxy=#<LHS::Collection>>
+data.count # 998
+data.total # 998
+```
+
+→ [Read more about collections](collections.md)
+
+`find_each` is a more fine grained way to process single records that are fetched in batches.
+
+```ruby
+Feedback.find_each(start: 50, batch_size: 20, params: { has_reviews: true }) do |feedback|
+  # Iterates over each record. Starts with record nr. 50 and fetches 20 records each batch.
+  feedback #<LHS::Data @_proxy=#<LHS::Item>>
+end
+```
+
+`find_in_batches` is used by `find_each` and processes batches.
+```ruby
+Feedback.find_in_batches(start: 50, batch_size: 20, params: { has_reviews: true }) do |feedbacks|
+  # Iterates over multiple records (batch size is 20). Starts with record nr. 50 and fetches 20 records each batch.
+  feedbacks #<LHS::Data @_proxy=#<LHS::Collection>>
+end
+```
+
+## Create records
+
+```ruby
+  feedback = Feedback.create(
+    recommended: true,
+    source_id: 'aaa',
+    content_ad_id: '1z-5r1fkaj'
+  ) #<LHS::Data @_proxy=#<LHS::Item>>
+```
+
+When creation fails, the object contains errors in its `errors` attribute:
+
+```ruby
+  feedback.errors #<LHS::Errors>
+  feedback.errors.include?(:ratings) # true
+  feedback.errors[:ratings] # ['REQUIRED_PROPERTY_VALUE']
+  record.errors.messages # {:ratings=>["REQUIRED_PROPERTY_VALUE"], :recommended=>["REQUIRED_PROPERTY_VALUE"]}
+  record.errors.message # ratings must be set when review or name or review_title is set | The property value is required; it cannot be null, empty, or blank."
+```
+
+## Build new records
+
+Build and persist new items from scratch.
+
+```ruby
+  feedback = Feedback.build(recommended: true)
+  feedback.save
+```
+
+→ [Read more about items](items.md)
+
+
+## Include linked resources
+
+A service lets you specify in advance all the linked resources that you want to include in the results. With includes, a service ensures that all matching and explicitly linked resources are loaded and merged.
+
+The implementation is heavily influenced by [http://guides.rubyonrails.org/active_record_querying](http://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations)
+and you should read it to understand this feature in all its glory.
+
+### One-Level `includes`
+
+```ruby
+  # a claim has a localch_account
+  claims = Claims.includes(:localch_account).where(place_id: 'huU90mB_6vAfUdVz_uDoyA')
+  claims.first.localch_account.email # 'test@email.com'
+```
+* [see the JSON without include](examples/claim_no_include.json)
+* [see the JSON with include](examples/claim_with_include.json)
+
+### Two-Level `includes`
+
+```ruby
+  # a feedback has a campaign, which has an entry
+  feedbacks = Feedback.includes(campaign: :entry).where(has_reviews: true)
+  feedbacks.first.campaign.entry.name # 'Casa Ferlin'
+```
+
+## Map data
+
+To influence how data is accessed/provied, you can use mapping to either map deep nested data or to manipulate data when its accessed:
+
+```ruby
+class LocalEntry < LHS::Service
+  endpoint ':datastore/v2/local-entries'
+
+  map :name, ->(entry){ entry.addresses.first.business.identities.first.name }
+
+end
+```

data/lhs.gemspec

@@ -0,0 +1,31 @@
+$:.push File.expand_path("../lib", __FILE__)
+
+# Maintain your gem's version:
+require "lhs/version"
+
+# Describe your gem and declare its dependencies:
+Gem::Specification.new do |s|
+  s.name        = "lhs"
+  s.version     = LHS::VERSION
+  s.authors     = ['local.ch']
+  s.email       = ['ws-operations@local.ch']
+  s.homepage    = 'https://github.com/local-ch/lhs'
+  s.summary     = 'LocalHttpServices'
+  s.description = 'Rails gem providing an easy interface to use http services here at local'
+
+  s.files        = `git ls-files`.split("\n")
+  s.test_files   = `git ls-files -- spec/*`.split("\n")
+  s.require_paths = ['lib']
+
+  s.requirements << 'Ruby >= 1.9.2'
+  s.required_ruby_version = '>= 1.9.2'
+
+  s.add_dependency 'lhc', '>= 0.2.0'
+  s.add_dependency 'lhc-core-interceptors', '>= 0.1.0'
+
+  s.add_development_dependency 'rspec-rails', '>= 3.0.0'
+  s.add_development_dependency 'rails', '>= 4.0.0'
+  s.add_development_dependency 'webmock'
+  s.add_development_dependency 'geminabox'
+  s.add_development_dependency 'pry'
+end

data/lib/lhs.rb

@@ -0,0 +1,6 @@
+require 'lhc'
+
+module LHS
+end
+
+Gem.find_files('lhs/**/*.rb').each { |path| require path }

data/lib/lhs/collection.rb

@@ -0,0 +1,78 @@
+require File.join(__dir__, 'proxy.rb')
+
+# A collection is a special type of data
+# that contains multiple items
+class LHS::Collection < LHS::Proxy
+
+  def total
+    _data._raw['total']
+  end
+
+  def limit
+    _data._raw['limit']
+  end
+
+  def offset
+    _data._raw['offset']
+  end
+
+  def href
+    _data._raw['href']
+  end
+
+  def _collection
+    raw = _data._raw if _data._raw.is_a?(Array)
+    raw ||= _data._raw['items']
+    Collection.new(raw, _data, _data._service)
+  end
+
+  def _raw
+    _data._raw
+  end
+
+  protected
+
+  def method_missing(name, *args, &block)
+    value = _collection.send(name, *args, &block)
+    if value.is_a? Hash
+      data = LHS::Data.new(value, _data)
+      item = LHS::Item.new(data)
+      LHS::Data.new(item, _data)
+    else
+      value
+    end
+  end
+
+  def respond_to_missing?(name, include_all = false)
+    _collection.respond_to?(name, include_all)
+  end
+
+  private
+
+  # The internal collection class that includes enumerable
+  # and insures to return LHS::Items in case of iterating items
+  class Collection
+    include Enumerable
+
+    attr_accessor :raw
+
+    def initialize(raw, parent, service)
+      self.raw = raw
+      @parent = parent
+      @service = service
+    end
+
+    def each(&block)
+      raw.each do |item|
+        if item.is_a? Hash
+          yield LHS::Data.new(item, @parent, @service)
+        else
+          yield item
+        end
+      end
+    end
+
+    delegate :sample, to: :raw
+    delegate :[], to: :raw
+  end
+end

data/lib/lhs/concerns/data/json.rb

@@ -0,0 +1,12 @@
+require 'active_support'
+
+class LHS::Data
+
+  module Json
+    extend ActiveSupport::Concern
+
+    def as_json(options = {})
+      _data._raw.as_json
+    end
+  end
+end

data/lib/lhs/concerns/item/destroy.rb

@@ -0,0 +1,15 @@
+require 'active_support'
+require File.dirname(__FILE__) + '/../../proxy'
+
+class LHS::Item < LHS::Proxy
+
+  module Destroy
+    extend ActiveSupport::Concern
+
+    def destroy
+      service_instance = _data._root._service.instance
+      _data._request = service_instance.request(method: :delete, url: href)._request
+      _data
+    end
+  end
+end

data/lib/lhs/concerns/item/save.rb

@@ -0,0 +1,29 @@
+require 'active_support'
+require File.dirname(__FILE__) + '/../../proxy'
+
+class LHS::Item < LHS::Proxy
+
+  module Save
+    extend ActiveSupport::Concern
+
+    def save
+      save!
+      rescue LHC::Error => e
+        self.errors = LHS::Errors.new(e.response)
+        false
+    end
+
+    def save!
+      service = _data._root._service
+      data = _data._raw.dup
+      url = if href.present?
+       href
+      else
+        service.instance.find_endpoint(data).compile(data)
+      end
+      response = service.instance.request(method: :post, url: url, body: data.to_json, headers: {'Content-Type' => 'application/json'})
+      self._data.merge!(response)
+      true
+    end
+  end
+end

data/lib/lhs/concerns/item/update.rb

@@ -0,0 +1,24 @@
+require 'active_support'
+require File.dirname(__FILE__) + '/../../proxy'
+
+class LHS::Item < LHS::Proxy
+
+  module Update
+    extend ActiveSupport::Concern
+
+    def update(params)
+      update!(params)
+    rescue LHC::Error => e
+      self.errors = LHS::Errors.new(e.response)
+      false
+    end
+
+    def update!(params)
+      service = _data._root._service
+      data = _data._raw.dup
+      response = service.instance.request(method: :post, url: href, body: data.merge(params).to_json, headers: {'Content-Type' => 'application/json'})
+      self._data.merge!(response)
+      true
+    end
+  end
+end

data/lib/lhs/concerns/service/all.rb

@@ -0,0 +1,24 @@
+require 'active_support'
+
+class LHS::Service
+
+  module All
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+
+      def all(params = {})
+        all = []
+        data = instance.request(params: params.merge(limit: 100))
+        all.concat(data._raw['items'])
+        total_left = data._raw['total'] - data.count
+        requests = total_left / data._raw['limit']
+        requests.times do |i|
+          offset = data._raw['limit'] * (i+1) + 1
+          all.concat instance.request(params: params.merge(limit: data._raw['limit'], offset: offset))._raw['items']
+        end
+        LHS::Data.new(all, nil, self)
+      end
+    end
+  end
+end

data/lib/lhs/concerns/service/batch.rb

@@ -0,0 +1,37 @@
+require 'active_support'
+
+class LHS::Service
+
+  module Batch
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+
+      # Process single entries fetched in batches
+      def find_each(options = {})
+        find_in_batches(options) do |data|
+          data.each do |record|
+            item = LHS::Item.new(LHS::Data.new(record, data, self.class))
+            yield LHS::Data.new(item, data, self.class)
+          end
+        end
+      end
+
+      # Process batches of entries
+      def find_in_batches(options = {})
+        fail 'No block given' unless block_given?
+        start = options[:start] || 1
+        batch_size = options[:batch_size] || 100
+        params = options[:params] || {}
+        loop do # as suggested by Matz
+          data = instance.request(params: params.merge(limit: batch_size, offset: start))
+          batch_size = data._raw['limit']
+          left = data._raw['total'].to_i - data._raw['offset'].to_i - data._raw['limit'].to_i
+          yield data
+          break if left <= 0
+          start += batch_size
+        end
+      end
+    end
+  end
+end