Toro

Tree Oriented Routing

Usage

Here's a hello world app that you can copy and paste to get a sense of how Toro works:

require "toro"

class App < Toro::Router
  def routes
    get do
      text "hello world"
    end
  end
end

App.run do |server|
  server.listen "0.0.0.0", 8080
end

Save it to a file called hello_world.cr and run it with crystal run hello_world.cr. Then access your hello world application with your browser, or simply by calling curl http://localhost:8080/ from the command line.

What follows is an example that showcases some basic routing features:

require "toro"

class App < Toro::Router

  # You must define the `routes` methods. It will be the
  # entry point to your web application.
  def routes

    # The `get` matcher will execute the block when two conditions
    # are met: the `REQUEST_METHOD` is equal to "GET", and there are
    # no more path segments to match. In this case, as we haven't
    # consumed any path segment, the only way for this block to run
    # would be to have a "GET" request to "/". Check the API section
    # to see all available matchers.
    get do

      # The text method sets the Content-Type to "text/plain", and
      # prints the string to the response.
      text "hello world"
    end

    # A `String` matcher will run the block only if its content is equal
    # to the next segment in the current path. In this example, it will
    # match the request if the first segment is equal to "users".
    # You can always inspect the current path by looking at `path.curr`.
    on "users" do

      # If we get here it's because the previous matcher succeeded. It
      # means we were able to consume a segment off the current path. More
      # specifically, we consumed the "users" segment, and if we now
      # inspect the `path.prev` string we will find its value is "/users".
      #
      # With the next matcher we want to capture a segment. Let's say a
      # request is made to "/users/42". When we arrive at this point, this
      # symbol will match the number "42" and store it in the inbox.
      on :id do

        # If there are no more segments in the request path and if the
        # request method is "GET", this block will run.
        get do

          # Now, `inbox[:id]` has the value "42". The templates have access
          # to the inbox and to any other variables defined here.
          #
          # The `html` macro expects a path to a template. It automatically
          # appends the `.ecr` extension, which stands for Embedded Crystal
          # and is part of the standard library. It also sets the content
          # type to "text/html". For the html example to work, you need to
          # create the file ./views/users/show.ecr with the following content:
          #
          #   hello user <%= inbox[:id] %>
          #
          #
          # Once you have created the file, uncomment the line below.
          #
          # html "views/users/show"


          # As a placeholder, the following directive renders the same message
          # as plain text. Once you have the HTML template in place, you can
          # comment or remove both this comment and the `text` directive.
          #
          text "hello user #{inbox[:id]}"
        end
      end
    end

    # The `default` matcher always succeeds, but it doesn't mean the program's
    # flow will always reach this point. Once a matcher succeeds and runs a
    # block, the control is never returned. There's an implicit return at the
    # end of every block, which stops the processing of the request and
    # returns the response immediately.
    #
    # This route will match all the requests that don't have "users" as the
    # first segment (because of the previous matcher), and it will pass the
    # control to the `Guests` application, which has to be an instance of
    # `Toro::Router`. This illustrates how you can compose your applications
    # and split the logic among different routers.
    default do
      mount Guests
    end
  end
end

# This is another Toro application. You can mount apps on top of other Toro
# in order to achieve a modular design.
class Guests < Toro::Router
  def routes
    on "about" do
      get do
        text "about this site"
      end
    end
  end
end

# Start the app on port 8080.
App.run do |server|
  server.listen "0.0.0.0", 8080
end

Once you have this application running, try the requests below:

$ curl http://localhost:8080/
$ curl http://localhost:8080/about
$ curl http://localhost:8080/users/42

The routes are evaluated in a sandbox where the following methods are available: context, path, inbox, mount, basic_auth, root, root?, default, on, get, put, head, post, patch, delete, options, text, html, json, write and render.

API

context: Environment variables for the request.

path: Helper object that tracks the previous and current path.

inbox: Hash with captures and potentially other variables local to the request.

mount: Mounts a sub app.

basic_auth: Yields a username and password from the Authorization header, and returns whatever the block returns or nil.

root?: Returns true if the path yet to be consumed is empty.

root: Receives a block and calls it only if root? is true.

default: Receives a block that will be executed inconditionally.

on: Receives a value to be matched, and a block that will be executed only if the request is matched.

get: Receives a block and calls it only if root? and get? are true.

put: Receives a block and calls it only if root? and put? are true.

head: Receives a block and calls it only if root? and head? are true.

post: Receives a block and calls it only if root? and post? are true.

patch: Receives a block and calls it only if root? and patch? are true.

delete: Receives a block and calls it only if root? and delete? are true.

options: Receives a block and calls it only if root? and options? are true.

Matchers

The on method can receive a String to perform path matches; a Symbol to perform path captures; and a boolean to match any true values.

Each time on matches or captures a segment of the PATH, that part of the path is consumed. The current and previous paths can be queried by calling prev and curr on the path object: path.prev returns the part of the path already consumed, and path.curr provides the current version of the path. Any expression that evaluates to a boolean can also be used as a matcher.

Captures

When a symbol is provided, on will try to consume a segment of the path. A segment is defined as any sequence of characters after a slash and until either another slash or the end of the string. The captured value is stored in the inbox hash under the key that was provided as the argument to on. For example, after a call to on(:user_id), the value for the segment will be stored at inbox[:user_id].

Security

There are no security features built into this routing library. A framework using this library should implement the security layer.

Rendering

The most basic way of returning a string is by calling the method text. It sets the Content-Type header to text/plain and writes the passed string to the response. A similar helper is called html: it takes as an argument the path to an ECR template and renders its content. A lower level render macro is available: it also expects the path to a template, but it doesn't modify the headers. There's a json helper method expecting a Crystal generic Object. It will call the to_json serializer on the generic object. Please note that you need to require JSON from the standard library in order to use this helper (adding require "json" to your app should suffice). The lower level write method writes a string to the response object. It is used internally by text and json.

Running the server

If App is an instance of Toro, then you can start the server by calling App.run. It yields an instance of HTTP://Server that you can configure:

For example, you can start the server on port 80:

App.run do |server|
  server.listen "0.0.0.0", 80
end

The following example shows how to configure SSL certificates:

App.run do |server|
  ssl = OpenSSL::SSL::Context::Server.new
  ssl.private_key = "path/to/private_key"
  ssl.certificate_chain = "path/to/certificate_chain"
  server.tls = ssl
  server.listen "0.0.0.0", 443
end

Refer to Crystal's documentation for more options.

Status codes

The default status code is 404. It can be changed and queried with the status method:

  status
  #=> 404

  status 200

  status
  #=> 200

When a request method matcher succeeds, the status code for the request is changed to 200.

Basic Auth

The basic_auth method checks the Authentication header and, if present, yields to the block the values for username and password.

Here's an example of how you can use it:

class A < Toro::Router
  def users(user : User)
    get do
      text "Hello #{user.name}"
    end
  end

  def users(user : Nil)
    get do
      text "Hello guest!"
    end
  end

  def routes
    user = basic_auth do |name, pass|
      User.authenticate(name, pass)
    end

    users(user)
  end
end

The example overloads the users method so that it can deal both with instances of User and with nil. The flow of your router will naturally continue in one of those methods. You are free to define any other methods like users in order to split the logic of your application.

To illustrate the basic_auth feature we used an imaginary User class that responds to the authenticate method and returns either an instance of User or nil.

Installation

Add this to your application's shard.yml:

dependencies:
  toro:
    github: soveran/toro
    branch: master