sinatra 3.0.5 → 4.0.0

data/README.md

@@ -54,6 +54,8 @@ pick up if available.
       - [Erb Templates](#erb-templates)
       - [Builder Templates](#builder-templates)
       - [Nokogiri Templates](#nokogiri-templates)
+      - [Sass Templates](#sass-templates)
+      - [Scss Templates](#scss-templates)
       - [Liquid Templates](#liquid-templates)
       - [Markdown Templates](#markdown-templates)
       - [RDoc Templates](#rdoc-templates)
@@ -93,6 +95,7 @@ pick up if available.
   - [Configuration](#configuration)
     - [Configuring attack protection](#configuring-attack-protection)
     - [Available Settings](#available-settings)
+  - [Lifecycle Events](#lifecycle-events)
   - [Environments](#environments)
   - [Error Handling](#error-handling)
     - [Not Found](#not-found)
@@ -649,6 +652,39 @@ It also takes a block for inline templates (see [example](#inline-templates)).
 
 It also takes a block for inline templates (see [example](#inline-templates)).
 
+#### Sass Templates
+
+<table>
+  <tr>
+    <td>Dependency</td>
+    <td><a href="https://github.com/ntkme/sass-embedded-host-ruby" title="sass-embedded">sass-embedded</a></td>
+  </tr>
+  <tr>
+    <td>File Extension</td>
+    <td><tt>.sass</tt></td>
+  </tr>
+  <tr>
+    <td>Example</td>
+    <td><tt>sass :stylesheet, :style => :expanded</tt></td>
+  </tr>
+</table>
+
+#### Scss Templates
+
+<table>
+  <tr>
+    <td>Dependency</td>
+    <td><a href="https://github.com/ntkme/sass-embedded-host-ruby" title="sass-embedded">sass-embedded</a></td>
+  </tr>
+  <tr>
+    <td>File Extension</td>
+    <td><tt>.scss</tt></td>
+  </tr>
+  <tr>
+    <td>Example</td>
+    <td><tt>scss :stylesheet, :style => :expanded</tt></td>
+  </tr>
+</table>
 
 #### Liquid Templates
 
@@ -810,7 +846,7 @@ It also takes a block for inline templates (see [example](#inline-templates)).
 <table>
   <tr>
     <td>Dependency</td>
-    <td><a href="http://slim-lang.com/" title="Slim Lang">Slim Lang</a></td>
+    <td><a href="https://slim-template.github.io/" title="Slim Lang">Slim Lang</a></td>
   </tr>
   <tr>
     <td>File Extension</td>
@@ -1163,22 +1199,6 @@ $ ruby -e "require 'securerandom'; puts SecureRandom.hex(64)"
 99ae8af...snip...ec0f262ac
 ```
 
-**Session Secret Generation (Bonus Points)**
-
-Use the [sysrandom gem](https://github.com/cryptosphere/sysrandom#readme) to
-use the system RNG facilities to generate random values instead of
-userspace `OpenSSL` which MRI Ruby currently defaults to:
-
-```text
-$ gem install sysrandom
-Building native extensions.  This could take a while...
-Successfully installed sysrandom-1.x
-1 gem installed
-
-$ ruby -e "require 'sysrandom/securerandom'; puts SecureRandom.hex(64)"
-99ae8af...snip...ec0f262ac
-```
-
 **Session Secret Environment Variable**
 
 Set a `SESSION_SECRET` environment variable for Sinatra to the value you
@@ -1193,14 +1213,10 @@ purposes only:
 **Session Secret App Config**
 
 Set up your app config to fail-safe to a secure random secret
-if the `SESSION_SECRET` environment variable is not available.
-
-For bonus points use the [sysrandom
-gem](https://github.com/cryptosphere/sysrandom#readme) here as well:
+if the `SESSION_SECRET` environment variable is not available:
 
 ```ruby
 require 'securerandom'
-# -or- require 'sysrandom/securerandom'
 set :session_secret, ENV.fetch('SESSION_SECRET') { SecureRandom.hex(64) }
 ```
 
@@ -1405,53 +1421,9 @@ to `stream` finishes executing. Streaming does not work at all with Shotgun.
 
 If the optional parameter is set to `keep_open`, it will not call `close` on
 the stream object, allowing you to close it at any later point in the
-execution flow. This only works on evented servers, like Rainbows.
-Other servers will still close the stream:
-
-```ruby
-# config.ru
-require 'sinatra/base'
-
-class App < Sinatra::Base
-  connections = []
+execution flow.
 
-  get '/subscribe', provides: 'text/event-stream'  do
-    # register a client's interest in server events
-    stream(:keep_open) do |out|
-      connections << out
-      # purge dead connections
-      connections.reject!(&:closed?)
-    end
-  end
-
-  post '/' do
-    connections.each do |out|
-      # notify client that a new message has arrived
-      out << "data: #{params[:msg]}\n\n"
-
-      # indicate client to connect again
-      out.close
-    end
-
-    204 # response without entity body
-  end
-end
-
-run App
-```
-
-```ruby
-# rainbows.conf
-Rainbows! do
-  use :EventMachine
-end
-````
-
-Run:
-
-```shell
-rainbows -c rainbows.conf
-```
+You can have a look at the [chat example](https://github.com/sinatra/sinatra/blob/main/examples/chat.rb)
 
 It's also possible for the client to close the connection when trying to
 write to the socket. Because of this, it's recommended to check
@@ -1933,7 +1905,7 @@ end
 ### Configuring attack protection
 
 Sinatra is using
-[Rack::Protection](https://github.com/sinatra/sinatra/tree/master/rack-protection#readme) to
+[Rack::Protection](https://github.com/sinatra/sinatra/tree/main/rack-protection#readme) to
 defend your application against common, opportunistic attacks. You can
 easily disable this behavior (which will open up your application to tons
 of common vulnerabilities):
@@ -1950,7 +1922,7 @@ set :protection, :except => :path_traversal
 You can also hand in an array in order to disable a list of protections:
 
 ```ruby
-set :protection, :except => [:path_traversal, :session_hijacking]
+set :protection, :except => [:path_traversal, :remote_token]
 ```
 
 By default, Sinatra will only set up session based protection if `:sessions`
@@ -2089,9 +2061,13 @@ set :protection, :session => true
 
   <dt>raise_errors</dt>
     <dd>
-      Raise exceptions (will stop application). Enabled by default when
+      Raise unhandled errors (will stop application). Enabled by default when
       <tt>environment</tt> is set to <tt>"test"</tt>, disabled otherwise.
     </dd>
+    <dd>
+      Any explicitly defined error handlers always override this setting. See 
+      the "Error" section below.
+    </dd>
 
   <dt>run</dt>
     <dd>
@@ -2184,6 +2160,24 @@ set :protection, :session => true
     </dd>
 </dl>
 
+## Lifecycle Events
+
+There are 2 lifecycle events currently exposed by Sinatra. One when the server starts and one when it stops.
+
+They can be used like this:
+
+```ruby
+on_start do
+  puts "===== Booting up ====="
+end
+
+on_stop do
+  puts "===== Shutting down ====="
+end
+```
+
+Note that these callbacks only work when using Sinatra to start the web server.
+
 ## Environments
 
 There are three predefined `environments`: `"development"`,
@@ -2240,6 +2234,14 @@ show exceptions option to `:after_handler`:
 set :show_exceptions, :after_handler
 ```
 
+A catch-all error handler can be defined with `error` and a block:
+
+```ruby
+error do
+  'Sorry there was a nasty error'
+end
+```
+
 The exception object can be obtained from the `sinatra.error` Rack variable:
 
 ```ruby
@@ -2248,7 +2250,7 @@ error do
 end
 ```
 
-Custom errors:
+Pass an error class as an argument to create handlers for custom errors:
 
 ```ruby
 error MyCustomError do
@@ -2294,6 +2296,51 @@ Sinatra installs special `not_found` and `error` handlers when
 running under the development environment to display nice stack traces
 and additional debugging information in your browser.
 
+### Behavior with `raise_errors` option
+
+When `raise_errors` option is `true`, errors that are unhandled are raised 
+outside of the application. Additionally, any errors that would have been 
+caught by the catch-all error handler are raised.
+
+For example, consider the following configuration:
+
+```ruby
+# First handler
+error MyCustomError do
+  'A custom message'
+end
+
+# Second handler
+error do
+  'A catch-all message'
+end
+```
+
+If `raise_errors` is `false`:
+
+* When `MyCustomError` or descendant is raised, the first handler is invoked.
+  The HTTP response body will contain `"A custom message"`.
+* When any other error is raised, the second handler is invoked. The HTTP 
+  response body will contain `"A catch-all message"`.
+
+If `raise_errors` is `true`:
+
+* When `MyCustomError` or descendant is raised, the behavior is identical to 
+  when `raise_errors` is `false`, described above.
+* When any other error is raised, the second handler is *not* invoked, and 
+  the error is raised outside of the application.
+  * If the environment is `production`, the HTTP response body will contain 
+    a generic error message, e.g. `"An unhandled lowlevel error occurred. The
+    application logs may have details."`
+  * If the environment is not `production`, the HTTP response body will contain
+    the verbose error backtrace.
+  * Regardless of environment, if `show_exceptions` is set to `:after_handler`, 
+    the HTTP response body will contain the verbose error backtrace.
+
+In the `test` environment, `raise_errors` is set to `true` by default. This 
+means that in order to write a test for a catch-all error handler, 
+`raise_errors` must temporarily be set to `false` for that particular test.
+
 ## Rack Middleware
 
 Sinatra rides on [Rack](https://rack.github.io/), a minimal standard
@@ -2319,7 +2366,7 @@ end
 ```
 
 The semantics of `use` are identical to those defined for the
-[Rack::Builder](http://www.rubydoc.info/github/rack/rack/master/Rack/Builder) DSL
+[Rack::Builder](https://www.rubydoc.info/github/rack/rack/main/Rack/Builder) DSL
 (most frequently used from rackup files). For example, the `use` method
 accepts multiple/variable args as well as blocks:
 
@@ -2335,7 +2382,7 @@ many of these components automatically based on configuration so you
 typically don't have to `use` them explicitly.
 
 You can find useful middleware in
-[rack](https://github.com/rack/rack/tree/master/lib/rack),
+[rack](https://github.com/rack/rack/tree/main/lib/rack),
 [rack-contrib](https://github.com/rack/rack-contrib#readme),
 or in the [Rack wiki](https://github.com/rack/rack/wiki/List-of-Middleware).
 
@@ -2343,7 +2390,7 @@ or in the [Rack wiki](https://github.com/rack/rack/wiki/List-of-Middleware).
 
 Sinatra tests can be written using any Rack-based testing library or
 framework.
-[Rack::Test](http://www.rubydoc.info/github/brynary/rack-test/master/frames)
+[Rack::Test](https://www.rubydoc.info/github/rack/rack-test/main/frames)
 is recommended:
 
 ```ruby
@@ -2767,68 +2814,30 @@ by Konstantin_
 Sinatra doesn't impose any concurrency model but leaves that to the
 underlying Rack handler (server) like Puma or WEBrick. Sinatra
 itself is thread-safe, so there won't be any problem if the Rack handler
-uses a threaded model of concurrency. This would mean that when starting
-the server, you'd have to specify the correct invocation method for the
-specific Rack handler. The following example is a demonstration of how
-to start a multi-threaded Rainbows server:
-
-```ruby
-# config.ru
-
-require 'sinatra/base'
-
-class App < Sinatra::Base
-  get '/' do
-    "Hello, World"
-  end
-end
-
-run App
-```
-
-```ruby
-# rainbows.conf
-
-# Rainbows configurator is based on Unicorn.
-Rainbows! do
-  use :ThreadSpawn
-end
-```
-
-To start the server, the command would be:
-
-```shell
-rainbows -c rainbows.conf
-```
+uses a threaded model of concurrency.
 
 ## Requirement
 
 The following Ruby versions are officially supported:
 <dl>
-  <dt>Ruby 2.6</dt>
+  <dt>Ruby</dt>
   <dd>
-    2.6 is fully supported and recommended. There are currently no plans to
-    drop official support for it.
+    <a href="https://www.ruby-lang.org/en/downloads/">The stable releases</a> are fully supported and recommended.
   </dd>
 
-  <dt>Rubinius</dt>
+  <dt>TruffleRuby</dt>
   <dd>
-    Rubinius is officially supported (Rubinius >= 2.x). It is recommended to
-    <tt>gem install puma</tt>.
+    The latest stable release of TruffleRuby is supported.
   </dd>
 
   <dt>JRuby</dt>
   <dd>
-    The latest stable release of JRuby is officially supported. It is not
-    recommended to use C extensions with JRuby. It is recommended to
-    <tt>gem install trinidad</tt>.
+    The latest stable release of JRuby is supported. It is not
+    recommended to use C extensions with JRuby.
   </dd>
 </dl>
 
-Versions of Ruby before 2.6 are no longer supported as of Sinatra 3.0.0.
-
-We also keep an eye on upcoming Ruby versions. Expect upcoming
-3.x releases to be fully supported.
+Versions of Ruby before 2.7.8 are no longer supported as of Sinatra 4.0.0.
 
 Sinatra should work on any operating system supported by the chosen Ruby
 implementation.
@@ -2838,7 +2847,7 @@ Running Sinatra on a not officially supported Ruby flavor means that if things o
 ## The Bleeding Edge
 
 If you would like to use Sinatra's latest bleeding-edge code, feel free
-to run your application against the master branch, it should be rather
+to run your application against the main branch, it should be rather
 stable.
 
 We also push out prerelease gems from time to time, so you can do a
@@ -2887,20 +2896,19 @@ SemVerTag.
 
 ## Further Reading
 
-* [Project Website](http://www.sinatrarb.com/) - Additional documentation,
+* [Project Website](https://sinatrarb.com/) - Additional documentation,
   news, and links to other resources.
-* [Contributing](http://www.sinatrarb.com/contributing) - Find a bug? Need
+* [Contributing](https://sinatrarb.com/contributing) - Find a bug? Need
   help? Have a patch?
 * [Issue tracker](https://github.com/sinatra/sinatra/issues)
 * [Twitter](https://twitter.com/sinatra)
 * [Mailing List](https://groups.google.com/forum/#!forum/sinatrarb)
 * IRC: [#sinatra](irc://chat.freenode.net/#sinatra) on [Freenode](https://freenode.net)
-* [Sinatra & Friends](https://sinatrarb.slack.com) on Slack
-  ([get an invite](https://sinatra-slack.herokuapp.com/))
+* [Sinatra & Friends](https://discord.gg/ncjsfsNHh7) on Discord
 * [Sinatra Book](https://github.com/sinatra/sinatra-book) - Cookbook Tutorial
 * [Sinatra Recipes](http://recipes.sinatrarb.com/) - Community contributed
   recipes
-* API documentation for the [latest release](http://www.rubydoc.info/gems/sinatra)
-  or the [current HEAD](http://www.rubydoc.info/github/sinatra/sinatra) on
-  [RubyDoc](http://www.rubydoc.info/)
+* API documentation for the [latest release](https://www.rubydoc.info/gems/sinatra)
+  or the [current HEAD](https://www.rubydoc.info/github/sinatra/sinatra) on
+  [RubyDoc](https://www.rubydoc.info/)
 * [CI Actions](https://github.com/sinatra/sinatra/actions)

data/Rakefile

@@ -1,14 +1,11 @@
 # frozen_string_literal: true
 
 require 'rake/clean'
-require 'rake/testtask'
+require 'minitest/test_task'
 require 'fileutils'
 require 'date'
 
 task default: :test
-task spec: :test
-
-CLEAN.include '**/*.rbc'
 
 def source_version
   @source_version ||= File.read(File.expand_path('VERSION', __dir__)).strip
@@ -24,27 +21,20 @@ def prev_version
   source_version.gsub(/\d+$/) { |s| s.to_i - 1 }
 end
 
-# SPECS ===============================================================
+# Tests ===============================================================
 
-Rake::TestTask.new(:test) do |t|
-  t.test_files = FileList['test/*_test.rb']
-  t.ruby_opts = ['-r rubygems'] if defined? Gem
+Minitest::TestTask.create # Default `test` task
+Minitest::TestTask.create(:'test:core') do |t|
   t.warning = true
-end
-
-Rake::TestTask.new(:'test:core') do |t|
-  core_tests = %w[
+  t.test_globs = %w[
     base delegator encoding extensions filter
     helpers mapped_error middleware rdoc
     readme request response result route_added_hook
     routing server settings sinatra static templates
-  ]
-  t.test_files = core_tests.map { |n| "test/#{n}_test.rb" }
-  t.ruby_opts = ['-r rubygems'] if defined? Gem
-  t.warning = true
+  ].map { |n| "test/#{n}_test.rb" }
 end
 
-# Rcov ================================================================
+# Test code coverage ==================================================
 
 namespace :test do
   desc 'Measures test coverage'
@@ -54,6 +44,7 @@ namespace :test do
     Rake::Task['test'].invoke
   end
 end
+CLEAN.include('coverage')
 
 # Website =============================================================
 
@@ -200,7 +191,7 @@ if defined?(Gem)
       end
     end
 
-    desc 'Commits the version to github repository'
+    desc 'Commits the version to git (no push)'
     task :commit_version do
       %w[
         lib/sinatra
@@ -212,10 +203,22 @@ if defined?(Gem)
       end
 
       sh <<-SH
-        git commit --allow-empty -a -m '#{source_version} release'  &&
-        git tag -s v#{source_version} -m '#{source_version} release'  &&
-        git push && (git push origin || true) &&
-        git push --tags && (git push origin --tags || true)
+        git commit --allow-empty --all --message '#{source_version} release'
+      SH
+    end
+
+    desc 'Tags the version in git (no push)'
+    task :tag_version do
+      sh <<-SH
+        git tag --sign v#{source_version} --message '#{source_version} release'
+      SH
+    end
+
+    desc 'Watch the release workflow run'
+    task :watch do
+      sh <<-SH
+        runId=$(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[].databaseId')
+        gh run watch --interval 1 --exit-status $runId
       SH
     end
 

data/SECURITY.md

@@ -6,7 +6,7 @@ After the initial reply to your report the security team will endeavor to keep y
 
 If you have not received a reply to your email within 48 hours, or have not heard from the security team for the past five days there are a few steps you can take:
 
-* Contact the current security coordinator [Zachary Scott](mailto:zzak@ruby-lang.org) directly
+* Reach out to us on [discord](https://discord.gg/ncjsfsNHh7)
 
 ## Disclosure Policy
 

data/VERSION

@@ -1 +1 @@
-3.0.5
+4.0.0

data/examples/chat.rb

@@ -1,11 +1,13 @@
 #!/usr/bin/env ruby -I ../lib -I lib
 # frozen_string_literal: true
 
-require_relative 'rainbows'
+# This example does *not* work properly with WEBrick or other
+# servers that buffer output. To shut down the server, close any
+# open browser tabs that are connected to the chat server.
 
 require 'sinatra'
-set :server, :rainbows
-connections = []
+set :server, :puma
+connections = Set.new
 
 get '/' do
   halt erb(:login) unless params[:user]
@@ -14,13 +16,22 @@ end
 
 get '/stream', provides: 'text/event-stream' do
   stream :keep_open do |out|
-    connections << out
-    out.callback { connections.delete(out) }
+    if connections.add?(out)
+      out.callback { connections.delete(out) }
+    end
+    out << "heartbeat:\n"
+    sleep 1
+  rescue
+    out.close
   end
 end
 
 post '/' do
-  connections.each { |out| out << "data: #{params[:msg]}\n\n" }
+  connections.each do |out|
+    out << "data: #{params[:msg]}\n\n"
+  rescue
+    out.close
+  end
   204 # response without entity body
 end
 
@@ -37,10 +48,10 @@ __END__
 </html>
 
 @@ login
-<form action='/'>
+<form action="/">
   <label for='user'>User Name:</label>
-  <input name='user' value='' />
-  <input type='submit' value="GO!" />
+  <input name="user" value="" />
+  <input type="submit" value="GO!" />
 </form>
 
 @@ chat

data/examples/lifecycle_events.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby -I ../lib -I lib
+# frozen_string_literal: true
+
+require 'sinatra'
+
+get('/') do
+  'This shows how lifecycle events work'
+end
+
+on_start do
+  puts "=============="
+  puts "  Booting up"
+  puts "=============="
+end
+
+on_stop do
+  puts "================="
+  puts "  Shutting down"
+  puts "================="
+end

data/examples/stream.ru

@@ -4,10 +4,8 @@
 #
 # run *one* of these:
 #
-#   rackup -s mongrel stream.ru         # gem install mongrel
 #   unicorn stream.ru                   # gem install unicorn
 #   puma stream.ru                      # gem install puma
-#   rainbows -c rainbows.conf stream.ru # gem install rainbows eventmachine
 
 require 'sinatra/base'