praxis 2.0.pre.10 → 2.0.pre.11

data/lib/praxis/plugins/mapper_plugin.rb

@@ -1,10 +1,23 @@
 require 'singleton'
 
+require 'praxis/extensions/field_selection'
+
 module Praxis  
   module Plugins
     module MapperPlugin
       include Praxis::PluginConcern
 
+      # The Mapper plugin is an overarching set of things to include in your application
+      # when you want to use the rendring, field_selection, filtering (and potentially pagination) extensions
+      # To use the plugin, set it up like any other plugin by registering to the bootloader.
+      # Typically you'd do that in environment.rb, inside the `Praxis::Application.configure do |application|` block, by:
+      #   application.bootloader.use Praxis::Plugins::MapperPlugin
+      #
+      # The plugin accepts only 1 configuration option thus far, which you can set inside the same block as:
+      #   application.config.mapper.debug_queries = true
+      # when debug_queries is set to true, the system will output information about the expanded fields 
+      # and associations that the system ihas calculated necessary to pull from the DB, based on the requested
+      # API fields, API filters and `property` dependencies defined in the domain models (i.e., resources)
       class Plugin < Praxis::Plugin
         include Singleton
 
@@ -28,17 +41,11 @@ module Praxis
         extend ActiveSupport::Concern
 
         included do
+          include Praxis::Extensions::Rendering
           include Praxis::Extensions::FieldExpansion
         end
 
-        def set_selectors
-          return unless self.media_type.respond_to?(:domain_model) &&
-            self.media_type.domain_model < Praxis::Mapper::Resource
-
-          selector_generator.add(self.media_type.domain_model, self.expanded_fields)
-        end
-
-        def build_query(base_query, type: :active_record) # rubocop:disable Metrics/AbcSize
+        def build_query(base_query) # rubocop:disable Metrics/AbcSize
           domain_model = self.media_type&.domain_model
           raise "No domain model defined for #{self.name}. Cannot use the attribute filtering helpers without it" unless domain_model
           
@@ -47,18 +54,20 @@ module Praxis
           base_query = domain_model.craft_filter_query( base_query , filters: filters )
           # Handle field and nested field selection
           base_query = domain_model.craft_field_selection_query(base_query, selectors: selector_generator.selectors)
-          # handle pagination and ordering
-          base_query = _craft_pagination_query(query: base_query, type: type) if self.respond_to?(:_pagination)
+          # handle pagination and ordering if the pagination extention is included
+          base_query = domain_model.craft_pagination_query(base_query, pagination: _pagination)  if self.respond_to?(:_pagination)
 
           base_query
         end
 
         def selector_generator
-          @selector_generator ||= Praxis::Mapper::SelectorGenerator.new
-        end
+          return unless self.media_type.respond_to?(:domain_model) &&
+            self.media_type.domain_model < Praxis::Mapper::Resource
 
+          @selector_generator ||= \
+            Praxis::Mapper::SelectorGenerator.new.add(self.media_type.domain_model, self.expanded_fields)
+        end
       end
-
     end
   end
 end

data/lib/praxis/plugins/pagination_plugin.rb

@@ -1,14 +1,45 @@
 require 'singleton'
 require 'praxis/extensions/pagination'
 
-# Simple plugin concept
+# The PaginationPlugin can be configured to take advantage of adding pagination and sorting to
+# your DB queries.
+# When combined with the MapperPlugin, there is no extra configuration that needs to be done for
+# the system to appropriately identify the pagination and order parameters in the API, and translate
+# that in to the appropriate queries to fetch.
+# 
+# To use this plugin without the MapperPlugin (probably a rare case), one can apply the appropriate
+# clauses onto a query, by directly calling (in the controller) the `craft_pagination_query` method
+# of the domain_model associated to the controller's mediatype.
+# For example, here's how you can manually use this extension in a fictitious users index action:
+# def index
+#   base_query = User.all # Start by not excluding any user
+#   domain_model = self.media_type.domain_model
+#   objs = domain_model.craft_pagination_query(base_query, pagination: _pagination)
+#   display(objs)
+# end
+# 
+# This plugin accepts configuration about the default behavior of pagination.
+# Any of these configs can individually be overidden when defining each Pagination/Order parameters
+# in any of the Endpoint actions.
+#
 # Example configuration for this plugin
 # Praxis::Application.configure do |application|
 #   application.bootloader.use Praxis::Plugins::PaginationPlugin, {
+#     # The maximum number of results that a paginated response will ever allow
 #     max_items: 500,  # Unlimited by default,
+#     # The default page size to use when no `items` is specified
 #     default_page_size: 100,
-#     disallow_paging_by_default: false,
-#     # See all available options below
+#     # Disallows the use of the page type pagination mode when true (i.e., using 'page=' parameter)
+#     disallow_paging_by_default: true, # Default false
+#     # Disallows the use of the cursor type pagination mode when true (i.e., using 'by=' or 'from=' parameter)
+#     disallow_cursor_by_default: true, # Default false
+#     # The default mode params to use 
+#     paging_default_mode: {by: :uuid}, # Default {by: :uid}
+#     # Weather or not to enforce that all requested sort fields are part of the media_type attributes
+#     # when false (not enforced) only the first field would be checked
+#     sorting: {
+#       enforce_all_fields: false       # Default true 
+#     }
 #   end
 # end
 #
@@ -39,7 +70,6 @@ module Praxis
             attribute :paging_default_mode, Hash, default: Praxis::Types::PaginationParams.paging_default_mode
             attribute :disallow_paging_by_default, Attributor::Boolean, default: Praxis::Types::PaginationParams.disallow_paging_by_default
             attribute :disallow_cursor_by_default, Attributor::Boolean, default: Praxis::Types::PaginationParams.disallow_cursor_by_default
-            attribute :disallow_cursor_by_default, Attributor::Boolean, default: Praxis::Types::PaginationParams.disallow_cursor_by_default
             attribute :sorting do
               attribute :enforce_all_fields, Attributor::Boolean, default: Praxis::Types::OrderingParams.enforce_all_fields
             end

data/lib/praxis/tasks/api_docs.rb

@@ -21,7 +21,10 @@ namespace :praxis do
         trap('INT') { s.shutdown }
         s.start
       end
-      `open http://localhost:#{docs_port}/`
+      # If there is only 1 version we'll feature it and open the browser onto it
+      versions = Dir.children(root)
+      featured_version = (versions.size < 2) ? "#{versions.first}/" : ''
+      `open http://localhost:#{docs_port}/#{featured_version}`
       wb.join
     end
     desc "Generate and package all OpenApi Docs into a zip, ready for a Web server (like S3...) to present it"

data/lib/praxis/version.rb

@@ -1,3 +1,3 @@
 module Praxis
-  VERSION = '2.0.pre.10'
+  VERSION = '2.0.pre.11'
 end

data/spec/praxis/extensions/attribute_filtering/active_record_filter_query_builder_spec.rb

@@ -39,7 +39,7 @@ describe Praxis::Extensions::AttributeFiltering::ActiveRecordFilterQueryBuilder
       instance
       expect(instance.query).to eq(base_query)
       expect(instance.model).to eq(base_model)
-      expect(instance.attr_to_column).to eq(filters_map)
+      expect(instance.filters_map).to eq(filters_map)
     end
   end
   context 'generate' do
@@ -57,7 +57,20 @@ describe Praxis::Extensions::AttributeFiltering::ActiveRecordFilterQueryBuilder
         let(:filters_string) { 'category_uuid=deadbeef1' }
         it_behaves_like 'subject_equivalent_to', ActiveBook.where(category_uuid: 'deadbeef1')
       end
-      context 'that maps to a different name' do
+      context 'same-name filter mapping works' do
+        context 'even if ther was not a filter explicitly defined for it' do
+          let(:filters_string) { 'category_uuid=deadbeef1' }
+          it_behaves_like 'subject_equivalent_to', ActiveBook.where(category_uuid: 'deadbeef1')
+        end
+
+        context 'but if it is a field that does not exist in the model' do
+          let(:filters_string) { 'nonexisting=valuehere' }
+          it 'it blows up with the right error' do
+            expect{subject}.to raise_error(/Filtering by nonexisting is not allowed/)
+          end
+        end
+      end
+        context 'that maps to a different name' do
         let(:filters_string) { 'name=Book1'}
         it_behaves_like 'subject_equivalent_to', ActiveBook.where(simple_name: 'Book1')
       end

data/spec/praxis/extensions/field_selection/active_record_query_selector_spec.rb

@@ -29,7 +29,7 @@ describe Praxis::Extensions::FieldSelection::ActiveRecordQuerySelector do
       :id # We always load the primary keys
     ]
   end
-  let(:selector_node) { Praxis::Mapper::SelectorGenerator.new.add(ActiveBookResource,selector_fields)  }
+  let(:selector_node) { Praxis::Mapper::SelectorGenerator.new.add(ActiveBookResource,selector_fields).selectors  }
   let(:debug){ false }
 
   subject(:selector) {described_class.new(query: query, selectors: selector_node, debug: debug) }

data/spec/praxis/extensions/field_selection/sequel_query_selector_spec.rb

@@ -64,7 +64,7 @@ describe Praxis::Extensions::FieldSelection::SequelQuerySelector do
     ]
   end
 
-  let(:selector_node) { Praxis::Mapper::SelectorGenerator.new.add(SequelSimpleResource,selector_fields)  }
+  let(:selector_node) { Praxis::Mapper::SelectorGenerator.new.add(SequelSimpleResource,selector_fields).selectors  }
   subject {described_class.new(query: query, selectors: selector_node, debug: debug) }
 
   context 'generate' do

data/spec/praxis/extensions/support/spec_resources_active_model.rb

@@ -103,7 +103,7 @@ class ActiveBookResource < ActiveBaseResource
 
   filters_mapping(
     id: :id,
-    category_uuid: :category_uuid,
+    # category_uuid: :category_uuid  #NOTE: we do not need to define same-name-mappings if they exist
     'fake_nested.name': 'simple_name',
     'name': 'simple_name',
     'name_is_not': lambda do |spec| # Silly way to use a proc, but good enough for testing

data/spec/praxis/mapper/selector_generator_spec.rb

@@ -8,7 +8,7 @@ describe Praxis::Mapper::SelectorGenerator do
   context '#add' do
     let(:resource) { SimpleResource }
     shared_examples 'a proper selector' do
-      it { expect(generator.add(resource, fields).dump).to be_deep_equal selectors }
+      it { expect(generator.add(resource, fields).selectors.dump).to be_deep_equal selectors }
     end
     
     context 'basic combos' do

data/tasks/thor/example.rb

@@ -33,16 +33,22 @@ module PraxisGen
       puts
       puts "  cd #{app_name}"
       puts "  bundle"
-      puts "  bundle exec rake db:create db:migrate db:seed  # To create/migrate/seed the dev DB"
-      puts "  bundle exec rackup                             # To start the web server"
+      puts "  bundle exec rake db:recreate   # To create/migrate/seed the dev DB"
+      puts "  bundle exec rackup             # To start the web server"
       puts  
       puts "From another terminal/app, use curl (or your favorite HTTP client) to retrieve data from the API"
       puts "  For example: "
-      puts "  Get all users without filters or limit, and display only uid, and last_name fields"
-      puts "  curl -H 'X-Api-Version: 1' http://localhost:9292/users?fields=uid,last_name"
+      puts "  Get all users without filters or limit, and display only id, and first_name fields"
+      puts "  curl -G -H 'X-Api-Version: 1' http://localhost:9292/users \\"
+      puts "    --data-urlencode \"fields=id,first_name\""
       puts
-      puts "  Get the last 5 users, ordered by last_name (descending),  and display only uid, and last_name fields"
-      puts "  curl -H 'X-Api-Version: 1' 'http://localhost:9292/users?fields=uid,last_name&order=-last_name&pagination=by%3Dlast_name,items%3D5' "
+      puts "  Get the last 5 users, with last_names starting with \"L\" ordered by first_name (descending)"
+      puts "  and display only id, first_name, last_name, and email fields"
+      puts "  curl -G -H 'X-Api-Version: 1' http://localhost:9292/users \\"
+      puts "    --data-urlencode \"filters=last_name=L*\" \\"
+      puts "    --data-urlencode \"pagination=by=first_name,items=5\" \\"
+      puts "    --data-urlencode \"order=-first_name\" \\"      
+      puts "    --data-urlencode \"fields=id,first_name,last_name,email\""
       puts "  (Note: To list all routes use: bundle exec rake praxis:routes)"
       puts
       nil

data/tasks/thor/model.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module PraxisGen
+  class Model < Thor
+    require 'active_support/inflector'
+    include Thor::Actions
+    
+    def self.source_root
+      File.dirname(__FILE__) + "/templates/generator/scaffold"
+    end
+
+    desc "gmodel", "Generates a skeleton model file under app/models for ActiveRecord or Sequel."
+    argument :model_name, required: true
+    option :orm, required: false, default: 'activerecord', enum: ['activerecord','sequel']
+    def g
+      #self.class.check_name(model_name)
+      template_file = \
+        if options[:orm] == 'activerecord'
+          'models/active_record.rb'
+        else
+          'models/sequel.rb'
+        end
+      puts "Generating Model for #{model_name}"        
+      template template_file, "app/models/#{model_name}.rb"
+      nil
+    end
+    # Helper functions (which are available in the ERB contexts)
+    no_commands do
+      def model_class
+        model_name.camelize
+      end
+    end
+
+    # TODO: do we want the argument to be camelcase? or snake case?
+    def self.check_name(name)
+      sanitized = name.downcase.gsub(/[^a-z0-9_]/, '')
+      raise "Please use only downcase letters, numbers and underscores for the model" unless sanitized == name
+    end
+  end
+end

data/tasks/thor/scaffold.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module PraxisGen
+  class Scaffold < Thor
+    require 'active_support/inflector'
+    include Thor::Actions
+    
+    attr_reader :actions_hash
+
+    def self.source_root
+      File.dirname(__FILE__) + "/templates/generator/scaffold"
+    end
+
+    desc "g","Generates an API design and implementation scaffold for managing a collection of <collection_name>"
+    argument :collection_name, required: true
+    option :version, required: false, default: '1',
+    desc: 'Version string for the API endpoint. This also dictates the directory structure (i.e., v1/endpoints/...))'
+    option :design, type: :boolean, default: true,
+        desc: 'Include the Endpoint and MediaType files for the collection'
+    option :implementation, type: :boolean, default: true,
+        desc: 'Include the Controller and (possibly the) Resource files for the collection (see --no-resource)'
+    option :resource, type: :boolean, default: true,
+        desc: 'Disable (or enable) the creation of the Resource files when generating implementation'
+    option :model, type: :string, enum: ['activerecord','sequel'],
+        desc: 'It also generates a model for the given ORM. An empty --model flag will default to activerecord'
+    option :actions, type: :string, default: 'crud', enum: ['cr','cru','crud','u','ud','d'],
+        desc: 'Specifies the actions to generate for the API. cr=create, u=update, d=delete. Index and show actions are always generated'
+    def g
+      self.class.check_name(collection_name)
+      @actions_hash = self.class.compose_actions_hash(options[:actions])
+      env_rb = Pathname.new(destination_root)+Pathname.new("config/environment.rb")
+      @pagination_plugin_found = File.open(env_rb).grep(/Praxis::Plugins::PaginationPlugin.*/).reject{|l| l.strip[0] == '#'}.present?
+      if options[:design]
+        say_status 'Design', "Generating scaffold for #{plural_class}", :blue
+        template 'design/media_types/item.rb', "design/#{version_dir}/media_types/#{collection_name.singularize}.rb"
+        template 'design/endpoints/collection.rb', "design/#{version_dir}/endpoints/#{collection_name}.rb"
+      end
+      if options[:implementation]
+        say_status 'Implement', "Generating scaffold for #{plural_class}", :blue
+        if options[:resource]
+          base_resource = Pathname.new(destination_root)+Pathname.new("app/#{version_dir}/resources/base.rb")
+          unless base_resource.exist?
+            # Copy an appropriate base resource for the version (resources within same version must share same base)
+            say_status "NOTE:", 
+              "Creating a base resource file for resources to inherit from (at 'app/#{version_dir}/resources/base.rb')", 
+              :yellow
+            say_status "", 
+              "If you had already other resources in the app, change them to derive from this Base"
+            template 'implementation/resources/base.rb', "app/#{version_dir}/resources/base.rb"
+          end
+          template 'implementation/resources/item.rb', "app/#{version_dir}/resources/#{collection_name.singularize}.rb"
+        end
+        template 'implementation/controllers/collection.rb', "app/#{version_dir}/controllers/#{collection_name}.rb"
+      end
+      nil
+    end
+
+    # Helper functions (which are available in the ERB contexts)
+    no_commands do
+      def plural_class
+        collection_name.camelize
+      end
+    
+      def singular_class
+        collection_name.singularize.camelize
+      end
+      
+      def version
+        options[:version]
+      end
+
+      def version_module
+        "V#{version}"
+      end
+    
+      def version_dir
+        version_module.camelize(:lower)
+      end
+
+      def action_enabled?(action)
+        @actions_hash[action.to_sym]
+      end
+
+      def pagination_enabled?
+        @pagination_plugin_found
+      end
+    end
+
+    def self.compose_actions_hash(actions_opt)
+      required = { index: true, show: true }
+      case actions_opt
+      when nil
+        required
+      when 'cr'
+        required.merge(create: true)
+      when 'cru'
+        required.merge(create: true, update: true)
+      when 'crud'
+        required.merge(create: true, update: true, delete: true)
+      when 'u'
+        required.merge(update: true)
+      when 'ud'
+        required.merge(update: true, delete: true)
+      when 'd'
+        required.merge(delete: true)
+      else
+        raise "actions option does not support the string #{actions_opt}"
+      end
+    end
+
+    def self.check_name(name)
+      sanitized = name.downcase.gsub(/[^a-z0-9_]/, '')
+      # TODO: bail or support CamelCase collections (for now only snake case)
+      raise "Please use only downcase letters, numbers and underscores for the collection" unless sanitized == name
+    end
+  end
+end

data/tasks/thor/templates/generator/empty_app/config/environment.rb

@@ -18,6 +18,7 @@ Praxis::Application.configure do |application|
   #     map :models, 'models/**/*'
   #     map :responses, '**/responses/**/*'
   #     map :exceptions, '**/exceptions/**/*'
+  #     map :concerns, '**/concerns/**/*'
   #     map :resources, '**/resources/**/*'
   #     map :controllers, '**/controllers/**/*'
   #   end

data/tasks/thor/templates/generator/example_app/Rakefile

@@ -32,10 +32,17 @@ namespace :db do
     puts "Database migrated."
   end
 
+  desc 'Fully receate, migrate and seed the DB'
+  task :recreate do
+    Rake::Task['db:drop'].invoke rescue nil
+    Rake::Task['db:create'].invoke
+    Rake::Task['db:migrate'].invoke
+    Rake::Task['db:seed'].invoke
+  end
+
   desc 'seed with example data'
   task seed: 'praxis:environment' do
-    require_relative 'spec/helpers/database_helper'
-    DatabaseHelper.seed!
+    require_relative 'db/seeds.rb'
   end
 
   desc 'drops current database'

data/tasks/thor/templates/generator/example_app/app/v1/concerns/controller_base.rb

@@ -0,0 +1,24 @@
+module V1
+  module Concerns
+    module ControllerBase
+      extend ActiveSupport::Concern
+      # Controller concen that wraps an API with a transaction, and automatically rolls it back
+      # for non-2xx (or 3xx) responses
+      included do
+        around :action do |controller, callee|
+          begin
+            # TODO: Support Sequel as well
+            ActiveRecord::Base.transaction do
+              callee.call
+              res = controller.response
+              # Force a rollback for non 2xx or 3xx responses
+              raise ActiveRecord::Rollback unless res.status >= 200 && res.status < 400
+            end
+          rescue ActiveRecord::Rollback
+            # No need to do anything, let the responses flow normally
+          end
+        end
+      end
+    end
+  end
+end