roda 0.9.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ab3cd69eb4146c87b08dc9d58ac4c6cb40e98e71
-  data.tar.gz: f276b865b831438274335aa559ef1cbfe743f045
+  metadata.gz: 6ee4a240b4a2d17e55d10cc84f60b28ffd8fcf76
+  data.tar.gz: 50af03ce96aadac19fa0e9c81e0cb0ea86e90461
 SHA512:
-  metadata.gz: 04b6479269bea8bffa930f735a11d22436d791eb04531ac65248ab88b9eb7096146929c9538ab4589f0160c41839b1c488bfcc71adf0cd6c3fa3376277973b9f
-  data.tar.gz: 603135eaa279af4980f7e799decc28ee288bfbdcb86ebe1ccd66c84ee48c531edbcb032d9f7e1f68d80b08a8a02d1f98cc96e4534f6e7e86b9630428a1f8fc2e
+  metadata.gz: 6f3d44551360e5c38fbbe07826793a7fe986bb6c017bb9136e9494c7a8ec15741b74693f725be32cee455e4d10b6bf4083d44f32e8427b9b76296b5d4dc61090
+  data.tar.gz: db885f610de332b033bb565eadc86239c842e28e49d352cbb45513fed0404b934320ab9b1f9a09b30844e84f08a759cc931dde9ddbba55c1e4b46327f5b4c925

data/CHANGELOG

@@ -1,3 +1,65 @@
+= 1.0.0 (2014-08-19)
+
+* Don't have :extension hash matcher force a terminal match (jeremyevans)
+
+* Add :content option to view method in render plugin to use given content instead of rendering a template (jeremyevans)
+
+* Add :escape option to render plugin for using erb templates where <%= %> escapes and <%== %> does not (jeremyevans)
+
+* Make multi_route plugin route("route_name") method a request method instead of an instance method (jeremyevans)
+
+* Add r.multi_route method to multi_route plugin, for dispatching to named route based on first segment in path (jeremyevans)
+
+* Allow non-GET requests to use r.redirect with no argument, redirecting to current path (jeremyevans)
+
+* Add head plugin, for handling HEAD requests like GET requests with an empty body (jeremyevans)
+
+* Optimize consuming patterns by using a positive lookahead assertion (jeremyevans)
+
+* Add not_allowed plugin, for automatically returning 405 Method Not Allowed responses (jeremyevans)
+
+* Optimize match blocks with no arguments (jeremyevans)
+
+* Add content_for plugin, for storing content in one template and retrieving it in another (jeremyevans)
+
+* Add render_each plugin, for rendering a template for each value in an enumerable (jeremyevans)
+
+* Add backtracking_array plugin, allowing array matchers to backtrack if later matchers do not match (jeremyevans)
+
+* Add :all hash matcher, allowing array matchers to include conditions where you want to match multiple conditions (jeremyevans)
+
+* Add json plugin, allowing match blocks to return arrays/hashes, returning JSON (jeremyevans)
+
+* Add view_subdirs plugin, for setting a subdirectory for views on a per-request basis (jeremyevans)
+
+* Allow default halt method to take no arguments, and use the current response (jeremyevans)
+
+* Add symbol_views plugin, allowing match blocks to return a template name symbol (jeremyevans)
+
+* Add per_thread_caching plugin, for using separate caches per thread instead of shared thread-safe caches (jeremyevans)
+
+* Add hash_matcher class method, for easily creating hash match methods (jeremyevans)
+
+* Add symbol_matchers plugin, for using symbol-specific matching regexps (jeremyevans)
+
+* Add csrf plugin for csrf protection using rack_csrf (jeremyevans)
+
+* Optimize r.is, r.get, r.post and similar methods by reducing the number of Array objects created (jeremyevans)
+
+* Support RequestClassMethods and ResponseClassMethods in plugins (jeremyevans)
+
+* Add Roda::RodaCache for a thread safe cache, currently used for match patterns, templates, and plugins (jeremyevans)
+
+* Optimize matching by caching consume regexp for strings, regexp, symbol, and :extension matchers (jeremyevans)
+
+* Add r.root for GET / requests, for easier to read version of r.get "" (jeremyevans)
+
+* Optimize r.is terminal matcher, remove :term hash matcher (jeremyevans)
+
+* Make flash plugin no longer depend on sinatra-flash (jeremyevans)
+
+* Move version file to roda/version so it can be required separately without loading dependencies (jeremyevans)
+
 = 0.9.0 (2014-07-30)
 
 * Initial public release

data/README.rdoc

@@ -14,6 +14,16 @@ Bugs :: http://github.com/jeremyevans/roda/issues
 Google Group :: http://groups.google.com/group/ruby-roda
 IRC :: irc://chat.freenode.net/#roda
 
+== Inspiration
+
+Roda was inspired by {Sinatra}[http://www.sinatrarb.com] and {Cuba}[http://cuba.is],
+two other Ruby web frameworks.  It started out as a fork of Cuba, from which it borrows
+the idea of using a routing tree (which Cuba in turn took from
+{Rum}[https://github.com/chneukirchen/rum]).  From Sinatra it takes the ideas that
+route blocks should return the request bodies and that routes should be canonical.
+It pilfers the idea for an extensible plugin system from the Ruby database library
+{Sequel}[http://sequel.jeremyevans.net].
+
 == Usage
 
 Here's a simple application, showing how the routing tree works:
@@ -25,25 +35,30 @@ Here's a simple application, showing how the routing tree works:
     use Rack::Session::Cookie, :secret => ENV['SECRET']
 
     route do |r|
-      # matches any GET request
-      r.get do
+      # GET / request
+      r.root do
+        r.redirect "/hello"
+      end
 
-        # matches GET /
-        r.is "" do
-          r.redirect "/hello"
-        end
+      # /hello branch
+      r.on "hello" do
 
-        # matches GET /hello or GET /hello/.*
-        r.on "hello" do
+        # GET /hello/world request
+        r.get "world" do
+          "Hello world!"
+        end
 
-          # matches GET /hello/world
-          r.is "world" do
-            "Hello world!"
+        # /hello request
+        r.is do
+          # GET /hello request
+          r.get do
+            "Hello!"
           end
 
-          # matches GET /hello
-          r.is do
-            "Hello!"
+          # POST /hello request
+          r.post do
+            puts "Someone said hello!"
+            r.redirect
           end
         end
       end
@@ -52,8 +67,6 @@ Here's a simple application, showing how the routing tree works:
 
   run App.app
 
-You can now run +rackup+ and enjoy what you have just created.
-
 Here's a breakdown of what is going on in the above block:
 
 After requiring the library and subclassing Roda, the +use+ method
@@ -66,34 +79,120 @@ with some additional methods for matching routes.  By
 convention, this argument should be named +r+.
 
 The primary way routes are matched in Roda is by calling
-+r.on+, or a method like +r.get+ or +r.is+ which calls +r.on+.
-+r.on+ takes each of the arguments given and tries to match them to
-the current request.  If it is able to successfully match
-all of the arguments, it yields to the +r.on+ block, otherwise
-it returns immediately.
-
-+r.get+ is a shortcut that matches any GET request, and
-+r.is+ is a shortcut that ensures the the exact route is
-matched and there are no further entries in the path.
-
-If +r.on+ matches and control is yielded to the block, whenever
-the block returns, the response will be returned.  If the block
-returns a string and the response body hasn't already been
-written to, the block return value will interpreted as the body
-for the response.  If none of the +r.on+ blocks match and the
-route block returns a string, it will be interpreted as the body
-for the response.
++r.on+, +r.is+, +r.root+, +r.get+, or +r.post+.  These methods are
+calling the routing methods, and each of them takes a block. The
+block is referred to as a match block.
+
+Each routing method takes each of the arguments (called matchers)
+given and tries to match them to the current request.  If it is
+able to match all of the arguments, it yields to the match block,
+otherwise the block is skipped and execution continues.
+
++r.on+ matches if all of the arguments match.
++r.is+ matches if all of the arguments match, and there are no
+further entries in the path after matching.
++r.get+ when called without arguments matches any +GET+ request.
++r.get+ when called with any arguments matches only if the
+current request is a +GET+ request and there are no further entries
+in the path after matching.
++r.root+ only matches a +GET+ request where the current path is +/+.
+
+If a routing method matches and control is yielded to the match
+block, whenever the match block returns, Roda will return the
+rack response array of status, headers, and body, to the caller.
+
+If the match block returns a string and the response body hasn't
+already been written to, the block return value will interpreted
+as the body for the response.  If none of the routing methods match
+and the route block returns a string, it will be interpreted as the
+body for the response.
 
 +r.redirect+ immediately returns the response, allowing for
-code such as <tt>r.redirect(path) if some_condition</tt>.
+code such as <tt>r.redirect(path) if some_condition</tt>. If
+called without arguments, it redirects to the current path if
+the current request method is not +GET+.
 
 The +.app+ at the end is an optimization, which you can leave
 off, but which saves a few methods call for every response.
 
+== The Routing Tree
+
+Roda is called a routing tree web framework because the way most
+sites are structured, routing takes the form of a tree based on the
+URL structure of the site.  In general, +r.on+ is used to split the
+tree into different branches, and +r.is+ is finalizes the routing,
+where the request is actually handled.
+
+So a simple routing tree may look something like this:
+
+  r.on "a" do           # /a branch
+    r.on "b" do         # /a/b branch
+      r.is "c" do       # /a/b/c request
+        r.get do end    # GET /a/b/c request
+        r.post do end   # POST /a/b/c request
+      end
+      r.get "d" do end  # GET /a/b/d request
+      r.post "e" do end # POST /a/b/e request
+    end
+  end
+
+It's also possible to handle the same requests, but structure the
+routing tree by first branching on the request method:
+
+  r.get do              # GET 
+    r.on "a" do         # GET /a branch
+      r.on "b" do       # GET /a/b branch
+        r.is "c" do end # GET /a/b/c request
+        r.is "d" do end # GET /a/b/d request
+      end
+    end
+  end
+
+  r.post do             # POST
+    r.on "a" do         # POST /a branch
+      r.on "b" do       # POST /a/b branch
+        r.is "c" do end # POST /a/b/c request
+        r.is "e" do end # POST /a/b/e request
+      end
+    end
+  end
+
+This allows you to easily separate your +GET+ request handling from
+your +POST+ request handling.  If you only have a small number of
++POST+ request URLs and a large number of +GET+ request URLs, this
+may make things easier.
+
+However, in general routing first by the path and last by the
+request method is likely to lead to simpler and DRYer code. This
+is because at any point during the routing, you can act on the
+request.  For example, if all requests in the +/a+ branch need
+need access permission +A+ and all requests in the +/a/b+ branch
+need access permission +B+, you can easily handle this in the
+routing tree:
+
+  r.on "a" do           # /a branch
+    check_perm(:A)  
+    r.on "b" do         # /a/b branch
+      check_perm(:B)  
+      r.is "c" do       # /a/b/c request
+        r.get do end    # GET /a/b/c request
+        r.post do end   # POST /a/b/c request
+      end
+      r.get "d" do end  # GET /a/b/d request
+      r.post "e" do end # POST /a/b/e request
+    end
+  end
+
+Being able to operate on the request at any point during the
+the routing is one of the major advantages of Roda compared
+to other web frameworks that do not use a routing tree.
+
 == Matchers
 
-Here's an example showcasing how different matchers work.  Matchers
-are arguments passed to +r.on+.
+Other than +r.root+, the routing methods all take arguments called
+matchers.  If all of the matchers match, the routing method yields to
+the match block.  Here's an example showcasing how different
+matchers work:
 
   class App < Roda
     route do |r|
@@ -101,7 +200,7 @@ are arguments passed to +r.on+.
       r.get do
 
         # /
-        r.is "" do
+        r.root do
           "Home"
         end
 
@@ -126,7 +225,6 @@ are arguments passed to +r.on+.
 
           # /username/foobar/posts
           r.is "posts" do
-
             # You can access user here, because the blocks are closures.
             "Total Posts: #{user.posts.size}" #=> "Total Posts: 6"
           end
@@ -148,7 +246,7 @@ are arguments passed to +r.on+.
         r.is "login" do
 
           # POST /login, user: foo, pass: baz
-          r.on {:param=>"user"}, {:param=>"pass"} do |user, pass|
+          r.on({:param=>"user"}, {:param=>"pass"}) do |user, pass|
             "#{user}:#{pass}" #=> "foo:baz"
           end
 
@@ -170,75 +268,75 @@ The +/+ here is considered the empty segment.
 If it does not contain a colon or slash, it matches single segment
 with the text of the string, preceeded by a slash.
 
-  "" matches "/"
-  "foo" matches "/foo"
-  "foo" does not match "/food"
+  ""    # matches "/"
+  "foo" # matches "/foo"
+  "foo" # does not match "/food"
 
 If it contains any slashes, it matches one additional segment for
 each slash:
 
-  "foo/bar" matches "/foo/bar"
-  "foo/bar" does not match "/foo/bard"
+  "foo/bar" # matches "/foo/bar"
+  "foo/bar" # does not match "/foo/bard"
 
 If it contains a colon followed by any <tt>\\w</tt> characters, the colon and
 remaing <tt>\\w</tt> characters matches any nonempty segment that contains at
 least one character:
 
-  "foo/:id" matches "/foo/bar", "/foo/baz", etc.
-  "foo/:id" does not match "/fo/bar"
+  "foo/:id" # matches "/foo/bar", "/foo/baz", etc.
+  "foo/:id" # does not match "/fo/bar"
 
 You can use multiple colons in a string:
 
-  ":x/:y" matches "/foo/bar", "/bar/foo" etc.
-  ":x/:y" does not match "/foo", "/bar/"
+  ":x/:y" # matches "/foo/bar", "/bar/foo" etc.
+  ":x/:y" # does not match "/foo", "/bar/"
 
 You can prefix colons:
 
-  "foo:x/bar:y" matches "/food/bard", "/fool/bart", etc.
-  "foo:x/bar:y" does not match "/foo/bart", "/fool/bar", etc.
+  "foo:x/bar:y" # matches "/food/bard", "/fool/bart", etc.
+  "foo:x/bar:y" # does not match "/foo/bart", "/fool/bar", etc.
 
 If any colons are used, the block will yield one argument for
 each segment matched containing the matched text.  So:
 
-  "foo:x/:y" matching "/fool/bar" yields "l", "bar"
+  "foo:x/:y" # matching "/fool/bar" yields "l", "bar"
 
 Colons that are not followed by a <tt>\\w</tt> character are matched literally:
 
-  ":/a" matches "/:/a"
+  ":/a" # matches "/:/a"
 
 Note that strings are regexp escaped before being used in a regular
 expression, so:
 
-  "\\d+(/\\w+)?" matches "\d+(/\w+)?"
-  "\\d+/\\w+" does not match "123/abc"
+  "\\d+(/\\w+)?" # matches "/\d+(/\w+)?"
+  "\\d+(/\\w+)?" # does not match "/123/abc"
 
 === Regexp
 
 Regexps match one or more segments by looking for the pattern preceeded by a
 slash:
 
-  /foo\w+/ matches "/foobar"
-  /foo\w+/ does not match "/foo/bar"
+  /foo\w+/ # matches "/foobar"
+  /foo\w+/ # does not match "/foo/bar"
 
 If any patterns are captured by the regexp, they are yielded:
 
-  /foo\w+/ matches "/foobar", yields nothing
-  /foo(\w+)/ matches "/foobar", yields "bar" 
+  /foo\w+/   # matches "/foobar", yields nothing
+  /foo(\w+)/ # matches "/foobar", yields "bar" 
 
 === Symbol
 
 Symbols match any nonempty segment, yielding the segment except for the
 preceeding slash:
 
-  :id matches "/foo" yields "foo"
-  :id does not match "/"
+  :id # matches "/foo" yields "foo"
+  :id # does not match "/"
 
 === Proc
 
 Procs match unless they return false or nil:
 
-  proc{true} matches anything
-  proc{false} does not match anything
+  proc{true}  # matches anything
+  proc{false} # does not match anything
 
 Procs don't capture anything by default, but they can if you add
 the captured text to +r.captures+.
@@ -253,75 +351,81 @@ condition).  Evaluation stops at the first matcher that matches.
 Additionally, if the matched object is a String, the string is yielded.
 This makes it easy to handle multiple strings without a Regexp:
 
-  %w'page1 page2' matches "/page1", "/page2"
-  [] does not match anything
+  ['page1', 'page2'] # matches "/page1", "/page2"
+  []                 # does not match anything
 
 === Hash
 
-Hashes call a <tt>match_*</tt> method with the given key using the hash value,
-and match if that matcher returns true.
-
+Hashes allow easily calling specialized match methods on the request.
 The default registered matchers included with Roda are documented below.
-You can add your own hash matchers by adding the appropriate <tt>match_*</tt>
-method to the request class using the +request_module+ method:
+You can add your own hash matchers using the +hash_matcher+ class method,
+which creates an appropriate request match method.  The +hash_matcher+
+block will be called with the value of the hash.
 
   class App < Roda
-    request_module do
-      def match_foo(v)
-        ...
-      end
+    hash_matcher(:foo) do |v|
+      # ...
     end
-
+    
     route do |r|
       r.on :foo=>'bar' do
-        ...
+        # ...
       end
     end
   end
 
+==== :all
+
+The :all matcher matches if all of the entries in the given array matches. So
+
+  r.on :all=>[:a, :b] do
+    # ...
+  end
+
+is the same as:
+
+  r.on :a, :b do
+    # ...
+  end
+
+The reason it also exists as a separate hash matcher is so you can use it inside
+an array matcher. so:
+
+  r.on ['foo', {:all=>['foos', :id]}] do
+  end
+
+Would match +/foo+ and +/foos/10+, but not +/foos+.
 
 ==== :extension
 
 The :extension matcher matches any nonempty path ending with the given extension:
 
-  :extension => "css" matches "/foo.css", "/bar.css"
-  :extension => "css" does not match "/foo.css/x", "/foo.bar", "/.css"
+  {:extension => "css"} # matches "/foo.css", "/bar.css"
+  {:extension => "css"} # does not match "/foo.css/x", "/foo.bar", "/.css"
 
-This matcher yields the part before the extension.  Note that unlike other
-matchers, this matcher assumes terminal behavior, it doesn't match if there
-are additional segments.
+This matcher yields the part before the extension.
 
 ==== :method
 
 This matches the method of the request.  You can provide an array to specify multiple
 request methods and match on any of them:
 
-  :method => :post matches POST
-  :method => %w'post patch' matches POST and PATCH
+  {:method => :post}             # matches POST
+  {:method => ['post', 'patch']} # matches POST and PATCH
 
 ==== :param
 
 The :param matcher matches if the given parameter is present, even if empty.
 
-  :param => "user" matches "/foo?user=bar", "/foo?user="
-  :param => "user" does not matches "/foo"
+  {:param => "user"} # matches "/foo?user=bar", "/foo?user="
+  {:param => "user"} # does not matches "/foo"
 
 ==== :param!
 
 The :param! matcher matches if the given parameter is present and not empty.
 
-  :param! => "user" matches "/foo?user=bar"
-  :param! => "user" does not matches "/foo", "/foo?user="
-
-==== :term
-
-The :term matcher matches if true and there are no segments left.  This matcher is
-added by +r.is+ to ensure an exact path match.
-
-  :term => true matches ""
-  :term => true does not match "/"
-  :term => false matches "/"
-  :term => false does not match ""
+  {:param! => "user"} # matches "/foo?user=bar"
+  {:param! => "user"} # does not matches "/foo", "/foo?user="
 
 === false, nil
 
@@ -343,35 +447,8 @@ You can always set the status code manually via the status attribute
 for the response.
 
   route do |r|
-    r.get do
-      r.is "hello" do
-        response.status = 200
-      end
-    end
-  end
-
-== Security
-
-If you want to protect against some common web application
-vulnerabilities, you can use
-{Rack::Protection}[https://github.com/rkh/rack-protection].
-It is not included by default because there are legitimate
-uses for plain Roda (for instance, when designing an API).
-
-If you are using sessions, you should also always set a session
-secret to some undisclosed value. Keep in mind that the content
-in the session cookie is not encrypted, just signed to prevent
-tampering.
-
-  require "roda"
-  require "rack/protection"
-
-  class App < Roda
-    use Rack::Session::Cookie, :secret => ENV['SECRET']
-    use Rack::Protection
-
-    route do |r|
-      # ...
+    r.get "hello" do
+      response.status = 200
     end
   end
 
@@ -379,22 +456,27 @@ tampering.
 
 The main match method is +r.on+, but as displayed above, you can also
 use +r.get+ or +r.post+.  When called without any arguments, these
-call +r.on+ as long as the request has the appropriate method, so:
+match as long as the request has the appropriate method, so:
+
+  r.get do end
+
+matches any +GET+ request, and
 
-    r.get{}
+  r.post do end
 
-is syntax sugar for:
+matches any +POST+ request
 
-    r.on{} if r.get? 
+If any arguments are given to the method, these match only
+if the request method matches, all arguments match, and
+only the path has been fully matched by the arguments.  So:
 
-If any arguments are given to the method, these call +r.is+ as long as
-the request has the appropriate method, so:
+  r.post "" do end
 
-    r.post(""){}
+matches only +POST+ requests where the current path is +/+.
 
-is syntax sugar for:
+  r.get "a/b" do end
 
-    r.is(""){} if r.post?
+matches only +GET+ requests where the current path is +/a/b+.
 
 The reason for this difference in behavior is that if you are not
 providing any arguments, you probably don't want to to also test
@@ -407,11 +489,26 @@ you do want, you can provide true as an argument:
   end
 
 If you want to match the request method and do a partial match
-on the request path, you need to use +r.on+ with the <tt>:method</tt>
-hash matcher:
+on the request path instead of a full match, you need to use
++r.on+ with the <tt>:method</tt> hash matcher:
 
   r.on "foo", :method=>:get do # Matches GET /foo(/.*)?
-  edn
+  end
+
+== Root Method
+
+As displayed above, you can also use +r.root+ as a match method.  This
+method matches +GET+ requests where the current path +/+.  +r.root+ is
+similar to <tt>r.get ""</tt>, except that it does not consume the +/+ from the path.
+
+Unlike the other matching methods, +r.root+ takes no arguments.
+
+Note that +r.root+ does not match if the path is empty, you should use
+<tt>r.get true</tt> for that.  If you want to match either the
+the empty path or +/+, you can use <tt>r.get ["", true]</tt>.
+
+Note that +r.root+ does not match non-GET requests, so to handle
+<tt>POST /</tt> requests, use <tt>r.post ''</tt>.
 
 == Request and Response
 
@@ -430,8 +527,8 @@ methods, or via plugins.
 
 == Pollution
 
-Roda tries very hard to avoid polluting the scope in which the +route+
-block operates.  The only instance variables defined by default in the scope of
+Roda tries very hard to avoid polluting the scope of the +route+
+block.  The only instance variables defined by default in the scope of
 the +route+ block are <tt>@_request</tt> and <tt>@_response</tt>.  The only methods defined
 (beyond the default methods for +Object+) are: +env+, +opts+, +request+,
 +response+, +call+, +session+, and +_route+ (private). Constants inside the
@@ -468,8 +565,8 @@ in the request (via POST or QUERY_STRING) and it pushes the value as a capture.
 
 == Composition
 
-You can mount a Roda app, along with middlewares, inside another Roda app,
-via +r.run+:
+You can mount any Rack app (including another Roda app), with its own middlewares,
+inside a Roda app, using +r.run+:
 
   class API < Roda
     use SomeMiddleware
@@ -491,13 +588,24 @@ via +r.run+:
 
   run App.app
 
-You can also use the +multi_route+ plugin, which keeps the current scope of
+This will take any path starting with +/api+ and send it to +API+.  In this
+example, +API+ is a Roda app, but it could easily be a Sinatra, Rails, or
+other Rack app.
+
+When you use +r.run+, Roda calls the given Rack app (+API+ in this
+case), and whatever the Rack app returns will be returned as the response
+for the current application.
+
+=== multi_route plugin
+
+If you are just looking to split up the main route block up by branches, you
+should use the +multi_route+ plugin, which keeps the current scope of
 the route block:
 
   class App < Roda
     plugin :multi_route
 
-    route :api do |r|
+    route "api" do |r|
       r.is do
         # ...
       end
@@ -505,19 +613,22 @@ the route block:
 
     route do |r|
       r.on "api" do
-        route :api
+        r.route "api"
       end
     end
   end
 
   run App.app
 
+This allows you to set instance variables in the main route block, and still
+have access to them inside the +api+ route block.
+
 == Testing
 
 It is very easy to test Roda with {Rack::Test}[https://github.com/brynary/rack-test]
-or {Capybara}[https://github.com/jnicklas/capybara]. Roda's own tests are written
-with a combination of {RSpec}[http://rspec.info] and Rack::Test
-The default rake task will run the specs for Roda, if RSpec is installed.
+or {Capybara}[https://github.com/jnicklas/capybara]. Roda's own tests use
+{RSpec}[http://rspec.info].  The default rake task will run the specs for Roda, if
+RSpec is installed.
 
 == Settings
 
@@ -584,11 +695,84 @@ You can override the default rendering options by passing a hash to the plugin,
 or modifying the +render_opts+ hash after loading the plugin:
 
   class App < Roda
-    plugin :render, :engine=>'slim' # Tilt engine/template file extension to use
+    plugin :render, :escape => true # Automatically escape output in erb templates
     render_opts[:views] = 'admin_views' # Default views directory
     render_opts[:layout] = "admin_layout" # Default layout template
     render_opts[:layout_opts] = {:engine=>'haml'} # Default layout template options
     render_opts[:opts] = {:default_encoding=>'UTF-8'} # Default template options
+    render_opts[:cache] = false # Disable template caching
+    render_opts[:engine] = 'slim' # Tilt engine/template file extension to use
+  end
+
+== Sessions
+
+By default, Roda doesn't turn on sessions, but most users are going to
+want to turn on session support, and the simplest way to do that is to
+use the <tt>Rack::Session::Cookie</tt> middleware that comes with rack:
+
+  require "roda"
+
+  class App < Roda
+    use Rack::Session::Cookie, :secret => ENV['SECRET']
+  end
+
+== Security
+
+Web application security is a very large topic, but here are some
+things you can do with Roda to prevent some common web application
+vulnerabilities.
+
+=== Session Security
+
+If you are using sessions, you should also always set a session
+secret using the +:secret+ option as shown above.  Make sure this
+secret is not disclosed, because if an attacker knows the +:secret+
+value, they can inject arbitrary session values, which in the worst case
+scenario can lead to remote code execution.
+
+Keep in mind that with <tt>Rack::Session::Cookie</tt>, the content in
+the session cookie is not encrypted, just signed to prevent tampering.
+This means you should not store any data in the session that itself is
+secret.
+
+=== Cross Site Request Forgery (CSRF)
+
+CSRF can be prevented by using the +csrf+ plugin that ships with Roda,
+which uses the {rack_csrf}[https://github.com/baldowl/rack_csrf]
+library.  Just make sure that you include the CSRF token tags in your
+html as appropriate.
+
+It's also possible to use the <tt>Rack::Csrf</tt> middleware directly,
+you don't have to use the +csrf+ plugin.
+
+=== Cross Site Scripting (XSS)
+
+The easiest way to prevent XSS with Roda is to use a template library
+that automatically escapes output by default.  The +:escape+ option
+to the render plugin sets the ERB template processor to escape by
+default, so that in your templates:
+
+  <%= '<>' %>  # outputs &lt;&gt; 
+  <%== '<>' %> # outputs <>
+
+Note that unlike most other render options, the :escape option
+must be passed to the <tt>plugin :render</tt> call, it won't be
+respected if added later.
+
+This support requires {Erubis}[http://www.kuwata-lab.com/erubis/].
+
+=== Other
+
+For prevention of some other vulnerabilities, such as click-jacking,
+directory traversal, session hijacking, and IP spoofing, consider using
+{Rack::Protection}[https://github.com/rkh/rack-protection], which is
+a rack middleware that can be added the usual way:
+
+  require 'roda'
+  require 'rack/protection'
+
+  class App < Roda
+    use Rack::Protection
   end
 
 == Plugins
@@ -601,27 +785,46 @@ override any Roda method and call +super+ to get the default behavior.
 These plugins ship with roda:
 
 all_verbs :: Adds routing methods to the request for all http verbs.
+backtracking_array :: Allows array matchers to backtrack if later matchers
+                      do not match.
+content_for :: Allows storage of content in one template and retrieval of
+               that content in a different template.
+csrf :: Adds CSRF protection and helper methods using
+        {rack_csrf}[https://github.com/baldowl/rack_csrf].
 default_headers :: Override the default response headers used.
 error_handler :: Adds a +error+ block that is called for all responses that
                  raise exceptions.
-flash :: Adds a flash handler, requires sinatra-flash.
+flash :: Adds a flash handler.
 h :: Adds h method for html escaping.
 halt :: Augments request#halt method to take status and/or body or status,
         headers, and body.
+head :: Treat HEAD requests like GET requests with an empty response body.
 header_matchers :: Adds host, header, and accept hash matchers.
 hooks :: Adds before and after methods to run code before and after requests.
 indifferent_params :: Adds params method with indifferent access to params,
                       allowing use of symbol keys for accessing params.
+json :: Allows match blocks to return arrays and hashes, using a json
+        representation as the response body.
 middleware :: Allows the Roda app to be used as a rack middleware, calling the
               next middleware if no route matches.
 multi_route :: Adds the ability for multiple named route blocks, with the
                ability to dispatch to them add any point in the main route block.
+not_allowed :: Adds support for automatically returning 405 Method Not Allowed
+               responses.
 not_found :: Adds a +not_found+ block that is called for all 404 responses
              without bodies.
 pass :: Adds a pass method allowing you to skip the current +r.on+ block as if
         it did not match.
+per_thread_caching :: Switches the thread-safe cache from a shared cache to a
+                      per-thread cache.
 render :: Adds support for rendering templates via tilt, as described above.
+render_each :: Render a template for each value in an enumerable.
 streaming :: Adds support for streaming responses.
+symbol_matchers :: Adds support for symbol-specific matching regexps.
+symbol_views :: Allows match blocks to return template name symbols, uses the
+                template view as the response body.
+view_subdirs :: Allows for setting a view subdirectory to use on a per-request
+                basis.
 
 === External Plugins
 
@@ -633,13 +836,15 @@ autoforme :: Adds support for easily creating a simple administrative front
 
 === How to create plugins
 
-Authoring your own plugins is pretty straightforward.  Plugins are just modules
-that contain one of the following modules:
+Authoring your own plugins is pretty straightforward.  Plugins are just modules,
+which may contain any of the following modules:
 
 InstanceMethods :: module included in the Roda class
 ClassMethods :: module that extends the Roda class
 RequestMethods :: module included in the class of the request
+RequestClassMethods :: module extending the class of the request
 ResponseMethods :: module included in the class of the response
+ResponseClassMethods :: module extending the class of the response
 
 If the plugin responds to +load_dependencies+, it will be called first, and should
 be used if the plugin depends on another plugin.
@@ -667,9 +872,9 @@ So a simple plugin to add an instance method would be:
 If you want to ship a Roda plugin in a gem, but still have
 Roda load it automatically via <tt>Roda.plugin :plugin_name</tt>, you should
 place it where it can be required via +roda/plugins/plugin_name+, and
-then have the file register it as a plugin via +Roda.register_plugin+.
-It's recommended but not required that you store your plugin module
-in the <tt>Roda::RodaPlugins</tt> namespace:
+then have the file register it as a plugin via
+<tt>Roda::RodaPlugins.register_plugin</tt>.  It's recommended but not required
+that you store your plugin module in the <tt>Roda::RodaPlugins</tt> namespace:
 
   module Roda
     module RodaPlugins
@@ -680,26 +885,16 @@ in the <tt>Roda::RodaPlugins</tt> namespace:
           end
         end
       end
-    end
 
-    register_plugin :markdown, RodaPlugins::Markdown
+      register_plugin :markdown, Markdown
+    end
   end
 
 You should avoid creating your module directly in the +Roda+ namespace
 to avoid polluting the namespace.  Additionally, any instance variables
-created inside an InstanceMethods should be prefixed with an underscore
+created inside InstanceMethods should be prefixed with an underscore
 (e.g. <tt>@_variable</tt>) to avoid polluting the scope.
 
-== Inspiration
-
-Roda was inspired by {Sinatra}[http://www.sinatrarb.com] and {Cuba}[http://cuba.is],
-two other Ruby web frameworks.  It started out as a fork of Cuba, from which it borrows
-the idea of using a routing tree (which Cuba in turn took from
-{Rum}[https://github.com/chneukirchen/rum]).  From Sinatra it takes the ideas that
-route blocks should return the request bodies and that routes should be canonical.
-It pilfers the idea for an extensible plugin system from the Ruby database library
-{Sequel}[http://sequel.jeremyevans.net].
-
 == License
 
 MIT