praxis 0.10.1 → 0.11pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: eb59e46b853495a60984f953e66b32484735bbe2
-  data.tar.gz: 70a1dac56fae430f1ef83fca9879d6f1e2e85227
+  metadata.gz: 5925b03e5020e28fc79530a6991c3f030897996d
+  data.tar.gz: f301a81c0628df629ae32e805debbb653b0c2477
 SHA512:
-  metadata.gz: faa1f7c49da063995145e55ccfefd4f74687b4522f35613783aae4990b88cf82ad8c6da79192f12d43eda39c4057c8f387435513d8ff47b837a04a3685081422
-  data.tar.gz: aa5c73efd69e49cdde0129c7d5afcb245975b631a90313c5eb2240d50c5727c673a31a5cda3452e62e6a7e7632ba0734580ddb21c09fffc65c18fece9a8e28f9
+  metadata.gz: f573ece40063959ee3df1a11db4a36563acd44c68bc7ad70192f90bb8268501b4c128e504ba8080406037303a6fa5dbbf4a854d741843c80aae559df6b2a0f63
+  data.tar.gz: 3adb04192e7414e607482a44f2a8f9f83618dee6b0202094ee77c77d4d46ae0dd63e5579dd55e87ed76aa6212a0a294229108d8c5bd8d8bd841de417cf73fb63

data/.gitignore

@@ -8,4 +8,3 @@ _site/
 .tmp/
 node_modules/
 *.css.map
-

data/CHANGELOG.md

@@ -1,8 +1,49 @@
 # praxis changelog
 
-## next
+## 0.11
 
-* next thing here
+* `MediaTypeCollection`:
+  * Added support for loading  `decorate`ed `Resource` associations.
+* Refined and enhanced support for API versioning:
+  * version DSL now can take a `using` option which specifies and array of the methods are allowed: `:header`,`:params`,`:path`(new)
+    * if not specified, it will default to `using: [:header, :params]` (so that the version can be passed to the header OR the params)
+  * the new `:path` option will build the action routes by prefixing the version given a common pattern (i.e., "/v1.0/...")
+    * The effects of path versioning will be visible through `rake praxis:routes`
+    * the default api prefix pattern is ("/v(version)/") but can changed by either
+      * overriding ``Praxis::Request.path_version_prefix` and return the appropriate string prefix (i.e., by default this returns "/v") 
+      * or overriding `Praxis::Request.path_version_matcher` and providing the fully custom matching regexp. This regexp must have a capture (named `version`) that would return matched version value.
+* Enhanced praxis generator:
+  * Added a new generator (available through `praxis new app_name`) which creates a blank new app, with enough basic structure and setup to start building an API.
+  * Changed the example hello world generation command. Instead of `praxis generate app_name`, it is now available through `praxis example app_name`
+  * Changed the path lookup for the praxis directory (to not use installed gems, which could be multiple). [Issue #67]
+* `ResourceDefinition`:
+  * Added: `action_defaults` method, to define default options for actions. May be called more than once.
+  * Removed: `params`, `payload`, `headers`, and `response`. Specify these inside `action_defaults` instead.
+* `Application`:
+  * Added `middleware` method to use Rack middleware.
+* `ErrorHandler`
+  * It is now possible to register the error handler class to be invoked when an uncaught exception is thrown by setting `Application#error_handler`.
+  * The default error handler writes the error and backtrace into the Praxis logger, and returns an `InternalServerError` response
+* Added `Praxis::Notifications` framework backed by ActiveSupport::Notifications
+  * Its interface is the same as AS::Notifications (.publish, .instrument, .subscribe, and etc.)
+  * Each incoming rack request is instrumented as `rack.request.all`, with a payload of `{response: response}`, where `response` is the `Response` object that will be returned to the client. Internally, Praxis subscribes to this to generate timing statistics with `Praxis::Stats`.
+  * Additionally, each request that is dispatched to an action is instrumented as `praxis.request.all`, with a payload of `{request: request, response: response}`, where `response` is as above, and `request` is the `Request` object for the request.
+* Added `Praxis::Stats` framework backed by `Harness` (i.e. a statsd interface)
+  * Can be configured with a collector type (fake, Statsd) and an asynchronous queue + thread
+  * Wraps the statsd interface: count, increment, decrement, time ...
+* Added a new `decorate_docs` method to enhance generated JSON docs for actions in `ResourceDefinitions`
+  * Using this hook, anybody can register a block that can change/enhance the JSON structure of generated documents for any given action
+* Added a brand new Plugins architecture
+  * Plugins can easily inject code in the Request, Controller, ResourceDefinition or ActionDefinition
+  * Can be instances or singletons (and will be initialized correspondingly)
+  * Plugins can be easily configured under a unique "config key" in the Praxis config
+  * See the [Plugins](http://praxis-framework.io/reference/plugins/) section in the documentation for more information.
+* Added a Plugin for using the Praxis::Mapper gem
+  * Configurable through a simple `praxis_mapper.yml` file
+  * Its supports several repositories (by name)
+  * Each repository can be of a different type (default is sequel)
+* `praxis:doc_browser` rake task now takes a port argument for specifying the port to run on, e.g. `rake praxis:doc_browser[9000]` to run on port 9000.
+* Added `show_exceptions` configuration option to to control default ErrorHandler behavior.
 
 ## 0.10.0
 
@@ -22,7 +63,7 @@
   * Fixes [Issue #21](https://github.com/rightscale/praxis/issues/21)
 * Introduced `around` filters using blocks:
 	* Around filters can be set wrapping any of the request stages (load, validate, action...) and might apply to only certain actions (i.e. exactly the same as the before/after filters)
-  * Therefore they supports the same attributes as `before` and `after` filters. The only difference is that an around filter block will get an extra parameter with the block to call to continue the chain.	
+  * Therefore they supports the same attributes as `before` and `after` filters. The only difference is that an around filter block will get an extra parameter with the block to call to continue the chain.
 	* See the [Instances](https://github.com/rightscale/praxis/blob/master/spec/spec_app/app/controllers/instances.rb) controller for examples.
 * Fix: Change :created response template to take an optiona ‘location’ parameter (instead of a media_type one, since it doesn’t make sense for a 201 type response) [Issue #26](https://github.com/rightscale/praxis/issues/23)
 * Make the system be more robust in error reporting when controllers do not return a String or a Response
@@ -41,11 +82,7 @@
 * `MediaTypeCollection`. See [volume_snapshot](spec/spec_app/design/media_types/volume_snapshot.rb) in the specs for an example.
   * Added `member_view` DSL to define a view that renders the collection's members with the given view.
   * Change: Now requires all views to be explicitly defined (and will not automatically use the underlying member view if it exists). To define a view for member element (wrapping it in a collection) one can use the new member_view.
-* Application.setup now returns the application instance so it can be chained to other application methods.
-  * This allows a more compact way to rackup the application: `run Praxis::Application.instance.setup`.
-* Request headers are now backed by `Attributor::Hash` rather than (Structs)
-** Header keys are case sensitive now (although Praxis gracefully allows loading the uppercased RACK names )
-* Added tests for using `Attributor::Hash` attributes that can accept "extra" keys:
-** See the `bulk_create` action for an example applied to `Praxis::Multipart` (which derives from `Attributor::Hash`) payload [here](https://github.com/rightscale/praxis/blob/master/spec/spec_app/design/resources/instances.rb).
-	
+  *
+
+
 ## 0.9 Initial release

data/Gemfile

@@ -1,3 +1,3 @@
 source 'https://rubygems.org'
 
-gemspec
+gemspec

data/Guardfile

@@ -5,4 +5,5 @@ guard 'rspec', cmd: 'bundle exec rspec' do
   watch('spec/functional_spec.rb')  { "spec/" }
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/functional_spec.rb" }
   watch(%r{^app/(.+)\.rb$})     { "spec/" }
+  watch(%r{^spec/support}) { 'spec/' }
 end

data/bin/praxis

@@ -2,9 +2,38 @@
 
 require 'bundler'
 
-path_to_praxis    = Bundler.rubygems.find_name('praxis').first.full_gem_path
-path_to_generator = '%s/tasks/praxis_app_generator.thor' % path_to_praxis
+path_to_praxis = File.expand_path(File.dirname(File.dirname(__FILE__)))
+path_to_loader = '%s/tasks/loader.thor' % path_to_praxis
 
-load path_to_generator
+load path_to_loader
 
-PraxisAppGenerator.start(ARGV)
+class PraxisGenerator < Thor
+
+  # Simple helper to go get the existing description for the real action
+  # Usage must still be provided rather than retrieved (since it is not a 
+  # straight "usage" from the remote action when arguments are defined )
+  def self.desc_for( usage_string, klass, action_name, description_prefix="")
+    action_name = action_name.to_s
+    cmd = klass.commands[action_name]
+    raise "Error, could not find description for #{klass.name}##{action_name}" if cmd.nil?
+    desc usage_string, "#{description_prefix}#{cmd.description}"
+  end
+
+  desc_for "new APP_NAME", ::PraxisGen::App, :new
+  def new(app_name)
+    ::PraxisGen::App.start(['new' , app_name])
+  end
+
+  desc_for "example APP_NAME", ::PraxisGen::Example, :new
+  def example(app_name)
+    ::PraxisGen::Example.start(['new', app_name])
+  end
+  
+  desc_for "generate APP_NAME", ::PraxisGen::Example, :new, "DEPRECATED!: "
+  def generate(app_name)
+    warn "This is a deprecated method.\nTo generate a hello world example, please use:\n  praxis example #{app_name} "
+  end
+end
+
+
+PraxisGenerator.start(ARGV)

data/lib/api_browser/app/css/main.css

@@ -4111,9 +4111,6 @@ button.close {
   display: none !important;
   visibility: hidden !important; }
 
-.affix {
-  position: fixed; }
-
 @-ms-viewport {
   width: device-width; }
 

data/lib/praxis.rb

@@ -3,6 +3,8 @@ require 'attributor'
 require 'praxis-mapper'
 require 'praxis-blueprints'
 
+require 'active_support/concern'
+
 $:.unshift File.dirname(__FILE__)
 
 module Attributor
@@ -24,6 +26,7 @@ module MIME
 end
 
 module Praxis
+
   autoload :ActionDefinition, 'praxis/action_definition'
   autoload :ApiDefinition, 'praxis/api_definition'
   autoload :Application, 'praxis/application'
@@ -32,9 +35,11 @@ module Praxis
   autoload :Controller, 'praxis/controller'
   autoload :Callbacks, 'praxis/callbacks'
   autoload :Dispatcher, 'praxis/dispatcher'
+  autoload :ErrorHandler, 'praxis/error_handler'
   autoload :Exception, 'praxis/exception'
   autoload :FileGroup,'praxis/file_group'
   autoload :Plugin, 'praxis/plugin'
+  autoload :PluginConcern, 'praxis/plugin_concern'
   autoload :Request, 'praxis/request'
   autoload :ResourceDefinition, 'praxis/resource_definition'
   autoload :Response, 'praxis/response'
@@ -46,6 +51,11 @@ module Praxis
   autoload :Stage, 'praxis/stage'
   autoload :ContentTypeParser, 'praxis/content_type_parser'
 
+  autoload :Stats, 'praxis/stats'
+  autoload :Notifications, 'praxis/notifications'
+  
+  autoload :RestfulDocGenerator, 'praxis/restful_doc_generator'
+  
   # types
   autoload :Links, 'praxis/links'
   autoload :MediaType, 'praxis/media_type'
@@ -79,6 +89,12 @@ module Praxis
   module BootloaderStages
     autoload :FileLoader, 'praxis/bootloader_stages/file_loader'
     autoload :Environment, 'praxis/bootloader_stages/environment'
+
+    autoload :PluginLoader, 'praxis/bootloader_stages/plugin_loader'
+    autoload :PluginConfigPrepare, 'praxis/bootloader_stages/plugin_config_prepare'
+    autoload :PluginConfigLoad, 'praxis/bootloader_stages/plugin_config_load'
+    autoload :PluginSetup, 'praxis/bootloader_stages/plugin_setup'
+
     autoload :SubgroupLoader, 'praxis/bootloader_stages/subgroup_loader'
     autoload :WarnUnloadedFiles, 'praxis/bootloader_stages/warn_unloaded_files'
     autoload :Routing, 'praxis/bootloader_stages/routing'

data/lib/praxis/action_definition.rb

@@ -16,6 +16,16 @@ module Praxis
     attr_reader :named_routes
     attr_reader :responses
 
+    class << self
+      attr_accessor :doc_decorations      
+    end
+
+    @doc_decorations = []
+
+    def self.decorate_docs(&callback)
+      self.doc_decorations << callback
+    end
+
     def initialize(name, resource_definition, **opts, &block)
       @name = name
       @resource_definition = resource_definition
@@ -27,23 +37,8 @@ module Praxis
         end
       end
 
-      if resource_definition.params
-        saved_type, saved_opts, saved_block = resource_definition.params
-        params(saved_type, saved_opts, &saved_block)
-      end
-
-      if resource_definition.payload
-        saved_type, saved_opts, saved_block = resource_definition.payload
-        payload(saved_type, saved_opts, &saved_block)
-      end
-
-      if resource_definition.headers
-        saved_opts, saved_block = resource_definition.headers
-        headers(saved_opts, &saved_block)
-      end
-
-      resource_definition.responses.each do |name, args|
-        response(name, args)
+      resource_definition.action_defaults.each do |defaults|
+        self.instance_eval(&defaults)
       end
 
       self.instance_eval(&block) if block_given?
@@ -141,13 +136,13 @@ module Praxis
       end
     end
 
+
     def description(text = nil)
       @description = text if text
       @description
     end
 
 
-
     def describe
       {}.tap do |hash|
         hash[:description] = description
@@ -161,6 +156,9 @@ module Praxis
           memo[response.name] = response.describe
           memo
         end
+        self.class.doc_decorations.each do |callback|
+          callback.call(self, hash)
+        end
       end
     end
 

data/lib/praxis/application.rb

@@ -9,6 +9,8 @@ module Praxis
     attr_reader :router
     attr_reader :controllers
     attr_reader :resource_definitions
+    attr_reader :app
+    attr_reader :builder
 
     attr_accessor :bootloader
     attr_accessor :file_layout
@@ -16,6 +18,8 @@ module Praxis
     attr_accessor :logger
     attr_accessor :plugins
     attr_accessor :root
+    attr_accessor :error_handler
+
 
     def self.configure
       yield(self.instance)
@@ -25,11 +29,16 @@ module Praxis
       @controllers = Set.new
       @resource_definitions = Set.new
 
+      @error_handler = ErrorHandler.new
+
       @router = Router.new(self)
 
+      @builder = Rack::Builder.new
+      @app = nil
+
       @bootloader = Bootloader.new(self)
       @file_layout = nil
-      @plugins = Array.new
+      @plugins = Hash.new
       @loaded_files = Set.new
       @config = Config.new
       @root = nil
@@ -40,11 +49,30 @@ module Praxis
       @root = Pathname.new(root).expand_path
 
       @bootloader.setup!
+
+      @builder.run(@router)
+      @app = @builder.to_app
+
+      Notifications.subscribe 'rack.request.all'.freeze do |name, start, finish, _id, payload|
+        duration = (finish - start) * 1000
+        Stats.timing(name, duration)
+
+        status, _, _ = payload[:response]
+        Stats.increment "rack.request.#{status}"
+      end
+
       self
     end
 
+    def middleware(middleware, *args, &block)
+      @builder.use(middleware, *args, &block)
+    end
+
     def call(env)
-      self.router.call(env)
+      response = []
+      Notifications.instrument 'rack.request.all'.freeze, response: response do
+        response.push(*@app.call(env))
+      end
     end
 
     def layout(&block)
@@ -62,5 +90,6 @@ module Praxis
     def config=(config)
       @config.set(config)
     end
+    
   end
 end

data/lib/praxis/bootloader.rb

@@ -1,9 +1,9 @@
 module Praxis
 
-
   class Bootloader
 
-    attr_reader :application, :stages
+    attr_reader :application
+    attr_reader :stages
 
     def initialize(application)
       @application = application
@@ -24,6 +24,9 @@ module Praxis
       # Require environment first. they define constants and environment specific settings
       stages << BootloaderStages::Environment.new(:environment, application)
 
+      # then setup plugins
+      stages << BootloaderStages::PluginLoader.new(:plugins, application)
+      
       # then the initializers. as it is their job to ensure monkey patches and other
       # config is in place first.
       stages << BootloaderStages::FileLoader.new(:initializers, application)
@@ -71,11 +74,41 @@ module Praxis
       stages.find { |stage| stage.name == stage_name }.after(*stage_path, &block)
     end
 
-    def use(plugin,&block)
-      application.plugins << plugin.new(application, &block)
+    def use(plugin,**options, &block)
+      if plugin.ancestors.include?(PluginConcern)
+        plugin.setup!
+        plugin = plugin::Plugin
+      end
+
+      instance = if plugin.ancestors.include?(Singleton)
+        plugin.instance
+      elsif plugin.kind_of?(Class)
+        plugin.new
+      else
+        plugin
+      end
+
+      instance.application = application
+      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}"
+      end
+
+      if instance.config_key.nil?
+        raise "Error initializing plugin: #{plugin}, config_key may not be nil."
+      end
+
+      application.plugins[instance.config_key] = instance
+      instance
     end
 
     def setup!
+      # use the Stats and Notifications plugins by default
+      use Praxis::Stats
+      use Praxis::Notifications
+
       run
     end
 

data/lib/praxis/bootloader_stages/environment.rb

@@ -1,6 +1,5 @@
 module Praxis
 
-
   module BootloaderStages
 
     class Environment < Stage
@@ -9,18 +8,14 @@ module Praxis
       # 1) the environment.rb file    - generic stuff for all environments
       # 2) "Deployer.environment".rb  - environment specific stuff
       def execute
+        setup_initial_config!
+
         env_file = application.root + "config/environment.rb"
         require env_file if File.exists? env_file
 
-        application.plugins.each do |plugin|
-          plugin.setup!
-        end
-
         unless application.file_layout
           setup_default_layout!
         end
-
-        setup_initial_config!
       end
 
       def setup_default_layout!
@@ -47,6 +42,7 @@ module Praxis
         application.config do
           attribute :praxis do
             attribute :validate_responses, Attributor::Boolean, default: false
+            attribute :show_exceptions, Attributor::Boolean, default: false
           end
         end
       end