sinatra-browse 0.2 → 0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: eb3a18b58acc57c6a80b56bf6a0e08d96e2b04e0
-  data.tar.gz: 87150a5f51798b69ac97540940caec5ba16a5f9d
+  metadata.gz: 582bf7da2ddf0b18a42136d6fb4c52b8bf929f46
+  data.tar.gz: 4c37bf5a4830a81b5c11c5c4cf4f3f95e17f8252
 SHA512:
-  metadata.gz: 64b8e196681b25a346f8f0cfe135e220a9ebd1b38da76c50481491be880e9817d2384b293e588da7f4155bb0f7131cff9cef974516146bc230452775b8c285e7
-  data.tar.gz: 004f30d10ea627e10adce8b34a2115c820ff2b0934bbc3af47bb2a9d3116e154d04fd2d92a6d671047aaa4961674e42adf636e194706072d03c43581b8a431bf
+  metadata.gz: 9b2bd51af3b6e7532122077dd7496e23695946d5b23d17c061fbeff1be7d5507761a3bca5dd6452febdc993a368fc938bb4248edddd6420ab1090d03abdb725c
+  data.tar.gz: 634102de18bd57e1877dc1672b8e5b1df5d0b2db7172de3041c10b7ef6dea538a24f23390e206f26e4ec31cbdd637bf7b55001e95d3e38b9219124a90835b943

data/README.md

@@ -96,12 +96,21 @@ param :order, :String, in: ["ascending", "descending"]
 param :alphanumeric, :String, format: /^[0-9A-Za-z]*$/
 ```
 
+## Parameter transformation
+
+You can use transform to execute a quick method on any prameter provided. Anything that responds to *to_proc* will do.
+
+```ruby
+param :only_caps, :String, transform: :upcase
+param :power_of_two, :Integer, transform: proc { |n| n * n }
+```
+
 ## Error handling
 
 When a validation fails, a standard 400 error will be returned. You can override this and do your own error handling using `on_error`.
 
 ```ruby
-param :lets_fail, :Integer, in: 1..9, on_error: proc { halt 404, "if you're not giving us a number between 1 and 9, we're going to pretend not to be here!" }
+param :lets_fail, :Integer, in: 1..9, on_error: proc { halt 400, "Must be between 1 and 9!" }
 get 'example_route' do
   # This is the scope that the on_error proc will be executed in.
 end
@@ -109,20 +118,82 @@ end
 
 If a request is made that fails validation on the *lets_fail* parameter, then the proc provided to `on_error` will be called **in the same scope as your route**. Therefore you have access to Sinatra keywords such as *halt*.
 
-## Parameter transformation
+### The error hash
 
-You can use transform to execute a quick method on any prameter provided. Anything that will respond to *to_proc* will do.
+If you want to write a bit more intricate error handling, you can add *the error hash* as an argument to your `on_error` proc. This hash holds some extra information about what exactly went wrong.
 
 ```ruby
-param :only_caps, :String, transform: :upcase
-param :power_of_two, :Integer, transform: proc { |n| n * n }
+param :lets_fail, :Integer, in: 1..9, required: true, on_error: proc { |error_hash|
+  case error_hash[:reason]
+  when :in
+    halt 400, "Must be between 1 and 9!"
+  when :required
+    halt 400, "Why u no give us lets_fail?"
+  end
+}
+get 'example_route' do
+  # Some code
+end
+```
+
+The error hash contains the following keys:
+
+* `:reason` This tells you what validation failed. Possible values could be `:in`, `:required`, `:format`, etc.
+* `:parameter` The name of the faulty parameter.
+* `:value` The value our parameter had which caused it to fail validation.
+* `:type` The type of our parameter. Could be `:String`, `:Integer`, etc.
+* Any validation keys that were set in the parameter declaration will also be available in the error hash.
+
+### Overriding default error behaviour
+
+So we explained how to do error handling for single parameters. Now what if we wanted to set error handling for the entire application? You can do that with the `default_on_error` method.
+
+```ruby
+default_on_error do |error_hash|
+  case error_hash[:reason]
+  when :required
+    halt 400, "#{error_hash[:parameter]} is required! provide it!"
+  else
+    _default_on_error(error_hash)
+  end
+end
+
+param :a, :String, in: ["a"], required: true
+param :b, :String, format: /^bbb$/
+get "/features/default_error_override" do
+  # Again this is the scope that default_on_error is executed in
+  params.to_json
+end
 ```
+
+The block we passed to the `default_on_error` method will be called or every parameter in our application that fails validation and does not have its own `on_error` block. Notice how inside our `default_on_error`
+
+You might notice that in our example, the `default_on_error` method makes a call to `_default_on_error`. The latter is a fallback to sinatra-browse's standard error behaviour. It's available form both the `default_on_error` block and procs passed to `on_error` in parameter declarations.
+
 ## Removing undefined parameters
 
 By default sinatra-browse removes all parameters that weren't defined. You can disable this behaviour with the following line.
 
-    disable :remove_undefined_parameters
+```ruby
+disable :remove_undefined_parameters
+```
+
+You can also set a `allowed_undefined_parameters` variable to allow for a select few parameters that aren't removed.
+
+```ruby
+set allowed_undefined_parameters: [ "id", "username", "password" ]
+```
+
+## Named parameters in route patterns
+
+Unfortunately you are not able to use Sinatra-browse for named parameters in the route definition. Take the following example.
+
+```ruby
+get 'foo/:bar' do
+  # some code
+end
+```
 
-You can also set a `system_parameters` variable to allow for a select few parameters that aren't removed. By default this is set to *[ "splat", "captures" ]*.
+You will ***not*** be able to define the parameter `bar`. This is because Sinatra-browse does its thing in a before block and these parameters aren't added to the `params` hash until the route itself gets executed.
 
-    set system_parameters: [ "id", "username", "password" ]
+Some exta discussion of this problem can be found [here](https://github.com/sinatra/sinatra/issues/417).

data/lib/sinatra/browse/route.rb

@@ -53,17 +53,17 @@
       }
     end
 
-    def delete_undefined(params, system_params)
-      params.delete_if { |i| !(self.has_parameter?(i) || system_params.member?(i)) }
+    def delete_undefined(params, allowed)
+      params.delete_if { |i| !(self.has_parameter?(i) || allowed.member?(i)) }
     end
 
     def validate(params)
       @parameters.each { |k,v|
-        return fail_validation v, :required if !params[k] && v[:required]
+        return fail_validation k, params[k], v, :required if !params[k] && v[:required]
         if params[k]
-          return fail_validation v, :depends_on if v[:depends_on] && !params[v[:depends_on]]
-          return fail_validation v, :in if v[:in] && !v[:in].member?(params[k])
-          return fail_validation v, :format if v[:type] == :String && v[:format] && !(params[k] =~ v[:format])
+          return fail_validation k, params[k], v, :depends_on if v[:depends_on] && !params[v[:depends_on]]
+          return fail_validation k, params[k], v, :in if v[:in] && !v[:in].member?(params[k])
+          return fail_validation k, params[k], v, :format if v[:type] == :String && v[:format] && !(params[k] =~ v[:format])
         end
       }
 
@@ -86,8 +86,8 @@
       end
     end
 
-    def fail_validation(parameter, reason)
-      { success: false, reason: reason }.merge parameter
+    def fail_validation(parameter, value, options, reason)
+      {success: false, reason: reason , parameter: parameter, value: value}.merge(options)
     end
 
     def build_name(request_method, path_info)

data/lib/sinatra/browse.rb

@@ -46,21 +46,40 @@ module Sinatra::Browse
     browse_routes[new_route.name] = new_route
   end
 
+  def default_on_error(&blk)
+    @default_on_error = blk if block_given?
+    @default_on_error
+  end
+
   def self.registered(app)
     @app = app
 
     app.enable :remove_undefined_parameters
-    app.set system_parameters: ["splat", "captures"]
+    app.set allowed_undefined_parameters: []
+
+    app.disable :show_head_routes
+
+    app.class_eval {
+      def _default_on_error(error_hash)
+        halt 400, {
+          error: "parameter validation failed",
+          parameter: error_hash[:parameter],
+          value: error_hash[:value],
+          reason: error_hash[:reason]
+        }.to_json
+      end
+    }
+
+    app.default_on_error { |error_hash| _default_on_error(error_hash) }
 
     app.before do
       browse_route = app.browse_routes_for(request.request_method, request.path_info)
 
       if browse_route
         #TODO: Optionally throw error for undefined params
-        #TODO: Make undefined parameter deletion optional per route
 
         if settings.remove_undefined_parameters
-          browse_route.delete_undefined(params, settings.system_parameters)
+          browse_route.delete_undefined(params, settings.allowed_undefined_parameters)
         end
 
         browse_route.coerce_type(params)
@@ -68,13 +87,10 @@ module Sinatra::Browse
         validation_result = browse_route.validate(params)
         unless validation_result[:success]
           if validation_result[:on_error].respond_to?(:to_proc)
-            instance_exec &validation_result[:on_error].to_proc
+            error_proc = validation_result.delete(:on_error).to_proc
+            instance_exec validation_result, &error_proc
           else
-            halt 400, {
-              error: "parameter validation failed",
-              parameter: validation_result[:name],
-              reason: validation_result[:reason]
-            }.to_json
+            instance_exec validation_result, &app.default_on_error
           end
         end
         browse_route.transform(params)
@@ -89,6 +105,7 @@ module Sinatra::Browse
   end
 
   def self.route_added(verb, path, block)
+    return if verb == "HEAD" && !@app.settings.show_head_routes
     @app.set_browse_routes_for(verb, path)
     @app.reset_temp_params
     @app.desc ""

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-browse
 version: !ruby/object:Gem::Version
-  version: '0.2'
+  version: '0.3'
 platform: ruby
 authors:
 - Axsh Co. LTD
@@ -18,7 +18,6 @@ extra_rdoc_files: []
 files:
 - lib/sinatra/browse.rb
 - lib/sinatra/browse/route.rb
-- lib/sinatra/browse/parameter.rb
 - lib/sinatra/browse/format.rb
 - LICENSE
 - README.md

data/lib/sinatra/browse/parameter.rb

@@ -1,49 +0,0 @@
-# -*- coding: utf-8 -*-
-
-module Sinatra::Browse
-  def ValidationError < Exception; end
-
-  class Validation
-    attr_reader :fail_message
-  end
-
-  class In < Validation
-    def fail_message(value, accepted)
-      "Invalid value: '#{value}'. Must be a member of #{accepted.inspect}."
-    end
-    
-    def validate(value)
-    end
-
-    def fail(value, accepted)
-      raise ValidationError, fail_message(value, accepted)
-    end
-  end
-
-  class Parameter
-    attr_reader :value
-
-    def initialize(value)
-      @value = coerce(value)
-    end
-
-    def validate()
-    end
-  end
-
-  class BPString < Parameter
-    def coerce(v); String(v) end
-  end
-
-  class BPBoolean < Parameter
-    def coerce(v)
-      case v
-      when "y", "yes", "t", "true", "1"
-        true
-      when "n", "no", "f", "false", "0"
-        false
-      end
-    end
-  end
-end
-