protocol-http 0.45.0 → 0.46.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 989a6411106c9c491df6a8916877cc9d1abbd4509da3e859e5d627723edc8daa
-  data.tar.gz: 20fc3651bf5241e7c3fb55d286ff3172a09363a747ac97f5608eb4a7533aece7
+  metadata.gz: 753df89051cc0eeff1cab5100a4ebc2a98e11bd3dce4a3fbcba890406c198c32
+  data.tar.gz: dbc6b80efe3fc8a430839868f160151a9490336cc39423e31cfd851076b72947
 SHA512:
-  metadata.gz: dcc3a33c4b19b130df7825a44c4bdf6bc2c631fa9a073299180fd34256436e89ab012087a2adfebc37f1f6f39d4d5e4967fd14ef481d7c150328edf0ef95d088
-  data.tar.gz: 59b1398b707f7c79ca6055a45461006f1cffd5d90c862e05c0924baaaa5144161193b48c5d357f9648431dd57f18da57854e6eb2af56f4b0924ad0772e62a349
+  metadata.gz: 104b449c9a3beaaf7f3c50e28eb21df3f2bef95b89ec954bd20a808a09b508f69d8e0387d6b41ed8e7dc02e41a85bc1116ff8f775694c4e0b26c3899b248f310
+  data.tar.gz: 3ea2e87c3375055aa89f8d9b73b549854cb53ecb90bf6ee3f75ffc4c4ae8b7fbb61b10119fbdb0d125287aea03c894c7327b79ee410d28a771faab24e2fcafa5

data/lib/protocol/http/accept_encoding.rb

@@ -10,11 +10,15 @@ require_relative "body/inflate"
 
 module Protocol
 	module HTTP
-		# Set a valid accept-encoding header and decode the response.
+		# A middleware that sets the accept-encoding header and decodes the response according to the content-encoding header.
 		class AcceptEncoding < Middleware
+			# The header used to request encodings.
 			ACCEPT_ENCODING = "accept-encoding".freeze
+			
+			# The header used to specify encodings.
 			CONTENT_ENCODING = "content-encoding".freeze
 			
+			# The default wrappers to use for decoding content.
 			DEFAULT_WRAPPERS = {
 				"gzip" => Body::Inflate.method(:for),
 				
@@ -22,13 +26,21 @@ module Protocol
 				# 'identity' => ->(body){body},
 			}
 			
-			def initialize(app, wrappers = DEFAULT_WRAPPERS)
-				super(app)
+			# Initialize the middleware with the given delegate and wrappers.
+			#
+			# @parameter delegate [Protocol::HTTP::Middleware] The delegate middleware.
+			# @parameter wrappers [Hash] A hash of encoding names to wrapper functions.
+			def initialize(delegate, wrappers = DEFAULT_WRAPPERS)
+				super(delegate)
 				
 				@accept_encoding = wrappers.keys.join(", ")
 				@wrappers = wrappers
 			end
 			
+			# Set the accept-encoding header and decode the response body.
+			#
+			# @parameter request [Protocol::HTTP::Request] The request to modify.
+			# @returns [Protocol::HTTP::Response] The response.
 			def call(request)
 				request.headers[ACCEPT_ENCODING] = @accept_encoding
 				

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

@@ -43,6 +43,10 @@ module Protocol
 					self.new(chunks)
 				end
 				
+				# Initialize the buffered body with some chunks.
+				#
+				# @parameter chunks [Array(String)] the chunks to buffer.
+				# @parameter length [Integer] the length of the body, if known.
 				def initialize(chunks = [], length = nil)
 					@chunks = chunks
 					@length = length
@@ -50,6 +54,7 @@ module Protocol
 					@index = 0
 				end
 				
+				# @attribute [Array(String)] chunks the buffered chunks.
 				attr :chunks
 				
 				# 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.
@@ -59,36 +64,48 @@ module Protocol
 					self.class.new(@chunks)
 				end
 				
+				# Finish the body, this is a no-op.
+				#
+				# @returns [Buffered] self.
 				def finish
 					self
 				end
 				
-				# Ensure that future reads return nil, but allow for rewinding.
+				# Ensure that future reads return `nil`, but allow for rewinding.
+				#
+				# @parameter error [Exception | Nil] the error that caused the body to be closed, if any.
 				def close(error = nil)
 					@index = @chunks.length
 					
 					return nil
 				end
 				
+				# Clear the buffered chunks.
 				def clear
 					@chunks = []
 					@length = 0
 					@index = 0
 				end
 				
+				# The length of the body. Will compute and cache the length of the body, if it was not provided.
 				def length
 					@length ||= @chunks.inject(0) {|sum, chunk| sum + chunk.bytesize}
 				end
 				
+				# @returns [Boolean] if the body is empty.
 				def empty?
 					@index >= @chunks.length
 				end
 				
-				# A buffered response is always ready.
+				# Whether the body is ready to be read.
+				# @returns [Boolean] a buffered response is always ready.
 				def ready?
 					true
 				end
 				
+				# Read the next chunk from the buffered body.
+				#
+				# @returns [String | Nil] the next chunk or nil if there are no more chunks.
 				def read
 					return nil unless @chunks
 					
@@ -99,23 +116,30 @@ module Protocol
 					end
 				end
 				
+				# Discard the body. Invokes {#close}.
 				def discard
 					# It's safe to call close here because there is no underlying stream to close:
 					self.close
 				end
 				
+				# Write a chunk to the buffered body.
 				def write(chunk)
 					@chunks << chunk
 				end
 				
+				# Close the body for writing. This is a no-op.
 				def close_write(error)
 					# Nothing to do.
 				end
 				
+				# Whether the body can be rewound.
+				#
+				# @returns [Boolean] if the body has chunks.
 				def rewindable?
 					@chunks != nil
 				end
 				
+				# Rewind the body to the beginning, causing a subsequent read to return the first chunk.
 				def rewind
 					return false unless @chunks
 					
@@ -124,6 +148,9 @@ module Protocol
 					return true
 				end
 				
+				# Inspect the buffered body.
+				#
+				# @returns [String] a string representation of the buffered body.
 				def inspect
 					if @chunks
 						"\#<#{self.class} #{@chunks.size} chunks, #{self.length} bytes>"

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

@@ -10,6 +10,10 @@ module Protocol
 		module Body
 			# Invokes a callback once the body has completed, either successfully or due to an error.
 			class Completable < Wrapper
+				# Wrap a message body with a callback. If the body is empty, the callback is invoked immediately.
+				#
+				# @parameter message [Request | Response] the message body.
+				# @parameter block [Proc] the callback to invoke when the body is closed.
 				def self.wrap(message, &block)
 					if body = message&.body and !body.empty?
 						message.body = self.new(message.body, block)
@@ -18,20 +22,29 @@ module Protocol
 					end
 				end
 				
+				# Initialize the completable body with a callback.
+				#
+				# @parameter body [Readable] the body to wrap.
+				# @parameter callback [Proc] the callback to invoke when the body is closed.
 				def initialize(body, callback)
 					super(body)
 					
 					@callback = callback
 				end
 				
+				# @returns [Boolean] completable bodies are not rewindable.
 				def rewindable?
 					false
 				end
 				
+				# Rewind the body, is not supported.
 				def rewind
 					false
 				end
 				
+				# Close the body and invoke the callback. If an error is given, it is passed to the callback.
+				#
+				# The calback is only invoked once, and before `super` is invoked.
 				def close(error = nil)
 					if @callback
 						@callback.call(error)

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

@@ -10,17 +10,27 @@ require "zlib"
 module Protocol
 	module HTTP
 		module Body
+			# A body which compresses or decompresses the contents using the DEFLATE or GZIP algorithm.
 			class ZStream < Wrapper
+				# The default compression level.
 				DEFAULT_LEVEL = 7
 				
+				# The DEFLATE window size.
 				DEFLATE = -Zlib::MAX_WBITS
+				
+				# The GZIP window size.
 				GZIP =  Zlib::MAX_WBITS | 16
 				
+				# The supported encodings.
 				ENCODINGS = {
 					"deflate" => DEFLATE,
 					"gzip" => GZIP,
 				}
 				
+				# Initialize the body with the given stream.
+				#
+				# @parameter body [Readable] the body to wrap.
+				# @parameter stream [Zlib::Deflate | Zlib::Inflate] the stream to use for compression or decompression.
 				def initialize(body, stream)
 					super(body)
 					
@@ -30,6 +40,9 @@ module Protocol
 					@output_length = 0
 				end
 				
+				# Close the stream.
+				#
+				# @parameter error [Exception | Nil] the error that caused the stream to be closed.
 				def close(error = nil)
 					if stream = @stream
 						@stream = nil
@@ -39,14 +52,21 @@ module Protocol
 					super
 				end
 				
+				# The length of the output, if known. Generally, this is not known due to the nature of compression.
 				def length
 					# We don't know the length of the output until after it's been compressed.
 					nil
 				end
 				
+				# @attribute [Integer] input_length the total number of bytes read from the input.
 				attr :input_length
+				
+				# @attribute [Integer] output_length the total number of bytes written to the output.
 				attr :output_length
 				
+				# The compression ratio, according to the input and output lengths.
+				#
+				# @returns [Float] the compression ratio, e.g. 0.5 for 50% compression.
 				def ratio
 					if @input_length != 0
 						@output_length.to_f / @input_length.to_f
@@ -55,16 +75,29 @@ module Protocol
 					end
 				end
 				
+				# Inspect the body, including the compression ratio.
+				#
+				# @returns [String] a string representation of the body.
 				def inspect
 					"#{super} | \#<#{self.class} #{(ratio*100).round(2)}%>"
 				end
 			end
 			
+			# A body which compresses the contents using the DEFLATE or GZIP algorithm.
 			class Deflate < ZStream
+				# Create a new body which compresses the given body using the GZIP algorithm by default.
+				#
+				# @parameter body [Readable] the body to wrap.
+				# @parameter window_size [Integer] the window size to use for compression.
+				# @parameter level [Integer] the compression level to use.
+				# @returns [Deflate] the wrapped body.
 				def self.for(body, window_size = GZIP, level = DEFAULT_LEVEL)
 					self.new(body, Zlib::Deflate.new(level, window_size))
 				end
 				
+				# Read a chunk from the underlying body and compress it. If the body is finished, the stream is flushed and finished, and the remaining data is returned.
+				#
+				# @returns [String | Nil] the compressed chunk or `nil` if the stream is closed.
 				def read
 					return if @stream.finished?
 					

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

@@ -12,12 +12,21 @@ module Protocol
 		module Body
 			# Invokes a callback once the body has finished reading.
 			class Digestable < Wrapper
+				# Wrap a message body with a callback. If the body is empty, the callback is not invoked, as there is no data to digest.
+				#
+				# @parameter message [Request | Response] the message body.
+				# @parameter digest [Digest] the digest to use.
+				# @parameter block [Proc] the callback to invoke when the body is closed.
 				def self.wrap(message, digest = Digest::SHA256.new, &block)
 					if body = message&.body and !body.empty?
 						message.body = self.new(message.body, digest, block)
 					end
 				end
 				
+				# Initialize the digestable body with a callback.
+				#
+				# @parameter body [Readable] the body to wrap.
+				# @parameter digest [Digest] the digest to use.
 				# @parameter callback [Block] The callback is invoked when the digest is complete.
 				def initialize(body, digest = Digest::SHA256.new, callback = nil)
 					super(body)
@@ -25,11 +34,14 @@ module Protocol
 					@digest = digest
 					@callback = callback
 				end
+
+				# @attribute [Digest] digest the digest object.
+				attr :digest
 				
-				def digest
-					@digest
-				end
-				
+				# Generate an appropriate ETag for the digest, assuming it is complete. If you call this method before the body is fully read, the ETag will be incorrect.
+				#
+				# @parameter weak [Boolean] If true, the ETag is marked as weak.
+				# @returns [String] the ETag.
 				def etag(weak: false)
 					if weak
 						"W/\"#{digest.hexdigest}\""
@@ -38,6 +50,9 @@ module Protocol
 					end
 				end
 				
+				# Read the body and update the digest. When the body is fully read, the callback is invoked with `self` as the argument.
+				#
+				# @returns [String | Nil] the next chunk of data, or nil if the body is fully read.
 				def read
 					if chunk = super
 						@digest.update(chunk)

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

@@ -8,14 +8,27 @@ require_relative "readable"
 module Protocol
 	module HTTP
 		module Body
+			# A body which reads from a file.
 			class File < Readable
-				BLOCK_SIZE = 4096
+				# The default block size.
+				BLOCK_SIZE = 64*1024
+				
+				# The default mode for opening files.
 				MODE = ::File::RDONLY | ::File::BINARY
 				
+				# Open a file at the given path.
+				#
+				# @parameter path [String] the path to the file.
 				def self.open(path, *arguments, **options)
 					self.new(::File.open(path, MODE), *arguments, **options)
 				end
 				
+				# Initialize the file body with the given file.
+				#
+				# @parameter file [::File] the file to read from.
+				# @parameter range [Range] the range of bytes to read from the file.
+				# @parameter size [Integer] the size of the file, if known.
+				# @parameter block_size [Integer] the block size to use when reading from the file.
 				def initialize(file, range = nil, size: file.size, block_size: BLOCK_SIZE)
 					@file = file
 					@range = range
@@ -33,6 +46,9 @@ module Protocol
 					end
 				end
 				
+				# Close the file.
+				#
+				# @parameter error [Exception | Nil] the error that caused the file to be closed.
 				def close(error = nil)
 					@file.close
 					@remaining = 0
@@ -40,32 +56,46 @@ module Protocol
 					super
 				end
 				
+				# @attribute [::File] file the file to read from.
 				attr :file
 				
+				# @attribute [Integer] the offset to read from.
 				attr :offset
+				
+				# @attribute [Integer] the number of bytes to read.
 				attr :length
 				
+				# @returns [Boolean] whether more data should be read.
 				def empty?
 					@remaining == 0
 				end
 				
+				# @returns [Boolean] whether the body is ready to be read, always true for files.
 				def ready?
 					true
 				end
 				
+				# Returns a copy of the body, by duplicating the file descriptor, including the same range if specified.
+				#
+				# @returns [File] the duplicated body.
 				def buffered
 					self.class.new(@file.dup, @range, block_size: @block_size)
 				end
 				
+				# Rewind the file to the beginning of the range.
 				def rewind
 					@file.seek(@offset)
 					@remaining = @length
 				end
 				
+				# @returns [Boolean] whether the body is rewindable, generally always true for seekable files.
 				def rewindable?
 					true
 				end
 				
+				# Read the next chunk of data from the file.
+				#
+				# @returns [String | Nil] the next chunk of data, or nil if the file is fully read.
 				def read
 					if @remaining > 0
 						amount = [@remaining, @block_size].min
@@ -88,6 +118,9 @@ module Protocol
 				# 	stream.close
 				# end
 				
+				# Read all the remaining data from the file and return it as a single string.
+				#
+				# @returns [String] the remaining data.
 				def join
 					return "" if @remaining == 0
 					
@@ -98,6 +131,9 @@ module Protocol
 					return buffer
 				end
 				
+				# Inspect the file body.
+				#
+				# @returns [String] a string representation of the file body.
 				def inspect
 					"\#<#{self.class} file=#{@file.inspect} offset=#{@offset} remaining=#{@remaining}>"
 				end

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

@@ -8,7 +8,9 @@ require_relative "readable"
 module Protocol
 	module HTTP
 		module Body
+			# Represents a body suitable for HEAD requests, in other words, a body that is empty and has a known length.
 			class Head < Readable
+				# Create a head body for the given body, capturing it's length and then closing it.
 				def self.for(body)
 					head = self.new(body.length)
 					
@@ -17,18 +19,24 @@ module Protocol
 					return head
 				end
 				
+				# Initialize the head body with the given length.
+				#
+				# @parameter length [Integer] the length of the body.
 				def initialize(length)
 					@length = length
 				end
 				
+				# @returns [Boolean] the body is empty.
 				def empty?
 					true
 				end
 				
+				# @returns [Boolean] the body is ready.
 				def ready?
 					true
 				end
 				
+				# @returns [Integer] the length of the body, if known.
 				def length
 					@length
 				end

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

@@ -10,11 +10,19 @@ require_relative "deflate"
 module Protocol
 	module HTTP
 		module Body
+			# A body which decompresses the contents using the DEFLATE or GZIP algorithm.
 			class Inflate < ZStream
-				def self.for(body, encoding = GZIP)
-					self.new(body, Zlib::Inflate.new(encoding))
+				# Create a new body which decompresses the given body using the GZIP algorithm by default.
+				#
+				# @parameter body [Readable] the body to wrap.
+				# @parameter window_size [Integer] the window size to use for decompression.
+				def self.for(body, window_size = GZIP)
+					self.new(body, Zlib::Inflate.new(window_size))
 				end
 				
+				# Read from the underlying stream and inflate it.
+				#
+				# @returns [String | Nil] the inflated data, or nil if the stream is finished.
 				def read
 					if stream = @stream
 						# Read from the underlying stream and inflate it:

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

@@ -9,42 +9,51 @@ module Protocol
 		module Body
 			# Represents a readable input streams.
 			#
-			# Typically, you'd override `#read` to return chunks of data.
+			# There are two major modes of operation:
 			#
-			# In general, you read chunks of data from a body until it is empty and returns `nil`. Upon reading `nil`, the body is considered consumed and should not be read from again.
+			# 1. Reading chunks using {read} (or {each}/{join}), until the body is empty, or
+			# 2. Streaming chunks using {call}, which writes chunks to a provided output stream.
 			#
-			# Reading can also fail, for example if the body represents a streaming upload, and the connection is lost. In this case, `#read` will raise some kind of error.
+			# In both cases, reading can fail, for example if the body represents a streaming upload, and the connection is lost. In this case, {read} will raise some kind of error, or the stream will be closed with an error.
 			#
-			# If you don't want to read from a stream, and instead want to close it immediately, you can call `close` on the body. If the body is already completely consumed, `close` will do nothing, but if there is still data to be read, it will cause the underlying stream to be reset (and possibly closed).
+			# At any point, you can use {close} to close the stream and release any resources, or {discard} to read all remaining data without processing it which may allow the underlying connection to be reused (but can be slower).
 			class Readable
 				# Close the stream immediately. After invoking this method, the stream should be considered closed, and all internal resources should be released.
 				#
 				# If an error occured while handling the output, it can be passed as an argument. This may be propagated to the client, for example the client may be informed that the stream was not fully read correctly.
 				#
-				# Invoking `#read` after `#close` will return `nil`.
+				# Invoking {read} after {close} will return `nil`.
+				#
+				# @parameter error [Exception | Nil] The error that caused this stream to be closed, if any.
 				def close(error = nil)
 				end
 				
 				# Optimistically determine whether read (may) return any data.
-				# If this returns true, then calling read will definitely return nil.
-				# If this returns false, then calling read may return nil.
+				#
+				# - If this returns true, then calling read will definitely return nil.
+				# - If this returns false, then calling read may return nil.
+				#
+				# @return [Boolean] Whether the stream is empty.
 				def empty?
 					false
 				end
 				
-				# Whether calling read will return a chunk of data without blocking.
-				# We prefer pessimistic implementation, and thus default to `false`.
-				# @return [Boolean]
+				# Whether calling read will return a chunk of data without blocking. We prefer pessimistic implementation, and thus default to `false`.
+				#
+				# @return [Boolean] Whether the stream is ready (read will not block).
 				def ready?
 					false
 				end
 				
 				# Whether the stream can be rewound using {rewind}.
+				#
+				# @return [Boolean] Whether the stream is rewindable.
 				def rewindable?
 					false
 				end
 				
 				# Rewind the stream to the beginning.
+				#
 				# @returns [Boolean] Whether the stream was successfully rewound.
 				def rewind
 					false
@@ -60,19 +69,21 @@ module Protocol
 				end
 				
 				# The total length of the body, if known.
+				#
 				# @returns [Integer | Nil] The total length of the body, or `nil` if the length is unknown.
 				def length
 					nil
 				end
 				
 				# Read the next available chunk.
+				#
 				# @returns [String | Nil] The chunk of data, or `nil` if the stream has finished.
 				# @raises [StandardError] If an error occurs while reading.
 				def read
 					nil
 				end
 				
-				# Enumerate all chunks until finished, then invoke `#close`.
+				# Enumerate all chunks until finished, then invoke {close}.
 				#
 				# Closes the stream when finished or if an error occurs.
 				#
@@ -109,6 +120,9 @@ module Protocol
 					end
 				end
 				
+				# Whether to prefer streaming the body using {call} rather than reading it using {read} or {each}.
+				#
+				# @returns [Boolean] Whether the body should be streamed.
 				def stream?
 					false
 				end
@@ -131,6 +145,7 @@ module Protocol
 						end
 					end
 				ensure
+					# TODO Should this invoke close_write(error) instead?
 					stream.close
 				end
 				
@@ -152,6 +167,9 @@ module Protocol
 					end
 				end
 				
+				# Convert the body to a hash suitable for serialization. This won't include the contents of the body, but will include metadata such as the length, streamability, and readiness, etc.
+				#
+				# @returns [Hash] The body as a hash.
 				def as_json(...)
 					{
 						class: self.class.name,
@@ -162,6 +180,9 @@ module Protocol
 					}
 				end
 				
+				# Convert the body to JSON.
+				#
+				# @returns [String] The body as JSON.
 				def to_json(...)
 					as_json.to_json(...)
 				end