active_facets 1.2.2

data/lib/active_facets/config.rb

@@ -0,0 +1,263 @@
+# Field = Symbol representing a json attribute that corresponds to resource attributes or extensions
+
+# Field Set = Nested, Mixed Collection of Fields, Aliases, and Relations (Strings, Symbols, Arrays and Hashes)
+#  e.g. [:a, {b: "c"}]
+
+# Normalized Field Set = Field Set with all Strings converted to Symbols, Aliases dealiased, and Arrays converted to Hashes
+
+# Field Set Alias = Symbol representing a Field Set
+
+module ActiveFacets
+  class Config
+
+    #TODO --decouple this class completely from serializer by moving reflection to resource_manager
+
+    # Boolean: state
+    attr_reader :compiled
+
+    # Serializer::Base
+    attr_reader :serializer
+
+    # Hash: compiled field sets
+    attr_reader :normalized_field_sets
+
+    # Hash: keys are public API attribute names, values are resource attribute names
+    attr_reader :transforms_from, :transforms_to
+
+    # Hash: API attribute names requiring custom serialization
+    attr_reader :serializers
+
+    # Hash: keys are resource attribute names storing nested JSON, values are nested attribute names
+    attr_reader :namespaces
+
+    # Hash: keys are defined extension values
+    attr_reader :extensions
+
+    # Class: Resource Class to serialize
+    attr_accessor :resource_class
+
+    def alias_field_set(field_set_alias, field_set)
+      self.compiled = false
+      field_sets[field_set_alias] = field_set
+    end
+
+    # Returns Field to resource attribute map
+    # @param direction [Symbol]
+    # @return [Hash]
+    def transforms(direction = :from)
+      direction == :from ? transforms_from : transforms_to
+    end
+
+    # (Memoized) Normalizes all Field Set Aliases
+    # @param serializer [Serializer::Base]
+    # @return [Config]
+    def compile!(serializer)
+      self.serializer = serializer
+      self.normalized_field_sets = { all: {} }.with_indifferent_access
+
+      #aggregate all compiled field_sets into the all collection
+      normalized_field_sets[:all][:fields] = field_sets.inject({}) do |result, (field_set_alias, field_set)|
+        result = merge_field_sets(result, dealias_field_set!(field_set, field_set_alias)[:fields])
+      end
+
+      #filter all compiled field_sets into a corresponding attributes collection
+      normalized_field_sets.each do |field_set_alias, normalized_field_set|
+        normalized_field_set[:attributes] = normalized_field_set[:fields].reject { |field_set, nested_field_sets|
+          serializer.send :is_association?, field_set
+        }
+      end
+
+      self.compiled = true
+      self
+    end
+
+    # Merges all ancestor accessors into self
+    # @return [Config]
+    def merge!(config)
+      self.compiled = false
+      self.resource_class ||= config.resource_class
+      transforms_from.merge!  config.transforms_from
+      transforms_to.merge!    config.transforms_to
+      serializers.merge!      config.serializers
+      namespaces.merge!       config.namespaces
+      field_sets.merge!       config.field_sets
+      extensions.merge!       config.extensions
+
+      self
+    end
+
+    # Invokes block on a Field Set with recursive, depth first traversal
+    # @param field_set [Field Set] to traverse
+    # @param block [Block] to call for each field
+    # @return [Hash] injection of block results
+    def field_set_itterator(field_set)
+      raise ActiveFacets::Errors::ConfigurationError.new(ActiveFacets::Errors::ConfigurationError::COMPILED_ERROR_MSG) unless compiled
+      internal_field_set_itterator(dealias_field_set!(default_field_set(field_set))[:fields], Proc.new)
+    end
+
+    protected
+
+    attr_accessor :field_sets
+
+    attr_writer :compiled, :serializer, :normalized_field_sets, :transforms_from, :transforms_to,
+      :serializers, :namespaces, :extensions
+
+    private
+
+    #TODO --jdc change Serializer::Base to convert all Strings to Symbols and remove indifferent_access
+    def initialize
+      self.compiled = false
+      self.transforms_from  = {}.with_indifferent_access
+      self.transforms_to    = {}.with_indifferent_access
+      self.serializers      = {}.with_indifferent_access
+      self.namespaces       = {}.with_indifferent_access
+      self.field_sets       = {}.with_indifferent_access
+      self.extensions       = {}.with_indifferent_access
+    end
+
+    # (Memoized) Convert all Field Set Aliases to their declarations and Normalize Field Set
+    # @param field_set [Symbol] to evaluate
+    # @param field_set_alias [String] key to associate the evaluated field set with
+    # @return [Normalized Field Set]
+    def dealias_field_set!(field_set, field_set_alias = nil)
+      field_set_alias ||= field_set.to_s.to_sym
+      normalized_field_sets[field_set_alias] ||= begin
+        { fields: normalize_field_set(dealias_field_set field_set) }
+      end
+    end
+
+    # Converts all Field Set Aliases in a Field Set into their declarations (see Serializer::Base DSL)
+    # Recursively evaluates all aliases embedded within declaration
+    # - Does not recursively evalute associations
+    # @param field_set [Symbol] to evaluate
+    # @return [Mixed]
+    def dealias_field_set(field_set)
+      case field_set
+      when :all
+        dealias_field_set serializer.exposed_aliases(:all, true, true)
+      when :all_attributes
+        dealias_field_set serializer.exposed_aliases
+      when Symbol, String
+        field_set = field_set.to_sym
+        aliased_field_set?(field_set) ? dealias_field_set(field_sets[field_set]) : field_set
+      when Array
+        field_set.map do |s|
+          dealias_field_set(s)
+        end
+      when Hash
+        field_set.inject({}) { |result, (k,v)|
+          v.blank? ? inject_field_set(result, dealias_field_set(k)) : result[k] = v #todo: symbolize
+          result
+        }
+      end
+    end
+
+    # Converts Field Set into a Normalized Field Set that can be idempotently itterated
+    # @param field_set [Symbol] to normalize
+    # @return [Normalized Field Set]
+    def normalize_field_set(field_set)
+      case field_set
+      when nil
+        {}
+      when Symbol, String
+        {field_set.to_sym => nil}
+      when Array
+        field_set.flatten.compact.inject({}) do |result, s|
+          result = merge_field_sets(result, s)
+        end
+      when Hash
+        field_set.inject({}) { |result, (k,v)| result[k.to_sym] = v; result }
+      end
+    end
+
+    # Adds :basic to a Field Set unless minimal is specified
+    # @param field_set [Field Set] field set to be serialized
+    # @return [Field Set]
+    def default_field_set(field_set)
+      minimal = detect_field_set(field_set, :minimal)
+      case field_set
+      when nil
+        :basic
+      when Symbol, String
+        minimal ? field_set.to_sym : [field_set.to_sym, :basic]
+      when Array
+        minimal ? field_set : field_set + [:basic]
+      when Hash
+        field_set[:basic] = nil unless minimal
+        field_set
+      else
+        raise ActiveFacets::Errors::ConfigurationError.new(ActiveFacets::Errors::ConfigurationError::FIELD_SET_ERROR_MSG)
+      end
+    end
+
+    # Iterrates the first level of Field Set checking for key
+    # @param field_set [Field Set]
+    # @return [Boolean]
+    def detect_field_set(field_set, key)
+      case field_set
+      when nil
+        false
+      when Symbol
+        field_set == key
+      when String
+        field_set.to_sym == key
+      when Array
+        field_set.detect { |s| detect_field_set(s, key) }
+      when Hash
+        field_set.detect { |s, n| detect_field_set(s, key) }.try(:[], 0)
+      else
+        raise ActiveFacets::Errors::ConfigurationError.new(ActiveFacets::Errors::ConfigurationError::FIELD_SET_ERROR_MSG)
+      end
+    end
+
+    # Invokes block on Fields in a Field Set with recursive, depth first traversal
+    # Skips fields already processed
+    # @param field_set [Field Set] to traverse
+    # @param block [Block] to call for each field_set
+    # @return [Hash] injection of block results
+    def internal_field_set_itterator(field_set, block)
+      field_set.each do |field, nested_field_set|
+        block.call(field, nested_field_set)
+      end
+    end
+
+    # Adds a Field into a Normalized Field Set
+    # @param field_set [Normalized Field Set]
+    # @param key [Field Set]
+    # @return [Hash]
+    def inject_field_set(field_set, key)
+      case key
+      when Symbol, String
+        field_set[key.to_sym] = {}
+      when Hash
+        field_set.merge! key
+      when Array
+        key.each { |k| inject_field_set(field_set, k) }
+      end
+    end
+
+    # Tells if the Field is a Field Set Alias
+    # @param field_set [Symbol] to evaluate
+    # @return [Boolean]
+    def aliased_field_set?(field_set)
+      return false unless field_sets.key? field_set
+      v = field_sets[field_set]
+      !v.is_a?(Symbol) || v != field_set
+    end
+
+    # Recursively merges two Field Sets
+    # @param a [Symbol] to merge
+    # @param b [Symbol] to merge
+    # @return [Field Set]
+    def merge_field_sets(a, b)
+      na = normalize_field_set(a)
+      nb = normalize_field_set(b)
+      binding.pry unless nb
+      nb.inject(na.dup) do |result, (field_set, nested_field_sets)|
+        result[field_set] = merge_field_sets(na[field_set], nested_field_sets)
+        result
+      end
+    end
+
+  end
+end

data/lib/active_facets/document_cache.rb

@@ -0,0 +1,52 @@
+# This is a really dump cache interface that caches everything
+# Extend with custom class that conditionally caches and stitches independent documents
+module ActiveFacets
+  class DocumentCache
+    CACHE_PREFIX = 'af_doc_cache'
+
+    # Fetches a JSON document representing the facade
+    # @param facade [Object] to cache
+    # @param options [Hash] for Rails.cache.fetch
+    # @param &block [Proc] for cache miss
+    # @return [Object]
+    def self.fetch(facade, options = {})
+      return yield unless cacheable?(facade)
+
+      force = facade.opts[ActiveFacets.cache_force_key] || options[:force] || ActiveFacets::default_cache_options[:force]
+      cache_key = digest_key(facade)
+      if force || !(result = Rails.cache.fetch(cache_key))
+        result = yield
+        Rails.cache.write(cache_key, ::Oj.dump(result), ActiveFacets::default_cache_options.merge(options).merge(force: force))
+        result
+      else
+        ::Oj.load(result)
+      end
+    end
+
+    # Fetches a JSON document representing the association specified for the resource in the facade
+    # @param facade [Object] to cache
+    # @param options [Hash] for Rails.cache.fetch
+    # @param &block [Proc] for cache miss
+    # @return [Object]
+    def self.fetch_association(facade, association, options = {})
+      #TODO --jdc implement
+      yield
+    end
+
+    private
+
+    # Salts and hashes facade cache_key
+    # @param facade [Facade] to generate key for
+    # @return [String]
+    def self.digest_key(facade)
+      Digest::MD5.hexdigest(CACHE_PREFIX + facade.cache_key.to_s)
+    end
+
+    # Tells if the resource to be serialized can be cached
+    # @param facade [Facade] to inspect
+    # @return [Boolean]
+    def self.cacheable?(facade)
+      ActiveFacets.cache_enabled
+    end
+  end
+end

data/lib/active_facets/errors/attribute_error.rb

@@ -0,0 +1,6 @@
+module ActiveFacets
+  module Errors
+    class AttributeError < StandardError
+    end
+  end
+end

data/lib/active_facets/errors/configuration_error.rb

@@ -0,0 +1,14 @@
+module ActiveFacets
+  module Errors
+    class ConfigurationError < StandardError
+
+      RESOURCE_ERROR_MSG            = 'unable to identify resource class'
+      STACK_ERROR_MSG               = "self referencing attribute declaration"
+      ALL_ATTRIBUTES_ERROR_MSG      = "publish name (:all_attributes) reserved"
+      ALL_FIELDS_ERROR_MSG          = "publish name (:all) reserved"
+      COMPILED_ERROR_MSG            = "field set configuration not compiled"
+      FIELD_SET_ERROR_MSG           = "invalid field set"
+
+    end
+  end
+end

data/lib/active_facets/errors/lookup_error.rb

@@ -0,0 +1,6 @@
+module ActiveFacets
+  module Errors
+    class LookupError < StandardError
+    end
+  end
+end

data/lib/active_facets/resource_manager.rb

@@ -0,0 +1,124 @@
+#TODO --jdc rebuild this class to either not use an explicit singleton pattern or use a factory pattern
+module ActiveFacets
+  class ResourceManager
+
+    cattr_accessor :resource_mapper, :serializer_mapper
+
+    # Default resource mapping scheme, can be overrided with config
+    def self.default_resource_mapper(resource_class)
+      [].tap do |map|
+        until(resource_class.superclass == BasicObject) do
+          map << resource_class.name.tableize
+          resource_class = resource_class.superclass
+        end
+      end
+    end
+    self.resource_mapper = method(:default_resource_mapper)
+
+    # TODO --jdc implement recursive superclass/parentclass lookup
+    # Default serializer mapping scheme, can be overrided with config
+    def self.default_serializer_mapper(resource_class, serializer, type, version, options)
+      case type
+      when :serializer
+        [
+          'V' + version.to_i.to_s + '::' + resource_class.name.camelcase + '::' + resource_class.name.camelcase + type.to_s.camelcase,
+          'V' + version.to_i.to_s + '::' + resource_class.name.camelcase + type.to_s.camelcase,
+        ].each { |name|
+          klass = name.safe_constantize
+          return klass.new if klass.present?
+        }
+      else
+        [
+          'V' + version.to_i.to_s + '::' + resource_class.name.camelcase + '::' + serializer + type.to_s.camelcase,
+          'V' + version.to_i.to_s + '::' + serializer + type.to_s.camelcase,
+        ].find { |name|
+          klass = name.safe_constantize
+          return klass if klass.present?
+        }
+      end
+    end
+    self.serializer_mapper = method(:default_serializer_mapper)
+
+    # Singleton
+    # @return [ResourceManager]
+    def self.instance
+      @instance ||= new
+    end
+
+    # (Memoized) Associate a serializer with a resource_class
+    # @param resource_class [Object]
+    # @param serializer [Serializer::Base]
+    # @param namespace [String] (TODO --jdc currently unused)
+    # @return [Array]
+    def register(resource_class, serializer, namespace = nil)
+      registry[resource_class] = [serializer, namespace]
+    end
+
+    # Fetches the serializer registered for the resource_class
+    # @param resource_class [Object] to find serializer for
+    # @param options [Hash] context
+    # @return [Serializer::Base]
+    def serializer_for(resource_class, options)
+      fetch_serializer(resource_class, resource_class.name.demodulize.to_s.camelcase, :serializer, options)
+    end
+
+    # Fetches the attribute serializer registered for the given resource_class
+    # @param resource_class [Object] to find attribute serializer class for
+    # @param attribute_class_name [String] to find attribute serializer class for
+    # @param options [Hash] context
+    # @return [AttributeSerializer::Base]
+    def attribute_serializer_class_for(resource_class, attribute_name, options)
+      fetch_serializer(resource_class, attribute_name.to_s.camelcase, :attribute_serializer, options)
+    end
+
+    # Fetches the resource class registered for the serializer
+    # @param serializer [Serializer::Base] to find resource class for
+    # @return [Object]
+    def resource_class_for(serializer)
+      registry.each_pair do |resource_class, entry|
+        return resource_class if serializer == entry[0]
+      end
+      nil
+    end
+
+    # Fetches the set of filter and field override indexes for resource_class
+    # @param resource_class [Object]
+    # @return [Array] of string indexes
+    def resource_map(resource_class)
+      memoized_resource_map[resource_class] ||= begin
+        self.class.resource_mapper.call(resource_class)
+      end
+    end
+
+    def extract_version_from_opts(options)
+      ((options.try(:[], ActiveFacets.opts_key) || {})[ActiveFacets.version_key] || ActiveFacets.default_version).to_f
+    end
+
+    private
+
+    attr_accessor :registry, :memoized_serializers, :memoized_resource_map
+
+    # @return [ResourceManager]
+    def initialize
+      self.registry = {}
+      self.memoized_serializers = {}
+      self.memoized_resource_map = {}
+    end
+
+    # Retrieves serializer class from memory or lookup
+    # @param resource_class [Class] the class of the resource to serialize
+    # @param serializer [String] name of the base_class of the resource to serialize
+    # @param type [String] type of serializer to look for (attribute vs. basic, etc.)
+    # @param options [Hash] context
+    # @return [Class] the first Class successfully described
+    def fetch_serializer(resource_class, serializer, type, options)
+      version = extract_version_from_opts(options)
+      unless result = self.class.serializer_mapper.call(resource_class, serializer, type, version, options)
+        error_message = "Unable to locate serializer for:: " + [resource_class.name, serializer, type, version].to_s
+        Rails.logger.debug error_message
+        raise ActiveFacets::Errors::LookupError.new(error_message) if ActiveFacets.strict_lookups
+      end
+      result
+    end
+  end
+end