benjaminkrause-restful 0.2.8

data/lib/restful/rails.rb

@@ -0,0 +1,22 @@
+module Restful
+  module Rails
+    
+    # sets the hostname for this request in a threadsafe manner. 
+    def self.api_hostname=(hostname)
+      Thread.current[:api_hostname] = hostname
+    end
+    
+    # gets the hostname for the currently running thread. 
+    def self.api_hostname
+      Thread.current[:api_hostname]
+    end
+    
+    #
+    #  Shortcuts past namespaces
+    #
+    def self.tools
+      Restful::Rails::ActiveRecord::MetadataTools::Utils
+    end
+
+  end
+end

data/lib/restful/rails/action_controller.rb

@@ -0,0 +1,14 @@
+module Restful
+  module Rails
+    module ActionController
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    
+      module ClassMethods
+      end
+    end
+  end
+end
+
+ActionController::Base.send :include, Restful::Rails::ActionController

data/lib/restful/rails/active_record/configuration.rb

@@ -0,0 +1,167 @@
+#
+#  Configuration options for restful. 
+#
+module Restful
+  module Rails
+    module ActiveRecord
+      module Configuration
+        def self.included(base)
+          base.send :class_inheritable_accessor, :restful_config
+          base.restful_config = Config.new
+          base.send :include, ResourceInstanceMethods
+          base.send :include, CommonInstanceMethods
+          base.extend(ClassMethods)
+        end
+        
+        module ClassMethods
+          
+          #
+          #  In the form: 
+          #
+          #    Person.restful_publish(:name, :pets => [:name, :species])
+          #
+          #  If pet already has configured the api with restful_publish, you would
+          #  get the default nested attributes. In the above example, these would be
+          #  overriden. 
+          #
+          def restful_publish(*fieldnames) # declarative setter method
+            self.restful_config = Restful.cfg(*fieldnames)
+          end
+        end
+        
+        module CommonInstanceMethods
+          #
+          #  converts this AR object to an apimodel object. per default, only the
+          #  attributes in self.class.restful_config are shown. this can be overriden
+          #  by passing in something like @pet.to_restful(:name, :species).
+          #
+          def to_restful(config = nil)
+            add_to_whitelist = []
+
+            if config && config.is_a?(Hash) && config.keys.size == 1 && includes = config[:include] 
+              add_to_whitelist = [*includes].map { |el| el.is_a?(String) ? el.to_sym : el  }
+              config = nil
+            end
+            
+            config ||= self.class.restful_config.clone if self.class.respond_to?(:restful_config)
+            config ||= []
+            
+            if config && !config.is_a?(Config)
+             config = Config.new(config)
+            end
+            
+            if self.class.respond_to?(:restful_config)
+              config.whitelisted = Array.new(self.class.restful_config.whitelisted) if config.whitelisted.empty?
+              config.restful_options.merge! self.class.restful_config.restful_options
+            end
+            
+            config.whitelisted += add_to_whitelist
+            config.whitelisted = config.whitelisted.uniq
+            
+            # array
+            if self.is_a?(Array)
+              elements = self.map do |el|
+                raise TypeError.new("Not all array elements respond to #to_restful. ") unless el.respond_to?(:to_restful)
+                Restful::Converters::ActiveRecord.convert(el, el.class.restful_config)
+              end
+              
+              element_name = elements.first ? elements.first.name.pluralize : "nil-classes"
+              
+              returning Restful.collection(element_name, elements, :array) do |collection|
+                collection.total_entries = self.total_entries if self.respond_to?(:total_entries)
+              end
+                        
+            elsif self.is_a?(Hash)
+              elements = self.map do |k,v|
+                if v.respond_to?(:to_restful) and v.class.respond_to?(:restful_config)
+                  value = Restful::Converters::ActiveRecord.convert(v, v.class.restful_config)
+                else
+                  value =  v.respond_to?(:to_restful) ? v.to_restful : v
+                end
+                Restful::ApiModel::Attribute.new(k, value, :map)
+              end
+              
+              map = Restful::ApiModel::Map.new("hash")
+              map.values =  elements
+              map
+            else
+              Restful::Converters::ActiveRecord.convert(self, config)
+            end
+          end
+          
+          # FIXME: read Restful::Serializers::Base.serializers. Load order problems?
+          [:xml, :json, :atom_like].each do |format|
+            define_method("to_restful_#{ format }") do |*args|
+              self.to_restful(*args).serialize(format)
+            end            
+          end
+        end
+    
+        module ResourceInstanceMethods
+                    
+          # simple method through which a model should know it's own name. override this where necessary. 
+          def restful_url(url_base = Restful::Rails.api_hostname)
+            "#{ url_base }#{ restful_path }"
+          end
+          
+          def restful_path
+            "/#{ self.class.to_s.tableize }/#{ self.to_param }"
+          end
+        end
+        
+        class Config # configures what attributes are exposed to the api. for a single resource.
+          
+          attr_accessor :whitelisted, :restful_options
+          
+          def initialize(*fields) # set; eg :name, :pets => [:name, :species]
+            @whitelisted, @restful_options = split_into_whitelist_and_restful_options([fields].flatten.compact)
+          end
+
+          def published?(key)
+            @whitelisted.include?(key) || !!@whitelisted.select { |field| field.is_a?(Hash)  && field.keys.include?(key) }.first
+          end
+
+          def expanded?(key, nested = false) # if nothing was set, this defaults to true. 
+            force_expanded?(key) || (@restful_options[:expansion] != :collapsed && !nested)
+          end
+          
+          def force_expanded?(key)
+            force = [*@restful_options[:force_expand]]
+            force.include?(key)
+          end
+
+          def nested?
+            !!restful_options[:nested]
+          end
+
+          def nested(key)
+            definition = @whitelisted.select { |field| field.is_a?(Hash)  && field.keys.include?(key) }.first
+            Config.new((definition[key] if definition))
+          end
+
+          private
+          
+            def split_into_whitelist_and_restful_options(array)
+              options = {}
+        
+              return array.map do |el|
+                if el.is_a? Hash
+                  el = el.clone
+                  deleted = el.delete(:restful_options) 
+                  options.merge!(deleted) if deleted
+                  el = nil if el == {}
+                end
+              
+                el
+              end.compact, options
+            end
+            
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, Restful::Rails::ActiveRecord::Configuration
+Array.send :include, Restful::Rails::ActiveRecord::Configuration::CommonInstanceMethods
+Hash.send :include, Restful::Rails::ActiveRecord::Configuration::CommonInstanceMethods

data/lib/restful/rails/active_record/metadata_tools.rb

@@ -0,0 +1,106 @@
+#
+#  Handle ActiveRecord associations and such like. 
+#
+module Restful
+  module Rails
+    module ActiveRecord
+      module MetadataTools
+        
+        def self.included(base)
+          base.class_inheritable_accessor :apiable_associations
+          base.class_inheritable_accessor :apiable_association_table
+        
+          base.send :include, InstanceMethods
+          base.extend(ClassMethods)
+        end
+        
+        module ClassMethods
+          
+          def apiable
+            cache_association_restful_url_metadata
+          end
+
+          def cache_association_restful_url_metadata
+            self.apiable_associations ||= (self.reflect_on_all_associations(:belongs_to) + self.reflect_on_all_associations(:has_one)).flatten.uniq
+            self.apiable_association_table ||= self.apiable_associations.inject({}) { |memo, reflection| memo[reflection.primary_key_name] = reflection; memo }
+          end
+          
+          def find_by_restful(id)
+            find(id)
+          end
+        end
+        
+        module InstanceMethods
+          def resolve_association_restful_url(association_key_name)            
+            self.class.cache_association_restful_url_metadata
+
+            if reflection = self.class.apiable_association_table[association_key_name]
+              related_resource = self.send(reflection.name)
+              [Restful::Rails.api_hostname, related_resource.restful_path] if related_resource
+            end
+          end
+        end
+
+        module  Utils
+          
+          # called for nested resources. 
+          def self.expand(resource, config)
+            config.restful_options[:nested] = true
+            resource.to_restful(config)
+          end
+
+          def self.link(key, model, config)
+            Restful.link(key.to_sym, "base", "path", "link")
+          end
+          
+          def self.dereference(url)
+            regexp = Regexp.new("#{ Restful::Rails.api_hostname }\/(.*)\/(.*)")
+            m, resource, params = *url.match(regexp)
+            resource = if resource && params
+              clazz = resource.try(:singularize).try(:camelize).try(:constantize)
+              clazz.find_by_restful(params) if clazz 
+            end
+
+            resource ? resource.id : 0
+          end
+          
+          # retruns non association / collection attributes. 
+          def self.simple_attributes_on(model)
+            attributes = model.attributes
+            
+            attributes.delete_if do |k, v|
+              model.class.apiable_association_table && model.class.apiable_association_table.keys.include?(k)
+            end
+          end
+          
+          #
+          #  Takes an ar model and a key like :people, and returns an array of resources. 
+          #  
+          #   TODO: don't load the entire association, only the published attributes (with an appropriate :select). 
+          #   TODO: get some pagination in.
+          #
+          def self.convert_collection_to_resources(model, key, config)
+            
+            # load the associated objects.
+            models = model.send(key)
+            
+            # convert them to_restful. 
+            if models
+              [*models].map do |m| 
+                if m.respond_to? :to_restful
+                  config.nested? ?
+                    link(key, m, config) :
+                    expand(m, config)
+                else
+                  raise "Seems as if you want to export the relation #{ key } of an #{ model.class.to_s } object without making #{ key } apiable."
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, Restful::Rails::ActiveRecord::MetadataTools

data/lib/restful/serializers/atom_like_serializer.rb

@@ -0,0 +1,51 @@
+require 'restful/serializers/base'
+require 'builder'
+
+#
+#  Converts an APIModel to and from XML. 
+#
+module Restful
+  module Serializers
+    class AtomLikeSerializer < XMLSerializer
+      
+      serializer_name :atom_like
+      
+      protected
+        
+        def root_resource(node)
+          url_base = node.attribute(:base, :xml)
+          me_node = node.delete_element("link[@rel='self']")
+          own_url = me_node.attribute(:href)
+          Restful.resource(node.name, :path => own_url, :base => url_base)
+        end
+      
+        def build_link(el, type)
+          Restful.link(revert_link_name(el.attribute('rel')), nil, el.attribute('href'), type)
+        end
+        
+        def calculate_node_type(el)
+          return :link if el.name.downcase == "link"
+          (el.attributes["type"] || "string").to_sym
+        end
+                
+        def add_link_to(resource, builder, options = {})
+          is_self = !!options[:self]
+          builder.tag!("link", { :href => resource.path, :rel => (is_self ? "self" : resource.name) })
+        end
+        
+        def root_element(resource)
+          decorations = {}
+          
+          unless @nested_root
+            decorations =  { :"xml:base" => Restful::Rails.api_hostname } unless Restful::Rails.api_hostname.blank?
+            @nested_root = true
+          end
+          
+          [resource.name, decorations]
+        end
+        
+        def decorations(value); {}; end
+        def collections_decorations; {}; end                
+    end
+  end
+end

data/lib/restful/serializers/base.rb

@@ -0,0 +1,57 @@
+#
+#  Converts an APIModel to and from a given format.  
+#
+module Restful
+  module Serializers
+    class Base
+      cattr_accessor :serializers
+      
+      def serialize(resource, options = {}) # implement me. 
+        raise NotImplementedError.new
+      end
+      
+      def deserialize(resource, options = {}) # implement me. 
+        raise NotImplementedError.new        
+      end
+      
+      #
+      #  Grabs a serializer, given...
+      #
+      #    .serialize(:xml, Resource.new(:animal => "cow"))
+      #
+      def self.serializer(type)
+        serializers[type].new
+      end
+      
+      def self.serializer_name(key)
+        self.serializers ||= {}
+        self.serializers[key] = self
+      end
+      
+      def formatted_value(value)
+        return value unless value.respond_to?(:value)
+        
+        return nil if value.value.blank? && value.extended_type != :false_class
+        case value.extended_type
+        when :datetime
+          value.value.xmlschema
+        when :time
+          value.value.xmlschema
+        when :date
+          value.value.to_s(:db)
+        else
+          value.value
+        end        
+      end
+      
+      protected
+        def transform_link_name(name)
+          name.to_s.gsub /_id$/, "-restful-url"
+        end
+      
+        def revert_link_name(name)
+          name.to_s.gsub /-restful-url$/, "_id"
+        end      
+    end
+  end
+end

data/lib/restful/serializers/hash_serializer.rb

@@ -0,0 +1,59 @@
+require 'restful/serializers/base'
+
+#
+#  AR params hash.
+#
+module Restful
+  module Serializers
+    class HashSerializer < Base
+      
+      serializer_name :hash
+      
+      def serialize(resource, options = {})
+        case resource
+        when Restful::ApiModel::Collection then serialize_collection(resource)
+        when Restful::ApiModel::Resource   then serialize_tuples(resource.values, resource.full_url)
+        when Restful::ApiModel::Map        then serialize_map(resource)
+        else
+          serialize_tuples(resource.values, resource.full_url)
+        end
+      end
+
+      private      
+        
+        def serialize_collection(collection)
+          values = collection.value.map { |r| serialize(r) }
+        
+          if entries = collection.total_entries
+            values = { :total_entries => entries, collection.name => values }
+          end
+        
+          values
+        end
+        
+        def serialize_map(map)
+          map.values.inject({}) do |memo, attribute|
+            memo[attribute.name] = serialize_value(attribute.value)
+            memo
+          end
+        end
+        
+        def serialize_tuples(tuples, url)
+          tuples.inject({ "restful_url" => url }) do |params, value|
+            params[value.name.to_s.tr("-", "_").to_sym] = serialize_value(value)
+            params
+          end
+        end
+        
+        def serialize_value(value)
+          case value.type
+            when :collection then serialize_collection(value)
+            when :link       then Restful::Rails.tools.dereference(value.value)
+            when :resource   then serialize(value)
+            else                  formatted_value(value)
+          end
+        end
+
+    end
+  end
+end