praxis 2.0.pre.9 → 2.0.pre.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2a11ec74ee5a52178fe7aae10c503eb61407c739c40c262386e855e1abd40ee
-  data.tar.gz: 71b397991329ea9726b366938de75768bedf812324e4b2d768ac7dae3f25e33e
+  metadata.gz: dd76d8bd13954d5607d009ee37ff7fc1a8ef8a2c6c8c87544dddaee332d984bf
+  data.tar.gz: 719bffed7ea98fe42d7c620cd4377c4201c9d23e49a9777e981647d671b39ffd
 SHA512:
-  metadata.gz: 21fbd6dbb60486cea3ec5cdd18a1b4178873ff6343182f2b44a11d71cbdac1664bec005760b77511de342fc92a63abe7864c85f10ffc1c3953734a1069f2520d
-  data.tar.gz: 7c0f8a5c417ad9ecd76fd67e08f1f219cc274c3bbd30ec88d7ae669e0a10d4ec5585c365ad7c3a38163b3d4f367897e7129bbbda66664947e82c37dc90213f08
+  metadata.gz: 18e87e4563faa7a1ffbba174634f1ebabe57320b8324e4ac23a711f5785906482412db711c83308ff87264d48cc496f8bd118b5a5ac77f1d6bd8f09e543f90ed
+  data.tar.gz: 9da869a6acecf7c04273ef7dc0519be0cf8b3d00c29df16c851df04f5ea52d7cf4d62123e25533b8887c0a30b940155abfbd812f4fe2b347d1139df91e3e124f

data/.gitignore

@@ -14,3 +14,5 @@ lib/api_browser/node_modules/
 lib/api_browser/app/bower_components/
 lib/api_browser/.tmp/
 lib/api_browser/bower.json
+
+development.sqlite3

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## next
 
+- Simple, but pervasive breaking change: Rename `ResourceDefinition` to `EndpointDefinition` (but same functionality).
+- Remove all deprecated features (and raise error describing it's not supported yet)
+- Remove `Links` and `LinkBuilder`. Those seem unnecessary from a Framework point of view as they aren't clear most
+applications would benefit from it. Applications can choose to add that functionality on their own if so desire.
+- Rebuilt app generators: for new empty app, and example app.
+- Updated default layout to match new naming structure and more concepts commonly necessary for normal applications.
+- Completely removed the native Praxis API documentation browser in lieu of OpenAPI 3.x standards, and reDoc.
+- Remove dependency from praxis-blueprints, as simplified subset of its code has now been included in this repo:
+  - no more views for mediatypes. A default fieldset will be automatically defined which will be the default set of attributes to render with. This default fieldset will only contain simple direct attributes (i.e., non blueprint/mediatype attributes). One can override the default by explicitly defining one using the `default_fieldset` DSL, similar to how views were defined before.
+- Folded the pagination/ordering extensions to activate within the `build_query` method of the mapper plugin extension. This way all the field selection, filtering and pagination/ordering will kick in automatically when that plugin is included.
+
 ## 2.0.pre.9
 
 - Refined OpenAPI doc generation to output only non-null attributes in the InfoObject.

data/TODO.md

@@ -3,17 +3,14 @@
 ## Things to delete
 
  * views (just use a sensible default view of just simple types?)
- * make handlers hang from a singleton (and possibly get rid of xml encoding as well)
- * remove app instances?
  * remove collection summary things...
  * FieldResolver?? and that conditional dependency thing...?
  * simplify or change examples? ...maybe get rid of randexp.
- * get rid of doc browser in lieu to OAPI and redoc
- * traits? ... we still use them...
  * NOTE: make sure the types we use only expose the json-schema types...no longer things like Hash/Struct/Symbol ...(that might be good only for coding/implementation, not for documentation)
  * Plugins? ... maybe leave them out for the moment?
  * change errors to be machine readable
  * change naming of resource definition to endpoint definition
+ * get rid of deprecations
  
 
  ## DONE

data/bin/praxis

@@ -13,7 +13,8 @@ if ["routes","docs","console"].include? ARGV[0]
   require 'rake'
   require 'praxis'
   require 'praxis/tasks'
-  
+  load 'Rakefile' # Ensure that we read the App's Rakefile, to pickup any definitions etc.
+
   case ARGV[0]
     when "routes"
       Rake::Task['praxis:routes'].invoke(ARGV[1])
@@ -24,9 +25,8 @@ if ["routes","docs","console"].include? ARGV[0]
       when 'generate'
         'praxis:docs:generate'
       when 'package'
-        'praxis:docs:build'        
+        'praxis:docs:package'        
       end
-#      task_name = ARGV[1] == 'browser' ? 'praxis:doc_browser' : 'praxis:api_docs' 
       Rake::Task[task_name].invoke
     when "console"
       Rake::Task['praxis:console'].invoke
@@ -71,19 +71,17 @@ class PraxisGenerator < Thor
 
   desc_for "new APP_NAME", ::PraxisGen::App, :new
   def new(app_name)
-    ::PraxisGen::App.start(['new' , app_name])
+    gen = ::PraxisGen::App.new([app_name])
+    gen.destination_root = app_name
+    gen.invoke_all
   end
 
-  desc_for "example APP_NAME", ::PraxisGen::Example, :new
+  desc_for "example APP_NAME", ::PraxisGen::Example, :example
   def example(app_name)
-    ::PraxisGen::Example.start(['new', app_name])
-  end
-  
-  desc_for "generate APP_NAME", ::PraxisGen::Example, :new, "DEPRECATED!: "
-  def generate(app_name)
-    warn "This is a deprecated method.\nTo generate a hello world example, please use:\n  praxis example #{app_name} "
-  end
-  
+    gen = ::PraxisGen::Example.new([app_name])
+    gen.destination_root = app_name
+    gen.invoke(:example)
+  end  
 end
     
 PraxisGenerator.start(ARGV)

data/lib/praxis.rb

@@ -1,6 +1,5 @@
 require 'rack'
 require 'attributor'
-require 'praxis-blueprints'
 
 require 'active_support/concern'
 require 'praxis/request_superclassing'
@@ -33,7 +32,8 @@ module Praxis
   autoload :Plugin, 'praxis/plugin'
   autoload :PluginConcern, 'praxis/plugin_concern'
   autoload :Request, 'praxis/request'
-  autoload :ResourceDefinition, 'praxis/resource_definition'
+  autoload :ResourceDefinition, 'praxis/resource_definition' # Deprecated: this is to support an easier transition
+  autoload :EndpointDefinition, 'praxis/endpoint_definition'
   autoload :Response, 'praxis/response'
   autoload :ResponseDefinition, 'praxis/response_definition'
   autoload :ResponseTemplate, 'praxis/response_template'
@@ -43,6 +43,14 @@ module Praxis
   autoload :SimpleMediaType, 'praxis/simple_media_type'
   autoload :Stage, 'praxis/stage'
   autoload :Trait, 'praxis/trait'
+  autoload :ConfigHash, 'praxis/config_hash'
+  autoload :Finalizable, 'praxis/finalizable'
+
+  # Sort of part of the old Blueprints gem...but they're really not scoped...
+  autoload :Blueprint, 'praxis/blueprint'
+  autoload :FieldExpander, 'praxis/field_expander'
+  autoload :Renderer, 'praxis/renderer'
+  
 
   autoload :Notifications, 'praxis/notifications'
   autoload :MiddlewareApp, 'praxis/middleware_app'
@@ -62,7 +70,6 @@ module Praxis
 
   autoload :MediaType, 'praxis/media_type'
   autoload :MediaTypeIdentifier, 'praxis/media_type_identifier'
-  autoload :Multipart, 'praxis/types/multipart'
   autoload :Collection, 'praxis/collection'
 
   autoload :MultipartParser, 'praxis/multipart/parser'

data/lib/praxis/action_definition.rb

@@ -11,7 +11,7 @@ module Praxis
   class ActionDefinition
 
     attr_reader :name
-    attr_reader :resource_definition
+    attr_reader :endpoint_definition
     attr_reader :api_definition
     attr_reader :route
     attr_reader :responses
@@ -31,33 +31,33 @@ module Praxis
       self.doc_decorations << callback
     end
 
-    def initialize(name, resource_definition, **opts, &block)
+    def initialize(name, endpoint_definition, **opts, &block)
       @name = name
-      @resource_definition = resource_definition
+      @endpoint_definition = endpoint_definition
       @responses = Hash.new
       @metadata = Hash.new
       @route = nil
       @traits = []
 
-      if (media_type = resource_definition.media_type)
+      if (media_type = endpoint_definition.media_type)
         if media_type.kind_of?(Class) && media_type < Praxis::Types::MediaTypeCommon
           @reference_media_type = media_type
         end
       end
 
-      version = resource_definition.version
-      api_info = ApiDefinition.instance.info(resource_definition.version)
+      version = endpoint_definition.version
+      api_info = ApiDefinition.instance.info(endpoint_definition.version)
 
-      route_base = "#{api_info.base_path}#{resource_definition.version_prefix}"
-      prefix = Array(resource_definition.routing_prefix)
+      route_base = "#{api_info.base_path}#{endpoint_definition.version_prefix}"
+      prefix = Array(endpoint_definition.routing_prefix)
 
       @routing_config = RoutingConfig.new(version: version, base: route_base, prefix: prefix)
 
-      resource_definition.traits.each do |trait|
+      endpoint_definition.traits.each do |trait|
         self.trait(trait)
       end
 
-      resource_definition.action_defaults.apply!(self)
+      endpoint_definition.action_defaults.apply!(self)
 
       self.instance_eval(&block) if block_given?
     end
@@ -71,7 +71,6 @@ module Praxis
       trait.apply!(self)
       traits << trait_name
     end
-    alias_method :use, :trait
 
     def update_attribute(attribute, options, block)
       attribute.options.merge!(options)
@@ -246,7 +245,7 @@ module Praxis
     def params_description(example:)
       route_params = []
       if route.nil?
-        warn "Warning: No route defined for #{resource_definition.name}##{name}."
+        warn "Warning: No route defined for #{endpoint_definition.name}##{name}."
       else
         route_params = route.path.
           named_captures.
@@ -343,6 +342,9 @@ module Praxis
       metadata[:doc_visibility] = :none
     end
 
-
+    # [DEPRECATED] - Warn of the change of method name for the transition 
+    def resource_definition
+      raise "Praxis::ActionDefinition does not use `resource_definition` any longer. Use `endpoint_definition` instead."
+    end
   end
 end

data/lib/praxis/action_definition/headers_dsl_compiler.rb

@@ -27,13 +27,6 @@ module Praxis
         end
         key name , String, **options
       end
-
-      # Override the attribute to really call "key" in the hash (for temporary backwards compat)      
-      def attribute(name, attr_type=nil, **opts, &block)
-        warn "[DEPRECATION] `attribute` is deprecated when defining headers.  Please use `key` instead."
-        key(name, attr_type, **opts, &block)
-      end
-
     end
   end
 end

data/lib/praxis/api_general_info.rb

@@ -122,7 +122,7 @@ module Praxis
         global_path = @global_info.base_path
         if version_with == :path
           global_pattern = Mustermann.new(global_path)
-          global_path = global_pattern.expand(Request::API_VERSION_PARAM_NAME => self.version)
+          global_path = global_pattern.expand(Request::API_VERSION_PARAM_NAME => self.version.to_s)
         end
 
         version_path = @data.fetch(:base_path,'')

data/lib/praxis/application.rb

@@ -8,7 +8,7 @@ module Praxis
 
     attr_reader :router
     attr_reader :controllers
-    attr_reader :resource_definitions
+    attr_reader :endpoint_definitions
     attr_reader :app
     attr_reader :builder
 
@@ -32,7 +32,7 @@ module Praxis
 
     def initialize
       @controllers = Set.new
-      @resource_definitions = Set.new
+      @endpoint_definitions = Set.new
 
       @error_handler = ErrorHandler.new
       @validation_handler = ValidationHandler.new
@@ -123,5 +123,9 @@ module Praxis
       @config.set(config)
     end
 
+    # [DEPRECATED] - Warn of the change of method name for the transition 
+    def resource_definitions
+      raise "Praxis::Application.instance does not use `resource_definitions` any longer. Use `endpoint_definitions` instead."
+    end
   end
 end

data/lib/praxis/blueprint.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+module Praxis
+  class Blueprint    
+    
+    # Simple helper class that can parse the `attribute :foobar` dsl into
+    # an equivalent structure hash. Example:
+    # do
+    #   attribute :one
+    #   attribute :complex do
+    #     attribute :sub1
+    #   end
+    #  end
+    # is parsed as: { one: true, complex: { sub1: true} }
+    class FieldsetParser
+      def initialize( &block)
+        @hash = nil
+        @block = block
+      end
+    
+      def attribute(name, **args, &block)
+        raise "Default fieldset definitions do not accept parameters (got: #{args})" \
+              "If you're upgrading from a previous version of Praxis and still using the view :default " \
+              "block syntax, make sure you don't use any view: X parameters when you define the attributes " \
+              "(expand them explicitly if you want deeper structure)" \
+              "The offending view with parameters is defined in:\n#{Kernel.caller.first}" unless args.empty?
+        @hash[name] = block_given? ? FieldsetParser.new(&block).fieldset : true
+      end
+
+      def fieldset
+        return @hash if @hash
+        # Lazy eval
+        @hash = {}
+        instance_eval(&@block)
+        @hash
+      end
+    end
+    include Attributor::Type
+    include Attributor::Dumpable
+
+    extend Finalizable
+
+    @@caching_enabled = false
+
+    attr_reader :validating
+    attr_accessor :object
+
+    class << self
+      attr_reader :attribute
+      attr_reader :options
+      attr_accessor :reference
+    end
+
+    def self.inherited(klass)
+      super
+
+      klass.instance_eval do
+        @options = {}
+        @domain_model = Object
+        @default_fieldset = {}
+      end
+    end
+
+    # Override default new behavior to support memoized creation through an IdentityMap
+    def self.new(object)
+      # TODO: do we want to allow the identity map thing in the object?...maybe not.
+      if @@caching_enabled
+        return self.cache[object] ||= begin
+          blueprint = self.allocate
+          blueprint.send(:initialize, object)
+          blueprint
+        end
+      end
+
+      blueprint = self.allocate
+      blueprint.send(:initialize, object)
+      blueprint
+    end
+
+    def self.family
+      'hash'
+    end
+
+    def self.attributes(opts = {}, &block)
+      if block_given?
+        raise 'Redefining Blueprint attributes is not currently supported' if self.const_defined?(:Struct, false)
+
+        if opts.key?(:reference) && opts[:reference] != self.reference
+          raise "Reference mismatch in #{self.inspect}. Given :reference option #{opts[:reference].inspect}, while using #{self.reference.inspect}"
+        elsif self.reference
+          opts[:reference] = self.reference # pass the reference Class down
+        else
+          opts[:reference] = self
+        end
+
+        @options.merge!(opts)
+        @block = block
+
+        return @attribute
+      end
+
+      raise "@attribute not defined yet for #{self.name}" unless @attribute
+
+      @attribute.attributes
+    end
+
+    def self.domain_model(klass = nil)
+      return @domain_model if klass.nil?
+      @domain_model = klass
+    end
+
+    def self.check_option!(name, value)
+      Attributor::Struct.check_option!(name, value)
+    end
+
+    def self.load(value, context = Attributor::DEFAULT_ROOT_CONTEXT, **options)
+      case value
+      when self
+        value
+      when nil, Hash, String
+        if (value = self.attribute.load(value, context, **options))
+          self.new(value)
+        end
+      else
+        if value.is_a?(self.domain_model) || value.is_a?(self::Struct)
+          # Wrap the value directly
+          self.new(value)
+        else
+          # Wrap the object inside the domain_model
+          self.new(domain_model.new(value))
+        end
+      end
+    end
+
+    class << self
+      alias from load
+    end
+
+    def self.caching_enabled?
+      @@caching_enabled
+    end
+
+    def self.caching_enabled=(caching_enabled)
+      @@caching_enabled = caching_enabled
+    end
+
+    # Fetch current blueprint cache, scoped by this class
+    def self.cache
+      Thread.current[:praxis_blueprints_cache][self]
+    end
+
+    def self.cache=(cache)
+      Thread.current[:praxis_blueprints_cache] = cache
+    end
+
+    def self.valid_type?(value)
+      value.is_a?(self) || value.is_a?(self.attribute.type)
+    end
+
+    def self.example(context = nil, **values)
+      context = case context
+                when nil
+                  ["#{self.name}-#{values.object_id}"]
+                when ::String
+                  [context]
+                else
+                  context
+                end
+
+      self.new(self.attribute.example(context, values: values))
+    end
+
+    def self.validate(value, context = Attributor::DEFAULT_ROOT_CONTEXT, _attribute = nil)
+      raise ArgumentError, "Invalid context received (nil) while validating value of type #{self.name}" if context.nil?
+      context = [context] if context.is_a? ::String
+
+      unless value.is_a?(self)
+        raise ArgumentError, "Error validating #{Attributor.humanize_context(context)} as #{self.name} for an object of type #{value.class.name}."
+      end
+
+      value.validate(context)
+    end
+
+    def self.default_fieldset(&block)
+      return @default_fieldset unless block_given?
+
+      @block_for_default_fieldset = block
+    end
+
+    def self.view(name, **options, &block)
+      unless name == :default
+        raise "[ERROR] Views are no longer supported. Please use fully expanded fields when rendering.\n" \
+              "NOTE that defining the :default view is deprecated, but still temporarily allowed, as an alias to define the default_fieldset.\n" \
+              "A view for name #{name} is attempted to be defined in:\n#{Kernel.caller.first}"
+      end
+      raise "Cannot define the default fieldset through the default view unless a block is passed" unless block_given?
+      puts "[DEPRECATED] default fieldsets should be defined through `default_fieldset` instead of using the view :default block.\n" \
+           "A default view is attempted to be defined in:\n#{Kernel.caller.first}"
+      default_fieldset(&block)
+    end
+
+    def self.parse_default_fieldset(block)
+      @default_fieldset = FieldsetParser.new(&block).fieldset
+      @block_for_default_fieldset = nil
+    end
+
+    # renders using the implicit default fieldset
+    def self.dump(object, context: Attributor::DEFAULT_ROOT_CONTEXT, **opts)
+      object = self.load(object, context, **opts)
+      return nil if object.nil?
+
+      object.render(context: context, **opts)
+    end
+
+    class << self
+      alias render dump
+    end
+
+    # Internal finalize! logic
+    def self._finalize!
+      if @block
+        self.define_attribute!
+        self.define_readers!
+        # Don't blindly override a the default fieldset if the MediaType wants to define it on its own
+        if @block_for_default_fieldset
+          parse_default_fieldset(@block_for_default_fieldset) 
+        else
+          self.generate_default_fieldset!
+        end
+        self.resolve_domain_model!
+      end
+      super
+    end
+
+    def self.resolve_domain_model!
+      return unless self.domain_model.is_a?(String)
+
+      @domain_model = self.domain_model.constantize
+    end
+
+    def self.define_attribute!
+      @attribute = Attributor::Attribute.new(Attributor::Struct, @options, &@block)
+      @block = nil
+      @attribute.type.anonymous_type true
+      self.const_set(:Struct, @attribute.type)
+    end
+
+    def self.define_readers!
+      self.attributes.each do |name, _attribute|
+        name = name.to_sym
+
+        # Don't redefine existing methods
+        next if self.instance_methods.include? name
+
+        define_reader! name
+      end
+    end
+
+    def self.define_reader!(name)
+      attribute = self.attributes[name]
+      # TODO: profile and optimize
+      # because we use the attribute in the reader,
+      # it's likely faster to use define_method here
+      # than module_eval, but we should make sure.
+      define_method(name) do
+        value = @object.__send__(name)
+        return value if value.nil? || value.is_a?(attribute.type)
+        attribute.load(value)
+      end
+    end
+
+    def self.generate_default_fieldset!
+      attributes = self.attributes
+
+      @default_fieldset = {}
+      attributes.each do |name, attr|
+        the_type = (attr.type < Attributor::Collection) ? attr.type.member_type : attr.type
+        next if the_type < Blueprint
+        # Note: we won't try to expand fields here, as we want to be lazy (and we're expanding)
+        # every time a request comes in anyway. This could be an optimization we do at some point
+        # or we can 'memoize it' to avoid trying to expand it over an over...
+        @default_fieldset[name] = true
+      end
+    end
+    
+    def initialize(object)
+      @object = object
+      @validating = false
+    end
+
+    # By default we'll use the object identity, to avoid rendering the same object twice
+    # Override, if there is a better way cache things up
+    def _cache_key
+      self.object
+    end
+
+    # Render the wrapped data with the given fields (or using the default fieldset otherwise)
+    def render(fields: self.class.default_fieldset, context: Attributor::DEFAULT_ROOT_CONTEXT, renderer: Renderer.new, **opts)
+
+      # Accept a simple array of fields, and transform it to a 1-level hash with true values
+      if fields.is_a? Array
+        fields = fields.each_with_object({}) { |field, hash| hash[field] = true }
+      end
+
+      expanded  = Praxis::FieldExpander.new.expand(self, fields)
+      renderer.render(self, fields, context: context)
+    end
+
+    alias dump render
+
+    def to_h
+      Attributor.recursive_to_h(@object)
+    end
+
+    def validate(context = Attributor::DEFAULT_ROOT_CONTEXT)
+      raise ArgumentError, "Invalid context received (nil) while validating value of type #{self.name}" if context.nil?
+      context = [context] if context.is_a? ::String
+      keys_with_values = []
+
+      raise 'validation conflict' if @validating
+      @validating = true
+
+      errors = []
+      self.class.attributes.each do |sub_attribute_name, sub_attribute|
+        sub_context = self.class.generate_subcontext(context, sub_attribute_name)
+        value = self.send(sub_attribute_name)
+        keys_with_values << sub_attribute_name unless value.nil?
+
+        if value.respond_to?(:validating) # really, it's a thing with sub-attributes
+          next if value.validating
+        end
+        errors.concat(sub_attribute.validate(value, sub_context))
+      end
+      self.class.attribute.type.requirements.each do |req|
+        validation_errors = req.validate(keys_with_values, context)
+        errors.concat(validation_errors) unless validation_errors.empty?
+      end
+      errors
+    ensure
+      @validating = false
+    end
+
+    # generic semi-private getter used by Renderer
+    def _get_attr(name)
+      self.send(name)
+    end
+
+    # Delegates the json-schema methods to the underlying attribute/member_type
+    def self.as_json_schema(**args)
+      @attribute.type.as_json_schema(args)
+    end
+    
+    def self.json_schema_type
+      @attribute.type.json_schema_type
+    end
+  end
+end