hyperresource-aptible 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8016963a4231079f134bfe019e5d8092f355321f
+  data.tar.gz: c51ccfdd3523321c47d9d9efb7a80c9039026407
+SHA512:
+  metadata.gz: 91c88986ff52e6fe1f693559c887988de9dcfed25d8517b9f37d45f7e5b30609313647e7cdf9eaa97a833e6b9ccdfc215a8b13936eab0d86344461c535df6540
+  data.tar.gz: f0bcd175f570e738f7bb79452fb847d49adf67a02b6659bec16ed2e6fa9c6d2fa0fcaf7b31e42a8245be30a1930c3349919ede76e15d681b46017232bdf1bbb7

data/lib/hyper_resource.rb

@@ -0,0 +1,302 @@
+require 'hyper_resource/attributes'
+require 'hyper_resource/exceptions'
+require 'hyper_resource/link'
+require 'hyper_resource/links'
+require 'hyper_resource/objects'
+require 'hyper_resource/response'
+require 'hyper_resource/version'
+
+require 'hyper_resource/adapter'
+require 'hyper_resource/adapter/hal_json'
+
+require 'hyper_resource/modules/http'
+require 'hyper_resource/modules/internal_attributes'
+
+require 'rubygems' if RUBY_VERSION[0..2] == '1.8'
+
+require 'pp'
+
+## HyperResource is the main resource base class.  Normally it will be used
+## through subclassing, though it may also be used directly.
+
+class HyperResource
+
+  include HyperResource::Modules::HTTP
+  include HyperResource::Modules::InternalAttributes
+  include Enumerable
+
+private
+
+  DEFAULT_HEADERS = { 'Accept' => 'application/json' }
+
+public
+
+  ## Create a new HyperResource, given a hash of options.  These options
+  ## include:
+  ##
+  ## [root]  The root URL of the resource.
+  ##
+  ## [auth]  Authentication information.  Currently only +{basic:
+  ##         ['key', 'secret']}+ is supported.
+  ##
+  ## [namespace] Class or class name, into which resources should be
+  ##             instantiated.
+  ##
+  ## [headers] Headers to send along with requests for this resource (as
+  ##           well as its eventual child resources, if any).
+  ##
+  ## [faraday_options] Configuration passed to +Faraday::Connection.initialize+,
+  ##                   such as +{request: {timeout: 30}}+.
+  ##
+  def initialize(opts={})
+    return init_from_resource(opts) if opts.kind_of?(HyperResource)
+
+    self.root       = opts[:root] || self.class.root
+    self.href       = opts[:href] || ''
+    self.auth       = (self.class.auth || {}).merge(opts[:auth] || {})
+    self.namespace  = opts[:namespace] || self.class.namespace
+    self.headers    = DEFAULT_HEADERS.merge(self.class.headers || {}).
+                                      merge(opts[:headers]     || {})
+    self.faraday_options = opts[:faraday_options] ||
+                               self.class.faraday_options || {}
+
+    ## There's a little acrobatics in getting Attributes, Links, and Objects
+    ## into the correct subclass.
+    if self.class != HyperResource
+      if self.class::Attributes == HyperResource::Attributes
+        Object.module_eval(
+          "class #{self.class}::Attributes < HyperResource::Attributes; end"
+        )
+      end
+      if self.class::Links == HyperResource::Links
+        Object.module_eval(
+          "class #{self.class}::Links < HyperResource::Links; end"
+        )
+      end
+      if self.class::Objects == HyperResource::Objects
+        Object.module_eval(
+          "class #{self.class}::Objects < HyperResource::Objects; end"
+        )
+      end
+    end
+
+    self.attributes = self.class::Attributes.new(self)
+    self.links      = self.class::Links.new(self)
+    self.objects    = self.class::Objects.new(self)
+
+    self.loaded     = false
+
+    self.adapter    = opts[:adapter] || self.class.adapter ||
+                      HyperResource::Adapter::HAL_JSON
+  end
+
+
+  ## Returns true if one or more of this object's attributes has been
+  ## reassigned.
+  def changed?(*args)
+    attributes.changed?(*args)
+  end
+
+
+  #### Filters
+
+  ## +incoming_body_filter+ filters a hash of attribute keys and values
+  ## on their way from a response body to a HyperResource.  Override this
+  ## in a subclass of HyperResource to implement filters on incoming data.
+  def incoming_body_filter(attr_hash)
+    attr_hash
+  end
+
+  ## +outgoing_body_filter+ filters a hash of attribute keys and values
+  ## on their way from a HyperResource to a request body.  Override this
+  ## in a subclass of HyperResource to implement filters on outgoing data.
+  def outgoing_body_filter(attr_hash)
+    attr_hash
+  end
+
+  ## +outgoing_uri_filter+ filters a hash of attribute keys and values
+  ## on their way from a HyperResource to a URL.  Override this
+  ## in a subclass of HyperResource to implement filters on outgoing URI
+  ## parameters.
+  def outgoing_uri_filter(attr_hash)
+    attr_hash
+  end
+
+
+  #### Enumerable support
+
+  ## Returns the *i*th object in the first collection of objects embedded
+  ## in this resource.  Returns nil on failure.
+  def [](i)
+    get unless loaded
+    self.objects.first[1][i] rescue nil
+  end
+
+  ## Iterates over the objects in the first collection of embedded objects
+  ## in this resource.
+  def each(&block)
+    get unless loaded
+    self.objects.first[1].each(&block) rescue nil
+  end
+
+  #### Magic
+
+  ## method_missing will load this resource if not yet loaded, then
+  ## attempt to delegate to +attributes+, then +objects+, then +links+.
+  ## Override with care.
+  def method_missing(method, *args)
+    self.get unless self.loaded
+
+    method = method.to_s
+    if method[-1,1] == '='
+      return attributes[method[0..-2]] = args.first if attributes[method[0..-2]]
+    else
+      return attributes[method] if attributes && attributes.has_key?(method)
+      return objects[method] if objects && objects[method]
+      if links && links[method]
+        if args.count > 0
+          return links[method].where(*args)
+        else
+          return links[method]
+        end
+      end
+    end
+
+    raise NoMethodError, "undefined method `#{method}' for #{self.inspect}"
+  end
+
+
+  def inspect # @private
+    "#<#{self.class}:0x#{"%x" % self.object_id} @root=#{self.root.inspect} "+
+    "@href=#{self.href.inspect} @loaded=#{self.loaded} "+
+    "@namespace=#{self.namespace.inspect} ...>"
+  end
+
+  ## +response_body+, +response_object+, and +deserialized_response+
+  ##  are deprecated in favor of +body+.  (Sorry. Naming things is hard.)
+  def response_body # @private
+    _hr_deprecate('HyperResource#response_body is deprecated. '+
+                  'Please use HyperResource#body instead.')
+    body
+  end
+  def response_object # @private
+    _hr_deprecate('HyperResource#response_object is deprecated. '+
+                  'Please use HyperResource#body instead.')
+    body
+  end
+  def deserialized_response # @private
+    _hr_deprecate('HyperResource#deserialized_response is deprecated. '+
+                  'Please use HyperResource#body instead.')
+    body
+  end
+
+
+
+  ## Return a new HyperResource based on this object and a given href.
+  def _hr_new_from_link(href) # @private
+    self.class.new(:root            => self.root,
+                   :auth            => self.auth,
+                   :headers         => self.headers,
+                   :namespace       => self.namespace,
+                   :faraday_options => self.faraday_options,
+                   :href            => href)
+  end
+
+
+  ## Returns the class into which the given response should be cast.
+  ## If the object is not loaded yet, or if +namespace+ is
+  ## not set, returns +self+.
+  ##
+  ## Otherwise, +response_class+ uses +get_data_type_from_response+ to
+  ## determine subclass name, glues it to the given namespace, and
+  ## creates the class if it's not there yet. E.g., given a namespace of
+  ## +FooAPI+ and a response content-type of
+  ## "application/vnd.foocorp.fooapi.v1+json;type=User", this should
+  ## return +FooAPI::User+ (even if +FooAPI::User+ hadn't existed yet).
+  def self.response_class(response, namespace)
+    if self.to_s == 'HyperResource'
+      return self unless namespace
+    end
+
+    namespace ||= self.to_s
+
+    type_name = self.get_data_type_from_response(response)
+    return self unless type_name
+
+    namespaced_class(type_name, namespace)
+  end
+
+  def self.namespaced_class(type_name, namespace)
+    class_name = "#{namespace}::#{type_name}"
+    class_name.gsub!(/[^_0-9A-Za-z:]/, '')  ## sanitize class_name
+
+    ## Return data type class if it exists
+    klass = eval(class_name) rescue :sorry_dude
+    return klass if klass.is_a?(Class)
+
+    ## Data type class didn't exist -- create namespace (if necessary),
+    ## then the data type class
+    if namespace != ''
+      nsc = eval(namespace) rescue :bzzzzzt
+      unless nsc.is_a?(Class)
+        Object.module_eval "class #{namespace} < #{self}; end"
+      end
+    end
+    Object.module_eval "class #{class_name} < #{namespace}; end"
+    eval(class_name)
+  end
+
+  def _hr_response_class # @private
+    self.namespace ||= self.class.to_s unless self.class.to_s=='HyperResource'
+    self.class.response_class(self.response, self.namespace)
+  end
+
+
+  ## Inspects the given Faraday::Response, and returns a string describing
+  ## this resource's data type.
+  ##
+  ## By default, this method looks for a +type=...+ modifier in the
+  ## response's +Content-type+ and returns that value, capitalized.
+  ##
+  ## Override this method in a subclass to alter HyperResource's behavior.
+  def self.get_data_type_from_response(response)
+    return nil unless response
+    return nil unless content_type = response['content-type']
+    return nil unless m=content_type.match(/;\s* type=([0-9A-Za-z:]+)/x)
+    m[1][0,1].upcase + m[1][1..-1]
+  end
+
+  ## Uses +HyperResource.get_response_data_type+ to determine the proper
+  ## data type for this object.  Override to change behavior (though you
+  ## probably just want to override the class method).
+  def get_data_type_from_response
+    self.class.get_data_type_from_response(self.response)
+  end
+
+private
+
+  ## Return this object, "cast" into its proper response class.
+  def to_response_class
+    response_class = self._hr_response_class
+    return self if self.class == response_class
+    response_class.new(self)
+  end
+
+  ## Use the given resource's data to initialize this one.
+  def init_from_resource(resource)
+    (self.class._hr_attributes - [:attributes, :links, :objects]).each do |attr|
+      self.send("#{attr}=".to_sym, resource.send(attr))
+    end
+    self.adapter.apply(self.body, self)
+  end
+
+
+  ## Show a deprecation message.
+  def self._hr_deprecate(message) # @private
+    STDERR.puts "#{message} (called from #{caller[2]})"
+  end
+
+  def _hr_deprecate(*args) # @private
+    self.class._hr_deprecate(*args)
+  end
+end

data/lib/hyper_resource/adapter.rb

@@ -0,0 +1,31 @@
+class HyperResource
+
+  ## HyperResource::Adapter is the interface/abstract base class for 
+  ## adapters to different hypermedia formats (e.g., HAL+JSON).  New
+  ## adapters must implement the public methods of this class.
+
+  class Adapter
+    class << self
+
+      ## Serialize the given object into a string.
+      def serialize(object)
+        raise NotImplementedError, "This is an abstract method -- subclasses "+
+          "of HyperResource::Adapter must implement it."
+      end
+
+      ## Deserialize a given string into an object (Hash).
+      def deserialize(string)
+        raise NotImplementedError, "This is an abstract method -- subclasses "+
+          "of HyperResource::Adapter must implement it."
+      end
+
+      ## Use a given deserialized response object (Hash) to update a given
+      ## resource (HyperResource), returning the updated resource.
+      def apply(response, resource, opts={})
+        raise NotImplementedError, "This is an abstract method -- subclasses "+
+          "of HyperResource::Adapter must implement it."
+      end
+
+    end
+  end
+end

data/lib/hyper_resource/adapter/hal_json.rb

@@ -0,0 +1,135 @@
+require 'rubygems' if RUBY_VERSION[0..2] == '1.8'
+require 'json'
+
+class HyperResource
+  class Adapter
+
+    ## HyperResource::Adapter::HAL_JSON provides support for the HAL+JSON
+    ## hypermedia format by implementing the interface defined in
+    ## HyperResource::Adapter.
+
+    class HAL_JSON < Adapter
+      class << self
+
+        def serialize(object)
+          JSON.dump(object)
+        end
+
+        def deserialize(string)
+          JSON.parse(string)
+        end
+
+        def apply(response, resource, opts={})
+          if !response.kind_of?(Hash)
+            raise ArgumentError, "'response' argument must be a Hash"
+          end
+          if !resource.kind_of?(HyperResource)
+            raise ArgumentError, "'resource' argument must be a HyperResource"
+          end
+
+          apply_objects(response, resource)
+          apply_links(response, resource)
+          apply_attributes(response, resource)
+          resource.loaded = true
+          resource.href = response['_links']['self']['href'] rescue nil
+          resource
+        end
+
+
+      private
+
+        def apply_objects(resp, rsrc)
+          return unless resp['_embedded']
+          rc = rsrc.class
+          rsrc.objects = rc::Objects.new(rsrc)
+          objs = rsrc.objects
+
+          resp['_embedded'].each do |name, collection|
+            if collection.is_a? Hash
+              r = rc.new(:root => rsrc.root,
+                         :headers => rsrc.headers,
+                         :namespace => rsrc.namespace)
+              r.body = collection
+              objs[name] = apply(collection, r)
+            else
+              objs[name] = collection.map do |obj|
+                r = rc.new(:root => rsrc.root,
+                           :headers => rsrc.headers,
+                           :namespace => rsrc.namespace)
+                r.body = obj
+                r = classify(obj, r)
+                apply(obj, r)
+              end
+            end
+          end
+
+          # objs._hr_create_methods!
+        end
+
+        def classify(resp, rsrc)
+          return rsrc unless (type_name = get_data_type_from_object(resp)) &&
+                             (namespace = rsrc.namespace)
+          klass = rsrc.class.namespaced_class(type_name, namespace)
+
+          if klass
+            rsrc = klass.new(:root => rsrc.root,
+                             :headers => rsrc.headers,
+                             :namespace => rsrc.namespace)
+            rsrc.body = resp
+          end
+          rsrc
+        end
+
+        def get_data_type_from_object(object)
+          return nil unless object && object['type']
+          object['type'][0].upcase + object['type'][1..-1]
+        end
+
+        def apply_links(resp, rsrc)
+          return unless resp['_links']
+          rsrc.links = rsrc._hr_response_class::Links.new(rsrc)
+          links = rsrc.links
+
+          resp['_links'].each do |rel, link_spec|
+            keys = [rel]
+            if m=rel.match(/.+:(.+)/)
+              keys << m[1]
+            end
+            keys.each do |key|
+              if link_spec.is_a? Array
+                links[key] = link_spec.map do |link|
+                  new_link_from_spec(rsrc, link)
+                end
+              else
+                links[key] = new_link_from_spec(rsrc, link_spec)
+              end
+            end
+          end
+
+          # links._hr_create_methods!
+        end
+
+        def new_link_from_spec(resource, link_spec)
+          resource.class::Link.new(resource, link_spec)
+        end
+
+
+        def apply_attributes(resp, rsrc)
+          rsrc.attributes = rsrc._hr_response_class::Attributes.new(rsrc)
+
+          given_attrs = resp.reject{|k,v| %w(_links _embedded).include?(k)}
+          filtered_attrs = rsrc.incoming_body_filter(given_attrs)
+
+          filtered_attrs.keys.each do |attr|
+            rsrc.attributes[attr] = filtered_attrs[attr]
+          end
+
+          rsrc.attributes._hr_clear_changed
+          # rsrc.attributes._hr_create_methods!
+        end
+
+      end
+    end
+  end
+end
+

data/lib/hyper_resource/attributes.rb

@@ -0,0 +1,100 @@
+class HyperResource
+  class Attributes < Hash
+
+    attr_accessor :_resource # @private
+
+    def initialize(resource=nil) # @private
+      self._resource = resource || HyperResource.new
+    end
+
+    ## Creates accessor methods in self.class and self._resource.class.
+    ## Protects against method creation into HyperResource::Attributes and
+    ## HyperResource classes.  Just subclasses, please!
+    def _hr_create_methods!(opts={}) # @private
+      return if self.class.to_s == 'HyperResource::Attributes'
+      return if self._resource.class.to_s == 'HyperResource'
+      return if self.class.send(
+        :class_variable_defined?, :@@_hr_created_attributes_methods)
+
+      self.keys.each do |attr|
+        attr_sym = attr.to_sym
+        attr_eq_sym = "#{attr}=".to_sym
+
+        self.class.send(:define_method, attr_sym) do
+          self[attr]
+        end
+        self.class.send(:define_method, attr_eq_sym) do |val|
+          self[attr] = val
+        end
+
+        ## Don't stomp on _resource's methods
+        unless _resource.respond_to?(attr_sym)
+          _resource.class.send(:define_method, attr_sym) do
+            attributes.send(attr_sym)
+          end
+        end
+        unless _resource.respond_to?(attr_eq_sym)
+          _resource.class.send(:define_method, attr_eq_sym) do |val|
+            attributes.send(attr_eq_sym, val)
+          end
+        end
+      end
+
+      ## This is a good time to mark this object as not-changed
+      _hr_clear_changed
+
+      self.class.send(:class_variable_set, :@@_hr_created_attributes_methods, true) 
+    end
+
+    ## Returns +true+ if the given attribute has been changed since creation
+    ## time, +false+ otherwise.
+    ## If no attribute is given, return whether any attributes have been
+    ## changed.
+    def changed?(attr=nil)
+      @_hr_changed ||= Hash.new(false)
+      return @_hr_changed[attr.to_sym] if attr
+      return @_hr_changed.keys.count > 0
+    end
+
+    ## Returns a hash of the attributes and values which have been changed
+    ## since creation time.
+    def changed_attributes
+      @_hr_changed.select{|k,v| v}.keys.inject({}) {|h,k| h[k]=self[k]; h}
+    end
+
+    def []=(attr, value) # @private
+      return self[attr] if self.has_key?(attr.to_s) && self[attr] == value
+      _hr_mark_changed(attr) 
+      super(attr.to_s, value)
+    end
+
+    def [](key) # @private
+      return super(key.to_s) if self.has_key?(key.to_s)
+      return super(key.to_sym) if self.has_key?(key.to_sym)
+      nil
+    end
+
+    def method_missing(method, *args) # @private
+      method = method.to_s
+      if has_key?(method)
+        self[method]
+      elsif method[-1,1] == '='
+        self[method[0..-2]] = args.first
+      else
+        raise NoMethodError, "undefined method `#{method}' for #{self.inspect}"
+      end
+    end
+
+    def _hr_clear_changed # @private
+      @_hr_changed = nil
+    end
+
+    def _hr_mark_changed(attr, is_changed=true) # @private
+      attr = attr.to_sym
+      @_hr_changed ||= Hash.new(false)
+      @_hr_changed[attr] = is_changed
+    end
+
+  end
+end
+

data/lib/hyper_resource/exceptions.rb

@@ -0,0 +1,40 @@
+class HyperResource
+  class Exception < ::StandardError
+    ## The internal exception which led to this one, if any.
+    attr_accessor :cause
+
+    def initialize(message, attrs={}) # @private
+      self.cause = attrs[:cause]
+      super(message)
+    end
+  end
+
+  class ResponseError < Exception
+    ## The +Faraday::Response+ object which led to this exception.
+    attr_accessor :response
+
+    ## The deserialized response body which led to this exception.
+    ## May be blank, e.g. in case of deserialization errors.
+    attr_accessor :body
+
+    def initialize(message, attrs={}) # @private
+      self.response = attrs[:response]
+      self.body = attrs[:body]
+
+      ## Try to help out with the message
+      if self.body
+        if error = self.body['error']
+          message = "#{message} (#{error})"
+        end
+      elsif self.response
+        message = "#{message} (\"#{self.response.inspect}\")"
+      end
+
+      super(message, attrs)
+    end
+  end
+
+  class ClientError < ResponseError; end
+  class ServerError < ResponseError; end
+end
+

data/lib/hyper_resource/link.rb

@@ -0,0 +1,57 @@
+require 'uri_template'
+
+class HyperResource::Link
+  attr_accessor :base_href,
+                :name,
+                :templated,
+                :params,
+                :parent_resource
+
+  ## Returns true if this link is templated.
+  def templated?; templated end
+
+  def initialize(resource=nil, link_spec={})
+    self.parent_resource = resource || HyperResource.new
+    self.base_href = link_spec['href']
+    self.name = link_spec['name']
+    self.templated = !!link_spec['templated']
+    self.params    = link_spec['params'] || {}
+  end
+
+  ## Returns this link's href, applying any URI template params.
+  def href
+    if self.templated?
+      filtered_params = self.parent_resource.outgoing_uri_filter(params)
+      URITemplate.new(self.base_href).expand(filtered_params)
+    else
+      self.base_href
+    end
+  end
+
+  ## Returns a new scope with the given params; that is, returns a copy of
+  ## itself with the given params applied.
+  def where(params)
+    params = Hash[ params.map{|(k,v)| [k.to_s, v]} ]
+    self.class.new(self.parent_resource,
+                   'href' => self.base_href,
+                   'name' => self.name,
+                   'templated' => self.templated,
+                   'params' => self.params.merge(params))
+  end
+
+  ## Returns a HyperResource representing this link
+  def resource
+    parent_resource._hr_new_from_link(self.href)
+  end
+
+  ## Returns a HyperResource representing this link, and fetches it.
+  def get
+    self.resource.get
+  end
+
+  ## If we were called with a method we don't know, load this resource
+  ## and pass the message along.  This achieves implicit loading.
+  def method_missing(method, *args)
+    self.get.send(method, *args)
+  end
+end

data/lib/hyper_resource/links.rb

@@ -0,0 +1,63 @@
+class HyperResource
+  class Links < Hash
+    attr_accessor :_resource
+
+    def initialize(resource=nil)
+     self._resource = resource || HyperResource.new
+    end
+
+    ## Creates accessor methods in self.class and self._resource.class.
+    ## Protects against method creation into HyperResource::Links and
+    ## HyperResource classes.  Just subclasses, please!
+    def _hr_create_methods!(opts={}) # @private
+      return if self.class.to_s == 'HyperResource::Links'
+      return if self._resource.class.to_s == 'HyperResource'
+      return if self.class.send(
+        :class_variable_defined?, :@@_hr_created_links_methods)
+
+      self.keys.each do |attr|
+        attr_sym = attr.to_sym
+        self.class.send(:define_method, attr_sym) do |*args|
+          if args.count > 0
+            self[attr].where(*args)
+          else
+            self[attr]
+          end
+        end
+
+        ## Don't stomp on _resource's methods
+        unless _resource.respond_to?(attr_sym)
+          _resource.class.send(:define_method, attr_sym) do |*args|
+            links.send(attr_sym, *args)
+          end
+        end
+      end
+
+      self.class.send(:class_variable_set, :@@_hr_created_links_methods, true)
+    end
+
+    def []=(attr, value) # @private
+      super(attr.to_s, value)
+    end
+
+    def [](key) # @private
+      return super(key.to_s) if self.has_key?(key.to_s)
+      return super(key.to_sym) if self.has_key?(key.to_sym)
+      nil
+    end
+
+    def method_missing(method, *args) # @private
+      unless self[method]
+        raise NoMethodError, "undefined method `#{method}' for #{self.inspect}"
+      end
+
+      if args.count > 0
+        self[method].where(*args)
+      else
+        self[method]
+      end
+    end
+
+  end
+end
+

data/lib/hyper_resource/modules/http.rb

@@ -0,0 +1,129 @@
+require 'faraday'
+require 'uri'
+require 'json'
+
+class HyperResource
+  module Modules
+    module HTTP
+
+      ## Loads and returns the resource pointed to by +href+.  The returned
+      ## resource will be blessed into its "proper" class, if
+      ## +self.class.namespace != nil+.
+      def get
+        self.response = faraday_connection.get(self.href || '')
+        finish_up
+      end
+
+      ## By default, calls +post+ with the given arguments. Override to
+      ## change this behavior.
+      def create(*args)
+        post(*args)
+      end
+
+      ## POSTs the given attributes to this resource's href, and returns
+      ## the response resource.
+      def post(attrs)
+        self.response = faraday_connection.post do |req|
+          req.body = adapter.serialize(attrs)
+        end
+        finish_up
+      end
+
+      ## By default, calls +put+ with the given arguments.  Override to
+      ## change this behavior.
+      def update(*args)
+        put(*args)
+      end
+
+      ## PUTs this resource's attributes to this resource's href, and returns
+      ## the response resource.  If attributes are given, +put+ uses those
+      ## instead.
+      def put(attrs=nil)
+        attrs ||= self.attributes
+        self.response = faraday_connection.put do |req|
+          req.body = adapter.serialize(attrs)
+        end
+        finish_up
+      end
+
+      ## PATCHes this resource's changed attributes to this resource's href,
+      ## and returns the response resource.  If attributes are given, +patch+
+      ## uses those instead.
+      def patch(attrs=nil)
+        attrs ||= self.attributes.changed_attributes
+        self.response = faraday_connection.patch do |req|
+          req.body = adapter.serialize(attrs)
+        end
+        finish_up
+      end
+
+      ## DELETEs this resource's href, and returns the response resource.
+      def delete
+        self.response = faraday_connection.delete
+        finish_up
+      end
+
+      ## Returns a raw Faraday connection to this resource's URL, with proper
+      ## headers (including auth).  Threadsafe.
+      def faraday_connection(url=nil)
+        url ||= URI.join(self.root, self.href)
+        key = Digest::MD5.hexdigest({
+          'faraday_connection' => {
+            'url' => url,
+            'headers' => self.headers,
+            'ba' => self.auth[:basic]
+          }
+        }.to_json)
+        return Thread.current[key] if Thread.current[key]
+
+        fc = Faraday.new(self.faraday_options.merge(:url => url))
+        fc.headers.merge!('User-Agent' => "HyperResource #{HyperResource::VERSION}")
+        fc.headers.merge!(self.headers || {})
+        if ba=self.auth[:basic]
+          fc.basic_auth(*ba)
+        end
+        Thread.current[key] = fc
+      end
+
+    private
+
+      def finish_up
+        begin
+          self.body = self.adapter.deserialize(self.response.body) unless self.response.body.nil?
+        rescue StandardError => e
+          raise HyperResource::ResponseError.new(
+            "Error when deserializing response body",
+            :response => self.response,
+            :cause => e
+          )
+        end
+
+        self.adapter.apply(self.body, self)
+        self.loaded = true
+
+        status = self.response.status
+        if status / 100 == 2
+          return to_response_class
+        elsif status / 100 == 3
+          ## TODO redirect logic?
+        elsif status / 100 == 4
+          raise HyperResource::ClientError.new(status.to_s,
+                                               :response => self.response,
+                                               :body => self.body)
+        elsif status / 100 == 5
+          raise HyperResource::ServerError.new(status.to_s,
+                                               :response => self.response,
+                                               :body => self.body)
+
+        else ## 1xx? really?
+          raise HyperResource::ResponseError.new("Got status #{status}, wtf?",
+                                                 :response => self.response,
+                                                 :body => self.body)
+
+        end
+      end
+
+    end
+  end
+end
+

data/lib/hyper_resource/modules/internal_attributes.rb

@@ -0,0 +1,90 @@
+module HyperResource::Modules
+  module InternalAttributes
+
+    def self.included(base)
+      base.extend(ClassMethods)
+
+      base._hr_class_attributes.each do |attr|
+        base._hr_class_attribute attr
+      end
+
+      (base._hr_attributes - base._hr_class_attributes).each do |attr|
+         base.send(:attr_accessor, attr)
+      end
+
+      ## Fallback attributes fall back from instance to class.
+      (base._hr_attributes & base._hr_class_attributes).each do |attr|
+         base._hr_fallback_attribute attr
+      end
+    end
+
+    module ClassMethods
+
+      def _hr_class_attributes # @private
+        [ :root,             ## e.g. 'https://example.com/api/v1'
+          :auth,             ## e.g. {:basic => ['username', 'password']}
+          :headers,          ## e.g. {'Accept' => 'application/vnd.example+json'}
+          :namespace,        ## e.g. 'ExampleAPI', or the class ExampleAPI itself
+          :adapter,          ## subclass of HR::Adapter
+          :faraday_options   ## e.g. {:request => {:timeout => 30}}
+        ]
+      end
+
+      def _hr_attributes # @private
+        [ :root,
+          :href,
+          :auth,
+          :headers,
+          :namespace,
+          :adapter,
+          :faraday_options,
+
+          :request,
+          :response,
+          :body,
+
+          :attributes,
+          :links,
+          :objects,
+
+          :loaded
+        ]
+      end
+
+      ## Inheritable class attribute, kinda like in Rails.
+      def _hr_class_attribute(*names)
+        names.map(&:to_sym).each do |name|
+          instance_eval <<-EOT
+            def #{name}=(val)
+              @#{name} = val
+            end
+            def #{name}
+              return @#{name} if defined?(@#{name})
+              return superclass.#{name} if superclass.respond_to?(:#{name})
+              nil
+            end
+          EOT
+        end
+      end
+
+      ## Instance attributes which fall back to class attributes.
+      def _hr_fallback_attribute(*names)
+        names.map(&:to_sym).each do |name|
+          class_eval <<-EOT
+            def #{name}=(val)
+              @#{name} = val
+            end
+            def #{name}
+              return @#{name} if defined?(@#{name})
+              return self.class.#{name} if self.class.respond_to?(:#{name})
+              nil
+            end
+          EOT
+        end
+      end
+
+    end # ClassMethods
+
+  end
+end
+

data/lib/hyper_resource/objects.rb

@@ -0,0 +1,60 @@
+class HyperResource
+  class Objects < Hash
+    attr_accessor :_resource
+
+    def initialize(resource=nil) 
+      self._resource = resource || HyperResource.new
+    end
+
+    ## Creates accessor methods in self.class and self._resource.class.
+    ## Protects against method creation into HyperResource::Objects and
+    ## HyperResource classes.  Just subclasses, please!
+    def _hr_create_methods!(opts={}) # @private
+      return if self.class.to_s == 'HyperResource::Objects'
+      return if self._resource.class.to_s == 'HyperResource' 
+      return if self.class.send(
+        :class_variable_defined?, :@@_hr_created_objects_methods) 
+
+      self.keys.each do |attr|
+        attr_sym = attr.to_sym
+
+        self.class.send(:define_method, attr_sym) do
+          self[attr]
+        end
+
+        ## Don't stomp on _resource's methods
+        unless _resource.respond_to?(attr_sym)
+          _resource.class.send(:define_method, attr_sym) do
+            objects.send(attr_sym)
+          end
+        end
+      end
+
+      self.class.send(:class_variable_set, :@@_hr_created_objects_methods, true) 
+    end
+
+    def []=(attr, value) # @private
+      super(attr.to_s, value)
+    end
+
+    ## When +key+ is a string, returns the array of objects under that name.
+    ## When +key+ is a number, returns +ith(key)+. Returns nil on lookup
+    ## failure.
+    def [](key)
+      case key
+      when String, Symbol
+        return super(key.to_s) if self.has_key?(key.to_s)
+        return super(key.to_sym) if self.has_key?(key.to_sym)
+      when Fixnum
+        return ith(key)
+      end
+      nil
+    end
+
+    def method_missing(method, *args) # @private
+      return self[method] if self[method]
+      raise NoMethodError, "undefined method `#{method}' for #{self.inspect}"
+    end
+
+  end
+end

data/lib/hyper_resource/response.rb

@@ -0,0 +1,2 @@
+class HyperResource::Response < Hash
+end

data/lib/hyper_resource/version.rb

@@ -0,0 +1,4 @@
+class HyperResource
+  VERSION = '0.9.0'
+  VERSION_DATE = '2014-03-11'
+end

data/lib/hyperresource.rb

@@ -0,0 +1,2 @@
+require 'hyper_resource'
+

metadata

@@ -0,0 +1,172 @@
+--- !ruby/object:Gem::Specification
+name: hyperresource-aptible
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+platform: ruby
+authors:
+- Frank Macreery
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: uri_template
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.5.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.5.2
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.6
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 10.0.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 10.0.4
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 4.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 4.7.0
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.13.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.13.3
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+description: |2
+      HyperResource is a hypermedia client library for Ruby.  Its goals are to
+      interface directly with well-behaved hypermedia APIs, to allow the data
+      returned from these APIs to optionally be extended by client-side code,
+      and to present a modern replacement for ActiveResource.
+email: frank@macreery.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/hyper_resource.rb
+- lib/hyper_resource/adapter.rb
+- lib/hyper_resource/adapter/hal_json.rb
+- lib/hyper_resource/attributes.rb
+- lib/hyper_resource/exceptions.rb
+- lib/hyper_resource/link.rb
+- lib/hyper_resource/links.rb
+- lib/hyper_resource/modules/http.rb
+- lib/hyper_resource/modules/internal_attributes.rb
+- lib/hyper_resource/objects.rb
+- lib/hyper_resource/response.rb
+- lib/hyper_resource/version.rb
+- lib/hyperresource.rb
+homepage: https://github.com/fancyremarker/hyperresource
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.1
+signing_key: 
+specification_version: 4
+summary: Extensible hypermedia client for Ruby
+test_files: []