100% documentation coverage.

Author: ioquatix

lib/protocol/http1.rb

@@ -5,3 +5,10 @@
 
 require_relative "http1/version"
 require_relative "http1/connection"
+
+# @namespace
+module Protocol
+	# @namespace
+	module HTTP1
+	end
+end

lib/protocol/http1/body.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "body/chunked"
+require_relative "body/fixed"
+require_relative "body/remainder"
+
+module Protocol
+	module HTTP1
+		# A collection of classes for handling HTTP/1.1 request and response bodies.
+		module Body
+		end
+	end
+end

lib/protocol/http1/body/chunked.rb

@@ -9,9 +9,16 @@
 module Protocol
 	module HTTP1
 		module Body
+			# Represents a chunked body, which is a series of chunks, each with a length prefix.
+			#
+			# See https://tools.ietf.org/html/rfc7230#section-4.1 for more details on the chunked transfer encoding.
 			class Chunked < HTTP::Body::Readable
 				CRLF = "\r\n"
 
+				# Initialize the chunked body.
+				#
+				# @parameter connection [Protocol::HTTP1::Connection] the connection to read the body from.
+				# @parameter headers [Protocol::HTTP::Headers] the headers to read the trailer into, if any.
 				def initialize(connection, headers)
 					@connection = connection
 					@finished = false
@@ -22,19 +29,25 @@ def initialize(connection, headers)
 					@count = 0
 				end
 
+				# @attribute [Integer] the number of chunks read so far.
 				attr :count
 
+				# @attribute [Integer] the length of the body if known.
 				def length
-					# We only know the length once we've read everything. This is because the length is not known until the final chunk is read.
+					# We only know the length once we've read the final chunk:
 					if @finished
 						@length
 					end
 				end
 
+				# @returns [Boolean] true if the body is empty, in other words {read} will return `nil`.
 				def empty?
 					@connection.nil?
 				end
 
+				# Close the connection and mark the body as finished.
+				#
+				# @parameter error [Exception | Nil] the error that caused the body to be closed, if any.
 				def close(error = nil)
 					if connection = @connection
 						@connection = nil
@@ -49,7 +62,12 @@ def close(error = nil)
 
 				VALID_CHUNK_LENGTH = /\A[0-9a-fA-F]+\z/
 
+				# Read a chunk of data.
+				#
 				# Follows the procedure outlined in https://tools.ietf.org/html/rfc7230#section-4.1.3
+				#
+				# @returns [String | Nil] the next chunk of data, or `nil` if the body is finished.
+				# @raises [EOFError] if the connection is closed before the expected length is read.
 				def read
 					if !@finished
 						if @connection
@@ -96,12 +114,14 @@ def read
 					end
 				end
 
+				# @returns [String] a human-readable representation of the body.
 				def inspect
 					"\#<#{self.class} #{@length} bytes read in #{@count} chunks>"
 				end
 
 				private
 
+				# Read the trailer from the connection, and add any headers to the trailer.
 				def read_trailer
 					while line = @connection.read_line?
 						# Empty line indicates end of trailer:

lib/protocol/http1/body/fixed.rb

@@ -8,21 +8,33 @@
 module Protocol
 	module HTTP1
 		module Body
+			# Represents a fixed length body.
 			class Fixed < HTTP::Body::Readable
+				# Initialize the body with the given connection and length.
+				#
+				# @parameter connection [Protocol::HTTP1::Connection] the connection to read the body from.
+				# @parameter length [Integer] the length of the body.
 				def initialize(connection, length)
 					@connection = connection
 
 					@length = length
 					@remaining = length
 				end
 
+				# @attribute [Integer] the length of the body.
 				attr :length
+				
+				# @attribute [Integer] the remaining bytes to read.
 				attr :remaining
 
+				# @returns [Boolean] true if the body is empty.
 				def empty?
 					@connection.nil? or @remaining == 0
 				end
 
+				# Close the connection.
+				#
+				# @parameter error [Exception | Nil] the error that caused the connection to be closed, if any.
 				def close(error = nil)
 					if connection = @connection
 						@connection = nil
@@ -35,7 +47,10 @@ def close(error = nil)
 					super
 				end
 
-				# @raises EOFError if the connection is closed before the expected length is read.
+				# Read a chunk of data.
+				#
+				# @returns [String | Nil] the next chunk of data.
+				# @raises [EOFError] if the connection is closed before the expected length is read.
 				def read
 					if @remaining > 0
 						if @connection
@@ -57,6 +72,7 @@ def read
 					end
 				end
 
+				# @returns [String] a human-readable representation of the body.
 				def inspect
 					"\#<#{self.class} length=#{@length} remaining=#{@remaining} state=#{@connection ? 'open' : 'closed'}>"
 				end

lib/protocol/http1/body/remainder.rb

@@ -8,19 +8,24 @@
 module Protocol
 	module HTTP1
 		module Body
-			# A body that reads all remaining data from the connection.
+			# Represents the remainder of the body, which reads all the data from the connection until it is finished.
 			class Remainder < HTTP::Body::Readable
 				BLOCK_SIZE = 1024 * 64
 
-				# block_size may be removed in the future. It is better managed by connection.
-				def initialize(connection)
+				# Initialize the body with the given connection.
+				#
+				# @parameter connection [Protocol::HTTP1::Connection] the connection to read the body from.
+				def initialize(connection, block_size: BLOCK_SIZE)
 					@connection = connection
+					@block_size = block_size
 				end
 
+				# @returns [Boolean] true if the body is empty.
 				def empty?
 					@connection.nil?
 				end
 
+				# Discard the body, which will close the connection and prevent further reads.
 				def discard
 					if connection = @connection
 						@connection = nil
@@ -30,14 +35,20 @@ def discard
 					end
 				end
 
+				# Close the connection.
+				#
+				# @parameter error [Exception | Nil] the error that caused the connection to be closed, if any.
 				def close(error = nil)
 					self.discard
 
 					super
 				end
 
+				# Read a chunk of data.
+				#
+				# @returns [String | Nil] the next chunk of data.
 				def read
-					@connection&.readpartial(BLOCK_SIZE)
+					@connection&.readpartial(@block_size)
 				rescue EOFError
 					if connection = @connection
 						@connection = nil
@@ -47,6 +58,7 @@ def read
 					return nil
 				end
 
+				# @returns [String] a human-readable representation of the body.
 				def inspect
 					"\#<#{self.class} state=#{@connection ? 'open' : 'closed'}>"
 				end