Praxis has a Plugins framework

[Josep Blanquer]

All,

 Sorry for the cross-posting, but since Plugins is a broader theme that has been touched both from the developer and the support side I've decided to be a little more verbose with the announcement.

 In short, this email is to announce that Praxis version 0.11 contains support for a brand new Plugin framework. This will make extending Praxis a much easier and clean process, which opens up a host of new possibilities. Some of those plugin ideas have already been discussed in the list, and we believe the framework will allow for all of these to be built.

In particular, and to showcase the framework, we've built 2 simple but useful plugins that come bundled and enabled with Praxis (because Praxis itself uses them):

• Notifications: A wrapper to ActiveSupport Notifications. (Along with Praxis publishing to a couple of channels for when requests are handled)
• Stats: A metrics collector plugin that speaks Statsd. (Along with Praxis already sending certain statistics about request processing counts and timing).

Eventually, we will want to create a praxis-plugins or perhaps a praxis-contrib repository where to stick other plugins or contributed Praxis extensions. But until we have some more of those, we're going to be bundling plugins inside the 'lib/plugins' directory to keep dependencies easier.

The first one we will add to that directory is a plugin for the Praxis Mapper gem (https://github.com/rightscale/praxis-mapper). Stay tuned in the next few days to get that merged.

We've also experimented with building some authentication and authorization plugins, as they were one of the main requests in our brainstorming thread. I'm happy to share and or discuss details about how to best build these if there is interest in the list.

Anyway, it is time to start putting those plugin suggestions into realities.

The whole Plugin framework is fully documented in here: http://praxis-framework.io/reference/plugins. The documentation will allow you to both learn how to use Plugins as well as to develop new ones. We've also included documentation for the Stats and Notifications bundled Plugins.

You can read the long list of goods that 0.11 contains at: https://github.com/rightscale/praxis/blob/master/CHANGELOG.md#0111

Here's the paste from the Changelog:

• MediaTypeCollection:
  • Added support for loading decorateed 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 anInternalServerError 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 theRequest 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 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.

Happy Praxing!

Josep M.