Pipelines

A pipeline is a set of of transformations that is performed to a HTTP request. These transformations come in the form of a pipe. A pipe is a class which includes HTTP::Handler and implements the #call method.

You can use a handler to intercept any incoming request and modify the response. These can be used for request throttling, ip-based whitelisting, adding custom headers.

Every Amber application needs to define a pipeline with a set of pipes each pipeline allow a set of transformations to be applied to different sets of route, this give you granular control and explicitness of which transformation to run for each of the requests.

Amber::Server.configure do |app|
pipeline :web do
# Plug is the method to use connect a pipe (middleware)
# A plug accepts an instance of HTTP::Handler
# plug Amber::Pipe::Params.new
plug Amber::Pipe::Logger.new
plug Amber::Pipe::Flash.new
plug Amber::Pipe::Session.new
plug Amber::Pipe::CSRF.new
end
# All static content will run these transformations
pipeline :static do
plug HTTP::StaticFileHandler.new("./public")
plug HTTP::CompressHandler.new
end
routes :static do
# Each route is defined as follow
# Verb resource : String, controller : Symbol, action : Symbol
get "/*", StaticController, :index
end
routes :web do
get "/", HomeController, :static
end
end

Above we define a pipeline called :web as you can see the :web pipeline transforms the request using a Logger, StaticFileHandler and a CompressHandler, all of which extends from the Crystal HTTP::Handler class.

Amber provides us some default pipes for a number of common tasks. In turn we can customize them as well as create new pipelines to meet our needs.

  • Pipe::Static serves static assets

  • Pipe::Logger logs incoming requests

  • Pipe::CORS Handler adds support for Cross Origin Resource Sharing.

  • Pipe::CSRF Handler adds support for Cross Site Request Forgery.

  • Pipe::Error Handler catches RouteNotFound and returns.

  • Pipe::Flash handler provides a mechanism to pass flash message between

  • Pipe::Session a plug that sets up session management.

With our :web pipeline now define we can use it in our routes definitions.

Don't get rid of StaticController if you need to serve static assets.

Sharing Pipelines

If you have two pipelines that share a lot of the same pipes, you can assign the shared pipes in one block: pipeline :web, :auth do ... end

Full example for config/routes.cr:

Amber::Server.configure do |app|
pipeline :web, :auth do
plug Amber::Pipe::Logger.new
plug Amber::Pipe::Flash.new
plug Amber::Pipe::Session.new
plug Amber::Pipe::CSRF.new
end
pipeline :auth do
plug Authenticate.new
end
routes :web do
get "/", HomeController, :static
end
routes :auth do
get "/admin", AdminController, :dashboard
end
end