praxis 0.11.2 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: faa4c7b780be253c8aa05ac8f9969d2d9754efbf
-  data.tar.gz: 4b71e46c0337fc3c6346ca6d1da68512155d0712
+  metadata.gz: 4684312c88071162f3525b9ee7c88c9f9a7587d2
+  data.tar.gz: fcf53c832ebc5f430dc37b9944ccc334b7ec3678
 SHA512:
-  metadata.gz: 3914c19d0fdbc50d4aaa949dc0dfc4df0c8a602abd9313cc9c1bf12a17d73e667a024e2299b83d0f6b19697d808de5ab721d5089b36a658200979be680e78c6b
-  data.tar.gz: f692e9d7e62f5fe2ed80899f1b0c63ecbf0b01ec987a95bf157f78b4a373583a07720063c04a3bfea486cafae89340e3686f3b2f95ca4c91a5e2976461a62230
+  metadata.gz: a600f9e9857b338f87c3dbec975e016a7f3bee940b0a9c590cfc241e7b05e81825877a92a6b49049089ef76ecabcf127ef978d3d545d828b8d7ce197a0b792d8
+  data.tar.gz: 115db171ee75c4569beab2277e4c917bcd768e444e264b769862373936365a54cff1eaa154c21cf7543b59816756e45aafddbc0dd0c95714afdc392f95cae006

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # praxis changelog
 
+## next
+
+## 0.13.0
+
+* Added `nodoc!` method to `ActionDefinition`, `ResourceDefinition` to hide actions and resources from the generated documentation.
+* Default HTTP responses:
+  * Added descriptions
+  * Added 408 RequestTimeout response
+* Replaced Ruport dependency in `praxis:routes` rake task with TerminalTable.
+* Fixed doc browser issue when attributes defaulting to false wouldn't display the default section.
+* Enhanced several logging aspects of the PraxisMapper plugin:
+  * The log-level of the stats is now configurable in the plugin (see the comments [here](https://github.com/rightscale/praxis/blob/master/lib/praxis/plugins/praxis_mapper_plugin.rb) for details)
+  * Added a "silence_mapper_stats" attribute in the Request objects so, actions and/or controllers can selectively skip logging stats (for example, health check controllers, etc)
+  * It now logs a compact message (with the same heading) when the identity map has had no interactions.
+* Added X-Cascade header support
+  * Configured with boolean `praxis.x_cascade` that defaults to true.
+  * When enabled, Praxis will add an 'X-Cascade: pass' header to the response when the request was not routable to an action. It is not added if the action explicitly returns a `NotFound` response.
+* Fixed bug in request handling where `after` callbacks were being executed, even if the stage returned a response.
+* Added a handy option to tie an action route to match any HTTP verb.
+  * Simply use `any` as the verb when you define it (i.e. any '/things/:id' )
+* Allow a MediaType to define a custom `links` attribute like any other.
+  * This is not compatible if it also wants to use the `links` DSL.
+
+
 ## 0.11.2
 
 * The Doc Browser will now not change the menu when refreshing.

data/lib/api_browser/app/js/controllers/action.js

@@ -18,8 +18,8 @@ app.controller("ActionCtrl", function($scope, $stateParams, Documentation) {
           var example = set.example ? JSON.stringify(set.example[name], null, 2) : '';
           if (!attribute.options) attribute.options = {};
           if (example) attribute.options.example = example;
-          if (attribute.values) attribute.options.values = attribute.values;
-          if (attribute.default) attribute.options.default = attribute.default;
+          if (attribute.values != null) attribute.options.values = attribute.values;
+          if (attribute.default != null) attribute.options.default = attribute.default;
         });
       }
     });

data/lib/api_browser/app/js/controllers/type.js

@@ -15,8 +15,8 @@
       var example = JSON.stringify($scope.type.example[name], null, 2);
       if (!attribute.options) attribute.options = {};
       if (example) attribute.options.example = example;
-      if (attribute.values) attribute.options.values = attribute.values;
-      if (attribute.default) attribute.options.default = attribute.default;
+      if (attribute.values != null) attribute.options.values = attribute.values;
+      if (attribute.default != null) attribute.options.default = attribute.default;
     });
 
     Documentation.getIndex().success(function(response) {

data/lib/praxis/action_definition.rb

@@ -16,6 +16,10 @@ module Praxis
     attr_reader :named_routes
     attr_reader :responses
 
+    # opaque hash of user-defined medata, used to decorate the definition,
+    # and also available in the generated JSON documents
+    attr_reader :metadata
+
     class << self
       attr_accessor :doc_decorations      
     end
@@ -30,6 +34,7 @@ module Praxis
       @name = name
       @resource_definition = resource_definition
       @responses = Hash.new
+      @metadata = Hash.new
 
       if (media_type = resource_definition.media_type)
         if media_type.kind_of?(Class) && media_type < Praxis::MediaType
@@ -147,6 +152,7 @@ module Praxis
       {}.tap do |hash|
         hash[:description] = description
         hash[:name] = name
+        hash[:metadata] = metadata
         # FIXME: change to :routes along with api browser
         hash[:urls] = routes.collect(&:describe)
         hash[:headers] = headers.describe if headers
@@ -162,5 +168,10 @@ module Praxis
       end
     end
 
+    def nodoc!
+      metadata[:doc_visibility] = :none
+    end
+
+
   end
 end

data/lib/praxis/api_definition.rb

@@ -46,11 +46,13 @@ module Praxis
       api.response_template :ok do |media_type: |
         media_type media_type
         status 200
+        description 'Standard response for successful HTTP requests.'
       end
 
       api.response_template :created do |location: nil|
         location location
         status 201
+        description 'The request has been fulfilled and resulted in a new resource being created.'
       end
     end
 

data/lib/praxis/bootloader_stages/environment.rb

@@ -43,6 +43,7 @@ module Praxis
           attribute :praxis do
             attribute :validate_responses, Attributor::Boolean, default: false
             attribute :show_exceptions, Attributor::Boolean, default: false
+            attribute :x_cascade, Attributor::Boolean, default: true
           end
         end
       end

data/lib/praxis/controller.rb

@@ -4,6 +4,7 @@ require 'active_support/all'
 module Praxis
   module Controller
     extend ::ActiveSupport::Concern
+    
     # A Controller always requires the callbacks
     include Praxis::Callbacks
     
@@ -11,6 +12,7 @@ module Praxis
       attr_reader :request
       attr_accessor :response
     end
+
     module ClassMethods
       def implements(definition)
         define_singleton_method(:definition) do
@@ -27,16 +29,5 @@ module Praxis
       @response = response
     end
 
-#    def request
-#      @request
-#    end
-#
-#    def response
-#      @response
-#    end
-#
-#    def response=(value)
-#      @response = value
-#    end
   end
 end

data/lib/praxis/media_type.rb

@@ -30,11 +30,20 @@ module Praxis
       super(opts.merge(dsl_compiler: MediaType::DSLCompiler), &block)
     end
 
-    def links
-      self.class::Links.new(@object)
+    def self._finalize!
+      super
+      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)
+          end
+        RUBY
+      end
     end
 
-
   end
 
 end

data/lib/praxis/media_type_collection.rb

@@ -61,13 +61,11 @@ module Praxis
       members = []
       size = rand(3) + 1
 
-
       size.times do |i|
         subcontext = context + ["at(#{i})"]
         members << @member_attribute.example(subcontext)
       end
 
-
       result.object._members = members
       result
     end

data/lib/praxis/plugins/praxis_mapper_plugin.rb

@@ -36,6 +36,7 @@ require 'terminal-table'
 #      output into the Praxis::Application.instance.logger app log. Possible
 #      values are: "detailed", "short", and "skip" (i.e. do not print the stats
 #      at all).
+#   3. stats_log_level: the logging level with which the statistics should be logged. 
 #
 # See http://praxis-framework.io/reference/plugins/ for further details on how
 # to use a plugin and pass it options.
@@ -75,6 +76,7 @@ module Praxis
         def prepare_config!(node)
           node.attributes do
             attribute :log_stats, String, values: ['detailed', 'short', 'skip'], default: 'detailed'
+            attribute :stats_log_level, Symbol, values: [:fatal,:error,:warn,:info,:debug], default: :info            
             attribute :repositories, Attributor::Hash.of(key: String, value: RepositoryConfig)
           end
         end
@@ -103,7 +105,7 @@ module Praxis
           unless log_stats == 'skip'
             Praxis::Notifications.subscribe 'praxis.request.all' do |name, *junk, payload|
               if (identity_map = payload[:request].identity_map)
-                PraxisMapperPlugin::Statistics.log(identity_map, log_stats)
+                PraxisMapperPlugin::Statistics.log(payload[:request], identity_map, log_stats)
               end
             end
           end
@@ -126,6 +128,15 @@ module Praxis
         def identity_map=(map)
           @identity_map = map
         end
+        
+        def silence_mapper_stats
+          @silence_mapper_stats
+        end
+
+        def silence_mapper_stats=(value)
+          @silence_mapper_stats = value
+        end
+
       end
 
       module Controller
@@ -133,15 +144,22 @@ module Praxis
 
         included do
           before :action do |controller|
-            controller.request.identity_map = Praxis::Mapper::IdentityMap.setup!
+            controller.request.identity_map = Praxis::Mapper::IdentityMap.new
           end
         end
       end
 
       module Statistics
 
-        def self.log(identity_map, log_stats)
+        def self.log(request, identity_map, log_stats)
           return if identity_map.nil?
+          return if request.silence_mapper_stats == true
+          if identity_map.queries.empty?
+            self.to_logger "No database interactions observed."
+            return
+          end
+          
+          
           case log_stats
           when 'detailed'
             self.detailed(identity_map)
@@ -187,7 +205,7 @@ module Praxis
           table.align_column(3, :right)
           table.align_column(4, :right)
           table.align_column(5, :right)
-          Praxis::Application.instance.logger.info "Praxis::Mapper Statistics:\n#{table.to_s}"
+          self.to_logger "\n#{table.to_s}"
         end
 
         def self.round_fields_at(values, indices)
@@ -197,7 +215,11 @@ module Praxis
         end
 
         def self.short(identity_map)
-          Praxis::Application.instance.logger.info "Praxis::Mapper Statistics: #{identity_map.query_statistics.sum_totals.to_s}"
+          self.to_logger identity_map.query_statistics.sum_totals.to_s
+        end
+        
+        def self.to_logger(message)
+            Praxis::Application.instance.logger.__send__(Plugin.instance.config.stats_log_level, "Praxis::Mapper Statistics: #{message}")
         end
       end
     end

data/lib/praxis/request_stages/request_stage.rb

@@ -15,68 +15,89 @@ module Praxis
       end
 
       def execute_controller_callbacks(callbacks)
-        if callbacks.has_key?(path)
+        if callbacks.key?(path)
           callbacks[path].each do |(conditions, block)|
-            if conditions.has_key?(:actions)
+            if conditions.key?(:actions)
               next unless conditions[:actions].include? action.name
             end
             result = block.call(controller)
-            return result if result && result.kind_of?(Praxis::Response)
+            if result && result.kind_of?(Praxis::Response)
+              controller.response = result
+              return result
+            end
           end
         end
+
         nil
       end
-      
+
       def run
         setup!
         setup_deferred_callbacks!
-        
+
+        # stage-level callbacks (typically empty) will never shortcut
         execute_callbacks(self.before_callbacks)
-        # Shortcut lifecycle if filters return a response (non-nil but non-response-class response is ignored)
+
         r = execute_controller_callbacks(controller.class.before_callbacks)
+        # Shortcut lifecycle if filters return non-nil value
+        # (which should only be a Response)
         return r if r
 
         result = execute_with_around
-        # Still allow the after callbacks to shortcut it if necessary.
+        # Shortcut lifecycle if filters return a response
+        # (non-nil but non-response-class response is ignored)
+        if result && result.kind_of?(Praxis::Response)
+          controller.response = result
+          return result
+        end
+
         r = execute_controller_callbacks(controller.class.after_callbacks)
-        return r if r 
-        execute_callbacks(self.after_callbacks) 
+        # Shortcut lifecycle if filters return non-nil value
+        # (which should only be a Response)
+        return r if r
+
+        # stage-level callbacks (typically empty) will never shortcut
+        execute_callbacks(self.after_callbacks)
 
         result
       end
 
       def execute_with_around
-          cb = controller.class.around_callbacks[ path ]
-          if cb == nil || cb.empty?
-            execute
-          else
-            inner_proc = proc { execute }
-            
-            applicable = cb.select do |(conditions, handler)| 
-              if conditions.has_key?(:actions)
-                (conditions[:actions].include? action.name) ? true : false
-              else
-                true
-              end
+        cb = controller.class.around_callbacks[ path ]
+        if cb == nil || cb.empty?
+          execute
+        else
+          inner_proc = proc { execute }
+
+          applicable = cb.select do |(conditions, handler)|
+            if conditions.has_key?(:actions)
+              (conditions[:actions].include? action.name) ? true : false
+            else
+              true
+            end
+          end
+
+          chain = applicable.reverse.inject(inner_proc) do |blk, (conditions, handler)|
+            if blk
+              proc{ handler.call(controller,blk) }
+            else
+              proc{ handler.call }
             end
-            
-            chain = applicable.reverse.inject(inner_proc) do |blk, (conditions, handler)|
-              if blk
-                proc{ handler.call(controller,blk) }
-              else
-                proc{ handler.call }
-              end
-            end  
-            chain.call
           end
+          chain.call
+        end
       end
-      
+
+
       def execute
         raise NotImplementedError, 'Subclass must implement Stage#execute' unless @stages.any?
 
         @stages.each do |stage|
           shortcut = stage.run
-          return shortcut if shortcut && shortcut.kind_of?(Praxis::Response)
+          if shortcut && shortcut.kind_of?(Praxis::Response)
+            controller.response = shortcut
+            return shortcut 
+          end
         end
         nil
       end

data/lib/praxis/request_stages/response.rb

@@ -2,12 +2,11 @@ module Praxis
   module RequestStages
 
     class Response < RequestStage
-      WHITELIST_RESPONSES = [:validation_error] 
+      WHITELIST_RESPONSES = [:validation_error]
 
       def execute
         response = controller.response
 
-
         unless action.responses.include?(response.response_name) || WHITELIST_RESPONSES.include?(response.response_name)
           raise Exceptions::InvalidResponse.new(
             "Response #{response.name.inspect} is not allowed for #{action.name.inspect}"
@@ -21,7 +20,7 @@ module Praxis
         end
       rescue Exceptions::Validation => e
         controller.response = Responses::ValidationError.new(exception: e)
-        retry 
+        retry
       end
 
     end

data/lib/praxis/resource_definition.rb

@@ -12,6 +12,7 @@ module Praxis
       @responses = Hash.new
       @action_defaults = []
       @version_options = {}
+      @metadata = {}
       Application.instance.resource_definitions << self
     end
 
@@ -20,7 +21,11 @@ module Praxis
       attr_reader :routing_config
       attr_reader :responses
       attr_reader :version_options
-      
+  
+      # 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
 
       # FIXME: this is inconsistent with the rest of the magic DSL convention.
@@ -94,6 +99,7 @@ module Praxis
           hash[:description] = description
           hash[:media_type] = media_type.name if media_type
           hash[:actions] = actions.values.map(&:describe)
+          hash[:metadata] = metadata
         end
       end
 
@@ -104,6 +110,10 @@ module Praxis
         self.instance_eval(&ApiDefinition.instance.traits[trait_name])
       end
 
+      def nodoc!
+        metadata[:doc_visibility] = :none
+      end
+
     end
 
   end

data/lib/praxis/responses/http.rb

@@ -2,34 +2,37 @@ module Praxis
 
   module Responses
 
-    # Standard response for successful HTTP requests. 
-    # The actual response will depend on the request method used. 
-    # In a GET request, the response will contain an entity 
-    # corresponding to the requested resource. 
-    # In a POST request the response will contain an entity 
+    # Descriptions from http://en.wikipedia.org/wiki/List_of_HTTP_status_codes
+
+    # Standard response for successful HTTP requests.
+    # The actual response will depend on the request method used.
+    # In a GET request, the response will contain an entity
+    # corresponding to the requested resource.
+    # In a POST request the response will contain an entity
     # describing or containing the result of the action.
     class Ok < Praxis::Response
       self.status = 200
     end
 
-
-    # The request has been fulfilled and resulted in a new resource 
+    # The request has been fulfilled and resulted in a new resource
     # being created.
     class Created < Praxis::Response
       self.status = 201
     end
 
 
-    # The request has been accepted for processing, but the 
-    # processing has not been completed. The request might or might 
-    # not eventually be acted upon, as it might be disallowed when 
+    # The request has been accepted for processing, but the
+    # processing has not been completed. The request might or might
+    # not eventually be acted upon, as it might be disallowed when
     # processing actually takes place.
     class Accepted < Praxis::Response
       self.status = 202
     end
 
 
-    # The server successfully processed the request, but is not returning any content. Usually used as a response to a successful delete request.
+    # The server successfully processed the request, but is not
+    # returning any content. Usually used as a response to
+    # a successful delete request.
     class NoContent < Praxis::Response
       self.status = 204
     end
@@ -101,11 +104,15 @@ module Praxis
     end
 
 
-    # A request was made of a resource using a request method not supported by that resource; for example, using GET on a form which requires data to be presented via POST, or using PUT on a read-only resource.
+    # The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request.
     class NotAcceptable < Praxis::Response
       self.status = 406
     end
 
+    # The server timed out waiting for the request.
+    class RequestTimeout < Praxis::Response
+      self.status = 408
+    end
 
     # 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.
     class Conflict < Praxis::Response
@@ -124,19 +131,100 @@ module Praxis
       self.status = 422
     end
 
-
     ApiDefinition.define do |api|
-      self.constants.each do |class_name|
-        response_class = self.const_get(class_name)
-        response_name = response_class.response_name
-        next if api.responses.key?(response_name)
 
-        api.response_template response_name do
-          status response_class.status
-        end
+      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."
       end
+
     end
 
+
   end
 end

data/lib/praxis/responses/internal_server_error.rb

@@ -36,7 +36,7 @@ module Praxis
 
   ApiDefinition.define do |api|
     api.response_template :internal_server_error do
-      description "When an internal server error occurs..."
+      description "A generic error message, given when an unexpected condition was encountered and no more specific message is suitable."
       status 500
       media_type "application/json"
     end

data/lib/praxis/responses/validation_error.rb

@@ -31,7 +31,7 @@ module Praxis
 
   ApiDefinition.define do |api|
     api.response_template :validation_error do
-      description "When parameter validation hits..."
+      description "An error message indicating that one or more elements of the request did not match the API specification for the action"
       status 400
       media_type "application/json"
     end