syro 3.0.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 88701e942289c077ba534c8779ee97c650d23973
-  data.tar.gz: 65731a7bc5389784eeaadfb8fa55d938e30d41ca
+  metadata.gz: 585d2fe3559bfaa4cc09f2a6b25efac445ca739b
+  data.tar.gz: 99a97c194e80a465474f2439a7f80e938f6e69c8
 SHA512:
-  metadata.gz: f83855e744ad2f3efe4508d6b0a9221262664a2e2ec5d62d75735157a5323e387529dd0e60b52605002f2d2690f6af46a9dce875c13730f3ad60373cf2ebedf3
-  data.tar.gz: 31b066cd541d148bfe8ae8c2919f1ba27428de6cba381ab9b0157b768c688dbe9341b60d9f19569e759f1ab7199210ac6b3e45a52fd7d227af767886832bbaec
+  metadata.gz: 23adfa66e18f592c65688248b8f9c4f625c988c8a6392e84ea578cc2263396ef5170b1cde6a27132aa43b3139679f1e523ddfd38d07cf4ddb7fa09fd0f3a7804
+  data.tar.gz: e1ae691f6c4d9fee2aaaec0c814519bc0bb4cd6a765dea46b63e978564426bd9763b946e8e203e2ad8b0f64f55a766c2ad4be667a171180d85bacb08db9e6c3d

data/README.md

@@ -48,10 +48,10 @@ end
 
 The block is evaluated in a sandbox where the following methods are
 available: `env`, `req`, `res`, `path`, `inbox`, `call`, `run`,
-`halt`, `consume`, `capture`, `root?` `match`, `default`, `on`,
-`root`,`get`, `put`, `head`, `post`, `patch`, `delete` and `options`.
-Three other methods are available for customizations: `default_headers`,
-`request_class` and `response_class`.
+`halt`, `handle`, `finish!`, `consume`, `capture`, `root?` `match`,
+`default`, `on`, `root`,`get`, `put`, `head`, `post`, `patch`,
+`delete` and `options`. Three other methods are available for
+customizations: `default_headers`, `request_class` and `response_class`.
 
 As a recommendation, user created variables should be instance
 variables. That way they won't mix with the API methods defined in
@@ -83,6 +83,12 @@ argument.
 `halt`: Terminates the request. It receives an array with the
 response as per Rack's specification.
 
+`handle`: Installs a handler for a given status code. It receives
+a status code and a block that will be executed from `finish!`.
+
+`finish!`: Terminates the request by executing any installed handlers
+and then halting with the current value of `res.finish`.
+
 `consume`: Match and consume a path segment.
 
 `capture`: Match and capture a path segment. The value is stored in
@@ -254,6 +260,78 @@ post do
 end
 ```
 
+Handlers
+--------
+
+Status code handlers can be installed with the `handle` command,
+which receives a status code and a block to be executed just before
+finishing the request.
+
+By default, if there are no matches in a Syro application the
+response is a `404` with an empty body. If we decide to handle the
+`404` requests and return a string, we can do as follows:
+
+```ruby
+App = Syro.new do
+  handle 404 do
+    res.text "Not found!"
+  end
+
+  get do
+    res.text "Found!
+  end
+end
+```
+
+In this example, a `GET` request to `"/"` will return a status `200`
+with the body `"Found!"`. Any other request will return a `404`
+with the body `"Not found!"`.
+
+If a new handler is installed for the same status code, the previous
+handler is overwritten. A handler is valid in the current scope and
+in all its nested branches. Blocks that end before the handler is
+installed are not affected.
+
+This is a contrived example that shows some edge cases when using handlers:
+
+```ruby
+App = Syro.new do
+  on "foo" do
+    # 404, empty body
+  end
+
+  handle 404 do
+    res.text "Not found!"
+  end
+
+  on "bar" do
+    # 404, body is "Not found!"
+  end
+
+  on "baz" do
+    # 404, body is "Couldn't find baz"
+
+    handle 404 do
+      res.text "Couldn't find baz"
+    end
+  end
+end
+```
+
+A request to `"/foo"` will return a `404`, because the request
+method was not matched. But as the `on "foo"` block ends before the
+handler is installed, the result will be a blank screen. On the
+other hand, a request to `"/bar"` will return a `404` with the plain
+text `"Not found!"`.
+
+Finally, a request to `"/baz"` will return a `404` with the plain text
+`"Couldn't find baz"`, because by the time the `on "baz"` block ends
+a new handler is installed, and thus the previous one is overwritten.
+
+Any status code can be handled this way, even status `200`. In that
+case the handler will behave as a filter to be run after each
+successful request.
+
 Content type
 ------------
 
@@ -317,11 +395,11 @@ just use `Rack::Builder`:
 App = Rack::Builder.new do
   use Rack::Session::Cookie, secret: "..."
 
-  run Syro.new do
+  run Syro.new {
     get do
       res.write("Hello, world")
     end
-  end
+  }
 end
 ```
 

data/lib/syro.rb

@@ -269,8 +269,7 @@ class Syro
 
         catch(:halt) do
           instance_eval(&@syro_code)
-
-          @syro_res.finish
+          finish!
         end
       end
 
@@ -297,6 +296,64 @@ class Syro
         throw(:halt, response)
       end
 
+      # Install a handler for a given status code. Once a handler is
+      # installed, it will be called by Syro before halting the
+      # request.
+      #
+      #     handle 404 do
+      #       res.text "Not found!"
+      #     end
+      #
+      # If a new handler is installed for the same status code, the
+      # previous handler is overwritten. A handler is valid in the
+      # current scope and in all its nested branches. Blocks that end
+      # before the handler is installed are not affected.
+      #
+      # For example:
+      #
+      #     on "foo" do
+      #       # Not found
+      #     end
+      #
+      #     handle 404 do
+      #       res.text "Not found!"
+      #     end
+      #
+      #     on "bar" do
+      #       # Not found
+      #     end
+      #
+      #     on "baz" do
+      #       # Not found
+      #
+      #       handle 404 do
+      #         res.text "Couldn't find baz"
+      #       end
+      #     end
+      #
+      # A request to "/foo" will return a 404, because the request
+      # method was not matched. But as the `on "foo"` block ends
+      # before the handler is installed, the result will be a blank
+      # screen. On the other hand, a request to "/bar" will return a
+      # 404 with the plain text "Not found!".
+      #
+      # Finally, a request to "/baz" will return a 404 with the plain text
+      # "Couldn't find baz", because by the time the `on "baz"` block ends
+      # a new handler is installed, and thus the previous one is overwritten.
+      #
+      # Any status code can be handled this way, even status `200`.
+      # In that case the handler will behave as a filter to be run
+      # after each successful request.
+      #
+      def handle(status, &block)
+        inbox[status] = block
+      end
+
+      def finish!
+        inbox[res.status]&.call
+        halt(res.finish)
+      end
+
       def consume(arg)
         @syro_path.consume(arg)
       end
@@ -319,7 +376,7 @@ class Syro
       end
 
       def default
-        yield; halt(res.finish)
+        yield; finish!
       end
 
       def on(arg)

data/syro.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name              = "syro"
-  s.version           = "3.0.1"
+  s.version           = "3.1.0"
   s.summary           = "Simple router"
   s.description       = "Simple router for web applications"
   s.authors           = ["Michel Martens"]

data/test/all.rb

@@ -79,6 +79,26 @@ comments = Syro.new do
   end
 end
 
+handlers = Syro.new do
+  on "without_handler" do
+    # Not found
+  end
+
+  handle(404) do
+    res.text "Not found!"
+  end
+
+  on "with_handler" do
+    # Not found
+  end
+
+  on "with_local_handler" do
+    handle(404) do
+      res.text "Also not found!"
+    end
+  end
+end
+
 app = Syro.new do
   get do
     res.write "GET /"
@@ -194,6 +214,10 @@ app = Syro.new do
     run(json)
   end
 
+  on "handlers" do
+    run(handlers)
+  end
+
   on "private" do
     res.status = 401
     res.write("Unauthorized")
@@ -369,3 +393,25 @@ test "content type" do |f|
   f.get("/json")
   assert_equal "application/json", f.last_response.headers["Content-Type"]
 end
+
+test "status code handling" do |f|
+  f.get("/handlers")
+  assert_equal 404, f.last_response.status
+  assert_equal "text/plain", f.last_response.headers["Content-Type"]
+  assert_equal "Not found!", f.last_response.body
+
+  f.get("/handlers/without_handler")
+  assert_equal 404, f.last_response.status
+  assert_equal nil, f.last_response.headers["Content-Type"]
+  assert_equal "", f.last_response.body
+
+  f.get("/handlers/with_handler")
+  assert_equal 404, f.last_response.status
+  assert_equal "text/plain", f.last_response.headers["Content-Type"]
+  assert_equal "Not found!", f.last_response.body
+
+  f.get("/handlers/with_local_handler")
+  assert_equal 404, f.last_response.status
+  assert_equal "text/plain", f.last_response.headers["Content-Type"]
+  assert_equal "Also not found!", f.last_response.body
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: syro
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.1.0
 platform: ruby
 authors:
 - Michel Martens
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-27 00:00:00.000000000 Z
+date: 2018-02-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: seg
@@ -103,7 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
 summary: Simple router