sinja 1.2.1 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2baae47c1aa32d45265b3726e8a57163bf1d381e
-  data.tar.gz: 2e3de4a123865207d3a9bc6090563fa979a8ee52
+  metadata.gz: adc1346572a9c1a9ae1d2b85c70931cd329cdd1e
+  data.tar.gz: 73db963c1a496a98de718d1ea17ebda739d80ad9
 SHA512:
-  metadata.gz: 6fcfb53cdc190885a45594927e6fdb335c2fe44152884fe7051d3420f6431a7d7762215c924aea8526fd9486deb664a58486b3858d2b17f77e072f6d9b131f63
-  data.tar.gz: 952f451d6e3f18c992015e14d82fde782e866cdd078b06bbff30a00944b1c4a623a49c673fc971630f51ad943be7aebe59c3f50e900dd7f002ad7432720f4afc
+  metadata.gz: 55dc7ba3bc974625bb2cf65b943ccf8cf57541226f39eb0d66c7e56320c507cf3f8d76d0fddba5605698677f459958ede489477ebc9baed97d82a50c6a1e76f2
+  data.tar.gz: f75638978ade62140b1306644e4a81a62b18d1a8ce09b388ffa183c6c4a5859d531ce108b71299e5b82e39b3759e6d3c0b381799dc12be0f845a63784ec2280a

data/README.md

@@ -10,19 +10,23 @@
 [![Gem Version](https://badge.fury.io/rb/sinja.svg)](https://badge.fury.io/rb/sinja)
 [![Dependency Status](https://gemnasium.com/badges/github.com/mwpastore/sinja.svg)](https://gemnasium.com/github.com/mwpastore/sinja)
 [![Build Status](https://travis-ci.org/mwpastore/sinja.svg?branch=master)](https://travis-ci.org/mwpastore/sinja)
-
+[![{json:api} version](https://img.shields.io/badge/%7Bjson%3Aapi%7D%20version-1.0-lightgrey.svg)][7]
 [![Chat in #sinja-rb on Gitter](https://badges.gitter.im/sinja-rb/Lobby.svg)](https://gitter.im/sinja-rb/Lobby)
-[![Chat in #-ember-data on Slack](https://ember-community-slackin.herokuapp.com/badge.svg)](https://ember-community-slackin.herokuapp.com/?channel=-ember-data)
 
 Sinja is a [Sinatra][1] [extension][10] for quickly building [RESTful][11],
-[{json:api}][2]-[compliant][7] web services, leveraging the excellent
-[JSONAPI::Serializers][3] gem and [Sinatra::Namespace][21] extension. It
-enhances Sinatra's DSL to enable resource-, relationship-, and role-centric
-definition of applications, and it configures Sinatra with the proper settings,
-MIME-types, filters, conditions, and error-handling to implement {json:api}.
-Sinja aims to be lightweight (to the extent that Sinatra is), ORM-agnostic (to
-the extent that JSONAPI::Serializers is), and opinionated (to the extent that
-the {json:api} specification is).
+[{json:api}][2]-compliant web services, leveraging the excellent
+[JSONAPI::Serializers][3] gem for payload serialization. It enhances Sinatra's
+DSL to enable resource-, relationship-, and role-centric API development, and
+it configures Sinatra with the proper settings, MIME-types, filters,
+conditions, and error-handling.
+
+There are [many][31] parsing (deserializing) and rendering (serializing) and
+so-called "JSON API" libraries available for Ruby, but relatively few that
+attempt to correctly implement the entire {json:api} specification, including
+routing, request header and query parameter checking, and relationship
+side-loading. Sinja lets you focus on the business logic of your applications
+without worrying about the specification, and without pulling in a heavy
+framework like [Rails][16]. It's lightweight and ORM-agnostic!
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -30,14 +34,7 @@ the {json:api} specification is).
 
 - [Synopsis](#synopsis)
 - [Installation](#installation)
-- [Features & Design](#features--design)
-  - [Ol' Blue Eyes is Back](#ol-blue-eyes-is-back)
-  - [Public APIs](#public-apis)
-    - [Commonly Used](#commonly-used)
-    - [Less-Commonly Used](#less-commonly-used)
-  - [Performance](#performance)
-  - [Extensions](#extensions)
-  - [Comparison with JSONAPI::Resources](#comparison-with-jsonapiresources)
+- [Ol' Blue Eyes is Back](#ol-blue-eyes-is-back)
 - [Basic Usage](#basic-usage)
   - [Configuration](#configuration)
     - [Sinatra](#sinatra)
@@ -45,24 +42,8 @@ the {json:api} specification is).
   - [Resource Locators](#resource-locators)
   - [Action Helpers](#action-helpers)
     - [`resource`](#resource)
-      - [`index {..}` => Array](#index---array)
-      - [`show {|id| ..}` => Object](#show-id---object)
-      - [`show {..}` => Object](#show---object)
-      - [`show_many {|ids| ..}` => Array](#show_many-ids---array)
-      - [`create {|attr, id| ..}` => id, Object?](#create-attr-id---id-object)
-      - [`create {|attr| ..}` => id, Object](#create-attr---id-object)
-      - [`update {|attr| ..}` => Object?](#update-attr---object)
-      - [`destroy {..}`](#destroy-)
     - [`has_one`](#has_one)
-      - [`pluck {..}` => Object](#pluck---object)
-      - [`prune {..}` => TrueClass?](#prune---trueclass)
-      - [`graft {|rio| ..}` => TrueClass?](#graft-rio---trueclass)
     - [`has_many`](#has_many)
-      - [`fetch {..}` => Array](#fetch---array)
-      - [`clear {..}` => TrueClass?](#clear---trueclass)
-      - [`replace {|rios| ..}` => TrueClass?](#replace-rios---trueclass)
-      - [`merge {|rios| ..}` => TrueClass?](#merge-rios---trueclass)
-      - [`subtract {|rios| ..}` => TrueClass?](#subtract-rios---trueclass)
 - [Advanced Usage](#advanced-usage)
   - [Action Helper Hooks & Utilities](#action-helper-hooks--utilities)
   - [Authorization](#authorization)
@@ -82,15 +63,19 @@ the {json:api} specification is).
   - [Side-Unloading Related Resources](#side-unloading-related-resources)
   - [Side-Loading Relationships](#side-loading-relationships)
     - [Avoiding Null Foreign Keys](#avoiding-null-foreign-keys)
-      - [Many-to-One](#many-to-one)
-      - [One-to-Many](#one-to-many)
-      - [Many-to-Many](#many-to-many)
   - [Coalesced Find Requests](#coalesced-find-requests)
   - [Patchless Clients](#patchless-clients)
+- [Extensions](#extensions)
+  - [Sequel](#sequel)
 - [Application Concerns](#application-concerns)
+  - [Performance](#performance)
+  - [Public APIs](#public-apis)
+    - [Commonly Used](#commonly-used)
+    - [Less-Commonly Used](#less-commonly-used)
   - [Sinja or Sinatra::JSONAPI](#sinja-or-sinatrajsonapi)
   - [Code Organization](#code-organization)
   - [Testing](#testing)
+- [Comparison with JSONAPI::Resources](#comparison-with-jsonapiresources)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -100,7 +85,6 @@ the {json:api} specification is).
 ## Synopsis
 
 ```ruby
-require 'sinatra'
 require 'sinatra/jsonapi'
 
 resource :posts do
@@ -171,36 +155,12 @@ Or install it yourself as:
 $ gem install sinja
 ```
 
-## Features & Design
-
-* ORM-agnostic
-* Simple role-based authorization
-* To-one and to-many relationships and related resources
-* Side-loaded relationships on resource creation and update
-* Error-handling
-  * Conflicts (constraint violations)
-  * Missing records
-  * Validation failures
-* Filtering, sorting, and paging collections
-* Plus all the features of [JSONAPI::Serializers][3]!
-
-Its main competitors in the Ruby space are [ActiveModelSerializers][12] (AMS)
-with the JsonApi adapter, [JSONAPI::Resources][8] (JR), and
-[jsonapi-utils][26], all of which are designed to work with [Rails][16] and
-[ActiveRecord][17]/[ActiveModel][18] (although they may work with [Sequel][13]
-via [sequel-rails][14] and Sequel's [`:active_model` plugin][15]). Otherwise,
-you might use something like Sinatra, [Roda][20], or [Grape][19] with a
-(de)serialization library, your own routes, and a ton of boilerplate. The goal
-of this extension is to provide most or all of the boilerplate for a Sintara
-application and automate the drawing of routes based on the resource
-definitions.
-
-### Ol' Blue Eyes is Back
+## Ol' Blue Eyes is Back
 
 The "power" so to speak of implementing this functionality as a Sinatra
 extension is that all of Sinatra's usual features are available within your
-resource definitions. The action helpers blocks get compiled into Sinatra
-helpers, and the `resource`, `has_one`, and `has_many` keywords build
+resource definitions. Action helper blocks get compiled into Sinatra helpers,
+and the `resource`, `has_one`, and `has_many` keywords build
 [Sinatra::Namespace][21] blocks. You can manage caching directives, set
 headers, and even `halt` (or `not_found`, although such cases are usually
 handled transparently by returning `nil` values or empty collections from
@@ -295,107 +255,11 @@ class App < Sinatra::Base
 end
 ```
 
-### Public APIs
-
-Sinja makes a few APIs public to help you work around edge cases in your
-application.
-
-#### Commonly Used
-
-**can?**
-: Takes the symbol of an action helper and returns true if the current user has
-  access to call that action helper for the current resource using the `role`
-  helper and role definitions detailed under "Authorization" below.
-
-**role?**
-: Takes a list of role(s) and returns true if it has members in common with the
-  current user's role(s).
-
-**sideloaded?**
-: Returns true if the request was invoked from another action helper.
-
-#### Less-Commonly Used
-
-These are helpful if you want to add some custom routes to your Sinja
-application.
-
-**data**
-: Returns the `data` key of the deserialized request payload (with symbolized
-  names).
-
-**dedasherize**
-: Takes a string or symbol and returns the string or symbol with any and all
-  dashes transliterated to underscores, and camelCase converted to snake_case.
-
-**dedasherize_names**
-: Takes a hash and returns the hash with its keys dedasherized (deeply).
-
-**serialize_model**
-: Takes a model (and optional hash of JSONAPI::Serializers options) and returns
-  a serialized model.
-
-**serialize_model?**
-: Takes a model (and optional hash of JSONAPI::Serializers options) and returns
-  a serialized model if non-`nil`, or the root metadata if present, or a HTTP
-  status 204.
-
-**serialize_models**
-: Takes an array of models (and optional hash of JSONAPI::Serializers options)
-  and returns a serialized collection.
-
-**serialize_models?**
-: Takes an array of models (and optional hash of JSONAPI::Serializers options)
-  and returns a serialized collection if non-empty, or the root metadata if
-  present, or a HTTP status 204.
-
-### Performance
-
-Although there is some heavy metaprogramming happening at boot time, the end
-result is simply a collection of Sinatra namespaces, routes, filters,
-conditions, helpers, etc., and Sinja applications should perform as if you had
-written them verbosely. The main caveat is that there are quite a few block
-closures, which don't perform as well as normal methods in Ruby. Feedback
-welcome.
-
-### Extensions
-
-Sinja extensions provide additional helpers, DSL, and configuration, packaging
-ORM-specific boilerplate as separate gems. At the moment, the only available
-extension is for [Sequel][30], but community contributions are welcome!
-
-### Comparison with JSONAPI::Resources
-
-| Feature         | JR                               | Sinja                                             |
-| :-------------- | :------------------------------- | :------------------------------------------------ |
-| Serializer      | Built-in                         | [JSONAPI::Serializers][3]                         |
-| Framework       | Rails                            | Sinatra, but easy to mount within others          |
-| Routing         | ActionDispatch::Routing          | Mustermann                                        |
-| Caching         | ActiveSupport::Cache             | BYO                                               |
-| ORM             | ActiveRecord/ActiveModel         | BYO                                               |
-| Authorization   | [Pundit][9]                      | Role-based                                        |
-| Immutability    | `immutable` method               | Omit mutator action helpers (e.g. `update`)       |
-| Fetchability    | `fetchable_fields` method        | Omit attributes in Serializer                     |
-| Creatability    | `creatable_fields` method        | Handle in `create` action helper or Model\*       |
-| Updatability    | `updatable_fields` method        | Handle in `update` action helper or Model\*       |
-| Sortability     | `sortable_fields` method         | `sort` helper and `:sort_by` option               |
-| Default sorting | `default_sort` method            | Set default for `params[:sort]`                   |
-| Context         | `context` method                 | Rack middleware (e.g. `env['context']`)           |
-| Attributes      | Define in Model and Resource     | Define in Model\* and Serializer                  |
-| Formatting      | `:format` attribute keyword      | Define attribute as a method in Serialier         |
-| Relationships   | Define in Model and Resource     | Define in Model, Resource, and Serializer         |
-| Filters         | `filter(s)` keywords             | `filter` helper and `:filter_by` option           |
-| Default filters | `:default` filter keyword        | Set default for `params[:filter]`                 |
-| Pagination      | JSONAPI::Paginator               | `page` helper and `page_using` configurable       |
-| Meta            | `meta` method                    | Serializer `:meta` option               |
-| Primary keys    | `resource_key_type` configurable | Serializer `id` method               |
-
-\* - Depending on your ORM.
-
 ## Basic Usage
 
 You'll need a database schema and models (using the engine and ORM of your
 choice) and [serializers][3] to get started. Create a new Sinatra application
-(classic or modular) to hold all your {json:api} endpoints and (if modular)
+(classic or modular) to hold all your {json:api} controllers and (if modular)
 register this extension. Instead of defining routes with `get`, `post`, etc. as
 you normally would, define `resource` blocks with action helpers and `has_one`
 and `has_many` relationship blocks (with their own action helpers). Sinja will
@@ -417,7 +281,8 @@ these settings.
 * Registers [Sinatra::Namespace][21] and [Mustermann][25]
 * Disables [Rack::Protection][6] (can be reenabled with `enable :protection` or
   by manually `use`-ing the Rack::Protection middleware)
-* Disables static file routes (can be reenabled with `enable :static`)
+* Disables static file routes (can be reenabled with `enable :static`; be sure
+  to reenable Rack::Protection::PathTraversal as well)
 * Disables "classy" error pages (in favor of "classy" {json:api} error documents)
 * Adds an `:api_json` MIME-type (`application/vnd.api+json`)
 * Enforces strict checking of the `Accept` and `Content-Type` request headers
@@ -440,12 +305,12 @@ their defaults shown):
 configure_jsonapi do |c|
   #c.conflict_exceptions = [] # see "Conflicts" below
 
+  #c.not_found_exceptions = [] # see "Missing Records" below
+
   # see "Validations" below
   #c.validation_exceptions = []
   #c.validation_formatter = ->{ [] }
 
-  #c.not_found_exceptions = [] # see "Missing Records" below
-
   # see "Authorization" below
   #c.default_roles = {}
   #c.default_has_one_roles = {}
@@ -481,8 +346,9 @@ Much of Sinja's advanced functionality (e.g. updating and destroying resources,
 relationship routes) is dependent upon its ability to locate the corresponding
 resource for a request. To enable these features, define an ordinary helper
 method named `find` in your resource definition that takes a single ID argument
-and returns the corresponding object. Once defined, a `resource` object will
-be made available in any action helpers that operate on a single resource.
+and returns the corresponding object. Once defined, a `resource` object will be
+made available in any action helpers that operate on a single (parent)
+resource.
 
 ```ruby
 resource :posts do
@@ -574,13 +440,6 @@ any given resource block.)
 Take an array of IDs and return an equally-lengthed array of objects to
 serialize on the response. See "Coalesced Find Requests" below.
 
-##### `create {|attr, id| ..}` => id, Object?
-
-With client-generated IDs: Take a hash of (dedasherized) attributes and a
-client-generated ID, create a new resource, and return the ID and optionally
-the created resource. (Note that only one or the other `create` action helpers
-is allowed in any given resource block.)
-
 ##### `create {|attr| ..}` => id, Object
 
 Without client-generated IDs: Take a hash of (dedasherized) attributes, create
@@ -588,6 +447,13 @@ a new resource, and return the server-generated ID and the created resource.
 (Note that only one or the other `create` action helpers is allowed in any
 given resource block.)
 
+##### `create {|attr, id| ..}` => id, Object?
+
+With client-generated IDs: Take a hash of (dedasherized) attributes and a
+client-generated ID, create a new resource, and return the ID and optionally
+the created resource. (Note that only one or the other `create` action helpers
+is allowed in any given resource block.)
+
 ##### `update {|attr| ..}` => Object?
 
 Take a hash of (dedasherized) attributes, update `resource`, and optionally
@@ -885,8 +751,8 @@ The {json:api} specification states that any unhandled query parameters should
 cause the request to abort with HTTP status 400. To enforce this requirement,
 Sinja maintains a global "whitelist" of acceptable query parameters as well as
 a per-route whitelist, and interrogates your application to see which features
-it supports; for example, a route may allow a `filter` query parameter, but you
-may not have defined a `filter` helper.
+it supports; for example, a route may generally allow a `filter` query
+parameter, but you may not have defined a `filter` helper.
 
 To let a custom query parameter through to the standard action helpers, add it
 to the `query_params` configurable with a `nil` value:
@@ -1235,7 +1101,6 @@ end
 The following matrix outlines which combinations of action helpers and
 `:sideload_on` options enable which behaviors:
 
-<small>
 <table>
 <thead>
 <tr>
@@ -1274,7 +1139,6 @@ The following matrix outlines which combinations of action helpers and
 </tr>
 </tbody>
 </table>
-</small>
 
 #### Avoiding Null Foreign Keys
 
@@ -1428,14 +1292,86 @@ class MyApp < Sinatra::Base
 end
 ```
 
+## Extensions
+
+Sinja extensions provide additional helpers, DSL, and ORM-specific boilerplate
+as separate gems. Community contributions welcome!
+
+### Sequel
+
+Please see [Sinja::Sequel][30] for more information.
+
 ## Application Concerns
 
+### Performance
+
+Although there is some heavy metaprogramming happening at boot time, the end
+result is simply a collection of Sinatra namespaces, routes, filters,
+conditions, helpers, etc., and Sinja applications should perform as if you had
+written them verbosely. The main caveat is that there are quite a few block
+closures, which don't perform as well as normal methods in Ruby. Feedback
+welcome.
+
+### Public APIs
+
+Sinja makes a few APIs public to help you work around edge cases in your
+application.
+
+#### Commonly Used
+
+**can?**
+: Takes the symbol of an action helper and returns true if the current user has
+  access to call that action helper for the current resource using the `role`
+  helper and role definitions detailed under "Authorization" below.
+
+**role?**
+: Takes a list of role(s) and returns true if it has members in common with the
+  current user's role(s).
+
+**sideloaded?**
+: Returns true if the request was invoked from another action helper.
+
+#### Less-Commonly Used
+
+These are helpful if you want to add some custom routes to your Sinja
+application.
+
+**data**
+: Returns the `data` key of the deserialized request payload (with symbolized
+  names).
+
+**dedasherize**
+: Takes a string or symbol and returns the string or symbol with any and all
+  dashes transliterated to underscores, and camelCase converted to snake_case.
+
+**dedasherize_names**
+: Takes a hash and returns the hash with its keys dedasherized (deeply).
+
+**serialize_model**
+: Takes a model (and optional hash of JSONAPI::Serializers options) and returns
+  a serialized model.
+
+**serialize_model?**
+: Takes a model (and optional hash of JSONAPI::Serializers options) and returns
+  a serialized model if non-`nil`, or the root metadata if present, or a HTTP
+  status 204.
+
+**serialize_models**
+: Takes an array of models (and optional hash of JSONAPI::Serializers options)
+  and returns a serialized collection.
+
+**serialize_models?**
+: Takes an array of models (and optional hash of JSONAPI::Serializers options)
+  and returns a serialized collection if non-empty, or the root metadata if
+  present, or a HTTP status 204.
+
 ### Sinja or Sinatra::JSONAPI
 
 Everything is dual-namespaced under both Sinatra::JSONAPI and Sinja, and Sinja
 requires Sinatra::Base, so this:
 
 ```ruby
+require 'sinatra/base'
 require 'sinatra/jsonapi'
 
 class App < Sinatra::Base
@@ -1527,6 +1463,34 @@ applications will behave according to the {json:api} spec (as long as you
 follow the usage documented in this README) and focus on testing your business
 logic.
 
+## Comparison with JSONAPI::Resources
+
+| Feature         | JR                               | Sinja                                             |
+| :-------------- | :------------------------------- | :------------------------------------------------ |
+| Serializer      | Built-in                         | [JSONAPI::Serializers][3]                         |
+| Framework       | Rails                            | Sinatra, but easy to mount within others          |
+| Routing         | ActionDispatch::Routing          | Mustermann                                        |
+| Caching         | ActiveSupport::Cache             | BYO                                               |
+| ORM             | ActiveRecord/ActiveModel         | BYO                                               |
+| Authorization   | [Pundit][9]                      | Role-based                                        |
+| Immutability    | `immutable` method               | Omit mutator action helpers (e.g. `update`)       |
+| Fetchability    | `fetchable_fields` method        | Omit attributes in Serializer                     |
+| Creatability    | `creatable_fields` method        | Handle in `create` action helper or Model\*       |
+| Updatability    | `updatable_fields` method        | Handle in `update` action helper or Model\*       |
+| Sortability     | `sortable_fields` method         | `sort` helper and `:sort_by` option               |
+| Default sorting | `default_sort` method            | Set default for `params[:sort]`                   |
+| Context         | `context` method                 | Rack middleware (e.g. `env['context']`)           |
+| Attributes      | Define in Model and Resource     | Define in Model\* and Serializer                  |
+| Formatting      | `:format` attribute keyword      | Define attribute as a method in Serialier         |
+| Relationships   | Define in Model and Resource     | Define in Model, Resource, and Serializer         |
+| Filters         | `filter(s)` keywords             | `filter` helper and `:filter_by` option           |
+| Default filters | `:default` filter keyword        | Set default for `params[:filter]`                 |
+| Pagination      | JSONAPI::Paginator               | `page` helper and `page_using` configurable       |
+| Meta            | `meta` method                    | Serializer `:meta` option               |
+| Primary keys    | `resource_key_type` configurable | Serializer `id` method               |
+
+\* &ndash; Depending on your ORM.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
@@ -1555,7 +1519,7 @@ License](http://opensource.org/licenses/MIT).
 [4]: http://www.rubydoc.info/github/rack/rack/master/Rack/URLMap
 [5]: http://rodauth.jeremyevans.net
 [6]: https://github.com/sinatra/sinatra/tree/master/rack-protection
-[7]: http://jsonapi.org/format/
+[7]: http://jsonapi.org/format/1.0/
 [8]: https://github.com/cerebris/jsonapi-resources
 [9]: https://github.com/cerebris/jsonapi-resources#authorization
 [10]: http://www.sinatrarb.com/extensions-wild.html
@@ -1574,8 +1538,9 @@ License](http://opensource.org/licenses/MIT).
 [23]: http://jsonapi.org/recommendations/#patchless-clients
 [24]: http://www.rubydoc.info/github/rack/rack/Rack/MethodOverride
 [25]: http://www.sinatrarb.com/mustermann/
-[26]: https://github.com/tiagopog/jsonapi-utils
+[26]: https://jsonapi-suite.github.io/jsonapi_suite/
 [27]: https://github.com/coryodaniel/munson
 [28]: https://github.com/chingor13/json_api_client
 [29]: https://github.com/brynary/rack-test
 [30]: https://github.com/mwpastore/sinja-sequel
+[31]: http://jsonapi.org/implementations/#server-libraries-ruby

data/lib/sinatra/jsonapi.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-require 'sinatra'
+require 'sinatra' unless defined?(Sinatra)
 require 'sinja'
 
 module Sinatra

data/lib/sinja.rb

@@ -14,71 +14,11 @@ require 'sinja/version'
 
 module Sinja
   MIME_TYPE = 'application/vnd.api+json'
-  ERROR_CODES = [
-    BadRequestError,
-    ForbiddenError,
-    NotFoundError,
-    MethodNotAllowedError,
-    NotAcceptableError,
-    ConflictError,
-    UnsupportedTypeError
-  ].map! { |c| [c.new.http_status, c] }.to_h.tap do |h|
-    h[422] = UnprocessibleEntityError
-  end.freeze
-
-  def resource(resource_name, konst=nil, &block)
-    abort "Must supply proc constant or block for `resource'" \
-      unless block = (konst if konst.is_a?(Proc)) || block
-
-    resource_name = resource_name.to_s
-      .pluralize
-      .dasherize
-      .to_sym
-
-    # trigger default procs
-    config = _sinja.resource_config[resource_name]
-
-    namespace "/#{resource_name}" do
-      define_singleton_method(:_resource_config) { config }
-      define_singleton_method(:resource_config) { config[:resource] }
-
-      helpers do
-        define_method(:sanity_check!) do |*args|
-          super(resource_name, *args)
-        end
-      end
-
-      before %r{/(?<id>[^/]+)(?:/.+)?} do |id|
-        self.resource =
-          if env.key?('sinja.resource')
-            env['sinja.resource']
-          elsif respond_to?(:find)
-            find(id)
-          end
-
-        raise NotFoundError, "Resource '#{id}' not found" unless resource
-      end
-
-      register Resource
-
-      instance_eval(&block)
-    end
-  end
-
-  alias_method :resources, :resource
-
-  def sinja
-    if block_given?
-      yield _sinja
-    else
-      _sinja
-    end
-  end
-
-  alias_method :configure_jsonapi, :sinja
-  def freeze_jsonapi
-    _sinja.freeze
-  end
+  ERROR_CODES = ObjectSpace.each_object(Class).to_a
+    .keep_if { |klass| klass < HttpError }
+    .map! { |c| [(c.const_get(:HTTP_STATUS) rescue nil), c] }
+    .delete_if { |a| a.first.nil? }
+    .to_h.freeze
 
   def self.registered(app)
     app.register Mustermann if Sinatra::VERSION[/^\d+/].to_i < 2
@@ -101,20 +41,23 @@ module Sinja
       end
     end
 
-    app.set :qcapture do |*index|
+    app.set :qcaptures do |*index|
       condition do
         @qcaptures ||= []
+
         index.to_h.all? do |key, subkeys|
-          Hash === params[key.to_s] && params[key.to_s].any? &&
-            [*subkeys].all? do |subkey|
-              # TODO: What if deleting one is successful, but not another?
-              # We'll need to restore the hash to its original state.
-              @qcaptures << params[key.to_s].delete(subkey.to_s) \
-                if params[key.to_s].key?(subkey.to_s)
-            end.tap do |ok|
-              # If us deleting key(s) causes the hash to be empty, delete it.
-              params.delete(key.to_s) if ok && params[key.to_s].empty?
-            end
+          key = key.to_s
+
+          Hash === params[key] && params[key].any? && [*subkeys].all? do |subkey|
+            subkey = subkey.to_s
+
+            # TODO: What if deleting one is successful, but not another?
+            # We'll need to restore the hash to its original state.
+            @qcaptures << params[key].delete(subkey) if params[key].key?(subkey)
+          end.tap do |ok|
+            # If us deleting key(s) causes the hash to become empty, delete it.
+            params.delete(key) if ok && params[key].empty?
+          end
         end
       end
     end
@@ -132,7 +75,7 @@ module Sinja
           # Ignore interal Sinatra query parameters (e.g. :captures) and any
           # "known" query parameter set to `nil' in the configurable.
           next if !env['rack.request.query_hash'].key?(key.to_s) ||
-            settings._sinja.query_params.fetch(key, :_).nil?
+            settings._sinja.query_params.fetch(key, :__NOT_FOUND__).nil?
 
           raise BadRequestError, "`#{key}' query parameter not allowed" \
             unless allow_params.include?(key)
@@ -148,13 +91,13 @@ module Sinja
 
         return true if env['sinja.normalized'] == params.object_id
 
-        settings._sinja.query_params.each do |key, value|
-          next if value.nil?
+        settings._sinja.query_params.each do |key, default_value|
+          next if default_value.nil?
 
           if respond_to?("normalize_#{key}_params")
-            params[key.to_s] = send("normalize_#{key}_params")
+            params[key.to_s] = send("normalize_#{key}_params", default_value)
           else
-            params[key.to_s] ||= value
+            params[key.to_s] ||= default_value
           end
         end
 
@@ -186,6 +129,8 @@ module Sinja
 
       if method_defined?(:bad_request?)
         # This screws up our error-handling logic in Sinatra 2.0, so monkeypatch it.
+        # https://github.com/sinatra/sinatra/issues/1211
+        # https://github.com/sinatra/sinatra/pull/1212
         def bad_request?
           false
         end
@@ -209,8 +154,8 @@ module Sinja
         end
       end
 
-      def normalize_filter_params
-        return {} unless params[:filter]&.any?
+      def normalize_filter_params(default_value)
+        return default_value unless params[:filter]&.any?
 
         raise BadRequestError, "Unsupported `filter' query parameter(s)" \
           unless respond_to?(:filter)
@@ -230,7 +175,7 @@ module Sinja
         raise BadRequestError, "Invalid `filter' query parameter(s)"
       end
 
-      def normalize_sort_params
+      def normalize_sort_params(_default_value)
         return {} unless params[:sort]&.any?
 
         raise BadRequestError, "Unsupported `sort' query parameter(s)" \
@@ -252,8 +197,8 @@ module Sinja
         raise BadRequestError, "Invalid `sort' query parameter(s)"
       end
 
-      def normalize_page_params
-        return {} unless params[:page]&.any?
+      def normalize_page_params(default_value)
+        return default_value unless params[:page]&.any?
 
         raise BadRequestError, "Unsupported `page' query parameter(s)" \
           unless respond_to?(:page)
@@ -267,25 +212,17 @@ module Sinja
         return if params[:page].empty?
 
         return params[:page] \
-          if params[:page].keys.to_set.subset?(settings._sinja.page_using.keys.to_set)
+          if (params[:page].keys - settings._sinja.page_using.keys).empty?
 
         raise BadRequestError, "Invalid `page' query parameter(s)"
       end
 
       def filter_sort_page?(action)
-        return enum_for(__callee__, action).to_h unless block_given?
+        return enum_for(__callee__, action) unless block_given?
 
-        if filter = filter_by?(action)
-          yield :filter, filter
-        end
-
-        if sort = sort_by?(action)
-          yield :sort, sort
-        end
-
-        if page = page_using?
-          yield :page, page
-        end
+        if filter = filter_by?(action) then yield :filter, filter end
+        if sort = sort_by?(action) then yield :sort, sort end
+        if page = page_using? then yield :page, page end
       end
 
       def filter_sort_page(collection, opts)
@@ -347,7 +284,7 @@ module Sinja
     end
 
     app.after do
-      body serialize_response_body if response.ok? || response.created?
+      body serialize_response_body if response.successful?
     end
 
     app.not_found do
@@ -376,6 +313,60 @@ module Sinja
     end
   end
 
+  def resource(resource_name, konst=nil, &block)
+    abort "Must supply proc constant or block for `resource'" \
+      unless block = (konst if konst.is_a?(Proc)) || block
+
+    resource_name = resource_name.to_s
+      .pluralize
+      .dasherize
+      .to_sym
+
+    # trigger default procs
+    config = _sinja.resource_config[resource_name]
+
+    namespace "/#{resource_name}" do
+      define_singleton_method(:_resource_config) { config }
+      define_singleton_method(:resource_config) { config[:resource] }
+
+      helpers do
+        define_method(:sanity_check!) do |*args|
+          super(resource_name, *args)
+        end
+      end
+
+      before %r{/(?<id>[^/]+)(?:/.+)?} do |id|
+        self.resource =
+          if env.key?('sinja.resource')
+            env['sinja.resource']
+          elsif respond_to?(:find)
+            find(id)
+          end
+
+        raise NotFoundError, "Resource '#{id}' not found" unless resource
+      end
+
+      register Resource
+
+      instance_eval(&block)
+    end
+  end
+
+  alias_method :resources, :resource
+
+  def sinja
+    if block_given?
+      yield _sinja
+    else
+      _sinja
+    end
+  end
+
+  alias_method :configure_jsonapi, :sinja
+  def freeze_jsonapi
+    _sinja.freeze
+  end
+
   def self.extended(base)
     def base.route(*, **opts)
       opts[:qparams] ||= []

data/lib/sinja/errors.rb

@@ -27,34 +27,50 @@ module Sinja
   end
 
   class BadRequestError < HttpError
-    def initialize(*args) super(400, *args) end
+    HTTP_STATUS = 400
+
+    def initialize(*args) super(HTTP_STATUS, *args) end
   end
 
   class ForbiddenError < HttpError
-    def initialize(*args) super(403, *args) end
+    HTTP_STATUS = 403
+
+    def initialize(*args) super(HTTP_STATUS, *args) end
   end
 
   class NotFoundError < HttpError
-    def initialize(*args) super(404, *args) end
+    HTTP_STATUS = 404
+
+    def initialize(*args) super(HTTP_STATUS, *args) end
   end
 
   class MethodNotAllowedError < HttpError
-    def initialize(*args) super(405, *args) end
+    HTTP_STATUS = 405
+
+    def initialize(*args) super(HTTP_STATUS, *args) end
   end
 
   class NotAcceptableError < HttpError
-    def initialize(*args) super(406, *args) end
+    HTTP_STATUS = 406
+
+    def initialize(*args) super(HTTP_STATUS, *args) end
   end
 
   class ConflictError < HttpError
-    def initialize(*args) super(409, *args) end
+    HTTP_STATUS = 409
+
+    def initialize(*args) super(HTTP_STATUS, *args) end
   end
 
   class UnsupportedTypeError < HttpError
-    def initialize(*args) super(415, *args) end
+    HTTP_STATUS = 415
+
+    def initialize(*args) super(HTTP_STATUS, *args) end
   end
 
   class UnprocessibleEntityError < HttpError
+    HTTP_STATUS = 422
+
     attr_reader :tuples
 
     def initialize(tuples=[])
@@ -63,7 +79,7 @@ module Sinja
       fail 'Tuples not properly formatted' \
         unless @tuples.any? && @tuples.all? { |t| Array === t && t.length == 2 }
 
-      super(422)
+      super(HTTP_STATUS)
     end
   end
 end

data/lib/sinja/relationship_routes/has_many.rb

@@ -26,7 +26,7 @@ module Sinja
         app.get '', :qparams=>%i[include fields filter sort page], :actions=>:fetch do
           fsp_opts = filter_sort_page?(:fetch)
           collection, opts = fetch
-          collection, pagination = filter_sort_page(collection, fsp_opts)
+          collection, pagination = filter_sort_page(collection, fsp_opts.to_h)
           serialize_models(collection, opts, pagination)
         end
 

data/lib/sinja/resource.rb

@@ -13,6 +13,14 @@ require 'sinja/resource_routes'
 
 module Sinja
   module Resource
+    def self.registered(app)
+      app.helpers Helpers::Relationships do
+        attr_accessor :resource
+      end
+
+      app.register ResourceRoutes
+    end
+
     def def_action_helper(context, action, allow_opts=[])
       abort "Action helper names can't overlap with Sinatra DSL" \
         if Sinatra::Base.respond_to?(action)
@@ -72,14 +80,6 @@ module Sinja
       end
     end
 
-    def self.registered(app)
-      app.helpers Helpers::Relationships do
-        attr_accessor :resource
-      end
-
-      app.register ResourceRoutes
-    end
-
     %i[has_one has_many].each do |rel_type|
       define_method(rel_type) do |rel, &block|
         rel = rel.to_s

data/lib/sinja/resource_routes.rb

@@ -9,11 +9,11 @@ module Sinja
       app.def_action_helper(app, :update, :roles)
       app.def_action_helper(app, :destroy, :roles)
 
-      app.head '', :qcapture=>{ :filter=>:id } do
+      app.head '', :qcaptures=>{ :filter=>:id } do
         allow :get=>:show
       end
 
-      app.get '', :qcapture=>{ :filter=>:id }, :qparams=>%i[include fields], :actions=>:show do
+      app.get '', :qcaptures=>{ :filter=>:id }, :qparams=>%i[include fields], :actions=>:show do
         ids = @qcaptures.first # TODO: Get this as a block parameter?
         ids = ids.split(',') if String === ids
         ids = [*ids].tap(&:uniq!)
@@ -45,7 +45,7 @@ module Sinja
       app.get '', :qparams=>%i[include fields filter sort page], :actions=>:index do
         fsp_opts = filter_sort_page?(:index)
         collection, opts = index
-        collection, pagination = filter_sort_page(collection, fsp_opts)
+        collection, pagination = filter_sort_page(collection, fsp_opts.to_h)
         serialize_models(collection, opts, pagination)
       end
 

data/lib/sinja/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Sinja
-  VERSION = '1.2.1'
+  VERSION = '1.2.2'
 end

data/sinja.gemspec

@@ -10,6 +10,22 @@ Gem::Specification.new do |spec|
   spec.email         = ['mike@oobak.org']
 
   spec.summary       = 'RESTful, {json:api}-compliant web services in Sinatra'
+  spec.description   = <<~EOF
+    Sinja is a Sinatra extension for quickly building RESTful,
+    {json:api}-compliant web services, leveraging the excellent
+    JSONAPI::Serializers gem for payload serialization. It enhances Sinatra's
+    DSL to enable resource-, relationship-, and role-centric API development,
+    and it configures Sinatra with the proper settings, MIME-types, filters,
+    conditions, and error-handling.
+
+    There are many parsing (deserializing) and rendering (serializing) and
+    so-called "JSON API" libraries available for Ruby, but relatively few that
+    attempt to correctly implement the entire {json:api} specification,
+    including routing, request header and query parameter checking, and
+    relationship side-loading. Sinja lets you focus on the business logic of
+    your applications without worrying about the specification, and without
+    pulling in a heavy framework like Rails. It's lightweight and ORM-agnostic!
+  EOF
   spec.homepage      = 'https://github.com/mwpastore/sinja'
   spec.license       = 'MIT'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sinja
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.2.2
 platform: ruby
 authors:
 - Mike Pastore
@@ -208,7 +208,21 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
-description: 
+description: |
+  Sinja is a Sinatra extension for quickly building RESTful,
+  {json:api}-compliant web services, leveraging the excellent
+  JSONAPI::Serializers gem for payload serialization. It enhances Sinatra's
+  DSL to enable resource-, relationship-, and role-centric API development,
+  and it configures Sinatra with the proper settings, MIME-types, filters,
+  conditions, and error-handling.
+
+  There are many parsing (deserializing) and rendering (serializing) and
+  so-called "JSON API" libraries available for Ruby, but relatively few that
+  attempt to correctly implement the entire {json:api} specification,
+  including routing, request header and query parameter checking, and
+  relationship side-loading. Sinja lets you focus on the business logic of
+  your applications without worrying about the specification, and without
+  pulling in a heavy framework like Rails. It's lightweight and ORM-agnostic!
 email:
 - mike@oobak.org
 executables: []