SoarSc::Rack::Router

SoarSc::Rack::Router is a middleware-centric rack router. It has three key features:

• It is implemented as middleware.
• Its routing actions are rack apps (possibly supporting middleware through Rack::Builder).
• It supports parameterized URLs.

Because it is implemented as middleware, it supports fall-through. Therefore, it is possible to layer multiple routers into a single stack.

Because its routing actions are rack apps, it supports the selection of different stacks of middleware for different routes in a single router.

Because it supports parameterized URLs, it is familiar to users of several Ruby web frameworks, but also supports trivial translation of routes into WADL and other service descriptions. The parameter support is compatible with Rack::Request, without pushing a dependency on Rack::Request down into the router action API; the only requirement for router actions is that they are rack apps.

Users of Ruby web frameworks like Rails and Sinatra may be surprised that double-slashes in request paths are not normalized. In Sinatra, this is actually done by the rack-protection middleware, not sinatra-router. Users of SoarSc::Rack::Router definitely should be using the rack-protection middleware above the router in their stacks.

Installation

Add this line to your application's Gemfile:

gem 'soar_sc-rack-router'

And then execute:

$ bundle

Or install it yourself as:

$ gem install soar_sc-rack-router

Usage

The following are not examples of sensible ways to structure your router actions. They just demonstrate the SoarSc::Rack::Router API.

An example of a multi-router stack:

require 'soar_sc/rack/router'

stack = Rack::Builder.new do
  use SoarSc::Rack::Router do
    map "/", ->(env) { ... }
  end

  use Authentication

  use SoarSc::Rack::Router do
    get "/business/:id", ->(env) { ... }
    post "/business", ->(env) { ... }
  end

  run ->(env) { [404, {'Content-Type' => 'text/plain'}, ['Object Not Found']] }
end

run stack

An example of stacked routing actions under a single router:

require 'soar_sc/rack/router'

stack = Rack::Builder.new do
  use SoarSc::Rack::Router do
    map "/", ->(env) { ... }
    get "/business/:id", Rack::Builder.new do
      use Authentication
      run ->(...)
    end
    post "/business", Rack::Builder.new do
      use Authentication
      use Auditing
      run ->(...)
    end
  end

  run ->(env) { [404, {'Content-Type' => 'text/plain'}, ['Object Not Found']] }
end

run stack

An example of parameterized URL support:

require 'soar_sc/rack/router'

stack = Rack::Builder.new do
  use SoarSc::Rack::Router do
    get "/product/:id", ->(env) {
      id = Rack::Request.new(env).params["id"]
      ...
    }
    end
  end

  run ->(env) { [404, {'Content-Type' => 'text/plain'}, ['Object Not Found']] }
end

run stack

Note that, even though the router doesn't break the rack stack by demanding that routing actions receive a Rack::Request, it's recommended that routing actions use Rack::Request internally to retrieve path parameters. The router adds them to rack's env using Rack::Request#update_param, making Rack::Request#params the safest way to retrieve them.

Finally, here is a demonstration that doesn't use Rack::Builder, just to clarify that it's not a dependency:

require 'soar_sc/rack/router'

index = ->(env) { ... }
about = ->(env) { ... }
contact = ->(env) { ...]

run SoarSc::Rack::Router.new(index) do
  get "/about", about
  get "/contact", contact
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/hetznerZA/soar_sc-rack-router.

License

The gem is available as open source under the terms of the MIT License.