Introduce rewind and rewindable? as a general concept. (#60)

* Consistent implementation of `#wrap` for Wrapper sub-class.

Author: ioquatix

lib/protocol/http/body/buffered.rb

@@ -11,25 +11,29 @@ module HTTP
 		module Body
 			# A body which buffers all it's contents.
 			class Buffered < Readable
-				# Wraps an array into a buffered body.
+				# Tries to wrap an object in a {Buffered} instance.
 				#
 				# For compatibility, also accepts anything that behaves like an `Array(String)`.
 				#
 				# @parameter body [String | Array(String) | Readable | nil] the body to wrap.
 				# @returns [Readable | nil] the wrapped body or nil if nil was given.
-				def self.wrap(body)
-					if body.is_a?(Readable)
-						return body
-					elsif body.is_a?(Array)
-						return self.new(body)
-					elsif body.is_a?(String)
-						return self.new([body])
-					elsif body
-						return self.for(body)
+				def self.wrap(object)
+					if object.is_a?(Readable)
+						return object
+					elsif object.is_a?(Array)
+						return self.new(object)
+					elsif object.is_a?(String)
+						return self.new([object])
+					elsif object
+						return self.read(object)
 					end
 				end
 
-				def self.for(body)
+				# Read the entire body into a buffered representation.
+				#
+				# @parameter body [Readable] the body to read.
+				# @returns [Buffered] the buffered body.
+				def self.read(body)
 					chunks = []
 
 					body.each do |chunk|
@@ -77,8 +81,14 @@ def write(chunk)
 					@chunks << chunk
 				end
 
+				def rewindable?
+					true
+				end
+				
 				def rewind
 					@index = 0
+					
+					return true
 				end
 
 				def inspect

lib/protocol/http/body/completable.rb

@@ -24,6 +24,14 @@ def initialize(body, callback)
 					@callback = callback
 				end
 
+				def rewindable?
+					false
+				end
+				
+				def rewind
+					false
+				end
+				
 				def finish
 					super.tap do
 						if @callback

lib/protocol/http/body/readable.rb

@@ -29,6 +29,14 @@ def ready?
 					false
 				end
 
+				def rewindable?
+					false
+				end
+				
+				def rewind
+					false
+				end
+				
 				def length
 					nil
 				end
@@ -58,7 +66,7 @@ def call(stream)
 				# @returns [Buffered] The buffered body.
 				def finish
 					# Internally, this invokes `self.each` which then invokes `self.close`.
-					Buffered.for(self)
+					Buffered.read(self)
 				end
 
 				# Enumerate all chunks until finished, then invoke `#close`.

lib/protocol/http/body/rewindable.rb

@@ -11,6 +11,16 @@ module HTTP
 		module Body
 			# A body which buffers all it's contents as it is `#read`.
 			class Rewindable < Wrapper
+				def self.wrap(message)
+					if body = message.body
+						if body.rewindable?
+							body
+						else
+							message.body = self.new(body)
+						end
+					end
+				end
+				
 				def initialize(body)
 					super(body)
 
@@ -26,7 +36,9 @@ def ready?
 					(@index < @chunks.size) || super
 				end
 
-				# A rewindable body wraps some other body. Convert it to a buffered body 
+				# A rewindable body wraps some other body. Convert it to a buffered body. The buffered body will share the same chunks as the rewindable body.
+				#
+				# @returns [Buffered] the buffered body. 
 				def buffered
 					Buffered.new(@chunks)
 				end
@@ -54,6 +66,10 @@ def rewind
 					@index = 0
 				end
 
+				def rewindable?
+					true
+				end
+				
 				def inspect
 					"\#<#{self.class} #{@index}/#{@chunks.size} chunks read>"
 				end

lib/protocol/http/body/wrapper.rb

@@ -10,6 +10,10 @@ module HTTP
 		module Body
 			# Wrapping body instance. Typically you'd override `#read`.
 			class Wrapper < Readable
+				# Wrap the body of the given message in a new instance of this class.
+				#
+				# @parameter message [Request | Response] the message to wrap.
+				# @returns [Wrapper | nil] the wrapped body or nil if the body was nil.
 				def self.wrap(message)
 					if body = message.body
 						message.body = self.new(body)
@@ -42,6 +46,14 @@ def ready?
 					@body.ready?
 				end
 
+				def rewind
+					@body.rewind
+				end
+				
+				def rewindable?
+					@body.rewindable?
+				end
+				
 				def length
 					@body.length
 				end

test/protocol/http/body/buffered.rb

@@ -117,6 +117,10 @@
 	end
 
 	with "#rewind" do
+		it "is rewindable" do
+			expect(body).to be(:rewindable?)
+		end
+		
 		it "positions the cursor to the beginning" do
 			expect(body.read).to be == "Hello"
 			body.rewind

test/protocol/http/body/completable.rb

@@ -83,4 +83,13 @@
 			expect(completable.read).to be_nil
 		end
 	end
+	
+	with "#rewindable?" do
+		it "is not rewindable" do
+			# Because completion can only happen once, we can't rewind the body.
+			expect(body).to be(:rewindable?)
+			expect(completable).not.to be(:rewindable?)
+			expect(completable.rewind).to be == false
+		end
+	end
 end

test/protocol/http/body/inflate.rb

@@ -14,7 +14,7 @@
 	let(:sample) {"The quick brown fox jumps over the lazy dog."}
 	let(:chunks) {[sample] * 1024}
 
-	let(:body) {Protocol::HTTP::Body::Buffered.for(chunks)}
+	let(:body) {Protocol::HTTP::Body::Buffered.new(chunks)}
 	let(:deflate_body) {Protocol::HTTP::Body::Deflate.for(body)}
 	let(:compressed_chunks) {deflate_body.join.each_char.to_a}
 	let(:compressed_body_chunks) {compressed_chunks}

test/protocol/http/body/readable.rb

@@ -58,4 +58,11 @@
 			expect(JSON.dump(body)).to be == body.to_json
 		end
 	end
+	
+	with "#rewindable?" do
+		it "is not rewindable" do
+			expect(body).not.to be(:rewindable?)
+			expect(body.rewind).to be == false
+		end
+	end
 end

test/protocol/http/body/rewindable.rb

@@ -4,6 +4,7 @@
 # Copyright, 2019-2023, by Samuel Williams.
 
 require 'protocol/http/body/rewindable'
+require 'protocol/http/request'
 
 describe Protocol::HTTP::Body::Rewindable do
 	let(:source) {Protocol::HTTP::Body::Buffered.new}
@@ -47,6 +48,26 @@
 		end
 	end
 
+	with ".wrap" do
+		with "a buffered body" do
+			let(:body) {Protocol::HTTP::Body::Buffered.new}
+			let(:message) {Protocol::HTTP::Request.new(nil, nil, 'GET', '/', nil, Protocol::HTTP::Headers.new, body)}
+			
+			it "returns the body" do
+				expect(subject.wrap(message)).to be == body
+			end
+		end
+		
+		with "a non-rewindable body" do
+			let(:body) {Protocol::HTTP::Body::Readable.new}
+			let(:message) {Protocol::HTTP::Request.new(nil, nil, 'GET', '/', nil, Protocol::HTTP::Headers.new, body)}
+			
+			it "returns a new rewindable body" do
+				expect(subject.wrap(message)).to be_a(Protocol::HTTP::Body::Rewindable)
+			end
+		end
+	end
+	
 	with '#buffered' do
 		it "can generate buffered representation" do
 			3.times do |i|
@@ -76,6 +97,12 @@
 		end
 	end
 
+	with "#rewindable?" do
+		it "is rewindable" do
+			expect(body).to be(:rewindable?)
+		end
+	end
+	
 	with '#inspect' do
 		it "can generate string representation" do
 			expect(body.inspect).to be == "#<Protocol::HTTP::Body::Rewindable 0/0 chunks read>"

test/protocol/http/body/wrapper.rb

@@ -64,6 +64,20 @@
 		end
 	end
 
+	with "#rewindable?" do
+		it "should proxy rewindable?" do
+			expect(source).to receive(:rewindable?).and_return(true)
+			expect(body.rewindable?).to be == true
+		end
+	end
+	
+	with "#rewind" do
+		it "should proxy rewind" do
+			expect(source).to receive(:rewind).and_return(true)
+			expect(body.rewind).to be == true
+		end
+	end
+	
 	with "#as_json" do
 		it "generates a JSON representation" do
 			expect(body.as_json).to have_keys(