roda 3.83.0 → 3.84.0

data/doc/conventions.rdoc

@@ -1,177 +0,0 @@
-= Conventions
-
-This guide goes over conventions for directory layout and file layout for 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
-
-Which directory layout to use should reflect the size of your application.
-
-=== Small Applications
-
-For a small application, the following directory layout is recommended:
-
-  Rakefile
-  app_name.rb
-  assets/
-  config.ru
-  db.rb
-  migrate/
-  models.rb
-  models/
-  public/
-  spec/
-  views/
-
-+app_name.rb+ should contain the Roda application, and should reflect the name of your application.
-So, if your application is named +FooBar+, you should use +foo_bar.rb+.
-
-+config.ru+ should contain the code the webserver uses to determine which application to run.
-
-+views/+ should contain your template files.  This assumes you are using the +render+ plugin
-and server-side rendering.  If you are creating a single page application and just serving
-JSON, then you won't need a +views+ directory.  For small applications, all view files should be
-in the +views+ directory.
-
-+public/+ should contain any static files that should be served directly by the webserver.
-Again, for pure JSON applications, you won't need a +public+ directory.
-
-+assets/+ should contain the source files for your CSS and javascript assets.  If you are
-not using the +assets+ plugin, you won't need an +assets+ directory.
-
-+db.rb+ should contain the minimum code to setup a database connection, without loading any of
-the applications models.  This can be required in cases where you don't want the models loaded,
-such as when running migrations. This file should be required by +models.rb+.
-
-+models.rb+ should contain all code related to your ORM.  This file should be required
-by +app_name.rb+.  This keeps your model code separate from your web code, making it easier
-to use outside of your web code. It allows you to get an IRB shell for accessing your models
-via <tt>irb -r ./models</tt>, without loading the Roda application.
-
-+models/+ should contain your ORM models, with a separate file per model class.
-
-+migrate/+ should create your database migration files, if you are using an ORM that uses
-migrations.
-
-+spec/+ (or +test/+ should contain your specifications/tests.  For a small application, it's recommended
-to have a single file for your model tests, and a single file for your web/integration tests.
-
-+Rakefile+ should contain the rake tasks for the application.  The convention is that the
-default rake task will run all specs/tests related to the application.  If you are using
-the +assets+ plugin, you should have an <tt>assets:precompile</tt> task for precompiling
-assets.
-
-=== Large Applications
-
-Large applications generally need more structure:
-
-  Rakefile
-  app_name.rb
-  assets/
-  helpers/
-  migrate/
-  models.rb
-  models/
-  public/
-  routes/
-   prefix1.rb
-   prefix2.rb
-  spec/
-   models/
-   web/
-  views/
-   prefix1/
-   prefix2/
-
-For larger apps, the +Rakefile+, +assets/+, +migrate+, +models.rb+, +models/+, +public/+, remain the same.
-
-+app_name.rb+ should use the +hash_branch_view_subdir+ plugin (which builds on the +hash_branches+ and
-+view_options+ plugin), or the +multi_run+ plugin.
-The routes used by the +hash_branches+ 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/+. Substitute +spec+ with +test+ if that is what you are using as the
-name of the directory.
-
-You should have a separate view subdirectory per prefix. With the +hash_branch_view_subdir+, the application
-will automatically set a separate view subdirectory per routing tree branch.
-
-+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+
-
-=== Really Large Applications
-
-For very large applications, it's expected that there will be deviations from these conventions. However,
-it is recommended to use the +hash_branch_view_subdir+ 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
-
-=== Small Applications
-
-For a small application, the convention in Roda is to layout your Roda application file (+app_name.rb+) like this:
-
-  require 'roda'
-  require_relative 'models'
-
-  class AppName < Roda
-    SOME_CONSTANT = 1
-
-    use SomeMiddleware
-
-    plugin :render, escape: true
-    plugin :assets
-
-    route do |r|
-      # ...
-    end
-
-    def view_method
-      'foo'
-    end
-  end
-
-You should first require +roda+ and +./models+, followed by any other libraries needed by the
-application.
-
-You should subclass Roda and make the application's name the name of the Roda subclass.
-Inside the subclass, you first define the constants used by the application.  Then you add
-any middleware used by the application, followed by loading any plugins used by the application.
-Then you add the route block for the application.  After the route block, define the instance methods
-used in your route block or views.
-
-=== Large Applications
-
-For larger applications, there are some slight changes to the Roda application file layout:
-
-  require 'roda'
-  require_relative 'models'
-
-  class AppName < Roda
-    SOME_CONSTANT = 1
-
-    use SomeMiddleware
-
-    plugin :render, escape: true, layout: './layout'
-    plugin :assets
-    plugin :hash_branch_view_subdir
-    Dir['routes/*.rb'].each{|f| require_relative f}
-
-    route do |r|
-      r.hash_branches('')
-
-      r.root do
-        # ...
-      end
-    end
-
-    Dir['helpers/*.rb'].each{|f| require_relative f}
-  end
-
-After loading the +hash_branch_view_subdir+ plugin, you require all of your
-routing files.  Inside your route block, instead of defining your routes, you just call
-+r.hash_branches+, which will dispatch to all of your routing files.  After your route
-block, you require all of your helper files containing the instance methods for your
-route block or views, instead of defining the methods directly.

data/doc/release_notes/3.0.0.txt

@@ -1,84 +0,0 @@
-= Major Changes
-
-* String matchers now match literally by default, for simplicity,
-  understandability, and performance.  Use the String class matcher
-  or a symbol matcher to match arbitrary segments.
-
-    # Before
-    r.is "artists/:name" do |artist_name|
-    end
-
-    # Now
-    r.is "artists", String do |artist_name|
-    end
-    # or
-    r.is "artists", :name do |artist_name|
-    end
-
-  You can use the placeholder_string_matchers plugin to restore
-  the historical behavior if you don't want to modify your
-  routes.
-
-* Using an unsupported matcher now raises an error, making it
-  more likely to detect using a unexpected value as a matcher
-  (which previously matched everything).
-
-* Have a route/match block return an unsupported value now
-  raises an error if nothing has been written to the body, making
-  it more likely to detect using an unexpected value as a block
-  result (which previously was ignored).
-
-= Backwards Compatibility
-
-* Deprecated plugins, features, and constants have been removed.
-  Before upgrading to 3.0.0, please upgrade to 2.29.0 first and
-  fix any deprecation warnings.
-
-* Ruby 1.8.7 support has been dropped.  Ruby 1.9.2 is the new
-  minimum supported version.
-
-* The :check_paths render plugin option now defaults to true so that
-  generated template paths are checked by default, reducing the risk
-  of rendering arbitrary files.
-
-* The assets plugin now defaults to using subresource integrity
-  with SHA256 for compiled assets, and using SHA256 instead of
-  SHA1 for compiled asset hashes.
-
-* Subclassing a Roda app that uses the render plugin now always
-  uses a copy of the superclass's template cache.
-
-* Using a Roda app as middleware now always uses a subclass
-  of the app for the middleware.
-
-* public_send is now used instead of send internally unless it is
-  expected that private methods will be called.
-
-* The match methods added by the symbol_matchers and hash_matchers
-  plugins are now private instead of public.
-
-= Other Improvements
-
-* The streaming plugin has been greatly simplified, by dropping
-  deprecated compatibility for EventMachine.
-
-* It is now possible to reset the :include_request option to false
-  in the json and json_parser plugins by loading the plugin a
-  second time with the option set.
-
-* The precompile_templates plugin now always sorts locals.  This
-  plugin should now be used with Tilt 2.0.1+ (which also sorts
-  locals), though it will still work with earlier Tilt versions.
-
-* The multi_run plugin now recomputes the regexp when freezing the
-  app.
-
-= Deprecated Features
-
-These features will be removed in Roda 3.1.0:
-
-* Roda.thread_safe_cache is now deprecated.  RodaCache is now used
-  as the thread-safe cache class.
-
-* RodaRequest#placeholder_string_matcher? (private method) is now
-  deprecated and always returns false.

data/doc/release_notes/3.1.0.txt

@@ -1,24 +0,0 @@
-= New Features
-
-* A :timestamp_paths option has been added to the assets plugin to
-  include timestamps in paths in non-compiled mode.  This can fix
-  asset staleness issues when using a caching proxy.  This is
-  not needed in compiled mode, as the asset file names include the
-  hash of the asset.  It is not the default in non-compiled mode,
-  as few people would use a caching proxy in non-compiled mode.
-
-= Other Improvements
-
-* Make set_layout_locals and set_view_locals in branch_locals
-  plugin work when the other is not called.
-
-* When testing support for uglifier usability as a JS asset
-  compressor, handle case where uglifier is installed but there is
-  no available javascript runtime.
-
-= Backwards Compatibility
-
-* The deprecated Roda.thread_safe_cache method has been removed.
-
-* The deprecated private RodaRequest#placeholder_string_matcher?
-  method has been removed.

data/doc/release_notes/3.10.0.txt

@@ -1,132 +0,0 @@
-= New Features
-
-* A sessions plugin has been added that supports encrypted and
-  signed sessions. This plugin is now the recommended way to
-  implement sessions, replacing the previously recommended
-  Rack::Session::Cookie middleware.
-
-  The sessions plugin encrypts session data using the AES-256-CTR
-  cipher, and then signs the encrypted data with HMAC-SHA-256. By
-  doing this, attackers must be able to forge a valid HMAC before
-  they can try to exploit possible weaknesses in the encryption,
-  such as timing attacks during decryption that are dependent on
-  attacker chosen initialization vectors or ciphertext.
-
-  In addition to encryption and a stronger default signature
-  algorithm compared to Rack::Session::Cookie, the sessions
-  plugin has the following benefits:
-
-  * Built in session expiration enabeld by default, to mitigate
-    possible session replay issues (default: 30 days since session
-    creation, 7 days since last update).
-
-  * Padding by default to minimize information leakage due to
-    differing session data sizes (session data padded to
-    a multiple of 32 bytes by default before encryption).
-
-  * Automatic deflate compression of large sessions before
-    encryption (by default if session data is over 128 bytes).
-
-  * JSON is used for serialization instead of Marshal, preventing
-    remote code execution vulnerabilities if the session secret
-    is disclosed. Note that this means that many ruby types do not
-    round trip in the session, such as Symbol and Time instances.
-    This will probably be the largest barrier to adoption, as you
-    need to make sure your application only uses types that
-    round-trip through JSON before you start using the sessions
-    plugin.
-
-  * A plain hash is used for the session, instead of a hash-like
-    object. One consequence of this is that keys in the session
-    are not automatically converted to strings.
-    Rack::Session::Cookie converts session keys to strings for
-    keys at the top level, but not for keys in subhashes.
-
-  * In general sessions are smaller even if deflate compression is not
-    used, despite requiring 16 bytes for the cipher initialization
-    vector. The main reason for this is that the sessions plugin does
-    not set a session id, since one is not needed for cookie sessions.
-
-  * The sessions plugin requires a :secret option be set that is
-    at least 64 bytes, so that users have to make a determined
-    effort to use weak secrets.
-
-  * The HMAC calculation considers the cookie key, so that if the
-    same session secret is used for multiple applications with
-    different cookie keys, an attacker cannot use the session from
-    one application in a different application.
-
-  The sessions plugin ties into the Roda#session method instead
-  of being a rack middleware.  This makes it about twice as
-  fast as Rack::Session::Cookie if the session is not accessed.
-  If the session is accessed, the sessions plugin is roughly
-  as fast as Rack::Session::Cookie, even though it uses a
-  stronger HMAC and has to encrypt and decrypt the session.
-
-  Because the sessions plugin is not a middleware, it does not
-  offer session support to other middleware, only to the app
-  itself.  If you would like to use the same approach as the
-  sessions plugin uses but would like support for middleware to
-  access the sessions, a roda/session_middleware file has been
-  added. This file contains RodaSessionMiddleware, which is a
-  middleware that can be used by any other Rack app for session
-  support, and which uses a SessionHash class similar to the one used
-  by Rack::Session::Cookie.
-
-  To integrate with other plugins that can optionally use symbols
-  or strings in sessions, the sessions plugin sets the
-  :sessions_convert_symbols application option to true.  Other plugins
-  can check for this application option, and if set, should use
-  strings instead of symbols in the session.
-
-  The sessions plugin should be loaded after the flash plugin if both
-  are used in the same application, so that the flash is rotated
-  correctly in the session.
-
-* The middleware plugin now supports a :handle_result option, which
-  can be any callable object.  If set, this object is called with the
-  environment of the request and the rack response after either the
-  Roda app or next middleware returns the rack response.  The rack
-  response can be modified by the callable object, and the response
-  (after possible modification) will be returned to the previous
-  middleware.  Example:
-
-    plugin :middleware, :handle_result=>(proc do |env, res|
-      res[1]['MyHeader'] = 'HeaderValue'
-    end)
-
-* The :json_parser and :json_serializer application options are now
-  supported.  If set, these options are used for parsing and
-  serializing JSON instead of the default of JSON.parse and .to_json.
-
-= Other Improvements
-
-* RodaRequest initialization is now faster by avoiding 1-2 method
-  calls.
-
-* typecast_params.Integer in the typecast_params plugin now handles
-  numeric input as long the numeric input does not have fractional
-  parts.  This makes it more usable when handling JSON input.
-
-* If the flash is empty after the request is processed, the flash
-  session key is removed from the session instead of being left as
-  an empty hash.  If addition to making the session smaller, this
-  makes the session appear empty if there are no other keys in the
-  session, which works better with the sessions plugin as empty
-  sessions will remove the session cookie completely.
-
-= Backwards Compatibility
-
-* The flash plugin now uses '_flash' instead of :_flash as the session
-  key.  When using session middleware that uses
-  Rack::Session::Abstract::SessionHash to store the session (e.g.
-  Rack::Session::Cookie), session keys are converted internally to
-  strings, so this change will not affect you unless you are using
-  alternative session support.  Even if your session does treat
-  :_flash different than '_flash' in keys, the plugin will still work
-  because it will try :_flash if there is no value for '_flash'.  This
-  change was made to support the sessions plugin, which doesn't
-  convert keys to strings.
-
-* This DEFAULT_PARSER and DEFAULT_SERIALIZER constants from the
-  the json_parser and json plugins have been removed.

data/doc/release_notes/3.11.0.txt

@@ -1,54 +0,0 @@
-= Improvements
-
-* The order in which internal plugin before and after hooks are run
-  when multiple plugins are loaded is now fixed and does not depend
-  on the order in which the plugins are loaded.  This can prevent
-  some issues in cases the plugins were not loaded in the order
-  previously recommended in the documentation.
-
-  Internal plugin before hooks are now run in the following order:
-
-  * hooks
-  * heartbeat
-  * static_routing
-
-  and internal plugin after hooks are now run in the following order:
-
-  * class_level_routing
-  * status_handler
-  * head
-  * flash
-  * session
-  * hooks
-
-* Default compression of sessions over 128 bytes in length has been
-  disabled in the sessions plugin.  Compression of sessions must now
-  be manually enabled if it is desired by setting :gzip_over to an
-  integer.
-
-  This change is being made to avoid possible compression ratio
-  attacks if both sensitive data and user-submitted data are stored in
-  the session.  Such attacks were mitigated by the sessions plugin's
-  default use of padding after compression, and the JSON serialization
-  format used, but disabling compression avoids the possibility.
-
-  This does not affect backwards compatibility, as compressed sessions
-  will still be decompressed correctly, unless the size of the session
-  cookie when not using compression is over 4096 bytes.
-
-= Backwards Compatibility
-
-* When using the error_handler plugin, if routing raises an exception that
-  is handled by the error handler, but an exception is raised by a plugin
-  internal after hook after the error handler has been run, the exception
-  will be logged to the rack.errors entry in the environment, but it will
-  be otherwise ignored.
-
-  Exceptions raised inside the error handler will continue to be be raised
-  to the application's caller.
-
-  Additionally, the error_handler plugin no longers call before hooks
-  during error handling.
-
-* A private Roda#_call method has been added.  This could potentially
-  cause issues for applications that add their own _call method.

data/doc/release_notes/3.12.0.txt

@@ -1,19 +0,0 @@
-= New Features
-
-* A common_logger plugin has been added for common log support. This
-  offers about 30% better performance than Rack::CommonLogger, with
-  the following differences:
-
-  * When timing requests, doesn't consider middleware or proxy the
-    body, so timing information is just the time that Roda takes
-    to process the request.
-  * Only looks for "Content-Length" as a header, not different
-    capitalizations (Roda only uses "Content-Length" internally).
-  * Logs to $stderr instead of rack.errors in request environment
-    if a logger object is not explicitly passed.
-
-= Other Improvements
-
-* Internal before/after hook methods now use more descriptive names
-  for easier debugging, with a naming format designed to not
-  conflict with hook methods in external plugins.

data/doc/release_notes/3.13.0.txt

@@ -1,38 +0,0 @@
-= New Features
-
-* An exception_page plugin has been added for displaying debugging
-  information for a given exception.  It is based on
-  Rack::ShowExceptions, with the following differences:
-
-  * Not a middleware, so it doesn't handle exceptions itself, and
-    has no effect on the callstack unless the exception_page
-    method is called.
-  * Supports external javascript and stylesheets, allowing context
-    toggling to work in applications that use a content security
-    policy to restrict inline javascript and stylesheets (:assets,
-    :css_file, and :js_file options).
-  * Has fewer dependencies (does not require ostruct and erb).
-  * Sets the Content-Type for the response, and returns the body
-    string, but does not modify other headers or the response status.
-  * Supports a configurable amount of context lines in backtraces
-    (:context option).
-  * Supports optional JSON formatted output, if used with the json
-    plugin (:json option).
-
-  Because this plugin just adds a method you can call, you can
-  selectively choose when to display a debugging page and when not
-  to, as well as customize the debugging parameters on a per-call
-  basis (such as returning JSON formatted debugging information
-  for JSON requests, and HTML formatted debugging information for
-  normal requests).
-
-= Other Improvements
-
-* The common_logger plugin now correctly handles cases where an
-  exception is being raised and there is no rack response to
-  introspect.
-
-= Backwards Compatibility
-
-* Stream#write in the streaming plugin now returns the number of
-  bytes written instead of self, so it works with IO.copy_stream.

data/doc/release_notes/3.14.0.txt

@@ -1,36 +0,0 @@
-= New Features
-
-* The convert! and convert_each! methods in the typecast_params plugin
-  now support a :raise option for handling missing parameters specified
-  as arguments to the methods.
-  
-  If the :raise option is set to false for convert! and the parameter
-  argument is missing, then no conversion is done and an empty hash
-  is returned:
-
-    typecast_params.convert!('missing', raise: false) do |tp|
-      # ...
-    end
-    # => {}
-
-  If the :raise option is set to false for convert_each! and a :keys
-  option is given, any key not present is ignored and nil will be
-  returned for the converted value
-
-    typecast_params.convert_each!(:keys=>['present', 'missing'], raise: false) do |tp|
-      tp.int('b')
-    end
-    # => [{'b'=>1}, nil]
-
-= Other Improvements
-
-* The :symbolize setting to the convert! and convert_each! methods in
-  the typecast_params plugin is no longer persisted beyond the call
-  to the method.  This fixes unexpected behavior if you do:
-
-    typecast_params.convert!(:symbolize=>true) do |tp|
-      # ...
-    end
-    typecast_params.convert! do |tp|
-      # ...
-    end

data/doc/release_notes/3.14.1.txt

@@ -1,43 +0,0 @@
-= Security Fix
-  
-* Do not post-process content_for block result with template engine
-  
-  Since 2.8.0, the content_for block result was post-processed with the
-  template engine.  There is no actual need to do so, as content_for is
-  not designed to render output, it is designed to store already
-  rendered output.  This post-processing was introduced when support for
-  haml templates was added in 2.8.0.
-  
-  Post-processing the output with the template engine is generally a
-  no-op for most usage as most output does not contain template
-  metaprogramming characters, which is why this went undetected for so
-  long.  However, if a content_for block return value contained
-  unescaped user input, it was probably vulnerable to remote code
-  execution if the default ERB template engine is used, the same as if
-  the user input was passed directly to the render or view method.
-  
-  Example of a vulnerable usage (assuming automatic escaping is not
-  enabled) would be:
-  
-    <% content_for :foo do %>
-      User name: <%= request.params['user_name'] %>
-    <% end %>
-  
-  Such usage is likely vulnerable to cross site scripting unless the
-  content_for output is escaped before being displayed, even without
-  the content_for template post-processing. However, the post-processing
-  turned it from a cross site scripting vulnerability into a remote code
-  execution vulnerability.  For non-ERB template engines, whether the
-  post-processing introduced a vulnerability depends on the template
-  engine.
-  
-  Note that if you were correctly escaping user input in your ERB
-  templates (either automatically or manually), you are unlikely to be
-  vulnerable as the escaping escaped the ERB template metacharacters
-  (< and >).  For non-ERB templates, escaping the output may not have
-  mitigated the vulnerability, depending on what metacharacters
-  the template engine uses and whether the escaping will modify them.
-  
-  Calling content_for with an argument was not vulnerable as no
-  post-processing was done on the argument, it was only done on
-  the block result.

data/doc/release_notes/3.15.0.txt

@@ -1,21 +0,0 @@
-= New Features
-
-* The render plugin :escape option value can now be a string or an
-  array of strings, and then the plugin will will only add the
-  :escape template option for those specific template engines given.
-  By default, the :escape plugin option adds the :escape template
-  option for all engines, which breaks the usage with some engines
-  (such as the rcsv engine).
-
-* The convert! and convert_each! methods in the typecast_params plugin
-  now support a :skip_missing option to support not storing missing
-  parameters:
-
-    typecast_params.convert! do |tp|
-      tp.int('missing')
-    end
-    # => {'missing'=>nil}
-    typecast_params.convert!(skip_missing: false) do |tp|
-      tp.int('missing')
-    end
-    # => {}