lib/grape/dsl/inside_route.rb in grape-0.12.0 vs lib/grape/dsl/inside_route.rb in grape-0.13.0

@@ -175,16 +175,38 @@
       #   end
       #
       #   GET /file # => "contents of file"
       def file(value = nil)
         if value
-          @file = value
+          @file = Grape::Util::FileResponse.new(value)
         else
           @file
         end
       end
 
+      # Allows you to define the response as a streamable object.
+      #
+      # If Content-Length and Transfer-Encoding are blank (among other conditions),
+      # Rack assumes this response can be streamed in chunks.
+      #
+      # @example
+      #   get '/stream' do
+      #     stream FileStreamer.new(...)
+      #   end
+      #
+      #   GET /stream # => "chunked contents of file"
+      #
+      # See:
+      # * https://github.com/rack/rack/blob/99293fa13d86cd48021630fcc4bd5acc9de5bdc3/lib/rack/chunked.rb
+      # * https://github.com/rack/rack/blob/99293fa13d86cd48021630fcc4bd5acc9de5bdc3/lib/rack/etag.rb
+      def stream(value = nil)
+        header 'Content-Length', nil
+        header 'Transfer-Encoding', nil
+        header 'Cache-Control', 'no-cache' # Skips ETag generation (reading the response up front)
+        file(value)
+      end
+
       # Allows you to make use of Grape Entities by setting
       # the response body to the serializable hash of the
       # entity provided in the `:with` option. This has the
       # added benefit of automatically passing along environment
       # and version information to the serialization, making it
@@ -236,10 +258,18 @@
       #   end
       def route
         env['rack.routing_args'][:route_info]
       end
 
+      # Attempt to locate the Entity class for a given object, if not given
+      # explicitly. This is done by looking for the presence of Klass::Entity,
+      # where Klass is the class of the `object` parameter, or one of its
+      # ancestors.
+      # @param object [Object] the object to locate the Entity class for
+      # @param options [Hash]
+      # @option options :with [Class] the explicit entity class to use
+      # @return [Class] the located Entity class, or nil if none is found
       def entity_class_for_obj(object, options)
         entity_class = options.delete(:with)
 
         if entity_class.nil?
           # entity class not explicitely defined, auto-detect from relation#klass or first object in the collection
@@ -257,9 +287,11 @@
         end
 
         entity_class
       end
 
+      # @return the representation of the given object as done through
+      #   the given entity_class.
       def entity_representation_for(entity_class, object, options)
         embeds = { env: env }
         embeds[:version] = env['api.version'] if env['api.version']
         entity_class.represent(object, embeds.merge(options))
       end