http_router 0.0.1

data/README.rdoc

@@ -0,0 +1,60 @@
+= HTTP Router
+
+== Introduction
+ 
+When I wrote Usher, I made a few compromised in design that I wasn't totally happy with. More and more features got added to it, and eventually, it became harder to maintain. I took a few moments to work in Node.js, and wrote a router there called Sherpa, which I was happier with. But I felt that by losing more abstraction, and tackling just the problem of HTTP routing, I could come up with something even better.
+
+== Features
+
+* Supports variables, and globbing.
+* Regex support for variables.
+* Request condition support.
+* Partial matches.
+* Supports interstitial variables (e.g. /my-:variable-brings.all.the.boys/yard).
+* Very fast and small code base (~600 loc).
+* Sinatra compatibility.
+
+== Usage
+
+=== <tt>HttpRouter.new</tt>
+
+Takes the following options:
+
+* <tt>:default_app</tt> - The default #call made on non-matches. Defaults to a 404 generator.
+* <tt>:ignore_trailing_slash</tt> - Ignores the trailing slash when matching. Defaults to true.
+* <tt>:redirect_trailing_slash</tt> - Redirect on trailing slash matches to non-trailing slash paths. Defaults to false.
+
+=== <tt>#add(name, options)</tt>
+
+Maps a route. The format for variables in paths is:
+  :variable
+  *glob
+
+Everything else is treated literally. Optional parts are surrounded by brackets. Partially matching paths have a trailing <tt>*</tt>. Optional trailing slash matching is done with <tt>/?</tt>.
+
+Once you have a route object, use <tt>HttpRouter::Route#to</tt> to add a destination and <tt>HttpRouter::Route#name</tt> to name it.
+
+e.g.
+  
+  r = HttpRouter.new
+  r.add('/test/:variable(.:format)').name(:my_test_path).to {|env| [200, {}, "Hey dude #{env['router.params'][:variable]}"]}
+  r.add('/test').redirect_to("http://www.google.com")
+  r.add('/static').serves_static_from('/my_file_system')
+  
+As well, you can support regex matching and request conditions. To add a regex match, use <tt>:matches_with => { :id => /\d+/ }</tt>.
+To match on a request condition you can use <tt>:conditions => {:request_method => %w(POST HEAD)}</tt>.
+
+There are convenience methods HttpRouter#get, HttpRouter#post, etc for each request method.
+
+=== <tt>#url(name or route, *args)</tt>
+
+Generates a route. The args can either be a hash, a list, or a mix of both.
+
+=== <tt>#call(env or Rack::Request)</tt>
+
+Recognizes and dispatches the request.
+
+=== <tt>#recognize(env or Rack::Request)</tt>
+
+Only performs recognition.
+

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "http_router"
+    s.description = s.summary = "A kick-ass HTTP router for use in Rack & Sinatra"
+    s.email = "joshbuddy@gmail.com"
+    s.homepage = "http://github.com/joshbuddy/http_router"
+    s.authors = ["Joshua Hull"]
+    s.files = FileList["[A-Z]*", "{lib,spec}/**/*"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'spec'
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts ||= []
+  t.ruby_opts << "-rrubygems"
+  t.ruby_opts << "-Ilib"
+  t.ruby_opts << "-rhttp_router"
+  t.ruby_opts << "-rspec/spec_helper"
+  t.spec_opts << "--options" << "spec/spec.opts"
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+begin
+  require 'code_stats'
+  CodeStats::Tasks.new
+rescue LoadError
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/http_router/glob.rb

@@ -0,0 +1,18 @@
+class HttpRouter
+  class Glob < Variable
+    def matches(parts, whole_path)
+      if @matches_with && match = @matches_with.match(parts.first)
+        params = [parts.shift]
+        while !parts.empty? and match = @matches_with.match(parts.first)
+          params << parts.shift
+        end
+        whole_path.replace(parts.join('/'))
+        params
+      else
+        params = parts.dup
+        parts.clear
+        params
+      end
+    end
+  end
+end

data/lib/http_router/node.rb

@@ -0,0 +1,107 @@
+class HttpRouter
+  class Node
+    attr_accessor :value, :variable, :catchall, :request_node
+    attr_reader :linear, :lookup
+
+    def initialize
+      reset!
+    end
+
+    def reset!
+      @linear = []
+      @lookup = {}
+      @catchall = nil
+    end
+
+    def add(val)
+      if val.is_a?(Variable)
+        if val.matches_with
+          new_node = Node.new
+          @linear << [val, new_node]
+          new_node
+        else
+          @catchall ||= Node.new
+          @catchall.variable = val
+          @catchall
+        end
+      elsif val.is_a?(Regexp)
+        @linear << [val, Node.new]
+        @linear.last.last
+      else
+        @lookup[val] ||= Node.new
+      end
+    end
+    
+    def add_request_methods(options)
+      if options && options[:conditions]
+        current_nodes = [@request_node ||= RequestNode.new]
+        request_options = options[:conditions]
+        RequestNode::RequestMethods.each do |method|
+          current_nodes.each_with_index do |current_node, current_node_index|
+            if request_options[method]  #we care about the method
+              if current_node  # and we have to pay attention to what currently is there.
+                unless current_node.request_method
+                  current_node.request_method = method
+                end
+              
+                case RequestNode::RequestMethods.index(method) <=> RequestNode::RequestMethods.index(current_node.request_method)
+                when 0 #use this node
+                  if request_options[method].is_a?(Regexp)
+                    current_node = RequestNode.new
+                    current_node.linear << [request_options[method], current_node]
+                  elsif request_options[method].is_a?(Array)
+                    current_nodes[current_node_index] = request_options[method].map{|val| current_node.lookup[val] ||= RequestNode.new}
+                  else
+                    current_nodes[current_node_index] = (current_node.lookup[request_options[method]] ||= RequestNode.new)
+                  end
+                when 1 #this node is farther ahead
+                  current_nodes[current_node_index] = (current_node.catchall ||= RequestNode.new)
+                  redo
+                when -1 #this method is more important than the current node
+                  new_node = RequestNode.new
+                  new_node.request_method = method
+                  new_node.catchall = current_node
+                  current_nodes[current_node_index] = new_node
+                  redo
+                end
+              else
+                current_nodes[current_node_index] = RequestNode.new
+                redo
+              end
+            elsif !current_node
+              @request_node = RequestNode.new
+              current_nodes[current_node_index] = @request_node
+              redo
+            else
+              current_node.catchall ||= RequestNode.new
+            end
+          end
+          current_nodes.flatten!
+        end
+        if @value
+          target_node = @request_node
+          while target_node.request_method
+            target_node = (target_node.catchall ||= RequestNode.new)
+          end
+          target_node.value = @value
+          @value = nil
+        end
+        current_nodes
+      elsif @request_node
+        current_node = @request_node
+        while current_node.request_method
+          current_node = (current_node.catchall ||= RequestNode.new)
+        end
+        [current_node]
+      else
+        [self]
+      end
+    end
+  end
+  
+  class RequestNode < Node
+    RequestMethods =  [:request_method, :host, :port, :scheme]
+    attr_accessor :request_method
+  end
+  
+end

data/lib/http_router/path.rb

@@ -0,0 +1,38 @@
+class HttpRouter
+  class Path
+    attr_reader :parts, :extension
+    attr_accessor :route
+    def initialize(path, parts, extension)
+      @path, @parts, @extension = path, parts, extension
+      @eval_path = path.gsub(/[:\*]([a-zA-Z0-9_]+)/) {"\#{args.shift || (options && options[:#{$1}]) || raise(MissingParameterException.new(\"missing parameter #{$1}\"))}" }
+      instance_eval "
+      def raw_url(args,options)
+        \"#{@eval_path}\"
+      end
+      "
+    end
+
+    def url(args, options)
+      path = raw_url(args, options)
+      raise TooManyParametersException.new unless args.empty?
+      Rack::Utils.uri_escape!(path)
+      path
+    end
+
+    def variables
+      unless @variables
+        @variables = @parts.select{|p| p.is_a?(Variable)}
+        @variables << @extension if @extension.is_a?(Variable)
+      end
+      @variables
+    end
+
+    def variable_names
+      variables.map{|v| v.name}
+    end
+
+    def matches_extension?(extension)
+      @extension.nil? || @extension === (extension)
+    end
+  end
+end

data/lib/http_router/response.rb

@@ -0,0 +1,20 @@
+class HttpRouter
+  class Response < Struct.new(:path, :params, :extension, :matched_path, :remaining_path)
+    attr_reader :params_as_hash, :route
+
+    def initialize(path, params, extension, matched_path, remaining_path)
+      raise if matched_path.nil?
+      super
+      @params_as_hash = path.variable_names.zip(params).inject({}) {|h, (k,v)| h[k] = v; h }
+      @params_as_hash[path.extension.name] = extension if path.extension && path.extension.is_a?(Variable)
+    end
+
+    def route
+      path.route
+    end
+    
+    def partial_match?
+      remaining_path
+    end
+  end
+end

data/lib/http_router/root.rb

@@ -0,0 +1,103 @@
+class HttpRouter
+  class Root < Node
+    def initialize(base)
+      @base = base
+      reset!
+    end
+
+    def find(request)
+      path = request.path_info.dup
+      path.slice!(-1) if @base.ignore_trailing_slash? && path[-1] == ?/
+      path.gsub!(/\.([^\/\.]+)$/, '')
+      extension = $1
+      parts = @base.split(path)
+      parts << '' if path[path.size - 1] == ?/
+
+      current_node = self
+      params = []
+      while current_node
+        break if current_node.nil? || (current_node.value && current_node.value.route.partially_match?) || parts.empty?
+        unless current_node.linear.empty?
+          whole_path = parts.join('/')
+          next_node = current_node.linear.find do |(tester, node)|
+            if tester.is_a?(Regexp) and match = whole_path.match(tester)
+              whole_path.slice!(0,match[0].size)
+              parts.replace(@base.split(whole_path))
+              node
+            elsif new_params = tester.matches(parts, whole_path)
+              params << new_params
+              node
+            else
+              nil
+            end
+          end
+          if next_node
+            current_node = next_node.last
+            next
+          end
+        end
+        if match = current_node.lookup[parts.first]
+          parts.shift
+          current_node = match
+        elsif current_node.catchall
+          params << current_node.catchall.variable.matches(parts, whole_path)
+          parts.shift
+          current_node = current_node.catchall
+        elsif parts.size == 1 && parts.first == '' && current_node && (current_node.value && current_node.value.route.trailing_slash_ignore?)
+          parts.shift
+        elsif current_node.request_node
+          break
+        else
+          current_node = nil
+        end
+      end
+      
+      if current_node && current_node.request_node
+        current_node = current_node.request_node
+        while current_node
+          previous_node = current_node
+          break if current_node.nil? || current_node.is_a?(RoutingError) || current_node.value
+          request_value = request.send(current_node.request_method)
+          unless current_node.linear.empty?
+            next_node = current_node.linear.find do |(regexp, node)|
+              regexp === request_value
+            end
+            if next_node
+              current_node = next_node.last
+              next
+            end
+          end
+          current_node = current_node.lookup[request_value] || current_node.catchall
+          if current_node.nil?
+            current_node = previous_node.request_method == :request_method ? RoutingError.new(405, {"Allow" => previous_node.lookup.keys.join(", ")}) : nil
+          else
+            current_node
+          end
+        end
+      end
+      if current_node.is_a?(RoutingError)
+        current_node
+      elsif current_node && current_node.value
+        if parts.empty?
+          post_match(current_node.value, params, extension, request.path_info)
+        elsif current_node.value.route.partially_match?
+          rest = '/' << parts.join('/') << (extension ? ".#{extension}" : '')
+          
+          post_match(current_node.value, params, nil, request.path_info[0, request.path_info.size - rest.size], rest)
+        else
+          nil
+        end
+      else
+        nil
+      end
+    end
+
+    def post_match(path, params, extension, matched_path, remaining_path = nil)
+      if path.route.partially_match? || path.matches_extension?(extension)
+        Response.new(path, params, extension, matched_path, remaining_path)
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/http_router/route.rb

@@ -0,0 +1,102 @@
+class HttpRouter
+  class Route
+    attr_reader :dest, :paths
+    attr_accessor :trailing_slash_ignore, :partially_match, :default_values
+
+    def initialize(base, default_values)
+      @base, @default_values = base, default_values
+      @paths = []
+    end
+
+    def name(name)
+      @name = name
+      @base.routes[name] = self
+    end
+
+    def named
+      @name
+    end
+
+    def to(dest = nil, &block)
+      @dest = dest || block
+      self
+    end
+
+    def match_partially!(match = true)
+      @partially_match = match
+      self
+    end
+  
+    def redirect(path, status = 302)
+      unless (300..399).include?(status)
+        raise ArgumentError, "Status has to be an integer between 300 and 399"
+      end
+      to { |env|
+        params = env['router.params']
+        response = ::Rack::Response.new
+        response.redirect(eval(%|"#{path}"|), status)
+        response.finish
+      }
+      self
+    end
+    
+    def serves_static_from(root)
+      if File.directory?(root)
+        match_partially!
+        to ::Rack::File.new(root)
+      else
+        to proc{|env| env['PATH_INFO'] = File.basename(root); ::Rack::File.new(File.dirname(root)).call(env)}
+      end
+      self
+    end
+
+    def trailing_slash_ignore?
+      @trailing_slash_ignore
+    end
+
+    def partially_match?
+      @partially_match
+    end
+
+    def url(*args)
+      options = args.last.is_a?(Hash) ? args.pop : nil
+      path = matching_path(args.empty? ? options : args)
+      raise UngeneratableRouteException.new unless path
+      path.url(args, options)
+    end
+
+    def matching_path(params)
+      if @paths.size == 1
+        @paths.first
+      else
+        if params.is_a?(Array)
+          @paths.each do |path|
+            if path.variables.size == params.size
+              return path
+            end
+          end
+          nil
+        else
+          maximum_matched_route = nil
+          maximum_matched_params = -1
+          @paths.each do |path|
+            param_count = 0
+            path.variables.each do |variable|
+              if params && params.key?(variable.name)
+                param_count += 1
+              else
+                param_count = -1
+                break
+              end
+            end
+            if (param_count != -1 && param_count > maximum_matched_params)
+              maximum_matched_params = param_count;
+              maximum_matched_route = path;
+            end
+          end
+          maximum_matched_route
+        end
+      end
+    end
+  end
+end

data/lib/http_router/sinatra.rb

@@ -0,0 +1,149 @@
+$LOAD_PATH << File.join(File.dirname(__FILE__), '..')
+require 'http_router'
+
+class HttpRouter
+  module Interface
+    class Sinatra
+
+      def initialize
+        ::Sinatra.send(:include, Extension)
+      end
+
+      module Extension
+
+        def self.registered(app)
+          app.send(:include, Extension)
+        end
+
+        def self.included(base)
+          base.extend ClassMethods
+        end
+
+        def generate(name, *params)
+          self.class.generate(name, *params)
+        end
+
+        private
+          def route!(base=self.class, pass_block=nil)
+            if base.router and match = base.router.recognize(@request)
+              if match.is_a?(RoutingError)
+                route_eval { 
+                  match.headers.each{|k,v| response[k] = v}
+                  status match.status
+                }
+              else
+                @block_params = match.params
+                (@params ||= {}).merge!(match.params_as_hash)
+                pass_block = catch(:pass) do
+                  route_eval(&match.route.dest)
+                end
+              end
+            end
+
+            # Run routes defined in superclass.
+            if base.superclass.respond_to?(:router)
+              route! base.superclass, pass_block
+              return
+            end
+
+            route_eval(&pass_block) if pass_block
+
+            route_missing
+          end
+
+        module ClassMethods
+
+          def new(*args, &bk)
+            configure! unless @_configured
+            super(*args, &bk)
+          end
+
+          def route(verb, path, options={}, &block)
+            name = options.delete(:name)
+            options[:conditions] ||= {}
+            options[:conditions][:request_method] = verb
+            options[:conditions][:host] = options.delete(:host) if options.key?(:host)
+
+            define_method "#{verb} #{path}", &block
+            unbound_method = instance_method("#{verb} #{path}")
+            block =
+              if block.arity != 0
+                lambda { unbound_method.bind(self).call(*@block_params) }
+              else
+                lambda { unbound_method.bind(self).call }
+              end
+
+            invoke_hook(:route_added, verb, path, block)
+
+            route = router.add(path, options).to(block)
+            route.name(name) if name
+            route
+          end
+
+          def router
+            @router ||= HttpRouter.new
+            block_given? ? yield(@router) : @router
+          end
+
+          def generate(name, *params)
+            router.url(name, *params)
+          end
+
+          def reset!
+            router.reset!
+            super
+          end
+
+          def configure!
+            configure :development do
+              error 404 do
+                content_type 'text/html'
+
+                (<<-HTML).gsub(/^ {17}/, '')
+                <!DOCTYPE html>
+                <html>
+                <head>
+                  <style type="text/css">
+                  body { text-align:center;font-family:helvetica,arial;font-size:22px;
+                    color:#888;margin:20px}
+                  #c {margin:0 auto;width:500px;text-align:left}
+                  </style>
+                </head>
+                <body>
+                  <h2>Sinatra doesn't know this ditty.</h2>
+                  <div id="c">
+                    Try this:
+                    <pre>#{request.request_method.downcase} '#{request.path_info}' do\n  "Hello World"\nend</pre>
+                  </div>
+                </body>
+                </html>
+                HTML
+              end
+              error 405 do
+                content_type 'text/html'
+
+                (<<-HTML).gsub(/^ {17}/, '')
+                <!DOCTYPE html>
+                <html>
+                <head>
+                  <style type="text/css">
+                  body { text-align:center;font-family:helvetica,arial;font-size:22px;
+                    color:#888;margin:20px}
+                  #c {margin:0 auto;width:500px;text-align:left}
+                  </style>
+                </head>
+                <body>
+                  <h2>Sinatra sorta knows this ditty, but the request method is not allowed.</h2>
+                </body>
+                </html>
+                HTML
+              end
+            end
+
+            @_configured = true
+          end
+        end # ClassMethods
+      end # Extension
+    end # Sinatra
+  end # Interface
+end # HttpRouter

data/lib/http_router/variable.rb

@@ -0,0 +1,26 @@
+class HttpRouter
+  class Variable
+    attr_reader :name, :matches_with
+
+    def initialize(base, name, matches_with = nil)
+      @base = base
+      @name = name
+      @matches_with = matches_with
+    end
+    
+    def matches(parts, whole_path)
+      if @matches_with.nil?
+        parts.first
+      elsif @matches_with && match = @matches_with.match(whole_path)
+        whole_path.slice!(0, match[0].size)
+        parts.replace(@base.split(whole_path))
+        match[0]
+      end
+    end
+    
+    def ===(part)
+      @matches_with.nil?
+    end
+    
+  end
+end