roda 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3d246589728bb46404806737bb7e67819956f167
-  data.tar.gz: e57198e8df759bd70039ff42f94d86583c75c2f8
+  metadata.gz: 1ec447de1d1c9201190d3e05cddc9ca3aca957e4
+  data.tar.gz: fc6e061b744a3ed47259369907bb82e222d12515
 SHA512:
-  metadata.gz: 3127e9f7b7525780556555366e82b0e9f565216e62dacdd5e3e7a69e3440a47771ddad5472b94f7c09d15cf6acb49c7bcdb54fb1d469f68569eb5cf77e589dca
-  data.tar.gz: f6dd7cda1372931ce0bf92934d584e084f8b1b84d5a181ce1b28bcf951983adce7c477e6b4bdabdad9a8f0038cacafa49ba87948b46a38de0ad23b0b1330d86c
+  metadata.gz: a5d0a587873870952a81b8df6a0828c76d68e2de2ff6d388f1ccbf82da5b45815722460ba51a540d1cf74f11fa7911b45d6e7928515901095eb08a8d76754ade
+  data.tar.gz: 33f7d3837fdf5b846169597868531493e00cf1089b2d68771e2b9ea1345603adb3462ca8283735ab393721ddb461467a0813cb9b05d13cdda869d8d62aaf143f

data/CHANGELOG

@@ -1,3 +1,45 @@
+= 1.3.0 (2015-01-13)
+
+* Make static_path_info plugin restore original SCRIPT_NAME/PATH_INFO before returning from r.run (jeremyevans)
+
+* Add RodaMajorVersion, RodaMinorVersion, and RodaPatchVersion (jeremyevans)
+
+* Add delete_empty_headers plugin for deleting response headers that are empty before return response (jeremyevans)
+
+* Make freeze class method freeze internal data structures to avoid thread safety issues (jeremyevans)
+
+* Deprecate mutating plugin option hashes for chunked, default_headers, error_email, json, and render plugins (jeremyevans)
+
+* Fix subclassing app and using r.multi_run in subclass in multi_run plugin (jeremyevans)
+
+* Support :classes option in json plugin to set the classes to use (jeremyevans)
+
+* Improve performance in default_headers plugin by not duping the headers (jeremyevans)
+
+* Use :template_opts instead of :opts for providing options to the template in the render plugin (jeremyevans)
+
+* Support :match_header_yield Roda option in the header_matchers plugin, causing the :header match to yield the value (jeremyevans)
+
+* Move :param and :param! hash matchers to the param_matchers plugin (jeremyevans)
+
+* Add path_matchers plugin, for :extension, :prefix, and :suffix hash matchers (jeremyevans)
+
+* Move Roda.hash_matcher to hash_matcher plugin (jeremyevans)
+
+* Move Roda.request_module and .response_module to module_include plugin (jeremyevans)
+
+* Move RodaResponse#set_cookie and #delete_cookie to cookies plugin (jeremyevans)
+
+* Deprecate RodaRequest#full_path_info, use #path instead (jeremyevans)
+
+* Add class_delegate to the delegate plugin (jeremyevans)
+
+* Make not_found plugin clear headers for response if it is not found (jeremyevans)
+
+* Make error_handler plugin use a new response instead of reusing existing response (jeremyevans)
+
+* Make RodaResponse a subclass of Object instead of Rack::Response (jeremyevans)
+
 = 1.2.0 (2014-12-17)
 
 * Don't override explicit nil :default_encoding template option in the render plugin (jeremyevans)

data/README.rdoc

@@ -66,7 +66,7 @@ Here's a simple application, showing how the routing tree works:
     end
   end
 
-  run App.app
+  run App.freeze.app
 
 Here's a breakdown of what is going on in the block above:
 
@@ -111,8 +111,10 @@ allowing for code such as <tt>r.redirect(path) if some_condition</tt>.
 If +r.redirect+ is called without arguments
 and the current request method is not +GET+, it redirects to the current path.
 
-The +.app+ at the end is an (optional) optimization.
-It saves a few method calls for every response.
+The +.freeze.app+ at the end is optional.  Freezing the app avoids any possible
+thread safety issues inside the application at runtime, which shouldn't be possible
+anyway.  This generally should only be done in production mode.
+The +.app+ is an optimization, which saves a few method calls for every request.
 
 == The Routing Tree
 
@@ -195,63 +197,51 @@ Here's an example showcasing how different matchers work:
 
   class App < Roda
     route do |r|
-      # only GET requests
-      r.get do
-
-        # /
-        r.root do
-          "Home"
-        end
-
-        # /about
-        r.is "about" do
-          "About"
-        end
-
-        # /styles/basic.css
-        r.is "styles", :extension => "css" do |file|
-          "Filename: #{file}" #=> "Filename: basic"
-        end
+      # GET /
+      r.root do
+        "Home"
+      end
 
-        # /post/2011/02/16/hello
-        r.is "post/:y/:m/:d/:slug" do |y, m, d, slug|
-          "#{y}-#{m}-#{d} #{slug}" #=> "2011-02-16 hello"
-        end
+      # GET /about
+      r.get "about" do
+        "About"
+      end
 
-        # /username/foobar
-        r.on "username/:username" do |username|
-          user = User.find_by_username(username) # username == "foobar"
+      # GET /post/2011/02/16/hello
+      r.get "post/:y/:m/:d/:slug" do |y, m, d, slug|
+        "#{y}-#{m}-#{d} #{slug}" #=> "2011-02-16 hello"
+      end
 
-          # /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
+      # GET /username/foobar branch
+      r.on "username/:username", :method=>:get do |username|
+        user = User.find_by_username(username)
 
-          # /username/foobar/following
-          r.is "following" do
-            user.following.size.to_s #=> "1301"
-          end
+        # GET /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
 
-        # /search?q=barbaz
-        r.is "search", :param=>"q" do |query|
-          "Searched for #{query}" #=> "Searched for barbaz"
+        # GET /username/foobar/following
+        r.is "following" do
+          user.following.size.to_s #=> "1301"
         end
       end
 
-      # only POST requests
-      r.post do
-        r.is "login" do
+      # /search?q=barbaz
+      r.get "search" do
+        "Searched for #{r['q']}" #=> "Searched for barbaz"
+      end
 
-          # POST /login, user: foo, pass: baz
-          r.on({:param=>"user"}, {:param=>"pass"}) do |user, pass|
-            "#{user}:#{pass}" #=> "foo:baz"
-          end
+      r.is "login" do
+        # GET /login
+        r.get do
+          "Login"
+        end
 
-          # If the params user and pass are not provided, this
-          # will get executed.
-          "You need to provide user and pass!"
+        # POST /login?user=foo&password=baz
+        r.post do
+          "#{r['user']}:#{r['password']}" #=> "foo:baz"
         end
       end
     end
@@ -355,11 +345,12 @@ This makes it easy to handle multiple strings without a Regexp:
 
 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 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.
+Some plugins add additional hash matchers, and the hash_matcher plugin
+allows for easily defining your own:
 
   class App < Roda
+    plugin :hash_matcher
+
     hash_matcher(:foo) do |v|
       # ...
     end
@@ -393,15 +384,6 @@ is so you can use it inside an array matcher, so:
 
 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"
-
-This matcher yields the part found before the period and extension (e.g., +foo+).
-
 ==== :method
 
 The +:method+ matcher matches the method of the request.
@@ -410,20 +392,6 @@ You can provide an array to specify multiple request methods and match on any of
   {:method => :post}             # matches POST
   {:method => ['post', 'patch']} # matches POST and PATCH
 
-==== :param
-
-The +:param+ matcher matches if the given parameter is present (even if it is empty).
-
-  {: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="
-
 === false, nil
 
 If +false+ or +nil+ is given directly as a matcher, it doesn't match anything.
@@ -452,8 +420,11 @@ via the +status+ attribute for the response.
 
 == Verb Methods
 
-The main match method is +r.on+, but as displayed above,
-you can also use +r.get+ or +r.post+.
+As displayed above, Roda has +r.get+ and +r.post+ methods
+for matching based on the HTTP request method.  If you want
+to match on other HTTP request methods, use the all_verbs
+plugin.
+
 When called without any arguments, these match as long
 as the request has the appropriate method, so:
 
@@ -467,7 +438,7 @@ matches any +POST+ request
 
 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:
+the path has been fully matched by the arguments, so:
 
   r.post "" do end
 
@@ -506,7 +477,8 @@ 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>.
+you can use <tt>r.get ["", true]</tt>, or use the slash_path_empty
+plugin.
 
 Note that +r.root+ only matches +GET+ requests.
 So, to handle <tt>POST /</tt> requests, use <tt>r.post ''</tt>.
@@ -519,17 +491,15 @@ Likewise, the response object is available via the +response+ method.
 
 The request object is an instance of a subclass of <tt>Rack::Request</tt>,
 with some additional methods.
-The response object is an instance of a subclass of <tt>Rack::Response</tt>,
-with some additional methods.
 
 If you want to extend the request and response objects with additional modules,
-you can do so via the +request_module+ or +response_module+ methods, or via plugins.
+you can use the module_include plugin.
 
 == Pollution
 
 Roda tries very hard to avoid polluting the scope of the +route+ block.
 This should make it unlikely that Roda will cause namespace issues
-with your application code:
+with your application code.  Some of the things Roda does
 
 - The only instance variables defined by default in the scope of the +route+ block
   are <tt>@_request</tt> and <tt>@_response</tt>.
@@ -538,40 +508,12 @@ with your application code:
 - Constants inside the Roda namespace are all prefixed with +Roda+
   (e.g., <tt>Roda::RodaRequest</tt>).
 
-== Captures
-
-You may have noticed that some matchers yield a value to the block.
-The rules for determining if a matcher will yield a value are simple:
-
-1. Regexp captures: <tt>/posts\/(\d+)-(.*)/</tt> will yield two values, corresponding to each capture.
-2. String placeholders: <tt>"users/:id"</tt> will yield the value in the position of +:id+.
-3. Symbols: +:foobar+ will yield if a segment is available.
-4. File extensions: <tt>:extension=>"css"</tt> will yield the basename of the matched file.
-5. Parameters: <tt>:param=>"user"</tt> will yield the value of the parameter +user+, if present.
-
-The first case is important because it shows the underlying effect of Regexp captures.
-
-In the second case, the substring +:id+ gets replaced by <tt>([^\\/]+)</tt>
-and the Regexp becomes <tt>/users\/([^\/]+)/</tt> before performing the match.
-Thus, it reverts to the first form we saw.
-
-In the third case, the symbol, no matter what it says,
-gets replaced by <tt>/([^\\/]+)/</tt>, and again we are in presence of case 1.
-
-The fourth case, again, reverts to the basic matcher: it generates the string
-<tt>/([^\/]+?)\.#{ext}\z/</tt> before performing the match.
-
-The fifth case is different: it checks if the parameter supplied is present
-in the request (via POST or QUERY_STRING) and it pushes the value as a capture.
-
 == Composition
 
 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
-
     route do |r|
       r.is do
         # ...
@@ -597,6 +539,10 @@ When you use +r.run+, Roda calls the given Rack app (+API+ in this case);
 whatever the Rack app returns will be returned
 as the response for the current application.
 
+If you have a lot of rack applications that you want to dispatch to, and
+which one to dispatch to is based on the request path prefix, look into the
++multi_run+ plugin.
+
 === multi_route plugin
 
 If you are just looking to split up the main route block up by branches,
@@ -651,10 +597,15 @@ Note that when subclassing, Roda only does a shallow clone of the settings.
 If you store nested structures and plan to mutate them in subclasses,
 it is your responsibility to dup the nested structures inside +Roda.inherited+
 (making sure to call +super+).
+
 The plugins that ship with Roda all handle this.
 Also, note that this means that modifications to the parent class
 made after subclassing do _not_ affect the subclass.
 
+The plugins that ship with Roda freeze their settings and only allow modification
+to their settings by reloading the plugin, and external plugins are encouraged
+to follow this approach.
+
 == Rendering
 
 Roda ships with a +render+ plugin that provides helpers for rendering templates.
@@ -675,13 +626,13 @@ By default, +view+ will render the template inside the default layout template;
     route do |r|
       @var = '1'
 
-      r.is "render" do
+      r.get "render" do
         # Renders the views/home.erb template, which will have access to
         # the instance variable @var, as well as local variable content.
         render("home", :locals=>{:content => "hello, world"})
       end
 
-      r.is "view" do
+      r.get "view" do
         @var2 = '1'
 
         # Renders the views/home.erb template, which will have access to the
@@ -697,13 +648,11 @@ You can override the default rendering options by passing a hash to the plugin:
 
   class App < Roda
     plugin :render,
-      :cache => false,  # Disable template caching, useful in development
-      :engine => 'erb', # Tilt engine/template file extension to use
-      :escape => true,  # Automatically escape output in erb templates
-      :layout => "admin_layout",             # Default layout template
-      :layout_opts => {:ext=>'html.erb'},    # Default layout template options
-      :opts => {:default_encoding=>'UTF-8'}, # Default template options
-      :views => 'admin_views'                # Default views directory
+      :escape => true,        # Automatically escape output in erb templates
+      :views => 'admin_views' # Default views directory
+      :layout_opts => {:template=>'admin_layout',
+                       :ext=>'html.erb'},    # Default layout template options
+      :template_opts => {:default_encoding=>'UTF-8'}, # Default template options
   end
 
 == Sessions
@@ -760,27 +709,13 @@ to escape by default, so that in your templates:
 
 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].
-This is a Rack middleware that can be added in the usual way:
-
-  require 'roda'
-  require 'rack/protection'
-
-  class App < Roda
-    use Rack::Protection
-  end
-
 == Plugins
 
 By design, Roda has a very small core, providing only the essentials.
 All nonessential features are added via plugins.
 This is why Roda is referred to as a routing tree web framework toolkit.
 Using a combination of Roda plugins,
-you can build the routing tree web framework that needs your needs.
+you can build the routing tree web framework that suits your needs.
 
 Roda's plugins can override any Roda method and call +super+
 to get the default behavior, which makes Roda very extensible.
@@ -788,14 +723,6 @@ to get the default behavior, which makes Roda very extensible.
 {Roda ships with a large number of plugins}[http://roda.jeremyevans.net/documentation.html#included-plugins],
 and {some other libraries ship with support for Roda}[http://roda.jeremyevans.net/documentation.html#external].
 
-=== External Plugins
-
-The following libraries include Roda plugins:
-
-forme :: Adds support for easy HTML form creation in erb templates.
-autoforme :: Adds support for easily creating a simple administrative front
-             end for Sequel models.
-
 === How to create plugins
 
 Authoring your own plugins is pretty straightforward.
@@ -857,7 +784,9 @@ To avoid namespace pollution,
 you should avoid creating your module directly in the +Roda+ namespace.
 Additionally, any instance variables created inside +InstanceMethods+
 should be prefixed with an underscore (e.g., <tt>@_variable</tt>)
-to avoid polluting the scope.
+to avoid polluting the scope.  Finally, do not add any constants inside
+the InstanceMethods module, add constants to the plugin module itself
+(+Markdown+ in the above example).
 
 == License
 

data/doc/conventions.rdoc

@@ -1,8 +1,8 @@
 = Conventions
 
 This guide goes over conventions for directory layout and file layout for Roda applications.
-You are free to ignore these conventions, but following them will make your code similar
-to other Roda applications.
+You are free to ignore these conventions, they mostly exist to help users who are unsure how
+to structure their Roda applications.
 
 == Directory Layout
 
@@ -78,14 +78,16 @@ Large applications generally need more structure:
 
 For larger apps, the +Rakefile+, +assets/+, +migrate+, +models.rb+, +models/+, +public/+, remain the same.
 
-+app_name.rb+ should use the +multi_route+ and +view_subdirs+ plugins.  The routes used by the +multi_route+
-plugin should be stored in routing files in the +routes/+ directory, with one file per prefix.
++app_name.rb+ should use the +multi_route+ and +view_subdirs+ plugin, or the +multi_run+ plugin.
+The routes used by the +multi_route+ or +multi_run+ should be stored in routing files in the +routes/+
+directory, with one file per prefix.
 
 For specs/tests, you should have +spec/models/+ and +spec/web/+, with one file per model in +spec/models/+
 and one file per prefix in +spec/web/+.
 
-You should have a separate view subdirectory per prefix, and use +set_view_subdir+ in your routing files
-to specify the subdirectory to use, so it doesn't need to be specified on every call to view.
+You should have a separate view subdirectory per prefix. If you are using +multi_route+ and +view_subdirs+,
+use +set_view_subdir+ in your routing files to specify the subdirectory to use, so it doesn't need to be
+specified on every call to view.
 
 +helpers/+ should be used to store helper methods for your application, that you call in your routing files
 and views.  In a small application, these methods should just be specified in +app_name.rb+
@@ -93,8 +95,8 @@ and views.  In a small application, these methods should just be specified in +a
 === Really Large Applications
 
 For very large applications, it's expected that there will be deviations from these conventions. However,
-it is recommended to use namespaces in the +multi_route+ plugin, and have subdirectories in the +routes/+
-directory, and nested subdirectories in the +views/+ directory.
+it is recommended to use the +multi_route+ or +multi_run+ plugins to organize your application, and have
+subdirectories in the +routes/+ directory, and nested subdirectories in the +views/+ directory.
 
 == Roda Application File Layout