sinja 1.0.0.pre2 → 1.1.0.pre1

data/lib/sinja/helpers/sequel.rb

@@ -11,6 +11,12 @@ module Sinja
         c.not_found_exceptions << ::Sequel::NoMatchingRow
         c.validation_exceptions << ::Sequel::ValidationFailed
         c.validation_formatter = ->(e) { e.errors.keys.zip(e.errors.full_messages) }
+
+        c.page_using = {
+          :number=>1,
+          :size=>10,
+          :record_count=>nil
+        } if ::Sequel::Database::EXTENSIONS.key?(:pagination)
       end
 
       def validate!
@@ -21,6 +27,43 @@ module Sinja
         ::Sequel::DATABASES.first
       end
 
+      def filter(collection, **fields)
+        collection.where(fields)
+      end
+
+      def sort(collection, **fields)
+        collection.order(*fields.map { |k, v| ::Sequel.send(v, k) })
+      end
+
+      def page(collection, **opts)
+        opts = settings._sinja.page_using.merge(opts)
+        collection = collection.dataset \
+          unless collection.respond_to?(:paginate)
+        collection = collection.paginate \
+          opts[:number].to_i,
+          opts[:size].to_i,
+          (opts[:record_count].to_i if opts[:record_count])
+
+        # Attributes common to all pagination links
+        base = {
+          :size=>collection.page_size,
+          :record_count=>collection.pagination_record_count
+        }
+        pagination = {
+          :first=>base.merge(:number=>1),
+          :self=>base.merge(:number=>collection.current_page),
+          :last=>base.merge(:number=>collection.page_count)
+        }
+        pagination[:next] = base.merge(:number=>collection.next_page) if collection.next_page
+        pagination[:prev] = base.merge(:number=>collection.prev_page) if collection.prev_page
+
+        return collection, pagination
+      end if ::Sequel::Database::EXTENSIONS.key?(:pagination)
+
+      def finalize(collection)
+        collection.all
+      end
+
       def transaction(&block)
         database.transaction(&block)
       end

data/lib/sinja/helpers/serializers.rb

@@ -39,17 +39,16 @@ module Sinja
       end
 
       def include_exclude!(options)
-        client, default, excluded =
+        included, default, excluded =
           params[:include],
           options.delete(:include) || [],
           options.delete(:exclude) || []
 
-        included = Array === client ? client : client.split(',')
         if included.empty?
           included = Array === default ? default : default.split(',')
-        end
 
-        return included if included.empty?
+          return included if included.empty?
+        end
 
         excluded = Array === excluded ? excluded : excluded.split(',')
         unless excluded.empty?
@@ -64,7 +63,7 @@ module Sinja
           return included if included.empty?
         end
 
-        return included unless settings._resource_roles
+        return included unless settings._resource_config
 
         # Walk the tree and try to exclude based on fetch and pluck permissions
         included.keep_if do |termstr|
@@ -72,18 +71,19 @@ module Sinja
             *terms, last_term = termstr.split('.')
 
             # Start cursor at root of current resource
-            roles = settings._resource_roles
+            config = settings._resource_config
             terms.each do |term|
               # Move cursor through each term, avoiding the default proc,
               # halting if no roles found, i.e. client asked to include
               # something that Sinja doesn't know about
               throw :keep?, true \
-                unless roles = settings._sinja.resource_roles.fetch(term.pluralize.to_sym, nil)
+                unless config = settings._sinja.resource_config.fetch(term.pluralize.to_sym, nil)
             end
 
-            roles =
-              roles.dig(:has_many, last_term.pluralize.to_sym, :fetch) ||
-              roles.dig(:has_one, last_term.singularize.to_sym, :pluck)
+            roles = (
+              config.dig(:has_many, last_term.pluralize.to_sym, :fetch) ||
+              config.dig(:has_one, last_term.singularize.to_sym, :pluck)
+            )[:roles]
 
             throw :keep?, roles && (roles.empty? || roles === memoized_role)
           end
@@ -95,9 +95,9 @@ module Sinja
         options[:skip_collection_check] = defined?(::Sequel) && ::Sequel::Model === model
         options[:include] = include_exclude!(options)
         options[:fields] ||= params[:fields] unless params[:fields].empty?
+        options = settings._sinja.serializer_opts.merge(options)
 
-        ::JSONAPI::Serializer.serialize model,
-          settings._sinja.serializer_opts.merge(options)
+        ::JSONAPI::Serializer.serialize(model, options)
       end
 
       def serialize_model?(model=nil, options={})
@@ -114,9 +114,29 @@ module Sinja
         options[:is_collection] = true
         options[:include] = include_exclude!(options)
         options[:fields] ||= params[:fields] unless params[:fields].empty?
+        options = settings._sinja.serializer_opts.merge(options)
 
-        ::JSONAPI::Serializer.serialize [*models],
-          settings._sinja.serializer_opts.merge(options)
+        if options.key?(:links) && pagination = options[:links].delete(:pagination)
+          options[:links][:self] = request.url unless pagination.key?(:self)
+
+          query = Rack::Utils.build_nested_query \
+            env['rack.request.query_hash'].dup.tap { |h| h.delete('page') }
+          self_link, join_char =
+            if query.empty?
+              [request.path, ??]
+            else
+              ["#{request.path}?#{query}", ?&]
+            end
+
+          %i[self first prev next last].each do |key|
+            next unless pagination.key?(key)
+            query = Rack::Utils.build_nested_query \
+              :page=>pagination[key]
+            options[:links][key] = "#{self_link}#{join_char}#{query}"
+          end
+        end
+
+        ::JSONAPI::Serializer.serialize([*models], options)
       end
 
       def serialize_models?(models=[], options={})
@@ -129,16 +149,15 @@ module Sinja
         end
       end
 
-      def serialize_linkage(model, rel_path, options={})
+      def serialize_linkage(model, rel, options={})
         options[:is_collection] = false
         options[:skip_collection_check] = defined?(::Sequel) && ::Sequel::Model === model
-        options[:include] = rel_path.to_s
-
-        content = ::JSONAPI::Serializer.serialize model,
-          settings._sinja.serializer_opts.merge(options)
+        options[:include] = rel.to_s
+        options = settings._sinja.serializer_opts.merge(options)
 
         # TODO: This is extremely wasteful. Refactor JAS to expose the linkage serializer?
-        content['data']['relationships'][rel_path.to_s].tap do |linkage|
+        content = ::JSONAPI::Serializer.serialize(model, options)
+        content['data']['relationships'][rel.to_s].tap do |linkage|
           %w[meta jsonapi].each do |key|
             linkage[key] = content[key] if content.key?(key)
           end

data/lib/sinja/relationship_routes/has_many.rb

@@ -2,10 +2,11 @@
 module Sinja
   module RelationshipRoutes
     module HasMany
-      ACTIONS = %i[fetch clear merge subtract].freeze
-
       def self.registered(app)
-        app.def_action_helpers(ACTIONS, app)
+        app.def_action_helper(app, :fetch, %i[roles filter_by sort_by])
+        app.def_action_helper(app, :clear, %i[roles sideload_on])
+        app.def_action_helper(app, :merge, %i[roles sideload_on])
+        app.def_action_helper(app, :subtract, :roles)
 
         app.head '' do
           unless relationship_link?
@@ -21,8 +22,11 @@ module Sinja
           serialize_linkage
         end
 
-        app.get '', :actions=>:fetch do
-          serialize_models(*fetch)
+        app.get '', :qparams=>%i[include fields filter sort page], :actions=>:fetch do
+          collection, opts = fetch
+          collection, links = filter_sort_page(collection, :fetch)
+          (opts[:links] ||= {}).merge!(links)
+          serialize_models(collection, opts)
         end
 
         app.patch '', :nullif=>proc(&:empty?), :actions=>:clear do

data/lib/sinja/relationship_routes/has_one.rb

@@ -2,10 +2,10 @@
 module Sinja
   module RelationshipRoutes
     module HasOne
-      ACTIONS = %i[pluck prune graft].freeze
-
       def self.registered(app)
-        app.def_action_helpers(ACTIONS, app)
+        app.def_action_helper(app, :pluck, :roles)
+        app.def_action_helper(app, :prune, :roles)
+        app.def_action_helper(app, :graft, %i[roles sideload_on])
 
         app.head '' do
           unless relationship_link?
@@ -21,7 +21,7 @@ module Sinja
           serialize_linkage
         end
 
-        app.get '', :actions=>:pluck do
+        app.get '', :qparams=>%i[include fields], :actions=>:pluck do
           serialize_model(*pluck)
         end
 

data/lib/sinja/resource.rb

@@ -12,15 +12,17 @@ require 'sinja/resource_routes'
 
 module Sinja
   module Resource
-    SIDELOAD_ACTIONS = Set.new(%i[graft merge clear]).freeze
-
-    def def_action_helper(action, context)
-      abort "JSONAPI action helpers can't be HTTP verbs!" \
+    def def_action_helper(context, action, allow_opts=[])
+      abort "Action helper names can't overlap with Sinatra DSL" \
         if Sinatra::Base.respond_to?(action)
 
       context.define_singleton_method(action) do |**opts, &block|
-        resource_roles.merge!(action=>opts[:roles]) if opts.key?(:roles)
-        resource_sideload.merge!(action=>opts[:sideload_on]) if opts.key?(:sideload_on)
+        abort "Unexpected option(s) for `#{action}' action helper" \
+          unless (opts.keys - [*allow_opts]).empty?
+
+        resource_config[action].each do |k, v|
+          v.replace([*opts[k]]) if opts.key?(k)
+        end
 
         return unless block ||=
           case !method_defined?(action) && action
@@ -32,14 +34,16 @@ module Sinja
         required_arity = {
           :create=>2,
           :index=>-1,
-          :fetch=>-1
+          :fetch=>-1,
+          :show_many=>-1
         }.freeze[action] || 1
 
         define_method(action) do |*args|
-          raise ArgumentError, "Unexpected block signature for `#{action}' action helper" \
+          raise ArgumentError, "Unexpected argument(s) for `#{action}' action helper" \
             unless args.length == block.arity
 
-          public_send("before_#{action}", *args) if respond_to?("before_#{action}")
+          public_send("before_#{action}", *args) \
+            if respond_to?("before_#{action}")
 
           case result = instance_exec(*args, &block)
           when Array
@@ -67,10 +71,6 @@ module Sinja
       end
     end
 
-    def def_action_helpers(actions, context=nil)
-      [*actions].each { |action| def_action_helper(action, context) }
-    end
-
     def self.registered(app)
       app.helpers Helpers::Relationships do
         attr_accessor :resource
@@ -81,25 +81,23 @@ module Sinja
 
     %i[has_one has_many].each do |rel_type|
       define_method(rel_type) do |rel, &block|
-        rel_path = rel.to_s
+        rel = rel.to_s
           .send(rel_type == :has_one ? :singularize : :pluralize)
           .dasherize
           .to_sym
 
-        _resource_roles[rel_type][rel.to_sym] # trigger default proc
+        config = _resource_config[rel_type][rel] # trigger default proc
 
-        namespace %r{/[^/]+(?<r>/relationships)?/#{rel_path}} do
-          define_singleton_method(:resource_roles) do
-            _resource_roles[rel_type][rel.to_sym]
-          end
+        namespace %r{/[^/]+(?<r>/relationships)?/#{rel}} do
+          define_singleton_method(:resource_config) { config }
 
           helpers Helpers::Nested do
             define_method(:can?) do |*args|
-              super(*args, rel_type, rel.to_sym)
+              super(*args, rel_type, rel)
             end
 
             define_method(:serialize_linkage) do |*args|
-              super(resource, rel_path, *args)
+              super(resource, rel, *args)
             end
           end
 

data/lib/sinja/resource_routes.rb

@@ -1,39 +1,52 @@
 # frozen_string_literal: true
 module Sinja
   module ResourceRoutes
-    ACTIONS = %i[index show create update destroy].freeze
-
     def self.registered(app)
-      app.def_action_helpers(ACTIONS, app)
+      app.def_action_helper(app, :show, :roles)
+      app.def_action_helper(app, :show_many)
+      app.def_action_helper(app, :index, %i[roles filter_by sort_by])
+      app.def_action_helper(app, :create, :roles)
+      app.def_action_helper(app, :update, :roles)
+      app.def_action_helper(app, :destroy, :roles)
 
-      app.head '', :pfilters=>:id do
+      app.head '', :qcapture=>{ :filter=>:id } do
         allow :get=>:show
       end
 
-      app.get '', :pfilters=>:id, :actions=>:show do
-        ids = params['filter'].delete('id')
-        ids = ids.split(',') if ids.respond_to?(:split)
+      app.get '', :qcapture=>{ :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!)
 
-        opts = {}
-        resources = [*ids].tap(&:uniq!).map! do |id|
-          tmp, opts = show(id)
-          raise NotFoundError, "Resource '#{id}' not found" unless tmp
-          tmp
-        end
+        if respond_to?(:show_many)
+          resources, opts = show_many(ids)
+          raise NotFoundError, "Resource(s) not found" \
+            unless ids.length == resources.length
+          serialize_models(resources, opts)
+        else
+          opts = {}
+          resources = ids.map! do |id|
+            tmp, opts = show(id)
+            raise NotFoundError, "Resource '#{id}' not found" unless tmp
+            tmp
+          end
 
-        # TODO: Serialize collection with opts from last model found?
-        serialize_models(resources, opts)
+          serialize_models(resources, opts)
+        end
       end
 
       app.head '' do
         allow :get=>:index, :post=>:create
       end
 
-      app.get '', :actions=>:index do
-        serialize_models(*index)
+      app.get '', :qparams=>%i[include fields filter sort page], :actions=>:index do
+        collection, opts = index
+        collection, links = filter_sort_page(collection, :index)
+        (opts[:links] ||= {}).merge!(links)
+        serialize_models(collection, opts)
       end
 
-      app.post '', :actions=>:create do
+      app.post '', :qparams=>:include, :actions=>:create do
         sanity_check!
 
         opts = {}
@@ -72,13 +85,13 @@ module Sinja
         allow :get=>:show, :patch=>:update, :delete=>:destroy
       end
 
-      app.get '/:id', :actions=>:show do |id|
+      app.get '/:id', :qparams=>%i[include fields], :actions=>:show do |id|
         tmp, opts = show(id)
         raise NotFoundError, "Resource '#{id}' not found" unless tmp
         serialize_model(tmp, opts)
       end
 
-      app.patch '/:id', :actions=>:update do |id|
+      app.patch '/:id', :qparams=>:include, :actions=>:update do |id|
         sanity_check!(id)
         tmp, opts = transaction do
           update(attributes).tap do

data/lib/sinja/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Sinja
-  VERSION = '1.0.0.pre2'
+  VERSION = '1.1.0.pre1'
 end

data/lib/sinja.rb

@@ -4,6 +4,7 @@ require 'mustermann'
 require 'sinatra/base'
 require 'sinatra/namespace'
 
+require 'set'
 require 'sinja/config'
 require 'sinja/errors'
 require 'sinja/helpers/serializers'
@@ -34,33 +35,17 @@ module Sinja
       .to_sym
 
     # trigger default procs
-    _sinja.resource_roles[resource_name]
-    _sinja.resource_sideload[resource_name]
+    config = _sinja.resource_config[resource_name]
 
     namespace "/#{resource_name}" do
-      define_singleton_method(:_resource_roles) do
-        _sinja.resource_roles[resource_name]
-      end
-
-      define_singleton_method(:resource_roles) do
-        _resource_roles[:resource]
-      end
-
-      define_singleton_method(:resource_sideload) do
-        _sinja.resource_sideload[resource_name]
-      end
+      define_singleton_method(:_resource_config) { config }
+      define_singleton_method(:resource_config) { config[:resource] }
 
       helpers do
-        define_method(:can?) do |*args|
-          super(resource_name, *args)
-        end
-
-        define_method(:sanity_check!) do |*args|
-          super(resource_name, *args)
-        end
-
-        define_method(:sideload?) do |*args|
-          super(resource_name, *args)
+        %i[can? sanity_check! sideload?].each do |meth|
+          define_method(meth) do |*args|
+            super(resource_name, *args)
+          end
         end
       end
 
@@ -102,7 +87,7 @@ module Sinja
 
     app.disable :protection, :show_exceptions, :static
     app.set :_sinja, Sinja::Config.new
-    app.set :_resource_roles, nil # dummy value overridden in each resource
+    app.set :_resource_config, nil # dummy value overridden in each resource
 
     app.set :actions do |*actions|
       condition do
@@ -112,18 +97,61 @@ module Sinja
           raise MethodNotAllowedError, 'Action or method not implemented or supported' \
             unless respond_to?(action)
         end
+
         true
       end
     end
 
-    app.set :pfilters do |*pfilters|
+    app.set :qcapture do |*index|
       condition do
-        pfilters.all? do |pfilter|
-          params.key?('filter') && params['filter'].key?(pfilter.to_s)
+        @qcaptures ||= []
+        index.to_h.all? do |key, subkeys|
+          params.key?(key.to_s) && [*subkeys].all? do |subkey|
+            @qcaptures << params[key.to_s].delete(subkey.to_s) \
+              if params[key.to_s].key?(subkey.to_s)
+          end
         end
       end
     end
 
+    app.set :qparams do |*allow_params|
+      allow_params = allow_params.to_set
+
+      abort "Unexpected query parameter(s) in route definiton" \
+        unless allow_params.subset?(settings._sinja.query_params.keys.to_set)
+
+      condition do
+        params.each do |key, value|
+          key = key.to_sym
+
+          next if settings._sinja.query_params[key].nil?
+
+          raise BadRequestError, "`#{key}' query parameter not allowed" \
+            unless allow_params.include?(key) || value.empty?
+
+          if Array === settings._sinja.query_params[key] && String === value
+            value = (params[key.to_s] = value.split(','))
+          elsif !(settings._sinja.query_params[key].class === value)
+            raise BadRequestError, "`#{key}' query parameter malformed"
+          end
+        end
+
+        settings._sinja.query_params.each do |key, value|
+          next if value.nil?
+
+          key = key.to_s
+
+          if respond_to?("normalize_#{key}_params")
+            params[key] = send("normalize_#{key}_params")
+          else
+            params[key] ||= value
+          end
+        end
+
+        true
+      end
+    end
+
     app.set :nullif do |nullish|
       condition { nullish.(data) }
     end
@@ -151,10 +179,13 @@ module Sinja
       end
 
       def can?(resource_name, action, rel_type=nil, rel=nil)
-        lookup = settings._sinja.resource_roles[resource_name]
-        # TODO: This is... problematic.
-        roles = (lookup[rel_type][rel][action] if rel_type && rel) || lookup[:resource][action]
-        roles.nil? || roles.empty? || roles === memoized_role
+        config = settings._sinja.resource_config[resource_name]
+        config = rel_type && rel ? config[rel_type][rel] : config[:resource]
+        # JRuby issues with nil default_proc (fixed in 9.1.7.0?)
+        # https://github.com/jruby/jruby/issues/4302
+        #roles = config&.dig(action, :roles)
+        roles = config&.key?(action) && config[action][:roles]
+        !roles || roles.empty? || roles === memoized_role
       end
 
       def content?
@@ -166,8 +197,72 @@ module Sinja
         @data[request.path] ||= begin
           deserialize_request_body.fetch(:data)
         rescue NoMethodError, KeyError
-          raise BadRequestError, 'Malformed JSON:API request payload'
+          raise BadRequestError, 'Malformed {json:api} request payload'
+        end
+      end
+
+      def normalize_filter_params
+        return {} unless params[:filter]&.any?
+
+        halt 400, "Unsupported `filter' query parameter(s)" \
+          unless respond_to?(:filter)
+
+        params[:filter].map do |k, v|
+          [dedasherize(k).to_sym, v]
+        end.to_h
+      end
+
+      def normalize_sort_params
+        return [] unless params[:sort]&.any?
+
+        halt 400, "Unsupported `sort' query parameter(s)" \
+          unless respond_to?(:sort)
+
+        params[:sort].map do |k|
+          dir = k.sub!(/^-/, '') ? :desc : :asc
+          [dedasherize(k).to_sym, dir]
+        end.to_h
+      end
+
+      def normalize_page_params
+        return {} unless params[:page]&.any?
+
+        halt 400, "Unsupported `page' query parameter(s)" \
+          unless respond_to?(:page)
+
+        h = params[:page].map do |k, v|
+          [dedasherize(k).to_sym, v]
+        end.to_h
+
+        return h if h.keys.to_set.subset?(settings._sinja.page_using.keys.to_set)
+
+        halt 400, "Invalid `page' query parameter(s)"
+      end
+
+      def filter_sort_page(collection, action)
+        unless params[:filter].empty?
+          halt 400, "Invalid `filter' query parameter(s)" \
+            unless settings.resource_config[action][:filter_by].empty? ||
+              params[:filter].keys.to_set.subset?(settings.resource_config[action][:filter_by])
+
+          collection = filter(collection, params[:filter])
+        end
+
+        unless params[:sort].empty?
+          halt 400, "Invalid `sort' query parameter(s)" \
+            unless settings.resource_config[action][:sort_by].empty? ||
+              params[:sort].keys.to_set.subset?(settings.resource_config[action][:sort_by])
+
+          collection = sort(collection, params[:sort])
         end
+
+        unless params[:page].empty?
+          collection, pagination = page(collection, params[:page])
+        end
+
+        collection = finalize(collection) if respond_to?(:finalize)
+
+        return collection, :pagination=>pagination
       end
 
       def halt(code, body=nil)
@@ -184,22 +279,10 @@ module Sinja
         @role ||= role
       end
 
-      def normalize_params!
-        # TODO: halt 400 if other params, or params not implemented?
-        {
-          :fields=>{}, # passthru
-          :include=>[], # passthru
-          :filter=>{},
-          :page=>{},
-          :sort=>''
-        }.each { |k, v| params[k] ||= v }
-      end
-
       def sideload?(resource_name, child)
         return unless sideloaded?
-        parent = env.fetch('sinja.passthru', 'unknown').to_sym
-        settings._sinja.resource_sideload[resource_name][child]&.
-          include?(parent) && can?(parent)
+        parent = env['sinja.passthru'].to_sym
+        settings.resource_config[child][:sideload_on]&.include?(parent) && can?(parent)
       end
 
       def sideloaded?
@@ -235,8 +318,6 @@ module Sinja
         )
       end
 
-      normalize_params!
-
       content_type :api_json
     end
 
@@ -265,4 +346,12 @@ module Sinja
       serialize_errors(&settings._sinja.error_logger)
     end
   end
+
+  def self.extended(base)
+    def base.route(*, **opts)
+      opts[:qparams] ||= []
+
+      super
+    end
+  end
 end

data/sinja.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Mike Pastore']
   spec.email         = ['mike@oobak.org']
 
-  spec.summary       = 'RESTful, JSON:API-compliant web services in Sinatra'
+  spec.summary       = 'RESTful, {json:api}-compliant web services in Sinatra'
   spec.homepage      = 'https://github.com/mwpastore/sinja'
   spec.license       = 'MIT'