praxis 2.0.pre.6 → 2.0.pre.11

data/lib/praxis/bootloader.rb

@@ -48,7 +48,7 @@ module Praxis
 
       after(:app) do
         Praxis::Blueprint.finalize!
-        Praxis::ResourceDefinition.finalize!
+        Praxis::EndpointDefinition.finalize!
       end
 
     end
@@ -66,12 +66,18 @@ module Praxis
 
     def before(*stage_path, &block)
       stage_name = stage_path.shift
-      stages.find { |stage| stage.name == stage_name }.before(*stage_path, &block)
+      the_stage = stages.find { |stage| stage.name == stage_name }
+      raise Exceptions::StageNotFound.new("Error running a before block for stage #{stage_name}") unless the_stage
+
+      the_stage.before(*stage_path, &block)
     end
 
     def after(*stage_path, &block)
       stage_name = stage_path.shift
-      stages.find { |stage| stage.name == stage_name }.after(*stage_path, &block)
+      the_stage = stages.find { |stage| stage.name == stage_name }
+      raise Exceptions::StageNotFound.new("Error running an after block for stage #{stage_name}") unless the_stage
+
+      the_stage.after(*stage_path, &block)
     end
 
     def use(plugin,**options, &block)

data/lib/praxis/bootloader_stages/environment.rb

@@ -20,19 +20,22 @@ module Praxis
 
       def setup_default_layout!
         application.layout do
-          layout do
-            map :initializers, 'config/initializers/**/*'
-            map :lib, 'lib/**/*'
-            map :design, 'design/' do
-              map :api, 'api.rb'
-              map :media_types, '**/media_types/**/*'
-              map :resources, '**/resources/**/*'
-            end
-            map :app, 'app/' do
-              map :models, 'models/**/*'
-              map :controllers, '**/controllers/**/*'
-              map :responses, '**/responses/**/*'
-            end
+          map :initializers, 'config/initializers/**/*'
+          map :lib, 'lib/**/*'
+          map :design, 'design/' do
+            map :api, 'api.rb'
+            map :helpers, '**/helpers/**/*'
+            map :types, '**/types/**/*'
+            map :media_types, '**/media_types/**/*'
+            map :endpoints, '**/endpoints/**/*'
+          end
+          map :app, 'app/' do
+            map :models, 'models/**/*'
+            map :responses, '**/responses/**/*'
+            map :exceptions, '**/exceptions/**/*'
+            map :concerns, '**/concerns/**/*'
+            map :resources, '**/resources/**/*'
+            map :controllers, '**/controllers/**/*'
           end
         end
       end

data/lib/praxis/collection.rb

@@ -14,8 +14,7 @@ module Praxis
         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."
-        Attributor::Collection.of(type)
+        raise "Praxis::Collection.of() for non-MediaTypes is unsupported. Use Attributor::Collection.of() instead."
       end
 
     end
@@ -23,21 +22,12 @@ 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

data/lib/praxis/config_hash.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+# TODO: move to Praxis proper...it's not used here
+module Praxis
+  class ConfigHash < BasicObject
+    attr_reader :hash
+
+    def self.from(hash = {}, &block)
+      new(hash, &block)
+    end
+
+    def initialize(hash = {}, &block)
+      @hash = hash
+      @block = block
+    end
+
+    def to_hash
+      instance_eval(&@block)
+      @hash
+    end
+
+    def respond_to_missing?(_method_name, _include_private = false)
+      true
+    end
+
+    def method_missing(name, value, *rest, &block) # rubocop:disable Style/MethodMissing
+      if (existing = @hash[name])
+        if block
+          existing << [value, block]
+        else
+          existing << value
+          rest.each do |v|
+            existing << v
+          end
+        end
+      else
+        @hash[name] = if rest.any?
+                        [value] + rest
+                      else
+                        value
+                      end
+      end
+    end
+  end
+end

data/lib/praxis/docs/{openapi → open_api}/info_object.rb

@@ -10,20 +10,28 @@ module Praxis
         end
 
         def dump
-          data ={
-            title: info.title,
-            description: info.description,
-            termsOfService: info.termsOfService,
-            contact: info.contact,
-            license: info.license,
-            version: version,
-            :'x-name' => info.name,
-            :'x-logo' => {
+          data = { version: version }
+          [
+            :title,
+            :description,
+            :termsOfService,
+            :contact,
+            :license
+          ].each do |attr|
+            val = info.send(attr)
+            data[attr] = val if val
+          end
+
+          # Special attributes
+          data[:'x-name'] = info.name
+          if info.logo_url
+            data[:'x-logo'] = {
               url: info.logo_url,
               backgroundColor: "#FFFFFF",
               altText: info.title
             }
-          }
+          end
+          data
         end
       end
     end

data/lib/praxis/docs/{openapi → open_api}/parameter_object.rb

@@ -48,11 +48,11 @@ module Praxis
   
           if action.params
             route_params = \
-              if action.primary_route.nil?
+              unless action.route
                 warn "Warning: No routes defined for action #{action.name}"
                 []
               else
-                action.primary_route.path.named_captures.keys.collect(&:to_sym)
+                action.route.path.named_captures.keys.collect(&:to_sym)
               end
             (action.params.attributes||{}).each_with_object(output) do |(name, info), out|
               in_type = route_params.include?(name) ? :path : :query

data/lib/praxis/docs/{openapi → open_api}/paths_object.rb

@@ -31,21 +31,18 @@ module Praxis
           # fill in the paths hash with a key for each path for each action/route
           resource.actions.each do |action_name, action|
             params_example =  action.params ? action.params.example(nil) : nil
-            urls = action.routes.collect do |route|
-              ActionDefinition.url_description(route: route, params: action.params, params_example: params_example)
-            end.compact
-            urls.each do |url|
-              verb = url[:verb].downcase
-              templetized_path = OpenApiGenerator.templatize_url(url[:path])
-              path_entry = paths[templetized_path]
-              # Let's fill in verb stuff within the working hash
-              raise "VERB #{_verb} already defined for #{id}!?!?!" if path_entry[verb]
-              
-              action_uid = "action-#{action_name}-#{id}"
-              # Add a tag matching the resource name (hoping all actions of a resource are grouped)
-              action_tags = [resource.display_name]
-              path_entry[verb] = OperationObject.new( id: action_uid, url: url, action: action, tags: action_tags).dump
-            end
+            url = ActionDefinition.url_description(route: action.route, params: action.params, params_example: params_example)
+
+            verb = url[:verb].downcase
+            templetized_path = OpenApiGenerator.templatize_url(url[:path])
+            path_entry = paths[templetized_path]
+            # Let's fill in verb stuff within the working hash
+            raise "VERB #{_verb} already defined for #{id}!?!?!" if path_entry[verb]
+            
+            action_uid = "action-#{action_name}-#{id}"
+            # Add a tag matching the resource name (hoping all actions of a resource are grouped)
+            action_tags = [resource.display_name]
+            path_entry[verb] = OperationObject.new( id: action_uid, url: url, action: action, tags: action_tags).dump
           end
           # For each path, we can further annotate with 
           # servers

data/lib/praxis/docs/open_api_generator.rb

@@ -1,13 +1,31 @@
-require_relative 'openapi/info_object.rb'
-require_relative 'openapi/server_object.rb'
-require_relative 'openapi/paths_object.rb'
-require_relative 'openapi/tag_object.rb'
+require_relative 'open_api/info_object.rb'
+require_relative 'open_api/server_object.rb'
+require_relative 'open_api/paths_object.rb'
+require_relative 'open_api/tag_object.rb'
 
 module Praxis
   module Docs
 
-    class OpenApiGenerator < Generator
+    class OpenApiGenerator
+      require 'active_support/core_ext/enumerable' # For index_by
+
       API_DOCS_DIRNAME = 'docs/openapi' 
+      EXCLUDED_TYPES_FROM_OUTPUT = Set.new([
+        Attributor::Boolean,
+        Attributor::CSV,
+        Attributor::DateTime,
+        Attributor::Date,
+        Attributor::Float,
+        Attributor::Hash,
+        Attributor::Ids,
+        Attributor::Integer,
+        Attributor::Object,
+        Attributor::String,
+        Attributor::Symbol,
+        Attributor::URI,
+      ]).freeze
+
+      attr_reader :resources_by_version, :types_by_id, :infos_by_version, :doc_root_dir
 
       # substitutes ":params_like_so" for {params_like_so}
       def self.templatize_url( string )
@@ -37,10 +55,77 @@ module Praxis
 
       private
 
+      def collect_resources
+        # load all resource definitions registered with Praxis
+        Praxis::Application.instance.endpoint_definitions.map do |resource|
+          # skip resources with doc_visibility of :none
+          next if resource.metadata[:doc_visibility] == :none
+          version = resource.version
+          # TODO: it seems that we shouldn't hardcode n/a in Praxis
+          #  version = "unversioned" if version == "n/a"
+          @resources_by_version[version] << resource
+        end
+      end
+
+      def collect_types
+        @types_by_id = ObjectSpace.each_object( Class ).select do |obj|
+          obj < Attributor::Type
+        end.index_by(&:id)
+      end
+
       def write_index_file( for_versions: )
         # TODO. create a simple html file that can link to the individual versions available
       end
 
+      def scan_types_for_version(version, dumped_resources)
+        found_media_types =  resources_by_version[version].select{|r| r.media_type}.collect {|r| r.media_type.describe }
+
+        # We'll start by processing the rendered mediatypes
+        processed_types = Set.new(resources_by_version[version].select do|r|
+          r.media_type && !r.media_type.is_a?(Praxis::SimpleMediaType)
+        end.collect(&:media_type))
+
+        newfound = Set.new
+        found_media_types.each do |mt|
+          newfound += scan_dump_for_types( { type: mt} , processed_types )
+        end
+        # Then will process the rendered resources (noting)
+        newfound += scan_dump_for_types( dumped_resources, Set.new )
+
+        # At this point we've done a scan of the dumped resources and mediatypes.
+        # In that scan we've discovered a bunch of types, however, many of those might have appeared in the JSON
+        # rendered in just shallow mode, so it is not guaranteed that we've seen all the available types.
+        # For that we'll do a (non-shallow) dump of all the types we found, and scan them until the scans do not
+        # yield types we haven't seen before
+        while !newfound.empty? do
+          dumped = newfound.collect(&:describe)
+          processed_types += newfound
+          newfound = scan_dump_for_types( dumped, processed_types )
+        end
+        processed_types
+      end
+
+      def scan_dump_for_types( data, processed_types )
+        newfound_types = Set.new
+        case data
+        when Array
+          data.collect{|item| newfound_types += scan_dump_for_types( item , processed_types ) }
+        when Hash
+          if data.key?(:type) && data[:type].kind_of?(Hash) && ( [:id,:name,:family] - data[:type].keys ).empty?
+            type_id = data[:type][:id]
+            unless type_id.nil? || type_id == Praxis::SimpleMediaType.id #SimpleTypes shouldn't be collected
+              unless types_by_id[type_id]
+                raise "Error! We have detected a reference to a 'Type' with id='#{type_id}' which is not derived from Attributor::Type" +
+                      " Document generation cannot proceed."
+              end
+              newfound_types << types_by_id[type_id] unless processed_types.include? types_by_id[type_id]
+            end
+          end
+          data.values.map{|item| newfound_types += scan_dump_for_types( item , processed_types)}
+        end
+        newfound_types
+      end
+
       def write_version_file( version )
         # version_info = infos_by_version[version]
         # # Hack, let's "inherit/copy" all traits of a version from the global definition
@@ -159,7 +244,7 @@ module Praxis
         resources_by_version.keys.each do |version|
           FileUtils.mkdir_p @doc_root_dir + '/' + version
         end
-        FileUtils.mkdir_p @doc_root_dir + '/unversioned'
+        FileUtils.mkdir_p @doc_root_dir + '/unversioned' if resources_by_version.keys.include?('n/a')
       end
 
       def normalize_media_types( mtis )

data/lib/praxis/endpoint_definition.rb

@@ -0,0 +1,273 @@
+require 'active_support/concern'
+require 'active_support/inflector'
+
+module Praxis
+  module EndpointDefinition
+    extend ActiveSupport::Concern
+
+    DEFAULT_RESOURCE_HREF_ACTION = :show
+
+    included do
+      @version = 'n/a'.freeze
+      @actions = Hash.new
+      @responses = Hash.new
+
+      @action_defaults = Trait.new &EndpointDefinition.generate_defaults_block
+
+      @version_options = {}
+      @metadata = {}
+      @traits = []
+
+      if self.name
+        @prefix = '/' + self.name.split("::").last.underscore
+      else
+        @prefix = '/'
+      end
+
+      @version_prefix = ''
+
+      @parent = nil
+      @parent_prefix = ''
+
+      @routing_prefix = nil
+
+      @on_finalize = Array.new
+
+      Application.instance.endpoint_definitions << self
+    end
+
+    def self.generate_defaults_block( version: nil )
+
+      # Ensure we inherit any base params defined in the API definition for the passed in version
+      base_attributes = if (base_params = ApiDefinition.instance.info(version).base_params)
+        base_params.attributes
+      else
+        {}
+      end
+
+      Proc.new do
+        unless base_attributes.empty?
+          params do
+            base_attributes.each do |base_name, base_attribute|
+              attribute base_name, base_attribute.type, **base_attribute.options
+            end
+          end
+        end
+      end
+    end
+
+    def self.finalize!
+      Application.instance.endpoint_definitions.each do |resource_definition|
+        while (block = resource_definition.on_finalize.shift)
+          block.call
+        end
+      end
+    end
+
+
+
+    module ClassMethods
+      attr_reader :actions
+      attr_reader :responses
+      attr_reader :version_options
+      attr_reader :traits
+      attr_reader :version_prefix
+      attr_reader :parent_prefix
+
+      # opaque hash of user-defined medata, used to decorate the definition,
+      # and also available in the generated JSON documents
+      attr_reader :metadata
+
+      attr_accessor :controller
+
+      def display_name( string=nil )
+        unless string
+          return  @display_name ||= self.name.split("::").last  # Best guess at a display name?
+        end
+        @display_name = string
+      end
+
+      def on_finalize(&block)
+        if block_given?
+          @on_finalize << proc(&block)
+        end
+
+        @on_finalize
+      end
+
+      def prefix(prefix=nil)
+        return @prefix if prefix.nil?
+        @routing_prefix = nil # reset routing_prefix
+        @prefix = prefix
+      end
+
+      def media_type(media_type=nil)
+        return @media_type if media_type.nil?
+
+        if media_type.kind_of?(String)
+          media_type = SimpleMediaType.new(media_type)
+        end
+        @media_type = media_type
+      end
+
+
+      def parent(parent=nil, **mapping)
+        return @parent if parent.nil?
+
+        @routing_prefix = nil # reset routing_prefix
+
+        parent_action = parent.canonical_path
+        parent_route = parent_action.route.path
+
+        # if a mapping is passed, it *must* resolve any param name conflicts
+        unless mapping.any?
+          # assume last capture is the relevant one to replace
+          # if not... then I quit.
+          parent_param_name = parent_route.names.last
+
+          # more assumptions about names
+          parent_name = parent.name.demodulize.underscore.singularize
+
+          # put it together to find what we should call this new param
+          param = "#{parent_name}_#{parent_param_name}".to_sym
+          mapping[parent_param_name.to_sym] = param
+        end
+
+        # complete the mapping and massage the route
+        parent_route.names.collect(&:to_sym).each do |name|
+          if mapping.key?(name)
+            param = mapping[name]
+            # FIXME: this won't handle URI Template type paths, ie '/{parent_id}'
+            prefixed_path = parent_action.route.prefixed_path
+            @parent_prefix = prefixed_path.gsub(/(:)(#{name})(\W+|$)/, "\\1#{param.to_s}\\3")
+          else
+            mapping[name] = name
+          end
+        end
+
+        self.on_finalize do
+          self.inherit_params_from_parent(parent_action, **mapping)
+        end
+
+        @parent = parent
+      end
+
+      def inherit_params_from_parent(parent_action, **mapping)
+        actions.each do |name, action|
+          action.params do
+            mapping.each do |parent_name, name|
+              next if action.params && action.params.attributes.key?(name)
+
+              parent_attribute = parent_action.params.attributes[parent_name]
+
+              attribute name, parent_attribute.type, **parent_attribute.options
+            end
+          end
+        end
+
+      end
+
+      attr_writer :routing_prefix
+
+      def routing_prefix
+        return @routing_prefix if @routing_prefix
+
+        @routing_prefix = parent_prefix + prefix
+      end
+
+
+      def version(version=nil)
+        return @version unless version
+
+        @version = version
+        @action_defaults.instance_eval &EndpointDefinition.generate_defaults_block( version: version )
+      end
+
+
+      def canonical_path(action_name=nil)
+        if action_name
+          raise "Canonical path for #{self.name} is already defined as: '#{@canonical_action_name}'. 'canonical_path' can only be defined once." if @canonical_action_name
+          @canonical_action_name = action_name
+        else
+          # Resolution of the actual action definition needs to be done lazily, since we can use the `canonical_path` stanza
+          # at the top of the resource, well before the actual action is defined.
+          unless @canonical_action
+            href_action = @canonical_action_name || DEFAULT_RESOURCE_HREF_ACTION
+            @canonical_action = actions.fetch(href_action) do
+              raise "Error: trying to set canonical_href of #{self.name}. Action '#{href_action}' does not exist"
+            end
+          end
+          return @canonical_action
+        end
+      end
+
+      def to_href( params )
+        canonical_path.route.path.expand(params.transform_values(&:to_s))
+      end
+
+      def parse_href(path)
+        if path.kind_of?(::URI::Generic)
+          path = path.path
+        end
+        param_values = canonical_path.route.path.params(path)
+        attrs = canonical_path.params.attributes
+        param_values.each_with_object({}) do |(key,value),hash|
+          hash[key.to_sym] = attrs[key.to_sym].load(value,[key])
+        end
+      rescue => e
+        raise Praxis::Exception.new("Error parsing or coercing parameters from href: #{path}\n"+e.message)
+      end
+
+      def trait(trait_name)
+        unless ApiDefinition.instance.traits.has_key? trait_name
+          raise Exceptions::InvalidTrait.new("Trait #{trait_name} not found in the system")
+        end
+        trait = ApiDefinition.instance.traits.fetch(trait_name)
+        @traits << trait_name
+      end
+      alias_method :use, :trait
+
+      def action_defaults(&block)
+        if block_given?
+          @action_defaults.instance_eval(&block)
+        end
+
+        @action_defaults
+      end
+
+      def action(name, &block)
+        raise ArgumentError, "can not create ActionDefinition without block" unless block_given?
+        raise ArgumentError, "Action names must be defined using symbols (Got: #{name} (of type #{name.class}))" unless name.is_a? Symbol
+        @actions[name] = ActionDefinition.new(name, self, &block)
+      end
+
+      def description(text=nil)
+        @description = text if text
+        @description
+      end
+
+      def id
+        self.name.gsub('::'.freeze,'-'.freeze)
+      end
+
+      def describe(context: nil)
+        {}.tap do |hash|
+          hash[:description] = description
+          hash[:media_type] = media_type.describe(true) if media_type
+          hash[:actions] = actions.values.collect{|action| action.describe(context: context)}
+          hash[:name] = self.name
+          hash[:parent] = self.parent.id if self.parent
+          hash[:display_name] = self.display_name
+          hash[:metadata] = metadata
+          hash[:traits] = self.traits
+        end
+      end
+
+      def nodoc!
+        metadata[:doc_visibility] = :none
+      end
+
+    end
+
+  end
+end