praxis 0.18.1 → 0.19.0

data/lib/api_browser/app/views/type/details.html

@@ -16,7 +16,7 @@
           <div class="col-md-4">
             <h4>Attributes</h4>
             <ul>
-              <li ng-repeat="(name,value) in view.attributes">{{name}} <span class="label label-default" ng-if="value.view">rendered with {{value.view}} view</span></li>
+              <li ng-repeat="(name,value) in view.attributes">{{name}} <span class="label label-default" ng-if="value.view">{{value.view}} view</span></li>
             </ul>
           </div>
           <div class="col-md-8">

data/lib/api_browser/app/views/type.html

@@ -16,7 +16,7 @@
       <h3>Served by</h3>
       <ul>
         <li ng-repeat="controller in controllers">
-          <a ui-sref="root.controller({version: apiVersion, controller: controller.controller})">{{ controller.name | resourceName }}</a>
+          <a ui-sref="root.controller({version: apiVersion, controller: controller.id})">{{ controller.name | resourceName }}</a>
         </li>
       </ul>
     </div>

data/lib/api_browser/app/views/types/embedded/field-selector.html

@@ -0,0 +1,13 @@
+<tr>
+  <td ng-bind-html="name | attributeName">
+  </td>
+  <td>
+    <a ui-sref="root.builtin.field-selector">FieldSelector</a>
+  </td>
+  <td>
+    <p>This attribute allows you to specify what response you would like from
+      the API. You can select individual fields from the schema using a comma
+      separated list. <a ui-sref="root.builtin.field-selector">Find out more</a>.</p>
+    <attribute-description attribute="details"></attribute-description>
+  </td>
+</tr>

data/lib/api_browser/app/views/types/label/primitive.html

@@ -1 +1 @@
-<span>{{type.name}}</span>
+<span>{{type.name | resourceName}}</span>

data/lib/api_browser/app/views/types/standalone/array.html

@@ -0,0 +1,3 @@
+<p>A Collection of:</p>
+
+<type-placeholder type="type.member_attribute.type" template="standalone" details="type.member_attribute.type.attributes"></type-placeholder>

data/lib/praxis/action_definition.rb

@@ -95,7 +95,7 @@ module Praxis
     end
 
     def create_attribute(type=Attributor::Struct, **opts, &block)
-      unless opts[:reference]
+      unless opts.key?(:reference)
         opts[:reference] = @reference_media_type if @reference_media_type && block
       end
 
@@ -222,7 +222,7 @@ module Praxis
         hash[:metadata] = metadata
         if headers
           headers_example = headers.example(context)
-          hash[:headers] = headers.describe(example: headers_example)
+          hash[:headers] = headers_description(example: headers_example)
         end
         if params
           params_example = params.example(context)
@@ -249,6 +249,14 @@ module Praxis
       end
     end
 
+    def headers_description(example: )
+      output = headers.describe(example: example)
+      required_headers = self.headers.attributes.select{|k,attr| attr.options && attr.options[:required] == true  }
+      output[:example] = required_headers.each_with_object({}) do | (name, attr), hash |
+        hash[name] = example[name].to_s # Some simple types (like Boolean) can be used as header values, but must convert back to s
+      end
+      output
+    end
 
     def params_description(example:)
       route_params = []
@@ -270,6 +278,11 @@ module Praxis
         end
         desc[:type][:attributes][k][:source] = source
       end
+      required_params = desc[:type][:attributes].select{|k,v| v[:source] == 'query' && v[:required] == true }.keys
+      phash = required_params.each_with_object({}) do | name, hash |
+        hash[name] = example[name]
+      end
+      desc[:example] = URI.encode_www_form(phash)
       desc
     end
 

data/lib/praxis/collection.rb

@@ -1,5 +1,5 @@
 module Praxis
- class Collection < Attributor::Collection
+  class Collection < Attributor::Collection
     include Types::MediaTypeCommon
 
     def self.of(type)
@@ -8,12 +8,10 @@ module Praxis
       end
 
       klass = super
+      klass.anonymous_type
 
       if type < Praxis::Types::MediaTypeCommon
-        unless type.identifier.nil?
-          klass.identifier(type.identifier + ';type=collection')
-        end
-
+        klass.member_type type
         type.const_set :Collection, klass
       else
         warn "DEPRECATION: Praxis::Collection.of() for non-MediaTypes will be unsupported in 1.0. Use Attributor::Collection.of() instead."
@@ -25,10 +23,24 @@ module Praxis
     def self.member_type(type=nil)
       unless type.nil?
         @member_type = type
+        @views = nil
+        self.identifier(type.identifier + ';type=collection') unless type.identifier.nil?
       end
 
       @member_type
     end
 
+    def self.views
+      @views ||= begin
+        @member_type.views.each_with_object(Hash.new) do |(name, view), hash|
+          hash[name] = Praxis::CollectionView.new(name, @member_type, view)
+        end
+      end
+    end
+
+    def self.domain_model
+      @member_type.domain_model
+    end
+
   end
 end

data/lib/praxis/controller.rb

@@ -4,10 +4,10 @@ require 'active_support/all'
 module Praxis
   module Controller
     extend ::ActiveSupport::Concern
-    
+
     # A Controller always requires the callbacks
     include Praxis::Callbacks
-    
+
     included do
       attr_reader :request
       attr_accessor :response
@@ -22,7 +22,7 @@ module Praxis
         definition.controller = self
         Application.instance.controllers << self
       end
-      
+
       def id
         self.name.gsub('::'.freeze,'-'.freeze)
       end
@@ -36,5 +36,14 @@ module Praxis
     def definition
       self.class.definition
     end
+
+    def media_type
+      if (response_definition = self.request.action.responses[self.response.name])
+        return response_definition.media_type
+      else
+        self.definition.media_type
+      end
+    end
+
   end
 end

data/lib/praxis/docs/generator.rb

@@ -35,7 +35,8 @@ module Praxis
       end
 
       def save!
-        write_index_file
+        # Restrict the versions listed in the index file to the ones for which we have at least 1 resource
+        write_index_file( for_versions: resources_by_version.keys )
         resources_by_version.keys.each do |version|
           write_version_file(version)
         end
@@ -97,9 +98,9 @@ module Praxis
         reachable_types
       end
 
-      def write_index_file
+      def write_index_file( for_versions:  )
         # Gather the versions
-        versions = infos_by_version.keys.reject{|v| v == :global || v == :traits }.map do |version|
+        versions = infos_by_version.keys.reject{|v| v == :global || v == :traits || !for_versions.include?(v) }.map do |version|
           version == "n/a" ? "unversioned" : version
         end
         data = {
@@ -118,18 +119,17 @@ module Praxis
         # Eventually traits should be defined for a version (and inheritable from global) so we'll emulate that here
         version_info[:traits] = infos_by_version[:traits]
         dumped_resources = dump_resources( resources_by_version[version] )
-        found_media_types =  resources_by_version[version].collect {|r| r.media_type.describe }
+        found_media_types =  resources_by_version[version].select{|r| r.media_type}.collect {|r| r.media_type.describe }
 
         collected_types = Set.new
         collect_reachable_types( dumped_resources, collected_types );
         collect_reachable_types( found_media_types , collected_types );
 
         dumped_schemas = dump_schemas( collected_types )
-
         full_data = {
           info: version_info[:info],
           resources: dumped_resources,
-          schemas: nil,#dumped_schemas,
+          schemas: dumped_schemas,
           traits: version_info[:traits] || []
         }
         # Write the file
@@ -169,9 +169,13 @@ module Praxis
       def dump_schemas(types)
         reportable_types = types - EXCLUDED_TYPES_FROM_OUTPUT
         reportable_types.each_with_object({}) do |type, array|
+          next if ( type.respond_to?(:anonymous?) && type.anonymous? )
+
           context = [type.id]
           example_data = type.example(context)
           type_output = type.describe(false, example: example_data)
+
+          type_output[:display_name] = type.display_name if type.respond_to?(:display_name)
           unless type_output[:display_name]
             # For non MediaTypes or pure types or anonymous types fallback to their name, and worst case to their id
             type_output[:display_name] = type_output[:name] || type_output[:id]
@@ -205,4 +209,4 @@ module Praxis
 
     end
   end
-end
+end

data/lib/praxis/extensions/field_expansion.rb

@@ -0,0 +1,59 @@
+module Praxis
+  module Extensions
+    module FieldExpansion
+      extend ActiveSupport::Concern
+
+      included do
+        Praxis::ActionDefinition.send(:include, ActionDefinitionExtension)
+      end
+
+
+      def expanded_fields
+        @expansion ||= request.action.expanded_fields(self.request, self.media_type)
+      end
+
+
+      module ActionDefinitionExtension
+        extend ActiveSupport::Concern
+
+        def expanded_fields(request, media_type)
+          use_fields = self.params.attributes.key?(:fields)
+          use_view = self.params.attributes.key?(:view)
+
+          # Determine what, if any, fields to display.
+          fields = if use_fields
+            request.params.fields.fields
+          else
+            true
+          end
+
+          # Determine the view that COULD be applicable.
+          view = if use_view && (view_name = request.params.view)
+            media_type.views[view_name]
+          else
+            media_type.views[:default]
+          end
+
+          expandable = if fields == true
+            # We want to show ALL of the available fields.
+            # This can never be applied to the type (it's likely infinitely recursive).
+            # So use view_name determimed above.
+            view
+          else
+            # We want to show SOME of fields available on a view or type.
+            if use_view && request.params.view
+              # Use the requested view.
+              view
+            else
+              # Use the type.
+              media_type
+            end
+          end
+
+          Praxis::FieldExpander.expand(expandable,fields)
+        end
+      end
+
+    end
+  end
+end

data/lib/praxis/extensions/field_selection/field_selector.rb

@@ -0,0 +1,125 @@
+
+module Praxis
+  module Extensions
+    module FieldSelection
+
+        class FieldSelector
+          include Attributor::Type
+
+          def self.native_type
+            self
+          end
+
+          def self.display_name
+            'FieldSelector'
+          end
+
+          def self.family
+            'string'
+          end
+
+          def self.for(media_type)
+            unless media_type < Praxis::MediaType
+              raise ArgumentError, "Invalid type: #{media_type.name} for FieldSelector. " +
+                "Must be a subclass of MediaType"
+            end
+
+            ::Class.new(self) do
+              @media_type = media_type
+            end
+          end
+
+          def self.load(value,context=Attributor::DEFAULT_ROOT_CONTEXT, **options)
+            return value if value.kind_of?(self.native_type)
+
+            if value.nil? || value.blank?
+              self.new(true)
+            else
+              parsed = Attributor::FieldSelector.load(value)
+              self.new(parsed)
+            end
+          end
+
+          def self.example(context=Attributor::DEFAULT_ROOT_CONTEXT, **options)
+            fields = if media_type
+              media_type.attributes.keys.sample(3).join(',')
+            else
+              Attributor::FieldSelector.example(context,**options)
+            end
+            self.load(fields)
+          end
+
+          def self.validate(value, context=Attributor::DEFAULT_ROOT_CONTEXT, _attribute=nil)
+            return [] unless media_type
+            instance = self.load(value, context)
+            instance.validate(context)
+          end
+
+          def self.dump(value,**opts)
+            self.load(value).dump
+          end
+
+          class << self
+            attr_reader :media_type
+          end
+
+          attr_reader :fields
+
+          def initialize(fields)
+            @fields = fields
+          end
+
+          def dump(*args)
+            return '' if self.fields == true
+            _dump(self.fields)
+          end
+
+          def _dump(fields)
+            fields.each_with_object([]) do |(field, spec), array|
+              if spec == true
+                array << field
+              else
+                array << "#{field}{#{_dump(spec)}}"
+              end
+            end.join(',')
+          end
+
+          def validate(context=Attributor::DEFAULT_ROOT_CONTEXT)
+            errors = []
+            return errors if self.fields == true
+            _validate(self.class.media_type, fields)
+          end
+
+          def _validate(type, fields, context=Attributor::DEFAULT_ROOT_CONTEXT)
+            errors = []
+            fields.each do |name, field_spec|
+              unless type.attributes.key?(name)
+                errors << "Attribute with name #{name} not found in #{Attributor.type_name(type)}"
+                next
+              end
+
+              if field_spec.kind_of?(Hash)
+                sub_context = context + [name]
+                sub_attribute = type.attributes[name]
+                sub_type = sub_attribute.type
+                if sub_attribute.type.respond_to?(:member_attribute)
+                  sub_type = sub_type.member_type
+                end
+                errors.push(*_validate(sub_type,field_spec, sub_context))
+              end
+            end
+            errors
+          end
+
+        end
+
+    end
+  end
+end
+
+# Alias it to a much shorter and sweeter name in the Types namespace.
+module Praxis
+  module Types
+    FieldSelector = Praxis::Extensions::FieldSelection::FieldSelector
+  end
+end

data/lib/praxis/extensions/field_selection.rb

@@ -0,0 +1,10 @@
+require 'attributor/extras/field_selector'
+
+require 'praxis/extensions/field_selection/field_selector'
+
+module Praxis
+  module Extensions
+    module FieldSelection
+    end
+  end
+end

data/lib/praxis/extensions/mapper_selectors.rb

@@ -0,0 +1,16 @@
+module Praxis
+  module Extensions
+    module MapperSelectors
+      extend ActiveSupport::Concern
+      include FieldExpansion
+
+      def set_selectors
+        return unless self.media_type.respond_to?(:domain_model) &&
+          self.media_type.domain_model < Praxis::Mapper::Resource
+
+        resolved = Praxis::MediaType::FieldResolver.resolve(self.media_type, self.expanded_fields)
+        identity_map.add_selectors(self.media_type.domain_model, resolved)
+      end
+    end
+  end
+end

data/lib/praxis/extensions/rendering.rb

@@ -0,0 +1,43 @@
+module Praxis
+  module Extensions
+
+    module Rendering
+      extend ActiveSupport::Concern
+      include FieldExpansion
+
+      def render(object, include_nil: false)
+        loaded = self.media_type.load(object)
+        renderer = Praxis::Renderer.new(include_nil: include_nil)
+        renderer.render(loaded, self.expanded_fields)
+      rescue Attributor::DumpError
+        if self.media_type.domain_model == Object
+          warn "Detected the rendering of an object of type #{self.media_type} without having a domain object model set.\n" +
+               "Did you forget to define it?"
+        end
+        raise
+      end
+
+      def display(object, include_nil: false, encoder: self.default_encoder )
+        identifier = Praxis::MediaTypeIdentifier.load(self.media_type.identifier)
+        identifier += encoder unless encoder.blank?
+        response.headers['Content-Type'] = identifier.to_s
+        response.body = render(object, include_nil: include_nil)
+        response
+      rescue Praxis::Renderer::CircularRenderingError => e
+          Praxis::Application.instance.validation_handler.handle!(
+          summary: "Circular Rendering Error when rendering response. " +
+                   "Please especify a view to narrow the dependent fields, or narrow your field set.",
+          exception: e,
+          request: request,
+          stage: :action,
+          errors: nil
+        )
+      end
+
+      def default_encoder
+        ''
+      end
+
+    end
+  end
+end

data/lib/praxis/links.rb

@@ -32,6 +32,7 @@ module Praxis
       klass = Class.new(self) do
         @reference = reference
         @links = Hash.new
+        anonymous_type
       end
 
       reference.const_set :Links, klass

data/lib/praxis/media_type.rb

@@ -55,6 +55,7 @@ module Praxis
   #     end
   #   end
   class MediaType < Praxis::Blueprint
+
     include Types::MediaTypeCommon
 
     class DSLCompiler < Attributor::DSLCompiler
@@ -69,10 +70,11 @@ module Praxis
 
     def self._finalize!
       super
+
+      # Only define our special links accessor if it was setup using the special DSL
+      # (we might have an app defining an attribute called `links` on its own, in which
+      # case we leave it be)
       if @attribute && self.attributes.key?(:links) && self.attributes[:links].type < Praxis::Links
-        # Only define out special links accessor if it was setup using the special DSL
-        # (we might have an app defining an attribute called `links` on its own, in which
-        # case we leave it be)
         module_eval <<-RUBY, __FILE__, __LINE__ + 1
         def links
           self.class::Links.new(@object)
@@ -81,6 +83,88 @@ module Praxis
       end
     end
 
+
+    class FieldResolver
+      def self.resolve(type,fields)
+        self.new.resolve(type,fields)
+      end
+
+      attr_reader :history
+
+      def initialize
+        @history = Hash.new do |hash,key|
+          hash[key] = Hash.new
+        end
+      end
+
+      def resolve(type,fields)
+        history_key = fields
+        history_type = type
+        if fields.kind_of?(Array)
+          loop do
+            type = type.member_attribute.type
+            fields = fields.first
+            break unless fields.kind_of?(Array)
+          end
+        end
+
+        return true if fields == true
+
+        if history[history_type].include? history_key
+          return history[history_type][history_key]
+        end
+
+        result = history[history_type][history_key] = {}
+
+
+        fields.each do |name, sub_fields|
+          # skip links and do them below
+          next if name == :links && defined?(type::Links)
+
+          new_type = type.attributes[name].type
+          result[name] = resolve(new_type, sub_fields)
+        end
+
+        # now to tackle whatever links there may be
+        if (links_fields = fields[:links])
+          resolved_links = resolve_links(type::Links, links_fields)
+          self.deep_merge(result, resolved_links)
+        end
+
+        result
+      end
+
+      def resolve_links(links_type, links)
+        links.each_with_object({}) do |(name, link_fields), hash|
+          using = links_type.links[name]
+          new_type = links_type.attributes[name].type
+          hash[using] = resolve(new_type, link_fields)
+        end
+      end
+
+      # perform a deep recursive *in place* merge
+      # form all values in +source+ onto +target+
+      #
+      # note: can not use ActiveSupport's Hash#deep_merge! because it does not
+      # properly do a recursive `deep_merge!`, but instead does `deep_merge`,
+      # which destroys the self-referential behavior of field hashes.
+      #
+      # note: unlike Hash#merge, doesn't take a block.
+      def deep_merge(target, source)
+        source.each do |current_key, source_value|
+          target_value = target[current_key]
+
+          target[current_key] = if target_value.is_a?(Hash) && source_value.is_a?(Hash)
+            deep_merge(target_value, source_value)
+          else
+            source_value
+          end
+        end
+        target
+      end
+
+    end
+
   end
 
 end

data/lib/praxis/media_type_collection.rb

@@ -104,7 +104,7 @@ module Praxis
     def self.member_view(name, using: nil)
       if using
         member_view = self.member_type.view(using)
-        return self.views[name] = CollectionView.new(name, self, member_view)
+        return self.views[name] = CollectionView.new(name, self.member_type, member_view)
       end
 
       self.views[name]

data/lib/praxis/media_type_identifier.rb

@@ -1,4 +1,5 @@
 require 'set'
+require 'active_support/core_ext/object/blank'
 
 module Praxis
   # Ruby object representation of an Internet Media Type Identifier as defined by
@@ -41,7 +42,9 @@ module Praxis
     # @return [MediaTypeIdentifier]
     # @see Attributor::Model#load
     def self.load(value, context=Attributor::DEFAULT_ROOT_CONTEXT, recurse: false, **options)
-      if value.is_a?(String)
+      case value
+      when String
+        return nil if value.blank?
         base, *parameters = value.split(PARAMETER_SEPARATOR)
         match = VALID_TYPE.match(base)
 
@@ -62,6 +65,8 @@ module Praxis
           obj.parameters = {}
         end
         obj
+      when nil
+        return nil
       else
         super
       end