module Roda::RodaPlugins::Middleware

  1. lib/roda/plugins/middleware.rb

The middleware plugin allows the Roda app to be used as rack middleware.

In the example below, requests to /mid will return Mid by the Mid middleware, and requests to /app will not be matched by the Mid middleware, so they will be forwarded to App.

class Mid < Roda
  plugin :middleware

  route do |r|
    r.is "mid" do
      "Mid"
    end
  end
end

class App < Roda
  use Mid

  route do |r|
    r.is "app" do
      "App"
    end
  end
end

run App

By default, when the app is used as middleware and handles the request at all, it does not forward the request to the next middleware. For the following setup:

class Mid < Roda
  plugin :middleware

  route do |r|
    r.on "foo" do
      r.is "mid" do
        "Mid"
      end
    end
  end
end

class App < Roda
  use Mid

  route do |r|
    r.on "foo" do
      r.is "app" do
        "App"
      end
    end
  end
end

run App

Requests for +/foo/mid will+ return Mid, but requests for /foo/app will return an empty 404 response, because the middleware handles the /foo/app request in the r.on "foo" do block, but does not have the block return a result, which Roda treats as an empty 404 response. If you would like the middleware to forward /foo/app request to the application, you should use the :next_if_not_found plugin option.

It is possible to use the Roda app as a regular app even when using the middleware plugin. Using an app as middleware automatically creates a subclass of the app for the middleware. Because a subclass is automatically created when the app is used as middleware, any configuration of the app should be done before using it as middleware instead of after.

You can support configurable middleware by passing a block when loading the plugin:

class Mid < Roda
  plugin :middleware do |middleware, *args, &block|
    middleware.opts[:middleware_args] = args
    block.call(middleware)
  end

  route do |r|
    r.is "mid" do
      opts[:middleware_args].join(' ')
    end
  end
end

class App < Roda
  use Mid, :foo, :bar do |middleware|
    middleware.opts[:middleware_args] << :baz
  end
end

# Request to App for /mid returns
# "foo bar baz"

Methods

Public Class

  1. configure

Public Class methods

configure(app, opts={}, &block)

Configure the middleware plugin. Options:

:env_var

Set the environment variable to use to indicate to the roda application that the current request is a middleware request. You should only need to override this if you are using multiple roda middleware in the same application.

:handle_result

Callable object that will be called with request environment and rack response for all requests passing through the middleware, after either the middleware or next app handles the request and returns a response.

:forward_response_headers

Whether changes to the response headers made inside the middleware’s route block should be applied to the final response when the request is forwarded to the app. Defaults to false.

:next_if_not_found

If the middleware handles the request but returns a not found result (404 with no body), forward the result to the next middleware.

[show source] 
    # File lib/roda/plugins/middleware.rb
122 def self.configure(app, opts={}, &block)
123   app.opts[:middleware_env_var] = opts[:env_var] if opts.has_key?(:env_var)
124   app.opts[:middleware_env_var] ||= 'roda.forward_next'
125   app.opts[:middleware_configure] = block if block
126   app.opts[:middleware_handle_result] = opts[:handle_result]
127   app.opts[:middleware_forward_response_headers] = opts[:forward_response_headers]
128   app.opts[:middleware_next_if_not_found] = opts[:next_if_not_found]
129 end