jdx-sinatra-param 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 25b304c125e3f1409ede06a86888a15bb4ec4e3184242213c944f6e2022facee
+  data.tar.gz: edd31eedf1724a9f7e67741ce445b99ca5bbfa4bec01e65c86494e4a2ff99616
+SHA512:
+  metadata.gz: 56cbcf65a1de6583bd380ae27967401c24036b2f76255d3cd9dceccc3467b355d7310edfe71144e19b0df94d6701500dcaeabb8b0bbfa3a75a6f864398e620b9
+  data.tar.gz: 93680828a46da46330bc7604f87b912c295391a2c98538cff231b837bbdf3ee734b9b8ca91b56e3eb05a7529a6f34efa2abba44b6f1df51decc446cc54da11ec

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2012–2018 Mattt (http://mat.tt/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,182 @@
+# sinatra-param
+
+_Parameter Validation & Type Coercion for Sinatra_
+
+REST conventions take the guesswork out of designing and consuming web APIs. Simply `GET`, `POST`, `PATCH`, or `DELETE` resource endpoints, and you get what you'd expect.
+
+However, when it comes to figuring out what parameters are expected... well, all bets are off.
+
+This Sinatra extension takes a first step to solving this problem on the developer side
+
+**`sinatra-param` allows you to declare, validate, and transform endpoint parameters as you would in frameworks like [ActiveModel](http://rubydoc.info/gems/activemodel/3.2.3/frames) or [DataMapper](http://datamapper.org/).**
+
+> Use `sinatra-param` in combination with [`Rack::PostBodyContentTypeParser` and `Rack::NestedParams`](https://github.com/rack/rack-contrib) to automatically parameterize JSON `POST` bodies and nested parameters.
+
+## Install
+
+You can install `sinatra-param` from the command line with the following:
+
+```bash
+$ gem install sinatra-param
+```
+
+Alternatively, you can specify `sinatra-param` as a dependency in your `Gemfile` and run `$ bundle install`:
+
+```ruby
+gem "sinatra-param", require: "sinatra/param"
+```
+
+## Example
+
+```ruby
+require 'sinatra/base'
+require 'sinatra/param'
+require 'json'
+
+class App < Sinatra::Base
+  helpers Sinatra::Param
+
+  before do
+    content_type :json
+  end
+
+  # GET /search?q=example
+  # GET /search?q=example&categories=news
+  # GET /search?q=example&sort=created_at&order=ASC
+  get '/search' do
+    param :q,           String, required: true
+    param :categories,  Array
+    param :sort,        String, default: "title"
+    param :order,       String, in: ["ASC", "DESC"], transform: :upcase, default: "ASC"
+    param :price,       String, format: /[<\=>]\s*\$\d+/
+
+    one_of :q, :categories
+
+    {...}.to_json
+  end
+end
+```
+
+### Parameter Types
+
+By declaring parameter types, incoming parameters will automatically be transformed into an object of that type. For instance, if a param is `Boolean`, values of `'1'`, `'true'`, `'t'`, `'yes'`, and `'y'` will be automatically transformed into `true`.
+
+* `String`
+* `Integer`
+* `Float`
+* `Boolean` _("1/0", "true/false", "t/f", "yes/no", "y/n")_
+* `Array` _("1,2,3,4,5")_
+* `Hash` _(key1:value1,key2:value2)_
+* `Date`, `Time`, & `DateTime`
+
+### Validations
+
+Encapsulate business logic in a consistent way with validations. If a parameter does not satisfy a particular condition, a `400` error is returned with a message explaining the failure.
+
+* `required`
+* `blank`
+* `is`
+* `in`, `within`, `range`
+* `min` / `max`
+* `min_length` / `max_length`
+* `format`
+
+### Custom Error Messages
+
+Passing a `message` option allows you to customize the message
+for any validation error that occurs.
+
+```ruby
+param :spelling,
+      format: /\b(?![a-z]*cie)[a-z]*(?:cei|ie)[a-z]*/i,
+      message: "'i' before 'e', except after 'c'"
+```
+
+### Defaults and Transformations
+
+Passing a `default` option will provide a default value for a parameter if none is passed. A `default` can defined as either a default or as a `Proc`:
+
+```ruby
+param :attribution, String, default: "©"
+param :year, Integer, default: lambda { Time.now.year }
+```
+
+Use the `transform` option to take even more of the business logic of parameter I/O out of your code. Anything that responds to `to_proc` (including `Proc` and symbols) will do.
+
+```ruby
+param :order, String, in: ["ASC", "DESC"], transform: :upcase, default: "ASC"
+param :offset, Integer, min: 0, transform: lambda {|n| n - (n % 10)}
+```
+
+## One Of
+
+Using `one_of`, routes can specify two or more parameters to be mutually exclusive, and fail if _more than one_ of those parameters is provided:
+
+```ruby
+param :a, String
+param :b, String
+param :c, String
+
+one_of :a, :b, :c
+```
+
+## Any Of
+
+Using `any_of`, a route can specify that _at least one of_ two or more parameters are required, and fail if _none of them_ are provided:
+
+```ruby
+param :x, String
+param :y, String
+
+any_of :x, :y
+```
+
+## All Or None Of
+
+Using `all_or_none_of`, a router can specify that _all_ or _none_ of a set of parameters are required, and fail if _some_ are provided:
+
+```ruby
+param :x, String
+param :y, String
+
+all_or_none_of :x,:y
+```
+
+### Exceptions
+
+By default, when a parameter precondition fails, `Sinatra::Param` will `halt 400` with an error message:
+
+```json
+{
+  "message": "Parameter must be within [\"ASC\", \"DESC\"]",
+  "errors": {
+    "order": "Parameter must be within [\"ASC\", \"DESC\"]"
+  }
+}
+```
+
+To change this, you can set `:raise_sinatra_param_exceptions` to `true`, and intercept `Sinatra::Param::InvalidParameterError` with a Sinatra `error do...end` block. (To make this work in development, set `:show_exceptions` to `false` and `:raise_errors` to `true`):
+
+```ruby
+set :raise_sinatra_param_exceptions, true
+
+error Sinatra::Param::InvalidParameterError do
+    { error: "#{env['sinatra.error'].param} is invalid" }.to_json
+end
+```
+
+Custom exception handling can also be enabled on an individual parameter basis, by passing the `raise` option:
+
+```ruby
+param :order, String, in: ["ASC", "DESC"], raise: true
+
+one_of :q, :categories, raise: true
+```
+
+## Contact
+
+Mattt ([@mattt](http://twitter.com/mattt))
+
+## License
+
+sinatra-param is released under an MIT license. See LICENSE for more information.

data/Rakefile

@@ -0,0 +1,18 @@
+require "bundler"
+Bundler.setup
+
+gemspec = eval(File.read("sinatra-param.gemspec"))
+
+task :build => "#{gemspec.full_name}.gem"
+
+file "#{gemspec.full_name}.gem" => gemspec.files + ["sinatra-param.gemspec"] do
+  system "gem build sinatra-param.gemspec"
+end
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+
+  task :default => :spec
+rescue LoadError
+end

data/example/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+gem 'sinatra', '~> 2.0', require: 'sinatra/base'
+gem 'sinatra-param', path: File.join(__FILE__, "../.."), require: 'sinatra/param'

data/example/Procfile

@@ -0,0 +1 @@
+web: bundle exec rackup --port $PORT

data/example/app.rb

@@ -0,0 +1,52 @@
+class App < Sinatra::Base
+  helpers Sinatra::Param
+
+  before do
+    content_type :json
+  end
+
+  # GET /messages
+  # GET /messages?sort=name&order=ASC
+  get '/messages' do
+    param :sort,  String, default: "name"
+    param :order, String, in: ["ASC", "DESC"], transform: :upcase, default: "ASC"
+
+    {
+      sort: params[:sort],
+      order: params[:order]
+    }.to_json
+  end
+
+  # GET /messages/1,2,3,4,5
+  get '/messages/:ids' do
+    param :ids, Array, required: true
+
+    {
+      ids: params[:ids]
+    }.to_json
+  end
+
+  # POST /messages/1/response
+  post '/messages/:id/response' do
+    param :message, String, max: 1024, required: true
+
+    {
+      message: params[:message]
+    }.to_json
+  end
+
+  # GET /choice?a=foo
+  # GET /choice?b=bar
+  # GET /choice?c=baz
+  get '/choice' do
+    param :a, String
+    param :b, String
+    param :c, String
+
+    one_of(:a, :b, :c)
+
+    {
+      message: 'OK'
+    }.to_json
+  end
+end

data/example/config.ru

@@ -0,0 +1,6 @@
+require 'bundler'
+Bundler.require
+
+require './app'
+
+run App

data/lib/sinatra/param.rb

@@ -0,0 +1,199 @@
+require 'sinatra/base'
+require 'sinatra/param/version'
+require 'date'
+require 'time'
+
+module Sinatra
+  module Param
+    Boolean = :boolean
+
+    class InvalidParameterError < StandardError
+      attr_accessor :param, :options
+    end
+
+    def param(name, type, options = {})
+      name = name.to_s
+
+      return unless params.member?(name) or options.has_key?(:default) or options[:required]
+
+      begin
+        params[name] = coerce(name, params[name], type, options)
+        params[name] = (options[:default].call if options[:default].respond_to?(:call)) || options[:default] if params[name].nil? and options.has_key?(:default)
+        params[name] = options[:transform].to_proc.call(params[name]) if params[name] and options[:transform]
+        validate!(params[name], name, options)
+        params[name]
+      rescue InvalidParameterError => exception
+        if options[:raise] or (settings.raise_sinatra_param_exceptions rescue false)
+          exception.param, exception.options = name, options
+          raise exception
+        end
+
+        error = options[:message] || exception.to_s
+
+        if content_type and content_type.match(mime_type(:json))
+          error = {error: error}.to_json
+        else
+          content_type 'text/plain'
+        end
+
+        halt 400, error
+      end
+    end
+
+    # def one_of(*args)
+    #   options = args.last.is_a?(Hash) ? args.pop : {}
+    #   names = args.collect(&:to_s)
+
+    #   return unless names.length >= 2
+
+    #   begin
+    #     validate_one_of!(params, names, options)
+    #   rescue InvalidParameterError => exception
+    #     if options[:raise] or (settings.raise_sinatra_param_exceptions rescue false)
+    #       exception.param, exception.options = names, options
+    #       raise exception
+    #     end
+
+    #     error = "Invalid parameters [#{names.join(', ')}]"
+    #     if content_type and content_type.match(mime_type(:json))
+    #       error = {message: error, errors: {names => exception.message}}.to_json
+    #     end
+
+    #     halt 400, error
+    #   end
+    # end
+
+    # def any_of(*args)
+    #   options = args.last.is_a?(Hash) ? args.pop : {}
+    #   names = args.collect(&:to_s)
+
+    #   return unless names.length >= 2
+
+    #   begin
+    #     validate_any_of!(params, names, options)
+    #   rescue InvalidParameterError => exception
+    #     if options[:raise] or (settings.raise_sinatra_param_exceptions rescue false)
+    #       exception.param, exception.options = names, options
+    #       raise exception
+    #     end
+
+    #     error = "Invalid parameters [#{names.join(', ')}]"
+    #     if content_type and content_type.match(mime_type(:json))
+    #       error = {message: error, errors: {names => exception.message}}.to_json
+    #     end
+
+    #     halt 400, error
+    #   end
+    # end
+
+    # def all_or_none_of(*args)
+    #   options = args.last.is_a?(Hash) ? args.pop : {}
+    #   names = args.collect(&:to_s)
+
+    #  begin
+    #     validate_all_or_none_of!(params, names, options)
+    #   rescue InvalidParameterError => exception
+    #     if options[:raise] or (settings.raise_sinatra_param_exceptions rescue false)
+    #       exception.param, exception.options = names, options
+    #       raise exception
+    #     end
+
+    #     error = "Invalid parameters [#{names.join(', ')}]"
+    #     if content_type and content_type.match(mime_type(:json))
+    #       error = {message: error, errors: {names => exception.message}}.to_json
+    #     end
+
+    #     halt 400, error
+    #   end
+    # end
+
+    private
+
+    def coerce(param_name, param, type, options = {})
+      begin
+        return nil if param.nil?
+        return param if (param.is_a?(type) rescue false)
+        return Integer(param, 10) if type == Integer
+        return Float(param) if type == Float
+        return String(param) if type == String
+        return Date.parse(param) if type == Date
+        return Time.parse(param) if type == Time
+        return DateTime.parse(param) if type == DateTime
+        return Array(param.split(options[:delimiter] || ",")) if type == Array
+        return Hash[param.split(options[:delimiter] || ",").map{|c| c.split(options[:separator] || ":")}] if type == Hash
+        if [TrueClass, FalseClass, Boolean].include? type
+          coerced = /^(false|f|no|n|0)$/i === param.to_s ? false : /^(true|t|yes|y|1)$/i === param.to_s ? true : nil
+          raise ArgumentError if coerced.nil?
+          return coerced
+        end
+        return nil
+      rescue ArgumentError
+        raise InvalidParameterError, "Parameter #{param_name} '#{param}' is not a valid #{type}"
+      end
+    end
+
+    def validate!(param, param_name, options)
+      options.each do |key, value|
+        case key
+        when :required
+          raise InvalidParameterError, "Parameter #{param_name} is required" if value && param.nil?
+        when :blank
+          raise InvalidParameterError, "Parameter #{param_name} cannot be blank" if !value && case param
+          when String
+            !(/\S/ === param)
+          when Array, Hash
+            param.empty?
+          else
+            param.nil?
+          end
+        when :format
+          raise InvalidParameterError, "Parameter #{param_name} must be a string if using the format validation" unless param.kind_of?(String)
+          raise InvalidParameterError, "Parameter #{param_name} must match format #{value}" unless param =~ value
+        when :is
+          raise InvalidParameterError, "Parameter #{param_name} must be #{value}" unless param === value
+        when :in, :within, :range
+          raise InvalidParameterError, "Parameter #{param_name} must be within #{value}" unless param.nil? || case value
+          when Range
+            value.include?(param)
+          else
+            Array.wrap(value).any? {|v| Array.wrap(param).include?(v)}
+          end
+        when :min
+          raise InvalidParameterError, "Parameter #{param_name} cannot be less than #{value}" unless param.nil? || value <= param
+        when :max
+          raise InvalidParameterError, "Parameter #{param_name} cannot be greater than #{value}" unless param.nil? || value >= param
+        when :min_length
+          raise InvalidParameterError, "Parameter #{param_name} cannot have length less than #{value}" unless param.nil? || value <= param.length
+        when :max_length
+          raise InvalidParameterError, "Parameter #{param_name} cannot have length greater than #{value}" unless param.nil? || value >= param.length
+        when :custom
+            raise InvalidParameterError, "Parameter #{param_name} is not valid" unless value.to_proc.call(param)
+        end
+      end
+    end
+
+    # def validate_one_of!(params, names, options)
+    #   raise InvalidParameterError, "Only one of [#{names.join(', ')}] is allowed" if names.count{|name| present?(params[name])} > 1
+    # end
+
+    # def validate_any_of!(params, names, options)
+    #   raise InvalidParameterError, "One of parameters [#{names.join(', ')}] is required" if names.count{|name| present?(params[name])} < 1
+    # end
+
+    # def validate_all_or_none_of!(params, names, options)
+    #   present_count = names.count{|name| present?(params[name])}
+    #   raise InvalidParameterError, "All or none of parameters [#{names.join(', ')}] are required" if present_count > 0 and present_count != names.length
+    # end
+
+    # ActiveSupport #present? and #blank? without patching Object
+    # def present?(object)
+    #   !blank?(object)
+    # end
+
+    # def blank?(object)
+    #   object.respond_to?(:empty?) ? object.empty? : !object
+    # end
+  end
+
+  helpers Param
+end