aptible-resource 0.1.0

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,59 @@
+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
+
+  ## Delegate HTTP methods to the resource.
+  def get(*args);    self.resource.get(*args)    end
+  def post(*args);   self.resource.post(*args)   end
+  def patch(*args);  self.resource.patch(*args)  end
+  def put(*args);    self.resource.put(*args)    end
+  def delete(*args); self.resource.delete(*args) 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,131 @@
+require 'faraday'
+require 'uri'
+require 'json'
+require 'digest/md5'
+
+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=nil)
+        attrs || self.attributes
+        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
+