lotus-controller 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 596855476b8c72b53e86d1101e54edb8137e4206
-  data.tar.gz: 40df1097012f2d091aad3eff3734cdd71077ecde
+  metadata.gz: 4f0f02211060856c6f853b05907e1993a23684a2
+  data.tar.gz: 98db51b586aa274b812def351f2960219d26a254
 SHA512:
-  metadata.gz: ebeec9005fb1c28cc195af167872a9d6aa206c65c951488b9671c11a472ff36c017c3c647c9e964db92a903cfa16b7a0f6b3b4dab777d1c18fa7de7438c590e5
-  data.tar.gz: 2626b3767d3a68ef4a2b7418c3d0711e68e27ea70f32fed7623391419ef2eacc447b65476eaabac224121ff68f1e51b9cf2bf07961a3280637d3231b39a0c159
+  metadata.gz: 8a9988d2c322dba57028f60615652aa4307ef2808a1a742e7a12c15c70609defb83abec4cd8d0c31eddaf5de49e618f74a4010c97c2c03d95a4544fe459b388a
+  data.tar.gz: 688a5dba74eecf6c8d6a14891c9b4d0d2c8b853864e66fa0beb6f09c0abd3918b18ab2daf957e64ece73a1e72ea86f803b67ffbf6bd3a8bc1e0e433a66767f05

data/CHANGELOG.md

@@ -1,127 +1,65 @@
-## v0.2.0
-### Jun 23, 2014
-
-48a5715 2014-06-22 **Luca Guidi** Made Lotus::Action#content_type public
-
-2d7b0cc 2014-06-22 **Luca Guidi** Let to specify a default format for all the requests that aren't strict about the requested Mime type (eg. `*/*`).
-
-401c1af 2014-06-19 **Luca Guidi** [breaking] Raise error if Lotus::Controller::Configuration#format doesn't receive the proper argument. Let Lotus::Action::Mime#accept to work with registered mime types
-
-028ec2e 2014-06-19 **Luca Guidi** Make Lotus::Action::Mime#format a public method
-
-ce42cd4 2014-06-19 **Luca Guidi** Detect the asked mime type and return the corresponding format
-
-87323ad 2014-06-19 **Luca Guidi** Let actions to detect accepted mime type and to return the correct format symbol. Configuration can now register mime types
-
-adf0357 2014-06-18 **Krzysztof Zalewski** [breaking] Implement Action#format
-
-328153b 2014-06-17 **Luca Guidi** Bump version to v0.2.0
-
-b2e5c85 2014-06-17 **Luca Guidi** Depend on lotus-utils ~> 0.2
-
-166a3c8 2014-06-17 **Luca Guidi** Controller.duplicate can accept nil controllers namespace
-
-c11bc96 2014-06-17 **Luca Guidi** Lotus::Controller: .duplicate => .dup, .generate => .duplicate
-
-9488c66 2014-06-16 **Luca Guidi** Gem: build only with lib/ and essential files
-
-cd7038c 2014-06-16 **Luca Guidi** [breaking] Removed Lotus::Action::Throwable#throw in favor of #halt
-
-c200e68 2014-06-16 **Luca Guidi** Pretty print exceptions in rack.errors
-
-3c122b0 2014-06-13 **Krzysztof Zalewski** Reference exception in rack.errors
-
-9e64c3f 2014-06-11 **Luca Guidi** Let Lotus::Controller.generate to set action_module
-
-f28d7e3 2014-06-11 **Luca Guidi** Introducing Lotus::Controller.generate as shortcut for .duplicate and .configure
-
-af217ea 2014-06-08 **Luca Guidi** [breaking] Use composition over inheritance for Lotus::Action::Params
-
-47e86db 2014-06-08 **Luca Guidi** [breaking] Use composition over inheritance for Lotus::Action::CookieJar
-
-5e2a4a7 2014-05-28 **Luca Guidi** Allow standalone actions to inherit configuration from the right framework. Added Configuration#modules in order to configure the additional modules to include by default
-
-ceb7214 2014-05-28 **Luca Guidi** Better Ruby idioms
-
-075f9c3 2014-05-28 **Luca Guidi** Use the proper level of encapsulation for Configuration
-
-431970c 2014-05-27 **Luca Guidi** Ensure the right level of duplication for Lotus::Controller
-
-ae49c57 2014-05-27 **Luca Guidi** [breaking] Keep independent copies of framework, controller and action configurations. Introduced in action_module for configuration.
-
-c56683a 2014-05-27 **Luca Guidi** [breaking] Introduced configuration for Controller and Action
-
-8d39557 2014-05-10 **Luca Guidi** Added support for Ruby 2.1.2
-
-c2854b6 2014-04-27 **Luca Guidi** Make HTTP status messages compliant with IANA and Rack
-
-c137c3f 2014-04-27 **Luca Guidi** Implemented Action.use, that let to use a Rack middleware as a before callback
-
-eb86286 2014-04-20 **Damir Zekic** Replace `#throw` override with `#halt` method
-
-6da21f9 2014-03-17 **Damir Zekic** Allow exception handling to be disabled
-
-c0ccb72 2014-02-24 **Luca Guidi Added support for Ruby 2.1.1
-
-## v0.1.0
-### Feb 23, 2014
-
-f750e4c 2014-02-22 **Luca Guidi** Moved .handled_exceptions from Action to Controller, so that the place where to configure the framework will be easier to find for developers.
-
-1de2a27 2014-02-17 **Luca Guidi** Added Lotus::Action.handle_exception
-
-fd9e080 2014-02-13 **Luca Guidi** Implemented Lotus::Action.accept, in order to restrict the access when a non supported mime type is requested
-
-516983f 2014-02-13 **Luca Guidi** Implemented Lotus::Action#accept?
-
-634719a 2014-02-13 **Luca Guidi** Changed auto content type policy
-
-7cce354 2014-02-12 **Luca Guidi** Use @_env instead of the argument in Lotus::Action::Callable#call
-
-a41b43d 2014-02-12 **Luca Guidi** Extracted constants for Lotus::Action::Params
-
-6bdf55b 2014-01-31 **Luca Guidi** Make session support optional
-
-29c5f8c 2014-01-31 **Luca Guidi** Make cookies support optional
-
-0b36afb 2014-01-31 **Luca Guidi** Removed Lotus::HTTP::Request and Response
-
-25b2bcf 2014-01-31 **Luca Guidi** Return serialized Rack response (Array) instead of the object. Lotus::Action::Redirect no longer depends on Response. Lotus::Action::CookieJar no longer depends on Response, but on headers.
-
-b306f4f 2014-01-31 **Luca Guidi** Lotus::Action::Rack#session no longer depends on Request
-
-9a44477 2014-01-31 **Luca Guidi** Lotus::Action::Mime no longer depends on Request
-
-9b7f524 2014-01-31 **Luca Guidi** Lotus::Action::CookieJar logic for cookies extraction/set/get is no longer dependant on Request and Response.
-
-fc6de40 2013-09-24 **Luca Guidi** Don't wrap body if respond to #each
-
-ce46399 2013-09-24 **Luca Guidi** Introducing factory for Response
-
-83adc9c 2013-08-07 **Luca Guidi** Ensure to wrap body for HTTP::Response
-
-0a41bf8 2013-08-07 **Luca Guidi** Introducing Lotus::HTTP::Request/Response
-
-c44d440 2013-07-12 **Luca Guidi** Integration tests for sessions
-
-e62b355 2013-07-11 **Luca Guidi** Added automatic Mime Type capabilities
-
-351eb2f 2013-07-11 **Luca Guidi** Split features in proper `Lotus::Action` submodules.
-
-9d268df 2013-07-10 **Luca Guidi** Introducing throw facility, to stop the request flow immediately.
-
-73af6d1 2013-07-09 **Luca Guidi** Integration tests with Lotus::Router
-
-6938fae 2013-07-05 **Luca Guidi** Implemented cookies facilities.
-
-69f4c62 2013-07-02 **Luca Guidi** Rack compatibility
-
-13bd2d2 2013-06-28 **Luca Guidi** Implemented #redirect_to
-
-5adbee1 2013-06-28 **Luca Guidi** Implemented sessions support
-
-4bb794d 2013-06-28 **Luca Guidi** Implemented action callbacks
-
-3b792dc 2013-06-25 **Luca Guidi** Introducing Lotus::Controller
-
-d279c48 2013-06-25 **Luca Guidi** Initial mess
+# Lotus::Controller
+Complete, fast and testable actions for Rack
+
+## v0.3.0 - 2014-12-23
+### Added
+- [Luca Guidi] Introduced `Action#request_id` as unique identifier for an incoming HTTP request
+- [Luca Guidi] Introduced `Lotus::Controller.load!` as loading framework entry point
+- [Kir Shatrov] Allow to define a default charset (`default_charset` configuration)
+- [Kir Shatrov] Automatic content type with charset (eg `Content-Type: text/html; charset=utf-8`)
+- [Michał Krzyżanowski] Allow to specify custom exception handlers: procs or methods (`exception_handler` configuration)
+- [Karl Freeman & Lucas Souza] Introduced HTTP caching (`Cache-Control`, `Last-Modified`, ETAG, Conditional GET, expires)
+- [Satoshi Amemiya] Introduced `Action::Params#to_h` and `#to_hash`
+- [Luca Guidi] Added `#params` and `#errors` as default exposures
+- [Luca Guidi] Introduced complete params validations
+- [Luca Guidi & Matthew Bellantoni] Allow to whitelist params
+- [Luca Guidi & Matthew Bellantoni] Allow to define custom classes for params via `Action.params`
+- [Krzysztof Zalewski] Introduced `Action#format` as query method to introspect the requested mime type
+- [Luca Guidi] Official support for Ruby 2.2
+
+### Changed
+- [Trung Lê] Renamed `Configuration#modules` to `#prepare`
+- [Luca Guidi] Update HTTP status codes to IETF RFC 7231
+- [Luca Guidi] When `Lotus::Controller` is included, don't inject code
+- [Luca Guidi] Removed `Controller.action` as a DSL to define actions
+- [Krzysztof Zalewski] Removed `Action#content_type` in favor of `#format=` which accepts a symbol (eg. `:json`)
+- [Fuad Saud] Reduce method visibility where possible (Ruby `private` and `protected`)
+
+### Fixed
+- [Luca Guidi] Don't let exposures definition to override existing methods
+
+## v0.2.0 - 2014-06-23
+### Added
+- [Luca Guidi] Introduced `Controller.configure` and `Controller.duplicate`
+- [Luca Guidi] Introduced `Action.use`, that let to use a Rack middleware as a before callback
+– [Luca Guidi] Allow to define a default mime type when the request is `Accept: */*` (`default_format` configuration)
+– [Luca Guidi] Allow to register custom mime types and associate them to a symbol (`format` configuration)
+- [Luca Guidi] Introduced `Configuration#handle_exceptions` to associate exceptions to HTTP statuses
+- [Damir Zekic] Allow developers to toggle exception handling (`handle_exceptions` configuration)
+- [Luca Guidi] Introduced `Controller::Configuration`
+- [Luca Guidi] Official support for Ruby 2.1
+
+### Changed
+- [Luca Guidi] `Lotus::Action::Params` doesn't inherit from `Lotus::Utils::Hash` anymore
+- [Luca Guidi] `Lotus::Action::CookieJar` doesn't inherit from `Lotus::Utils::Hash` anymore
+- [Luca Guidi] Make HTTP status messages compliant with IANA and Rack
+- [Damir Zekic] Moved `#throw` override logic into `#halt`, which keeps the same semantic
+
+### Fixed
+- [Krzysztof Zalewski] Reference exception in `rack.errors`
+
+## v0.1.0 - 2014-02-23
+### Added
+- [Luca Guidi] Introduced `Action.accept` to whitelist accepted mime types
+- [Luca Guidi] Introduced `Action#accept?` as a query method for the current request
+- [Luca Guidi] Allow to whitelist handled exceptions and associate them to an HTTP status
+- [Luca Guidi] Automatic `Content-Type`
+- [Luca Guidi] Use `throw` as a control flow which understands HTTP status
+- [Luca Guidi] Introduced opt-in support for HTTP/Rack cookies
+- [Luca Guidi] Introduced opt-in support for HTTP/Rack sessions
+- [Luca Guidi] Introduced HTTP redirect API
+- [Luca Guidi] Introduced callbacks for actions: before and after
+- [Luca Guidi] Introduced exceptions handling with HTTP statuses
+- [Luca Guidi] Introduced exposures
+- [Luca Guidi] Introduced basic actions compatible with Rack
+- [Luca Guidi] Official support for Ruby 2.0

data/README.md

@@ -52,8 +52,8 @@ It's designed to be fast and testable.
 
 ### Actions
 
-The core of this frameworks are the actions.
-They are the endpoint that responds to incoming HTTP requests.
+The core of this framework are the actions.
+They are the endpoints that respond to incoming HTTP requests.
 
 ```ruby
 class Show
@@ -66,17 +66,17 @@ end
 ```
 
 The usage of `Lotus::Action` follows the Lotus philosophy: include a module and implement a minimal interface.
-In this case, it's only one method: `#call(params)`.
+In this case, the interface is one method: `#call(params)`.
 
 Lotus is designed to not interfere with inheritance.
 This is important, because you can implement your own initialization strategy.
 
-__An action is an object__ after all, it's important that __you have the full control on it__.
-In other words, you have the freedom of instantiate, inject dependencies and test it, both with unit and integration.
+__An action is an object__. That's important because __you have the full control on 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, we're stating that the default repository is `Article`, but during an unit test we can inject a stubbed version, and invoke `#call` with the params that we want to simulate.
+In the example below, the default repository is `Article`. During a unit test we can inject a stubbed version, and invoke `#call` with the params.
 __We're avoiding HTTP calls__, we're eventually avoiding to hit the database (it depends on the stubbed repository), __we're just dealing with message passing__.
-Imagine how **fast** can be a unit test like this.
+Imagine how **fast** the unit test could be.
 
 ```ruby
 class Show
@@ -99,7 +99,7 @@ action.call({ id: 23 })
 
 The request params are passed as an argument to the `#call` method.
 If routed with *Lotus::Router*, it extracts the relevant bits from the Rack `env` (eg the requested `:id`).
-Otherwise everything it's passed as it is: the full Rack `env` in production, and the given `Hash` for unit tests.
+Otherwise everything passed as is: the full Rack `env` in production, and the given `Hash` for unit tests.
 
 With Lotus::Router:
 
@@ -143,9 +143,81 @@ action   = Show.new
 response = action.call({ id: 23, key: 'value' })
 ```
 
+#### Whitelisting
+
+Params represent an untrusted input.
+For security reasons it's recommended to whitelist them.
+
+```ruby
+require 'lotus/controller'
+
+class Signup
+  include Lotus::Action
+
+  params do
+    param :first_name
+    param :last_name
+    param :email
+  end
+
+  def call(params)
+    # Describe inheritance hierarchy
+    puts params.class            # => Signup::Params
+    puts params.class.superclass # => Lotus::Action::Params
+
+    # Whitelist :first_name, but not :admin
+    puts params[:first_name]     # => "Luca"
+    puts params[:admin]          # => 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.
+
+```ruby
+require 'lotus/controller'
+
+class Signup
+  MEGABYTE = 1024 ** 2
+  include Lotus::Action
+
+  params do
+    param :first_name,       presence: true
+    param :last_name,        presence: true
+    param :email,            presence: true, format: /@/,   confirmation: true
+    param :password,         presence: true,                confirmation: true
+    param :terms_of_service, acceptance: true
+    param :avatar,           size: 0..(MEGABYTE * 3)
+    param :age,              type: Integer, size: 18..99
+  end
+
+  def call(params)
+    halt 400 unless params.valid?
+    # ...
+  end
+end
+
+action = Signup.new
+
+action.call(valid_params) # => [200, {}, ...]
+action.errors.empty?      # => true
+
+action.call(invalid_params) # => [400, {}, ...]
+action.errors               # =>  #<Lotus::Validations::Errors:0x007fabe4b433d0 @errors={...}>
+
+action.errors.for(:email)
+  # => [#<Lotus::Validations::Error:0x007fabe4b432e0 @attribute=:email, @validation=:presence, @expected=true, @actual=nil>]
+```
+
 ### Response
 
-The output of `#call` is a serialized Rack::Response (see [#finish](http://rack.rubyforge.org/doc/classes/Rack/Response.html#M000182)):
+The output of `#call` is a serialized Rack::Response (see [#finish](http://rubydoc.info/github/rack/rack/master/Rack/Response#finish-instance_method)):
 
 ```ruby
 class Show
@@ -176,13 +248,20 @@ end
 action = Show.new
 action.call({}) # => [201, { "X-Custom" => "OK" }, ["Hi!"]]
 ```
+
 ### Exposures
 
 We know that actions are objects and Lotus::Action respects one of the pillars of OOP: __encapsulation__.
 Other frameworks extract instance variables (`@ivar`) and make them available to the view context.
-The solution of Lotus::Action is a simple and powerful DSL: `expose`.
-It's a thin layer on top of `attr_reader`. When used, it creates a getter for the given attribute, and adds it to the _exposures_.
-Exposures (`#exposures`) is set of exposed attributes, so that the view context can have the information needed to render a page.
+
+Lotus::Action's solution is the simple and powerful DSL: `expose`.
+It's a thin layer on top of `attr_reader`.
+
+Using `expose` creates a getter for the given attribute, and adds it to the _exposures_.
+Exposures (`#exposures`) are a set of attributes exposed to the view.
+That is to say the variables necessary for rendering a view.
+
+By default, all Lotus::Actions expose `#params` and `#errors`.
 
 ```ruby
 class Show
@@ -205,7 +284,7 @@ puts action.exposures # => { article: <Article:0x007f965c1d0318 @id=23> }
 
 ### Callbacks
 
-It offers powerful, inheritable callbacks chain which is executed before and/or after your `#call` method invocation:
+It offers a powerful, inheritable callback chain which is executed before and/or after your `#call` method invocation:
 
 ```ruby
 class Show
@@ -235,7 +314,7 @@ class Show
   include Lotus::Action
 
   before { ... } # do some authentication stuff
-  before {|params| @article = Article.find params[:id] }
+  before { |params| @article = Article.find params[:id] }
 
   def call(params)
   end
@@ -259,7 +338,7 @@ action = Show.new
 action.call({}) # => [500, {}, ["Internal Server Error"]]
 ```
 
-You can define how a specific raised exception should be transformed in an HTTP status.
+You can map a specific raised exception to a different HTTP status.
 
 ```ruby
 class Show
@@ -275,6 +354,27 @@ action = Show.new
 action.call({id: 'unknown'}) # => [404, {}, ["Not Found"]]
 ```
 
+You can also define custom handlers for exceptions.
+
+```ruby
+class Create
+  include Lotus::Action
+  handle_exception ArgumentError => :my_custom_handler
+
+  def call(params)
+    raise ArgumentError.new("Invalid arguments")
+  end
+
+  private
+  def my_custom_handler(exception)
+    status 400, exception.message
+  end
+end
+
+action = Create.new
+action.call({}) # => [400, {}, ["Invalid arguments"]]
+```
+
 Exception policies can be defined globally, **before** the controllers/actions
 are loaded.
 
@@ -304,22 +404,22 @@ end
 
 # or
 
-class ArticlesController
-  include Lotus::Controller
+module Articles
+  class Show
+    include Lotus::Action
 
-  configure do
-    handle_exceptions false
-  end
+    configure do
+      handle_exceptions false
+    end
 
-  action 'Show' do
     def call(params)
       @article = Article.find params[:id]
     end
   end
 end
 
-action = ArticlesController::Show.new
-action.call({id: 'unknown'}) # => [404, {}, ["Not Found"]]
+action = Articles::Show.new
+action.call({id: 'unknown'}) # => raises RecordNotFound
 ```
 
 ### Throwable HTTP statuses
@@ -348,9 +448,9 @@ action.call({}) # => [401, {}, ["Unauthorized"]]
 
 ### Cookies
 
-It offers convenient access to cookies.
+Lotus::Controller offers convenient access to cookies.
 
-They are read as an Hash from Rack env:
+They are read as a Hash from Rack env:
 
 ```ruby
 require 'lotus/controller'
@@ -370,7 +470,7 @@ action = ReadCookiesFromRackEnv.new
 action.call({'HTTP_COOKIE' => 'foo=bar'})
 ```
 
-They are set like an Hash:
+They are set like a Hash:
 
 ```ruby
 require 'lotus/controller'
@@ -432,7 +532,7 @@ action = ReadSessionFromRackEnv.new
 action.call({ 'rack.session' => { 'age' => '31' }})
 ```
 
-Values can be set like an Hash:
+Values can be set like a Hash:
 
 ```ruby
 require 'lotus/controller'
@@ -452,7 +552,7 @@ action = SetSession.new
 action.call({}) # => [200, {"Set-Cookie"=>"rack.session=..."}, "..."]
 ```
 
-Values can be removed like an Hash:
+Values can be removed like a Hash:
 
 ```ruby
 require 'lotus/controller'
@@ -480,6 +580,92 @@ use Rack::Session::Cookie, secret: SecureRandom.hex(64)
 run Show.new
 ```
 
+### Http Cache
+
+Lotus::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:
+
+```ruby
+require 'lotus/controller'
+require 'lotus/action/cache'
+
+class HttpCacheController
+  include Lotus::Action
+  include Lotus::Action::Cache
+
+  cache_control :public, max_age: 600 # => Cache-Control: public, max-age=600
+
+  def call(params)
+    # ...
+  end
+end
+```
+
+Expires header can be specified using `expires` method:
+
+```ruby
+require 'lotus/controller'
+require 'lotus/action/cache'
+
+class HttpCacheController
+  include Lotus::Action
+  include Lotus::Action::Cache
+
+  expires 60, :public, max_age: 600 # => Expires: Sun, 03 Aug 2014 17:47:02 GMT, Cache-Control: public, max-age=600
+
+  def call(params)
+    # ...
+  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 Not Modified header (304).
+
+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:
+
+```ruby
+require 'lotus/controller'
+require 'lotus/action/cache'
+
+class ConditionalGetController
+  include Lotus::Action
+  include Lotus::Action::Cache
+
+  def call(params)
+    # ...
+    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 lotus will `halt 304`.
+
+The same behavior is accomplished using `last_modified`:
+
+```ruby
+require 'lotus/controller'
+require 'lotus/action/cache'
+
+class ConditionalGetController
+  include Lotus::Action
+  include Lotus::Action::Cache
+
+  def call(params)
+    # ...
+    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 lotus will `halt 304`.
+
 ### Redirect
 
 If you need to redirect the client to another resource, use `#redirect_to`:
@@ -498,7 +684,23 @@ action = Create.new
 action.call({ article: { title: 'Hello' }}) # => [302, {'Location' => '/articles/23'}, '']
 ```
 
-### Mime types
+You can also redirect with a custom status code:
+
+```ruby
+class Create
+  include Lotus::Action
+
+  def call(params)
+    # ...
+    redirect_to 'http://example.com/articles/23', status: 301
+  end
+end
+
+action = Create.new
+action.call({ article: { title: 'Hello' }}) # => [301, {'Location' => '/articles/23'}, '']
+```
+
+### Mime Types
 
 Lotus::Action automatically sets the `Content-Type` header, according to the request.
 
@@ -627,10 +829,10 @@ You can set the body directly (see [response](#response)), or use [Lotus::View](
 
 ### Controllers
 
-A Controller is nothing more than a logical group for actions.
+A Controller is nothing more than a logical group of actions: just a Ruby module.
 
 ```ruby
-class ArticlesController
+module Articles
   class Index
     include Lotus::Action
 
@@ -643,29 +845,13 @@ class ArticlesController
     # ...
   end
 end
-```
-
-Which is a bit verbose. Instead, just do:
-
-```ruby
-class ArticlesController
-  include Lotus::Controller
 
-  action 'Index' do
-    # ...
-  end
-
-  action 'Show' do
-    # ...
-  end
-end
-
-ArticlesController::Index.new.call({})
+Articles::Index.new.call({})
 ```
 
 ### Lotus::Router integration
 
-While Lotus::Router works great with this framework, Lotus::Controller doesn't depend from it.
+While Lotus::Router works great with this framework, Lotus::Controller doesn't depend on it.
 You, as developer, are free to choose your own routing system.
 
 But, if you use them together, the **only constraint is that an action must support _arity 0_ in its constructor**.
@@ -703,20 +889,19 @@ While a Lotus application's architecture is more web oriented, this framework is
 ### Rack middleware
 
 Rack middleware can be configured globally in `config.ru`, but often they add an
-unnecessary overhead for all those endpoints who aren't direct users of a
-certain middleware. Think about a middleware to create sessions, where only
-`SessionsController::Create` may be involved and the rest of the application
-shouldn't pay the performance ticket of calling that middleware.
+unnecessary overhead for all those endpoints that aren't direct users of a
+certain middleware.
+
+Think about a middleware to create sessions, where only `SessionsController::Create` needs that middleware, but every other action pays the performance price for that middleware.
 
-An action can employ one or more Rack middleware, with `.use`.
+The solution is that an action can employ one or more Rack middleware, with `.use`.
 
 ```ruby
 require 'lotus/controller'
 
-class SessionsController
-  include Lotus::Controller
-
-  action 'Create' do
+module Sessions
+  class Create
+    include Lotus::Action
     use OmniAuth
 
     def call(params)
@@ -729,10 +914,10 @@ end
 ```ruby
 require 'lotus/controller'
 
-class SessionsController
-  include Lotus::Controller
+module Sessions
+  class Create
+    include Lotus::Controller
 
-  action 'Create' do
     use XMiddleware.new('x', 123)
     use YMiddleware.new
     use ZMiddleware
@@ -746,7 +931,7 @@ end
 
 ### Configuration
 
-Lotus::Controller can be configured with a DSL that determines its behavior.
+Lotus::Controller can be configured with a DSL.
 It supports a few options:
 
 ```ruby
@@ -754,7 +939,7 @@ require 'lotus/controller'
 
 Lotus::Controller.configure do
   # Handle exceptions with HTTP statuses (true) or don't catch them (false)
-  # Argument: boolean, defaults to true
+  # Argument: boolean, defaults to `true`
   #
   handle_exceptions true
 
@@ -764,65 +949,77 @@ Lotus::Controller.configure do
   #
   handle_exception ArgumentError => 404
 
-  # Configure which module to include when Lotus::Controller.action is used
-  # Argument: module, defaults to Lotus::Action
-  #
-  action_module MyApp::Action # module, defaults to Lotus::Action
-
   # Register a format to mime type mapping
   # Argument: hash, key: format symbol, value: mime type string, empty by default
   #
   format custom: 'application/custom'
 
-  # Configure the modules to be included/extended/prepended by default.
-  # Argument: proc, empty by default
+  # Define a default format to return in case of HTTP request with `Accept: */*`
+  # If not defined here, it will return Rack's default: `application/octet-stream`
+  # Argument: symbol, it should be already known. defaults to `nil`
   #
-  modules do
+  default_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`
+  #
+  default_charset 'koi8-r'
+
+  # Configure the logic to be executed when Lotus::Action is included
+  # This is useful to DRY code by having a single place where to configure
+  # shared behaviors like authentication, sessions, cookies etc.
+  # Argument: proc
+  #
+  prepare do
     include Lotus::Action::Sessions
-    prepend MyLibrary::Session::Store
+    include MyAuthentication
+    use SomeMiddleWare
+
+    before { authenticate! }
   end
 end
 ```
 
-All those global configurations can be overwritten at a finer grained level:
-controllers. Each controller and action has its own copy of the global
-configuration, so that changes are inherited from the top to the bottom, but
-not bubbled up in the opposite direction.
+All of the global configurations can be overwritten at the controller level.
+Each controller and action has its own copy of the global configuration.
+
+This means changes are inherited from the top to the bottom, but do not bubble back up.
 
 ```ruby
 require 'lotus/controller'
 
 Lotus::Controller.configure do
-  handle_exception ArgumentError => 404
+  handle_exception ArgumentError => 400
 end
 
-class ArticlesController
-  include Lotus::Controller
+module Articles
+  class Create
+    include Lotus::Action
 
-  configure do
-    handle_exceptions false
-  end
+    configure do
+      handle_exceptions false
+    end
 
-  action 'Create' do
     def call(params)
       raise ArgumentError
     end
   end
 end
 
-class UsersController
-  include Lotus::Controller
+module Users
+  class Create
+    include Lotus::Action
 
-  action 'Create' do
     def call(params)
       raise ArgumentError
     end
   end
 end
 
-UsersController::Create.new.call({}) # => HTTP 400
+Users::Create.new.call({}) # => HTTP 400
 
-ArticlesController::Create.new.call({})
+Articles::Create.new.call({})
   # => raises ArgumentError because we set handle_exceptions to false
 ```
 
@@ -850,7 +1047,7 @@ end
 ```
 
 The code above defines `WebApp::Controller` and `WebApp::Action`, to be used for
-the `WebApp` endpoints, while `ApiApp::Controller` and `ApiApp::Action` have 
+the `WebApp` endpoints, while `ApiApp::Controller` and `ApiApp::Action` have
 a different configuration.
 
 ### Thread safety
@@ -877,6 +1074,9 @@ end
 run Action
 ```
 
+Lotus::Controller heavely depends on class configuration, to ensure immutability
+in deployment environments, please consider of invoke `Lotus::Controller.load!`.
+
 ## Versioning
 
 __Lotus::Controller__ uses [Semantic Versioning 2.0.0](http://semver.org)