Hanami::Controller
Complete, fast and testable actions for Rack and Hanami
Version
This branch contains the code for hanami-controller
2.x.
Status
Contact
- Home page: http://hanamirb.org
- Community: http://hanamirb.org/community
- Guides: https://guides.hanamirb.org
- Mailing List: http://hanamirb.org/mailing-list
- API Doc: http://rdoc.info/gems/hanami-controller
- Bugs/Issues: https://github.com/hanami/controller/issues
- Chat: http://chat.hanamirb.org
Rubies
Hanami::Controller supports Ruby (MRI) 3.0+
Installation
Add this line to your application's Gemfile:
gem "hanami-controller"
And then execute:
$ bundle
Or install it yourself as:
$ gem install hanami-controller
Usage
Hanami::Controller is a micro library for web frameworks. It works beautifully with Hanami::Router, but it can be employed everywhere. It's designed to be fast and testable.
Actions
The core of this framework are the actions. They are the endpoints that respond to incoming HTTP requests.
class Show < Hanami::Action
def handle(req, res)
res[:article] = ArticleRepository.new.find(req.params[:id])
end
end
Hanami::Action
follows the Hanami philosophy: a single purpose object with a minimal interface.
In this case, Hanami::Action
provides the key public interface of #call(env)
, making your actions Rack-compatible.
To provide custom behaviour when your actions are being called, you can implement #handle(req, res)
An action is an object and you have full control over it. In other words, you have the freedom to instantiate, inject dependencies and test it, both at the unit and integration level.
In the example below, the default repository is ArticleRepository
. During a unit test we can inject a stubbed version, and invoke #call
with the params.
We're avoiding HTTP calls, we're also going to avoid hitting the database (it depends on the stubbed repository), we're just dealing with message passing.
Imagine how fast the unit test could be.
class Show < Hanami::Action
def initialize(configuration:, repository: ArticleRepository.new)
@repository = repository
super(configuration: configuration)
end
def handle(req, res)
res[:article] = repository.find(req.params[:id])
end
private
attr_reader :repository
end
configuration = Hanami::Controller::Configuration.new
action = Show.new(configuration: configuration, repository: ArticleRepository.new)
action.call(id: 23)
Params
The request params are part of the request passed as an argument to the #handle
method.
If routed with Hanami::Router, it extracts the relevant bits from the Rack env
(eg the requested :id
).
Otherwise everything is passed as is: the full Rack env
in production, and the given Hash
for unit tests.
With Hanami::Router
:
class Show < Hanami::Action
def handle(req, *)
# ...
puts req.params # => { id: 23 } extracted from Rack env
end
end
Standalone:
class Show < Hanami::Action
def handle(req, *)
# ...
puts req.params # => { :"rack.version"=>[1, 2], :"rack.input"=>#<StringIO:0x007fa563463948>, ... }
end
end
Unit Testing:
class Show < Hanami::Action
def handle(req, *)
# ...
puts req.params # => { id: 23, key: "value" } passed as it is from testing
end
end
action = Show.new(configuration: configuration)
response = action.call(id: 23, key: "value")
Whitelisting
Params represent an untrusted input. For security reasons it's recommended to whitelist them.
require "hanami/validations"
require "hanami/controller"
class Signup < Hanami::Action
params do
required(:first_name).filled(:str?)
required(:last_name).filled(:str?)
required(:email).filled(:str?)
required(:address).schema do
required(:line_one).filled(:str?)
required(:state).filled(:str?)
required(:country).filled(:str?)
end
end
def handle(req, *)
# Describe inheritance hierarchy
puts req.params.class # => Signup::Params
puts req.params.class.superclass # => Hanami::Action::Params
# Whitelist :first_name, but not :admin
puts req.params[:first_name] # => "Luca"
puts req.params[:admin] # => nil
# Whitelist nested params [:address][:line_one], not [:address][:line_two]
puts req.params[:address][:line_one] # => "69 Tender St"
puts req.params[:address][:line_two] # => nil
end
end
Validations & Coercions
Because params are a well defined set of data required to fulfill a feature in your application, you can validate them. So you can avoid hitting lower MVC layers when params are invalid.
If you specify the :type
option, the param will be coerced.
require "hanami/validations"
require "hanami/controller"
class Signup < Hanami::Action
MEGABYTE = 1024 ** 2
params do
required(:first_name).filled(:str?)
required(:last_name).filled(:str?)
required(:email).filled?(:str?, format?: /\A.+@.+\z/)
required(:password).filled(:str?).confirmation
required(:terms_of_service).filled(:bool?)
required(:age).filled(:int?, included_in?: 18..99)
optional(:avatar).filled(size?: 1..(MEGABYTE * 3))
end
def handle(req, *)
halt 400 unless req.params.valid?
# ...
end
end
Response
The output of #call
is a Hanami::Action::Response
:
class Show < Hanami::Action
end
action = Show.new(configuration: configuration)
action.call({}) # => #<Hanami::Action::Response:0x00007fe8be968418 @status=200 ...>
This is the same res
response object passed to #handle
, where you can use its accessors to explicitly set status, headers, and body:
class Show < Hanami::Action
def handle(*, res)
res.status = 201
res.body = "Hi!"
res.headers.merge!("X-Custom" => "OK")
end
end
action = Show.new
action.call({}) # => [201, { "X-Custom" => "OK" }, ["Hi!"]]
Exposures
In case you need to send data from the action to other layers of your application, you can use exposures. By default, an action exposes the received params.
class Show < Hanami::Action
def handle(req, res)
res[:article] = ArticleRepository.new.find(req.params[:id])
end
end
action = Show.new(configuration: configuration)
response = action.call(id: 23)
article = response[:article]
article.class # => Article
article.id # => 23
response.exposures.keys # => [:params, :article]
Callbacks
If you need to execute logic before or after #handle
is invoked, you can use callbacks.
They are useful for shared logic like authentication checks.
class Show < Hanami::Action
before :authenticate, :set_article
def handle(*)
end
private
def authenticate
# ...
end
# `req` and `res` in the method signature is optional
def set_article(req, res)
res[:article] = ArticleRepository.new.find(req.params[:id])
end
end
Callbacks can also be expressed as anonymous lambdas:
class Show < Hanami::Action
before { ... } # do some authentication stuff
before { |req, res| res[:article] = ArticleRepository.new.find(req.params[:id]) }
def handle(*)
end
end
Exceptions management
When the app raises an exception, hanami-controller
, does NOT manage it.
You can write custom exception handling on per action or configuration basis.
An exception handler can be a valid HTTP status code (eg. 500
, 401
), or a Symbol
that represents an action method.
class Show < Hanami::Action
handle_exception StandardError => 500
def handle(*)
raise
end
end
action = Show.new(configuration: configuration)
action.call({}) # => [500, {}, ["Internal Server Error"]]
You can map a specific raised exception to a different HTTP status.
class Show < Hanami::Action
handle_exception RecordNotFound => 404
def handle(*)
raise RecordNotFound
end
end
action = Show.new(configuration: configuration)
action.call({}) # => [404, {}, ["Not Found"]]
You can also define custom handlers for exceptions.
class Create < Hanami::Action
handle_exception ArgumentError => :my_custom_handler
gle(*)
raise ArgumentError.new("Invalid arguments")
end
private
def my_custom_handler(req, res, exception)
res.status = 400
res.body = exception.message
end
end
action = Create.new(configuration: configuration)
action.call({}) # => [400, {}, ["Invalid arguments"]]
Exception policies can be defined globally via configuration:
configuration = Hanami::Controller::Configuration.new do |config|
config.handle_exception RecordNotFound => 404
end
class Show < Hanami::Action
def handle(*)
raise RecordNotFound
end
end
action = Show.new(configuration: configuration)
action.call({}) # => [404, {}, ["Not Found"]]
Inherited Exceptions
class MyCustomException < StandardError
end
module Articles
class Index < Hanami::Action
handle_exception MyCustomException => :handle_my_exception
def handle(*)
raise MyCustomException
end
private
def handle_my_exception(req, res, exception)
# ...
end
end
class Show < Hanami::Action
handle_exception StandardError => :handle_standard_error
def handle(*)
raise MyCustomException
end
private
def handle_standard_error(req, res, exception)
# ...
end
end
end
Articles::Index.new.call({}) # => `handle_my_exception` will be invoked
Articles::Show.new.call({}) # => `handle_standard_error` will be invoked,
# because `MyCustomException` inherits from `StandardError`
Throwable HTTP statuses
When #halt
is used with a valid HTTP code, it stops the execution and sets the proper status and body for the response:
class Show < Hanami::Action
before :authenticate!
def handle(*)
# ...
end
private
def authenticate!
halt 401 unless authenticated?
end
end
action = Show.new(configuration: configuration)
action.call({}) # => [401, {}, ["Unauthorized"]]
Alternatively, you can specify a custom message.
class Show < Hanami::Action
def handle(req, res)
res[:droid] = DroidRepository.new.find(req.params[:id]) or not_found
end
private
def not_found
halt 404, "This is not the droid you're looking for"
end
end
action = Show.new(configuration: configuration)
action.call({}) # => [404, {}, ["This is not the droid you're looking for"]]
Cookies
You can read the original cookies sent from the HTTP client via req.cookies
.
If you want to send cookies in the response, use res.cookies
.
They are read as a Hash from Rack env:
require "hanami/controller"
require "hanami/action/cookies"
class ReadCookiesFromRackEnv < Hanami::Action
include Hanami::Action::Cookies
def handle(req, *)
# ...
req.[:foo] # => "bar"
end
end
action = ReadCookiesFromRackEnv.new(configuration: configuration)
action.call({"HTTP_COOKIE" => "foo=bar"})
They are set like a Hash:
require "hanami/controller"
require "hanami/action/cookies"
class SetCookies < Hanami::Action
include Hanami::Action::Cookies
def handle(*, res)
# ...
res.[:foo] = "bar"
end
end
action = SetCookies.new(configuration: configuration)
action.call({}) # => [200, {"Set-Cookie" => "foo=bar"}, "..."]
They are removed by setting their value to nil
:
require "hanami/controller"
require "hanami/action/cookies"
class RemoveCookies < Hanami::Action
include Hanami::Action::Cookies
def handle(*, res)
# ...
res.[:foo] = nil
end
end
action = RemoveCookies.new(configuration: configuration)
action.call({}) # => [200, {"Set-Cookie" => "foo=; max-age=0; expires=Thu, 01 Jan 1970 00:00:00 -0000"}, "..."]
Default values can be set in configuration, but overridden case by case.
require "hanami/controller"
require "hanami/action/cookies"
configuration = Hanami::Controller::Configuration.new do |config|
config.(max_age: 300) # 5 minutes
end
class SetCookies < Hanami::Action
include Hanami::Action::Cookies
def handle(*, res)
# ...
res.[:foo] = { value: "bar", max_age: 100 }
end
end
action = SetCookies.new(configuration: configuration)
action.call({}) # => [200, {"Set-Cookie" => "foo=bar; max-age=100;"}, "..."]
Sessions
Actions have builtin support for Rack sessions.
Similarly to cookies, you can read the session sent by the HTTP client via
req.session
, and also manipulate it via res.ression
.
require "hanami/controller"
require "hanami/action/session"
class ReadSessionFromRackEnv < Hanami::Action
include Hanami::Action::Session
def handle(req, *)
# ...
req.session[:age] # => "35"
end
end
action = ReadSessionFromRackEnv.new(configuration: configuration)
action.call({ "rack.session" => { "age" => "35" } })
Values can be set like a Hash:
require "hanami/controller"
require "hanami/action/session"
class SetSession < Hanami::Action
include Hanami::Action::Session
def handle(*, res)
# ...
res.session[:age] = 31
end
end
action = SetSession.new(configuration: configuration)
action.call({}) # => [200, {"Set-Cookie"=>"rack.session=..."}, "..."]
Values can be removed like a Hash:
require "hanami/controller"
require "hanami/action/session"
class RemoveSession < Hanami::Action
include Hanami::Action::Session
def handle(*, res)
# ...
res.session[:age] = nil
end
end
action = RemoveSession.new(configuration: configuration)
action.call({}) # => [200, {"Set-Cookie"=>"rack.session=..."}, "..."] it removes that value from the session
While Hanami::Controller supports sessions natively, it's session store agnostic.
You have to specify the session store in your Rack middleware configuration (eg config.ru
).
use Rack::Session::Cookie, secret: SecureRandom.hex(64)
run Show.new(configuration: configuration)
HTTP Cache
Hanami::Controller sets your headers correctly according to RFC 2616 / 14.9 for more on standard cache control directives: http://tools.ietf.org/html/rfc2616#section-14.9.1
You can easily set the Cache-Control header for your actions:
require "hanami/controller"
require "hanami/action/cache"
class HttpCacheController < Hanami::Action
include Hanami::Action::Cache
cache_control :public, max_age: 600 # => Cache-Control: public, max-age=600
def handle(*)
# ...
end
end
Expires header can be specified using expires
method:
require "hanami/controller"
require "hanami/action/cache"
class HttpCacheController < Hanami::Action
include Hanami::Action::Cache
expires 60, :public, max_age: 600 # => Expires: Sun, 03 Aug 2014 17:47:02 GMT, Cache-Control: public, max-age=600
def handle(*)
# ...
end
end
Conditional Get
According to HTTP specification, conditional GETs provide a way for web servers to inform clients that the response to a GET request hasn't change since the last request returning a 304 (Not Modified)
response.
Passing the HTTP_IF_NONE_MATCH
(content identifier) or HTTP_IF_MODIFIED_SINCE
(timestamp) headers allows the web server define if the client has a fresh version of a given resource.
You can easily take advantage of Conditional Get using #fresh
method:
require "hanami/controller"
require "hanami/action/cache"
class ConditionalGetController < Hanami::Action
include Hanami::Action::Cache
def handle(*)
# ...
fresh etag: resource.cache_key
# => halt 304 with header IfNoneMatch = resource.cache_key
end
end
If resource.cache_key
is equal to IfNoneMatch
header, then hanami will halt 304
.
An alterative to hashing based check, is the time based check:
require "hanami/controller"
require "hanami/action/cache"
class ConditionalGetController < Hanami::Action
include Hanami::Action::Cache
def handle(*)
# ...
fresh last_modified: resource.update_at
# => halt 304 with header IfModifiedSince = resource.update_at.httpdate
end
end
If resource.update_at
is equal to IfModifiedSince
header, then hanami will halt 304
.
Redirect
If you need to redirect the client to another resource, use res.redirect_to
:
class Create < Hanami::Action
def handle(*, res)
# ...
res.redirect_to "http://example.com/articles/23"
end
end
action = Create.new(configuration: configuration)
action.call({ article: { title: "Hello" }}) # => [302, {"Location" => "/articles/23"}, ""]
You can also redirect with a custom status code:
class Create < Hanami::Action
def handle(*, res)
# ...
res.redirect_to "http://example.com/articles/23", status: 301
end
end
action = Create.new(configuration: configuration)
action.call({ article: { title: "Hello" }}) # => [301, {"Location" => "/articles/23"}, ""]
MIME Types
Hanami::Action
automatically sets the Content-Type
header, according to the request.
class Show < Hanami::Action
def handle(*)
end
end
action = Show.new(configuration: configuration)
response = action.call({ "HTTP_ACCEPT" => "*/*" }) # Content-Type "application/octet-stream"
response.format # :all
response = action.call({ "HTTP_ACCEPT" => "text/html" }) # Content-Type "text/html"
response.format # :html
However, you can force this value:
class Show < Hanami::Action
def handle(*, res)
# ...
res.format = :json
end
end
action = Show.new(configuration: configuration)
response = action.call({ "HTTP_ACCEPT" => "*/*" }) # Content-Type "application/json"
response.format # :json
response = action.call({ "HTTP_ACCEPT" => "text/html" }) # Content-Type "application/json"
response.format # :json
You can restrict the accepted MIME types:
class Show < Hanami::Action
accept :html, :json
def handle(*)
# ...
end
end
# When called with "\*/\*" => 200
# When called with "text/html" => 200
# When called with "application/json" => 200
# When called with "application/xml" => 415
You can check if the requested MIME type is accepted by the client.
class Show < Hanami::Action
def handle(req, res)
# ...
# @_env["HTTP_ACCEPT"] # => "text/html,application/xhtml+xml,application/xml;q=0.9"
req.accept?("text/html") # => true
req.accept?("application/xml") # => true
req.accept?("application/json") # => false
res.format # :html
# @_env["HTTP_ACCEPT"] # => "*/*"
req.accept?("text/html") # => true
req.accept?("application/xml") # => true
req.accept?("application/json") # => true
res.format # :html
end
end
Hanami::Controller is shipped with an extensive list of the most common MIME types. Also, you can register your own:
configuration = Hanami::Controller::Configuration.new do |config|
config.format custom: "application/custom"
end
class Index < Hanami::Action
def handle(*)
end
end
action = Index.new(configuration: configuration)
response = action.call({ "HTTP_ACCEPT" => "application/custom" }) # => Content-Type "application/custom"
response.format # => :custom
class Show < Hanami::Action
def handle(*, res)
# ...
res.format = :custom
end
end
action = Show.new(configuration: configuration)
response = action.call({ "HTTP_ACCEPT" => "*/*" }) # => Content-Type "application/custom"
response.format # => :custom
Streamed Responses
When the work to be done by the server takes time, it may be a good idea to stream your response. Here's an example of a streamed CSV.
configuration = Hanami::Controller::Configuration.new do |config|
config.format csv: 'text/csv'
end
class Csv < Hanami::Action
def handle(*, res)
res.format = :csv
res.body = Enumerator.new do |yielder|
yielder << csv_header
# Expensive operation is streamed as each line becomes available
csv_body.each_line do |line|
yielder << line
end
end
end
end
Note:
- In development, Hanami' code reloading needs to be disabled for streaming to work. This is because
Shotgun
interferes with the streaming action. You can disable it like thishanami server --code-reloading=false
- Streaming does not work with WEBrick as it buffers its response. We recommend using
puma
, though you may find success with other servers
No rendering, please
Hanami::Controller is designed to be a pure HTTP endpoint, rendering belongs to other layers of MVC. You can set the body directly (see response), or use Hanami::View.
Controllers
A Controller is nothing more than a logical group of actions: just a Ruby module.
module Articles
class Index < Hanami::Action
# ...
end
class Show < Hanami::Action
# ...
end
end
Articles::Index.new(configuration: configuration).call({})
Hanami::Router integration
require "hanami/router"
require "hanami/controller"
module Web
module Controllers
module Books
class Show < Hanami::Action
def handle(*)
end
end
end
end
end
configuration = Hanami::Controller::Configuration.new
router = Hanami::Router.new(configuration: configuration, namespace: Web::Controllers) do
get "/books/:id", "books#show"
end
Rack integration
Hanami::Controller is compatible with Rack. If you need to use any Rack middleware, please mount them in config.ru
.
Configuration
Hanami::Controller can be configured via Hanami::Controller::Configuration
.
It supports a few options:
require "hanami/controller"
configuration = Hanami::Controller::Configuration.new do |config|
# If the given exception is raised, return that HTTP status
# It can be used multiple times
# Argument: hash, empty by default
#
config.handle_exception ArgumentError => 404
# Register a format to MIME type mapping
# Argument: hash, key: format symbol, value: MIME type string, empty by default
#
config.format custom: "application/custom"
# Define a default format to set as `Content-Type` header for response,
# unless otherwise specified.
# If not defined here, it will return Rack's default: `application/octet-stream`
# Argument: symbol, it should be already known. defaults to `nil`
#
config.default_response_format = :html
# Define a default charset to return in the `Content-Type` response header
# If not defined here, it returns `utf-8`
# Argument: string, defaults to `nil`
#
config.default_charset = "koi8-r"
end
Thread safety
An Action is immutable, it works without global state, so it's thread-safe by design.
Versioning
Hanami::Controller uses Semantic Versioning 2.0.0
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
Copyright
Copyright © 2014 Hanami Team – Released under MIT License