rage-rb 0.1.0

data/lib/rage/router/backend.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require "uri"
+
+class Rage::Router::Backend
+  OPTIONAL_PARAM_REGEXP = /\/?\(\/?(:\w+)\/?\)/
+  STRING_HANDLER_REGEXP = /^([a-z0-9_\/]+)#([a-z_]+)$/
+
+  def initialize
+    @routes = []
+    @trees = {}
+    @constrainer = Rage::Router::Constrainer.new({})
+  end
+
+  def on(method, path, handler, constraints: {})
+    raise "Path could not be empty" if path&.empty?
+
+    if match_index = (path =~ OPTIONAL_PARAM_REGEXP)
+      raise "Optional Parameter has to be the last parameter of the path" if path.length != match_index + $&.length
+
+      path_full = path.sub(OPTIONAL_PARAM_REGEXP, "/#{$1}")
+      path_optional = path.sub(OPTIONAL_PARAM_REGEXP, "")
+
+      on(method, path_full, handler)
+      on(method, path_optional, handler)
+      return
+    end
+
+    if handler.is_a?(String)
+      raise "Invalid route handler format, expected to match the 'controller#action' pattern" unless handler =~ STRING_HANDLER_REGEXP
+
+      controller, action = to_controller_class($1), $2
+      run_action_method_name = controller.__register_action(action.to_sym)
+
+      handler = eval("->(env, params) { #{controller}.new(env, params).#{run_action_method_name} }")
+    else
+      raise "Non-string route handler should respond to `call`" unless handler.respond_to?(:call)
+      # while regular handlers are expected to be called with the `env` and `params` objects,
+      # lambda handlers expect just `env` as an argument;
+      # TODO: come up with something nicer?
+      orig_handler = handler
+      handler = ->(env, _params) { orig_handler.call(env) }
+    end
+
+    __on(method, path, handler, constraints)
+  end
+
+  def lookup(env)
+    constraints = @constrainer.derive_constraints(env)
+    find(env, constraints)
+  end
+
+  private
+
+  def __on(method, path, handler, constraints)
+    @constrainer.validate_constraints(constraints)
+    # Let the constrainer know if any constraints are being used now
+    @constrainer.note_usage(constraints)
+
+    # Boot the tree for this method if it doesn't exist yet
+    @trees[method] ||= Rage::Router::StaticNode.new("/")
+
+    pattern = path
+    if pattern == "*" && !@trees[method].prefix.empty?
+      current_root = @trees[method]
+      @trees[method] = Rage::Router::StaticNode.new("")
+      @trees[method].static_children["/"] = current_root
+    end
+
+    current_node = @trees[method]
+    parent_node_path_index = current_node.prefix.length
+
+    i, params = 0, []
+    while i <= pattern.length
+      if pattern[i] == ":" && pattern[i + 1] == ":"
+        # It's a double colon
+        i += 2
+        next
+      end
+
+      is_parametric_node = pattern[i] == ":" && pattern[i + 1] != ":"
+      is_wildcard_node = pattern[i] == "*"
+
+      if is_parametric_node || is_wildcard_node || (i == pattern.length && i != parent_node_path_index)
+        static_node_path = pattern[parent_node_path_index, i - parent_node_path_index]
+        static_node_path = static_node_path.split("::").join(":")
+        static_node_path = static_node_path.split("%").join("%25")
+        # add the static part of the route to the tree
+        current_node = current_node.create_static_child(static_node_path)
+      end
+
+      if is_parametric_node
+        last_param_start_index = i + 1
+
+        j = last_param_start_index
+        while true
+          char = pattern[j]
+          is_end_of_node = (char == "/" || j == pattern.length)
+
+          if is_end_of_node
+            param_name = pattern[last_param_start_index, j - last_param_start_index]
+            params << param_name
+
+            static_part_start_index = j
+            while j < pattern.length
+              j_char = pattern[j]
+              break if j_char == "/"
+              if j_char == ":"
+                next_char = pattern[j + 1]
+                next_char == ":" ? j += 1 : break
+              end
+              j += 1
+            end
+
+            static_part = pattern[static_part_start_index, j - static_part_start_index]
+            unless static_part.empty?
+              static_part = static_part.split("::").join(":")
+              static_part = static_part.split("%").join("%25")
+            end
+
+            last_param_start_index = j + 1
+
+            if is_end_of_node || pattern[j] == "/" || j == pattern.length
+              node_path = pattern[i, j - i]
+
+              pattern = "#{pattern[0, i + 1]}#{static_part}#{pattern[j, pattern.length - j]}"
+              i += static_part.length
+
+              current_node = current_node.create_parametric_child(static_part == "" ? nil : static_part, node_path)
+              parent_node_path_index = i + 1
+              break
+            end
+          end
+
+          j += 1
+        end
+      elsif is_wildcard_node
+        # add the wildcard parameter
+        params << "*"
+        current_node = current_node.create_wildcard_child
+        parent_node_path_index = i + 1
+        raise "Wildcard must be the last character in the route" if i != pattern.length - 1
+      end
+
+      i += 1
+    end
+
+    if pattern == "*"
+      pattern = "/*"
+    end
+
+    @routes.each do |existing_route|
+      if (
+        existing_route[:method] == method &&
+        existing_route[:pattern] == pattern &&
+        existing_route[:constraints] == constraints
+      )
+        raise "Method '#{method}' already declared for route '#{pattern}' with constraints '#{constraints.inspect}'"
+      end
+    end
+
+    route = { method: method, path: path, pattern: pattern, params: params, constraints: constraints, handler: handler }
+    @routes << route
+    current_node.add_route(route, @constrainer)
+  end
+
+  def find(env, derived_constraints)
+    method, path = env["REQUEST_METHOD"], env["PATH_INFO"]
+
+    current_node = @trees[method]
+    return nil unless current_node
+
+    origin_path = path
+
+    path_index = current_node.prefix.length
+    url_params = []
+    path_len = path.length
+
+    brothers_nodes_stack = []
+
+    while true
+      if path_index == path_len && current_node.is_leaf_node
+        handle = current_node.handler_storage.get_matching_handler(derived_constraints)
+        if handle
+          return {
+            handler: handle[:handler],
+            params: handle[:create_params_object].call(url_params)
+          }
+        end
+      end
+
+      node = current_node.get_next_node(path, path_index, brothers_nodes_stack, url_params.length)
+
+      unless node
+        return if brothers_nodes_stack.length == 0
+
+        brother_node_state = brothers_nodes_stack.pop
+        path_index = brother_node_state[:brother_path_index]
+        url_params.slice!(brother_node_state[:params_count], url_params.length)
+        node = brother_node_state[:brother_node]
+      end
+
+      current_node = node
+
+      if current_node.kind == Rage::Router::Node::STATIC
+        path_index += current_node.prefix.length
+        next
+      end
+
+      if current_node.kind == Rage::Router::Node::WILDCARD
+        param = origin_path[path_index, origin_path.length - path_index]
+        param = Rack::Utils.unescape(param) if param.include?("%")
+
+        url_params << param
+        path_index = path_len
+        next
+      end
+
+      if current_node.kind == Rage::Router::Node::PARAMETRIC
+        param_end_index = origin_path.index("/", path_index)
+        param_end_index = path_len unless param_end_index
+
+        param = origin_path.slice(path_index, param_end_index - path_index)
+        param = Rack::Utils.unescape(param) if param.include?("%")
+
+        url_params << param
+        path_index = param_end_index
+      end
+    end
+  end
+
+  def to_controller_class(str)
+    str.capitalize!
+    str.gsub!(/([\/_])([a-zA-Z0-9]+)/) do
+      if $1 == "/"
+        "::#{$2.capitalize}"
+      else
+        $2.capitalize
+      end
+    end
+
+    klass = "#{str}Controller"
+    if Object.const_defined?(klass)
+      Object.const_get(klass)
+    else
+      raise "Routing error: could not find the #{klass} class"
+    end
+  end
+end

data/lib/rage/router/constrainer.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "set"
+
+class Rage::Router::Constrainer
+  attr_reader :strategies
+
+  def initialize(custom_strategies)
+    @strategies = {
+      host: Rage::Router::Strategies::Host.new
+    }
+
+    @strategies_in_use = Set.new
+  end
+
+  def strategy_used?(strategy_name)
+    @strategies_in_use.include?(strategy_name)
+  end
+
+  def has_constraint_strategy(strategy_name)
+    custom_constraint_strategy = @strategies[strategy_name]
+    if custom_constraint_strategy
+      return custom_constraint_strategy.custom? || strategy_used?(strategy_name)
+    end
+
+    false
+  end
+
+  def derive_constraints(env)
+  end
+
+  # When new constraints start getting used, we need to rebuild the deriver to derive them. Do so if we see novel constraints used.
+  def note_usage(constraints)
+    if constraints
+      before_size = @strategies_in_use.size
+
+      constraints.each_key do |key|
+        @strategies_in_use.add(key)
+      end
+
+      if before_size != @strategies_in_use.size
+        __build_derive_constraints
+      end
+    end
+  end
+
+  def new_store_for_constraint(constraint)
+    raise "No strategy registered for constraint key '#{constraint}'" unless @strategies[constraint]
+    @strategies[constraint].storage
+  end
+
+  def validate_constraints(constraints)
+    constraints.each do |key, value|
+      strategy = @strategies[key]
+      raise "No strategy registered for constraint key '#{key}'" unless strategy
+
+      strategy.validate(value)
+    end
+  end
+
+  # Optimization: build a fast function for deriving the constraints for all the strategies at once. We inline the definitions of the version constraint and the host constraint for performance.
+  # If no constraining strategies are in use (no routes constrain on host, or version, or any custom strategies) then we don't need to derive constraints for each route match, so don't do anything special, and just return undefined
+  # This allows us to not allocate an object to hold constraint values if no constraints are defined.
+  def __build_derive_constraints
+    return if @strategies_in_use.empty?
+
+    lines = ["{"]
+
+    @strategies_in_use.each do |key|
+      strategy = @strategies[key]
+      # Optimization: inline the derivation for the common built in constraints
+      if !strategy.custom?
+        if key == :host
+          lines << "   host: env['HTTP_HOST'.freeze],"
+        else
+          raise 'unknown non-custom strategy for compiling constraint derivation function'
+        end
+      else
+        lines << "  #{strategy.name}: @strategies[#{key}].derive_constraint(env),"
+      end
+    end
+
+    lines << "}"
+
+    instance_eval <<-RUBY
+      def derive_constraints(env)
+        #{lines.join("\n")}
+      end
+    RUBY
+  end
+end

data/lib/rage/router/dsl.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+class Rage::Router::DSL
+  def initialize(router)
+    @router = router
+  end
+
+  def draw(&block)
+    Handler.new(@router).instance_eval(&block)
+  end
+
+  class Handler
+    def initialize(router)
+      @router = router
+
+      @path_prefixes = []
+      @module_prefixes = []
+    end
+
+    # Register a new GET route.
+    #
+    # @param path [String] the path for the route handler
+    # @param to [String] the route handler in the format of "controller#action"
+    # @param constraints [Hash] a hash of constraints for the route
+    # @example
+    #   get "/photos/:id", to: "photos#show", constraints: { host: /myhost/ }
+    def get(path, to:, constraints: nil)
+      __on("GET", path, to, constraints)
+    end
+
+    # Register a new POST route.
+    #
+    # @param path [String] the path for the route handler
+    # @param to [String] the route handler in the format of "controller#action"
+    # @param constraints [Hash] a hash of constraints for the route
+    # @example
+    #   post "/photos", to: "photos#create", constraints: { host: /myhost/ }
+    def post(path, to:, constraints: nil)
+      __on("POST", path, to, constraints)
+    end
+
+    # Register a new PUT route.
+    #
+    # @param path [String] the path for the route handler
+    # @param to [String] the route handler in the format of "controller#action"
+    # @param constraints [Hash] a hash of constraints for the route
+    # @example
+    #   put "/photos/:id", to: "photos#update", constraints: { host: /myhost/ }
+    def put(path, to:, constraints: nil)
+      __on("PUT", path, to, constraints)
+    end
+
+    # Register a new PATCH route.
+    #
+    # @param path [String] the path for the route handler
+    # @param to [String] the route handler in the format of "controller#action"
+    # @param constraints [Hash] a hash of constraints for the route
+    # @example
+    #   patch "/photos/:id", to: "photos#update", constraints: { host: /myhost/ }
+    def patch(path, to:, constraints: nil)
+      __on("PATCH", path, to, constraints)
+    end
+
+    # Register a new DELETE route.
+    #
+    # @param path [String] the path for the route handler
+    # @param to [String] the route handler in the format of "controller#action"
+    # @param constraints [Hash] a hash of constraints for the route
+    # @example
+    #   delete "/photos/:id", to: "photos#destroy", constraints: { host: /myhost/ }
+    def delete(path, to:, constraints: nil)
+      __on("DELETE", path, to, constraints)
+    end
+
+    # Register a new route pointing to '/'.
+    #
+    # @param to [String] the route handler in the format of "controller#action"
+    # @example
+    #   root to: "photos#index"
+    def root(to:)
+      __on("GET", "/", to, nil)
+    end
+
+    # Scopes a set of routes to the given default options.
+    #
+    # @param [Hash] opts scope options.
+    # @option opts [String] :module module option
+    # @option opts [String] :path path option
+    # @example Route `/photos` to `Api::PhotosController`
+    #   scope module: "api" do
+    #     get "photos", to: "photos#index"
+    #   end
+    # @example Route `admin/photos` to `PhotosController`
+    #   scope path: "admin" do
+    #     get "photos", to: "photos#index"
+    #   end
+    # @example Nested calls
+    #   scope module: "admin" do
+    #     get "photos", to: "photos#index"
+    #
+    #     scope path: "api", module: "api" do
+    #       get "photos/:id", to: "photos#show"
+    #     end
+    #   end
+    def scope(opts, &block)
+      raise ArgumentError, "only 'module' and 'path' options are accepted" if (opts.keys - %i(module path)).any?
+
+      @path_prefixes << opts[:path].delete_prefix("/").delete_suffix("/") if opts[:path]
+      @module_prefixes << opts[:module] if opts[:module]
+
+      instance_eval &block
+
+      @path_prefixes.pop if opts[:path]
+      @module_prefixes.pop if opts[:module]
+    end
+
+    private
+
+    def __on(method, path, to, constraints)
+      if path != "/"
+        path = "/#{path}" unless path.start_with?("/")
+        path = path.delete_suffix("/") if path.end_with?("/")
+      end
+
+      path_prefix = @path_prefixes.any? ? "/#{@path_prefixes.join("/")}" : nil
+      module_prefix = @module_prefixes.any? ? "#{@module_prefixes.join("/")}/" : nil
+
+      if to.is_a?(String)
+        @router.on(method, "#{path_prefix}#{path}", "#{module_prefix}#{to}", constraints: constraints || {})
+      else
+        @router.on(method, "#{path_prefix}#{path}", to, constraints: constraints || {})
+      end
+    end
+  end
+end

data/lib/rage/router/handler_storage.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+class Rage::Router::HandlerStorage
+  def initialize
+    @unconstrained_handler = nil # optimized reference to the handler that will match most of the time
+    @constraints = []
+    @handlers = [] # unoptimized list of handler objects for which the fast matcher function will be compiled
+    @constrained_handler_stores = nil
+  end
+
+  # This is the hot path for node handler finding -- change with care!
+  def get_matching_handler(derived_constraints)
+    return @unconstrained_handler unless derived_constraints
+    get_handler_matching_constraints(derived_constraints)
+  end
+
+  def add_handler(constrainer, route)
+    params = route[:params]
+    constraints = route[:constraints]
+
+    handler_object = {
+      params: params,
+      constraints: constraints,
+      handler: route[:handler],
+      create_params_object: compile_create_params_object(params)
+    }
+
+    constraints_keys = constraints.keys
+    if constraints_keys.empty?
+      @unconstrained_handler = handler_object
+    end
+
+    constraints_keys.each do |constraint_key|
+      @constraints << constraint_key unless @constraints.include?(constraint_key)
+    end
+
+    if @handlers.length >= 32
+      raise "Limit reached: a maximum of 32 route handlers per node allowed when there are constraints"
+    end
+
+    @handlers << handler_object
+    # Sort the most constrained handlers to the front of the list of handlers so they are tested first.
+    @handlers.sort_by! { |a| a[:constraints].length }
+
+    compile_get_handler_matching_constraints(constrainer)
+  end
+
+  private
+
+  def compile_create_params_object(param_keys)
+    lines = []
+
+    param_keys.each_with_index do |key, i|
+      lines << "'#{key}' => param_values[#{i}]"
+    end
+
+    eval "->(param_values) { { #{lines.join(',')} } }"
+  end
+
+  def get_handler_matching_constraints(_derived_constraints)
+  end
+
+  # Builds a store object that maps from constraint values to a bitmap of handler indexes which pass the constraint for a value
+  # So for a host constraint, this might look like { "fastify.io": 0b0010, "google.ca": 0b0101 }, meaning the 3rd handler is constrainted to fastify.io, and the 2nd and 4th handlers are constrained to google.ca.
+  # The store's implementation comes from the strategies provided to the Router.
+  def build_constraint_store(store, constraint)
+    @handlers.each_with_index do |handler, i|
+      constraint_value = handler[:constraints][constraint]
+      if constraint_value
+        indexes = store.get(constraint_value) || 0
+        indexes |= 1 << i # set the i-th bit for the mask because this handler is constrained by this value https://stackoverflow.com/questions/1436438/how-do-you-set-clear-and-toggle-a-single-bit-in-javascrip
+        store.set(constraint_value, indexes)
+      end
+    end
+  end
+
+  # Builds a bitmask for a given constraint that has a bit for each handler index that is 0 when that handler *is* constrained and 1 when the handler *isnt* constrainted. This is opposite to what might be obvious, but is just for convienience when doing the bitwise operations.
+  def constrained_index_bitmask(constraint)
+    mask = 0
+
+    @handlers.each_with_index do |handler, i|
+      constraint_value = handler[:constraints][constraint]
+      mask |= 1 << i if constraint_value
+    end
+
+    ~mask
+  end
+
+  # Compile a fast function to match the handlers for this node
+  # The function implements a general case multi-constraint matching algorithm.
+  # The general idea is this: we have a bunch of handlers, each with a potentially different set of constraints, and sometimes none at all. We're given a list of constraint values and we have to use the constraint-value-comparison strategies to see which handlers match the constraint values passed in.
+  # We do this by asking each constraint store which handler indexes match the given constraint value for each store. Trickily, the handlers that a store says match are the handlers constrained by that store, but handlers that aren't constrained at all by that store could still match just fine. So, each constraint store can only describe matches for it, and it won't have any bearing on the handlers it doesn't care about. For this reason, we have to ask each stores which handlers match and track which have been matched (or not cared about) by all of them.
+  # We use bitmaps to represent these lists of matches so we can use bitwise operations to implement this efficiently. Bitmaps are cheap to allocate, let us implement this masking behaviour in one CPU instruction, and are quite compact in memory. We start with a bitmap set to all 1s representing every handler that is a match candidate, and then for each constraint, see which handlers match using the store, and then mask the result by the mask of handlers that that store applies to, and bitwise AND with the candidate list. Phew.
+  # We consider all this compiling function complexity to be worth it, because the naive implementation that just loops over the handlers asking which stores match is quite a bit slower.
+  def compile_get_handler_matching_constraints(constrainer)
+    @constrained_handler_stores = {}
+
+    @constraints.each do |constraint|
+      store = constrainer.new_store_for_constraint(constraint)
+      @constrained_handler_stores[constraint] = store
+
+      build_constraint_store(store, constraint)
+    end
+
+    lines = []
+    lines << <<-RUBY
+      candidates = #{(1 << @handlers.length) - 1}
+      mask, matches = nil
+    RUBY
+
+    @constraints.each do |constraint|
+      # Setup the mask for indexes this constraint applies to. The mask bits are set to 1 for each position if the constraint applies.
+      lines << <<-RUBY
+        mask = #{constrained_index_bitmask(constraint)}
+        value = derived_constraints[:#{constraint}]
+      RUBY
+
+      # If there's no constraint value, none of the handlers constrained by this constraint can match. Remove them from the candidates.
+      # If there is a constraint value, get the matching indexes bitmap from the store, and mask it down to only the indexes this constraint applies to, and then bitwise and with the candidates list to leave only matching candidates left.
+      strategy = constrainer.strategies[constraint]
+      match_mask = strategy.must_match_when_derived ? "matches" : "(matches | mask)"
+
+      lines.push << <<-RUBY
+        if !value
+          candidates &= mask
+        else
+          matches = @constrained_handler_stores[:#{constraint}].get(value) || 0
+          candidates &= #{match_mask}
+        end
+
+        return nil if candidates == 0
+      RUBY
+    end
+
+    # There are some constraints that can be derived and marked as "must match", where if they are derived, they only match routes that actually have a constraint on the value, like the SemVer version constraint.
+    # An example: a request comes in for version 1.x, and this node has a handler that matches the path, but there's no version constraint. For SemVer, the find-my-way semantics do not match this handler to that request.
+    # This function is used by Nodes with handlers to match when they don't have any constrained routes to exclude request that do have must match derived constraints present.
+    constrainer.strategies.each do |constraint, strategy|
+      if strategy.must_match_when_derived && !@constraints.include?(constraint)
+        lines << "return nil if derived_constraints[:#{constraint}]"
+      end
+    end
+
+    # Return the first handler whose bit is set in the candidates https://stackoverflow.com/questions/18134985/how-to-find-index-of-first-set-bit
+    lines << "return @handlers[Math.log2(candidates).floor]"
+
+    instance_eval <<-RUBY
+      def get_handler_matching_constraints(derived_constraints)
+        #{lines.join("\n")}
+      end
+    RUBY
+  end
+end