rutter 0.1.0

data/lib/rutter/builder.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+require "rack"
+
+require_relative "route"
+require_relative "scope"
+
+module Rutter
+  # The router redirect incoming requests to defined endpoints. Most often
+  # it's to a controller and an action or a Rack endpoint.
+  #
+  # @attr_reader [Array<Rutter::Route>] flat_map
+  #   Defined routes.
+  # @attr_reader [Hash<String => Array>] verb_map
+  #   Routes group by verb.
+  # @attr_reader [Hash<Symbol => Rutter::Route>] named_map
+  #   Named routes.
+  #
+  # @example basic usage
+  #   Rutter.new do
+  #     get "/", to: ->(env) {}
+  #     post "/", to: ->(env) {}
+  #     put "/", to: ->(env) {}
+  #     patch "/", to: ->(env) {}
+  #     delete "/", to: ->(env) {}
+  #     options "/", to: ->(env) {}
+  #     head "/", to: ->(env) {}
+  #     trace "/", to: ->(env) {}
+  #   end.freeze
+  class Builder
+    attr_reader :flat_map, :verb_map, :named_map
+
+    # Initializes the router.
+    #
+    # @param [String] scheme
+    #   URL scheme.
+    # @param [String] host
+    #   URL host.
+    # @param [Integer] port
+    #   URL port.
+    # @param [String] controller_suffix
+    #   Suffix string for controllers (BooksController).
+    #
+    # @yield
+    #   Block is run inside the created `Builder` context.
+    #
+    # @return [self]
+    def initialize(
+      scheme: "http",
+      host: "example.com",
+      port: 80,
+      controller_suffix: nil,
+      &block
+    )
+      @scheme = scheme
+      @host = host
+      @port = port
+      @controller_suffix = controller_suffix
+      @flat_map = []
+      @verb_map = Hash.new { |hash, key| hash[key] = [] }
+      @named_map = {}
+
+      instance_eval(&block) if block_given?
+    end
+
+    # Mount a Rack application at the specified path.
+    #
+    # @param [Class, Object] app
+    #   A class or an object that responds to `call`.
+    # @param [String] at
+    #   Path prefix to match.
+    #
+    # @return [void]
+    def mount(app, at:)
+      Route::VERBS.each { |verb| add verb, "#{at}*_", to: app }
+    end
+
+    # Convenient method to create a redirect endpoint.
+    #
+    # @param [String] destination
+    #   The destination.
+    # @param [Integer] status
+    #   Response status code.
+    #
+    # @return [Proc]
+    #   Redirect endpoint.
+    #
+    # @example basic usage
+    #   Rutter.new do
+    #     get "/legacy-path", to: redirect("/new_path")
+    #   end
+    #
+    # @example with custom status
+    #   Rutter.new do
+    #     get "/legacy-path", to: redirect("/new_path", status: 301)
+    #   end
+    def redirect(destination, status: 302)
+      ->(_env) { [status, { "Location" => destination.to_s }, []] }
+    end
+
+    # Defines a root route (a GET route for '/').
+    #
+    # @return [Rutter::Route]
+    #
+    # @see Rutter::Builder#add
+    def root(**opts)
+      get "/", **opts.merge(as: :root)
+    end
+
+    # Adds a new route to the collection.
+    #
+    # @param [String, Symbol] method
+    #   Request method.
+    # @param [String] path
+    #   Path template.
+    # @param [String, Symbol] as
+    #   Route identifier (name).
+    # @param [String, Proc] to
+    #   Route endpoint.
+    #
+    # @return [Rutter::Route]
+    def add(method, path, to:, as: nil)
+      route = Route.new(method, path, to, controller_suffix: @controller_suffix)
+
+      flat_map << route
+      verb_map[route.method] << route
+
+      return route unless as
+
+      add_named_route!(as, route)
+    end
+
+    # @see Rutter::Builder#add
+    Route::VERBS.each do |verb|
+      define_method verb.downcase do |path, to:, **opts|
+        add verb, path, to: to, **opts
+      end
+    end
+
+    # Starts a scoped collection of routes.
+    #
+    # @option opts [String] :path (nil)
+    #   Path prefix
+    # @option opts [String] :namespace (nil)
+    #   Namespace prefix
+    # @option opts [String, Symbol] :as (nil)
+    #   Name prefix
+    # @yield
+    #   Scope context.
+    #
+    # @return [Rutter::Scope]
+    #
+    # @example
+    #   Rutter.new do
+    #     scope path: "animals", namespace: "Species", as: "animals" do
+    #       scope path: "mammals", namespace: "Mammals", as: "mammals" do
+    #         get "/cats", to: "Cats#index", as: :cats
+    #       end
+    #     end
+    #   end
+    #
+    # @example with subdomain
+    #   Rutter.new do
+    #     scope path: "v1", namespace: "Api::V1", subdomain: "api" do
+    #       get "/books", to: "Books#index"
+    #     end
+    #   end
+    def scope(**opts, &block)
+      Scope.new(self, **opts, &block)
+    end
+
+    # Transforms a named route into a URL path.
+    #
+    # @param [Symbol] name
+    #   Name of the route.
+    # @param [Hash] params
+    #   Route paremeters.
+    #
+    # @return [String]
+    #
+    # @raise [ArgumentError]
+    #   if route not found.
+    def path(name, params = {})
+      route = named_map[name]
+
+      raise ArgumentError, "no route called '#{name}'" unless route
+
+      path = route.expand(params)
+      path = path.gsub(%r{\A[\/]+|[\/]+\z}, "")
+      "/#{path}"
+    end
+
+    # Transforms a named route into a full URL with scheme and host.
+    #
+    # @param [Symbol] name
+    #   Name of the route.
+    # @option params [String] :_scheme (configuration.scheme)
+    #   Override scheme.
+    # @option params [String] :_host (configuration.host)
+    #   Override host.
+    # @option params [String] :_subdomain (nil)
+    #   Set a specific subdomain for the URL.
+    # @option params [Symbol] :_port (configuration.port)
+    #   Override port. The port will only be visible unless it's set to `80`
+    #   or `443`.
+    #
+    # @return [String]
+    #
+    # @raise [ArgumentError]
+    #   If route not found.
+    def url(name, params = {})
+      scheme = params.delete(:_scheme) || @scheme
+      host = params.delete(:_host) || @host
+      port = (params.delete(:_port) || @port).to_i
+      host = "#{host}:#{port}" unless [80, 443].include?(port)
+      subdomain = params.delete(:_subdomain)
+      host = "#{subdomain}.#{host}" if subdomain
+      "#{scheme}://#{host}#{path(name, params)}"
+    end
+
+    # Process the request and is compatible with the Rack protocol.
+    #
+    # @param [Hash] env
+    #   Rack environment hash.
+    #
+    # @return [Array]
+    #   Serialized Rack response.
+    #
+    # @see http://rack.github.io
+    #
+    # @private
+    def call(env)
+      if (route = match(env))
+        env["rutter.action"] = route.endpoint[:action]
+        env["rutter.params"] = route.params(env["PATH_INFO"])
+        ctrl = route.endpoint[:controller]
+        ctrl = Object.const_get(ctrl) if ctrl.is_a?(String)
+        return ctrl.call(env)
+      end
+
+      NOT_FOUND_RESPONSE
+    end
+
+    # Freezes the router and its routes.
+    #
+    # @return [self]
+    def freeze
+      flat_map.freeze
+      verb_map.freeze
+      named_map.freeze
+
+      super
+    end
+
+    private
+
+    # Matches the incoming request with the routes.
+    #
+    # @param env [Hash] Rack's environment hash.
+    #
+    # @return [Rutter::Route, false]
+    #
+    # @private
+    def match(env)
+      path = env["PATH_INFO"].downcase
+      path = path.chomp("/") if path != "/" && path.end_with?("/")
+
+      routes = verb_map[env["REQUEST_METHOD"]]
+      routes.each do |route|
+        return route if route.match?(path)
+      end
+
+      false
+    end
+
+    # @private
+    def add_named_route!(name, route)
+      name = normalize_route_name(name)
+
+      if named_map.key?(name)
+        raise "a route called '#{name}' has already been defined"
+      end
+
+      named_map[name] = route
+    end
+
+    # @private
+    def normalize_route_name(name)
+      name.to_s
+          .tr("/", "_")
+          .gsub(/[_]{2,}/, "_")
+          .gsub(/\A_|_\z/, "")
+          .downcase
+          .to_sym
+    end
+
+    # Response returned when no route matched the request.
+    #
+    # @private
+    NOT_FOUND_RESPONSE = [
+      404,
+      { "X-Cascade" => "pass" },
+      ["Route Not Found"]
+    ].freeze
+  end
+end

data/lib/rutter/route.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Rutter
+  # Represents a single route.
+  #
+  # @attr_reader [String] method
+  #   Request method to match.
+  # @attr_reader [String] path
+  #   Path to match.
+  # @attr_reader [Hash] endpoint
+  #   Route endpoint.
+  class Route
+    # Valid request verbs.
+    VERBS = %w[GET POST PUT PATCH DELETE OPTIONS HEAD TRACE].freeze
+
+    attr_reader :method, :path, :endpoint
+
+    # Initializes the route.
+    #
+    # @param [Symbol, String] method
+    #   Requets method to match.
+    # @param [String] path
+    #   Path template.
+    # @param [String, Proc, Hash] endpoint
+    #    Route endpoint.
+    # @param [String, false] controller_suffix
+    #   Suffix for string controllers.
+    #
+    # @return [self]
+    #
+    # @raise [ArgumentError]
+    #   If request method is unknown.
+    #
+    # @private
+    def initialize(method, path, endpoint, controller_suffix: nil)
+      @method = method.to_s.upcase
+
+      unless VERBS.include?(method)
+        raise ArgumentError, "invalid verb: '#{method}'"
+      end
+
+      @controller_suffix = controller_suffix || ""
+      @path = normalize_path(path)
+      @dynamic = false
+      @pattern = path_to_pattern(@path).freeze
+      @endpoint = build_endpoint_hash(endpoint).freeze
+
+      freeze
+    end
+
+    # Matches the given path to the route pattern.
+    #
+    # @param [String] path_info
+    #   Requested path to match against.
+    #
+    # @return [Boolean]
+    def match?(path_info)
+      @dynamic ? path_info.match?(@pattern) : path_info == @path
+    end
+
+    # Extract params from the given path.
+    #
+    # NOTE: If the path does not match, `nil` is returned.
+    #
+    # @param [String] path
+    #   Requested path to extract params from.
+    #
+    # @return [nil, Hash<String => String>]
+    def params(path)
+      return unless (result = path.match(@pattern))
+      values = result.captures.map { |v| CGI.unescape(v) if v }
+      Hash[result.names.zip(values)]
+    end
+
+    # Expands the pattern with the given arguments.
+    #
+    # @param [Hash] params
+    #   Expand parameters.
+    #
+    # @return [String] Expanded string.
+    #
+    # @example basic example
+    #   route = Route.new("GET", "/books/:id/:title", -> {})
+    #
+    #   route.expand(id: 54, title: "eloquent-ruby")
+    #     # => "/books/54/eloquent-ruby"
+    #
+    # @example with query
+    #   route = Route.new("GET", "/books/:id/reviews", -> {})
+    #
+    #   route.expand(id: 54, status: "approved")
+    #     # => "/books/54/reviews?status=approved"
+    def expand(params = {})
+      string = if @dynamic
+        new_path = path.gsub(SEGMENT_MATCH) do |match|
+          params.delete(match[1..-1].to_sym)
+        end
+        new_path.gsub(/\(|\)/, "")
+      else
+        path.dup
+      end
+
+      string = normalize_path(string)
+      return string if params.empty?
+
+      "#{string}?#{Rack::Utils.build_nested_query(params)}"
+    end
+
+    private
+
+    # Segment for dynamic parts.
+    #
+    # @private
+    DYNAMIC_SEGMENT = "[^/.,;?]+"
+
+    # Segment for wildcards.
+    #
+    # @private
+    WILDCARD_SEGMENT = ".*"
+
+    # Match segment regexp.
+    #
+    # @private
+    SEGMENT_MATCH = /((:|\*)[\w]+)/
+
+    # @private
+    def path_to_pattern(path)
+      pattern = path.dup
+
+      if pattern.include?("(")
+        @dynamic = true
+        pattern = pattern.gsub("(", "(?:").gsub(")", ")?")
+      end
+
+      pattern = pattern.gsub(SEGMENT_MATCH) do |match|
+        @dynamic = true
+        segment = match[0] == ":" ? DYNAMIC_SEGMENT : WILDCARD_SEGMENT
+        "(?<#{match[1..-1]}>#{segment})"
+      end
+
+      /\A#{pattern}\z/
+    end
+
+    # @private
+    def normalize_path(path)
+      path = path.gsub(%r{[\/]{2,}}, "/")
+                 .gsub(%r{\A[\/]+|[\/]+\z}, "")
+                 .downcase
+
+      "/#{path}"
+    end
+
+    # @private
+    def build_endpoint_hash(endpoint)
+      if endpoint.is_a?(String)
+        ctrl, action = endpoint.gsub(/[:]{3,}/, "::")
+                               .gsub(/\A[:]+|[:]+\z/, "")
+                               .split("#")
+
+        { controller: "#{ctrl}#{@controller_suffix}", action: action }
+      else
+        { controller: endpoint, action: nil }
+      end
+    end
+  end
+end

data/lib/rutter/routes.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Rutter
+  # Routes helper.
+  class Routes
+    extend Forwardable
+
+    # Delegate path and url method to the builder.
+    #
+    # @see Rutter::Builder#path
+    # @see Rutter::Builder#url
+    def_delegators :@builder, :path, :url
+
+    # Initializes the helper.
+    #
+    # @param [Rutter::Builder] builder
+    #   Route builder object.
+    #
+    # @return [self]
+    def initialize(builder)
+      @builder = builder
+    end
+
+    protected
+
+    # @private
+    def method_missing(method, *args)
+      named_route, type = method.to_s.split(/\_(path|url)\z/)
+      return super unless type
+      @builder.public_send(type, named_route.to_sym, *args)
+    end
+  end
+end

data/lib/rutter/scope.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Rutter
+  # Scoped set of routes.
+  class Scope
+    # Initializes the scope.
+    #
+    # @param [Rutter::Builder] router
+    #   Root router object.
+    # @option opts [String] :path (nil)
+    #   Path prefix
+    # @option opts [String] :namespace (nil)
+    #   Namespace prefix
+    # @option opts [String, Symbol] :as (nil)
+    #   Name prefix
+    # @yield
+    #   Scope context.
+    #
+    # @return [self]
+    #
+    # @private
+    def initialize(router, **opts, &block)
+      @router = router
+      @path_prefix = opts[:path]
+      @namespace_prefix = opts[:namespace]
+      @name_prefix = opts[:as]
+
+      instance_eval(&block) if block_given?
+    end
+
+    # @see Rutter::Builder#scope
+    def scope(**opts, &block)
+      opts[:as] = "#{@name_prefix}_#{opts[:as]}" if @name_prefix
+      opts[:path] = "#{@path_prefix}/#{opts[:path]}" if @path_prefix
+
+      if @namespace_prefix
+        opts[:namespace] = "#{@namespace_prefix}::#{opts[:namespace]}"
+      end
+
+      Scope.new(@router, **opts, &block)
+    end
+
+    # @see Rutter::Builder#mount
+    def mount(app, at:, **opts)
+      at = "#{@path_prefix}/#{at}" if @path_prefix
+      @router.mount app, at: at, **opts
+    end
+
+    # @see Rutter::Builder#root
+    def root(to:, as: :root)
+      get "/", to: to, as: as
+    end
+
+    # @see Rutter::Builder#add
+    Route::VERBS.each do |verb|
+      verb_method = verb.downcase
+      define_method verb_method do |path, **opts|
+        path = "#{@path_prefix}/#{path}" if @path_prefix
+        opts[:as] = "#{@name_prefix}_#{opts[:as]}" if opts[:as]
+        if @namespace_prefix && opts[:to].is_a?(String)
+          opts[:to] = "#{@namespace_prefix}::#{opts[:to]}"
+        end
+
+        @router.public_send verb_method, path, **opts
+      end
+    end
+  end
+end

data/lib/rutter/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Rutter
+  # Current version number.
+  VERSION = "0.1.0"
+end

data/lib/rutter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "rutter/version"
+require_relative "rutter/builder"
+require_relative "rutter/routes"
+
+# HTTP router for Ramverk and Rack.
+module Rutter
+  # Creates a new builder object.
+  #
+  # @return [Rutter::Builder]
+  #
+  # @see Rutter::Builder
+  def self.new(**opts, &block)
+    Builder.new(**opts, &block)
+  end
+end

data/rutter.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require File.expand_path("../lib/rutter/version", __FILE__)
+
+Gem::Specification.new do |spec|
+  spec.name = "rutter"
+  spec.version = Rutter::VERSION
+  spec.summary = "HTTP router for Rack."
+
+  spec.required_ruby_version = ">= 2.4.0"
+  spec.required_rubygems_version = ">= 2.5.0"
+
+  spec.license = "MIT"
+
+  spec.author = "Tobias Sandelius"
+  spec.email = "tobias@sandeli.us"
+  spec.homepage = "https://github.com/sandelius/rutter"
+
+  spec.files = `git ls-files -z`.split("\x0")
+  spec.test_files = spec.files.grep(%r{^(spec)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rack", "~> 2.0"
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "mocha"
+  spec.add_development_dependency "rack-test"
+end

data/spec/integration/mount_spec.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+describe "Rutter::Builder#mount" do
+  let(:router) do
+    Rutter.new do
+      mount ->(_env) { [200, {}, ["Admin App"]] }, at: "/admin"
+    end
+  end
+
+  def app
+    router.freeze
+  end
+
+  it "forwards the request to the given application" do
+    get "/admin/with/sub/paths"
+    assert_equal "Admin App", last_response.body
+  end
+end

data/spec/integration/params_spec.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "json"
+require "spec_helper"
+
+class TestController
+  def self.call(env)
+    hash = env["rutter.params"]
+    hash["action"] = env["rutter.action"]
+    [100, {}, [JSON.generate(hash)]]
+  end
+end
+
+describe "ramverk.router_params" do
+  let(:router) { Rutter.new(controller_suffix: "Controller") }
+
+  def app
+    router.freeze
+  end
+
+  it "calls the endpoint (controller)" do
+    router.get "/books/:title", to: "Test#index"
+    get "/books/eloquent-ruby"
+    assert_equal 100, last_response.status
+    assert_equal '{"title":"eloquent-ruby","action":"index"}',
+                 last_response.body
+  end
+end