protocol-http 0.45.0 → 0.46.0

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

@@ -8,8 +8,11 @@ module Protocol
 	module HTTP
 		module Body
 			# General operations for interacting with a request or response body.
+			#
+			# This module is included in both {Request} and {Response}.
 			module Reader
 				# Read chunks from the body.
+				#
 				# @yields {|chunk| ...} chunks from the body.
 				def each(&block)
 					if @body
@@ -19,6 +22,7 @@ module Protocol
 				end
 				
 				# Reads the entire request/response body.
+				#
 				# @returns [String] the entire body as a string.
 				def read
 					if @body
@@ -30,6 +34,7 @@ module Protocol
 				end
 				
 				# Gracefully finish reading the body. This will buffer the remainder of the body.
+				#
 				# @returns [Buffered] buffers the entire body.
 				def finish
 					if @body
@@ -46,19 +51,27 @@ module Protocol
 						@body = nil
 						body.discard
 					end
+					
+					return nil
 				end
 				
 				# Buffer the entire request/response body.
+				#
 				# @returns [Reader] itself.
 				def buffered!
 					if @body
 						@body = @body.finish
 					end
 					
+					# TODO Should this return @body instead? It seems more useful.
 					return self
 				end
 				
 				# Write the body of the response to the given file path.
+				#
+				# @parameter path [String] the path to write the body to.
+				# @parameter mode [Integer] the mode to open the file with.
+				# @parameter options [Hash] additional options to pass to `File.open`.
 				def save(path, mode = ::File::WRONLY|::File::CREAT|::File::TRUNC, **options)
 					if @body
 						::File.open(path, mode, **options) do |file|
@@ -70,6 +83,8 @@ module Protocol
 				end
 				
 				# Close the connection as quickly as possible. Discards body. May close the underlying connection if necessary to terminate the stream.
+				#
+				# @parameter error [Exception | Nil] the error that caused the stream to be closed, if any.
 				def close(error = nil)
 					if @body
 						@body.close(error)
@@ -78,6 +93,8 @@ module Protocol
 				end
 				
 				# Whether there is a body?
+				#
+				# @returns [Boolean] whether there is a body.
 				def body?
 					@body and !@body.empty?
 				end

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

@@ -9,8 +9,13 @@ require_relative "buffered"
 module Protocol
 	module HTTP
 		module Body
-			# A body which buffers all it's contents as it is `#read`.
+			# A body which buffers all it's contents as it is read.
+			#
+			# As the body is buffered in memory, you may want to ensure your server has sufficient (virtual) memory available to buffer the entire body.
 			class Rewindable < Wrapper
+				# Wrap the given message body in a rewindable body, if it is not already rewindable.
+				#
+				# @parameter message [Request | Response] the message to wrap.
 				def self.wrap(message)
 					if body = message.body
 						if body.rewindable?
@@ -21,6 +26,9 @@ module Protocol
 					end
 				end
 				
+				# Initialize the body with the given body.
+				#
+				# @parameter body [Readable] the body to wrap.
 				def initialize(body)
 					super(body)
 					
@@ -28,10 +36,12 @@ module Protocol
 					@index = 0
 				end
 				
+				# @returns [Boolean] Whether the body is empty.
 				def empty?
 					(@index >= @chunks.size) && super
 				end
 				
+				# @returns [Boolean] Whether the body is ready to be read.
 				def ready?
 					(@index < @chunks.size) || super
 				end
@@ -43,6 +53,9 @@ module Protocol
 					Buffered.new(@chunks)
 				end
 				
+				# Read the next available chunk. This may return a buffered chunk if the stream has been rewound, or a chunk from the underlying stream, if available.
+				#
+				# @returns [String | Nil] The chunk of data, or `nil` if the stream has finished.
 				def read
 					if @index < @chunks.size
 						chunk = @chunks[@index]
@@ -58,14 +71,19 @@ module Protocol
 					return chunk
 				end
 				
+				# Rewind the stream to the beginning.
 				def rewind
 					@index = 0
 				end
 				
+				# @returns [Boolean] Whether the stream is rewindable, which it is.
 				def rewindable?
 					true
 				end
 				
+				# Inspect the rewindable body.
+				#
+				# @returns [String] a string representation of the body.
 				def inspect
 					"\#<#{self.class} #{@index}/#{@chunks.size} chunks read>"
 				end

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

@@ -11,8 +11,13 @@ module Protocol
 		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
+				# The default line separator, used by {gets}.
 				NEWLINE = "\n"
 				
+				# Initialize the stream with the given input and output.
+				#
+				# @parameter input [Readable] The input stream.
+				# @parameter output [Writable] The output stream.
 				def initialize(input = nil, output = Buffered.new)
 					@input = input
 					@output = output
@@ -26,7 +31,10 @@ module Protocol
 					@closed_read = false
 				end
 				
+				# @attribute [Readable] The input stream.
 				attr :input
+				
+				# @attribute [Writable] The output stream.
 				attr :output
 				
 				# This provides a read-only interface for data, which is surprisingly tricky to implement correctly.
@@ -39,9 +47,9 @@ module Protocol
 					#
 					# 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
+					# @parameterlength [Integer] the amount of data to read
+					# @parameter buffer [String] the buffer which will receive the data
+					# @returns [String] a buffer containing the data
 					def read(length = nil, buffer = nil)
 						return "" if length == 0
 						
@@ -125,11 +133,14 @@ module Protocol
 					end
 					
 					# Similar to {read_partial} but raises an `EOFError` if the stream is at EOF.
+					#
+					# @parameter length [Integer] The maximum number of bytes to read.
+					# @parameter buffer [String] The buffer to read into.
 					def readpartial(length, buffer = nil)
 						read_partial(length, buffer) or raise EOFError, "End of file reached!"
 					end
 					
-					# Iterate over each chunk of data in the stream.
+					# Iterate over each chunk of data from the input stream.
 					#
 					# @yields {|chunk| ...} Each chunk of data.
 					def each(&block)
@@ -146,6 +157,9 @@ module Protocol
 					end
 					
 					# Read data from the stream without blocking if possible.
+					#
+					# @parameter length [Integer] The maximum number of bytes to read.
+					# @parameter buffer [String | Nil] The buffer to read into.
 					def read_nonblock(length, buffer = nil, exception: nil)
 						@buffer ||= read_next
 						chunk = nil
@@ -323,6 +337,10 @@ module Protocol
 				end
 				
 				# Close the input body.
+				#
+				# If, while processing the data that was read from this stream, an error is encountered, it should be passed to this method.
+				#
+				# @parameter error [Exception | Nil] The error that was encountered, if any.
 				def close_read(error = nil)
 					if input = @input
 						@input = nil
@@ -334,6 +352,10 @@ module Protocol
 				end
 				
 				# Close the output body.
+				#
+				# If, while generating the data that is written to this stream, an error is encountered, it should be passed to this method.
+				#
+				# @parameter error [Exception | Nil] The error that was encountered, if any.
 				def close_write(error = nil)
 					if output = @output
 						@output = nil
@@ -343,6 +365,8 @@ module Protocol
 				end
 				
 				# Close the input and output bodies.
+				#
+				# @parameter error [Exception | Nil] The error that caused this stream to be closed, if any.
 				def close(error = nil)
 					self.close_read(error)
 					self.close_write(error)
@@ -352,18 +376,22 @@ module Protocol
 					@closed = true
 				end
 				
-				# Whether the stream has been closed.
+				# @returns [Boolean] Whether the stream has been closed.
 				def closed?
 					@closed
 				end
 				
-				# Whether there are any output chunks remaining?
+				# @returns [Boolean] Whether there are any output chunks remaining.
 				def empty?
 					@output.empty?
 				end
 				
 				private
 				
+				# Read the next chunk of data from the input stream.
+				#
+				# @returns [String] The next chunk of data.
+				# @raises [IOError] If the input stream was explicitly closed.
 				def read_next
 					if @input
 						return @input.read

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

@@ -13,39 +13,65 @@ module Protocol
 		module Body
 			# A body that invokes a block that can read and write to a stream.
 			#
-			# In some cases, it's advantageous to directly read and write to the underlying stream if possible. For example, HTTP/1 upgrade requests, WebSockets, and similar. To handle that case, response bodies can implement `stream?` and return `true`. When `stream?` returns true, the body **should** be consumed by calling `call(stream)`. Server implementations may choose to always invoke `call(stream)` if it's efficient to do so. Bodies that don't support it will fall back to using `#each`.
+			# In some cases, it's advantageous to directly read and write to the underlying stream if possible. For example, HTTP/1 upgrade requests, WebSockets, and similar. To handle that case, response bodies can implement {stream?} and return `true`. When {stream?} returns true, the body **should** be consumed by calling `call(stream)`. Server implementations may choose to always invoke `call(stream)` if it's efficient to do so. Bodies that don't support it will fall back to using {each}.
 			#
 			# When invoking `call(stream)`, the stream can be read from and written to, and closed. However, the stream is only guaranteed to be open for the duration of the `call(stream)` call. Once the method returns, the stream **should** be closed by the server.
 			module Streamable
+				# Generate a new streaming request body using the given block to generate the body.
+				#
+				# @parameter block [Proc] The block that generates the body.
+				# @returns [RequestBody] The streaming request body.
 				def self.request(&block)
 					RequestBody.new(block)
 				end
 				
+				# Generate a new streaming response body using the given block to generate the body.
+				#
+				# @parameter request [Request] The request.
+				# @parameter block [Proc] The block that generates the body.
+				# @returns [ResponseBody] The streaming response body.
 				def self.response(request, &block)
 					ResponseBody.new(block, request.body)
 				end
 				
+				# A output stream that can be written to by a block.
 				class Output
+					# Schedule the block to be executed in a fiber.
+					#
+					# @parameter input [Readable] The input stream.
+					# @parameter block [Proc] The block that generates the output.
+					# @returns [Output] The output stream.
 					def self.schedule(input, block)
 						self.new(input, block).tap(&:schedule)
 					end
 					
+					# Initialize the output stream with the given input and block.
+					#
+					# @parameter input [Readable] The input stream.
+					# @parameter block [Proc] The block that generates the output.
 					def initialize(input, block)
 						@output = Writable.new
 						@stream = Stream.new(input, @output)
 						@block = block
 					end
 					
+					# Schedule the block to be executed in a fiber.
+					#
+					# @returns [Fiber] The fiber.
 					def schedule
 						@fiber ||= Fiber.schedule do
 							@block.call(@stream)
 						end
 					end
 					
+					# Read from the output stream (may block).
 					def read
 						@output.read
 					end
 					
+					# Close the output stream.
+					#
+					# @parameter error [Exception | Nil] The error that caused this stream to be closed, if any.
 					def close(error = nil)
 						@output.close_write(error)
 					end
@@ -55,13 +81,19 @@ module Protocol
 				class ConsumedError < StandardError
 				end
 				
+				# A streaming body that can be read from and written to.
 				class Body < Readable
+					# Initialize the body with the given block and input.
+					#
+					# @parameter block [Proc] The block that generates the body.
+					# @parameter input [Readable] The input stream, if known.
 					def initialize(block, input = nil)
 						@block = block
 						@input = input
 						@output = nil
 					end
 					
+					# @returns [Boolean] Whether the body can be streamed, which is true.
 					def stream?
 						true
 					end
@@ -81,9 +113,9 @@ module Protocol
 						@output.read
 					end
 					
-					# Invoke the block with the given stream.
+					# Invoke the block with the given stream. The block can read and write to the stream, and must close the stream when finishing.
 					#
-					# The block can read and write to the stream, and must close the stream when finishing.
+					# @parameter stream [Stream] The stream to read and write to.
 					def call(stream)
 						if @block.nil?
 							raise ConsumedError, "Streaming block has already been consumed!"
@@ -101,6 +133,9 @@ module Protocol
 						raise
 					end
 					
+					# Close the input. The streaming body will eventually read all the input.
+					#
+					# @parameter error [Exception | Nil] The error that caused this stream to be closed, if any.
 					def close_input(error = nil)
 						if input = @input
 							@input = nil
@@ -108,6 +143,9 @@ module Protocol
 						end
 					end
 					
+					# Close the output, the streaming body will be unable to write any more output.
+					#
+					# @parameter error [Exception | Nil] The error that caused this stream to be closed, if any.
 					def close_output(error = nil)
 						@output&.close(error)
 					end
@@ -115,8 +153,8 @@ module Protocol
 				
 				# A response body is used on the server side to generate the response body using a block.
 				class ResponseBody < Body
+					# Close will be invoked when all the output is written.
 					def close(error = nil)
-						# Close will be invoked when all the output is written.
 						self.close_output(error)
 					end
 				end
@@ -125,12 +163,15 @@ module Protocol
 				#
 				# As the response body isn't available until the request is sent, the response body must be {stream}ed into the request body.
 				class RequestBody < Body
+					# Initialize the request body with the given block.
+					#
+					# @parameter block [Proc] The block that generates the body.
 					def initialize(block)
 						super(block, Writable.new)
 					end
 					
+					# Close will be invoked when all the input is read.
 					def close(error = nil)
-						# Close will be invoked when all the input is read.
 						self.close_input(error)
 					end
 					

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

@@ -13,20 +13,26 @@ module Protocol
 				# 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.
+				# @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)
 					end
 				end
 				
+				# Initialize the wrapper with the given body.
+				#
+				# @parameter body [Readable] The body to wrap.
 				def initialize(body)
 					@body = body
 				end
 				
-				# The wrapped body.
+				# @attribute [Readable] The wrapped body.
 				attr :body
 				
+				# Close the body.
+				#
+				# @parameter error [Exception | Nil] The error that caused this stream to be closed, if any.
 				def close(error = nil)
 					@body.close(error)
 					
@@ -34,39 +40,49 @@ module Protocol
 					# super
 				end
 				
+				# Forwards to the wrapped body.
 				def empty?
 					@body.empty?
 				end
 				
+				# Forwards to the wrapped body.
 				def ready?
 					@body.ready?
 				end
 				
+				# Forwards to the wrapped body.
 				def buffered
 					@body.buffered
 				end
 				
+				# Forwards to the wrapped body.
 				def rewind
 					@body.rewind
 				end
 				
+				# Forwards to the wrapped body.
 				def rewindable?
 					@body.rewindable?
 				end
 				
+				# Forwards to the wrapped body.
 				def length
 					@body.length
 				end
 				
-				# Read the next available chunk.
+				# Forwards to the wrapped body.
 				def read
 					@body.read
 				end
 				
+				# Forwards to the wrapped body.
 				def discard
 					@body.discard
 				end
 				
+				# Convert the body to a hash suitable for serialization.
+				#
+				# @returns [Hash] The body as a hash.
 				def as_json(...)
 					{
 						class: self.class.name,
@@ -74,10 +90,16 @@ module Protocol
 					}
 				end
 				
+				# Convert the body to JSON.
+				#
+				# @returns [String] The body as JSON.
 				def to_json(...)
 					as_json.to_json(...)
 				end
 				
+				# Inspect the wrapped body. The wrapper, by default, is transparent.
+				#
+				# @returns [String] a string representation of the wrapped body.
 				def inspect
 					@body.inspect
 				end

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

@@ -10,11 +10,14 @@ module Protocol
 		module Body
 			# A dynamic body which you can write to and read from.
 			class Writable < Readable
+				# An error indicating that the body has been closed and no further writes are allowed.
 				class Closed < StandardError
 				end
 				
-				# @param [Integer] length The length of the response body if known.
-				# @param [Async::Queue] queue Specify a different queue implementation, e.g. `Async::LimitedQueue.new(8)` to enable back-pressure streaming.
+				# Initialize the writable body.
+				#
+				# @parameter length [Integer] The length of the response body if known.
+				# @parameter queue [Thread::Queue] Specify a different queue implementation, e.g. `Thread::SizedQueue` to enable back-pressure.
 				def initialize(length = nil, queue: Thread::Queue.new)
 					@length = length
 					@queue = queue
@@ -22,11 +25,12 @@ module Protocol
 					@error = nil
 				end
 				
-				def length
-					@length
-				end
+				# @attribute [Integer] The length of the response body if known.
+				attr :length
 				
 				# Stop generating output; cause the next call to write to fail with the given error. Does not prevent existing chunks from being read. In other words, this indicates both that no more data will be or should be written to the body.
+				#
+				# @parameter error [Exception] The error that caused this body to be closed, if any. Will be raised on the next call to {read}.
 				def close(error = nil)
 					@error ||= error
 					
@@ -36,20 +40,29 @@ module Protocol
 					super
 				end
 				
+				# Whether the body is closed. A closed body can not be written to or read from.
+				#
+				# @returns [Boolean] Whether the body is closed.
 				def closed?
 					@queue.closed?
 				end
 				
+				# @returns [Boolean] Whether the body is ready to be read from, without blocking.
 				def ready?
 					!@queue.empty? || @queue.closed?
 				end
 				
-				# Has the producer called #finish and has the reader consumed the nil token?
+				# Indicates whether the body is empty. This can occur if the body has been closed, or if the producer has invoked {close_write} and the reader has consumed all available chunks.
+				#
+				# @returns [Boolean] Whether the body is empty.
 				def empty?
 					@queue.empty? && @queue.closed?
 				end
 				
 				# Read the next available chunk.
+				#
+				# @returns [String | Nil] The next chunk, or `nil` if the body is finished.
+				# @raises [Exception] If the body was closed due to an error.
 				def read
 					if @error
 						raise @error
@@ -65,7 +78,11 @@ module Protocol
 					return chunk
 				end
 				
-				# Write a single chunk to the body. Signal completion by calling `#finish`.
+				# Write a single chunk to the body. Signal completion by calling {close_write}.
+				#
+				# @parameter chunk [String] The chunk to write.
+				# @raises [Closed] If the body has been closed without error.
+				# @raises [Exception] If the body has been closed due to an error.
 				def write(chunk)
 					if @queue.closed?
 						raise(@error || Closed)
@@ -75,27 +92,41 @@ module Protocol
 					@count += 1
 				end
 				
+				# Signal that no more data will be written to the body.
+				#
+				# @parameter error [Exception] The error that caused this body to be closed, if any.
 				def close_write(error = nil)
 					@error ||= error
 					@queue.close
 				end
 				
+				# The output interface for writing chunks to the body.
 				class Output
+					# Initialize the output with the given writable body.
+					#
+					# @parameter writable [Writable] The writable body.
 					def initialize(writable)
 						@writable = writable
 						@closed = false
 					end
 					
+					# @returns [Boolean] Whether the output is closed for writing only.
 					def closed?
 						@closed || @writable.closed?
 					end
 					
+					# Write a chunk to the body.
 					def write(chunk)
 						@writable.write(chunk)
 					end
 					
 					alias << write
 					
+					# Close the output stream.
+					#
+					# If an error is given, the error will be used to close the body by invoking {close} with the error. Otherwise, only the write side of the body will be closed.
+					#
+					# @parameter error [Exception | Nil] The error that caused this stream to be closed, if any.
 					def close(error = nil)
 						@closed = true
 						
@@ -108,6 +139,12 @@ module Protocol
 				end
 				
 				# Create an output wrapper which can be used to write chunks to the body.
+				#
+				# If a block is given, and the block raises an error, the error will used to close the body by invoking {close} with the error.
+				#
+				# @yields {|output| ...} if a block is given.
+				# 	@parameter output [Output] The output wrapper.
+				# @returns [Output] The output wrapper.
 				def output
 					output = Output.new(self)
 					
@@ -124,6 +161,9 @@ module Protocol
 					end
 				end
 				
+				# Inspect the body.
+				#
+				# @returns [String] A string representation of the body.
 				def inspect
 					if @error
 						"\#<#{self.class} #{@count} chunks written, #{status}, error=#{@error}>"
@@ -134,6 +174,7 @@ module Protocol
 				
 				private
 				
+				# @returns [String] A string representation of the body's status.
 				def status
 					if @queue.empty?
 						if @queue.closed?

data/lib/protocol/http/body.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require_relative "body/readable"
+require_relative "body/writable"
+require_relative "body/wrapper"
+
+module Protocol
+	module HTTP
+		# @namespace
+		module Body
+		end
+	end
+end