rails-param-validation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 78a64263517a4c6d2d0c0e649cc7a3e4708f4ed1abb96beffb8a52b2acc2f8a0
+  data.tar.gz: dfd6039f8ce21dd31c7f96a93daf9c6b10a490107a4f96be6ceaa33f26e1a7fd
+SHA512:
+  metadata.gz: c4862edac9546192dddce87b4d0e846443611db3426ad4b91eb5c3827ddbc72cc7e283dfef1f3ed624ee18fcce52db21a4aa04b5ef359dcf85ea5f707dba5caf
+  data.tar.gz: d0606f8d37a4f2bf9e822c410779be3efbefec1e81c505179d3ecc26780202c0961e6f412bd1d4503a354d5b6c8395dd14ba6027f35840783574ad1a75bd642a

data/.gitignore

@@ -0,0 +1,2 @@
+coverage
+.idea

data/.gitlab-ci.yml

@@ -0,0 +1,34 @@
+test:2.3:
+  image: ruby:2.3
+  script:
+    - bundle install && rake spec
+
+test:2.4:
+  image: ruby:2.4
+  script:
+    - bundle install && rake spec
+
+test:2.5:
+  image: ruby:2.5
+  script:
+    - bundle install && rake spec
+
+test:2.6:
+  image: ruby:2.6
+  script:
+    - bundle install && rake spec
+
+test:2.7:
+  image: ruby:2.7
+  script:
+    - bundle install && rake spec
+
+test:jruby9.2:
+  image: jruby:9.2
+  script:
+    - bundle install && rake spec
+
+test:jruby9.1:
+  image: jruby:9.1
+  script:
+    - bundle install && rake spec

data/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in rails-param-validation.gemspec
+gemspec
+
+gem "rake", "~> 12.0"
+gem "rspec", "~> 3.0"
+gem "simplecov"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Oskar Kirmis
+
+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,63 @@
+# RailsParamValidation
+
+[![pipeline status](https://git.iftrue.de/okirmis/rails-param-validation/badges/master/pipeline.svg)](https://git.iftrue.de/okirmis/rails-param-validation/commits/master)
+
+This gem provides parameter validation for Rails using a declarative parameter definition and makes the automatic validation of complex parameters very easy. It also supports an export of the definition as an OpenAPI document.
+
+* [Why this gem?](./docs/main-idea.md)
+* [Getting started](./docs/getting-started.md)
+* [Annotations](./docs/annotations.md)
+* [How to specify types](./docs/type-definition.md)
+* [OpenAPI Export](./docs/openapi.md)
+
+## Quick Example
+
+Let's take a look at a very simple example: a controller with a sample action, which gets a list of floats, rounds them to the nearest integer and returns it in a json encoded form.
+
+```ruby
+class ExampleController
+  desc "Show the functionality of this gem"
+
+  action "Round float values" do
+    # Expect a parameter with the name "values" which contains an array of floats
+    query_param :values, ArrayType(Float), "Values to round"
+    # Document the response of http status 200, which is an array of integers
+    response 200, :success, ArrayType(Integer), "Rounded values response"
+  end
+  def sample_action
+    render json: params[:values].map(&:round)
+  end
+
+  # We assume GET /round to be mapped to this action
+end
+```
+
+Sending a valid request, the parameters are validated and casted correctly and we get the response one would expect:
+
+```
+$ curl -H "Accept: application/json" "http://localhost:3000/round?values[]=1.5&values[]=2.0&values[]=-0.777"
+[2,2,-1]
+```
+
+When a request with invalid parameters is sent, we get an error response which also describes the error.
+
+```
+$ curl -H "Accept: application/json" "http://localhost:3000/round?values[]=1.5&values[]=2.0&values[]=XYZ"
+{"status":"fail","errors":[{"path":"values/2","message":"Expected a float"}]}
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rails-param-validation'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install rails-param-validator

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/docs/_config.yml

@@ -0,0 +1,3 @@
+theme: jekyll-theme-slate
+title: Rails Parameter Validation
+description: Declarative, easy-to-use parameter validations and OpenAPI export

data/docs/annotations.md

@@ -0,0 +1,62 @@
+# Annotations
+
+## Controller annotations
+
+**desc**
+
+Define a description for the controller that is later used in the OpenAPI export.
+
+## Action annotations
+
+All of the following annotations have to be placed **above** the action definition and must be used within an `action` block like this:
+
+```ruby
+action "Return a random number" do
+  query_param :min, Optional(Float, 0.0), 'Minimum value'
+  query_param :max, Optional(Float, 1.0), 'Maximum value'
+
+  response 200, { value: Float }, 'Random value response'
+end
+def random_value
+    render json: { value: Random.rand(params[:min]..params[:max]) }
+end
+```
+
+**query_param**
+
+Parameter passed via query string, e.g. `http://localhost/my_action?parameter=value`. The first value is the parameter name (which must be a symbol), the second is the [type definition](./docs/type-definition.md). The last (optional) parameter to this call is the description.
+
+**path_param**
+
+Parameter passed as part of the actions route, e.g. `http://localhost/my_action/value` where the route definition is something like `get '/my_action/:parameter, to: 'my_controller#my_action'`. The first value is the parameter name (which must be a symbol), the second is the [type definition](./docs/type-definition.md). The last (optional) parameter to this call is the description.
+
+**body_param**
+
+Parameter as part of a JSON body in a POST/PUT/PATCH operation. The first value is the parameter name (which must be a symbol) as the JSON body must be a JSON object which has a key named like the parameter. The second parameter is the [type definition](./docs/type-definition.md). The last (optional) parameter to this call is the description.
+
+Example body:
+
+```json
+{
+  "min": 1.3,
+  "max": 3.7
+}
+```
+
+This body contains two parameters which have to be documented separately, e.g. like this:
+
+```ruby
+action do
+  body_param :min, Optional(Float, 0.0), 'Minimum value'
+  body_param :max, Optional(Float, 1.0), 'Maximum value'
+end
+# ...
+```
+
+**response**
+
+The response annotation defines the possible responses the action can generate, where the first parameter is the HTTP status code, the second is the [type definition](./docs/type-definition.md). The last (optional) parameter to this call is the description.
+
+**accept_all_params**
+
+To disable parameter validation, an action can be annotated with the `accept_all_params` annotation.

data/docs/getting-started.md

@@ -0,0 +1,32 @@
+# Getting started
+
+To get started with this gem, first include it into your Rails application by adding it to your `Gemfile` ...
+
+```ruby
+gem 'rails-param-validation'
+```
+
+... and running:
+```sh
+$ bundle install
+```
+
+Having included the gem, you can start using it right away, e.g. by annotating a controller class:
+
+```ruby
+class ExampleController
+  desc "Show the functionality of this gem"
+
+  action "Round float values" do
+    # Expect a parameter with the name "values" which contains an array of floats
+    query_param :values, ArrayType(Float), "Values to round"
+    # Document the response of http status 200, which is an array of integers
+    response 200, ArrayType(Integer), "Rounded values response"
+  end
+  def sample_action
+    render json: params[:values].map(&:round)
+  end
+end
+```
+
+The parameters for `sample_action` will be automatically checked against our definition on every request.

data/docs/index.md

@@ -0,0 +1,61 @@
+[![pipeline status](https://git.iftrue.de/okirmis/rails-param-validation/badges/master/pipeline.svg)](https://git.iftrue.de/okirmis/rails-param-validation/commits/master)
+
+This gem provides parameter validation for Rails using a declarative parameter definition and makes the automatic validation of complex parameters very easy. It also supports an export of the definition as an OpenAPI document.
+
+* [Why this gem?](./main-idea.md)
+* [Getting started](./getting-started.md)
+* [Annotations](./annotations.md)
+* [How to specify types](./type-definition.md)
+* [OpenAPI Export](./openapi.md)
+
+## Quick Example
+
+Let's take a look at a very simple example: a controller with a sample action, which gets a list of floats, rounds them to the nearest integer and returns it in a json encoded form.
+
+```ruby
+class ExampleController
+  desc "Show the functionality of this gem"
+
+  action "Round float values" do
+    # Expect a parameter with the name "values" which contains an array of floats
+    query_param :values, ArrayType(Float), "Values to round"
+    # Document the response of http status 200, which is an array of integers
+    response 200, :success, ArrayType(Integer), "Rounded values response"
+  end
+  def sample_action
+    render json: params[:values].map(&:round)
+  end
+
+  # We assume GET /round to be mapped to this action
+end
+```
+
+Sending a valid request, the parameters are validated and casted correctly and we get the response one would expect:
+
+```
+$ curl -H "Accept: application/json" "http://localhost:3000/round?values[]=1.5&values[]=2.0&values[]=-0.777"
+[2,2,-1]
+```
+
+When a request with invalid parameters is sent, we get an error response which also describes the error.
+
+```
+$ curl -H "Accept: application/json" "http://localhost:3000/round?values[]=1.5&values[]=2.0&values[]=XYZ"
+{"status":"fail","errors":[{"path":"values/2","message":"Expected a float"}]}
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rails-param-validation'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install rails-param-validator

data/docs/main-idea.md

@@ -0,0 +1,72 @@
+# What problem does this gem try to solve?
+
+Let's say we expect a JSON body that contains an array of objects which contain - besides others - an array of timestamps (date-times), e.g.:
+
+```json
+[
+  {
+    "type": "maxima",
+    "timestamps": [
+      "2020-03-01T16:49:50+01:00",
+      "2020-02-28T16:50:22+01:00"
+    ]
+  },
+  {
+    "type": "minima",
+    "timestamps": [
+      "2020-02-29T16:51:12+01:00"
+    ]
+  }
+]
+```
+
+Validating such a request requires a lot of code, involving a lot of `is_a?` statements etc. This is both - annoying from a developer perspective and error prone.
+
+# How does this gem solve this issue?
+
+This gem introduces a simple way to annotate controller actions with declarative parameter type annotations. For the example shown above, it would look like this:
+
+```ruby
+action do
+  body_param :data, ArrayType({ type: [:minima, :maxima], timestamps: ArrayType(DateTime) })
+end
+def sample_action
+  render json: { status: :ok }
+end
+```
+
+This will check the body parameter `:data` and will convert all string representing the timestamps automatically to `DateTime` objects. If the request does not match the definition, it will render either a JSON or HTML response which nicely describes what parameter does not match and why, e.g.:
+
+```sh
+$ curl -X POST -d \
+ '{"data": [{"type": "maxima","timestamps": ["2020-03-01T16:49:50+01:00","2020-02-28T16:50:22+01:00"]},{"type": "minima","timestamps": ["2020-02-29T16:51:12+01:00"]}]}' \
+ -H "Content-Type: application/json" \
+ -H "Accept: application/json" \
+ http://localhost:3000/sample_action
+```
+
+returns `{"status": "ok"}`. But if we send an invalid value, we get a different response:
+
+```sh
+$ curl -X POST -d \
+ '{"data": [{"type": "maxima","timestamps": ["abc","2020-02-28T16:50:22+01:00"]},{"type": "minima","timestamps": ["2020-02-29T16:51:12+01:00"]}]}' \
+ -H "Content-Type: application/json" \
+ -H "Accept: application/json" \
+ http://localhost:3000/home
+```
+the server will answer:
+```json
+{
+    "errors": [
+        {
+            "message": "Expected a date-time",
+            "path": "data/0/timestamps/0"
+        }
+    ],
+    "status": "fail"
+}
+```
+
+If we do not request `application/json`, we get an HTML response which looks like this:
+
+![alt text](./image/error-screenshot.png)

data/docs/openapi.md

@@ -0,0 +1,39 @@
+# OpenAPI Export
+
+When annotating the controller actions with parameter and response types, you get an [OpenAPI](https://www.openapis.org/) 3.0 export for free.
+
+## Export task
+
+When included in a Rails application, this gem automatically adds a rake task with the name `openapi:export`. It exports the OpenAPI definition in YAML format to the applications root directory (filename: `openapi.yaml`).
+
+```sh
+$ rake openapi:export
+Writing <your_apps_dir>/openapi.yaml... done.
+```
+
+## Configuration
+
+An OpenAPI document contains some meta data about the API. By default, the following default values are assumed:
+
+|  Property | Default | Description |
+|---|---|---|
+| `info.version` | `1.0` | API version |
+| `info.title`   | Application module name | Name or title of the API |
+| `info.description`   | Application module name + `" application"` | The API's brief description |
+| `info.url`   | `http://localhost:3000` | The base URL of the API, all specified paths are relative to that |
+
+These properties can be configured, e.g. in the `application.rb`, using:
+
+```ruby
+# ...
+module MyApp
+  class Application < Rails::Application
+    RailsParamValidation.openapi.title = "My App's API"
+    RailsParamValidation.openapi.description = 'This is an awesome API to interact with my App'
+    RailsParamValidation.openapi.version = '2.0'
+    RailsParamValidation.openapi.url = 'https://api.myapp.com'
+
+    # ...
+  end
+end 
+```

data/docs/type-definition.md

@@ -0,0 +1,178 @@
+# Type definition
+
+This gem provides declarative type checking. This part of the documentation will explain, how types are declared. Some types support inner types (e.g. arrays), so the definition can be nested.
+
+* [Constants](#type-constant)
+* [Alternatives](#type-alternatives)
+* [String](#type-string)
+* [Integer](#type-integer)
+* [Float](#type-float)
+* [Boolean](#type-boolean)
+* [UUID (v4)](#type-uuid)
+* [RegEx Pattern](#type-regex)
+* [Date & DateTime](#type-date-time)
+* [Optional Values](#type-optional)
+* [Array](#type-array)
+* [Object](#type-object)
+* [Hash](#type-hash)
+
+<a name="type-constant"></a>
+### Constants
+
+Accepts exactly the defined value, if its string representation is identical. This is especially useful in combination with alternatives.
+
+Example:
+```ruby
+query_param :accept_terms, true, "The user's consent to the terms of service"
+```
+
+This would accept the values `"true"` or `true` and reject all others.
+
+<a name="type-alternatives"></a>
+### Alternatives
+
+Accepts values that match at least one of the definitions.
+
+Example:
+```ruby
+query_param :gender, [:male, :female, :other], "User's gender"
+query_param :date_or_timestamp, [DateTime, Integer], "Modification date"
+```
+
+The first example will match any of the values `"male"`, `"female"`, `"other"`.
+
+The second example will match any iso formatted date time string or a timestamp (e.g. seconds since 1970-01-01).
+
+<a name="type-string"></a>
+### String
+
+Accept any string or type which can be converted to a string, namely: `String`, `Symbol`, `Numeric`, `Boolean`. The value will be automatically converted to a string.
+
+Example:
+```ruby
+query_param :name, String, "The user's name"
+```
+
+<a name="type-integer"></a>
+### Integer
+
+Accepts an integer or a string which represents an integer. If a string is passed, which cannot be parsed to an integer, the value is rejected. If the string can be converted to an integer, this is done in any case, if the value is accepted, an integer is returned.
+
+Example:
+```ruby
+query_param :year_of_birth, Integer, "The year, the user was born"
+```
+
+In this case, `params[:year_of_birth].is_a? Integer` returns `true`.
+
+
+<a name="type-float"></a>
+### Float
+
+Accepts an integer, float or a string which represents a float. If a string is passed, which cannot be parsed to a float, the value is rejected. If the string can be converted to a float, this is done in any case, if the value is accepted, a float is returned. Also integers are converted to floats.
+
+Example:
+```ruby
+query_param :radius, Float, "Search radius"
+```
+
+In this case, `params[:radius].is_a? Float` returns `true`.
+
+
+<a name="type-boolean"></a>
+### Boolean
+
+Accepts a float or a string, which represents a boolean (either `"true"` or `"false"`).
+
+Example:
+```ruby
+query_param :radius, Float, "Search radius"
+```
+
+In this case, `params[:radius].is_a? Float` returns `true`.
+
+
+<a name="type-uuid"></a>
+### Uuid
+
+Accepts a string or symbol in uuid v4 format. If the string does not match the correct format, it is rejected.
+
+Example:
+```ruby
+query_param :user_id, Uuid, "The user's ID"
+```
+
+
+<a name="type-regex"></a>
+### Regex
+
+Accepts a string or symbol, that matches a given `RegExp` pattern.
+
+Example:
+```ruby
+query_param :slug, /[a-z][a-z_0-9]+/, "Slug for the article as used in the URL"
+```
+
+<a name="type-date-time"></a>
+### Date & DateTime
+
+Accept strings that represent valid dates or datetimes, e.g. `"2020-02-28"` (for dates) or `"2020-02-28T12:13:14+01:00"`.
+
+Example:
+```ruby
+query_param :expiration_date, Date, "Date until the article will be available"
+```
+
+<a name="type-optional"></a>
+### Optional Value
+
+If a value is not passed, define a default value which is returned in this case. It can be used with any inner type. If the value is passed, it is validated. If it does not match, the value is rejected. If it is not specified at all, the default value is used.
+
+Example:
+```ruby
+query_param :public, Optional(Boolean, false), "Will the article be publicly available"
+query_param :expiration_date, Optional(Date, -> { Date.today + 14.days }), "Date until the article will be available"
+```
+
+In the first example, the constant is `false` is returned if no value is specified.
+
+In the second example, the `Proc` is evaluated whenever no data is passed for the parameter.
+
+<a name="type-array"></a>
+### Array
+
+Accepts a list of values. Every value of the entry has to match the inner type.
+
+Example:
+```ruby
+body_param :tags, ArrayType(String), "Tags to assign to the article"
+```
+
+This can be combined with any inner type.
+
+<a name="type-object"></a>
+### Object
+
+Accept an object with a defined list of keys. All properties have to match there definition.
+
+Example:
+```ruby
+body_param :article, { 
+              title: String,
+              body: String,
+              expiration_date: Optional(Date, Date.today + 14.days),
+              tags: ArrayType(String)
+            }, "Article to store"
+```
+
+<a name="type-hash"></a>
+### Hash
+
+Accept an object with arbitrary keys. The values and the keys can be validated against a type definition.
+
+Example:
+```ruby
+body_param :settings, HashType(DateTime, /key_[a-z]/), "User settings"
+```
+
+In this case, all keys have to start with `key_` and the rest may only consist of lower case letters. The values have to be date times.

data/lib/rails-param-validation/errors/missing_parameter_annotation.rb

@@ -0,0 +1,9 @@
+module RailsParamValidation
+
+  class MissingParameterAnnotation < StandardError
+    def initialize
+      super "Missing parameter annotation for controller action"
+    end
+  end
+
+end

data/lib/rails-param-validation/errors/no_matching_factory.rb

@@ -0,0 +1,9 @@
+module RailsParamValidation
+
+  class NoMatchingFactory < StandardError
+    def initialize(schema)
+      super "No matching factory found for schema: #{schema.inspect}"
+    end
+  end
+
+end

data/lib/rails-param-validation/errors/param_validation_failed_error.rb

@@ -0,0 +1,12 @@
+module RailsParamValidation
+
+  class ParamValidationFailedError < StandardError
+    attr_reader :result
+
+    def initialize(result)
+      @result = result
+      super "Parameter validation has failed: #{result.error_messages.join ", "}"
+    end
+  end
+
+end

data/lib/rails-param-validation/errors/type_not_found.rb

@@ -0,0 +1,9 @@
+module RailsParamValidation
+
+  class TypeNotFound < StandardError
+    def initialize(type)
+      super("The following type was not found: #{type}")
+    end
+  end
+
+end