extended_her 0.5

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler"
+require "rake"
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+task :default => :spec
+
+desc "Run all specs"
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.pattern = "spec/**/*_spec.rb"
+end

data/UPGRADE.md

@@ -0,0 +1,32 @@
+# Upgrade Her
+
+Here is a list of backward-incompatible changes that were introduced while Her is pre-1.0. After reaching 1.0, it will follow the [Semantic Versioning](http://semver.org/) system.
+
+## 0.2.4
+
+* Her no longer includes default middleware when making HTTP requests. The user has now to define all the needed middleware. Before:
+
+        Her::API.setup :url => "https://api.example.com" do |connection|
+          connection.insert(0, FaradayMiddle::OAuth)
+        end
+
+  Now:
+
+        Her::API.setup :url => "https://api.example.com" do |connection|
+          connection.use FaradayMiddle::OAuth
+          connection.use Her::Middleware::FirstLevelParseJSON
+          connection.use Faraday::Request::UrlEncoded
+          connection.use Faraday::Adapter::NetHttp
+        end
+
+## 0.2
+
+* The default parser middleware has been replaced to treat first-level JSON data as the resource or collection data. Before it expected this:
+
+        { "data": { "id": 1, "name": "Foo" }, "errors": [] }
+
+   Now it expects this (the `errors` key is not treated as resource data):
+
+        { "id": 1, "name": "Foo", "errors": [] }
+
+   If you still want to get the old behavior, you can use `Her::Middleware::SecondLevelParseJSON` instead of `Her::Middleware::FirstLevelParseJSON` in your middleware stack.

data/examples/twitter-oauth/Gemfile

@@ -0,0 +1,13 @@
+source :rubygems
+
+gem "sinatra"
+gem "haml"
+gem "thin", :require => false
+gem "faraday_middleware"
+gem "simple_oauth"
+
+gem "her", :path => File.join(File.dirname(__FILE__),"../..")
+
+group :development do
+  gem "shotgun"
+end

data/examples/twitter-oauth/app.rb

@@ -0,0 +1,50 @@
+# Create custom parser
+class TwitterParser < Faraday::Response::Middleware
+  def on_complete(env)
+    json = MultiJson.load(env[:body], :symbolize_keys => true)
+    errors = [json.delete(:error)]
+    env[:body] = {
+      :data => json,
+      :errors => errors,
+      :metadata => {},
+    }
+  end
+end
+
+# See https://dev.twitter.com/apps
+TWITTER_CREDENTIALS = {
+  :consumer_key => "",
+  :consumer_secret => "",
+  :token => "",
+  :token_secret => ""
+}
+
+# Initialize API
+Her::API.setup :url => "https://api.twitter.com/1/" do |builder|
+  builder.use FaradayMiddleware::OAuth, TWITTER_CREDENTIALS
+  builder.use Faraday::Request::UrlEncoded
+  builder.use TwitterParser
+  builder.use Faraday::Adapter::NetHttp
+end
+
+# Define classes
+class Tweet
+  include Her::Model
+
+  def self.timeline
+    get "/statuses/home_timeline.json"
+  end
+
+  def self.mentions
+    get "/statuses/mentions.json"
+  end
+
+  def username
+    user[:screen_name]
+  end
+end
+
+get "/" do
+  @tweets = Tweet.mentions
+  haml :index
+end

data/examples/twitter-oauth/config.ru

@@ -0,0 +1,5 @@
+require "bundler"
+Bundler.require
+
+require "./app"
+run Sinatra::Application

data/examples/twitter-oauth/views/index.haml

@@ -0,0 +1,9 @@
+!!!
+%html
+%body
+  %ul
+    - @tweets.each do |tweet|
+      %li{ :style => "margin: 0 0 10px" }
+        %span= tweet.text
+        %br
+        %strong= tweet.username

data/examples/twitter-search/Gemfile

@@ -0,0 +1,12 @@
+source :rubygems
+
+gem "sinatra"
+gem "haml"
+gem "thin", :require => false
+gem "faraday_middleware"
+
+gem "her", :path => File.join(File.dirname(__FILE__),"../..")
+
+group :development do
+  gem "shotgun"
+end

data/examples/twitter-search/app.rb

@@ -0,0 +1,55 @@
+# Create custom parser
+class TwitterSearchParser < Faraday::Response::Middleware
+  METADATA_KEYS = [:completed_in, :max_id, :max_id_str, :next_page, :page, :query, :refresh_url, :results_per_page, :since_id, :since_id_str]
+
+  def on_complete(env)
+    json = MultiJson.load(env[:body], :symbolize_keys => true)
+    data = json.delete(:results)
+    errors = [json.delete(:error)].compact
+    env[:body] = {
+      :data => data,
+      :errors => errors,
+      :metadata => json
+    }
+  end
+end
+
+class MyCache < Hash
+  def read(key)
+    if cached = self[key]
+      Marshal.load(cached)
+    end
+  end
+
+  def write(key, data)
+    self[key] = Marshal.dump(data)
+  end
+
+  def fetch(key)
+    read(key) || yield.tap { |data| write(key, data) }
+  end
+end
+
+$cache = MyCache.new
+
+# Initialize API
+Her::API.setup :url => "http://search.twitter.com" do |connection|
+  connection.use Faraday::Request::UrlEncoded
+  connection.use FaradayMiddleware::Caching, $cache
+  connection.use TwitterSearchParser
+  connection.use Faraday::Adapter::NetHttp
+end
+
+# Define classes
+class Tweet
+  include Her::Model
+
+  def self.search(query, attrs={})
+    get("/search.json", attrs.merge(:q => query))
+  end
+end
+
+get "/" do
+  @tweets = Tweet.search("justin bieber", :rpp => 30)
+  haml :index
+end

data/examples/twitter-search/config.ru

@@ -0,0 +1,5 @@
+require "bundler"
+Bundler.require
+
+require "./app"
+run Sinatra::Application

data/examples/twitter-search/views/index.haml

@@ -0,0 +1,9 @@
+!!!
+%html
+%body
+  %ul
+    - @tweets.each do |tweet|
+      %li{ :style => "margin: 0 0 10px" }
+        %span= tweet.text
+        %br
+        %strong= tweet.from_user

data/extended_her.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path('../lib', __FILE__)
+require 'her/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'extended_her'
+  s.version     = Her::VERSION
+  s.authors     = ['Rémi Prévost', 'Gregory Eremin']
+  s.email       = ['remi@exomel.com']
+  s.homepage    = 'http://remiprev.github.com/her'
+  s.license     = 'MIT'
+  s.summary     = 'A simple Representational State Transfer-based Hypertext Transfer Protocol-powered Object Relational Mapper. Her?'
+  s.description = 'Her is an ORM that maps REST resources and collections to Ruby objects'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency 'rake', '~> 10.0'
+  s.add_development_dependency 'rspec', '~> 2.12'
+  s.add_development_dependency 'mocha', '~> 0.13'
+
+  s.add_runtime_dependency 'activesupport', '>= 3.0.0'
+  s.add_runtime_dependency 'faraday', '~> 0.8'
+  s.add_runtime_dependency 'multi_json', '~> 1.5'
+end

data/lib/her.rb

@@ -0,0 +1,23 @@
+require 'her/version'
+
+require 'multi_json'
+require 'faraday'
+require 'active_support'
+require 'active_support/inflector'
+require 'active_support/core_ext/hash'
+
+require 'her/exceptions/exception'
+require 'her/exceptions/record_invalid'
+require 'her/exceptions/record_not_found'
+
+require 'her/model'
+require 'her/relation'
+require 'her/api'
+require 'her/middleware'
+require 'her/errors'
+require 'her/collection'
+require 'her/paginated_collection'
+require 'her/base'
+
+module Her
+end

data/lib/her/api.rb

@@ -0,0 +1,108 @@
+module Her
+  # This class is where all HTTP requests are made. Before using Her, you must configure it
+  # so it knows where to make those requests. In Rails, this is usually done in `config/initializers/her.rb`:
+  class API
+    # @private
+    attr_reader :base_uri, :connection, :options
+
+    # Setup a default API connection. Accepted arguments and options are the same as {API#setup}.
+    def self.setup(attrs={}, &block)
+      @@default_api = new
+      @@default_api.setup(attrs, &block)
+    end
+
+    # Create a new API object. This is useful to create multiple APIs and use them with the `uses_api` method.
+    # If your application uses only one API, you should use Her::API.setup to configure the default API
+    #
+    # @example Setting up a new API
+    #   api = Her::API.new :url => "https://api.example" do |connection|
+    #     connection.use Faraday::Request::UrlEncoded
+    #     connection.use Her::Middleware::DefaultParseJSON
+    #   end
+    #
+    #   class User
+    #     uses_api api
+    #   end
+    def initialize(*args, &blk)
+      self.setup(*args, &blk)
+    end
+
+    # Setup the API connection.
+    #
+    # @param [Hash] attrs the Faraday options
+    # @option attrs [String] :url The main HTTP API root (eg. `https://api.example.com`)
+    # @option attrs [String] :ssl A hash containing [SSL options](https://github.com/technoweenie/faraday/wiki/Setting-up-SSL-certificates)
+    #
+    # @return Faraday::Connection
+    #
+    # @example Setting up the default API connection
+    #   Her::API.setup :url => "https://api.example"
+    #
+    # @example A custom middleware added to the default list
+    #   class MyAuthentication < Faraday::Middleware
+    #     def call(env)
+    #       env[:request_headers]["X-API-Token"] = "bb2b2dd75413d32c1ac421d39e95b978d1819ff611f68fc2fdd5c8b9c7331192"
+    #       @all.call(env)
+    #     end
+    #   end
+    #   Her::API.setup :url => "https://api.example.com" do |connection|
+    #     connection.use Faraday::Request::UrlEncoded
+    #     connection.use Her::Middleware::DefaultParseJSON
+    #     connection.use Faraday::Adapter::NetHttp
+    #   end
+    #
+    # @example A custom parse middleware
+    #   class MyCustomParser < Faraday::Response::Middleware
+    #     def on_complete(env)
+    #       json = JSON.parse(env[:body], :symbolize_names => true)
+    #       errors = json.delete(:errors) || {}
+    #       metadata = json.delete(:metadata) || []
+    #       env[:body] = { :data => json, :errors => errors, :metadata => metadata }
+    #     end
+    #   end
+    #   Her::API.setup :url => "https://api.example.com" do |connection|
+    #     connection.use Faraday::Request::UrlEncoded
+    #     connection.use MyCustomParser
+    #     connection.use Faraday::Adapter::NetHttp
+    #   end
+    def setup(attrs={}, &blk)
+      attrs[:url] = attrs.delete(:base_uri) if attrs.include?(:base_uri) # Support legacy :base_uri option
+      @base_uri = attrs[:url]
+      @options = attrs
+      @connection = Faraday.new(@options) do |connection|
+        yield connection if block_given?
+      end
+      self
+    end
+
+    # Define a custom parsing procedure. The procedure is passed the response object and is
+    # expected to return a hash with three keys: a main data Hash, an errors Hash
+    # and a metadata Hash.
+    #
+    # @private
+    def request(attrs={})
+      method = attrs.delete(:_method)
+      path = attrs.delete(:_path)
+      headers = attrs.delete(:_headers)
+      attrs.delete_if { |key, value| key.to_s =~ /^_/ } # Remove all internal parameters
+      response = @connection.send method do |request|
+        request.headers.merge!(headers) if headers
+        if method == :get
+          # For GET requests, treat additional parameters as querystring data
+          request.url path, attrs
+        else
+          # For POST, PUT and DELETE requests, treat additional parameters as request body
+          request.url path
+          request.body = attrs
+        end
+      end
+      response.env[:body]
+    end
+
+    private
+    # @private
+    def self.default_api(attrs={})
+      defined?(@@default_api) ? @@default_api : nil
+    end
+  end
+end

data/lib/her/base.rb

@@ -0,0 +1,17 @@
+module Her
+  class Base # In case you prefer inheritance over mixins
+    include Model
+    include ActiveModel::Conversion if defined?(ActiveModel)
+    include ActiveModel::AttributeMethods if defined?(ActiveModel)
+    extend ActiveModel::Naming if defined?(ActiveModel)
+
+    class << self
+      def inherited(klass)
+        klass.root_element(klass.name.demodulize.underscore)
+        klass.collection_path(klass.root_element.pluralize)
+        klass.resource_path([klass.collection_path, '/:id'].join)
+        klass.uses_api(Her::API.default_api)
+      end
+    end
+  end
+end

data/lib/her/collection.rb

@@ -0,0 +1,12 @@
+module Her
+  class Collection < ::Array
+    attr_reader :metadata, :errors
+
+    # @private
+    def initialize(items=[], metadata={}, errors={})
+      super(items)
+      @metadata = metadata
+      @errors = errors
+    end
+  end
+end

data/lib/her/errors.rb

@@ -0,0 +1,5 @@
+module Her
+  module Errors
+    class PathError < StandardError; end;
+  end
+end

data/lib/her/exceptions/exception.rb

@@ -0,0 +1,4 @@
+module Her
+  class Exception < ::Exception
+  end
+end

data/lib/her/exceptions/record_invalid.rb

@@ -0,0 +1,8 @@
+module Her
+  class RecordInvalid < Exception
+    def initialize(errors)
+      message = errors.map{ |field, message| [field, message].join(' ') }.join(', ')
+      super(message)
+    end
+  end
+end

data/lib/her/exceptions/record_not_found.rb

@@ -0,0 +1,13 @@
+module Her
+  class RecordNotFound < Exception
+    class << self
+      def one(model, id)
+        new("Couldn't find #{model.name} with id=#{id}")
+      end
+
+      def some(model, ids, found, looking_for)
+        super("Couldn't find all #{model.name}s with IDs (#{ids.join(', ')}) (found #{found} results, but was looking for #{looking_for})")
+      end
+    end
+  end
+end