Introduce Body#discard for efficiently ignoring body. (#69)

lib/protocol/http/body/buffered.rb

@@ -59,6 +59,8 @@ def finish
 				# Ensure that future reads return nil, but allow for rewinding.
 				def close(error = nil)
 					@index = @chunks.length
+
+					return nil
 				end
 
 				def clear
@@ -90,6 +92,10 @@ def read
 					end
 				end
 
+				def discard
+					self.close
+				end
+
 				def write(chunk)
 					@chunks << chunk
 				end

lib/protocol/http/body/readable.rb

@@ -133,6 +133,16 @@ def finish
 					Buffered.read(self)
 				end
 
+				# Discard the body as efficiently as possible.
+				#
+				# The default implementation simply reads all chunks until the body is empty.
+				#
+				# Useful for discarding the body when it is not needed, but preserving the underlying connection.
+				def discard
+					while chunk = self.read
+					end
+				end
+
 				def as_json(...)
 					{
 						class: self.class.name,

lib/protocol/http/body/reader.rb

@@ -40,6 +40,14 @@ def finish
 					end
 				end
 
+				# Discard the body as efficiently as possible.
+				def discard
+					if body = @body
+						@body = nil
+						body.discard
+					end
+				end
+
 				# Buffer the entire request/response body.
 				# @returns [Reader] itself.
 				def buffered!

lib/protocol/http/body/wrapper.rb

@@ -59,6 +59,10 @@ def read
 					@body.read
 				end
 
+				def discard
+					@body.discard
+				end
+
 				def as_json(...)
 					{
 						class: self.class.name,

test/protocol/http/body/buffered.rb

@@ -175,4 +175,12 @@
 			expect(body.inspect).to be =~ /\d+ chunks, \d+ bytes/
 		end
 	end
+
+	with "#discard" do
+		it "closes the body" do
+			expect(body).to receive(:close)
+
+			expect(body.discard).to be == nil
+		end
+	end
 end

test/protocol/http/body/readable.rb

@@ -58,6 +58,13 @@
 		end
 	end
 
+	with "#discard" do
+		it "should read all chunks" do
+			expect(body).to receive(:read).and_return(nil)
+			expect(body.discard).to be_nil
+		end
+	end
+
 	with "#as_json" do
 		it "generates a JSON representation" do
 			expect(body.as_json).to have_keys(

test/protocol/http/body/reader.rb

@@ -29,6 +29,13 @@ def initialize(body)
 		end
 	end
 
+	with "#discard" do
+		it 'discards the body' do
+			expect(body).to receive(:discard)
+			expect(reader.discard).to be_nil
+		end
+	end
+
 	with '#buffered!' do
 		it 'buffers the body' do
 			expect(reader.buffered!).to be_equal(reader)

test/protocol/http/body/wrapper.rb

@@ -104,4 +104,11 @@
 			body.call(stream)
 		end
 	end
+
+	with "#discard" do
+		it "should proxy discard" do
+			expect(source).to receive(:discard).and_return(nil)
+			expect(body.discard).to be_nil
+		end
+	end
 end