un-deprecate stream-like objects

- this splits the "stream" and "file" inside_route methods
- file is purely for specifying a file (and utilizing sendfile when it can)
- stream is purely for stream-like objects.. This allows you to have streaming responses of generated data

Author: urkle

CHANGELOG.md

@@ -5,6 +5,7 @@
 * Your contribution here.
 * [#1850](https://github.com/ruby-grape/grape/pull/1850): Adds `same_as` validator - [@glaucocustodio](https://github.com/glaucocustodio).
 * [#1833](https://github.com/ruby-grape/grape/pull/1833): Allows to set the `ParamBuilder` globally - [@myxoh](https://github.com/myxoh).
+* [#1520](https://github.com/ruby-grape/grape/pull/1520): un-deprecate stream-like objects - [@urkle](https://github.com/urkle).
 
 #### Fixes
 

lib/grape.rb

@@ -185,11 +185,11 @@ module Presenters
     autoload :Presenter
   end
 
-  module ServeFile
+  module ServeStream
     extend ::ActiveSupport::Autoload
-    autoload :FileResponse
     autoload :FileBody
     autoload :SendfileResponse
+    autoload :StreamResponse
   end
 end
 

lib/grape/dsl/inside_route.rb

@@ -257,13 +257,13 @@ def return_no_content
       #   GET /file # => "contents of file"
       def file(value = nil)
         if value.is_a?(String)
-          file_body = Grape::ServeFile::FileBody.new(value)
-          @file = Grape::ServeFile::FileResponse.new(file_body)
+          file_body = Grape::ServeStream::FileBody.new(value)
+          @stream = Grape::ServeStream::SteamResponse.new(file_body)
         elsif !value.is_a?(NilClass)
           warn '[DEPRECATION] Argument as FileStreamer-like object is deprecated. Use path to file instead.'
-          @file = Grape::ServeFile::FileResponse.new(value)
+          @stream = Grape::ServeStream::StreamResponse.new(value)
         else
-          @file
+          @stream
         end
       end
 
@@ -286,7 +286,16 @@ 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)
+        if value.is_a?(String)
+          warn '[DEPRECATION] Use `file file_path` to stream a file instead.'
+          file(value)
+        elsif value.respond_to?(:each)
+          @stream = Grape::ServeStream::StreamResponse.new(value)
+        elsif !value.is_a?(NilClass)
+          raise ArgumentError, 'Stream object must respond to :each.'
+        else
+          @stream
+        end
       end
 
       # Allows you to make use of Grape Entities by setting

lib/grape/middleware/formatter.rb

@@ -34,9 +34,9 @@ def after
       def build_formatted_response(status, headers, bodies)
         headers = ensure_content_type(headers)
 
-        if bodies.is_a?(Grape::ServeFile::FileResponse)
-          Grape::ServeFile::SendfileResponse.new([], status, headers) do |resp|
-            resp.body = bodies.file
+        if bodies.is_a?(Grape::ServeStream::StreamResponse)
+          Grape::ServeStream::SendfileResponse.new([], status, headers) do |resp|
+            resp.body = bodies.stream
           end
         else
           # Allow content-type to be explicitly overwritten

lib/grape/serve_file/file_body.rb renamed to lib/grape/serve_stream/file_body.rb

@@ -1,5 +1,5 @@
 module Grape
-  module ServeFile
+  module ServeStream
     CHUNK_SIZE = 16_384
 
     # Class helps send file through API

lib/grape/serve_file/sendfile_response.rb renamed to lib/grape/serve_stream/sendfile_response.rb

@@ -1,5 +1,5 @@
 module Grape
-  module ServeFile
+  module ServeStream
     # Response should respond to to_path method
     # for using Rack::SendFile middleware
     class SendfileResponse < Rack::Response

lib/grape/serve_file/file_response.rb renamed to lib/grape/serve_stream/stream_response.rb

@@ -1,20 +1,20 @@
 module Grape
-  module ServeFile
-    # A simple class used to identify responses which represent files and do not
+  module ServeStream
+    # A simple class used to identify responses which represent streams (or files) and do not
     # need to be formatted or pre-read by Rack::Response
-    class FileResponse
-      attr_reader :file
+    class StreamResponse
+      attr_reader :stream
 
-      # @param file [Object]
-      def initialize(file)
-        @file = file
+      # @param stream [Object]
+      def initialize(stream)
+        @stream = stream
       end
 
       # Equality provided mostly for tests.
       #
       # @return [Boolean]
       def ==(other)
-        file == other.file
+        stream == other.stream
       end
     end
   end

spec/grape/dsl/inside_route_spec.rb

@@ -206,15 +206,15 @@ def initialize
         let(:file_path) { '/some/file/path' }
 
         let(:file_response) do
-          file_body = Grape::ServeFile::FileBody.new(file_path)
-          Grape::ServeFile::FileResponse.new(file_body)
+          file_body = Grape::ServeStream::FileBody.new(file_path)
+          Grape::ServeStream::StreamResponse.new(file_body)
         end
 
         before do
           subject.file file_path
         end
 
-        it 'returns value wrapped in FileResponse' do
+        it 'returns value wrapped in StreamResponse' do
           expect(subject.file).to eq file_response
         end
       end
@@ -223,14 +223,14 @@ def initialize
         let(:file_object) { Class.new }
 
         let(:file_response) do
-          Grape::ServeFile::FileResponse.new(file_object)
+          Grape::ServeStream::StreamResponse.new(file_object)
         end
 
         before do
           subject.file file_object
         end
 
-        it 'returns value wrapped in FileResponse' do
+        it 'returns value wrapped in StreamResponse' do
           expect(subject.file).to eq file_response
         end
       end
@@ -243,7 +243,7 @@ def initialize
 
   describe '#stream' do
     describe 'set' do
-      let(:file_object) { Class.new }
+      let(:file_object) { double('StreamerObject', each: nil) }
 
       before do
         subject.header 'Cache-Control', 'cache'
@@ -252,12 +252,12 @@ def initialize
         subject.stream file_object
       end
 
-      it 'returns value wrapped in FileResponse' do
-        expect(subject.stream).to eq Grape::ServeFile::FileResponse.new(file_object)
+      it 'returns value wrapped in StreamResponse' do
+        expect(subject.stream).to eq Grape::ServeStream::StreamResponse.new(file_object)
       end
 
-      it 'also sets result of file to value wrapped in FileResponse' do
-        expect(subject.file).to eq Grape::ServeFile::FileResponse.new(file_object)
+      it 'also sets result of file to value wrapped in StreamResponse' do
+        expect(subject.file).to eq Grape::ServeStream::StreamResponse.new(file_object)
       end
 
       it 'sets Cache-Control header to no-cache' do

spec/grape/middleware/formatter_spec.rb

@@ -371,12 +371,12 @@ def to_xml
   end
 
   context 'send file' do
-    let(:body) { Grape::ServeFile::FileResponse.new('file') }
+    let(:body) { Grape::ServeStream::StreamResponse.new('file') }
     let(:app) { ->(_env) { [200, {}, body] } }
 
-    it 'returns Grape::Uril::SendFileReponse' do
+    it 'returns Grape::ServerStream::SendFileReponse' do
       env = { 'PATH_INFO' => '/somewhere', 'HTTP_ACCEPT' => 'application/json' }
-      expect(subject.call(env)).to be_a(Grape::ServeFile::SendfileResponse)
+      expect(subject.call(env)).to be_a(Grape::ServeStream::SendfileResponse)
     end
   end