praxis 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 969f34805663e8986a5ac60e86216c3139324d98
-  data.tar.gz: 8fb76988854889627663ff66874ecb1a8f4549b0
+  metadata.gz: 0dbe3630ec0519b3fe1c0c4581155e1fd9858002
+  data.tar.gz: 1a93b0745b2413203e13a69a1a7c83e41f4c7ab8
 SHA512:
-  metadata.gz: 228bc86fd20fef3ad70b282519266378b6f90333e36438923b5a5ed8c416ccacf7d5ac4444bab3d675a2bdd210a3cb89a62090d3ce780d2a5c62cc9c848216d1
-  data.tar.gz: b355e2bd55fe51389ba695d8348303560208d960694f8832d74ebf59942b3e9088cf757c48ae37109b975d6dac238815f15528457c32655c2baa3c3c9b7cf290
+  metadata.gz: 8f0e8f6ff18f14cbfd2e0d18fbbcb7a05ef32c01914106dd29952c63b8d2dd70fbab8c254961ca48f9ae2597206f0548acd057b820adbc5656d74d98ca7073e7
+  data.tar.gz: 77d8c97b50f6f3853002289d59f8e17585269d5dad0d3b1d8089e00694dabd06fddfa67ed0179c918587ef6b1e624a4736b47a4b2b05478ca63ef6cde2135dda

data/CHANGELOG.md

@@ -2,7 +2,21 @@
 
 ## next
 
-## 0.14.0 
+## 0.15.0
+
+* Fixed handling of no app or design file groups defined in application layout.
+* Handled and added warning message for doc generation task when no routing block is defined for an action.  
+* Improved `link` method in `MediaType` attribute definition to support inheriting the type from the `:using` option if if that specifies an attribute. For example: `link :posts, using: :posts_summary` would use the type of the `:posts_summary` attribute.
+* Fixed generated `Links` accessors to properly load the returned value.
+* Added `MediaTypeIdentifier` class to parse and manipulate Content-Type headers and Praxis::MediaType identifiers.
+* Created a registry for media type handlers that parse and generate document bodies with formats other than JSON.
+  * Given a structured-data response, Praxis will convert it to JSON, XML or other formats based on the handler indicated by its Content-Type.
+  * Given a request, Praxis will use the handler indicated by its Content-Type header to parse the body into structured data.
+* Fixed bug allowing "praxis new" to work when Praxis is installed as a system (non-bundled) gem. 
+* Fixed doc generation code for custom types
+* Hardened Multipart type loading
+
+## 0.14.0
 
 * Adds features for customizing and exporting the Doc browser, namely the following changes:
   1. All doc browser stuff is now centralised under the `praxis:docs` namespace.

data/Gemfile

@@ -1,3 +1,8 @@
 source 'https://rubygems.org'
 
 gemspec
+
+group :test do
+  gem 'nokogiri'
+  gem 'builder'
+end

data/bin/praxis

@@ -2,9 +2,12 @@
 
 require 'bundler'
 
-Bundler.setup :default, :test
-Bundler.require :default, :test
-
+begin
+  Bundler.setup :default, :test
+  Bundler.require :default, :test
+rescue Bundler::GemfileNotFound
+  # no-op: we might be installed as a system gem
+end
 
 if ["routes","docs","console"].include? ARGV[0]
   require 'rake'
@@ -83,4 +86,4 @@ class PraxisGenerator < Thor
   
 end
     
-PraxisGenerator.start(ARGV)
+PraxisGenerator.start(ARGV)

data/lib/api_browser/package.json

@@ -23,7 +23,7 @@
     "grunt-file-blocks": "^0.3.0",
     "grunt-filerev": "^0.2.1",
     "grunt-ngmin": "0.0.3",
-    "grunt-sass": "^0.17.0",
+    "grunt-sass": "^0.18.0",
     "grunt-usemin": "^2.1.1",
     "grunt-wiredep": "^1.7.0",
     "load-grunt-tasks": "^0.4.0"

data/lib/praxis/action_definition.rb

@@ -173,10 +173,15 @@ module Praxis
     end
 
     def params_description
-      route_params = primary_route.path.
-        named_captures.
-        keys.
-        collect(&:to_sym)
+      route_params = []
+      if primary_route.nil?
+        warn "Warning: No routes defined for #{resource_definition.name}##{name}."
+      else
+        route_params = primary_route.path.
+          named_captures.
+          keys.
+          collect(&:to_sym)
+      end
 
       desc = params.describe
       desc[:type][:attributes].keys.each do |k|
@@ -185,7 +190,7 @@ module Praxis
         else
           'query'
         end
-        desc[:type][:attributes][k][:source] = source          
+        desc[:type][:attributes][k][:source] = source
       end
       desc
     end

data/lib/praxis/application.rb

@@ -17,6 +17,7 @@ module Praxis
     attr_accessor :loaded_files
     attr_accessor :logger
     attr_accessor :plugins
+    attr_accessor :handlers
     attr_accessor :root
     attr_accessor :error_handler
 
@@ -39,6 +40,7 @@ module Praxis
       @bootloader = Bootloader.new(self)
       @file_layout = nil
       @plugins = Hash.new
+      @handlers = Hash.new
       @loaded_files = Set.new
       @config = Config.new
       @root = nil
@@ -48,6 +50,15 @@ module Praxis
     def setup(root: '.')
       @root = Pathname.new(root).expand_path
 
+      builtin_handlers = {
+          'json'                  => Praxis::Handlers::JSON,
+          'x-www-form-urlencoded' => Praxis::Handlers::WWWForm
+      }
+      # Register built-in handlers unless the app already provided its own
+      builtin_handlers.each_pair do |name, handler|
+        self.handler(name, handler) unless handlers.key?(name)
+      end
+
       @bootloader.setup!
 
       @builder.run(@router)
@@ -68,6 +79,25 @@ module Praxis
       @builder.use(middleware, *args, &block)
     end
 
+    # Register a media type handler used to transform medias' structured data
+    # to HTTP response entitites with a specific encoding (JSON, XML, etc)
+    # and to parse request bodies into structured data.
+    #
+    # @param [String] name
+    # @param [Class] a class that responds to .new, #parse and #generate
+    def handler(name, handler)
+      # Construct an instance, if the handler is a class and needs to be initialized.
+      handler = handler.new
+
+      # Make sure it quacks like a handler.
+      unless handler.respond_to?(:generate) && handler.respond_to?(:parse)
+        raise ArgumentError, "Media type handlers must respond to #generate and #parse"
+      end
+
+      # Register that thing!
+      @handlers[name.to_s] = handler
+    end
+
     def call(env)
       response = []
       Notifications.instrument 'rack.request.all'.freeze, response: response do

data/lib/praxis/bootloader_stages/subgroup_loader.rb

@@ -9,11 +9,11 @@ module Praxis
       def initialize(name, application)
         super
         # always finalize Taylor after loading app code.
-      
+
       end
 
       def order
-        @order ||= application.file_layout[name].groups.keys
+        @order ||= application.file_layout[name] == [] ? [] : application.file_layout[name].groups.keys
       end
 
       def setup!

data/lib/praxis/bootloader_stages/warn_unloaded_files.rb

@@ -16,6 +16,11 @@ module Praxis
 
       def execute
         return unless self.class.enabled
+
+        if application.file_layout[:app] == []
+          return
+        end
+
         base = application.file_layout[:app].base
         return unless base.exist?
         file_enum = base.find.to_a
@@ -26,12 +31,12 @@ module Praxis
 
         missing = Set.new(files) - application.loaded_files
         if missing.any?
-          msg = "The following files application files under #{base} were not loaded:\n"
+          msg = "The following application files under #{base} were not loaded:\n"
           missing.each do |file|
             path = file.relative_path_from(base)
             msg << " * #{path}\n"
           end
-          puts msg
+          warn msg
         end
       end
 

data/lib/praxis/file_group.rb

@@ -7,7 +7,7 @@ module Praxis
     def initialize(base, &block)
       if base.nil?
         raise ArgumentError, "base must not be nil." \
-          "Are you missing a call Praxis::Application.instance.setup?" 
+          "Are you missing a call Praxis::Application.instance.setup?"
       end
 
 

data/lib/praxis/handlers/json.rb

@@ -0,0 +1,32 @@
+module Praxis
+  module Handlers
+    class JSON
+      # Construct a JSON handler and initialize any related libraries.
+      #
+      # @raise [Praxis::Exceptions::InvalidConfiguration] if the handler is unsupported
+      def initialize
+        require 'json'
+      rescue LoadError
+        # Should never happen since JSON is a default gem; might as well be cautious!
+        raise Praxis::Exceptions::InvalidConfiguration,
+              "JSON handler depends on json ~> 1.0; please add it to your Gemfile"
+      end
+
+      # Parse a JSON document into structured data.
+      #
+      # @param [String] document
+      # @return [Hash,Array] the structured-data representation of the document
+      def parse(document)
+        ::JSON.parse(document)
+      end
+
+      # Generate a pretty-printed JSON document from structured data.
+      #
+      # @param [Hash,Array] structured_data
+      # @return [String]
+      def generate(structured_data)
+        ::JSON.pretty_generate(structured_data)
+      end
+    end
+  end
+end

data/lib/praxis/handlers/www_form.rb

@@ -0,0 +1,20 @@
+module Praxis
+  module Handlers
+    class WWWForm
+      def initialize
+        require 'rack' # superfluous, but might as well be safe
+      end
+
+      # Parse a URL-encoded WWW form into structured data.
+      def parse(entity)
+        ::Rack::Utils.parse_nested_query(entity)
+      end
+
+      # Generate a URL-encoded WWW form from structured data. Not implemented since this format
+      # is not very useful for a response body.
+      def generate(structured_data)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/praxis/handlers/xml.rb

@@ -0,0 +1,78 @@
+module Praxis
+  module Handlers
+    class XML
+      # Construct an XML handler and initialize any related libraries.
+      #
+      # @raise [Praxis::Exceptions::InvalidConfiguration] if the handler is unsupported
+      def initialize
+        require 'nokogiri'
+        require 'builder'
+        require 'active_support'
+        ActiveSupport::XmlMini.backend = 'Nokogiri'
+      rescue LoadError
+        raise Praxis::Exceptions::InvalidConfiguration,
+              "XML handler depends on builder ~> 3.2 and nokogiri ~> 1.6; please add them to your Gemfile"
+      end
+
+      # Parse an XML document into structured data.
+      #
+      # @param [String] document
+      # @return [Hash,Array] the structured-data representation of the document
+      def parse(document)
+        p = Nokogiri::XML(document)
+        process(p.root, p.root.attributes['type'])
+      end
+
+      # Generate a pretty-printed XML document from structured data.
+      #
+      # @param [Hash,Array] structured_data
+      # @return [String]
+      def generate(structured_data)
+        # courtesy of active_support + builder
+        structured_data.to_xml
+      end
+
+      protected
+
+      # Transform a Nokogiri DOM object into structured data.
+      def process(node, type_attribute)
+        type = type_attribute.value if type_attribute
+
+        case type
+        when nil
+          if node.children.size == 1 && node.child.text?
+            # leaf text node
+            return node.content
+          else
+            # A hash
+            return node.children.each_with_object({}) do |child, hash|
+              next unless child.element? # There might be text fragments like newlines...spaces
+              hash[child.name] = process(child, child.attributes['type'])
+            end
+          end
+        when "array"
+          return node.children.each_with_object([]) do |child, arr|
+            next unless child.element? # There might be text fragments like newlines...spaces
+            arr << process(child, child.attributes['type'])
+          end
+        when "integer"
+          return Integer(node.content)
+        when "symbol"
+          return node.content.to_sym
+        when "decimal"
+          return BigDecimal.new(node.content)
+        when "float"
+          return Float(node.content)
+        when "boolean"
+          return ((node.content == "false") ? false : true)
+        when "date"
+          return Date.parse(node.content)
+        when "dateTime"
+          return DateTime.parse(node.content)
+        else
+          raise ArgumentError, "Unknown attribute type: #{type}"
+        end
+      end
+    end
+  end
+end

data/lib/praxis/links.rb

@@ -13,6 +13,9 @@ module Praxis
 
       def link(name, type=nil, using: name, **opts, &block)
         links[name] = using
+        if type.nil? && (name != using)
+          type = options[:reference].attributes[using].type
+        end
         attribute(name, type, **opts, &block)
       end
     end
@@ -69,7 +72,7 @@ module Praxis
       define_method(name) do
         value = @object.__send__(using)
         return value if value.nil? || value.kind_of?(attribute.type)
-        attribute.type.new(value)
+        attribute.load(value)
       end
 
       # do whatever crazy aliasing we need to here....

data/lib/praxis/media_type.rb

@@ -1,4 +1,59 @@
 module Praxis
+  # An Internet Media Type as defined in RFC 1590, as used in HTTP (see RFC 2616). As used in the
+  # Praxis framework, media types also define the structure and content of entities of that type:
+  # the attributes that exist, their names and types.
+  #
+  # An object with a media type can be represented on the wire using different structured-syntax
+  # encodings; for example, a controller might respond with an actual Widget object, but a
+  # Content-Type header specifying 'application/vnd.acme.widget+json'; Praxis uses the information
+  # contained in the media-type definition of Widget to transform the object into an equivalent
+  # JSON representation. If the content type ends with '+xml' instead, and the XML handler is
+  # registered with the framework, Praxis will respond with an XML representation of the
+  # widget. The use of media types allows your application's models to be decoupled from its
+  # HTTP interface specification.
+  #
+  # A media type definition consists of:
+  #   - a MIME type identifier
+  #   - attributes, each of which has a name and a data type
+  #   - named links to other resources
+  #   - named views, which expose interesting subsets of attributes
+  #
+  # @example Declare a widget type that's used by my supply-chain management app
+  #   class MyApp::MediaTypes::Widget < Praxis::MediaType
+  #     description 'Represents a widget'
+  #     identifier 'application/vnd.acme.widget'
+  #
+  #     attributes do
+  #       attribute :id, Integer
+  #         description: 'Database ID'
+  #       attribute :href, Attributor::Href,
+  #         description: 'Canonical resource refernece'
+  #       attribute :color, String,
+  #         example: 'red'
+  #       attribute :material, String,
+  #         description: 'Construction medium of the widget',
+  #         values: ['copper', 'steel', 'aluminum']
+  #       attribute :factory, MyApp::MediaTypes::Factory,
+  #         description: 'The factory in which this widget was produced'
+  #     end
+  #
+  #     links do
+  #       link :factory,
+  #         description: 'Link to the factory in which this widget was produced'
+  #     end
+  #
+  #     # If widgets can be linked-to by other resources, they should have a link view
+  #     view :link do
+  #       attribute :href
+  #     end
+  #
+  #     # All resources should have a default view
+  #     view :default do
+  #       attribute :id
+  #       attribute :color
+  #       attribute :material
+  #     end
+  #   end
   class MediaType < Praxis::Blueprint
     include Types::MediaTypeCommon
 

data/lib/praxis/media_type_identifier.rb

@@ -0,0 +1,198 @@
+require 'set'
+
+module Praxis
+  # Ruby object representation of an Internet Media Type Identifier as defined by
+  # RFC6838; also known as MIME types due to their origin in RFC2046 (the
+  # MIME specification).
+  class MediaTypeIdentifier < Attributor::Model
+    # Postel's principle encourages us to accept anything that MIGHT be an identifier, although
+    # the syntax for type identifiers is substantially narrower than what we accept there.
+    #
+    # Note that this ONLY matches type, subtype and suffix; we handle options differently.
+    VALID_TYPE = /^\s*(?<type>[^\/]+)\/(?<subtype>[^\+]+)(\+(?<suffix>[^; ]+))?\s*$/x.freeze
+
+    # Pattern that separates parameters of a media type from each other, and from the base identifier.
+    PARAMETER_SEPARATOR = /\s*;\s*/x.freeze
+
+    # Pattern used to identify the first "word" when we encounter a malformed type identifier, so
+    # we can apply a heuristic and assume the user meant "application/XYZ".
+    WORD_SEPARATOR = /[^a-z0-9-]/i.freeze
+
+    # Pattern that lets us strip quotes from parameter values.
+    QUOTED_STRING = /^".*"$/.freeze
+
+    # Token that indicates a media-type component that matches anything.
+    WILDCARD = '*'.freeze
+
+    # Inner type representing semicolon-delimited parameters.
+    Parameters = Attributor::Hash.of(key: String)
+
+    attributes do
+      attribute :type, Attributor::String, default: 'application', description: 'RFC2046 media type'
+      attribute :subtype, Attributor::String, default: '*', description: 'RFC2046 media subtype', example: 'vnd.widget'
+      attribute :suffix, Attributor::String, default: '', description: 'RFC6838 structured-syntax suffix', example: 'json'
+      attribute :parameters, Parameters, default: {}, description: "Type-specific parameters", example: "{'type' => 'collection'}"
+    end
+
+    # Parse a media type identifier from a String, or load it from a Hash or Model. Assume malformed
+    # types represent a subtype, e.g. "nachos" => application/nachos"
+    #
+    # @param [String,Hash,Attributor::Model] value
+    # @return [MediaTypeIdentifier]
+    # @see Attributor::Model#load
+    def self.load(value, context=Attributor::DEFAULT_ROOT_CONTEXT, recurse: false, **options)
+      if value.is_a?(String)
+        base, *parameters = value.split(PARAMETER_SEPARATOR)
+        match = VALID_TYPE.match(base)
+
+        obj = new
+        if match
+          parameters = parameters.each_with_object({}) do |e, h|
+            k, v = e.split('=', 2)
+            v = v[1...-1] if v =~ QUOTED_STRING
+            h[k] = v
+          end
+
+          obj.type, obj.subtype, obj.suffix, obj.parameters =
+              match[:type], match[:subtype], match[:suffix], parameters
+        else
+          obj.type = 'application'
+          obj.subtype = base.split(WORD_SEPARATOR, 2).first
+          obj.suffix = ''
+          obj.parameters = {}
+        end
+        obj
+      else
+        super
+      end
+    end
+
+    # Determine whether another identifier is compatible with (i.e. is a subset or specialization of)
+    # this identifier.
+    #
+    # @return [Boolean] true if this type is compatible with other, false otherwise
+    #
+    # @param [MediaTypeIdentifier,String] other
+    #
+    # @example match anything
+    #      MediaTypeIdentifier.load('*/*').match('application/icecream+cone; flavor=vanilla') # => true
+    #
+    # @example match a subtype wildcard
+    #      MediaTypeIdentifier.load('image/*').match('image/jpeg') # => true
+    #
+    # @example match a specific type irrespective of structured syntax
+    #      MediaTypeIdentifier.load('application/vnd.widget').match('application/vnd.widget+json') # => true
+    #
+    # @example match a specific type, respective of important parameters but irrespective of extra parameters or structured syntax
+    #      MediaTypeIdentifier.load('application/vnd.widget; type=collection').match('application/vnd.widget+json; material=steel; type=collection') # => true
+    def match(other)
+      other = MediaTypeIdentifier.load(other)
+
+      return false if other.nil?
+      return false unless type == other.type || type == WILDCARD
+      return false unless subtype == other.subtype || subtype == WILDCARD
+      return false unless suffix.empty? || suffix == other.suffix
+      parameters.each_pair do |k, v|
+        return false unless other.parameters[k] == v
+      end
+
+      true
+    end
+
+    # Determine whether this type is compatible with (i.e. is a subset or specialization of) another identifier.
+    # This is the same operation as #match, but with the position of the operands switched -- analogous to
+    # "Regexp#match(String)" vs "String =~ Regexp".
+    #
+    # @return [Boolean] true if this type is compatible with other, false otherwise
+    #
+    # @param [MediaTypeIdentifier,String] other
+    #
+    # @see #match
+    def =~(other)
+      other.match(self)
+    end
+
+    # @return [String] canonicalized representation of the media type including all suffixes and parameters
+    def to_s
+      # Our handcrafted media types consist of a rich chocolatey center
+      s = "#{type}/#{subtype}"
+
+      # coated in a hard candy shell
+      s << '+' << suffix unless suffix.empty?
+
+      # and encrusted with lexically-ordered sprinkles
+      unless parameters.empty?
+        s << '; '
+        s << parameters.keys.sort.map { |k| "#{k}=#{parameters[k]}" }.join('; ')
+      end
+
+      # May contain peanuts, tree nuts, soy, dairy, sawdust or glue
+      s
+    end
+
+    # If parameters are empty, return self; otherwise return a new object consisting of this type
+    # minus parameters.
+    #
+    # @return [MediaTypeIdentifier]
+    def without_parameters
+      if self.parameters.empty?
+        self
+      else
+        MediaTypeIdentifier.load(type: self.type, subtype: self.subtype, suffix: self.suffix)
+      end
+    end
+
+    # Make an educated guess about the structured-syntax encoding implied by this media type,
+    # which in turn governs which handler should be used to parse and generate media of this
+    # type.
+    #
+    # If a suffix e.g. "+json" is present, return it. Otherwise, return the subtype.
+    #
+    # @return [String] a type identifier fragment e.g. "json" or "xml" that MAY indicate encoding
+    #
+    # @see xxx
+    def handler_name
+      suffix.empty? ? subtype : suffix
+    end
+
+    # Extend this type identifier by adding a suffix or parameter(s); return a new type identifier.
+    #
+    # @param [String] extension an optional suffix, followed by an optional semicolon-separated list of name="value" pairs
+    # @return [MediaTypeIdentifier]
+    #
+    # @raise [ArgumentError] when an invalid string is passed (e.g. containing neither parameters nor a suffix)
+    #
+    # @example Indicate JSON structured syntax
+    #     MediaTypeIdentifier.new('application/vnd.widget') + 'json' # => 'application/vnd.widget+json'
+    #
+    # @example Indicate UTF8 encoding
+    #     MediaTypeIdentifier.new('application/vnd.widget') + 'charset=UTF8' # => 'application/vnd.widget; charset="UTF8"'
+    def +(extension)
+      parameters = extension.split(PARAMETER_SEPARATOR)
+      # remove useless initial '; '
+      parameters.shift if parameters.first && parameters.first.empty?
+
+      raise ArgumentError, "Must pass a type identifier suffix and/or parameters" if parameters.empty?
+
+      suffix = parameters.shift unless parameters.first.include?('=')
+      # remove redundant '+'
+      suffix = suffix[1..-1] if suffix && suffix[0] == '+'
+
+      parameters = parameters.each_with_object({}) do |e, h|
+        k, v = e.split('=', 2)
+        v = v[1...-1] if v =~ /^".*"$/
+        h[k] = v
+        h
+      end
+      parameters = Parameters.load(parameters)
+
+      obj = self.class.new
+      obj.type = self.type
+      obj.subtype = self.subtype
+      obj.suffix = suffix || self.suffix || ''
+      obj.parameters = self.parameters.merge(parameters)
+
+      obj
+    end
+  end
+end

data/lib/praxis/multipart/part.rb

@@ -11,6 +11,22 @@ module Praxis
       @filename = filename
     end
 
+    # Determine the content type of this response.
+    #
+    # @return [MediaTypeIdentifier]
+    def content_type
+      MediaTypeIdentifier.load(headers['Content-Type']).freeze
+    end
+
+    # Set the content type for this response.
+    # @todo DRY this out (also used in Response)
+    #
+    # @return [String]
+    # @param [String,MediaTypeIdentifier] identifier
+    def content_type=(identifier)
+      headers['Content-Type'] = MediaTypeIdentifier.load(identifier).to_s
+    end
+
     def status
       @headers['Status'].to_i
     end