praxis 0.20.1 → 0.21

data/lib/praxis/api_general_info.rb

@@ -78,6 +78,19 @@ module Praxis
       end
     end
 
+    def documentation_url(val=nil)
+      if val.nil?
+        get(:documentation_url)
+      else
+        if @global_info.nil? # this *is* the global info
+          set(:documentation_url, val)
+        else
+          raise "Use of documentation_url is only allowed in the global part of " \
+            "the API definition (but you are attempting to use it in the API " \
+            "definition of version #{self.version}"
+        end
+      end
+    end
 
     def base_path(val=nil)
       if val

data/lib/praxis/bootloader.rb

@@ -93,15 +93,21 @@ module Praxis
       instance.options.merge!(options)
       instance.block = block if block_given?
 
-      if application.plugins.key?(instance.config_key)
-        raise "Can not use plugin: #{plugin}, another plugin is already registered with key: #{instance.config_key}"
+      config_key = if instance.config_key.nil?
+        raise "Cannot use plugin: #{plugin}. It does not have a config_key defined, and its class does not have a name" unless instance.class.name
+        # Default the config key based on the full class name transformed to snake case (and joining modules with '_')
+        instance.class.name.to_s.split('::').collect{|n| n.underscore }.join('_').to_sym
+      else
+        instance.config_key
       end
 
-      if instance.config_key.nil?
-        raise "Error initializing plugin: #{plugin}, config_key may not be nil."
+      if application.plugins.key?(instance.config_key)
+        used_in = application.plugins[config_key].class
+        raise "Can not use plugin: #{plugin}, another plugin (#{used_in}) is already registered with key: #{instance.config_key}"
       end
 
-      application.plugins[instance.config_key] = instance
+      application.plugins[config_key] = instance
+
       instance
     end
 

data/lib/praxis/docs/generator.rb

@@ -79,12 +79,15 @@ module Praxis
       end
 
 
-      # Recursively inspect the structure in data and collect any
-      # newly discovered types into the `reachable_types` in/out parameter
-      def collect_reachable_types( data, reachable_types )
+      # Data: hash/array structure of dumped resources and/or types
+      # processed_types: list of type classes that have already gone through a describe+collect (this or previous rounds)
+      # ... any processed type won't need to be described+reached any longer
+      # newly_found: list of type classes that have been seen in the search (and that weren't already in the processed type)
+      def scan_dump_for_types( data, processed_types )
+        newfound_types = Set.new
         case data
         when Array
-          data.collect{|item| collect_reachable_types( item , reachable_types) }
+          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]
@@ -93,12 +96,12 @@ module Praxis
                 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
-              reachable_types << types_by_id[type_id]
+              newfound_types << types_by_id[type_id] unless processed_types.include? types_by_id[type_id]
             end
           end
-          data.values.map{|item| collect_reachable_types( item , reachable_types)}
+          data.values.map{|item| newfound_types += scan_dump_for_types( item , processed_types)}
         end
-        reachable_types
+        newfound_types
       end
 
       def write_index_file( for_versions:  )
@@ -124,13 +127,30 @@ module Praxis
         dumped_resources = dump_resources( resources_by_version[version] )
         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 )
+        # 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|
-          collect_reachable_types( { type: mt} , collected_types )
+          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
 
-        dumped_schemas = dump_schemas( collected_types )
+        dumped_schemas = dump_schemas( processed_types )
         full_data = {
           info: version_info[:info],
           resources: dumped_resources,

data/lib/praxis/docs/link_builder.rb

@@ -0,0 +1,30 @@
+module Praxis
+  module Docs
+    # Generates links into the generated doc browser.
+    class LinkBuilder
+      include Singleton
+
+      # Generates a link based on a request gone wrong.
+      # @return [String, nil] The doc browser link.
+      def for_request(req)
+        build_link req.version, 'controller', req.action.resource_definition.id, req.action.name
+      end
+
+      private
+
+      def build_link(*segments)
+        if endpoint
+          endpoint + '#' + segments.join('/')
+        end
+      end
+
+      def endpoint
+        @endpoint ||= begin
+          endpoint = ApiDefinition.instance.global_info.documentation_url
+          endpoint.gsub(/\/index\.html$/i, '/') if endpoint
+        end
+      end
+    end
+
+  end
+end

data/lib/praxis/extensions/field_expansion.rb

@@ -17,8 +17,8 @@ module Praxis
         extend ActiveSupport::Concern
 
         def expanded_fields(request, media_type)
-          use_fields = self.params.attributes.key?(:fields)
-          use_view = self.params.attributes.key?(:view)
+          use_fields = self.params && self.params.attributes.key?(:fields)
+          use_view = self.params && self.params.attributes.key?(:view)
 
           # Determine what, if any, fields to display.
           fields = if use_fields

data/lib/praxis/media_type.rb

@@ -126,7 +126,7 @@ module Praxis
         end
 
         # now to tackle whatever links there may be
-        if (links_fields = fields[:links])
+        if defined?(type::Links) &&(links_fields = fields[:links])
           resolved_links = resolve_links(type::Links, links_fields)
           self.deep_merge(result, resolved_links)
         end

data/lib/praxis/middleware_app.rb

@@ -0,0 +1,30 @@
+module Praxis
+  class MiddlewareApp
+
+    attr_reader :target
+
+    # Initialize the application instance with the desired args, and return the wrapping class.
+    def self.for( **args )
+      Praxis::Application.instance.setup(**args)
+      self
+     end
+
+    def initialize( inner )
+      @target = inner
+    end
+
+    def call(env)
+      result = Praxis::Application.instance.call(env)
+
+      unless ( [404,405].include?(result[0].to_i) && result[1]['X-Cascade'] == 'pass' )
+        # Respect X-Cascade header if it doesn't specify 'pass'
+        result
+      else
+        last_body = result[2]
+        last_body.close if last_body.respond_to? :close
+        target.call(env)
+      end
+    end
+
+  end
+end

data/lib/praxis/resource_definition.rb

@@ -11,7 +11,8 @@ module Praxis
       @version = 'n/a'.freeze
       @actions = Hash.new
       @responses = Hash.new
-      @action_defaults = Trait.new
+
+      @action_defaults = Trait.new &ResourceDefinition.generate_defaults_block
 
       @version_options = {}
       @metadata = {}
@@ -35,9 +36,28 @@ module Praxis
       Application.instance.resource_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.resource_definitions.each do |resource_definition|
-
         while (block = resource_definition.on_finalize.shift)
           block.call
         end
@@ -178,6 +198,8 @@ module Praxis
             @version_prefix = "#{Praxis::Request::path_version_prefix}#{self.version}"
           end
         end
+
+        @action_defaults.instance_eval &ResourceDefinition.generate_defaults_block( version: version )
       end
 
 

data/lib/praxis/response.rb

@@ -18,11 +18,12 @@ module Praxis
       klass.status = self.status if self.status
     end
 
-    def initialize(status:self.class.status, headers:{}, body:'')
+    def initialize(status:self.class.status, headers:{}, body:'', location: nil)
       @name    = response_name
       @status  = status
       @headers = headers
       @body    = body
+      @headers['Location'] = location if location
       @form_data = nil
       @parts = Hash.new
     end

data/lib/praxis/response_definition.rb

@@ -147,14 +147,14 @@ module Praxis
             default_handlers.include?(k)
           end
 
-          if (handler = handlers[identifier.handler_name])
+          if (identifier && handler = handlers[identifier.handler_name])
             payload[:examples][identifier.handler_name] = {
               content_type: identifier.to_s,
               body: handler.generate(rendered_payload)
             }
           else
             handlers.each do |name, handler|
-              content_type = identifier + name
+              content_type = ( identifier ) ? identifier + name : 'application/' + name
               payload[:examples][name] = {
                 content_type: content_type.to_s,
                 body: handler.generate(rendered_payload)

data/lib/praxis/responses/http.rb

@@ -18,11 +18,6 @@ module Praxis
     # being created.
     class Created < Praxis::Response
       self.status = 201
-
-      def initialize(status:self.class.status, headers:{}, body:'', location: nil)
-        super(status: status, headers: headers, body: body)
-        headers['Location'] = location if location
-      end
     end
 
 
@@ -138,94 +133,35 @@ module Praxis
 
     ApiDefinition.define do |api|
 
-      api.response_template :accepted do
-        status 202
-        description "The request has been accepted for processing, but the processing has not been completed."
-      end
-
-      api.response_template :no_content do
-        status 204
-        description "The server successfully processed the request, but is not returning any content."
-      end
-
-      api.response_template :multiple_choices do
-        status 300
-        description "Indicates multiple options for the resource that the client may follow."
-      end
-
-      api.response_template :moved_permanently do
-        status 301
-        description "This and all future requests should be directed to the given URI."
-      end
-
-      api.response_template :found do
-        status 302
-        description "The requested resource resides temporarily under a different URI."
-      end
-
-      api.response_template :see_other do
-        status 303
-        description "The response to the request can be found under another URI using a GET method"
-      end
-
-      api.response_template :not_modified do
-        status 304
-        description "Indicates that the resource has not been modified since the version specified by the request headers If-Modified-Since or If-Match."
-      end
-
-      api.response_template :temporary_redirect do
-        status 307
-        description "In this case, the request should be repeated with another URI; however, future requests should still use the original URI."
-      end
-
-      api.response_template :bad_request do
-        status 400
-        description "The request cannot be fulfilled due to bad syntax."
-      end
-
-      api.response_template :unauthorized do
-        status 401
-        description "Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided."
-      end
-
-      api.response_template :forbidden do
-        status 403
-        description "The request was a valid request, but the server is refusing to respond to it."
-      end
-
-      api.response_template :not_found do
-        status 404
-        description "The requested resource could not be found but may be available again in the future."
-      end
-
-      api.response_template :method_not_allowed do
-        status 405
-        description "A request was made of a resource using a request method not supported by that resource."
-      end
-
-      api.response_template :not_acceptable do
-        status 406
-        description "The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request."
-      end
-
-      api.response_template :request_timeout do
-        status 408
-        description "The server timed out waiting for the request."
-      end
-
-      api.response_template :conflict do
-        status 409
-        description "Indicates that the request could not be processed because of conflict in the request, such as an edit conflict in the case of multiple updates."
-      end
-
-      api.response_template :precondition_failed do
-        status 412
-        description "The server does not meet one of the preconditions that the requester put on the request."
-      end
 
-      api.response_template :unprocessable_entity do
-        status 422
-        description "The request was well-formed but was unable to be followed due to semantic errors."
+      [
+        [ :accepted, 202, "The request has been accepted for processing, but the processing has not been completed." ],
+        [ :no_content, 204,"The server successfully processed the request, but is not returning any content."],
+        [ :multiple_choices, 300,"Indicates multiple options for the resource that the client may follow."],
+        [ :moved_permanently, 301,"This and all future requests should be directed to the given URI."],
+        [ :found, 302,"The requested resource resides temporarily under a different URI."],
+        [ :see_other, 303,"The response to the request can be found under another URI using a GET method"],
+        [ :not_modified, 304,"Indicates that the resource has not been modified since the version specified by the request headers If-Modified-Since or If-Match."],
+        [ :temporary_redirect, 307,"In this case, the request should be repeated with another URI; however, future requests should still use the original URI."],
+        [ :bad_request, 400,"The request cannot be fulfilled due to bad syntax."],
+        [ :unauthorized, 401,"Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided."],
+        [ :forbidden, 403,"The request was a valid request, but the server is refusing to respond to it."],
+        [ :not_found, 404,"The requested resource could not be found but may be available again in the future."],
+        [ :method_not_allowed, 405,"A request was made of a resource using a request method not supported by that resource."],
+        [ :not_acceptable, 406,"The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request."],
+        [ :request_timeout, 408,"The server timed out waiting for the request."],
+        [ :conflict, 409, "Indicates that the request could not be processed because of conflict in the request, such as an edit conflict in the case of multiple updates."],
+        [ :precondition_failed, 412,"The server does not meet one of the preconditions that the requester put on the request."],
+        [ :unprocessable_entity, 422,"The request was well-formed but was unable to be followed due to semantic errors."],
+      ].each do |name, code, base_description|
+        api.response_template name do |media_type: nil, location: nil, headers: nil, description: nil|
+          status code
+          description( description || base_description ) # description can "potentially" be overriden in an individual action.
+
+          media_type media_type if media_type
+          location location if location
+          headers headers if headers
+        end
       end
 
     end

data/lib/praxis/responses/validation_error.rb

@@ -3,7 +3,7 @@ module Praxis
   module Responses
 
     class ValidationError < BadRequest
-      def initialize(summary:, errors: nil, exception: nil, **opts)
+      def initialize(summary:, errors: nil, exception: nil, documentation: nil, **opts)
         super(**opts)
         @headers['Content-Type'] = 'application/json' #TODO: might want an error mediatype
         @errors = errors
@@ -12,6 +12,7 @@ module Praxis
          end
         @exception = exception
         @summary = summary
+        @documentation = documentation
       end
 
       def format!
@@ -22,6 +23,8 @@ module Praxis
           @body[:cause] = {name: @exception.cause.class.name, message: @exception.cause.message}
         end
 
+        @body[:documentation] = @documentation if @documentation
+
         @body
       end
     end

data/lib/praxis/tasks/api_docs.rb

@@ -1,6 +1,13 @@
 namespace :praxis do
 
   namespace :docs do
+
+    def base_path
+      require 'uri'
+      documentation_url = Praxis::ApiDefinition.instance.global_info.documentation_url
+      URI(documentation_url).path.gsub(/\/[^\/]*$/, '/') if documentation_url
+    end
+
     path = File.expand_path(File.join(File.dirname(__FILE__), '../../api_browser'))
 
     desc "Install dependencies"
@@ -32,7 +39,8 @@ namespace :praxis do
       exec({
         'USER_DOCS_PATH' => File.join(Dir.pwd, 'docs'),
         'DOC_PORT' => doc_port,
-        'PLUGIN_PATHS' => Praxis::Application.instance.doc_browser_plugin_paths.join(':')
+        'PLUGIN_PATHS' => Praxis::Application.instance.doc_browser_plugin_paths.join(':'),
+        'BASE_PATH' => '/'
       }, "#{path}/node_modules/.bin/grunt serve --gruntfile '#{path}/Gruntfile.js'")
     end
 
@@ -40,19 +48,11 @@ namespace :praxis do
     task :build => [:install, :generate] do
       exec({
         'USER_DOCS_PATH' => File.join(Dir.pwd, 'docs'),
-        'PLUGIN_PATHS' => Praxis::Application.instance.doc_browser_plugin_paths.join(':')
+        'PLUGIN_PATHS' => Praxis::Application.instance.doc_browser_plugin_paths.join(':'),
+        'BASE_PATH' => base_path
       }, "#{path}/node_modules/.bin/grunt build --gruntfile '#{path}/Gruntfile.js'")
     end
 
-    desc "Generate deprecated API docs (JSON definitions) for a Praxis App"
-    task :generate_old => [:environment] do |t, args|
-      require 'fileutils'
-      STDERR.puts "DEPRECATION: praxis:docs:generate_old is deprecated and will be removed in the next version. Please update tooling that may need this."
-
-      Praxis::Blueprint.caching_enabled = false
-      generator = Praxis::RestfulDocGenerator.new(Dir.pwd)
-    end
-
     desc "Generate API docs (JSON definitions) for a Praxis App"
     task :generate => [:environment] do |t, args|
       require 'fileutils'
@@ -63,17 +63,4 @@ namespace :praxis do
     end
 
   end
-
-  desc "Generate API docs (JSON definitions) for a Praxis App"
-  task :api_docs do
-    STDERR.puts "DEPRECATION: praxis:api_docs is deprecated and will be removed by 1.0. Please use praxis:docs:generate instead."
-    Rake::Task["praxis:docs:generate_old"].invoke
-  end
-
-  desc "Run API Documentation Browser"
-  task :doc_browser, [:port] do |t, args|
-    STDERR.puts "DEPRECATION: praxis:doc_browser is deprecated and will be removed by 1.0. Please use praxis:docs:preview instead. The doc browser now runs on port 9090."
-    Rake::Task["praxis:docs:preview"].invoke
-  end
-
 end