sinja 1.1.0.pre4 → 1.2.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a86013c139ad0c6cd3555443076a4c813c8cedc6
-  data.tar.gz: 7c3dc7d285fb817bb9e4c6003bc24c0cb8d2b1f2
+  metadata.gz: 7194e1502968ad1c77f29a86eba2142a02e9fab0
+  data.tar.gz: d60c872b2a8b8d5555f18eb2a3064fd748ab4ec8
 SHA512:
-  metadata.gz: 86a0909d1e859b4f2177de1d71c91b60fa5bc0160c8b1568f94acc100ce84c01157439633e89124eed2e09318a3b4ffb0aa6596fc7bae3a09ee88a4e9132ca43
-  data.tar.gz: 21f0f20bda31d9a6954437f66848eb47f7c13dd8e8250992bb259c9791f7cb3fa7b39f6ba8291101f7128bf8b7add9b8e87b32c768d95d3924a839fee90627c6
+  metadata.gz: a42b7e9f8c15e748145b731f9329c7bcce307fb4224ba1f33c2172faacb41fd75dcebe02374e9aa6101fef422f8d12bf09f1c32fdfb4b2a45239e97bd28643c1
+  data.tar.gz: ec35d6bd75b8b47b03ad9a6803407f03ca5c89593389962820de22c1a63de6c7ce7309b592264e8ac961ad552547658ff8723eeac22f8a0f1b8b628cd3c8a9da

data/Gemfile

@@ -1,5 +1,6 @@
 source 'https://rubygems.org'
 
 gemspec
-gem 'munson', '~> 0.3',
+gem 'sinja-sequel', :require=>false, :path=>'extensions/sequel'
+gem 'munson', '~> 0.3', :require=>false,
   :git=>'https://github.com/mwpastore/munson', :branch=>'develop'

data/README.md

@@ -1,8 +1,18 @@
 # Sinja (Sinatra::JSONAPI)
 
+<!--
+  Title: Sinja
+  Description: RESTful, {json:api}-compliant web services in Sinatra
+  Author: Mike Pastore
+  Keywords: JSON, API, JSONAPI, JSON:API, {json:api}, Ruby, Sinatra, JSONAPI::Serializers, jsonapi-serializers
+  -->
+
 [![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)
-[![Chat](https://badges.gitter.im/sinja-rb/Lobby.svg)](https://gitter.im/sinja-rb/Lobby)
+
+[![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
@@ -26,6 +36,7 @@ the {json:api} specification is).
     - [Commonly Used](#commonly-used)
     - [Less-Commonly Used](#less-commonly-used)
   - [Performance](#performance)
+  - [Extensions](#extensions)
   - [Comparison with JSONAPI::Resources](#comparison-with-jsonapiresources)
 - [Basic Usage](#basic-usage)
   - [Configuration](#configuration)
@@ -48,6 +59,7 @@ the {json:api} specification is).
     - [`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)
@@ -346,6 +358,13 @@ 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](/extensions/sequel), but community contributions are
+welcome!
+
 ### Comparison with JSONAPI::Resources
 
 | Feature         | JR                               | Sinja                                             |
@@ -436,7 +455,7 @@ configure_jsonapi do |c|
 
   # You can't set this directly; see "Query Parameters" below
   #c.query_params = {
-  #  :include=>[], :fields=>{}, :filter=>{}, :page=>{}, :sort=>{}
+  #  :include=>[], :fields=>{}, :filter=>{}, :page=>{}, :sort=>[]
   #}
 
   #c.page_using = {} # see "Paging" below
@@ -630,6 +649,18 @@ has_many :bars do
 end
 ```
 
+##### `replace {|rios| ..}` => TrueClass?
+
+Take an array of [resource identifier object][22] hashes and update
+(add/remove) the relationships on `resource`. To serialize the updated linkage
+on the response, refresh or reload `resource` (if necessary) and return a
+truthy value.
+
+In principle, `replace` should delete all members of the existing collection
+and insert all members of a new collection, but in practice&mdash;for
+performance reasons, especially with large collections and/or complex
+constraints&mdash;it may be prudent to simply apply a delta.
+
 ##### `merge {|rios| ..}` => TrueClass?
 
 Take an array of [resource identifier object][22] hashes and update (add unless
@@ -735,6 +766,7 @@ configure_jsonapi do |c|
   c.default_has_many_roles = {
     fetch: :user,
     clear: :admin,
+    replace: :admin,
     merge: :admin,
     subtract: :admin
   }
@@ -835,8 +867,8 @@ resource :foos do
     end
   end
 
-  create(roles: :user) { |attr| .. }
-  update(roles: :owner) { |attr| .. }
+  create(roles: :user) {|attr| .. }
+  update(roles: :owner) {|attr| .. }
 end
 ```
 
@@ -934,7 +966,7 @@ For example, to implement sorting using Sequel:
 ```ruby
 helpers do
   def sort(collection, fields={})
-    collection.order(*fields.map { |k, v| Sequel.send(v, k) })
+    collection.order(*fields.map {|k, v| Sequel.send(v, k) })
   end
 end
 
@@ -968,7 +1000,7 @@ Allow clients to page the collections returned by the `index` and `fetch`
 action helpers by defining a `page` helper in the appropriate scope that takes
 a collection and a hash of `page` query parameters (with its top-level keys
 dedasherized and symbolized) and returns the paged collection along with a
-special nested hash used to build the paging links.
+special nested hash used as root metadata and to build the paging links.
 
 The top-level keys of the hash returned by this method must be members of the
 set: {`:self`, `:first`, `:prev`, `:next`, `:last`}. The values of the hash are
@@ -1000,8 +1032,8 @@ Could be used to build the following top-level links in the response document:
 You must also set the `page_using` configurable to a hash of symbols
 representing the paging fields used in your application (for example, `:number`
 and `:size` for the above example) along with their default values (or `nil`).
-Please see the [Sequel helpers](/lib/sinja/helpers/sequel.rb) in this
-repository for a detailed, working example.
+Please see the [Sequel extension](/extensions/sequel) in this repository for a
+detailed, working example.
 
 The easiest way to page a collection by default is to tweak the post-processed
 query parameter(s) in a `before_<action>` hook:
@@ -1036,10 +1068,6 @@ helpers do
 end
 ```
 
-(Note that in addition to finalizing Sequel datasets with `#all`, you should
-also enable the `:tactical_eager_loading` plugin for the best compatibility
-with JSONAPI::Serializers.)
-
 ### Conflicts
 
 If your database driver raises exceptions on constraint violations, you should
@@ -1174,12 +1202,11 @@ request will fail and any database changes will be rolled back (given a
 `transaction` helper). Note that the user's role must grant them access to call
 either `graft` or `create`.
 
-`create` and `update` are the only two action helpers that trigger sideloading;
-`graft`, `merge`, and `clear` are the only action helpers invoked by
+`create` and `update` are the resource action helpers that trigger sideloading;
+`graft` and `prune` are the to-one action helpers invoked by sideloading; and
+`replace`, `merge`, and `clear` are the to-many action helpers invoked by
 sideloading. You must indicate which combinations are valid using the
-`:sideload_on` action helper option. (Note that if you want to sideload `merge`
-on `update`, you must define a `clear` action helper and allow it to sideload
-on `update` as well.) For example:
+`:sideload_on` action helper option. For example:
 
 ```ruby
 resource :photos do
@@ -1187,24 +1214,64 @@ resource :photos do
     def find(id) ..; end
   end
 
-  create { |attr| .. }
-  update { |attr| .. }
+  create {|attr| .. }
 
   has_one :photographer do
-    # Allow `create' to sideload the Photographer
-    graft(sideload_on: :create) { |rio| .. }
+    # Allow `create' to sideload Photographer
+    graft(sideload_on: :create) {|rio| .. }
   end
 
   has_many :tags do
-    # Allow `create' and `update' to sideload Tags
-    merge(sideload_on: [:create, :update]) { |rios| .. }
-
-    # Allow `update' to clear Tags before sideloading them
-    clear(sideload_on: :update) { .. }
+    # Allow `create' to sideload Tags
+    merge(sideload_on: :create) {|rios| .. }
   end
 end
 ```
 
+The following matrix outlines which combinations of action helpers and
+`:sideload_on` options enable which behaviors:
+
+<small>
+<table>
+<thead>
+<tr>
+  <th rowspan="2">Desired behavior</th>
+  <th colspan="2">For to-one relationship(s)</th>
+  <th colspan="2">For to-many relationship(s)</th>
+</tr>
+<tr>
+  <th>Define Action Helper</th>
+  <th>With <code>:sideload_on</code></th>
+  <th>Define Action Helper</th>
+  <th>With <code>:sideload_on</code></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+  <td>Set relationship(s) when creating resource</td>
+  <td><code>graft</code></td>
+  <td><code>:create</code></td>
+  <td><code>merge</code></td>
+  <td><code>:create</code></td>
+</tr>
+<tr>
+  <td>Set relationship(s) when updating resource</td>
+  <td><code>graft</code></td>
+  <td><code>:update</code></td>
+  <td><code>replace</code></td>
+  <td><code>:update</code></td>
+</tr>
+<tr>
+  <td>Delete relationship(s) when updating resource</td>
+  <td><code>prune</code></td>
+  <td><code>:update</code></td>
+  <td><code>clear</code></td>
+  <td><code>:update</code></td>
+</tr>
+</tbody>
+</table>
+</small>
+
 #### Avoiding Null Foreign Keys
 
 Now, let's say our DBA is forward-thinking and wants to make the foreign key
@@ -1271,9 +1338,9 @@ end
 ```
 
 Note that the `validate!` hook is _only_ invoked from within transactions
-involving the `create` and `update` action helpers (and any dependent `graft`
-and `merge` action helpers), so this deferred validation pattern is only
-appropriate in those cases. You must use immedate validation in all other
+involving the `create` and `update` action helpers (and any action helpers
+invoked via the sideloading mechanism), so this deferred validation pattern is
+only appropriate in those cases. You must use immedate validation in all other
 cases. The `sideloaded?` helper is provided to help disambiguate edge cases.
 
 > TODO: The following three sections are a little confusing. Rewrite them.

data/demo-app/.dockerignore

@@ -0,0 +1 @@
+Gemfile.lock

data/demo-app/Dockerfile

@@ -0,0 +1,26 @@
+FROM ruby:2.3-alpine
+ARG container_port=4567
+ENV container_port=$container_port
+
+RUN apk --no-cache upgrade
+RUN apk --no-cache add \
+        sqlite-libs
+
+COPY Gemfile /app/
+RUN apk --no-cache add --virtual build-dependencies \
+        build-base \
+        git \
+        ruby-dev \
+        sqlite-dev \
+    && cd /app \
+    && DOCKER_BUILD=true bundle install --jobs=4 \
+    && apk del build-dependencies
+
+COPY . /app
+RUN chown -R nobody:nogroup /app
+
+USER nobody
+WORKDIR /app
+CMD bundle exec ruby app.rb -o 0.0.0.0 -p $container_port
+
+EXPOSE $container_port

data/demo-app/Gemfile

@@ -1,3 +1,14 @@
 source 'https://rubygems.org'
 
-gemspec :path=>'..'
+gem 'json', '~> 2.0'
+gem 'sequel', '~> 4.41'
+gem 'sinatra', '>= 2.0.0.beta2', '< 3'
+gem 'sinatra-contrib', '>= 2.0.0.beta2', '< 3'
+unless ENV.key?('DOCKER_BUILD')
+  gem 'sinja', path: '..'
+  gem 'sinja-sequel', path: '../extensions/sequel'
+else
+  gem 'sinja'
+  gem 'sinja-sequel'
+end
+gem 'sqlite3', '~> 1.3'

data/demo-app/README.md

@@ -1,38 +1,51 @@
 ## Demo App
 
-This is the demo app for Sinja, used as an example of and for testing Sinja. It
-is a very simplistic blog-like application with database tables, models,
-serializers, and controllers for authors, posts, comments, and tags. It uses
-[Sequel ORM](http://sequel.jeremyevans.net) (and the [Sequel
-helpers](/lib/sinja/helpers/sequel.rb) provided with Sinja) with an in-memory
-SQLite database, and it works under both MRI/YARV 2.3+ and JRuby 9.1+.
+This is the demo app for Sinja, provided both as an example of and for testing
+Sinja. It uses [Sequel ORM](http://sequel.jeremyevans.net) with an in-memory
+SQLite database and demonstrates the [Sequel extension](/extensions/sequel) for
+Sinja. It works under both MRI/YARV 2.3+ and JRuby 9.1+. It is a very
+simplistic blog-like application with [database
+tables](http://sequel.jeremyevans.net/rdoc/files/doc/schema_modification_rdoc.html),
+[models](http://sequel.jeremyevans.net/rdoc/files/README_rdoc.html#label-Sequel+Models),
+[serializers](https://github.com/fotinakis/jsonapi-serializers), and
+[controllers](/) for [authors](/demo-app/classes/author.rb),
+[posts](/demo-app/classes/post.rb), [comments](/demo-app/classes/comment.rb),
+and [tags](/demo-app/classes/tag.rb).
 
 ### Usage
 
-Assuming you have a working, Bundler-enabled Ruby environment, simply clone
-this repo, `cd` into the `demo-app` subdirectory, and run the following
-commands:
+Assuming you have a working, [Bundler](http://bundler.io)-enabled Ruby
+environment, simply clone this repo, `cd` into the `demo-app` subdirectory, and
+run the following commands:
 
 ```
 $ bundle install
 $ bundle exec ruby app.rb [-p <PORT>]
 ```
 
-The web server will report the port it's listening on, or you can specify a
-port with the `-p` option. It will respond to {json:api}-compliant requests
-(don't forget to set an `Accept` header) to `/authors`, `/posts`, `/comments`,
-and `/tags`, although not every endpoint is implemented. Log in by setting the
-`X-Email` header on the request to the email address of a registered user; the
-default administrator email address is all@yourbase.com.
+The web server will report the port it's listening on (most likely 4567), or
+you can specify a port with the `-p` option.
 
-**This is clearly extremely insecure and should not be used as-is in production.
-Caveat emptor.**
+Alternatively, if you don't want to clone this repo and set up a Ruby
+environment just for a quick demo, it's available on Docker Cloud as
+[mwpastore/sinja-demo-app](https://cloud.docker.com/app/mwpastore/repository/docker/mwpastore/sinja-demo-app):
+
+```
+$ docker run -it -p 4567:4567 --rm mwpastore/sinja-demo-app
+```
+
+It will respond to {json:api}-compliant requests (don't forget to set an
+`Accept` header) to `/authors`, `/posts`, `/comments`, and `/tags`, although
+not every endpoint is implemented. Log in by setting the `X-Email` header on
+the request to the email address of a registered user; the email address for
+the default admin user is all@yourbase.com. **This is clearly extremely
+insecure and should not be used as-is in production. Caveat emptor.**
 
 You can point it at a different database by setting `DATABASE_URL` in the
 environment before executing `app.rb`. See the relevant [Sequel
 documentation](http://sequel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html)
-for more information. It (rather na&iuml;vely) migrates the database at
-startup.
+for more information. It (rather na&iuml;vely) migrates the database and
+creates the default admin user at startup.
 
 ### Productionalizing
 
@@ -40,18 +53,20 @@ You can certainly use this as a starting point for a production application,
 but you will at least want to:
 
 - [ ] Use a persistent database
+- [ ] Remove or change the default admin user
 - [ ] Separate the class files (e.g. `author.rb`, `post.rb`) into separate
-      files for the migrations, models, serializers, and Sinja controllers
+      files for migrations, models, serializers, and Sinja controllers
 - [ ] Create a Gemfile using the dependencies in the top-level
       [gemspec](/sinja.gemspec) as a starting point
-- [ ] Add authentication middleware and rewrite the `role` helper to enable
-      the authorization scheme. You can use the existing roles as defined or
-      rename them (e.g. use `:admin` instead of `:superuser`)
+- [ ] Add authentication and rewrite the `role` helper to enable the
+      authorization scheme. You can use the existing roles as defined or rename
+      them (e.g. use `:admin` instead of `:superuser`)
 - [ ] Use a real application server such as [Puma](http://puma.io) or
       [Passenger](https://www.phusionpassenger.com) instead of Ruby's
       stdlib (WEBrick)
 - [ ] Configure Sequel's connection pool (i.e. `:max_connections`) to match the
-      application server's thread pool (if any)
+      application server's thread pool (if any) size, e.g.
+      `Puma.cli_config.options[:max_threads]`
 - [ ] Add caching directives (i.e. `cache_control`, `expires`, `last_modified`,
       and `etag`) as appropriate
 

data/demo-app/Rakefile

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+namespace :docker do
+  require 'securerandom'
+
+  IMAGE = 'mwpastore/sinja-demo-app'
+  NAME = SecureRandom.hex(6)
+  PORT = 4567
+
+  def port
+    %x{
+      docker inspect --format '{{ (index ( index .NetworkSettings.Ports "#{PORT}/tcp") 0).HostPort }}' #{NAME}
+    }.chomp
+  end
+
+  task :build do
+    sh "docker build --build-arg container_port=#{PORT} --no-cache -t #{IMAGE}:latest #{__dir__}"
+  end
+
+  task :test do
+    sh "docker run --rm -d -P --name #{NAME} #{IMAGE}"
+    sleep 5
+    begin
+      sh "curl -sf -H 'Accept: application/vnd.api+json' -I :#{port}/authors"
+    ensure
+      sh "docker stop #{NAME} >/dev/null || true"
+    end
+  end
+
+  task push: [:build, :test] do
+    sh "docker push #{IMAGE}:latest"
+  end
+
+  task :run do
+    sh "docker run --rm -it -p #{PORT}:#{PORT} #{IMAGE}"
+  end
+end

data/demo-app/app.rb

@@ -1,28 +1,21 @@
 # frozen_string_literal: true
 require 'sinatra'
 require 'sinatra/jsonapi'
+require 'sinja/sequel/helpers'
 
 require_relative 'classes/author'
 require_relative 'classes/comment'
 require_relative 'classes/post'
 require_relative 'classes/tag'
 
-require 'sinja/helpers/sequel'
-
 configure :development do
   set :server_settings, AccessLog: [] # avoid WEBrick double-logging issue
 end
 
-configure_jsonapi do |c|
-  Sinja::Helpers::Sequel.config(c)
-end
-
-helpers do
-  prepend Sinja::Helpers::Sequel
-
+helpers Sinja::Sequel::Helpers do
   def current_user
     # TESTING/DEMO PURPOSES ONLY -- DO NOT DO THIS IN PRODUCTION
-    Author.first_by_email(env['HTTP_X_EMAIL']) if env.key?('HTTP_X_EMAIL')
+    @current_user ||= Author.first_by_email(env['HTTP_X_EMAIL']) if env.key?('HTTP_X_EMAIL')
   end
 
   def role