circuit 0.2.0

data/Gemfile

@@ -0,0 +1,34 @@
+source "http://rubygems.org"
+
+group :development, :test do
+  gem "rake",               "~> 0.9.2"
+  gem "combustion",         "= 0.3.2"
+  gem "rspec-rails",        "~> 2.9.0"
+  gem "shoulda-matchers",   "~> 1.1.0"
+  gem "database_cleaner",   "~> 0.7.2"
+  gem "mocha",              "~> 0.11.4"
+  gem "rspec-rails-mocha",  "~> 0.3.2"
+  gem "delorean",           "~> 1.2.0"
+  gem "machinist",          "~> 2.0.0.beta2"
+  gem "faker",              "~> 1.0.1"
+  gem "simplecov",          "~> 0.6.4", :require => false
+end
+
+group :development do
+  gem "yard",               "~> 0.8"
+  gem "redcarpet",          "~> 2.1"
+end
+
+group :mongo do
+  gem "mongoid",            "~> 2.4"
+  gem "mongoid-tree",       "~> 0.7"
+  gem "bson_ext",           "~> 1.4"
+  gem "mongoid-rspec",      "= 1.4.4"
+  gem "machinist_mongo",
+      :require => "machinist/mongoid",
+      :git => "git://github.com/nmerouze/machinist_mongo.git",
+      :branch => "machinist2"
+end
+
+# Specify core dependencies in core.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 MaxMedia
+
+Permission is hereby granted, free of charge, to any person obtaining 
+a copy of this software and associated documentation files (the 
+"Software"), to deal in the Software without restriction, including 
+without limitation the rights to use, copy, modify, merge, publish, 
+distribute, sublicense, and/or sell copies of the Software, and to 
+permit persons to whom the Software is furnished to do so, subject 
+to the following conditions:
+
+The above copyright notice and this permission notice shall be included 
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,161 @@
+**Circuit is in heavy development and reorganization at the moment.  We are planning to have this API and change
+stabilized in the 0.4.0 release.  0.4.0 and future releases will include deprecation warning and a 0.4.0-stable 
+branch in GitHub.**
+
+# Circuit
+
+<<< description.md
+
+**GitHub** http://github.com/maxmedia/circuit
+
+**Issues** http://github.com/maxmedia/circuit/issues
+
+**Travis-CI** http://travis-ci.org/maxmedia/circuit
+[![Build Status](https://secure.travis-ci.org/maxmedia/circuit.png?branch=master)](http://travis-ci.org/maxmedia/circuit)
+
+**Docs** http://rubydoc.info/gems/circuit
+
+**RubyGems** http://rubygems.org/gems/circuit
+
+## Contributing
+
+Anyone is welcome to contribute to circuit.  Just [fork us on GitHub](https://github.com/maxmedia/circuit/fork_select)
+and send a pull request when you are ready.
+
+Please ensure the following compatibility requirements are met.
+
+<<< docs/COMPATIBILITY.md
+
+## A common discussion ensues.
+
+**Q: But why would someone need database powered Rack::Builder?**
+
+Response: The rack ecosystem doesn't have a good way to handle dynamic http routing.  Circuit meets the 
+needs of dynamic routing while preserving the functionality that Rack provides.  
+
+**Comment: That seems really... slow.**
+
+Response: A valid point, but circuit isn't for every codebase.  If you need dynamic routing (i.e. 
+using splat routing methods followed by a database lookup), you are going to see similar 
+performance to circuits backends.  Along with that, circuit provides a number of useful features 
+that far outweigh performance costs.
+
+**Comment: this isn't very _Railsy_**
+
+Response: In practice, codebases that use circuit to solve dynamic routing are **more** railsy.  
+Let me explain:
+
+If you are constructing an application in Rails that requires dynamic user specified slugs, you 
+probably have this line uncommented from your routes: 
+
+    # yuck.
+    match '/*', to: 'site#proxy'
+    
+Say you are creating a CMS using this line.  This means that that one action will handle all 
+requests that don't match the rest of your routes definition.  Immediately this might seem like a good 
+idea, but it will inevitably lead to a very expensive Rails action that handles a large number of 
+requests on the site.
+
+Circuit will allow you to remove this line and use middlewares to route requests to different 
+controllers (even rack applications), and control this logic via the backend of your choice. 
+Routes can be extended with their specified behaviors, allowing even more control over requests 
+than rails provides out of the box.
+
+Using the Rerouting Middleware you can easily reroute downstream requests to standard-issue rails 
+controllers, enabling your dynamic requests to add middleware, modify the rack request object and 
+even change your downstream app (to another rack app).
+
+## A mapping graph to route rack requests.
+
+TODO
+
+## Rackup-based behaviors.
+
+Circuit uses behaviors to extend a requests functionality in the rack stack.  Behaviors are written
+and stored in circuit-rackup files (`.cru`).  The difference between a normal rackup file and a 
+circuit-rackup file is that a circuit-rackup file does not have to have a `run` declaration; this 
+makes circuit-rackup files only *partially* rackup compliant. Below is an example of a behavior 
+that renders an ok response (this is a fully-compliant rackup file; however, we still use the 
+`.cru` extension for the behavior):
+
+    # ./app/behaviors/render_ok.cru
+    
+    run proc {|env| [200, {'Content-Type' => 'text/plain'}, ['OK']] }
+    
+
+First, setup your `Site`:
+
+    $ > @site = Circuit::Site.new(host: "example.com", aliases: ["www.example.com"])
+    $ > @site.save
+    $ => true
+
+Then, setup your `Node` and specify the behavior:
+
+    $ > @node = Circuit::Node.new(slug: "", behavior_klass: "RenderOk")
+    $ > @node.site = @site
+    $ > @node.save
+    $ => true
+    $ > @node.root? # the blank slug indicates the root
+    $ => true
+    $ > @node.behavior
+    $ => RenderOk
+    $ > @node.behavior.class
+    $ => Module
+    $ > @node.behavior.included_modules
+    $ => [Circuit::Behavior]
+    
+When your site is loaded, the render_ok.ru behavior will be executed.
+
+Behaviors are loaded into memory during application initialization.  Any modifications to behaviors 
+will require restarting your application.
+
+## Circuit::Middleware::Rewriter
+
+One useful middleware baked into circuit is the `Rewriter`.  The idea of this middleware is 
+to use circuit routing to route to dynamic content you have associated in you routing tree.
+
+    # ./app/behaviors/page.ru
+    
+    use Circuit::Middleware::Rewriter do |request|
+      content = request.route.last.content
+      ["/#{content.class.to_s.underscore.pluralize}", "/#{content.id}"]
+    end
+
+and the corresponding downstream rails file:
+
+    # ./config/routes.rb
+    
+    Rails.application.routes.draw do
+      resources :contents
+    end
+
+In the above example, we are assuming you have created a model that has a content object associated 
+to it.  By doing this we have now created a small CMS.
+
+## Multi-Backend support
+
+Circuit provides support for different backends to power this map tree. Currently, the gem includes a 
+Mongoid backend and a memory backend.  Each backend is how Circuit is constructed to interface with your
+persisted routing tree.  Backends are ActiveModel based.
+
+Currently, Backends are ActiveModel backed and within them they define the model that the router interacts 
+with. We are discussing the idea of separating the backends from the model (to drop the ActiveModel dependency).
+
+**This is where circuit needs your help!**  We would love to see backends for many common ODM's.  Our 
+hit-list includes:
+
+* <del>Mongoid</del>
+* <del>Memory</del>
+* Yaml
+* Redis
+* ActiveRecord
+* RiakClient/Ripple
+
+We will entertain pull requests from other commonly used libraries.
+
+<<< docs/ROADMAP.md
+
+-----------------------------------------------
+```
+<<< LICENSE
+```

data/Rakefile

@@ -0,0 +1,27 @@
+require "bundler/gem_tasks"
+require "pathname"
+
+$rake_root = Pathname(__FILE__).expand_path.dirname
+
+Dir.glob($rake_root.join("**/*.rake").to_s).each do |fn|
+  load fn
+end
+
+task :default => [:spec]
+
+namespace :clobber do
+  desc "Clobber Gem Package (pkg/)"
+  task :pkg do
+    $rake_root.join("pkg").rmtree rescue nil
+  end
+
+  desc "Clobber Coverage (coverage/)"
+  task :coverage do
+    $rake_root.join("coverage").rmtree rescue nil
+  end
+
+  task :doc => ["doc:clobber"]
+end
+
+desc "Clobber All"
+task :clobber => ["doc:clobber", "clobber:pkg", "clobber:coverage"]

data/config.ru

@@ -0,0 +1,7 @@
+require 'rubygems'
+require 'bundler'
+
+Bundler.require :default, :development
+
+Combustion.initialize! :action_controller, :action_view, :sprockets
+run Combustion::Application

data/description.md

@@ -0,0 +1,5 @@
+Circuit is a rack application middleware that enables dynamic request mapping.  Modeled after 
+[Rack::Builder](https://github.com/rack/rack/blob/master/lib/rack/builder.rb), Circuit provides 
+for a tree of url-mappings that is walked at request time.  If you are interested in dynamically 
+loading middleware and functionality into requests, circuit is a viable solution to do that in a 
+maintainable way.

data/docs/COMPATIBILITY.md

@@ -0,0 +1,14 @@
+## Compatibility
+
+Circuit is compatible with the following versions of Ruby, Rack, and Rails components:
+
+**Ruby** 1.8.7 and 1.9
+*Ruby 1.8.7 support will be removed when Rails 4 support is added*
+
+**Rack** 1.3 and 1.4
+
+**Rails** 3.1 and 3.2  
+*ActiveSupport and ActiveModel are the only requirements from Rails*
+
+**Mongoid** 2.4+
+*MongoDB/Mongoid is not required*

data/docs/ROADMAP.md

@@ -0,0 +1,29 @@
+## Roadmap
+
+### 0.2.0
+
+* <del>better readme</del>
+* <del>Separate site and routing tree</del>
+* <del>database site aliases</del>
+* <del>multi-backend support</del>
+* <del>travis-ci</del>
+* <del>Move to github issues</del>
+* <del>Remove rails dependencies (specifically ActionPack)</del>
+* <del>Behaviors are specified in rackup files, instead of classes</del>
+* <del>Behaviors support partial Rack::Builder: `run` and `use` methods<del>
+
+### 0.2.1
+* Behaviors support full Rack::Builder: `run`, `use`, and `map` methods.
+
+### 0.3.0
+
+* tree inheritable middlewares.
+* full documentation. 
+
+### 0.4.0
+
+* API stability
+
+### In the future
+
+* Goliath support

data/lib/circuit.rb

@@ -0,0 +1,125 @@
+if Object.const_defined?(:Rails)
+  require "circuit/railtie"
+end
+require 'logger'
+require 'circuit/version'
+require 'circuit/compatibility'
+require 'active_support/configurable'
+require 'dionysus/configuration_callbacks'
+
+module Circuit
+  autoload :Middleware, 'circuit/middleware'
+  autoload :Rack,       'circuit/rack'
+  autoload :Behavior,   'circuit/behavior'
+  autoload :Storage,    'circuit/storage'
+
+  # Top-level error class for Circuit errorsr
+  class CircuitError < StandardError; end
+
+  # @!attribute [r] config
+  #   Maintains configuration values for `logger`, `cru_path`, `site_store`,
+  #   and `node_store`
+  #   @return [ActiveSupport::Configurable::Configuration] configuration
+  #   @see http://rubydoc.info/gems/activesupport/ActiveSupport/Configurable/ClassMethods#config-instance_method
+
+  # @!method configure()
+  #   Configure Circuit
+  #   @yield [ActiveSupport::Configurable::Configuration] configuration object
+  #   @see http://rubydoc.info/gems/activesupport/ActiveSupport/Configurable/ClassMethods#configure-instance_method
+  include ActiveSupport::Configurable
+  include Dionysus::ConfigurationCallbacks
+  config_accessor :logger, :cru_path, :site_store, :node_store,
+                  :instance_reader => false,
+                  :instance_writer => false
+
+  # @!method logger=(logger)
+  #   @!scope class
+  #   @param [Logger] logger for Circuit
+  #   @return [Logger] logger for Circuit
+
+  # @!method logger
+  #   @!scope class
+  #   @return [Logger] logger for Circuit
+
+  # @!method cru_path=(pathname)
+  #   @!scope class
+  #   @param [Pathname,String] pathname directory for behaviors, .cru, and .ru files
+  #   @return [Pathname] pathname directory for behaviors, .cru, and .ru files
+
+  # @!method cru_path
+  #   @!scope class
+  #   @return [Pathname] pathname directory for behaviors, .cru, and .ru files
+
+  # @!method site_store
+  #   @!scope class
+  #   @return [Storage::Sites::BaseStore] the Site storage instance
+
+  # @!method node_store
+  #   @!scope class
+  #   @return [Storage::Nodes::BaseStore] the Node storage instance
+  configure do |c|
+    c.logger = ::Logger.new($stdout)
+
+    c.after :set, :cru_path do
+      val = _get(:cru_path)
+      if val and !val.is_a?(Pathname)
+        _set(:cru_path, Pathname.new(val.to_s))
+      end
+    end
+
+    c.forward :get, :site_store, Storage::Sites, :instance
+    c.forward :get, :node_store, Storage::Nodes, :instance
+  end
+
+  config.instance_exec do
+    def site_store=(args)
+      Storage::Sites.set_instance(*args)
+    end
+    def node_store=(args)
+      Storage::Nodes.set_instance(*args)
+    end
+  end
+
+  # @overload set_site_store(instance)
+  #   @param [Storage::Sites::BaseStore] instance for the Site store
+  #   @example Set the Site store
+  #     Circuit.set_site_store Circuit::Storage::Sites::MongoidStore.new
+  # @overload set_site_store(klass)
+  #   @param [Class] klass to create instance for the Site store
+  #   @example Set the Site store
+  #     Circuit.set_site_store Circuit::Storage::Sites::MongoidStore
+  # @overload set_site_store(symbol)
+  #   @param [Symbol] symbol for a Site store class under Circuit::Storage::Sites
+  #   @example Set the Site store
+  #     Circuit.set_site_store :mongoid_store
+  # @return [Storage::Sites::BaseStore] the Site storage instance
+  # @see Storage.set_instance
+  def self.set_site_store(*args)
+    config.site_store = args
+  end
+
+  # @overload set_node_store(instance)
+  #   @param [Storage::Nodes::BaseStore] instance for the Node store
+  #   @example Set the Node store
+  #     Circuit.set_node_store Circuit::Storage::Nodes::MongoidStore.new
+  # @overload set_node_store(klass)
+  #   @param [Class] klass to create instance for the Node store
+  #   @example Set the Node store
+  #     Circuit.set_node_store Circuit::Storage::Nodes::MongoidStore
+  # @overload set_node_store(symbol)
+  #   @param [Symbol] symbol for a Node store class under Circuit::Storage::Nodes
+  #   @example Set the Node store
+  #     Circuit.set_node_store :mongoid_store
+  # @return [Storage::Nodes::BaseStore] the Node storage instance
+  # @see Storage.set_instance
+  def self.set_node_store(*args)
+    config.node_store = args
+  end
+
+  # @return [Pathname] path to the vendor directory
+  def self.vendor_path
+    Pathname.new(__FILE__).expand_path.dirname.join("..", "vendor")
+  end
+end
+
+Circuit::Compatibility.make_compatible

data/lib/circuit/behavior.rb

@@ -0,0 +1,99 @@
+require 'active_support/concern'
+require 'active_support/inflector'
+require 'active_support/core_ext/module/delegation'
+require 'pathname'
+
+module Circuit
+  module Behavior
+    extend ActiveSupport::Concern
+
+    # Raised when the path for a rackup file is indeterminate.
+    class RackupPathError < Circuit::CircuitError; end
+
+    # @param [String] str name of Behavior constant to get
+    # @return [Behavior] Behavior constant
+    def self.get(str)
+      str.classify.constantize
+    rescue NameError
+      str = str.classify
+      nesting = str.deconstantize
+      nesting = (nesting.blank? ? Object : nesting.constantize)
+
+      mod = Module.new do
+          include Circuit::Behavior
+          self.cru_path = Circuit.cru_path.join(str.classify.underscore+".cru")
+          self.builder!
+          class_eval %(def self.to_s() "#{str}"; end)
+        end
+      nesting.const_set(str.demodulize, mod)
+    end
+
+    module ClassMethods
+      # Clones the builder into the subclass when using inheritance
+      def inherited(subclass)
+        subclass.builder = @builder.clone
+      end
+
+      # Indicates whether a Builder is defined or will be defined based on a rackup file
+      # @return [Boolean] false if there is no Builder and no rackup file to create one
+      def builder?
+        !!@builder or self.cru_path.file?
+      rescue RackupPathError
+        false
+      end
+
+      # Creates an empty Builder object or parses the rackup file if it exists
+      # @return [Builder] the Builder
+      def builder!
+        if self.cru_path.file?
+          @builder = Circuit::Rack::Builder.parse_file(self.cru_path)
+        else
+          @builder = Circuit::Rack::Builder.new
+        end
+      end
+
+      # Returns the Builder (and creates one if it doesn't exist yet)
+      # @return [Builder] the Builder
+      # @see #builder!
+      def builder
+        @builder ||= self.builder!
+      end
+
+      attr_writer :builder
+
+      # @return [Pathname] the path to the rackup file
+      # @raise [RackupPathError] if the rackup file path is indeterminate
+      def cru_path
+        if @cru_path.nil? and Circuit.cru_path.nil?
+          raise RackupPathError, "Rackup path cannot be determined for #{self.to_s}"
+        end
+        @cru_path ||= Circuit.cru_path.join(self.class.to_s.underscore)
+      end
+
+      # Sets the rackup file path and clears the #builder
+      # @param [Pathname,String] pathname of the rackup file
+      def cru_path=(pathname)
+        @cru_path = (pathname.is_a?(Pathname) ? pathname : Pathname.new(pathname.to_s))
+        self.builder = nil
+      end
+
+      # @!method use(middleware, *args, &block)
+      #   @see http://rubydoc.info/gems/rack/Rack/Builder#use-instance_method
+      #        ::Rack::Builder#use
+
+      # @!method run(app)
+      #   @see http://rubydoc.info/gems/rack/Rack/Builder#run-instance_method
+      #        ::Rack::Builder#run
+
+      # @!method map(path, &block)
+      #   @see http://rubydoc.info/gems/rack/Rack/Builder#map-instance_method
+      #        ::Rack::Builder#map
+
+      # @!method useto_app
+      #   @see http://rubydoc.info/gems/rack/Rack/Builder#to_app-instance_method
+      #        ::Rack::Builder#to_app
+
+      delegate :use, :run, :map, :to_app, :to => :builder
+    end
+  end
+end