leadlight 0.0.2 → 0.0.3

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    leadlight (0.0.1)
+    leadlight (0.0.2)
+      addressable
       faraday
       fattr
       hookr
@@ -20,7 +21,7 @@ GEM
     faraday (0.7.5)
       addressable (~> 2.2.6)
       multipart-post (~> 1.1.3)
-      rack (< 2, >= 1.1.0)
+      rack (>= 1.1.0, < 2)
     fattr (2.2.0)
     ffi (1.0.11)
     guard (0.10.0)
@@ -33,7 +34,6 @@ GEM
       guard (>= 0.10.0)
     hookr (1.1.1)
       fail-fast (= 1.0.0)
-    libnotify (0.7.1)
     linecache19 (0.5.12)
       ruby_core_source (>= 0.1.4)
     link_header (0.0.5)
@@ -41,8 +41,7 @@ GEM
     multi_json (1.0.4)
     multipart-post (1.1.4)
     rack (1.4.0)
-    rb-inotify (0.8.8)
-      ffi (>= 0.5.0)
+    rake (0.9.2.2)
     rspec (2.7.0)
       rspec-core (~> 2.7.0)
       rspec-expectations (~> 2.7.0)
@@ -72,8 +71,7 @@ DEPENDENCIES
   guard-bundler
   guard-rspec
   leadlight!
-  libnotify
-  rb-inotify
+  rake
   rspec
   ruby-debug19
   vcr (~> 2.0.0.rc1)

data/README.md

@@ -0,0 +1,82 @@
+# Leadlight [![Build Status](https://secure.travis-ci.org/avdi/leadlight.png)](http://travis-ci.org/avdi/leadlight)
+
+Rose colored stained glass windows for HTTP.
+
+
+## Goals
+
+### Progressive enhancement for HTTP APIs
+
+Don't cover up the web; just fill in the gaps here and there. Make it easy to
+add links and other affordances API publishers might have forgotten.
+
+### Model RESTful APIs as a web of links
+
+Don't try to make the web look like a database.
+
+### Representations over resources
+
+Resources are the server's job to worry about. The things we get back from a
+server are representations. Take representations at face value and interpret
+them sensibly, rather than trying to fit them into a client-side model of an
+imaginary server-side object graph.
+
+### Support current and emerging standards
+
+Such as the [Link header][], [URI templates][], [PATCH][], [ETags][], and
+[JSON-schema][].
+
+### Sensible defaults
+
+Always try to convert representations returned by the server into a form that is
+useful to the programmer--whether that is a Hash parsed from JSON data, a
+Nokogiri document, or a text string.
+
+### Backend agnostic
+
+Using the power of [Faraday][].
+
+### Exception-free
+
+Only raise exceptions in API calls which explicitly request them. Provide ample
+information to explain the cause of a failure.
+
+### Async-ready
+
+Architected from the ground up with asynchrony in mind. It's easier to build a
+synchronous API on top of an async one than vice-versa.
+
+### Controlled abstraction leakage
+
+All abstractions are leaky. Provide ample and convenient access points into the
+guts of the request lifecycle for situations when the defaults are not
+sufficient.
+
+### Quality
+
+Code quality is important. [Code Climate][] keeps a
+[close eye on Leadlight][leadlight_climate] instilling confidence and showing
+how any technical debt can be paid down.
+
+
+[link header]:       http://tools.ietf.org/html/draft-nottingham-http-link-header
+[uri templates]:     http://tools.ietf.org/html/draft-gregorio-uritemplate
+[patch]:             http://tools.ietf.org/html/rfc5789
+[etags]:             http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19
+[json-schema]:       http://tools.ietf.org/html/draft-zyp-json-schema
+[faraday]:           https://github.com/technoweenie/faraday
+[code climate]:      https://codeclimate.com
+[leadlight_climate]: https://codeclimate.com/github/avdi/leadlight
+
+
+## Installation
+
+```ruby
+gem 'leadlight'
+```
+
+## Usage
+
+_See
+[leadlight_spec.rb](https://github.com/avdi/leadlight/blob/master/spec/leadlight_spec.rb)
+for now._

data/default.gems

@@ -0,0 +1 @@
+bundler -v1.0.21

data/leadlight.gemspec

@@ -13,14 +13,14 @@ Gem::Specification.new do |s|
   ## If your rubyforge_project name is different, then edit it and comment out
   ## the sub! line in the Rakefile
   s.name              = 'leadlight'
-  s.version           = '0.0.2'
-  s.date              = '2012-01-09'
+  s.version           = '0.0.3'
+  s.date              = '2012-02-05'
   s.rubyforge_project = 'leadlight'
 
   ## Make sure your summary is short. The description may be as long
   ## as you like.
-  s.summary     = "Short description used in Gem listings."
-  s.description = "Long description. Maybe copied from the README."
+  s.summary     = "Rose colored stained glass windows for HTTP."
+  s.description = "Rose colored stained glass windows for HTTP."
 
   ## List the primary authors. If there are a bunch of authors, it's probably
   ## better to set the email to an email list or something. If you don't have
@@ -41,6 +41,7 @@ Gem::Specification.new do |s|
   ## List your runtime dependencies here. Runtime dependencies are those
   ## that are needed for an end user to actually USE your code.
   ## s.add_dependency('DEPNAME', [">= 1.1.0", "< 2.0.0"])
+  s.add_dependency 'addressable'
   s.add_dependency 'faraday'
   s.add_dependency 'fattr'
   s.add_dependency 'link_header'
@@ -51,6 +52,7 @@ Gem::Specification.new do |s|
   ## List your development dependencies here. Development dependencies are
   ## those that are only needed during development
   ## s.add_development_dependency('DEVDEPNAME', [">= 1.1.0", "< 2.0.0"])
+  s.add_development_dependency 'rake'
   s.add_development_dependency 'rspec'
   s.add_development_dependency 'vcr', '~> 2.0.0.rc1'
   s.add_development_dependency 'guard'
@@ -66,27 +68,33 @@ Gem::Specification.new do |s|
     Gemfile
     Gemfile.lock
     Guardfile
+    README.md
     Rakefile
+    default.gems
     leadlight.gemspec
     lib/leadlight.rb
+    lib/leadlight/basic_converter.rb
     lib/leadlight/blank.rb
     lib/leadlight/codec.rb
+    lib/leadlight/entity.rb
     lib/leadlight/enumerable_representation.rb
     lib/leadlight/errors.rb
+    lib/leadlight/header_helpers.rb
     lib/leadlight/hyperlinkable.rb
     lib/leadlight/link.rb
     lib/leadlight/link_template.rb
     lib/leadlight/representation.rb
     lib/leadlight/request.rb
     lib/leadlight/service.rb
+    lib/leadlight/service_class_methods.rb
     lib/leadlight/service_middleware.rb
     lib/leadlight/tint.rb
     lib/leadlight/tint_helper.rb
-    lib/leadlight/type.rb
+    lib/leadlight/type_map.rb
     spec/cassettes/Leadlight/authorized_GitHub_example/_user/has_the_expected_content.yml
     spec/cassettes/Leadlight/authorized_GitHub_example/_user/indicates_the_expected_oath_scopes.yml
     spec/cassettes/Leadlight/authorized_GitHub_example/adding_and_removing_team_members.yml
-    spec/cassettes/Leadlight/authorized_GitHub_example/adding_and_removing_team_members/.yml
+    spec/cassettes/Leadlight/authorized_GitHub_example/adding_and_removing_teams.yml
     spec/cassettes/Leadlight/authorized_GitHub_example/test_team/.yml
     spec/cassettes/Leadlight/basic_GitHub_example/_root/.yml
     spec/cassettes/Leadlight/basic_GitHub_example/_root/__location__/.yml
@@ -111,7 +119,8 @@ Gem::Specification.new do |s|
     spec/leadlight/service_middleware_spec.rb
     spec/leadlight/service_spec.rb
     spec/leadlight/tint_helper_spec.rb
-    spec/leadlight/type_spec.rb
+    spec/leadlight/tint_spec.rb
+    spec/leadlight/type_map_spec.rb
     spec/leadlight_spec.rb
     spec/spec_helper_lite.rb
     spec/support/credentials.rb

data/lib/leadlight.rb

@@ -1,27 +1,37 @@
 require 'faraday'
 require 'fattr'
 require 'logger'
+require 'hookr'
 require 'leadlight/errors'
 require 'leadlight/link'
 require 'leadlight/hyperlinkable'
 require 'leadlight/service_middleware'
 require 'leadlight/representation'
 require 'leadlight/tint'
-require 'leadlight/type'
 require 'leadlight/service'
+require 'leadlight/service_class_methods'
 require 'leadlight/enumerable_representation'
+require 'leadlight/basic_converter'
 
 
 module Leadlight
 
-  VERSION = '0.0.2'
-
-  def self.build_service(target, &block)
-    target.module_eval do
-      extend ServiceClassMethods
-      include Service
+  VERSION = '0.0.3'
+
+  def self.build_service(target=Class.new, &block)
+    target.tap do
+      target.module_eval do
+        extend ServiceClassMethods
+        include Service
+        include HookR::Hooks
+        extend SingleForwardable
+        
+        request_events = request_class.hooks.map(&:name)
+        def_delegators :request_class, *request_events
+        define_hook :on_init, :service
+      end
+      target.module_eval(&block)
     end
-    target.module_eval(&block)
   end
 
   def self.build_connection_common(&common_connection_stack)
@@ -34,59 +44,5 @@ module Leadlight
     }
   end
 
-  module ServiceClassMethods
-    fattr(:tints) { default_tints }
-    fattr(:types) { []            }
-
-    def url(new_url=:none)
-      if new_url == :none
-        @url ||= Addressable::URI.parse('http://example.com')
-      else
-        @url = Addressable::URI.parse(new_url)
-      end
-    end
-
-    def session(options={})
-      sessions[options]
-    end
-
-    def sessions
-      @sessions ||= Hash.new{|h,k|
-        h[k] = new(k)
-      }
-    end
-
-    def connection_stack
-      @connection_stack ||= ->(builder){}
-    end
-
-    def default_tints
-      [
-       EnumerableRepresentation::Tint
-      ]
-    end
-
-    private
-
-    def tint(name, &block)
-      self.tints << Tint.new(name, &block)
-    end
-
-    def type(name, &block)
-      self.types << Type.new(name, self, &block)
-    end
-
-    def type_for_name(name)
-      raise_on_missing = -> do
-        raise KeyError, "Type not found: #{name}"
-      end
-      types.detect(raise_on_missing){|type| type.name.to_s == name.to_s}
-    end
-
-    def build_connection(&block)
-      @connection_stack = block
-    end
-
-  end
 
 end

data/lib/leadlight/basic_converter.rb

@@ -0,0 +1,18 @@
+module Leadlight
+  module BasicConverter
+    fattr(:codec) { Codec.new }
+
+    def initialize(codec)
+      @codec = codec
+    end
+
+    def decode_with_type(content_type, entity_body, options={})
+      codec.decode(content_type, entity_body, options)
+    end
+
+    def encode_with_type(content_type, object, options={})
+      body = codec.encode(content_type, object, options)
+      Entity.new(content_type, body)
+    end
+  end
+end

data/lib/leadlight/codec.rb

@@ -1,3 +1,5 @@
+require 'multi_json'
+
 module Leadlight
   class Codec
     Strategy ||= Struct.new(:name, :encoder, :decoder, :patterns)

data/lib/leadlight/entity.rb

@@ -0,0 +1 @@
+Entity ||= Struct.new(:content_type, :body)

data/lib/leadlight/errors.rb

@@ -1,14 +1,22 @@
+require 'forwardable'
+
 module Leadlight
   class Error < StandardError; end
   class CredentialsRequiredError < Error; end
   class HttpError < Error
+    extend Forwardable
+
     attr_reader :response
-    def initialize(response)
+
+    def_delegator :response, :status
+
+    def initialize(response, message=response.status.to_s)
       @response = response
-      super("HTTP Error #{response.status}")
+      super(message)
     end
   end
   class ClientError < HttpError; end
   class ResourceNotFound < ClientError; end
   class ServerError < HttpError; end
+  class TypeError < Error; end
 end

data/lib/leadlight/header_helpers.rb

@@ -0,0 +1,11 @@
+module Leadlight
+  module HeaderHelpers
+    def clean_content_type(content_type)
+      unless content_type.nil?
+        mimetype = MIME::Type.new(content_type)
+        content_type = "#{mimetype.media_type}/#{mimetype.sub_type}"
+      end
+      content_type
+    end
+  end
+end

data/lib/leadlight/hyperlinkable.rb

@@ -10,7 +10,7 @@ module Leadlight
   module Hyperlinkable
     def self.extended(representation)
       super(representation)
-      representation.add_link(representation.__response__.env[:url],
+      representation.add_link(representation.__location__,
                               'self', 'self', rev: 'self')
       representation.add_links_from_headers
     end

data/lib/leadlight/representation.rb

@@ -1,12 +1,12 @@
 require 'addressable/uri'
 require 'leadlight/link'
+require 'leadlight/errors'
 
 module Leadlight
   module Representation
     attr_accessor :__service__
     attr_accessor :__location__
     attr_accessor :__response__
-    attr_accessor :__type__
 
     def initialize_representation(service, location, response)
       self.__service__ = service
@@ -21,6 +21,24 @@ module Leadlight
       self
     end
 
+    def exception(message=exception_message)
+      return super if defined?(super)
+      case __response__.status.to_i
+      when 404 then ResourceNotFound
+      when (400..499) then ClientError
+      when (500..599) then ServerError
+      end.new(__response__, exception_message)
+    end
+
+    def exception_message
+      http_status_message
+    end
+
+    def http_status_message
+      __response__.env.fetch(:response_headers).fetch('status'){
+        status.to_s
+      }
+    end
 
     private
 

data/lib/leadlight/request.rb

@@ -1,35 +1,49 @@
 require 'monitor'
 require 'fattr'
+require 'forwardable'
 require 'hookr'
 require 'leadlight/errors'
+require 'leadlight/blank'
+require 'leadlight/hyperlinkable'
+require 'leadlight/representation'
+require 'leadlight/type_map'
+require 'leadlight/header_helpers'
 
 module Leadlight
   class Request
     include HookR::Hooks
     include MonitorMixin
+    extend Forwardable
+    include HeaderHelpers
 
     fattr(:http_method)
     fattr(:url)
     fattr(:connection)
     fattr(:body)
     fattr(:params)
+    fattr(:service)
+    fattr(:codec)
+    fattr(:type_map) { service.type_map || TypeMap.new }
 
     attr_reader :response    
 
     define_hook :on_prepare_request, :request
     define_hook :on_complete,        :response
 
-    def initialize(connection, url, method, params={}, body=nil)
+    def_delegator :service, :service_options
+
+    def initialize(service, connection, url, method, params={}, body=nil)
       self.connection  = connection
       self.url         = url
       self.http_method = method
       self.body        = body
       self.params      = params
+      self.service     = service
       @completed       = new_cond
       @state           = :initialized
       @env             = nil
       @response        = nil
-      super
+      super()
     end
 
     def completed?
@@ -37,11 +51,16 @@ module Leadlight
     end
 
     def submit
-      connection.run_request(http_method, url, body, {}) do |request|
+      entity = type_map.to_entity_body(body)
+      entity_body = entity.body
+      content_type = entity.content_type
+      connection.run_request(http_method, url, entity_body, {}) do |request|
+        request.headers['Content-Type'] = content_type if content_type
+        request.options[:leadlight_request] = self        
         execute_hook(:on_prepare_request, request)
       end.on_complete do |env|
         synchronize do
-          @response = Faraday::Response.new(env)
+          @response = env.fetch(:response)
           execute_hook :on_complete, @response
           @env = env
           @state = :completed
@@ -66,13 +85,8 @@ module Leadlight
 
     def raise_on_error
       on_or_after_complete do |response|
-        case response.status.to_i
-        when 404
-          raise ResourceNotFound, response
-        when (400..499)
-          raise ClientError, response
-        when (500..599)
-          raise ServerError, response
+        unless response.success?
+          raise response.env.fetch(:leadlight_representation)
         end
       end
       self
@@ -87,5 +101,24 @@ module Leadlight
         end
       end
     end
+
+    def represent(env)      
+      content_type = env[:response_headers]['Content-Type']
+      content_type = clean_content_type(content_type)
+      representation = type_map.to_native(content_type, env[:body])
+      location = Addressable::URI.parse(env[:response_headers].fetch('location'){ env[:url] })
+      representation.
+        extend(Representation).
+        initialize_representation(env[:leadlight_service], location, env[:response]).
+        extend(Hyperlinkable).
+        apply_all_tints
+    end
+
+    private
+
+    def representation
+      raise "No representation until complete" unless completed?
+      @env.fetch(:leadlight_representation)
+    end
   end
 end