Class: Lotus::Router

Inherits:
Object
  • Object
show all
Defined in:
lib/lotus/router.rb,
lib/lotus/router/version.rb

Overview

Rack compatible, lightweight and fast HTTP Router.

Examples:

It offers an intuitive DSL, that supports most of the HTTP verbs:

require 'lotus/router'

endpoint = ->(env) { [200, {}, ['Welcome to Lotus::Router!']] }
router = Lotus::Router.new do
  get     '/', to: endpoint # => get and head requests
  post    '/', to: endpoint
  put     '/', to: endpoint
  patch   '/', to: endpoint
  delete  '/', to: endpoint
  options '/', to: endpoint
  trace   '/', to: endpoint
end

Specify an endpoint with ‘:to` (Rack compatible object)

require 'lotus/router'

endpoint = ->(env) { [200, {}, ['Welcome to Lotus::Router!']] }
router = Lotus::Router.new do
  get '/', to: endpoint
end

# :to is mandatory for the default resolver (`Lotus::Routing::EndpointResolver.new`),
# This behavior can be changed by passing a custom resolver to `Lotus::Router#initialize`

Specify an endpoint with ‘:to` (controller and action string)

require 'lotus/router'

router = Lotus::Router.new do
  get '/', to: 'articles#show' # => Articles::Show
end

# This is a builtin feature for a Lotus::Controller convention.

Specify a named route with ‘:as`

require 'lotus/router'

endpoint = ->(env) { [200, {}, ['Welcome to Lotus::Router!']] }
router = Lotus::Router.new(scheme: 'https', host: 'lotusrb.org') do
  get '/', to: endpoint, as: :root
end

router.path(:root) # => '/'
router.url(:root)  # => 'https://lotusrb.org/'

# This isn't mandatory for the default route class (`Lotus::Routing::Route`),
# This behavior can be changed by passing a custom route to `Lotus::Router#initialize`

Mount an application

require 'lotus/router'

router = Lotus::Router.new do
  mount Api::App, at: '/api'
end

# All the requests starting with "/api" will be forwarded to Api::App

Since:

  • 0.1.0

Defined Under Namespace

Classes: NotRoutableEndpointError

Constant Summary collapse

VERSION =

Since:

  • 0.1.0

'0.5.1'.freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}, &blk) ⇒ Lotus::Router

Initialize the router.

Examples:

Basic example

require 'lotus/router'

endpoint = ->(env) { [200, {}, ['Welcome to Lotus::Router!']] }

router = Lotus::Router.new
router.get '/', to: endpoint

# or

router = Lotus::Router.new do
  get '/', to: endpoint
end

Body parsers

require 'json'
require 'lotus/router'

# It parses JSON body and makes the attributes available to the params

endpoint = ->(env) { [200, {},[env['router.params'].inspect]] }

router = Lotus::Router.new(parsers: [:json]) do
  patch '/books/:id', to: endpoint
end

# From the shell

curl http://localhost:2300/books/1    \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"       \
  -d '{"published":"true"}'           \
  -X PATCH

# It returns

[200, {}, ["{:published=>\"true\",:id=>\"1\"}"]]

Custom body parser

require 'lotus/router'

class XmlParser
  def mime_types
    ['application/xml', 'text/xml']
  end

  # Parse body and return a Hash
  def parse(body)
    # ...
  end
end

# It parses XML body and makes the attributes available to the params

endpoint = ->(env) { [200, {},[env['router.params'].inspect]] }

router = Lotus::Router.new(parsers: [XmlParser.new]) do
  patch '/authors/:id', to: endpoint
end

# From the shell

curl http://localhost:2300/authors/1 \
  -H "Content-Type: application/xml" \
  -H "Accept: application/xml"       \
  -d '<name>LG</name>'               \
  -X PATCH

# It returns

[200, {}, ["{:name=>\"LG\",:id=>\"1\"}"]]

Parameters:

  • options (Hash) (defaults to: {}) —

    the options to initialize the router

  • blk (Proc) —

    the optional block to define the routes

Options Hash (options):

  • :scheme (String) —

    The HTTP scheme (defaults to ‘“http”`)

  • :host (String) —

    The URL host (defaults to ‘“localhost”`)

  • :port (String) —

    The URL port (defaults to ‘“80”`)

  • :resolver (Object, #resolve, #find, #action_separator) —

    the route resolver (defaults to ‘Lotus::Routing::EndpointResolver.new`)

  • :route (Object, #generate) —

    the route class (defaults to ‘Lotus::Routing::Route`)

  • :action_separator (String) —

    the separator between controller and action name (eg. ‘dashboard#show’, where ‘#’ is the :action_separator)

  • :parsers (Array<Symbol,String,Object #mime_types, parse>) —

    the body parsers for mime types

Since:

  • 0.1.0



220
221
222
223
 
# File 'lib/lotus/router.rb', line 220

def initialize(options = {}, &blk)
  @router = Routing::HttpRouter.new(options)
  define(&blk)
end

Class Method Details

.define(&blk) ⇒ Proc

Returns the given block as it is.

When Lotus::Router is used as a standalone gem and the routes are defined into a configuration file, some systems could raise an exception.

Imagine the following file into a Ruby on Rails application:

get '/', to: 'api#index'

Because Ruby on Rails in production mode use to eager load code and the routes file uses top level method calls, it crashes the application.

If we wrap these routes with Lotus::Router.define, the block doesn’t get yielded but just returned to the caller as it is.

Usually the receiver of this block is Lotus::Router#initialize, which finally evaluates the block.

Examples:

# apps/web/config/routes.rb
Lotus::Router.define do
  get '/', to: 'home#index'
end

Parameters:

  • blk (Proc) —

    a set of route definitions

Returns:

  • (Proc) —

    the given block

Since:

  • 0.5.0



123
124
125
 
# File 'lib/lotus/router.rb', line 123

def self.define(&blk)
  blk
end

Instance Method Details

#call(env) ⇒ Rack::Response, Array

Resolve the given Rack env to a registered endpoint and invoke it.

Parameters:

  • env (Hash) —

    a Rack env instance

Returns:

  • (Rack::Response, Array)

Since:

  • 0.1.0



930
931
932
 
# File 'lib/lotus/router.rb', line 930

def call(env)
  @router.call(env)
end

#define(&blk) ⇒ Lotus::Routing::Route

To support defining routes in the ‘define` wrapper.

Examples:

In Lotus framework

class Application < Lotus::Application
  configure do
    routes 'config/routes'
  end
end

# In `config/routes`

define do
  get # ...
end

Parameters:

  • blk (Proc) —

    the block to define the routes

Returns:

Since:

  • 0.2.0



259
260
261
 
# File 'lib/lotus/router.rb', line 259

def define(&blk)
  instance_eval(&blk) if block_given?
end

#defined? ⇒ TrueClass, FalseClass

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Check if there are defined routes

Examples:


router = Lotus::Router.new
router.defined? # => false

router = Lotus::Router.new { get '/', to: ->(env) { } }
router.defined? # => true

Returns:

  • (TrueClass, FalseClass) —

    the result of the check

Since:

  • 0.2.0



277
278
279
 
# File 'lib/lotus/router.rb', line 277

def defined?
  @router.routes.any?
end

#delete(path, options = {}, &blk) ⇒ Lotus::Routing::Route

Defines a route that accepts a DELETE request for the given path.

Parameters:

  • path (String) —

    the relative URL to be matched

  • options (Hash) (defaults to: {}) —

    the options to customize the route

  • blk (Proc) —

    the anonymous proc to be used as endpoint for the route

Options Hash (options):

  • :to (String, Proc, Class, Object#call) —

    the endpoint

Returns:

See Also:

Since:

  • 0.1.0



471
472
473
 
# File 'lib/lotus/router.rb', line 471

def delete(path, options = {}, &blk)
  @router.delete(path, options, &blk)
end

#get(path, options = {}, &blk) ⇒ Lotus::Routing::Route

Defines a route that accepts a GET request for the given path.

Examples:

Fixed matching string

require 'lotus/router'

router = Lotus::Router.new
router.get '/lotus', to: ->(env) { [200, {}, ['Hello from Lotus!']] }

String matching with variables

require 'lotus/router'

router = Lotus::Router.new
router.get '/flowers/:id',
  to: ->(env) {
    [
      200,
      {},
      ["Hello from Flower no. #{ env['router.params'][:id] }!"]
    ]
  }

Variables Constraints

require 'lotus/router'

router = Lotus::Router.new
router.get '/flowers/:id',
  id: /\d+/,
  to: ->(env) { [200, {}, [":id must be a number!"]] }

String matching with globbling

require 'lotus/router'

router = Lotus::Router.new
router.get '/*',
  to: ->(env) {
    [
      200,
      {},
      ["This is catch all: #{ env['router.params'].inspect }!"]
    ]
  }

String matching with optional tokens

require 'lotus/router'

router = Lotus::Router.new
router.get '/lotus(.:format)',
  to: ->(env) {
    [200, {}, ["You've requested #{ env['router.params'][:format] }!"]]
  }

Named routes

require 'lotus/router'

router = Lotus::Router.new(scheme: 'https', host: 'lotusrb.org')
router.get '/lotus',
  to: ->(env) { [200, {}, ['Hello from Lotus!']] },
  as: :lotus

router.path(:lotus) # => "/lotus"
router.url(:lotus)  # => "https://lotusrb.org/lotus"

Duck typed endpoints (Rack compatible objects)

require 'lotus/router'

router = Lotus::Router.new

router.get '/lotus',      to: ->(env) { [200, {}, ['Hello from Lotus!']] }
router.get '/middleware', to: Middleware
router.get '/rack-app',   to: RackApp.new
router.get '/method',     to: ActionControllerSubclass.action(:new)

# Everything that responds to #call is invoked as it is

Duck typed endpoints (strings)

require 'lotus/router'

class RackApp
  def call(env)
    # ...
  end
end

router = Lotus::Router.new
router.get '/lotus', to: 'rack_app' # it will map to RackApp.new

Duck typed endpoints (string: controller + action)

require 'lotus/router'

module Flowers
  class Index
    def call(env)
      # ...
    end
  end
end

 router = Lotus::Router.new
 router.get '/flowers', to: 'flowers#index'

 # It will map to Flowers::Index.new, which is the
 # Lotus::Controller convention.

Parameters:

  • path (String) —

    the relative URL to be matched

  • options (Hash) (defaults to: {}) —

    the options to customize the route

  • blk (Proc) —

    the anonymous proc to be used as endpoint for the route

Options Hash (options):

  • :to (String, Proc, Class, Object#call) —

    the endpoint

Returns:

Since:

  • 0.1.0



395
396
397
 
# File 'lib/lotus/router.rb', line 395

def get(path, options = {}, &blk)
  @router.get(path, options, &blk)
end

#inspector ⇒ Object

Returns an routes inspector

Examples:

require 'lotus/router'

router = Lotus::Router.new do
  get    '/',       to: 'home#index'
  get    '/login',  to: 'sessions#new',     as: :login
  post   '/login',  to: 'sessions#create'
  delete '/logout', to: 'sessions#destroy', as: :logout
end

puts router.inspector
  # =>        GET, HEAD  /                        Home::Index
         GET, HEAD  /login                   Sessions::New
              POST       /                   Sessions::Create
       logout GET, HEAD  /logout                  Sessions::Destroy

See Also:

Since:

  • 0.2.0



1128
1129
1130
1131
 
# File 'lib/lotus/router.rb', line 1128

def inspector
  require 'lotus/routing/routes_inspector'
  Routing::RoutesInspector.new(@router.routes)
end

#mount(app, options) ⇒ Object

Mount a Rack application at the specified path. All the requests starting with the specified path, will be forwarded to the given application.

All the other methods (eg #get) support callable objects, but they restrict the range of the acceptable HTTP verb. Mounting an application with #mount doesn’t apply this kind of restriction at the router level, but let the application to decide.

Examples:

Basic usage

require 'lotus/router'

Lotus::Router.new do
  mount Api::App.new, at: '/api'
end

# Requests:
#
# GET  /api          # => 200
# GET  /api/articles # => 200
# POST /api/articles # => 200
# GET  /api/unknown  # => 404

Difference between #get and #mount

require 'lotus/router'

Lotus::Router.new do
  get '/rack1',      to: RackOne.new
  mount RackTwo.new, at: '/rack2'
end

# Requests:
#
# # /rack1 will only accept GET
# GET  /rack1        # => 200 (RackOne.new)
# POST /rack1        # => 405
#
# # /rack2 accepts all the verbs and delegate the decision to RackTwo
# GET  /rack2        # => 200 (RackTwo.new)
# POST /rack2        # => 200 (RackTwo.new)

Types of mountable applications

require 'lotus/router'

class RackOne
  def self.call(env)
  end
end

class RackTwo
  def call(env)
  end
end

class RackThree
  def call(env)
  end
end

module Dashboard
  class Index
    def call(env)
    end
  end
end

Lotus::Router.new do
  mount RackOne,                             at: '/rack1'
  mount RackTwo,                             at: '/rack2'
  mount RackThree.new,                       at: '/rack3'
  mount ->(env) {[200, {}, ['Rack Four']]},  at: '/rack4'
  mount 'dashboard#index',                   at: '/dashboard'
end

# 1. RackOne is used as it is (class), because it respond to .call
# 2. RackTwo is initialized, because it respond to #call
# 3. RackThree is used as it is (object), because it respond to #call
# 4. That Proc is used as it is, because it respond to #call
# 5. That string is resolved as Dashboard::Index (Lotus::Controller)

Parameters:

  • app (#call) —

    a class or an object that responds to #call

  • options (Hash) —

    the options to customize the mount

Options Hash (options):

  • the (:at) —

    relative path where to mount the app

Since:

  • 0.1.1



919
920
921
 
# File 'lib/lotus/router.rb', line 919

def mount(app, options)
  @router.mount(app, options)
end

#namespace(namespace, &blk) ⇒ Lotus::Routing::Namespace

Defines a Ruby block: all the routes defined within it will be namespaced with the given relative path.

Namespaces blocks can be nested multiple times.

Examples:

Basic example

require 'lotus/router'

Lotus::Router.new do
  namespace 'trees' do
    get '/sequoia', to: endpoint # => '/trees/sequoia'
  end
end

Nested namespaces

require 'lotus/router'

Lotus::Router.new do
  namespace 'animals' do
    namespace 'mammals' do
      get '/cats', to: endpoint # => '/animals/mammals/cats'
    end
  end
end

require 'lotus/router'

router = Lotus::Router.new
router.namespace 'trees' do
  get '/sequoia', to: endpoint # => '/trees/sequoia'
end

Parameters:

  • namespace (String) —

    the relative path where the nested routes will be mounted

  • blk (Proc) —

    the block that defines the resources

Returns:

See Also:

Since:

  • 0.1.0



585
586
587
 
# File 'lib/lotus/router.rb', line 585

def namespace(namespace, &blk)
  Routing::Namespace.new(self, namespace, &blk)
end

#options(path, options = {}, &blk) ⇒ Lotus::Routing::Route

Defines a route that accepts a OPTIONS request for the given path.

Parameters:

  • path (String) —

    the relative URL to be matched

  • options (Hash) (defaults to: {}) —

    the options to customize the route

  • blk (Proc) —

    the anonymous proc to be used as endpoint for the route

Options Hash (options):

  • :to (String, Proc, Class, Object#call) —

    the endpoint

Returns:

See Also:

Since:

  • 0.1.0



509
510
511
 
# File 'lib/lotus/router.rb', line 509

def options(path, options = {}, &blk)
  @router.options(path, options, &blk)
end

#patch(path, options = {}, &blk) ⇒ Lotus::Routing::Route

Defines a route that accepts a PATCH request for the given path.

Parameters:

  • path (String) —

    the relative URL to be matched

  • options (Hash) (defaults to: {}) —

    the options to customize the route

  • blk (Proc) —

    the anonymous proc to be used as endpoint for the route

Options Hash (options):

  • :to (String, Proc, Class, Object#call) —

    the endpoint

Returns:

See Also:

Since:

  • 0.1.0



452
453
454
 
# File 'lib/lotus/router.rb', line 452

def patch(path, options = {}, &blk)
  @router.patch(path, options, &blk)
end

#path(route, *args) ⇒ String

Generate an relative URL for a specified named route. The additional arguments will be used to compose the relative URL - in

case it has tokens to match - and for compose the query string.

Examples:

require 'lotus/router'

router = Lotus::Router.new(scheme: 'https', host: 'lotusrb.org')
router.get '/login', to: 'sessions#new',    as: :login
router.get '/:name', to: 'frameworks#show', as: :framework

router.path(:login)                          # => "/login"
router.path(:login, return_to: '/dashboard') # => "/login?return_to=%2Fdashboard"
router.path(:framework, name: 'router')      # => "/router"

Parameters:

  • route (Symbol) —

    the route name

Returns:

  • (String)

Raises:

Since:

  • 0.1.0



1076
1077
1078
 
# File 'lib/lotus/router.rb', line 1076

def path(route, *args)
  @router.path(route, *args)
end

#post(path, options = {}, &blk) ⇒ Lotus::Routing::Route

Defines a route that accepts a POST request for the given path.

Parameters:

  • path (String) —

    the relative URL to be matched

  • options (Hash) (defaults to: {}) —

    the options to customize the route

  • blk (Proc) —

    the anonymous proc to be used as endpoint for the route

Options Hash (options):

  • :to (String, Proc, Class, Object#call) —

    the endpoint

Returns:

See Also:

Since:

  • 0.1.0



414
415
416
 
# File 'lib/lotus/router.rb', line 414

def post(path, options = {}, &blk)
  @router.post(path, options, &blk)
end

#put(path, options = {}, &blk) ⇒ Lotus::Routing::Route

Defines a route that accepts a PUT request for the given path.

Parameters:

  • path (String) —

    the relative URL to be matched

  • options (Hash) (defaults to: {}) —

    the options to customize the route

  • blk (Proc) —

    the anonymous proc to be used as endpoint for the route

Options Hash (options):

  • :to (String, Proc, Class, Object#call) —

    the endpoint

Returns:

See Also:

Since:

  • 0.1.0



433
434
435
 
# File 'lib/lotus/router.rb', line 433

def put(path, options = {}, &blk)
  @router.put(path, options, &blk)
end

#recognize(env, options = {}, params = nil) ⇒ Lotus::Routing::RecognizedRoute

Recognize the given env, path, or name and return a route for testing inspection.

If the route cannot be recognized, it still returns an object for testing inspection.

Examples:

Successful Path Recognition

require 'lotus/router'

router = Lotus::Router.new do
  get '/books/:id', to: 'books#show', as: :book
end

route = router.recognize('/books/23')
route.verb      # => "GET" (default)
route.routable? # => true
route.params    # => {:id=>"23"}

Successful Rack Env Recognition

require 'lotus/router'

router = Lotus::Router.new do
  get '/books/:id', to: 'books#show', as: :book
end

route = router.recognize(Rack::MockRequest.env_for('/books/23'))
route.verb      # => "GET" (default)
route.routable? # => true
route.params    # => {:id=>"23"}

Successful Named Route Recognition

require 'lotus/router'

router = Lotus::Router.new do
  get '/books/:id', to: 'books#show', as: :book
end

route = router.recognize(:book, id: 23)
route.verb      # => "GET" (default)
route.routable? # => true
route.params    # => {:id=>"23"}

Failing Recognition For Unknown Path

require 'lotus/router'

router = Lotus::Router.new do
  get '/books/:id', to: 'books#show', as: :book
end

route = router.recognize('/books')
route.verb      # => "GET" (default)
route.routable? # => false

Failing Recognition For Path With Wrong HTTP Verb

require 'lotus/router'

router = Lotus::Router.new do
  get '/books/:id', to: 'books#show', as: :book
end

route = router.recognize('/books/23', method: :post)
route.verb      # => "POST"
route.routable? # => false

Failing Recognition For Rack Env With Wrong HTTP Verb

require 'lotus/router'

router = Lotus::Router.new do
  get '/books/:id', to: 'books#show', as: :book
end

route = router.recognize(Rack::MockRequest.env_for('/books/23', method: :post))
route.verb      # => "POST"
route.routable? # => false

Failing Recognition Named Route With Wrong Params

require 'lotus/router'

router = Lotus::Router.new do
  get '/books/:id', to: 'books#show', as: :book
end

route = router.recognize(:book)
route.verb      # => "GET" (default)
route.routable? # => false

Failing Recognition Named Route With Wrong HTTP Verb

require 'lotus/router'

router = Lotus::Router.new do
  get '/books/:id', to: 'books#show', as: :book
end

route = router.recognize(:book, {method: :post}, {id: 1})
route.verb      # => "POST"
route.routable? # => false
route.params    # => {:id=>"1"}

Parameters:

  • env (Hash, String, Symbol) —

    Rack env, path or route name

  • options (Hash) (defaults to: {}) —

    a set of options for Rack env or route params

  • params (Hash) (defaults to: nil) —

    a set of params

Returns:

See Also:

Since:

  • 0.5.0



1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
 
# File 'lib/lotus/router.rb', line 1042

def recognize(env, options = {}, params = nil)
  require 'lotus/routing/recognized_route'

  env          = env_for(env, options, params)
  responses, _ = *@router.recognize(env)

  Routing::RecognizedRoute.new(
    responses.nil? ? responses : responses.first,
    env, @router)
end

#redirect(path, options = {}, &endpoint) ⇒ Lotus::Routing::Route

Defines an HTTP redirect

Examples:

require 'lotus/router'

Lotus::Router.new do
  redirect '/legacy',  to: '/new_endpoint'
  redirect '/legacy2', to: '/new_endpoint2', code: 302
end

require 'lotus/router'

router = Lotus::Router.new
router.redirect '/legacy',  to: '/new_endpoint'

Parameters:

  • path (String) —

    the path that needs to be redirected

  • options (Hash) (defaults to: {}) —

    the options to customize the redirect behavior

Options Hash (options):

  • the (Fixnum) —

    HTTP status to return (defaults to ‘301`)

Returns:

  • (Lotus::Routing::Route) —

    the generated route. This may vary according to the ‘:route` option passed to the initializer

See Also:

Since:

  • 0.1.0



539
540
541
 
# File 'lib/lotus/router.rb', line 539

def redirect(path, options = {}, &endpoint)
  get(path).redirect @router.find(options), options[:code] || 301
end

#resource(name, options = {}, &blk) ⇒ Lotus::Routing::Resource

Defines a set of named routes for a single RESTful resource. It has a built-in integration for Lotus::Controller.

Examples:

Default usage

require 'lotus/router'

Lotus::Router.new do
  resource 'identity'
end

# It generates:
#
# +--------+----------------+-------------------+----------+----------------+
# | Verb   | Path           | Action            | Name     | Named Route    |
# +--------+----------------+-------------------+----------+----------------+
# | GET    | /identity      | Identity::Show    | :show    | :identity      |
# | GET    | /identity/new  | Identity::New     | :new     | :new_identity  |
# | POST   | /identity      | Identity::Create  | :create  | :identity      |
# | GET    | /identity/edit | Identity::Edit    | :edit    | :edit_identity |
# | PATCH  | /identity      | Identity::Update  | :update  | :identity      |
# | DELETE | /identity      | Identity::Destroy | :destroy | :identity      |
# +--------+----------------+-------------------+----------+----------------+

Limit the generated routes with :only

require 'lotus/router'

Lotus::Router.new do
  resource 'identity', only: [:show, :new, :create]
end

# It generates:
#
# +--------+----------------+------------------+----------+----------------+
# | Verb   | Path           | Action           | Name     | Named Route    |
# +--------+----------------+------------------+----------+----------------+
# | GET    | /identity      | Identity::Show   | :show    | :identity      |
# | GET    | /identity/new  | Identity::New    | :new     | :new_identity  |
# | POST   | /identity      | Identity::Create | :create  | :identity      |
# +--------+----------------+------------------+----------+----------------+

Limit the generated routes with :except

require 'lotus/router'

Lotus::Router.new do
  resource 'identity', except: [:edit, :update, :destroy]
end

# It generates:
#
# +--------+----------------+------------------+----------+----------------+
# | Verb   | Path           | Action           | Name     | Named Route    |
# +--------+----------------+------------------+----------+----------------+
# | GET    | /identity      | Identity::Show   | :show    | :identity      |
# | GET    | /identity/new  | Identity::New    | :new     | :new_identity  |
# | POST   | /identity      | Identity::Create | :create  | :identity      |
# +--------+----------------+------------------+----------+----------------+

Additional single routes

require 'lotus/router'

Lotus::Router.new do
  resource 'identity', only: [] do
    member do
      patch 'activate'
    end
  end
end

# It generates:
#
# +--------+--------------------+--------------------+------+--------------------+
# | Verb   | Path               | Action             | Name | Named Route        |
# +--------+--------------------+--------------------+------+--------------------+
# | PATCH  | /identity/activate | Identity::Activate |      | :activate_identity |
# +--------+--------------------+--------------------+------+--------------------+

Additional collection routes

require 'lotus/router'

Lotus::Router.new do
  resource 'identity', only: [] do
    collection do
      get 'keys'
    end
  end
end

# It generates:
#
# +------+----------------+----------------+------+----------------+
# | Verb | Path           | Action         | Name | Named Route    |
# +------+----------------+----------------+------+----------------+
# | GET  | /identity/keys | Identity::Keys |      | :keys_identity |
# +------+----------------+----------------+------+----------------+

Parameters:

  • name (String) —

    the name of the resource

  • options (Hash) (defaults to: {}) —

    a set of options to customize the routes

  • blk (Proc) —

    a block of code to generate additional routes

Options Hash (options):

  • :only (Array<Symbol>) —

    a subset of the default routes that we want to generate

  • :except (Array<Symbol>) —

    prevent the given routes to be generated

Returns:

See Also:

Since:

  • 0.1.0



707
708
709
 
# File 'lib/lotus/router.rb', line 707

def resource(name, options = {}, &blk)
  Routing::Resource.new(self, name, options.merge(separator: @router.action_separator), &blk)
end

#resources(name, options = {}, &blk) ⇒ Lotus::Routing::Resources

Defines a set of named routes for a plural RESTful resource. It has a built-in integration for Lotus::Controller.

Examples:

Default usage

require 'lotus/router'

Lotus::Router.new do
  resources 'articles'
end

# It generates:
#
# +--------+--------------------+-------------------+----------+----------------+
# | Verb   | Path               | Action            | Name     | Named Route    |
# +--------+--------------------+-------------------+----------+----------------+
# | GET    | /articles          | Articles::Index   | :index   | :articles      |
# | GET    | /articles/:id      | Articles::Show    | :show    | :articles      |
# | GET    | /articles/new      | Articles::New     | :new     | :new_articles  |
# | POST   | /articles          | Articles::Create  | :create  | :articles      |
# | GET    | /articles/:id/edit | Articles::Edit    | :edit    | :edit_articles |
# | PATCH  | /articles/:id      | Articles::Update  | :update  | :articles      |
# | DELETE | /articles/:id      | Articles::Destroy | :destroy | :articles      |
# +--------+--------------------+-------------------+----------+----------------+

Limit the generated routes with :only

require 'lotus/router'

Lotus::Router.new do
  resources 'articles', only: [:index]
end

# It generates:
#
# +------+-----------+-----------------+--------+-------------+
# | Verb | Path      | Action          | Name   | Named Route |
# +------+-----------+-----------------+--------+-------------+
# | GET  | /articles | Articles::Index | :index | :articles   |
# +------+-----------+-----------------+--------+-------------+

Limit the generated routes with :except

require 'lotus/router'

Lotus::Router.new do
  resources 'articles', except: [:edit, :update]
end

# It generates:
#
# +--------+--------------------+-------------------+----------+----------------+
# | Verb   | Path               | Action            | Name     | Named Route    |
# +--------+--------------------+-------------------+----------+----------------+
# | GET    | /articles          | Articles::Index   | :index   | :articles      |
# | GET    | /articles/:id      | Articles::Show    | :show    | :articles      |
# | GET    | /articles/new      | Articles::New     | :new     | :new_articles  |
# | POST   | /articles          | Articles::Create  | :create  | :articles      |
# | DELETE | /articles/:id      | Articles::Destroy | :destroy | :articles      |
# +--------+--------------------+-------------------+----------+----------------+

Additional single routes

require 'lotus/router'

Lotus::Router.new do
  resources 'articles', only: [] do
    member do
      patch 'publish'
    end
  end
end

# It generates:
#
# +--------+-----------------------+-------------------+------+-------------------+
# | Verb   | Path                  | Action            | Name | Named Route       |
# +--------+-----------------------+-------------------+------+-------------------+
# | PATCH  | /articles/:id/publish | Articles::Publish |      | :publish_articles |
# +--------+-----------------------+-------------------+------+-------------------+

Additional collection routes

require 'lotus/router'

Lotus::Router.new do
  resources 'articles', only: [] do
    collection do
      get 'search'
    end
  end
end

# It generates:
#
# +------+------------------+------------------+------+------------------+
# | Verb | Path             | Action           | Name | Named Route      |
# +------+------------------+------------------+------+------------------+
# | GET  | /articles/search | Articles::Search |      | :search_articles |
# +------+------------------+------------------+------+------------------+

Parameters:

  • name (String) —

    the name of the resource

  • options (Hash) (defaults to: {}) —

    a set of options to customize the routes

  • blk (Proc) —

    a block of code to generate additional routes

Options Hash (options):

  • :only (Array<Symbol>) —

    a subset of the default routes that we want to generate

  • :except (Array<Symbol>) —

    prevent the given routes to be generated

Returns:

See Also:

Since:

  • 0.1.0



830
831
832
 
# File 'lib/lotus/router.rb', line 830

def resources(name, options = {}, &blk)
  Routing::Resources.new(self, name, options.merge(separator: @router.action_separator), &blk)
end

#routes ⇒ self

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns self

This is a duck-typing trick for compatibility with ‘Lotus::Application`. It’s used by ‘Lotus::Routing::RoutesInspector` to inspect both apps and routers.

Returns:

  • (self)

Since:

  • 0.2.0



235
236
237
 
# File 'lib/lotus/router.rb', line 235

def routes
  self
end

#trace(path, options = {}, &blk) ⇒ Lotus::Routing::Route

Defines a route that accepts a TRACE request for the given path.

Parameters:

  • path (String) —

    the relative URL to be matched

  • options (Hash) (defaults to: {}) —

    the options to customize the route

  • blk (Proc) —

    the anonymous proc to be used as endpoint for the route

Options Hash (options):

  • :to (String, Proc, Class, Object#call) —

    the endpoint

Returns:

See Also:

Since:

  • 0.1.0



490
491
492
 
# File 'lib/lotus/router.rb', line 490

def trace(path, options = {}, &blk)
  @router.trace(path, options, &blk)
end

#url(route, *args) ⇒ String

Generate a URL for a specified named route. The additional arguments will be used to compose the relative URL - in

case it has tokens to match - and for compose the query string.

Examples:

require 'lotus/router'

router = Lotus::Router.new(scheme: 'https', host: 'lotusrb.org')
router.get '/login', to: 'sessions#new', as: :login
router.get '/:name', to: 'frameworks#show', as: :framework

router.url(:login)                          # => "https://lotusrb.org/login"
router.url(:login, return_to: '/dashboard') # => "https://lotusrb.org/login?return_to=%2Fdashboard"
router.url(:framework, name: 'router')      # => "https://lotusrb.org/router"

Parameters:

  • route (Symbol) —

    the route name

Returns:

  • (String)

Raises:

Since:

  • 0.1.0



1103
1104
1105
 
# File 'lib/lotus/router.rb', line 1103

def url(route, *args)
  @router.url(route, *args)
end