praxis 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0dbe3630ec0519b3fe1c0c4581155e1fd9858002
-  data.tar.gz: 1a93b0745b2413203e13a69a1a7c83e41f4c7ab8
+  metadata.gz: 2498e7738d76689742c8f8d3486e1e194c3c0e23
+  data.tar.gz: 989b01e640dd2ad1dbc8d67a320add322d76ec36
 SHA512:
-  metadata.gz: 8f0e8f6ff18f14cbfd2e0d18fbbcb7a05ef32c01914106dd29952c63b8d2dd70fbab8c254961ca48f9ae2597206f0548acd057b820adbc5656d74d98ca7073e7
-  data.tar.gz: 77d8c97b50f6f3853002289d59f8e17585269d5dad0d3b1d8089e00694dabd06fddfa67ed0179c918587ef6b1e624a4736b47a4b2b05478ca63ef6cde2135dda
+  metadata.gz: a0007fdd60eb2186c06e2d8652a4daa1e09bd8dd7d7f1c84109605d946bf32070fccb177c3fdaf4129d498610a957b44ca4a3aed4f53ddb9699ff9abbd7f2a7c
+  data.tar.gz: 729ea4407e325d64658f690e8f6ae9e6716bb494b36b0cf97a33e2f372901e65cf4e4330e4a4648ce867f60db3e0cbf34ae7f2d906455c83ae7bc1e2563c6660

data/CHANGELOG.md

@@ -2,17 +2,43 @@
 
 ## next
 
+## 0.16.0
+
+* Overhauled traits: they're now represented by a `Trait` class, which are created from `ApiDefinition#trait`.
+  * `ApiDefinition#describe` will also include details of the defined traits.
+  * `ResourceDefinition#describe` and `ActionDefinition#describe` will also include the names of the used traits.
+  * *Note*: this may break some existing trait use cases, as they are now more-defined in their behavior, rather than simply stored blocks that are `instance_eval`-ed on the target.
+* Deprecated `ResourceDefinition.routing`. Use `ResourceDefinition.prefix` to define resource-level route prefixes instead.
+* Significantly refactored route generation.
+  * The `base_path` property defined in `ApiDefinition#info` will now appear in the routing paths 'base' (instead of simply being used for documentation purposes).
+    *Note*: unlike other info at that level, a global (unversioned) `base_path` is *not* overriden by specific version, rather the specific version's path is appended to the global path.
+  * Any prefixes set on a `ResourceDefinition` or inside a `routing` block of an ActionDefinition are now additive. For example:
+    * Setting a "/myresource" prefix in a "MyResource" definition, and setting a "/myaction" prefix within an action of that resource definition will result in a route containing the following segments ".../myresource/myaction...".
+    * Prefixes can be equally set by including `Traits`, which will follow exactly the same additive rules.
+  * To break the additive nature of the prefixes one can use a couple of different options:
+    * Define the action route path with "//" to make it absolute, i.e. a path like "//people" would not include any defined prefix.
+    * Explicitly clear the prefix by setting the prefix to `''` or `'//'`.
+* Added `base_params` to `ApiDefinition#info` as a way to share common action params
+  * `base_params` may be defined for a specific Api version, which will make sharing params across all Resource definitions of that version)
+  * or `base_params` may be defined in the Global Api section, which will make the parameters shared across all actions of all defined Api versions.
+* Fixed `MediaType#describe` to include the correct string representation of its identifier.
+* Allow route options to be passed to the underlying router (i.e. Mustermann at the moment)
+  * routes defined in the `routing` blocks can now take any extra options which will be passed down to the Mustermann routing engine. Unknown options will be ignored!
+  * Displaying routes (`praxis routes` or `rake praxis:routes`) will now include any options defined in a route.
+  * Added an example on the instances resource of the embedded spec_app to show how to use the advanced `*` pattern and the `:except` Mustermann options (along with the required `:splat` attribute).
+* Spruced up the example app (generator) to use the latest `prefix` and `trait` changes
+
 ## 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.  
+* 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 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
 

data/lib/api_browser/Gruntfile.js

@@ -220,7 +220,12 @@ module.exports = function(grunt) {
           cwd: userDocsPath,
           dest: buildPath,
           src: [
-            'api/**'
+            '**/*',
+            '!**/*.{js,scss,sass,less,coffee}',
+            '!views/**',
+            '!**/.*',
+            '!output/**'
+
           ]
         }]
       }

data/lib/praxis.rb

@@ -7,17 +7,6 @@ require 'active_support/concern'
 
 $:.unshift File.dirname(__FILE__)
 
-module Attributor
-  class DSLCompiler
-    def use(name)
-      unless Praxis::ApiDefinition.instance.traits.has_key? name
-        raise Exceptions::InvalidTrait.new("Trait #{name} not found in the system")
-      end
-      self.instance_eval(&Praxis::ApiDefinition.instance.traits[name])
-    end
-  end
-end
-
 require 'mime'
 module MIME
   class Header
@@ -48,8 +37,10 @@ module Praxis
   autoload :ResponseTemplate, 'praxis/response_template'
   autoload :Route, 'praxis/route'
   autoload :Router, 'praxis/router'
+  autoload :RoutingConfig, 'praxis/routing_config'
   autoload :SimpleMediaType, 'praxis/simple_media_type'
   autoload :Stage, 'praxis/stage'
+  autoload :Trait, 'praxis/trait'
 
   autoload :Stats, 'praxis/stats'
   autoload :Notifications, 'praxis/notifications'
@@ -121,7 +112,4 @@ module Praxis
     autoload :Response, 'praxis/request_stages/response'
   end
 
-  module Skeletor
-    autoload :RestfulRoutingConfig, 'praxis/skeletor/restful_routing_config'
-  end
 end

data/lib/praxis/action_definition.rb

@@ -6,6 +6,7 @@
 #
 # Plugins may be used to extend this Config DSL.
 #
+
 module Praxis
   class ActionDefinition
 
@@ -15,6 +16,7 @@ module Praxis
     attr_reader :primary_route
     attr_reader :named_routes
     attr_reader :responses
+    attr_reader :traits
 
     # opaque hash of user-defined medata, used to decorate the definition,
     # and also available in the generated JSON documents
@@ -36,6 +38,7 @@ module Praxis
       @responses = Hash.new
       @metadata = Hash.new
       @routes = []
+      @traits = []
 
       if (media_type = resource_definition.media_type)
         if media_type.kind_of?(Class) && media_type < Praxis::Types::MediaTypeCommon
@@ -43,19 +46,40 @@ module Praxis
         end
       end
 
-      resource_definition.action_defaults.each do |defaults|
-        self.instance_eval(&defaults)
+      version = resource_definition.version
+      api_info = ApiDefinition.instance.info(resource_definition.version)
+
+      version_prefix = "#{api_info.base_path}#{resource_definition.version_prefix}"
+      prefix = Array(resource_definition.prefix)
+
+      @routing_config = RoutingConfig.new(version: version, base: version_prefix, prefix: prefix)
+
+      resource_definition.traits.each do |trait|
+        self.trait(trait)
       end
 
+      resource_definition.action_defaults.apply!(self)
+
       self.instance_eval(&block) if block_given?
     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)
+      trait.apply!(self)
+      traits << trait_name
+    end
+    alias_method :use, :trait
+
     def update_attribute(attribute, options, block)
       attribute.options.merge!(options)
       attribute.type.attributes(options, &block)
     end
 
-    def response( name, **args )
+    def response(name, **args)
       template = ApiDefinition.instance.response(name)
       @responses[name] = template.compile(self, **args)
     end
@@ -68,13 +92,6 @@ module Praxis
       return Attributor::Attribute.new(type, opts, &block)
     end
 
-    def use(trait_name)
-      unless ApiDefinition.instance.traits.has_key? trait_name
-        raise Exceptions::InvalidTrait.new("Trait #{trait_name} not found in the system")
-      end
-      self.instance_eval(&ApiDefinition.instance.traits[trait_name])
-    end
-
     def params(type=Attributor::Struct, **opts, &block)
       return @params if !block && type == Attributor::Struct
 
@@ -87,7 +104,17 @@ module Praxis
         update_attribute(@params, opts, block)
       else
         @params = create_attribute(type, **opts, &block)
+        if (api_info = ApiDefinition.instance.info(resource_definition.version))
+          if api_info.base_params
+            base_attrs = api_info.base_params.attributes
+            @params.attributes.merge!(base_attrs) do |key, oldval, newval|
+              oldval
+            end
+          end
+        end
       end
+
+      @params
     end
 
     def payload(type=Attributor::Struct, **opts, &block)
@@ -112,8 +139,8 @@ module Praxis
       else
         type = Attributor::Hash.of(key:String) unless type
         @headers = create_attribute(type,
-          dsl_compiler: HeadersDSLCompiler, case_insensitive_load: true,
-          **opts, &block)
+                                    dsl_compiler: HeadersDSLCompiler, case_insensitive_load: true,
+                                    **opts, &block)
       end
       @precomputed_header_keys_for_rack = nil #clear memoized data
     end
@@ -133,11 +160,11 @@ module Praxis
 
 
     def routing(&block)
-      routing_config = Skeletor::RestfulRoutingConfig.new(name, resource_definition, &block)
+      @routing_config.instance_eval &block
 
-      @routes = routing_config.routes
-      @primary_route = routing_config.routes.first
-      @named_routes = routing_config.routes.each_with_object({}) do |route, hash|
+      @routes = @routing_config.routes
+      @primary_route = @routing_config.routes.first
+      @named_routes = @routing_config.routes.each_with_object({}) do |route, hash|
         next if route.name.nil?
         hash[route.name] = route
       end
@@ -166,6 +193,8 @@ module Praxis
           memo[response.name] = response.describe
           memo
         end
+        hash[:traits] = traits if traits.any?
+
         self.class.doc_decorations.each do |callback|
           callback.call(self, hash)
         end

data/lib/praxis/api_definition.rb

@@ -10,6 +10,7 @@ module Praxis
     attr_reader :traits
     attr_reader :responses
     attr_reader :infos
+    attr_reader :global_info
 
     def self.define(&block)
       if block.arity == 0
@@ -22,8 +23,12 @@ module Praxis
     def initialize
       @responses = Hash.new
       @traits = Hash.new
+      @base_path = ''
+
+      @global_info = ApiGeneralInfo.new
+
       @infos = Hash.new do |hash, version|
-          hash[version] = ApiGeneralInfo.new
+        hash[version] = ApiGeneralInfo.new(@global_info)
       end
     end
 
@@ -41,35 +46,49 @@ module Praxis
       if self.traits.has_key? name
         raise Exceptions::InvalidTrait.new("Overwriting a previous trait with the same name (#{name})")
       end
-      self.traits[name] = block
+      self.traits[name] = Trait.new(&block)
     end
 
-    # Setting info to the nil version, means setting it for all versions (if they don't  override them)
-    def info( version=nil, &block)
-      i = @infos[version]
-      i.instance_eval(&block)
-      i
+    # Setting info to the nil version, means setting it for all versions (if they don't override them)
+    def info(version=nil, &block)
+      if version.nil?
+        if block_given?
+          @global_info.instance_eval(&block)
+        else
+          @global_info
+        end
+      else
+        i = @infos[version]
+        if block_given?
+          i.instance_eval(&block)
+        end
+        i
+      end
     end
-    
+
     def describe
-      global_info = @infos[nil].describe
       data = Hash.new do |hash, version|
         hash[version] = Hash.new
       end
+
+      data[:global][:info] = @global_info.describe
+
       # Fill in the "info" portion
       @infos.each do |version,info|
-        next unless version
-        info_hash = global_info.merge(info.describe)
-        [:name, :title].each do |attr|
-          raise "Error: API Global information for version '#{version}' does not have '#{attr}' defined. " unless info_hash.key? attr
+        data[version][:info] = info.describe
+      end
+
+
+      if traits.any?
+        data[:traits] = {}
+        traits.each do |name, trait|
+          data[:traits][name] = trait.describe
         end
-        data[version][:info] = info_hash
       end
-      
-      # Maybe report the traits?...or somehow the registered response_templates ...
+
       data
     end
-    
+
     define do |api|
       api.response_template :ok do |media_type: |
         media_type media_type

data/lib/praxis/api_general_info.rb

@@ -1,36 +1,79 @@
 module Praxis
   class ApiGeneralInfo
-        
+
+    def initialize(global_info=nil)
+      @global_info = global_info
+      @data = Hash.new
+    end
+
+    def get(k)
+      return @data[k] if @data.key?(k)
+      return @global_info.get(k) if @global_info
+      nil
+    end
+
+    def set(k, v)
+      @data[k] = v
+    end
+
     def name(val=nil)
-      return @name unless val
-      @name = val
+      if val.nil?
+        get(:name)
+      else
+        set(:name, val)
+      end
     end
 
     def title(val=nil)
-      return @title unless val
-      @title = val
+      if val.nil?
+        get(:title)
+      else
+        set(:title, val)
+      end
     end
 
     def description(val=nil)
-      return @description unless val
-      @description = val
+      if val.nil?
+        get(:description)
+      else
+        set(:description, val)
+      end
     end
 
     def base_path(val=nil)
-      return @base_path unless val
-      @base_path = val
+      if val
+        return set(:base_path, val)
+      end
+
+      if @global_info
+        version_path = @data.fetch(:base_path,'')
+        global_path = @global_info.get(:base_path)
+        "#{global_path}#{version_path}"
+      else
+        @data.fetch(:base_path,'')
+      end
+    end
+
+    def base_params(type=Attributor::Struct, **opts, &block)
+      if !block && type == Attributor::Struct
+        get(:base_params)
+      else
+        set(:base_params, Attributor::Attribute.new(type, opts, &block) )
+      end
     end
-        
+
     def describe
       hash = { schema_version: "1.0".freeze }
-
       [:name, :title, :description, :base_path].each do |attr|
-        val = self.__send__(attr) 
+        val = self.__send__(attr)
         hash[attr] = val unless val.nil?
       end
+      if base_params
+        hash[:base_params] = base_params.describe[:type][:attributes]
+      end
       hash
-    end      
-        
+    end
+
   end
-  
-end
+
+end

data/lib/praxis/request_stages/request_stage.rb

@@ -5,7 +5,6 @@ module Praxis
     # 1- Run specific controller callbacks (in addition to any normal callbacks)
     # 2- Shortcut the controller callback chain if any returns a Response object
     class RequestStage < Stage
-      extend Forwardable
 
       alias :dispatcher :application # it's technically application in the base Stage
 
@@ -34,22 +33,19 @@ module Praxis
         setup_deferred_callbacks!
       end
 
-      # Avoid using delegators, and create the explicit functions:
-      # def_delegators :@context, :controller, :action, :request
-      # they allocate all kinds of things and we don't need the generality here
       def controller
         @context.controller
       end
+
       def action
         @context.action
       end
+      
       def request
         @context.request
       end
 
-      
       def run
-
         # stage-level callbacks (typically empty) will never shortcut
         execute_callbacks(self.before_callbacks)