Awesome
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