grape 0.1.1 → 2.4.0

data/lib/grape/api.rb

@@ -1,214 +1,178 @@
-require 'rack/mount'
-require 'rack/auth/basic'
-require 'logger'
+# frozen_string_literal: true
 
 module Grape
-  # The API class is the primary entry point for
-  # creating Grape APIs. Users should subclass this
-  # class in order to build an API.
+  # The API class is the primary entry point for creating Grape APIs. Users
+  # should subclass this class in order to build an API.
   class API
+    # Class methods that we want to call on the API rather than on the API object
+    NON_OVERRIDABLE = %i[call call! configuration compile! inherited recognize_path].freeze
+
+    class Boolean
+      def self.build(val)
+        return nil if val != true && val != false
+
+        new
+      end
+    end
+
+    class Instance
+      Boolean = Grape::API::Boolean
+    end
+
     class << self
-      attr_reader :route_set
-      
-      def logger
-        @logger ||= Logger.new($STDOUT)
-      end
-      
-      def reset!
-        @settings = [{}]
-        @route_set = Rack::Mount::RouteSet.new
-        @prototype = nil
-      end
-      
-      def call(env)
-        logger.info "#{env['REQUEST_METHOD']} #{env['PATH_INFO']}"
-        route_set.freeze.call(env)
-      end
-      
-      # Settings are a stack, so when we
-      # want to access them they are merged
-      # in the order pushed.
-      def settings
-        @settings.inject({}){|f,h| f.merge!(h); f}
-      end
-      
-      def settings_stack
-        @settings
-      end
-      
-      # Set a configuration value for this
-      # namespace.
-      #
-      # @param key [Symbol] The key of the configuration variable.
-      # @param value [Object] The value to which to set the configuration variable.
-      def set(key, value)
-        @settings.last[key.to_sym] = value
-      end
-      
-      # Define a root prefix for your entire
-      # API. For instance, if you had an api
-      # that you wanted to be namespaced at
-      # `/api/` you would do this:
-      # 
-      #   prefix '/api'
-      def prefix(prefix = nil)
-        prefix ? set(:root_prefix, prefix) : settings[:root_prefix]
-      end
-      
-      def version(*new_versions, &block)
-        new_versions.any? ? nest(block){ set(:version, new_versions) } : settings[:version]
-      end
-      
-      # Specify the default format for the API's 
-      # serializers. Currently only `:json` is
-      # supported.
-      def default_format(new_format = nil)
-        new_format ? set(:default_format, new_format.to_sym) : settings[:default_format]
-      end
-
-      # Add helper methods that will be accessible from any
-      # endpoint within this namespace (and child namespaces).
-      #
-      #    class ExampleAPI
-      #      helpers do
-      #        def current_user
-      #          User.find_by_id(params[:token])
-      #        end
-      #      end
-      #    end
-      def helpers(&block)
+      extend Forwardable
+      attr_accessor :base_instance, :instances
+
+      delegate_missing_to :base_instance
+      def_delegators :base_instance, :new, :configuration
+
+      # This is the interface point between Rack and Grape; it accepts a request
+      # from Rack and ultimately returns an array of three values: the status,
+      # the headers, and the body. See [the rack specification]
+      # (http://www.rubydoc.info/github/rack/rack/master/file/SPEC) for more.
+      # NOTE: This will only be called on an API directly mounted on RACK
+      def_delegators :instance_for_rack, :call, :compile!
+
+      # When inherited, will create a list of all instances (times the API was mounted)
+      # It will listen to the setup required to mount that endpoint, and replicate it on any new instance
+      def inherited(api)
+        super
+
+        api.initial_setup(self == Grape::API ? Grape::API::Instance : @base_instance)
+        api.override_all_methods!
+      end
+
+      # Initialize the instance variables on the remountable class, and the base_instance
+      # an instance that will be used to create the set up but will not be mounted
+      def initial_setup(base_instance_parent)
+        @instances = []
+        @setup = []
+        @base_parent = base_instance_parent
+        @base_instance = mount_instance
+      end
+
+      # Redefines all methods so that are forwarded to add_setup and be recorded
+      def override_all_methods!
+        (base_instance.methods - Class.methods - NON_OVERRIDABLE).each do |method_override|
+          define_singleton_method(method_override) do |*args, &block|
+            add_setup(method: method_override, args: args, block: block)
+          end
+        end
+      end
+
+      # Configure an API from the outside. If a block is given, it'll pass a
+      # configuration hash to the block which you can use to configure your
+      # API. If no block is given, returns the configuration hash.
+      # The configuration set here is accessible from inside an API with
+      # `configuration` as normal.
+      def configure
+        config = @base_instance.configuration
         if block_given?
-          m = settings_stack.last[:helpers] || Module.new
-          m.class_eval &block
-          set(:helpers, m)
+          yield config
+          self
         else
-          m = Module.new
-          settings_stack.each do |s|
-            m.send :include, s[:helpers] if s[:helpers]
-          end
-          m
+          config
+        end
+      end
+
+      # The remountable class can have a configuration hash to provide some dynamic class-level variables.
+      # For instance, a description could be done using: `desc configuration[:description]` if it may vary
+      # depending on where the endpoint is mounted. Use with care, if you find yourself using configuration
+      # too much, you may actually want to provide a new API rather than remount it.
+      def mount_instance(configuration: nil)
+        Class.new(@base_parent).tap do |instance|
+          instance.configuration = Grape::Util::EndpointConfiguration.new(configuration || {})
+          instance.base = self
+          replay_setup_on(instance)
+        end
+      end
+
+      private
+
+      # Replays the set up to produce an API as defined in this class, can be called
+      # on classes that inherit from Grape::API
+      def replay_setup_on(instance)
+        @setup.each do |setup_step|
+          replay_step_on(instance, **setup_step)
         end
       end
-      
-      # Add an authentication type to the API. Currently
-      # only `:http_basic` is supported.
-      def auth(type = nil, options = {}, &block)
-        if type
-          set(:auth, {:type => type.to_sym, :proc => block}.merge(options))
+
+      def instance_for_rack
+        if never_mounted?
+          base_instance
         else
-          settings[:auth]
+          mounted_instances.first
         end
       end
-      
-      # Add HTTP Basic authorization to the API.
-      #
-      # @param [Hash] options A hash of options.
-      # @option options [String] :realm "API Authorization" The HTTP Basic realm.
-      def http_basic(options = {}, &block)
-        options[:realm] ||= "API Authorization"
-        auth :http_basic, options, &block
-      end
-      
-      # Defines a route that will be recognized
-      # by the Grape API.
-      #
-      # @param methods [HTTP Verb(s)] One or more HTTP verbs that are accepted by this route. Set to `:any` if you want any verb to be accepted.
-      # @param paths [String(s)] One or more strings representing the URL segment(s) for this route.
-      # @param block [Proc] The code to be executed 
-      def route(methods, paths, &block)
-        methods = Array(methods)
-        paths = ['/'] if paths == []
-        paths = Array(paths)
-        endpoint = build_endpoint(&block)
-        
-        methods.each do |method|
-          paths.each do |path|
-            path = Rack::Mount::Strexp.compile(compile_path(path))
-            route_set.add_route(endpoint, 
-              :path_info => path, 
-              :request_method => (method.to_s.upcase unless method == :any)
-            )
-          end
+
+      # Adds a new stage to the set up require to get a Grape::API up and running
+      def add_setup(step)
+        @setup << step
+        last_response = nil
+        @instances.each do |instance|
+          last_response = replay_step_on(instance, **step)
         end
+
+        refresh_mount_step if step[:method] != :mount
+        last_response
       end
-      
-      def get(*paths, &block); route('GET', paths, &block) end
-      def post(*paths, &block); route('POST', paths, &block) end
-      def put(*paths, &block); route('PUT', paths, &block) end
-      def head(*paths, &block); route('HEAD', paths, &block) end
-      def delete(*paths, &block); route('DELETE', paths, &block) end
-      
-      def namespace(space = nil, &block)
-        if space || block_given?
-          nest(block) do
-            set(:namespace, space.to_s) if space
+
+      # Updating all previously mounted classes in the case that new methods have been executed.
+      def refresh_mount_step
+        @setup.each do |setup_step|
+          next if setup_step[:method] != :mount
+
+          refresh_mount_step = setup_step.merge(method: :refresh_mounted_api)
+          @setup << refresh_mount_step
+          @instances.each do |instance|
+            replay_step_on(instance, **refresh_mount_step)
           end
-        else
-          Rack::Mount::Utils.normalize_path(settings_stack.map{|s| s[:namespace]}.join('/'))
         end
       end
-      
-      alias_method :group, :namespace
-      alias_method :resource, :namespace
-      alias_method :resources, :namespace
-      
-      # Create a scope without affecting the URL.
-      # 
-      # @param name [Symbol] Purely placebo, just allows to to name the scope to make the code more readable.
-      def scope(name = nil, &block)
-        nest(block)
-      end
-      
-      protected
-      
-      # Execute first the provided block, then each of the
-      # block passed in. Allows for simple 'before' setups
-      # of settings stack pushes.
-      def nest(*blocks, &block)
-        blocks.reject!{|b| b.nil?}
-        if blocks.any?
-          settings_stack << {}
-          instance_eval &block if block_given?
-          blocks.each{|b| instance_eval &b}
-          settings_stack.pop
+
+      def replay_step_on(instance, method:, args:, block:)
+        return if skip_immediate_run?(instance, args)
+
+        eval_args = evaluate_arguments(instance.configuration, *args)
+        response = instance.send(method, *eval_args, &block)
+        if skip_immediate_run?(instance, [response])
+          response
         else
-          instance_eval &block
+          evaluate_arguments(instance.configuration, response).first
         end
       end
-      
-      def build_endpoint(&block)
-        b = Rack::Builder.new
-        b.use Grape::Middleware::Error
-        b.use Rack::Auth::Basic, settings[:auth][:realm], &settings[:auth][:proc] if settings[:auth] && settings[:auth][:type] == :http_basic
-        b.use Grape::Middleware::Prefixer, :prefix => prefix if prefix        
-        b.use Grape::Middleware::Versioner, :versions => (version if version.is_a?(Array)) if version
-        b.use Grape::Middleware::Formatter, :default_format => default_format || :json
-        
-        endpoint = Grape::Endpoint.generate(&block)
-        endpoint.send :include, helpers
-        b.run endpoint
-        
-        b.to_app
-      end
-      
-      def inherited(subclass)
-        subclass.reset!
-      end
-      
-      def route_set
-        @route_set ||= Rack::Mount::RouteSet.new
-      end
-      
-      def compile_path(path)
-        parts = []
-        parts << prefix if prefix
-        parts << ':version' if version
-        parts << namespace if namespace
-        parts << path
-        Rack::Mount::Utils.normalize_path(parts.join('/'))
-      end
-    end  
-    
-    reset! 
+
+      # Skips steps that contain arguments to be lazily executed (on re-mount time)
+      def skip_immediate_run?(instance, args)
+        instance.base_instance? &&
+          (any_lazy?(args) || args.any? { |arg| arg.is_a?(Hash) && any_lazy?(arg.values) })
+      end
+
+      def any_lazy?(args)
+        args.any? { |argument| argument.try(:lazy?) }
+      end
+
+      def evaluate_arguments(configuration, *args)
+        args.map do |argument|
+          if argument.try(:lazy?)
+            argument.evaluate_from(configuration)
+          elsif argument.is_a?(Hash)
+            argument.transform_values { |value| evaluate_arguments(configuration, value).first }
+          elsif argument.is_a?(Array)
+            evaluate_arguments(configuration, *argument)
+          else
+            argument
+          end
+        end
+      end
+
+      def never_mounted?
+        mounted_instances.empty?
+      end
+
+      def mounted_instances
+        instances - [base_instance]
+      end
+    end
   end
-end
+end

data/lib/grape/content_types.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Grape
+  module ContentTypes
+    module_function
+
+    # Content types are listed in order of preference.
+    DEFAULTS = {
+      xml: 'application/xml',
+      serializable_hash: 'application/json',
+      json: 'application/json',
+      binary: 'application/octet-stream',
+      txt: 'text/plain'
+    }.freeze
+
+    MIME_TYPES = Grape::ContentTypes::DEFAULTS.except(:serializable_hash).invert.freeze
+
+    def content_types_for(from_settings)
+      from_settings.presence || DEFAULTS
+    end
+
+    def mime_types_for(from_settings)
+      return MIME_TYPES if from_settings == Grape::ContentTypes::DEFAULTS
+
+      from_settings.each_with_object({}) do |(k, v), types_without_params|
+        # remove optional parameter
+        types_without_params[v.split(';', 2).first] = k
+      end
+    end
+  end
+end

data/lib/grape/cookies.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Grape
+  class Cookies
+    extend Forwardable
+
+    DELETED_COOKIES_ATTRS = {
+      max_age: '0',
+      value: '',
+      expires: Time.at(0)
+    }.freeze
+
+    def_delegators :cookies, :[], :each
+
+    def initialize(rack_cookies)
+      @cookies = rack_cookies
+      @send_cookies = nil
+    end
+
+    def response_cookies
+      return unless @send_cookies
+
+      send_cookies.each do |name|
+        yield name, cookies[name]
+      end
+    end
+
+    def []=(name, value)
+      cookies[name] = value
+      send_cookies << name
+    end
+
+    # see https://github.com/rack/rack/blob/main/lib/rack/utils.rb#L338-L340
+    def delete(name, **opts)
+      self.[]=(name, opts.merge(DELETED_COOKIES_ATTRS))
+    end
+
+    private
+
+    def cookies
+      return @cookies unless @cookies.is_a?(Proc)
+
+      @cookies = @cookies.call.with_indifferent_access
+    end
+
+    def send_cookies
+      @send_cookies ||= Set.new
+    end
+  end
+end

data/lib/grape/dry_types.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Grape
+  module DryTypes
+    # Call +Dry.Types()+ to add all registered types to +DryTypes+ which is
+    # a container in this case. Check documentation for more information
+    # https://dry-rb.org/gems/dry-types/1.2/getting-started/
+    include Dry.Types()
+  end
+end

data/lib/grape/dsl/api.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Grape
+  module DSL
+    module API
+      extend ActiveSupport::Concern
+
+      include Grape::DSL::Validations
+      include Grape::DSL::Callbacks
+      include Grape::DSL::Configuration
+      include Grape::DSL::Helpers
+      include Grape::DSL::Middleware
+      include Grape::DSL::RequestResponse
+      include Grape::DSL::Routing
+    end
+  end
+end

data/lib/grape/dsl/callbacks.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Grape
+  module DSL
+    # Blocks can be executed before or after every API call, using `before`, `after`,
+    # `before_validation` and `after_validation`.
+    #
+    # Before and after callbacks execute in the following order:
+    #
+    # 1. `before`
+    # 2. `before_validation`
+    # 3. _validations_
+    # 4. `after_validation`
+    # 5. _the API call_
+    # 6. `after`
+    #
+    # Steps 4, 5 and 6 only happen if validation succeeds.
+    module Callbacks
+      extend ActiveSupport::Concern
+
+      include Grape::DSL::Configuration
+
+      module ClassMethods
+        # Execute the given block before validation, coercion, or any endpoint
+        # code is executed.
+        def before(&block)
+          namespace_stackable(:befores, block)
+        end
+
+        # Execute the given block after `before`, but prior to validation or
+        # coercion.
+        def before_validation(&block)
+          namespace_stackable(:before_validations, block)
+        end
+
+        # Execute the given block after validations and coercions, but before
+        # any endpoint code.
+        def after_validation(&block)
+          namespace_stackable(:after_validations, block)
+        end
+
+        # Execute the given block after the endpoint code has run.
+        def after(&block)
+          namespace_stackable(:afters, block)
+        end
+
+        # Allows you to specify a something that will always be executed after a call
+        # API call. Unlike the `after` block, this code will run even on
+        # unsuccesful requests.
+        # @example
+        #   class ExampleAPI < Grape::API
+        #     before do
+        #       ApiLogger.start
+        #     end
+        #     finally do
+        #       ApiLogger.close
+        #     end
+        #   end
+        #
+        # This will make sure that the ApiLogger is opened and closed around every
+        # request
+        # @param  ensured_block [Proc] The block to be executed after every api_call
+        def finally(&block)
+          namespace_stackable(:finallies, block)
+        end
+      end
+    end
+  end
+end

data/lib/grape/dsl/configuration.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Grape
+  module DSL
+    module Configuration
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        include Grape::DSL::Settings
+        include Grape::DSL::Logger
+        include Grape::DSL::Desc
+      end
+    end
+  end
+end