lgierth-rack-mount 0.6.13

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Joshua Peek
+
+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.rdoc

@@ -0,0 +1,36 @@
+= Rack::Mount
+
+A stackable dynamic tree based Rack router.
+
+Rack::Mount supports Rack's +X-Cascade+ convention to continue trying routes if the response returns +pass+. This allows multiple routes to be nested or stacked on top of each other. Since the application endpoint can trigger the router to continue matching, middleware can be used to add arbitrary conditions to any route. This allows you to route based on other request attributes, session information, or even data dynamically pulled from a database.
+
+=== Usage
+
+Rack::Mount provides a plugin API to build custom DSLs on top of.
+
+The API is extremely minimal and only 3 methods are exposed as the public API.
+
+<tt>Rack::Mount::RouteSet#add_route</tt>:: builder method for adding routes to the set
+<tt>Rack::Mount::RouteSet#call</tt>:: Rack compatible recognition and dispatching method
+<tt>Rack::Mount::RouteSet#generate</tt>:: generates a route condition from identifiers or significant keys
+
+=== Example
+
+  require 'rack/mount'
+
+  Routes = Rack::Mount::RouteSet.new do |set|
+    # add_route takes a rack application and conditions to match with
+    #
+    # valid conditions methods are any method on Rack::Request
+    # the values to match against may be strings or regexps
+    #
+    # See Rack::Mount::RouteSet#add_route for more options.
+    set.add_route FooApp, { :request_method => 'GET', :path_info => %r{^/foo$} }, {}, :foo
+  end
+
+  # The route set itself is a simple rack app you mount
+  run Routes
+
+
+  # generate path for route named "foo"
+  Routes.generate(:path_info, :foo) #=> "/foo"

data/lib/rack/mount.rb

@@ -0,0 +1,32 @@
+require 'rack'
+
+module Rack #:nodoc:
+  # A stackable dynamic tree based Rack router.
+  #
+  # Rack::Mount supports Rack's Cascade style of trying several routes until
+  # it finds one that is not a 404. This allows multiple routes to be nested
+  # or stacked on top of each other. Since the application endpoint can
+  # trigger the router to continue matching, middleware can be used to add
+  # arbitrary conditions to any route. This allows you to route based on
+  # other request attributes, session information, or even data dynamically
+  # pulled from a database.
+  module Mount
+    autoload :CodeGeneration, 'rack/mount/code_generation'
+    autoload :GeneratableRegexp, 'rack/mount/generatable_regexp'
+    autoload :Multimap, 'rack/mount/multimap'
+    autoload :Prefix, 'rack/mount/prefix'
+    autoload :RegexpWithNamedGroups, 'rack/mount/regexp_with_named_groups'
+    autoload :Route, 'rack/mount/route'
+    autoload :RouteSet, 'rack/mount/route_set'
+    autoload :RoutingError, 'rack/mount/route_set'
+    autoload :Strexp, 'rack/mount/strexp'
+    autoload :Utils, 'rack/mount/utils'
+    autoload :Version, 'rack/mount/version'
+
+    module Analysis #:nodoc:
+      autoload :Frequency, 'rack/mount/analysis/frequency'
+      autoload :Histogram, 'rack/mount/analysis/histogram'
+      autoload :Splitting, 'rack/mount/analysis/splitting'
+    end
+  end
+end

data/lib/rack/mount/analysis/frequency.rb

@@ -0,0 +1,60 @@
+require 'rack/mount/utils'
+
+module Rack::Mount
+  module Analysis
+    class Frequency #:nodoc:
+      def initialize(*keys)
+        clear
+        keys.each { |key| self << key }
+      end
+
+      def clear
+        @raw_keys = []
+        @key_frequency = Analysis::Histogram.new
+        self
+      end
+
+      def <<(key)
+        raise ArgumentError unless key.is_a?(Hash)
+        @raw_keys << key
+        nil
+      end
+
+      def possible_keys
+        @possible_keys ||= begin
+          @raw_keys.map do |key|
+            key.inject({}) { |requirements, (method, requirement)|
+              process_key(requirements, method, requirement)
+              requirements
+            }
+          end
+        end
+      end
+
+      def process_key(requirements, method, requirement)
+        if requirement.is_a?(Regexp)
+          expression = Utils.parse_regexp(requirement)
+
+          if expression.is_a?(Regin::Expression) && expression.anchored_to_line?
+            expression = Regin::Expression.new(expression.reject { |e| e.is_a?(Regin::Anchor) })
+            return requirements[method] = expression.to_s if expression.literal?
+          end
+        end
+
+        requirements[method] = requirement
+      end
+
+      def report
+        @report ||= begin
+          possible_keys.each { |keys| keys.each_pair { |key, _| @key_frequency << key } }
+          return [] if @key_frequency.count <= 1
+          @key_frequency.keys_in_upper_quartile
+        end
+      end
+
+      def expire!
+        @possible_keys = @report = nil
+      end
+    end
+  end
+end

data/lib/rack/mount/analysis/histogram.rb

@@ -0,0 +1,74 @@
+module Rack::Mount
+  module Analysis
+    class Histogram < Hash #:nodoc:
+      attr_reader :count
+
+      def initialize
+        @count = 0
+        super(0)
+        expire_caches!
+      end
+
+      def <<(value)
+        @count += 1
+        self[value] += 1 if value
+        expire_caches!
+        self
+      end
+
+      def sorted_by_frequency
+        sort_by { |_, value| value }.reverse!
+      end
+
+      def max
+        @max ||= values.max || 0
+      end
+
+      def min
+        @min ||= values.min || 0
+      end
+
+      def mean
+        @mean ||= calculate_mean
+      end
+
+      def standard_deviation
+        @standard_deviation ||= calculate_standard_deviation
+      end
+
+      def upper_quartile_limit
+        @upper_quartile_limit ||= calculate_upper_quartile_limit
+      end
+
+      def keys_in_upper_quartile
+        @keys_in_upper_quartile ||= compute_keys_in_upper_quartile
+      end
+
+      private
+        def calculate_mean
+          count / size
+        end
+
+        def calculate_variance
+          values.inject(0) { |sum, e| sum + (e - mean) ** 2 } / count.to_f
+        end
+
+        def calculate_standard_deviation
+          Math.sqrt(calculate_variance)
+        end
+
+        def calculate_upper_quartile_limit
+          mean + standard_deviation
+        end
+
+        def compute_keys_in_upper_quartile
+          sorted_by_frequency.select { |_, value| value >= upper_quartile_limit }.map! { |key, _| key }
+        end
+
+        def expire_caches!
+          @max = @min = @mean = @standard_deviation = nil
+          @keys_in_upper_quartile = nil
+        end
+    end
+  end
+end

data/lib/rack/mount/analysis/splitting.rb

@@ -0,0 +1,159 @@
+require 'rack/mount/utils'
+
+module Rack::Mount
+  module Analysis
+    class Splitting < Frequency
+      NULL = "\0".freeze
+
+      class Key < Struct.new(:method, :index, :separators)
+        def self.split(value, separator_pattern)
+          keys = value.split(separator_pattern)
+          keys.shift if keys[0] == ''
+          keys << NULL
+          keys
+        end
+
+        def call(cache, obj)
+          (cache[method] ||= self.class.split(obj.send(method), separators))[index]
+        end
+
+        def call_source(cache, obj)
+          "(#{cache}[:#{method}] ||= Analysis::Splitting::Key.split(#{obj}.#{method}, #{separators.inspect}))[#{index}]"
+        end
+
+        def inspect
+          "#{method}[#{index}].split(#{separators.inspect})"
+        end
+      end
+
+      def clear
+        @boundaries = {}
+        super
+      end
+
+      def <<(key)
+        super
+        key.each_pair do |k, v|
+          analyze_capture_boundaries(v, @boundaries[k] ||= Histogram.new)
+        end
+      end
+
+      def separators(key)
+        @separators ||= {}
+        @separators[key] ||= lookup_separators(key)
+      end
+      attr_writer :separators
+
+      def lookup_separators(key)
+        @boundaries[key].keys_in_upper_quartile
+      end
+
+      def process_key(requirements, method, requirement)
+        separators = separators(method)
+        if requirement.is_a?(Regexp) && separators.any?
+          generate_split_keys(requirement, separators).each_with_index do |value, index|
+            requirements[Key.new(method, index, Regexp.union(*separators))] = value
+          end
+        else
+          super
+        end
+      end
+
+      private
+        def analyze_capture_boundaries(regexp, boundaries) #:nodoc:
+          return boundaries unless regexp.is_a?(Regexp)
+
+          parts = Utils.parse_regexp(regexp)
+          parts.each_with_index do |part, index|
+            if part.is_a?(Regin::Group)
+              if index > 0
+                previous = parts[index-1]
+                if previous.is_a?(Regin::Character) && previous.literal?
+                  boundaries << previous.to_s
+                end
+              end
+
+              if inside = part.expression[0]
+                if inside.is_a?(Regin::Character) && inside.literal?
+                  boundaries << inside.to_s
+                end
+              end
+
+              if index < parts.length
+                following = parts[index+1]
+                if following.is_a?(Regin::Character) && following.literal?
+                  boundaries << following.to_s
+                end
+              end
+            end
+          end
+
+          boundaries
+        end
+
+        def generate_split_keys(regexp, separators) #:nodoc:
+          segments = []
+          buf = nil
+          parts = Utils.parse_regexp(regexp)
+          parts.each_with_index do |part, index|
+            case part
+            when Regin::Anchor
+              if part.value == '$' || part.value == '\Z'
+                segments << join_buffer(buf, regexp) if buf
+                segments << NULL
+                buf = nil
+                break
+              end
+            when Regin::CharacterClass
+              break if separators.any? { |s| part.include?(s) }
+              buf = nil
+              segments << part.to_regexp(true)
+            when Regin::Character
+              if separators.any? { |s| part.include?(s) }
+                segments << join_buffer(buf, regexp) if buf
+                peek = parts[index+1]
+                if peek.is_a?(Regin::Character) && separators.include?(peek.value)
+                  segments << ''
+                end
+                buf = nil
+              else
+                buf ||= Regin::Expression.new([])
+                buf += [part]
+              end
+            when Regin::Group
+              if part.quantifier == '?'
+                value = part.expression.first
+                if separators.any? { |s| value.include?(s) }
+                  segments << join_buffer(buf, regexp) if buf
+                  buf = nil
+                end
+                break
+              elsif part.quantifier == nil
+                break if separators.any? { |s| part.include?(s) }
+                buf = nil
+                segments << part.to_regexp(true)
+              else
+                break
+              end
+            else
+              break
+            end
+          end
+
+          while segments.length > 0 && (segments.last.nil? || segments.last == '')
+            segments.pop
+          end
+
+          segments
+        end
+
+        def join_buffer(parts, regexp)
+          if parts.literal?
+            parts.to_s
+          else
+            parts.to_regexp(true)
+          end
+        end
+    end
+  end
+end

data/lib/rack/mount/code_generation.rb

@@ -0,0 +1,117 @@
+module Rack::Mount
+  module CodeGeneration #:nodoc:
+    def _expired_recognize(env) #:nodoc:
+      raise 'route set not finalized'
+    end
+
+    def rehash
+      super
+      optimize_recognize!
+    end
+
+    private
+      def expire!
+        if @optimized_recognize_defined
+          remove_metaclass_method :recognize
+
+          class << self
+            alias_method :recognize, :_expired_recognize
+          end
+
+          @optimized_recognize_defined = false
+        end
+
+        super
+      end
+
+      def optimize_container_iterator(container)
+        Utils.debug "optimizing container - size #{container.size}"
+
+        body = []
+
+        container.each_with_index { |route, i|
+          body << "route = self[#{i}]"
+          body << 'matches = {}'
+          body << 'params = route.defaults.dup'
+
+          conditions = []
+          route.conditions.each do |method, condition|
+            b = []
+            if condition.is_a?(Regexp)
+              b << "if m = obj.#{method}.match(#{condition.inspect})"
+              b << "matches[:#{method}] = m"
+              if (named_captures = route.named_captures[method]) && named_captures.any?
+                b << 'captures = m.captures'
+                b << 'p = nil'
+                b << named_captures.map { |k, j| "params[#{k.inspect}] = p if p = captures[#{j}]" }.join('; ')
+              end
+            else
+              b << "if m = obj.#{method} == route.conditions[:#{method}]"
+            end
+            b << 'true'
+            b << 'end'
+            conditions << "(#{b.join('; ')})"
+          end
+
+          body << <<-RUBY
+            if #{conditions.join(' && ')}
+              yield route, matches, params
+            end
+          RUBY
+        }
+
+        container.instance_eval(<<-RUBY, __FILE__, __LINE__)
+          def optimized_each(obj)
+            #{body.join("\n")}
+            nil
+          end
+        RUBY
+      end
+
+      def optimize_recognize!
+        Utils.debug "optimizing recognize"
+
+        keys = @recognition_keys.map { |key|
+          if key.respond_to?(:call_source)
+            key.call_source(:cache, :obj)
+          else
+            "obj.#{key}"
+          end
+        }.join(', ')
+
+        @optimized_recognize_defined = true
+
+        remove_metaclass_method :recognize
+
+        instance_eval(<<-RUBY, __FILE__, __LINE__)
+          def recognize(obj)
+            cache = {}
+            container = @recognition_graph[#{keys}]
+            optimize_container_iterator(container) unless container.respond_to?(:optimized_each)
+
+            if block_given?
+              container.optimized_each(obj) do |route, matches, params|
+                yield route, matches, params
+              end
+            else
+              container.optimized_each(obj) do |route, matches, params|
+                return route, matches, params
+              end
+            end
+
+            nil
+          end
+        RUBY
+      end
+
+      # method_defined? can't distinguish between instance
+      # and meta methods. So we have to rescue if the method
+      # has not been defined in the metaclass yet.
+      def remove_metaclass_method(symbol)
+        metaclass = class << self; self; end
+        Utils.silence_debug { metaclass.send(:remove_method, symbol) }
+      rescue NameError => e
+        nil
+      end
+  end
+end