sinja 1.0.0.pre2 → 1.1.0.pre1

data/demo-app/README.md

@@ -0,0 +1,58 @@
+## 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+.
+
+### 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:
+
+```
+$ 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.
+
+**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.
+
+### Productionalizing
+
+You can certainly use this as a starting point for a production application,
+but you will at least want to:
+
+- [ ] Use a persistent database
+- [ ] Separate the class files (e.g. `author.rb`, `post.rb`) into separate
+      files for the 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`)
+- [ ] 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)
+- [ ] Add caching directives (i.e. `cache_control`, `expires`, `last_modified`,
+      and `etag`) as appropriate
+
+And probably a whole lot more!

data/demo-app/app.rb

@@ -9,6 +9,10 @@ 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
@@ -19,16 +23,16 @@ helpers Sinja::Helpers::Sequel do
     Author.first_by_email(env['HTTP_X_EMAIL']) if env.key?('HTTP_X_EMAIL')
   end
 
+  def database
+    DB
+  end
+
   def role
     [].tap do |a|
       a << :logged_in if current_user
       a << :superuser if current_user&.admin?
     end
   end
-
-  def database
-    DB
-  end
 end
 
 resource :authors, AuthorController

data/demo-app/boot.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
 require 'bundler/setup'
 
-Bundler.require(:default, :development)
+Bundler.require :default
+Bundler.require Sinatra::Base.environment
+Bundler.require :development if Sinatra::Base.test?

data/demo-app/classes/author.rb

@@ -4,10 +4,10 @@ require_relative '../database'
 
 DB.create_table?(:authors) do
   primary_key :id
-  String :email, :null=>false, :unique=>true
+  String :email, null: false, unique: true
   String :real_name
   String :display_name
-  TrueClass :admin, :default=>false
+  TrueClass :admin, default: false
   DateTime :created_at
   DateTime :updated_at
 end
@@ -17,13 +17,14 @@ class Author < Sequel::Model
   plugin :boolean_readers
 
   finder def self.by_email(arg)
-    where(:email=>arg)
+    where(email: arg)
   end
 
   one_to_many :comments
   one_to_many :posts
 end
 
+# We have to create an admin user here, otherwise we have no way to create one.
 Author.create(email: 'all@yourbase.com', admin: true)
 
 class AuthorSerializer < BaseSerializer
@@ -40,14 +41,12 @@ AuthorController = proc do
     end
 
     def role
-      if resource == current_user
-        super.push(:self)
-      else
-        super
+      [*super].tap do |a|
+        a << :myself if resource == current_user
       end
     end
 
-    def fields
+    def settable_fields
       %i[email real_name display_name].tap do |a|
         a << :admin if role?(:superuser)
       end
@@ -56,33 +55,37 @@ AuthorController = proc do
 
   show
 
+  show_many do |ids|
+    Author.where(id: ids.map!(&:to_i)).all
+  end
+
   index do
-    Author.all
+    Author.dataset
   end
 
   create do |attr|
     author = Author.new
-    author.set_fields(attr, fields)
+    author.set_fields(attr, settable_fields)
     next_pk author.save(validate: false)
   end
 
-  update(roles: %i[self superuser]) do |attr|
-    resource.update_fields(attr, fields, validate: false, missing: :skip)
+  update(roles: %i[myself superuser]) do |attr|
+    resource.update_fields(attr, settable_fields, validate: false, missing: :skip)
   end
 
-  destroy(roles: %i[self superuser]) do
+  destroy(roles: %i[myself superuser]) do
     resource.destroy
   end
 
   has_many :comments do
     fetch(roles: :logged_in) do
-      resource.comments
+      resource.comments_dataset
     end
   end
 
   has_many :posts do
     fetch do
-      resource.posts
+      resource.posts_dataset
     end
   end
 end

data/demo-app/classes/comment.rb

@@ -4,9 +4,9 @@ require_relative '../database'
 
 DB.create_table?(:comments) do
   primary_key :id
-  foreign_key :author_id, :authors, :on_delete=>:cascade
-  foreign_key :post_slug, :posts, :on_delete=>:cascade, :type=>String
-  String :body, :text=>true, :null=>false
+  foreign_key :author_id, :authors, on_delete: :cascade
+  foreign_key :post_slug, :posts, type: String, on_delete: :cascade, on_update: :cascade
+  String :body, text: true, null: false
   DateTime :created_at
   DateTime :updated_at
 end
@@ -37,12 +37,14 @@ CommentController = proc do
     end
 
     def role
-      if resource&.author == current_user
-        super.push(:owner)
-      else
-        super
+      [*super].tap do |a|
+        a << :owner if resource&.author == current_user
       end
     end
+
+    def settable_fields
+      %i[body]
+    end
   end
 
   show do |id|
@@ -51,13 +53,13 @@ CommentController = proc do
 
   create(roles: :logged_in) do |attr|
     comment = Comment.new
-    comment.set_fields(attr, %i[body])
+    comment.set_fields(attr, settable_fields)
     comment.save(validate: false)
     next_pk comment
   end
 
   update(roles: %i[owner superuser]) do |attr|
-    resource.update_fields(attr, %i[body], validate: false, missing: :skip)
+    resource.update_fields(attr, settable_fields, validate: false, missing: :skip)
   end
 
   destroy(roles: %i[owner superuser]) do

data/demo-app/classes/post.rb

@@ -3,10 +3,10 @@ require_relative '../base'
 require_relative '../database'
 
 DB.create_table?(:posts) do
-  String :slug, :primary_key=>true
-  foreign_key :author_id, :authors, :on_delete=>:cascade
-  String :title, :null=>false
-  String :body, :text=>true, :null=>false
+  String :slug, primary_key: true
+  foreign_key :author_id, :authors, on_delete: :cascade
+  String :title, null: false
+  String :body, text: true, null: false
   DateTime :created_at
   DateTime :updated_at
 end
@@ -14,11 +14,11 @@ end
 class Post < Sequel::Model
   plugin :timestamps
 
-  unrestrict_primary_key
+  unrestrict_primary_key # allow client-generated slugs
 
   many_to_one :author
   one_to_many :comments
-  many_to_many :tags, :left_key=>:post_slug
+  many_to_many :tags, left_key: :post_slug
 
   def validate
     super
@@ -45,33 +45,38 @@ PostController = proc do
     end
 
     def role
-      if resource&.author == current_user
-        super.push(:owner)
-      else
-        super
+      [*super].tap do |a|
+        a << :owner if resource&.author == current_user
       end
     end
+
+    def settable_fields
+      %i[title body]
+    end
   end
 
   show do |slug|
     next find(slug), include: %w[author comments tags]
   end
 
+  show_many do |slugs|
+    next Post.where(slug: slugs.map!(&:to_s)).all, include: %i[author tags]
+  end
+
   index do
-    # TODO: Filter/sort by created_at and/or updated_at?
-    Post.all
+    Post.dataset
   end
 
   create(roles: :logged_in) do |attr, slug|
     post = Post.new
-    post.set_fields(attr, %i[title body])
+    post.set_fields(attr, settable_fields)
     post.slug = slug.to_s # set primary key
     post.save(validate: false)
     next_pk post
   end
 
   update(roles: %i[owner superuser]) do |attr|
-    resource.update_fields(attr, %i[title body], validate: false, missing: :skip)
+    resource.update_fields(attr, settable_fields, validate: false, missing: :skip)
   end
 
   destroy(roles: %i[owner superuser]) do
@@ -94,13 +99,13 @@ PostController = proc do
 
   has_many :comments do
     fetch do
-      next resource.comments, include: 'author'
+      next resource.comments_dataset, include: 'author'
     end
   end
 
   has_many :tags do
     fetch do
-      resource.tags
+      resource.tags_dataset
     end
 
     merge(roles: %i[owner superuser], sideload_on: %i[create update]) do |rios|

data/demo-app/classes/tag.rb

@@ -6,18 +6,18 @@ require_relative 'post' # make sure we create the posts table before the join ta
 
 DB.create_table?(:tags) do
   primary_key :id
-  String :name, :null=>false, :unique=>true
+  String :name, null: false, unique: true
 end
 
 DB.create_table?(:posts_tags) do
-  foreign_key :post_slug, :posts, :null=>false, :on_delete=>:cascade, :type=>String
-  foreign_key :tag_id, :tags, :null=>false, :on_delete=>:cascade
+  foreign_key :post_slug, :posts, type: String, null: false, on_delete: :cascade, on_update: :cascade
+  foreign_key :tag_id, :tags, null: false, on_delete: :cascade
   primary_key [:post_slug, :tag_id]
   index [:tag_id, :post_slug]
 end
 
 class Tag < Sequel::Model
-  many_to_many :posts
+  many_to_many :posts, right_key: :post_slug
 end
 
 class TagSerializer < BaseSerializer
@@ -31,17 +31,21 @@ TagController = proc do
     def find(id)
       Tag[id.to_i]
     end
+
+    def settable_fields
+      %i[name]
+    end
   end
 
   show
 
-  index do
-    Tag.all
+  index(sort_by: :name, filter_by: :name) do
+    Tag.dataset
   end
 
   create(roles: :logged_in) do |attr|
     tag = Tag.new
-    tag.set_fields(attr, %i[name])
+    tag.set_fields(attr, settable_fields)
     tag.save(validate: false)
     next_pk tag
   end
@@ -52,7 +56,7 @@ TagController = proc do
 
   has_many :posts do
     fetch do
-      resource.posts
+      resource.posts_dataset
     end
 
     merge(roles: :logged_in) do |rios|

data/demo-app/database.rb

@@ -2,11 +2,9 @@
 require 'logger'
 require_relative 'boot'
 
-DB =
-  if defined?(JRUBY_VERSION)
-    Sequel.connect 'jdbc:sqlite::memory:'
-  else
-    Sequel.sqlite
-  end
+DB = Sequel.connect ENV.fetch 'DATABASE_URL',
+  defined?(JRUBY_VERSION) ? 'jdbc:sqlite::memory:' : 'sqlite:/'
+
+DB.extension :pagination
 
 DB.loggers << Logger.new($stderr) if Sinatra::Base.development?

data/lib/sinja/config.rb

@@ -15,7 +15,21 @@ module Sinja
     end
 
     def deep_freeze(c)
-      c.tap { |i| i.values.each(&:freeze) }.freeze
+      if c.respond_to?(:default_proc)
+        c.default_proc = nil
+      end
+
+      if c.respond_to?(:values)
+        c.values.each do |i|
+          if Hash === i
+            deep_freeze(i)
+          else
+            i.freeze
+          end
+        end
+      end
+
+      c.freeze
     end
   end
 
@@ -33,41 +47,54 @@ module Sinja
     }.freeze
 
     attr_reader \
+      :query_params,
       :error_logger,
-      :default_roles,
-      :default_has_many_roles,
-      :default_has_one_roles,
-      :resource_roles,
-      :resource_sideload,
+      :resource_config,
       :conflict_exceptions,
       :not_found_exceptions,
       :validation_exceptions,
       :validation_formatter,
+      :page_using,
       :serializer_opts
 
     def initialize
-      @error_logger = ->(eh) { logger.error('sinja') { eh } }
-
-      @default_roles = RolesConfig.new(ResourceRoutes::ACTIONS)
-      @default_has_many_roles = RolesConfig.new(RelationshipRoutes::HasMany::ACTIONS)
-      @default_has_one_roles = RolesConfig.new(RelationshipRoutes::HasOne::ACTIONS)
-
-      @resource_roles = Hash.new { |h, k| h[k] = {
-        :resource=>@default_roles.dup,
-        :has_many=>Hash.new { |rh, rk| rh[rk] = @default_has_many_roles.dup },
-        :has_one=>Hash.new { |rh, rk| rh[rk] = @default_has_one_roles.dup }
+      @query_params = {
+        :fields=>{}, # passthru to JAS
+        :include=>[], # passthru to JAS
+        :filter=>{},
+        :page=>{},
+        :sort=>[],
+        :capture=>nil
+      }
+
+      @error_logger = ->(h) { logger.error('sinja') { h } }
+
+      @default_roles = {
+        :resource=>RolesConfig.new(%i[show show_many index create update destroy]),
+        :has_many=>RolesConfig.new(%i[fetch merge subtract clear]),
+        :has_one=>RolesConfig.new(%i[pluck graft prune])
+      }
+
+      action_proc = proc { |type, hash, action| hash[action] = {
+        :roles=>@default_roles[type][action].dup,
+        :sideload_on=>Set.new,
+        :filter_by=>Set.new,
+        :sort_by=>Set.new
+      }}.curry
+
+      @resource_config = Hash.new { |h, k| h[k] = {
+        :resource=>Hash.new(&action_proc[:resource]),
+        :has_many=>Hash.new { |rh, rk| rh[rk] = Hash.new(&action_proc[:has_many]) },
+        :has_one=>Hash.new { |rh, rk| rh[rk] = Hash.new(&action_proc[:has_one]) }
       }}
 
-      @resource_sideload = Hash.new do |h, k|
-        h[k] = SideloadConfig.new(Resource::SIDELOAD_ACTIONS)
-      end
-
       @conflict_exceptions = Set.new
       @not_found_exceptions = Set.new
       @validation_exceptions = Set.new
       @validation_formatter = ->{ Array.new }
 
       @opts = deep_copy(DEFAULT_OPTS)
+      @page_using = Hash.new
       @serializer_opts = deep_copy(DEFAULT_SERIALIZER_OPTS)
     end
 
@@ -82,15 +109,15 @@ module Sinja
     end
 
     def conflict_exceptions=(e=[])
-      @conflict_exceptions.replace(Set[*e])
+      @conflict_exceptions.replace([*e])
     end
 
     def not_found_exceptions=(e=[])
-      @not_found_exceptions.replace(Set[*e])
+      @not_found_exceptions.replace([*e])
     end
 
     def validation_exceptions=(e=[])
-      @validation_exceptions.replace(Set[*e])
+      @validation_exceptions.replace([*e])
     end
 
     def validation_formatter=(f)
@@ -103,12 +130,28 @@ module Sinja
       @validation_formatter = f
     end
 
-    def_delegator :@default_roles, :merge!, :default_roles=
-    def_delegator :@default_has_many_roles, :merge!, :default_has_many_roles=
-    def_delegator :@default_has_one_roles, :merge!, :default_has_one_roles=
+    def default_roles
+      @default_roles[:resource]
+    end
 
-    def serializer_opts=(h={})
-      @serializer_opts.replace(deep_copy(DEFAULT_SERIALIZER_OPTS).merge!(h))
+    def default_roles=(other={})
+      @default_roles[:resource].merge!(other)
+    end
+
+    def default_has_many_roles
+      @default_roles[:has_many]
+    end
+
+    def default_has_many_roles=(other={})
+      @default_roles[:has_many].merge!(other)
+    end
+
+    def default_has_one_roles
+      @default_roles[:has_one]
+    end
+
+    def default_has_one_roles=(other={})
+      @default_roles[:has_one].merge!(other)
     end
 
     DEFAULT_OPTS.keys.each do |k|
@@ -116,34 +159,29 @@ module Sinja
       define_method("#{k}=") { |v| @opts[k] = v }
     end
 
+    def page_using=(p={})
+      @page_using.replace(p)
+    end
+
+    def serializer_opts=(h={})
+      @serializer_opts.replace(deep_copy(DEFAULT_SERIALIZER_OPTS).merge!(h))
+    end
+
     def freeze
+      @query_params.freeze
       @error_logger.freeze
 
-      @default_roles.freeze
-      @default_has_many_roles.freeze
-      @default_has_one_roles.freeze
-
-      @resource_roles.default_proc = nil
-      @resource_roles.values.each do |h|
-        h[:resource].freeze
-        h[:has_many].default_proc = nil
-        deep_freeze(h[:has_many])
-        h[:has_one].default_proc = nil
-        deep_freeze(h[:has_one])
-      end
-      deep_freeze(@resource_roles)
-
-      @resource_sideload.default_proc = nil
-      deep_freeze(@resource_sideload)
+      deep_freeze(@default_roles)
+      deep_freeze(@resource_config)
 
       @conflict_exceptions.freeze
       @not_found_exceptions.freeze
       @validation_exceptions.freeze
       @validation_formatter.freeze
 
-      deep_freeze(@serializer_opts)
-
       @opts.freeze
+      @page_using.freeze
+      deep_freeze(@serializer_opts)
 
       super
     end
@@ -173,7 +211,7 @@ module Sinja
       h.each do |action, roles|
         abort "Unknown or invalid action helper `#{action}' in configuration" \
           unless @data.key?(action)
-        @data[action].replace(Roles[*roles])
+        @data[action].replace([*roles])
       end
       @data
     end
@@ -188,33 +226,4 @@ module Sinja
       super
     end
   end
-
-  class SideloadConfig
-    include ConfigUtils
-    extend Forwardable
-
-    def initialize(actions=[])
-      @data = actions.map { |child| [child, Set.new] }.to_h
-    end
-
-    def_delegators :@data, :[], :dig
-
-    def ==(other)
-      @data == other.instance_variable_get(:@data)
-    end
-
-    def merge!(h={})
-      h.each do |child, parents|
-        abort "Unknown or invalid action helper `#{child}' in configuration" \
-          unless @data.key?(child)
-        @data[child].replace(Set[*parents])
-      end
-      @data
-    end
-
-    def freeze
-      deep_freeze(@data)
-      super
-    end
-  end
 end

data/lib/sinja/helpers/relationships.rb

@@ -19,9 +19,11 @@ module Sinja
       end
 
       def dispatch_relationship_requests!(id, methods: {}, **opts)
-        data.fetch(:relationships, {}).each do |path, body|
-          method = methods.fetch(settings._resource_roles[:has_one].key?(path.to_sym) ? :has_one : :has_many, :patch)
-          code, _, *json = dispatch_relationship_request(id, path, opts.merge(:body=>body, :method=>method))
+        data.fetch(:relationships, {}).each do |rel, body|
+          rel_type = settings._resource_config[:has_one].key?(rel) ? :has_one : :has_many
+          code, _, *json = dispatch_relationship_request id, rel,
+            opts.merge(:body=>body, :method=>methods.fetch(rel_type, :patch))
+
           # TODO: Gather responses and report all errors instead of only first?
           # `halt' was called (instead of raise); rethrow it as best as possible
           raise SideloadError.new(code, json) unless (200...300).cover?(code)