pipelines.md

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.

{% hint style="warning" %} Don't get rid of StaticController if you need to serve static assets. {% endhint %}

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