grape 4.0.1 → 4.1.0

data/lib/grape/dsl/version_options.rb

@@ -3,9 +3,9 @@
 module Grape
   module DSL
     # Immutable value object holding the resolved options from
-    # +Grape::DSL::Routing#version+. Stored on the inheritable settings as
+    # +Grape::DSL::Versioning#version+. Stored on the inheritable settings as
     # +Grape::Util::InheritableSetting#version_options+ and read by internal call
-    # sites (`Path`, `Endpoint`, `API::Instance#cascade?`,
+    # sites (`Path`, `Endpoint`, `API::Instance`,
     # `Middleware::Versioner::Base`) via accessors.
     #
     # Defaults are duplicated on +#initialize+ here and on +#version+'s

data/lib/grape/dsl/versioning.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Grape
+  module DSL
+    module Versioning
+      # Called without a value, answers whether the API cascades: the value
+      # given here, else the +cascade:+ of +version+, else true. The compiled
+      # API reads it here too; this reader used to skip +version+, and so
+      # answered true for an API that did not cascade.
+      def cascade(value = nil)
+        return inheritable_setting.cascade = value unless value.nil?
+
+        setting = inheritable_setting
+        return setting.cascade if setting.cascade_defined?
+        return setting.version_options.cascade if setting.version_options
+
+        true
+      end
+
+      # Specify an API version.
+      #
+      # Called without arguments, returns the most recently declared version
+      # (or +nil+). Called with one or more version strings, registers them
+      # and stores a {Grape::DSL::VersionOptions} value object on the
+      # inheritable settings; when given a block, the registration applies
+      # within a nested namespace.
+      #
+      # @example API with legacy support.
+      #   class MyAPI < Grape::API
+      #     version 'v2'
+      #
+      #     get '/main' do
+      #       {some: 'data'}
+      #     end
+      #
+      #     version 'v1' do
+      #       get '/main' do
+      #         {legacy: 'data'}
+      #       end
+      #     end
+      #   end
+      #
+      # @param args [Array<String, Symbol>] one or more version identifiers.
+      # @param using [Symbol] versioning strategy — one of +:path+ (default),
+      #   +:header+, +:param+, or +:accept_version_header+.
+      # @param cascade [Boolean] forward to subsequent routes via the
+      #   +X-Cascade+ header on version mismatch. Defaults to +true+.
+      # @param parameter [String] name of the query/body parameter that
+      #   carries the version when +using: :param+. Defaults to +'apiver'+.
+      # @param strict [Boolean] reject requests that don't supply a usable
+      #   version (header strategies). Defaults to +false+.
+      # @param vendor [String, nil] vendor segment for the +:header+
+      #   strategy (+application/vnd.<vendor>-<version>+); required when
+      #   +using: :header+.
+      # @yield optional block to scope routes under this version.
+      # @return [String, nil] the most recently declared version.
+      # @raise [Grape::Exceptions::MissingVendorOption] when +using: :header+
+      #   is supplied without a +:vendor+.
+      def version(*args, using: :path, cascade: true, parameter: 'apiver', strict: false, vendor: nil, &block)
+        return @versions&.last if args.empty?
+
+        options = build_version_options(using:, cascade:, parameter:, strict:, vendor:)
+        requested_versions = args.flatten.map(&:to_s)
+
+        @versions = versions | requested_versions
+
+        if block
+          within_namespace do
+            apply_version(requested_versions, options)
+            instance_eval(&block)
+          end
+        else
+          apply_version(requested_versions, options)
+        end
+
+        @versions.last
+      end
+
+      # @return array of defined versions
+      def versions
+        @versions ||= []
+      end
+
+      private
+
+      def build_version_options(using:, vendor:, **)
+        raise Grape::Exceptions::MissingVendorOption.new if using == :header && vendor.nil?
+
+        VersionOptions.new(using:, vendor:, **)
+      end
+
+      def apply_version(versions, options)
+        inheritable_setting.version = versions
+        inheritable_setting.version_options = options
+      end
+    end
+  end
+end

data/lib/grape/endpoint/state.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Grape
+  class Endpoint
+    # Everything an endpoint's requests read from it and none of them changes.
+    # Each request's copy of the endpoint holds this and its own state, and
+    # nothing else of the endpoint. +app+, +callbacks+ and +build_params_with+
+    # are filled in by Endpoint#compile!.
+    State = Data.define(:inheritable_setting, :options, :config, :source, :options_route_enabled, :app, :callbacks, :build_params_with) do
+      def initialize(inheritable_setting:, options:, config:, source:, options_route_enabled: false, app: nil, callbacks: nil, build_params_with: nil)
+        super
+      end
+    end
+  end
+end

data/lib/grape/endpoint.rb

@@ -11,14 +11,41 @@ module Grape
     include Grape::DSL::Headers
     include Grape::DSL::InsideRoute
 
-    attr_reader :env, :request, :source, :options, :endpoints
-    attr_accessor :options_route_enabled
+    # The innermost app of every endpoint's Rack stack. The endpoint to run
+    # comes out of the env, so the lambda holds no state and one of them serves
+    # every stack, rather than one being allocated per endpoint.
+    RUN_ENDPOINT = ->(env) { env[Grape::Env::API_ENDPOINT].run }
+    private_constant :RUN_ENDPOINT
+
+    attr_reader :env, :request, :endpoints
+
+    # Written out rather than delegated: the request path reads them, and a
+    # +def_delegator+ method checks +defined?+ on every call.
+    def inheritable_setting
+      @state.inheritable_setting
+    end
+
+    def options
+      @state.options
+    end
+
+    def source
+      @state.source
+    end
+
+    def options_route_enabled
+      @state.options_route_enabled
+    end
+
+    def options_route_enabled=(enabled)
+      @state = @state.with(options_route_enabled: enabled)
+    end
 
     def_delegators :request, :params, :headers, :cookies
     def_delegator :cookies, :response_cookies
 
     # The API (a +Grape::API+ instance) this endpoint belongs to.
-    def_delegator :@config, :api
+    def_delegator :config, :api
 
     # The logger configured on the API this endpoint belongs to. Available
     # inside route handlers, +before+/+after+/+after_validation+/+finally+
@@ -32,6 +59,13 @@ module Grape
       config.app
     end
 
+    # The paths this endpoint was declared at, relative to its {#namespace},
+    # as an Array: the paths given to +route+, or for a mount the path
+    # {#mounted_app} was mounted at.
+    def path
+      config.path
+    end
+
     class << self
       def block_to_unbound_method(block)
         return unless block
@@ -67,21 +101,18 @@ module Grape
     # endpoint does not know if it will be mounted under a different endpoint.
     # @yield a block defining what your API should do when this endpoint is hit
     def initialize(new_settings, http_methods:, path:, api:, app: nil, params: {}, requirements: nil, anchor: true, **options, &block)
-      self.inheritable_setting = new_settings.point_in_time_copy_for_endpoint
-
-      @options = options
-      @config = Options.new(http_methods:, path:, api:, app:, params:, requirements:, anchor:, **options)
+      config = Options.new(http_methods:, path:, api:, app:, params:, requirements:, anchor:, **options)
       # +:app+ is still surfaced on the public options Hash for backwards
       # compatibility (e.g. grape-swagger); prefer the +mounted_app+ reader.
-      @options[:app] = app if app
+      options[:app] = app if app
 
-      @status = nil
-      @stream = nil
-      @body = nil
-      @source = self.class.block_to_unbound_method(block)
-      @before_filter_passed = false
-      @options_route_enabled = false
-      @endpoints = @config.app.endpoints if @config.app.respond_to?(:endpoints)
+      @state = State.new(
+        inheritable_setting: new_settings.point_in_time_copy_for_endpoint,
+        options:,
+        config:,
+        source: self.class.block_to_unbound_method(block)
+      )
+      @endpoints = app.endpoints if app.respond_to?(:endpoints)
     end
 
     # Update our settings from a given parent settings instance. Used when
@@ -110,12 +141,7 @@ module Grape
 
       reset_routes!
       compile!
-      routes.each do |route|
-        router.append(route.apply(self))
-        next if inheritable_setting.do_not_route_head? || route.request_method != Rack::GET
-
-        router.append(route.to_head.apply(self))
-      end
+      append_routes_to(router)
     end
 
     def namespace
@@ -129,7 +155,7 @@ module Grape
     def call!(env)
       env[Grape::Env::API_ENDPOINT] = self
       @env = env
-      @app.call(env)
+      @state.app.call(env)
     end
 
     def ==(other)
@@ -156,45 +182,32 @@ module Grape
       "#{self.class} in '#{route.origin}' endpoint"
     end
 
-    protected
-
+    # Serve the request the endpoint's Rack stack was entered with: its
+    # +before+ filters, its validations, the route block, its +after+ and
+    # +finally+ filters, answered as a Rack triplet. The innermost app of that
+    # stack calls it, so it expects #call! to have put the env in place first.
     def run
       instrument_run do
-        @request = Grape::Request.new(env, build_params_with: @build_params_with)
+        @request = Grape::Request.new(env, build_params_with: @state.build_params_with)
+        callbacks = @state.callbacks
         begin
-          run_filters befores, :before
+          run_filters callbacks, :before if callbacks
           @before_filter_passed = true
 
-          if env.key?(Grape::Env::GRAPE_ALLOWED_METHODS)
-            header['Allow'] = env[Grape::Env::GRAPE_ALLOWED_METHODS].join(', ')
-            raise Grape::Exceptions::MethodNotAllowed.new(header) unless options?
-
-            response_object = ''
-            status 204
-          else
-            run_filters before_validations, :before_validation
-            run_validators(request:)
-            run_filters after_validations, :after_validation
-            response_object = execute
-          end
-
-          run_filters afters, :after
+          response_object = env.key?(Grape::Env::GRAPE_ALLOWED_METHODS) ? answer_allowed_methods : validate_and_execute(callbacks)
+          run_filters callbacks, :after if callbacks
           build_response_cookies
-
-          # status verifies body presence when DELETE
-          @body ||= response_object
-
-          # The body commonly is an Array of Strings, the application instance itself, or a Stream-like object
-          response_object = stream || [body]
-
-          [status, header, response_object]
+          rack_triplet(response_object)
         ensure
-          run_filters finallies, :finally
+          run_filters callbacks, :finally if callbacks
         end
       end
     end
 
+    protected
+
     def execute
+      source = @state.source
       return unless source
 
       instrument_render do
@@ -203,8 +216,8 @@ module Grape
     end
 
     def run_validators(request:)
-      validators = inheritable_setting.route_validations
-      return if validators.blank?
+      validators = @state.inheritable_setting.route_validations
+      return if validators.empty?
 
       validation_exceptions = nil
 
@@ -222,24 +235,73 @@ module Grape
       raise Grape::Exceptions::ValidationErrors.new(exceptions: validation_exceptions, headers: header) if validation_exceptions
     end
 
-    def run_filters(filters, type = :other)
-      return if filters.blank?
+    # An endpoint with filters still has none in most of its five phases, so
+    # an empty phase returns before it is instrumented.
+    def run_filters(callbacks, type)
+      filters = callbacks[type]
+      return if filters.empty?
 
       instrument_run_filters(filters, type) do
         filters.each { |filter| instance_eval(&filter) }
       end
     end
 
-    attr_reader :befores, :before_validations, :after_validations, :afters, :finallies, :config
+    def config
+      @state.config
+    end
 
     def options?
       options_route_enabled && env[Rack::REQUEST_METHOD] == Rack::OPTIONS
     end
 
+    # Makes an +allocate+d endpoint the prototype #build_prototype answers:
+    # +state+, and the ivars a request sets, in place so that every copy
+    # starts with the same shape.
+    def become_prototype(state)
+      @state = state
+      @status = nil
+      @stream = nil
+      @body = nil
+      @before_filter_passed = false
+      self
+    end
+
     private
 
     attr_reader :before_filter_passed
 
+    # The answer of a greedy route, which the router hands a request for a
+    # method its path has no route for: the Allow header, with a 204 to an
+    # auto-OPTIONS and a 405 to anything else.
+    def answer_allowed_methods
+      header['Allow'] = env[Grape::Env::GRAPE_ALLOWED_METHODS].join(', ')
+      raise Grape::Exceptions::MethodNotAllowed.new(header) unless options?
+
+      status 204
+      ''
+    end
+
+    # The route block's value, run once the params are validated between the
+    # +before_validation+ and +after_validation+ filters.
+    def validate_and_execute(callbacks)
+      run_filters callbacks, :before_validation if callbacks
+      run_validators(request:)
+      run_filters callbacks, :after_validation if callbacks
+      execute
+    end
+
+    # The response #run answers with, its body +route_value+ unless the
+    # endpoint set a body or a stream itself.
+    def rack_triplet(route_value)
+      # status verifies body presence when DELETE
+      @body ||= route_value
+
+      # The body commonly is an Array of Strings, the application instance itself, or a Stream-like object
+      response_body = stream || [body]
+
+      [status, header, response_body]
+    end
+
     # Instrument helpers. Each guards on +listening?+ so that with no subscriber
     # the payload Hash and notification machinery are skipped and the block runs
     # directly (no added allocations); the block is forwarded anonymously so
@@ -269,45 +331,49 @@ module Grape
     end
 
     def compile!
-      @app = config.app || build_stack
+      app = config.app || build_stack
       warn_unauthenticated_mounted_app
-      @helpers = build_helpers
+      # nil when no phase has a filter -- most endpoints -- so that #run skips
+      # all five on one read.
       callbacks = inheritable_setting.callbacks
-      @befores            = callbacks.fetch(:before)
-      @before_validations = callbacks.fetch(:before_validation)
-      @after_validations  = callbacks.fetch(:after_validation)
-      @afters             = callbacks.fetch(:after)
-      @finallies          = callbacks.fetch(:finally)
-      @build_params_with  = inheritable_setting.build_params_with
-      @prototype          = build_prototype
+      @state = @state.with(
+        app:,
+        callbacks: callbacks.each_value.all?(&:empty?) ? nil : callbacks.freeze,
+        build_params_with: inheritable_setting.build_params_with
+      )
+      @prototype = build_prototype(build_helpers)
     end
 
-    # The object each request is copied from.
+    # The object each request is copied from: this endpoint's State, and none
+    # of the route-building state (+@prototype+, +@endpoints+, +@namespace+,
+    # +@routes+) the request path never reads.
+    #
+    # Ruby sizes a new object by the most instance variables any object of its
+    # class has held. A copy holds the State and the seven ivars a request
+    # sets, which fits an 80-byte slot until a route block or a helper sets one
+    # of its own; carrying the route-building state as well, it took 320. The
+    # endpoint itself counts too when there are no helpers, both being a
+    # Grape::Endpoint, and it holds at most five.
     #
     # Helpers reach an endpoint by module inclusion, and +Object#dup+ does not
     # carry a singleton class over — so including them on the per-request copy
     # meant giving every request a brand-new singleton class, whose method
     # cache then started cold for the helpers, the route block and every DSL
     # method the endpoint answers. Include them once into a subclass owned by
-    # this endpoint instead, and copy this endpoint's state onto an instance of
-    # it: the per-request copy already answers to the helpers, against a class
-    # that has been warm since boot. It also keeps request handling free of
-    # class mutation.
-    #
-    # Endpoints with no helpers are their own prototype, exactly as before.
+    # this endpoint instead, and hand its State to an instance of it: the
+    # per-request copy already answers to the helpers, against a class that
+    # has been warm since boot. It also keeps request handling free of class
+    # mutation.
     #
-    # +allocate+ rather than +new+ because the constructor rebuilds state from
-    # the DSL's arguments — a fresh settings copy, a fresh +@config+, another
-    # +block_to_unbound_method+ — and would still not hold what +compile!+ has
-    # just computed. What is wanted is what +dup+ itself does (allocate, then
-    # copy the ivars over) across a class boundary, which neither +dup+ nor
-    # +initialize_copy+ will do: both insist on the receiver's own class. So
-    # the copy is written out here. Taking all of them is safe because
-    # everything set past this point (+routes+, +namespace+) is route-building
-    # memoization the request path never reads.
-    def build_prototype
-      return self unless @helpers
+    # +allocate+ rather than +new+ because the constructor builds an endpoint
+    # from the DSL's arguments — a fresh settings copy, a fresh +config+,
+    # another +block_to_unbound_method+ — and would still not hold what
+    # +compile!+ has just computed, while the State already holds all of it.
+    def build_prototype(helpers)
+      (helpers ? helpers_class(helpers) : self.class).allocate.become_prototype(@state)
+    end
 
+    def helpers_class(helpers)
       klass = Class.new(self.class)
       # Anonymous classes answer nil to +name+ and render as a bare address,
       # which would reach anything that reports on the endpoint — +inspect+
@@ -315,41 +381,59 @@ module Grape
       # +set_temporary_name+ is for; a plain constant path is rejected, which
       # is right, since this class is not reachable under that name.
       klass.set_temporary_name("#{self.class}(helpers)")
-      klass.include(@helpers)
-      prototype = klass.allocate
-      # Everything but the prototype slot itself, so that recompiling (a
-      # remount) does not leave the new prototype holding the one it replaces.
-      (instance_variables - [:@prototype]).each { |name| prototype.instance_variable_set(name, instance_variable_get(name)) }
-      prototype
+      klass.include(helpers)
+    end
+
+    # Each route, and after a GET route the HEAD route it also answers unless
+    # the API declared +do_not_route_head!+.
+    def append_routes_to(router)
+      routes.each do |route|
+        router.append(route.apply(self))
+        next if inheritable_setting.do_not_route_head? || route.request_method != Rack::GET
+
+        router.append(route.to_head.apply(self))
+      end
     end
 
     def to_routes
+      patterns = route_patterns
       route_options = config.route_options
-      params = config.params
+      attributes = route_attributes
+
+      config.http_methods.flat_map do |method|
+        patterns.map { |pattern| Grape::Router::Route.new(self, method, pattern, route_options, **attributes) }
+      end
+    end
+
+    # The pattern of each of the endpoint's paths, shared by the routes of
+    # every method it answers, as a HEAD route shares its GET route's.
+    def route_patterns
       path_settings = inheritable_setting.path_settings
-      forward_match = bare_rack_app?
-      version = prepare_version(inheritable_setting.version)
-      prefix = inheritable_setting.root_prefix
-      requirements = prepare_routes_requirements(config.requirements)
+      params = config.params
+      version = prepare_version
+      requirements = prepare_routes_requirements
       anchor = config.anchor
-      settings = inheritable_setting.route_settings
 
-      config.http_methods.flat_map do |method|
-        config.path.map do |path|
-          pattern = Grape::Router::Pattern.build(
-            path:,
-            namespace:,
-            settings: path_settings,
-            anchor:,
-            params:,
-            version:,
-            requirements:
-          )
-          Grape::Router::Route.new(self, method, pattern, route_options, forward_match:, params:, namespace:, prefix:, settings:)
-        end
+      config.path.map do |path|
+        Grape::Router::Pattern.build(
+          path:,
+          namespace:,
+          settings: path_settings,
+          anchor:,
+          params:,
+          version:,
+          requirements:
+        )
       end
     end
 
+    # What every route of the endpoint is built with besides its method,
+    # pattern and options, read once for all of them.
+    def route_attributes
+      setting = inheritable_setting
+      { forward_match: bare_rack_app?, params: config.params, namespace:, prefix: setting.root_prefix, settings: setting.route_settings }
+    end
+
     # True when a bare Rack app (anything that isn't a Grape app) is mounted at
     # this endpoint. Such an app is called directly and matched by path prefix
     # rather than an anchored route.
@@ -357,14 +441,16 @@ module Grape
       config.app && !config.app.is_a?(Grape::Mountable)
     end
 
-    def prepare_routes_requirements(route_options_requirements)
+    def prepare_routes_requirements
       namespace_requirements = inheritable_setting.namespace_requirements
-      namespace_requirements << route_options_requirements if route_options_requirements.present?
-      namespace_requirements.reduce({}, :merge)
+      route_requirements = config.requirements
+      namespace_requirements << route_requirements if route_requirements
+      {}.merge!(*namespace_requirements)
     end
 
-    def prepare_version(namespace_inheritable_version)
-      return if namespace_inheritable_version.blank?
+    def prepare_version
+      namespace_inheritable_version = inheritable_setting.version
+      return if namespace_inheritable_version.nil? || namespace_inheritable_version.empty?
 
       namespace_inheritable_version.length == 1 ? namespace_inheritable_version.first : namespace_inheritable_version
     end
@@ -372,36 +458,46 @@ module Grape
     def build_stack
       stack = Grape::Middleware::Stack.new
 
-      content_types = inheritable_setting.content_types
-      format = inheritable_setting.format
+      setting = inheritable_setting
+      content_types = setting.content_types
+      format = setting.format
 
-      stack.use Rack::Head
-      stack.use Rack::Lint if lint?
       stack.use Grape::Middleware::Error, **error_middleware_options(format, content_types)
 
-      stack.concat inheritable_setting.middleware
-
-      if inheritable_setting.version.present?
-        version_options = inheritable_setting.version_options
-        stack.use Grape::Middleware::Versioner.using(version_options.using),
-                  versions: inheritable_setting.version.flatten,
-                  version_options:,
-                  prefix: inheritable_setting.root_prefix,
-                  mount_path: inheritable_setting.mount_path
-      end
-
-      stack.use Grape::Middleware::Formatter,
-                format:,
-                default_format: inheritable_setting.default_format || :txt,
-                content_types:,
-                formatters: inheritable_setting.formatters,
-                parsers: inheritable_setting.parsers
+      stack.concat setting.middleware
+      use_versioner(stack)
+      stack.use Grape::Middleware::Formatter, **formatter_middleware_options(format, content_types)
 
       builder = stack.build
-      builder.run ->(env) { env[Grape::Env::API_ENDPOINT].run }
+      builder.run RUN_ENDPOINT
       builder.to_app
     end
 
+    # The versioner for the strategy +version+ declared, when it declared one.
+    def use_versioner(stack)
+      setting = inheritable_setting
+      versions = setting.version
+      return if versions.nil? || versions.empty?
+
+      version_options = setting.version_options
+      stack.use Grape::Middleware::Versioner.using(version_options.using),
+                versions: versions.flatten,
+                version_options:,
+                prefix: setting.root_prefix,
+                mount_path: setting.mount_path
+    end
+
+    def formatter_middleware_options(format, content_types)
+      setting = inheritable_setting
+      {
+        format:,
+        default_format: setting.default_format || :txt,
+        content_types:,
+        formatters: setting.formatters,
+        parsers: setting.parsers
+      }
+    end
+
     def error_middleware_options(format, content_types)
       setting = inheritable_setting
       {
@@ -449,9 +545,5 @@ module Grape
         Rack::Utils.set_cookie_header! header, name, cookie_value
       end
     end
-
-    def lint?
-      inheritable_setting.lint? || Grape.config.lint
-    end
   end
 end