request_handler 1.1.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bdc41be4882152511b384885eb59192f5173abb7f08e9f2c32f06030c571821
-  data.tar.gz: 910f9f1a2a227c1536c3153857eca1906313a6594d6e66c13989fdb78ef6af39
+  metadata.gz: f859646a0aa398cdae621ee5fa65dfc141041f2d7459130e43c6dd187f33cd34
+  data.tar.gz: 58ac3fcdfdace2cef4810ff885cf9f43b98902c37a84aea56489359df14741ed
 SHA512:
-  metadata.gz: c0ee7d6b5160d2f8e4a5c33501aecc4cbd43c6c8d1cbb7dd54a6ecd3700ddedf7f600dffc3b6985775b3f7fae4d077a88774b3f6d3762c7a1f79e386162e190d
-  data.tar.gz: b912e9cde9288dee5e004c1ad71e9f0a9e985e7bc5ff4fe742b1284078ab7c35d882a757b3ae4235b3d5968fc12f29c1c3c6d37ee106960661134e3a36441042
+  metadata.gz: 246011e015199ccabf514606819ee30ff53784e658f756fb891c3dba75b8af20a962910c4251401a9b770f194c06a089c15f2f10e1eadd78061128bba8c49872
+  data.tar.gz: ab07fa30b9095bcc7dbc41cd5fe948e80fa84d55252fb9b02b6a8ea656324f4c597d7e469b6d70b976b66a08f013f66feb71fbe141208deb71bc82a491292502

data/.circleci/config.yml

@@ -0,0 +1,75 @@
+# Ruby CircleCI 2.0 configuration file
+#
+# Check https://circleci.com/docs/2.0/language-ruby/ for more details
+#
+
+common_steps: &common_steps
+  - checkout
+  - run: gem update --system
+  - restore_cache:
+      key: gem-cache-{{ .Branch }}-{{ checksum "request_handler.gemspec" }}
+  - run:
+      name: install dependencies
+      command: |
+        gem update bundler
+        bundle install --jobs=4 --retry=3 --path vendor/bundle
+  - save_cache:
+      key: gem-cache-{{ .Branch }}-{{ checksum "request_handler.gemspec" }}
+      paths:
+        - vendor/bundle
+
+  - run: ruby -v
+  - run: bundle exec danger
+  - run: 
+      name: run tests
+      command: |
+        mkdir /tmp/test-results
+        TEST_FILES="$(circleci tests glob "spec/**/*_spec.rb" | \
+          circleci tests split --split-by=timings)"
+
+        bundle exec rspec \
+          --format progress \
+          --format RspecJunitFormatter \
+          --out /tmp/test-results/rspec.xml \
+          --format progress \
+          $TEST_FILES
+  # collect reports
+  - store_test_results:
+      path: /tmp/test-results
+  - store_artifacts:
+      path: /tmp/test-results
+      destination: test-results
+
+version: 2
+jobs:
+  ruby-2.4:
+    docker:
+      - image: circleci/ruby:2.4
+    steps:
+      *common_steps
+  ruby-2.5:
+    docker:
+      - image: circleci/ruby:2.5
+    steps:
+      *common_steps
+  jruby-9.2:
+    docker:
+      - image: circleci/jruby:9.2
+    steps:
+      *common_steps
+  jruby-9.2-indy:
+    docker:
+      - image: circleci/jruby:9.2
+    environment:
+      JRUBY_OPTS: '-Xcompile.invokedynamic=true'
+    steps:
+      *common_steps
+
+workflows:
+  version: 2
+  build:
+    jobs:
+      - ruby-2.4
+      - ruby-2.5
+      - jruby-9.2
+      - jruby-9.2-indy

data/CHANGELOG.md

@@ -6,6 +6,41 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [2.1.1] - 2021-06-14
+### Fixed
+- Change error object's source attribute from `param` to `parameters` to align with JSONAPI specification
+
+## [2.1.0] - 2020-04-01
+### Added
+- Headers validation
+
+## [2.0.0] - 2019-11-19
+### Changed
+- BREAKING: Required configuration of validation engine
+- BREAKING: Dynamic resource keys in config DSL are not supported anymore and
+  have to be defined via the `resource` key
+
+### Added
+- Support for dry-* 1.x
+
+### Removed
+- BREAKING: Dry dependencies were removed and should manually be added
+- BREAKING: Support for config inheritance
+- BREAKING: Support for dry-* 0.x
+
+## [1.3.0] - 2019-05-21
+### Added
+- Serializable JSONAPI error objects out of validation failures
+- Configuration option to enable returning validation failures in errors method of exceptions
+
+### Changed
+- Format of error messages for external causes (bad requests)
+- Inheritance chain of error classes
+
+## [1.2.0] - 2019-04-15
+### Added
+- Apart from dry-validation, now definition or any other validation library can be used
+
 ## [1.1.0] - 2018-07-13
 ### Changed
 - loosen dry-gems restrictions, now allow all version > 0.11

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,69 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq

data/Gemfile

@@ -9,4 +9,7 @@ group :development, :test do
   gem 'danger'
   gem 'danger-commit_lint'
   gem 'danger-rubocop'
+  gem 'dry-types', '~> 1.0'
+  gem 'dry-validation', '~> 1.0'
+  gem 'rspec_junit_formatter'
 end

data/README.md

@@ -1,19 +1,13 @@
 # RequestHandler
 
 [![Gem Version](https://badge.fury.io/rb/request_handler.svg)](https://badge.fury.io/rb/request_handler)
-[![Build Status](https://travis-ci.org/runtastic/request_handler.svg?branch=master)](https://travis-ci.org/runtastic/request_handler)
+[![CircleCI](https://circleci.com/gh/andreaseger/receptacle.svg?style=svg)](https://circleci.com/gh/runtastic/request_handler)
 [![codecov](https://codecov.io/gh/runtastic/request_handler/branch/master/graph/badge.svg)](https://codecov.io/gh/runtastic/request_handler)
 
 This gem allows easy and dry handling of requests based on the dry-validation
 gem for validation and data coersion. It allows to handle headers, filters,
 include_options, sorting and of course to validate the body.
 
-## dry-gem dependency
-
-Version 1.1 removes the strict dependency to dry-types v0.11 & dry-validation v0.11 and allows usage of newer versions of dry-gems. This gem uses these gems but only a very small interface with them therefore this gem itself is usually not impacted by smaller breaking changes each minor version of the dry-gems might introduce.
-
-**Please check your applications compatibility with each dry-types version and pin versions as necessary**
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -30,12 +24,65 @@ Or install it yourself as:
 
     $ gem install request_handler
 
+## Configuration
+
+You have to chose a validation engine and configure it globally:
+```ruby
+RequestHandler.configure do |config|
+  config.validation_engine = RequestHandler::Validation::DryEngine
+end
+```
+
+If you want to use the included dry engine you also have to add the dry gems to
+your Gemfile:
+```ruby
+  gem 'dry-validation', '~> 1.0'
+  gem 'dry-types', '~> 1.0'
+```
+Note that only dry >= 1.0 is supported.
+
+The default logger and separator can be changed globally:
+
+```ruby
+RequestHandler.configure do |config|
+  config.logger = Logger.new(STDERR)
+  config.separator = '____'
+end
+```
+
+JSON:API-style error data can be included in validation errors raised by `RequestHandler`.
+
+```ruby
+RequestHandler.configure do |config|
+  config.raise_jsonapi_errors = true # default: false
+end
+```
+
+
+### Validation Engine
+You have to chose a validation engine and configure it globally (see
+configuration section above).
+All examples in this Readme assume you are using the `DryEngine` which relies on
+dry-validation. However you can also use the builtin `DefinitionEngine`, which
+uses [Definition](https://github.com/Goltergaul/definition) as validation
+library:
+
+```ruby
+RequestHandler.configure do |config|
+  require 'request_handler/validation/definition_engine'
+  config.validation_engine = RequestHandler::Validation::DefinitionEngine
+end
+```
+
+You can also implement your own engine to use any other library, by implementing
+the abstract class `RequestHandler::Validation::Engine`
+
 ## Usage
 
 To set up a handler, you need create a class which inherits from
 `RequestHandler::Base`, providing at least the options block and a `to_dto`
 method with the parts you want to use. To use it, create a new instance of the
-handler passing in the request, after that you can use the handler.dto method to
+handler passing in the request, after that you can use the handler.to_dto method to
 process and access the data. Here is a short example, check
 `spec/integration/request_handler_spec.rb` for a detailed one.
 
@@ -55,14 +102,13 @@ defines if the JsonApiDocumentParser or JsonParser is used.
 If nothing is defined, JsonApiDocumentParser will be used by default.
 
 ```ruby
-require "dry-validation"
 require "request_handler"
 class DemoHandler < RequestHandler::Base
   options do
     page do
       default_size 10
       max_size 20
-      comments do
+      resource :comments do
         default_size 20
         max_size 100
       end
@@ -78,11 +124,11 @@ class DemoHandler < RequestHandler::Base
 
     filter do
       schema(
-        Dry::Validation.Params do
-          configure do
-            option :foo
+        Class.new(Dry::Validation::Contract) do
+          option :foo
+          params do
+            required(:name).filled(:string)
           end
-          required(:name).filled(:str?)
         end
       )
       additional_url_filter %i(user_id id)
@@ -92,8 +138,8 @@ class DemoHandler < RequestHandler::Base
 
     query do
       schema(
-        Dry::Validation.Params do
-          optional(:name).filled(:str?)
+        Dry::Schema.Params do
+          optional(:name).filled(:string)
         end
       )
     end
@@ -101,11 +147,11 @@ class DemoHandler < RequestHandler::Base
     body do
       type :jsonapi
       schema(
-        Dry::Validation.JSON do
-          configure do
-            option :foo
+        Class.new(Dry::Validation::Contract) do
+          option :foo
+          json do
+            required(:id).filled(:string)
           end
-          required(:id).filled(:str?)
         end
       )
       options(->(_handler, _request) { { foo: "bar" } })
@@ -178,19 +224,19 @@ file related to the question
 class CreateQuestionHandler < RequestHandler::Base
   options do
     multipart do
-      question do
+      resource :question do
         required true
         type "json"
         schema(
-          Dry::Validation.JSON do
-            required(:id).filled(:str?)
-            required(:type).filled(:str?)
-            required(:content).filled(:str?)
+          Dry::Schema.JSON do
+            required(:id).filled(:string)
+            required(:type).filled(:string)
+            required(:content).filled(:string)
           end
         )
       end
 
-      file do
+      resource :file do
         # no validation necessary
       end
     end
@@ -203,7 +249,7 @@ class CreateQuestionHandler < RequestHandler::Base
 end
 ```
 
-Assuming that the request consists of a json file `question.json` containing  
+Assuming that the request consists of a json file `question.json` containing
 ``` json
 {
   "id": "1",
@@ -235,18 +281,44 @@ and an additional file `image.png`, the resulting `multipart_params` will be the
 
 Please note that each part's content has to be uploaded as a separate file currently.
 
-### Configuration
+### JSON:API errors
+
+Errors caused by bad requests respond to `:errors`.
+
+When the gem is configured to `raise_jsonapi_errors`, this method returns a list of hashes
+containing `code`, `status`, `detail`, (`links`) and `source` for each specific issue
+that contributed to the error. Otherwise it returns an empty array.
 
-The default logger and separator can be changed globally by using
-`RequestHandler.configure {}`.
+The exception message contains `<error code>: <source> <detail>` for every issue,
+with one issue per line.
 
+| `:code`                   | `:status` | What is it? |
+|:--------------------------|:----------|:------------|
+| INVALID_RESOURCE_SCHEMA   | 422       | Resource did not pass configured validation |
+| INVALID_QUERY_PARAMETER   | 400       | Query parameter violates syntax or did not pass configured validation |
+| MISSING_QUERY_PARAMETER   | 400       | Query parameter required in configuration is missing |
+| INVALID_JSON_API          | 400       | Request body violates JSON:API syntax |
+| INVALID_MULTIPART_REQUEST | 400       | Sidecar resource missing or invalid JSON |
+
+#### Example
 ```ruby
-RequestHandler.configure do
-  logger Logger.new(STDERR)
-  separator '____'
+rescue RequestHandler::SchemaValidationError => e
+  puts e.errors
 end
 ```
 
+```ruby
+[
+  {
+    status: '422',
+    code: 'INVALID_RESOURCE_SCHEMA',
+    title: 'Invalid resource',
+    detail: 'is missing',
+    source: { pointer: '/data/attributes/name' }
+  }
+]
+```
+
 ### Caveats
 
 It is currently expected that _url_ parameter are already parsed and included in
@@ -261,25 +333,149 @@ get "/users/:user_id/posts" do
 end
 ```
 
+## v1 to v2 migration guide
+Multiple breaking changes were introduced with request_handler 2.0. This section
+describes which steps have to be taken in order to migrate from 1.x to 2.0.
+
+### Configure validation engine
+By default the DryEngine was used in 1.0. You now have to explicitly configure
+a validation engine:
+
+```ruby
+RequestHandler.configure do |config|
+  config.validation_engine = RequestHandler::Validation::DryEngine
+end
+```
+
+### Add dry dependency if you use the DryEngine
+Since the DryEngine is not configured by default anymore, the dependency to the
+dry gems could be removed from request_handler. If you use the DryEngine
+simply add the dry-gems to your Gemfile:
+
+```ruby
+gem 'dry-validation', '~> 1.0'
+gem 'dry-types', '~> 1.0'
+```
+Note that only dry >= 1.0 is supported.
+
+### Define custom resources via the `resource` key
+In request_handler 1.x it was possible to define custom resource names like this:
+
+```ruby
+options  do
+  fieldsets do
+    allowed do
+      posts schema
+    end
+  end
+end
+```
+
+This was possible in multiple places (`page`, `multipart`, `fieldsets.allowed`).
+Starting with version 2.0 you will have to define those custom resources via the
+`resource` key:
+
+```ruby
+options do
+  fieldsets do
+    allowed do
+      resource :posts, schema
+    end
+  end
+end
+```
+
+### Use dry-* 1.x instead of dry-* 0.x if you use the DryEngine
+Some of the most common required changes are listed here:
+
+* Use `Dry::Schema.Params` instead of `Dry::Validation.Schema`
+* Use `Dry::Schema.JSON` instead of `Dry::Validation.JSON`
+* If you use some more complex validation rules with options like this:
+
+```
+Dry::Validation.Params do
+  configure do
+    option :query_id
+  end
+  required(:id).value(eql?: query_id)
+end
+
+options(->(_parser, request) { { query_id: request.params['id'] } })
+```
+
+please rewrite it using `Dry::Validation::Contract` like this:
+
+```
+Class.new(Dry::Validation::Contract) do
+  option :query_id
+  params do
+    required(:id).value(:string)
+  end
+  rule(:id) do
+    key.failure('invalid id') unless values[:id] == query_id
+  end
+end)
+options(->(_parser, request) { { query_id: request.params['id'] } })
+```
+
+A useful guide for upgrading to dry 1 types, validations and schemas can be
+found [here](https://www.morozov.is/2019/05/31/upgrading-dry-gems.html).
+
+Also please refer to the official docs of
+[dry-schema](https://dry-rb.org/gems/dry-schema) and
+[dry-validation](https://dry-rb.org/gems/dry-validation).
+
+### Remove config inheritance
+It was possible to (partially) overwrite configs defined in a request-handler
+super-class:
+```
+class Parent < RequestHandler::Base
+  options  do
+    page do
+      comments do
+        default_size 20
+      end
+    end
+  end
+end
+```
+
+```ruby
+class Child < Parent
+  options  do
+    page do
+      comments do
+        default_size 10
+      end
+    end
+  end
+end
+```
+
+Support for this has been fully removed. If you overwrite configs in subclasses
+please remove the inheritance and define the two request-handlers separately.
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`rake test` to run the tests. You can also run `bin/console` for an interactive
-prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. You can
+also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+Run `bundle exec rspec` to run the tests.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To
 release a new version, update the version number in `version.rb`, and then run
-`bundle exec rake release`, which will create a git tag for the version, push
-git commits and tags, and push the `.gem` file
-to [rubygems.org](https://rubygems.org).
+`bundle exec rake release`, which will create a git tag for the version, push git
+commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
-Bug reports and pull requests are welcome on GitHub at
-https://github.com/runtastic/request_handler. This project is intended to be a
-safe, welcoming space for collaboration, and contributors are expected to adhere
-to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/runtastic/request_handler.
+This project is intended to be a safe, welcoming space for collaboration, and
+contributors are expected to adhere to the [code of conduct][cc].
+
+Check out our [career page](https://www.runtastic.com/career/) if you'd like to work with us.
 
 ## License
+The gem is available as open source under [the terms of the MIT License][mit].
 
-The gem is available as open source under the terms of
-the [MIT License](http://opensource.org/licenses/MIT).
+[mit]: https://choosealicense.com/licenses/mit/
+[cc]: ../CODE_OF_CONDUCT.md