lotus-controller 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fac98fda3029902773f0dc45d886942f4e3fae87
-  data.tar.gz: b2a40a8361d84bb0625aaf8d60925952999704ce
+  metadata.gz: 596855476b8c72b53e86d1101e54edb8137e4206
+  data.tar.gz: 40df1097012f2d091aad3eff3734cdd71077ecde
 SHA512:
-  metadata.gz: 8f3c1d85c792b625120de32d1210dcd080501a6b041a5ccc3ee9d6788cb44bbe0354162c097f9488acdc25ddd841fa1378e9d24547832ba4b61b83edb4e44251
-  data.tar.gz: 5080fe24a7c4260054730dddf65ebcf10803c45ddd4f95981984971cc81a9e635ef723fcffbc19150226125fc34ce3d9c9003b57ce59fbdd3f9f330b4b8c8104
+  metadata.gz: ebeec9005fb1c28cc195af167872a9d6aa206c65c951488b9671c11a472ff36c017c3c647c9e964db92a903cfa16b7a0f6b3b4dab777d1c18fa7de7438c590e5
+  data.tar.gz: 2626b3767d3a68ef4a2b7418c3d0711e68e27ea70f32fed7623391419ef2eacc447b65476eaabac224121ff68f1e51b9cf2bf07961a3280637d3231b39a0c159

data/CHANGELOG.md

@@ -0,0 +1,127 @@
+## 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

data/README.md

@@ -9,6 +9,7 @@ A Rack compatible Controller layer for [Lotus](http://lotusrb.org).
 [![Coverage](https://coveralls.io/repos/lotus/controller/badge.png?branch=master)](https://coveralls.io/r/lotus/controller)
 [![Code Climate](https://codeclimate.com/github/lotus/controller.png)](https://codeclimate.com/github/lotus/controller)
 [![Dependencies](https://gemnasium.com/lotus/controller.png)](https://gemnasium.com/lotus/controller)
+[![Inline docs](http://inch-ci.org/github/lotus/controller.png)](http://inch-ci.org/github/lotus/controller)
 
 ## Contact
 
@@ -16,7 +17,8 @@ A Rack compatible Controller layer for [Lotus](http://lotusrb.org).
 * Mailing List: http://lotusrb.org/mailing-list
 * API Doc: http://rdoc.info/gems/lotus-controller
 * Bugs/Issues: https://github.com/lotus/controller/issues
-* Support: http://stackoverflow.com/questions/tagged/lotusrb
+* Support: http://stackoverflow.com/questions/tagged/lotus-ruby
+* Chat: https://gitter.im/lotus/chat
 
 ## Rubies
 
@@ -44,7 +46,7 @@ $ gem install lotus-controller
 
 ## Usage
 
-Lotus::Controller is a thin layer (**275 LOCs**) for MVC web frameworks.
+Lotus::Controller is a micro library for web frameworks.
 It works beautifully with [Lotus::Router](https://github.com/lotus/router), but it can be employed everywhere.
 It's designed to be fast and testable.
 
@@ -262,7 +264,7 @@ You can define how a specific raised exception should be transformed in an HTTP
 ```ruby
 class Show
   include Lotus::Action
-  handle_exception RecordNotFound, 404
+  handle_exception RecordNotFound => 404
 
   def call(params)
     @article = Article.find params[:id]
@@ -277,7 +279,9 @@ Exception policies can be defined globally, **before** the controllers/actions
 are loaded.
 
 ```ruby
-Lotus::Controller.handled_exceptions = { RecordNotFound => 404 }
+Lotus::Controller.configure do
+  handle_exception RecordNotFound => 404
+end
 
 class Show
   include Lotus::Action
@@ -291,9 +295,36 @@ action = Show.new
 action.call({id: 'unknown'}) # => [404, {}, ["Not Found"]]
 ```
 
+This feature can be turned off globally, in a controller or in a single action.
+
+```ruby
+Lotus::Controller.configure do
+  handle_exceptions false
+end
+
+# or
+
+class ArticlesController
+  include Lotus::Controller
+
+  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"]]
+```
+
 ### Throwable HTTP statuses
 
-When [#throw](http://ruby-doc.org/core-2.1.0/Kernel.html#method-i-throw) is used with a valid HTTP code, it stops the execution and sets the proper status and body for the response:
+When `#halt` is used with a valid HTTP code, it stops the execution and sets the proper status and body for the response:
 
 ```ruby
 class Show
@@ -307,7 +338,7 @@ class Show
 
   private
   def authenticate!
-    throw 401 unless authenticated?
+    halt 401 unless authenticated?
   end
 end
 
@@ -469,8 +500,26 @@ action.call({ article: { title: 'Hello' }}) # => [302, {'Location' => '/articles
 
 ### Mime types
 
-Lotus::Action automatically sets the mime type, according to the request headers.
-However, you can override this value:
+Lotus::Action automatically sets the `Content-Type` header, according to the request.
+
+```ruby
+class Show
+  include Lotus::Action
+
+  def call(params)
+  end
+end
+
+action = Show.new
+
+action.call({ 'HTTP_ACCEPT' => '*/*' }) # Content-Type "application/octet-stream"
+action.format                           # :all
+
+action.call({ 'HTTP_ACCEPT' => 'text/html' }) # Content-Type "text/html"
+action.format                                 # :html
+```
+
+However, you can force this value:
 
 ```ruby
 class Show
@@ -478,12 +527,17 @@ class Show
 
   def call(params)
     # ...
-    self.content_type = 'application/json'
+    self.format = :json
   end
 end
 
 action = Show.new
-action.call({ id: 23 }) # => [200, {'Content-Type' => 'application/json'}, '...']
+
+action.call({ 'HTTP_ACCEPT' => '*/*' }) # Content-Type "application/json"
+action.format                           # :json
+
+action.call({ 'HTTP_ACCEPT' => 'text/html' }) # Content-Type "application/json"
+action.format                                 # :json
 ```
 
 You can restrict the accepted mime types:
@@ -517,6 +571,7 @@ class Show
     accept?('text/html')        # => true
     accept?('application/xml')  # => true
     accept?('application/json') # => false
+    self.format                 # :html
 
 
 
@@ -525,8 +580,44 @@ class Show
     accept?('text/html')        # => true
     accept?('application/xml')  # => true
     accept?('application/json') # => true
+    self.format                 # :html
+  end
+end
+```
+
+Lotus::Controller is shipped with an extensive list of the most common mime types.
+Also, you can register your own:
+
+```ruby
+Lotus::Controller.configure do
+  format custom: 'application/custom'
+end
+
+class Index
+  include Lotus::Action
+
+  def call(params)
+  end
+end
+
+action = Index.new
+
+action.call({ 'HTTP_ACCEPT' => 'application/custom' }) # => Content-Type 'application/custom'
+action.format                                          # => :custom
+
+class Show
+  include Lotus::Action
+
+  def call(params)
+    # ...
+    self.format = :custom
   end
 end
+
+action = Show.new
+
+action.call({ 'HTTP_ACCEPT' => '*/*' }) # => Content-Type 'application/custom'
+action.format                           # => :custom
 ```
 
 ### No rendering, please
@@ -554,7 +645,7 @@ class ArticlesController
 end
 ```
 
-Which is a bit verboses. Instead, just do:
+Which is a bit verbose. Instead, just do:
 
 ```ruby
 class ArticlesController
@@ -572,7 +663,7 @@ end
 ArticlesController::Index.new.call({})
 ```
 
-## Lotus::Router integration
+### Lotus::Router integration
 
 While Lotus::Router works great with this framework, Lotus::Controller doesn't depend from it.
 You, as developer, are free to choose your own routing system.
@@ -604,12 +695,165 @@ convenient fallback, you should know that it's the slower option. **Be sure of
 loading your controllers before you initialize the router.**
 
 
-## Rack integration
+### Rack integration
 
 Lotus::Controller is compatible with Rack. However, it doesn't mount any middleware.
-While a Lotus application's architecture is more web oriented, this framework is designed to build pure HTTP entpoints.
+While a Lotus application's architecture is more web oriented, this framework is designed to build pure HTTP endpoints.
+
+### 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.
+
+An action can employ one or more Rack middleware, with `.use`.
+
+```ruby
+require 'lotus/controller'
+
+class SessionsController
+  include Lotus::Controller
+
+  action 'Create' do
+    use OmniAuth
+
+    def call(params)
+      # ...
+    end
+  end
+end
+```
+
+```ruby
+require 'lotus/controller'
+
+class SessionsController
+  include Lotus::Controller
+
+  action 'Create' do
+    use XMiddleware.new('x', 123)
+    use YMiddleware.new
+    use ZMiddleware
+
+    def call(params)
+      # ...
+    end
+  end
+end
+```
+
+### Configuration
+
+Lotus::Controller can be configured with a DSL that determines its behavior.
+It supports a few options:
+
+```ruby
+require 'lotus/controller'
+
+Lotus::Controller.configure do
+  # Handle exceptions with HTTP statuses (true) or don't catch them (false)
+  # Argument: boolean, defaults to true
+  #
+  handle_exceptions true
+
+  # If the given exception is raised, return that HTTP status
+  # It can be used multiple times
+  # Argument: hash, empty by default
+  #
+  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
+  #
+  modules do
+    include Lotus::Action::Sessions
+    prepend MyLibrary::Session::Store
+  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.
+
+```ruby
+require 'lotus/controller'
+
+Lotus::Controller.configure do
+  handle_exception ArgumentError => 404
+end
+
+class ArticlesController
+  include Lotus::Controller
+
+  configure do
+    handle_exceptions false
+  end
+
+  action 'Create' do
+    def call(params)
+      raise ArgumentError
+    end
+  end
+end
+
+class UsersController
+  include Lotus::Controller
+
+  action 'Create' do
+    def call(params)
+      raise ArgumentError
+    end
+  end
+end
+
+UsersController::Create.new.call({}) # => HTTP 400
+
+ArticlesController::Create.new.call({})
+  # => raises ArgumentError because we set handle_exceptions to false
+```
+
+### Reusability
+
+Lotus::Controller can be used as a singleton framework as seen in this README.
+The application code includes `Lotus::Controller` or `Lotus::Action` directly
+and the configuration is unique per Ruby process.
+
+While this is convenient for tiny applications, it doesn't fit well for more
+complex scenarios, where we want micro applications to coexist together.
+
+```ruby
+require 'lotus/controller'
+
+module WebApp
+  Controller = Lotus::Controller.duplicate
+end
+
+module ApiApp
+  Controller = Lotus::Controller.duplicate(self) do
+    handle_exception ArgumentError => 400
+  end
+end
+```
+
+The code above defines `WebApp::Controller` and `WebApp::Action`, to be used for
+the `WebApp` endpoints, while `ApiApp::Controller` and `ApiApp::Action` have 
+a different configuration.
 
-## Thread safety
+### Thread safety
 
 An Action is **mutable**. When used without Lotus::Router, be sure to instantiate an
 action for each request.