protocol-http 0.4.1 → 0.5.0

data/lib/protocol/http/body/readable.rb

@@ -0,0 +1,92 @@
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'async/io/buffer'
+
+module Protocol
+	module HTTP
+		module Body
+			# A generic base class for wrapping body instances. Typically you'd override `#read`.
+			# The implementation assumes a sequential unbuffered stream of data.
+			# 	def each -> yield(String | nil)
+			# 	def read -> String | nil
+			# 	def join -> String
+			
+			# 	def finish -> buffer the stream and close it.
+			# 	def close(error = nil) -> close the stream immediately.
+			# end
+			class Readable
+				# The consumer can call stop to signal that the stream output has terminated.
+				def close(error = nil)
+				end
+				
+				# Will read return any data?
+				def empty?
+					false
+				end
+				
+				def length
+					nil
+				end
+				
+				# Read the next available chunk.
+				def read
+					nil
+				end
+				
+				# Read all remaining chunks into a buffered body and close the underlying input.
+				def finish
+					# Internally, this invokes `self.each` which then invokes `self.close`.
+					Buffered.for(self)
+				end
+				
+				# Enumerate all chunks until finished, then invoke `#close`.
+				def each
+					while chunk = self.read
+						yield chunk
+						# chunk.clear
+					end
+				ensure
+					self.close($!)
+				end
+				
+				def call(stream)
+					# Flushing after every chunk is inefficient, but it's also a safe default.
+					self.each do |chunk|
+						stream.write(chunk)
+						stream.flush
+					end
+				end
+				
+				# Read all remaining chunks into a single binary string using `#each`.
+				def join
+					buffer = String.new.force_encoding(Encoding::BINARY)
+					
+					self.each do |chunk|
+						buffer << chunk
+						chunk.clear
+					end
+					
+					return buffer
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http/body/reader.rb

@@ -0,0 +1,83 @@
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Protocol
+	module HTTP
+		module Body
+			# General operations for interacting with a request or response body.
+			module Reader
+				# Read chunks from the body.
+				# @yield [String] read chunks from the body.
+				def each(&block)
+					if @body
+						@body.each(&block)
+						@body = nil
+					end
+				end
+				
+				# Reads the entire request/response body.
+				# @return [String] the entire body as a string.
+				def read
+					if @body
+						buffer = @body.join
+						@body = nil
+						
+						return buffer
+					end
+				end
+				
+				# Gracefully finish reading the body. This will buffer the remainder of the body.
+				# @return [Buffered] buffers the entire body.
+				def finish
+					if @body
+						body = @body.finish
+						@body = nil
+						
+						return body
+					end
+				end
+				
+				# Write the body of the response to the given file path.
+				def save(path, mode = ::File::WRONLY|::File::CREAT, *args)
+					if @body
+						::File.open(path, mode, *args) do |file|
+							self.each do |chunk|
+								file.write(chunk)
+							end
+						end
+					end
+				end
+				
+				# Close the connection as quickly as possible. Discards body. May close the underlying connection if necessary to terminate the stream.
+				def close(error = nil)
+					if @body
+						@body.close(error)
+						@body = nil
+					end
+				end
+				
+				# Whether there is a body?
+				def body?
+					@body and !@body.empty?
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http/body/rewindable.rb

@@ -0,0 +1,60 @@
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'wrapper'
+
+module Protocol
+	module HTTP
+		module Body
+			# A body which buffers all it's contents as it is `#read`.
+			class Rewindable < Wrapper
+				def initialize(body)
+					super(body)
+					
+					@chunks = []
+					@index = 0
+				end
+				
+				def read
+					if @index < @chunks.count
+						chunk = @chunks[@index]
+						@index += 1
+					else
+						if chunk = super
+							@chunks << chunk
+							@index += 1
+						end
+					end
+					
+					# We dup them on the way out, so that if someone modifies the string, it won't modify the rewindability.
+					return chunk&.dup
+				end
+				
+				def rewind
+					@index = 0
+				end
+				
+				def inspect
+					"\#<#{self.class} #{@index}/#{@chunks.count} chunks read>"
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http/body/stream.rb

@@ -0,0 +1,143 @@
+# Copyright, 2019, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Protocol
+	module HTTP
+		module Body
+			# The input stream is an IO-like object which contains the raw HTTP POST data. When applicable, its external encoding must be “ASCII-8BIT” and it must be opened in binary mode, for Ruby 1.9 compatibility. The input stream must respond to gets, each, read and rewind.
+			class Stream
+				def initialize(input, output)
+					@input = input
+					@output = output
+					
+					# Will hold remaining data in `#read`.
+					@buffer = nil
+					@closed = false
+				end
+				
+				attr :input
+				attr :output
+				
+				# rack.hijack_io must respond to:
+				# read, write, read_nonblock, write_nonblock, flush, close, close_read, close_write, closed?
+				
+				# read behaves like IO#read. Its signature is read([length, [buffer]]). If given, length must be a non-negative Integer (>= 0) or nil, and buffer must be a String and may not be nil. If length is given and not nil, then this method reads at most length bytes from the input stream. If length is not given or nil, then this method reads all data until EOF. When EOF is reached, this method returns nil if length is given and not nil, or “” if length is not given or is nil. If buffer is given, then the read data will be placed into buffer instead of a newly created String object.
+				# @param length [Integer] the amount of data to read
+				# @param buffer [String] the buffer which will receive the data
+				# @return a buffer containing the data
+				def read(length = nil, buffer = nil)
+					buffer ||= Async::IO::Buffer.new
+					buffer.clear
+					
+					until buffer.bytesize == length
+						@buffer = read_next if @buffer.nil?
+						break if @buffer.nil?
+						
+						remaining_length = length - buffer.bytesize if length
+						
+						if remaining_length && remaining_length < @buffer.bytesize
+							# We know that we are not going to reuse the original buffer.
+							# But byteslice will generate a hidden copy. So let's freeze it first:
+							@buffer.freeze
+							
+							buffer << @buffer.byteslice(0, remaining_length)
+							@buffer = @buffer.byteslice(remaining_length, @buffer.bytesize)
+						else
+							buffer << @buffer
+							@buffer = nil
+						end
+					end
+					
+					return nil if buffer.empty? && length && length > 0
+					
+					return buffer
+				end
+				
+				def read_nonblock(length, buffer = nil)
+					@buffer ||= read_next
+					chunk = nil
+					
+					if @buffer.bytesize > length
+						chunk = @buffer.byteslice(0, length)
+						@buffer = @buffer.byteslice(length, @buffer.bytesize)
+					else
+						chunk = @buffer
+						@buffer = nil
+					end
+					
+					if buffer
+						buffer.replace(chunk)
+					else
+						buffer = chunk
+					end
+					
+					return buffer
+				end
+				
+				def write(buffer)
+					@output.write(buffer)
+				end
+				
+				alias write_nonblock write
+				
+				def flush
+				end
+				
+				def close_read
+					@input&.close
+				end
+				
+				# close must never be called on the input stream. huh?
+				def close_write
+					@output&.close
+				end
+				
+				# Close the input and output bodies.
+				def close
+					self.close_read
+					self.close_write
+				ensure
+					@closed = true
+				end
+				
+				# Whether the stream has been closed.
+				def closed?
+					@closed
+				end
+				
+				# Whether there are any output chunks remaining?
+				def empty?
+					@output.empty?
+				end
+				
+				private
+				
+				def read_next
+					if chunk = @input&.read
+						return chunk
+					else
+						@input = nil
+						return nil
+					end
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http/body/streamable.rb

@@ -0,0 +1,83 @@
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'wrapper'
+
+module Protocol
+	module HTTP
+		module Body
+			# Invokes a callback once the body has finished reading.
+			class Streamable < Wrapper
+				def self.wrap(message, &block)
+					if message and body = message.body
+						if remaining = body.length
+							remaining = Integer(remaining)
+						end
+						
+						message.body = self.new(message.body, block, remaining)
+					else
+						yield
+					end
+				end
+				
+				def initialize(body, callback, remaining = nil)
+					super(body)
+					
+					@callback = callback
+					@remaining = remaining
+				end
+				
+				def finish
+					if @body
+						result = super
+						
+						@callback.call
+						
+						@body = nil
+						
+						return result
+					end
+				end
+				
+				def close(*)
+					if @body
+						super
+						
+						@callback.call
+						
+						@body = nil
+					end
+				end
+				
+				def read
+					if chunk = super
+						@remaining -= chunk.bytesize if @remaining
+					else
+						if @remaining and @remaining > 0
+							raise EOFError, "Expected #{@remaining} more bytes!"
+						end
+					end
+					
+					return chunk
+				end
+			end
+		end
+	end
+end