protocol-rack 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 253756f1f94918a43327d8f107e1a614414b6c7eee787d876135454697f3f108
-  data.tar.gz: bfe5453d726e362ac82c06a723d941991da8d6663749a924f8a81c919f6ca798
+  metadata.gz: b70faf13a5271971f02ddae3e19e17262c9df2ce74832cce7e0f6312265d76df
+  data.tar.gz: e9a4a1dfc0cb419d6395a7e68300f270e26398fadb00661b08093c60b47b7ea2
 SHA512:
-  metadata.gz: 990b93f88c80068cdcf57c36ed0ff8bfeeb0e79044dab843668bf93db4eff71ce4117da113b0cac812625d178603c815ca121d8b233945772a0af289690e053c
-  data.tar.gz: f84b64ec28519ab67db3770d6e2dce6ee86387cbc730a283fe7fa83811da2bb0d6ff831fd05f41ca5c2e8f15b33c92e7864e6ab17ad8335ba965ff3be24505a2
+  metadata.gz: 1d8a7f11acb1220d0ed05626c4ddfb87ef23578922741e92d15bf32e0e0294c433ebfa2149e538f10352695b3c0cf30af69667ab34033beead13f799dbbbdad5
+  data.tar.gz: 4d59623d81149838f7b2bf5f0ce67a13bdf39a0d5b04e17367ab6d07d57468d008834d6ad439cd6f41e42dcf95e6d314694334b38bfcfe02ba0d96f5a35b5def

data/lib/protocol/rack/adapter/generic.rb

@@ -1,35 +1,52 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 require "console"
 
 require_relative "../constants"
 require_relative "../input"
 require_relative "../response"
+require_relative "../rewindable"
 
 module Protocol
 	module Rack
 		module Adapter
+			# The base adapter class that provides common functionality for all Rack adapters.
+			# It handles the conversion between {Protocol::HTTP} and Rack environments.
 			class Generic
+				# Creates a new adapter instance for the given Rack application.
+				# Wraps the adapter in a {Rewindable} instance to ensure request body can be read multiple times, which is required for Rack < 3.
+				# 
+				# @parameter app [Interface(:call)] A Rack application.
+				# @returns [Rewindable] A rewindable adapter instance.
 				def self.wrap(app)
-					self.new(app)
+					Rewindable.new(self.new(app))
 				end
 				
+				# Parses a Rackup file and returns the application.
+				# 
+				# @parameter path [String] The path to the Rackup file.
+				# @returns [Interface(:call)] The Rack application.
 				def self.parse_file(...)
 					# This is the old interface, which was changed in Rack 3.
 					::Rack::Builder.parse_file(...).first
 				end
 				
 				# Initialize the rack adaptor middleware.
-				# @parameter app [Object] The rack middleware.
+				# 
+				# @parameter app [Interface(:call)] The rack middleware.
+				# @raises [ArgumentError] If the app does not respond to `call`.
 				def initialize(app)
 					@app = app
 					
 					raise ArgumentError, "App must be callable!" unless @app.respond_to?(:call)
 				end
 				
+				# The logger to use for this adapter.
+				# 
+				# @returns [Console] The console logger.
 				def logger
 					Console
 				end
@@ -108,6 +125,10 @@ module Protocol
 					end
 				end
 				
+				# Create a base environment hash for the request.
+				# 
+				# @parameter request [Protocol::HTTP::Request] The incoming request.
+				# @returns [Hash] The base environment hash.
 				def make_environment(request)
 					{
 						request: request
@@ -117,6 +138,8 @@ module Protocol
 				# Build a rack `env` from the incoming request and apply it to the rack middleware.
 				#
 				# @parameter request [Protocol::HTTP::Request] The incoming request.
+				# @returns [Protocol::HTTP::Response] The HTTP response.
+				# @raises [ArgumentError] If the status is not an integer or headers are nil.
 				def call(request)
 					env = self.make_environment(request)
 					
@@ -148,12 +171,18 @@ module Protocol
 				end
 				
 				# Generate a suitable response for the given exception.
-				# @parameter exception [Exception]
-				# @returns [Protocol::HTTP::Response]
+				# 
+				# @parameter exception [Exception] The exception that occurred.
+				# @returns [Protocol::HTTP::Response] A response representing the error.
 				def failure_response(exception)
 					Protocol::HTTP::Response.for_exception(exception)
 				end
 				
+				# Extract protocol information from the environment and response.
+				# 
+				# @parameter env [Hash] The rack environment.
+				# @parameter response [Protocol::HTTP::Response] The HTTP response.
+				# @parameter headers [Hash] The response headers to modify.
 				def self.extract_protocol(env, response, headers)
 					if protocol = response.protocol
 						# This is the newer mechanism for protocol upgrade:

data/lib/protocol/rack/adapter/rack2.rb

@@ -12,16 +12,23 @@ require_relative "../rewindable"
 module Protocol
 	module Rack
 		module Adapter
+			# The Rack 2 adapter provides compatibility with Rack 2.x applications.
+			# It handles the conversion between {Protocol::HTTP} and Rack 2 environments.
 			class Rack2 < Generic
+				# The Rack version constant.
 				RACK_VERSION = "rack.version"
+				# Whether the application is multithreaded.
 				RACK_MULTITHREAD = "rack.multithread"
+				# Whether the application is multiprocess.
 				RACK_MULTIPROCESS = "rack.multiprocess"
+				# Whether the application should run only once.
 				RACK_RUN_ONCE = "rack.run_once"
 				
-				def self.wrap(app)
-					Rewindable.new(self.new(app))
-				end
-				
+				# Create a Rack 2 environment hash for the request.
+				# Sets up all required Rack 2 environment variables and processes the request.
+				# 
+				# @parameter request [Protocol::HTTP::Request] The incoming request.
+				# @returns [Hash] The Rack 2 environment hash.
 				def make_environment(request)
 					request_path, query_string = request.path.split("?", 2)
 					server_name, server_port = (request.authority || "").split(":", 2)
@@ -38,13 +45,13 @@ module Protocol
 						RACK_ERRORS => $stderr,
 						RACK_LOGGER => self.logger,
 
-						# The HTTP request method, such as “GET” or “POST”. This cannot ever be an empty string, and so is always required.
+						# The HTTP request method, such as "GET" or "POST". This cannot ever be an empty string, and so is always required.
 						CGI::REQUEST_METHOD => request.method,
 						
-						# The initial portion of the request URL's “path” that corresponds to the application object, so that the application knows its virtual “location”. This may be an empty string, if the application corresponds to the “root” of the server.
+						# The initial portion of the request URL's "path" that corresponds to the application object, so that the application knows its virtual "location". This may be an empty string, if the application corresponds to the "root" of the server.
 						CGI::SCRIPT_NAME => "",
 						
-						# The remainder of the request URL's “path”, designating the virtual “location” of the request's target within the application. This may be an empty string, if the request URL targets the application root and does not have a trailing slash. This value may be percent-encoded when originating from a URL.
+						# The remainder of the request URL's "path", designating the virtual "location" of the request's target within the application. This may be an empty string, if the request URL targets the application root and does not have a trailing slash. This value may be percent-encoded when originating from a URL.
 						CGI::PATH_INFO => request_path,
 						CGI::REQUEST_PATH => request_path,
 						CGI::REQUEST_URI => request.path,
@@ -75,11 +82,27 @@ module Protocol
 				# Build a rack `env` from the incoming request and apply it to the rack middleware.
 				#
 				# @parameter request [Protocol::HTTP::Request] The incoming request.
+				# @returns [Protocol::HTTP::Response] The HTTP response.
+				# @raises [ArgumentError] If the status is not an integer or headers are nil.
 				def call(request)
 					env = self.make_environment(request)
 					
 					status, headers, body = @app.call(env)
 					
+					if status
+						status = status.to_i
+					else
+						raise ArgumentError, "Status must be an integer!"
+					end
+					
+					unless headers
+						raise ArgumentError, "Headers must not be nil!"
+					end
+					
+					# unless body.respond_to?(:each)
+					# 	raise ArgumentError, "Body must respond to #each!"
+					# end
+					
 					headers, meta = self.wrap_headers(headers)
 					
 					# Rack 2 spec does not allow only partial hijacking.
@@ -96,8 +119,11 @@ module Protocol
 					return failure_response(exception)
 				end
 				
-				# Process the rack response headers into into a {Protocol::HTTP::Headers} instance, along with any extra `rack.` metadata.
-				# @returns [Tuple(Protocol::HTTP::Headers, Hash)]
+				# Process the rack response headers into a {Protocol::HTTP::Headers} instance, along with any extra `rack.` metadata.
+				# Headers with newline-separated values are split into multiple headers.
+				# 
+				# @parameter fields [Hash] The raw response headers.
+				# @returns [Tuple(Protocol::HTTP::Headers, Hash)] The processed headers and metadata.
 				def wrap_headers(fields)
 					headers = ::Protocol::HTTP::Headers.new
 					meta = {}
@@ -119,6 +145,12 @@ module Protocol
 					return headers, meta
 				end
 				
+				# Convert a {Protocol::HTTP::Response} into a Rack 2 response tuple.
+				# Handles protocol upgrades and streaming responses.
+				# 
+				# @parameter env [Hash] The rack environment.
+				# @parameter response [Protocol::HTTP::Response] The HTTP response.
+				# @returns [Tuple(Integer, Hash, Object)] The Rack 2 response tuple [status, headers, body].
 				def self.make_response(env, response)
 					# These interfaces should be largely compatible:
 					headers = response.headers.to_h
@@ -133,7 +165,11 @@ module Protocol
 					end
 					
 					headers.transform_values! do |value|
-						value.is_a?(Array) ? value.join("\n") : value
+						if value.is_a?(Array)
+							value.join("\n")
+						else
+							value
+						end
 					end
 					
 					[response.status, headers, body]

data/lib/protocol/rack/adapter/rack3.rb

@@ -11,15 +11,34 @@ require_relative "generic"
 module Protocol
 	module Rack
 		module Adapter
+			# The Rack 3 adapter provides compatibility with Rack 3.x applications.
+			# It handles the conversion between {Protocol::HTTP} and Rack 3 environments.
+			# Unlike Rack 2, this adapter supports streaming responses and has a simpler environment setup.
 			class Rack3 < Generic
+				# Creates a new adapter instance for the given Rack application.
+				# Unlike Rack 2, this adapter doesn't require a {Rewindable} wrapper.
+				# 
+				# @parameter app [Interface(:call)] A Rack application.
+				# @returns [Rack3] A new adapter instance.
 				def self.wrap(app)
 					self.new(app)
 				end
 				
+				# Parses a Rackup file and returns the application.
+				# Uses the Rack 3.x interface for parsing Rackup files.
+				# 
+				# @parameter path [String] The path to the Rackup file.
+				# @returns [Interface(:call)] The Rack application.
 				def self.parse_file(...)
 					::Rack::Builder.parse_file(...)
 				end
 				
+				# Create a Rack 3 environment hash for the request.
+				# Sets up all required Rack 3 environment variables and processes the request.
+				# Unlike Rack 2, this adapter doesn't set Rack version or threading flags.
+				# 
+				# @parameter request [Protocol::HTTP::Request] The incoming request.
+				# @returns [Hash] The Rack 3 environment hash.
 				def make_environment(request)
 					request_path, query_string = request.path.split("?", 2)
 					server_name, server_port = (request.authority || "").split(":", 2)
@@ -34,13 +53,13 @@ module Protocol
 						# The response finished callbacks:
 						RACK_RESPONSE_FINISHED => [],
 						
-						# The HTTP request method, such as “GET” or “POST”. This cannot ever be an empty string, and so is always required.
+						# The HTTP request method, such as "GET" or "POST". This cannot ever be an empty string, and so is always required.
 						CGI::REQUEST_METHOD => request.method,
 						
-						# The initial portion of the request URL's “path” that corresponds to the application object, so that the application knows its virtual “location”. This may be an empty string, if the application corresponds to the “root” of the server.
+						# The initial portion of the request URL's "path" that corresponds to the application object, so that the application knows its virtual "location". This may be an empty string, if the application corresponds to the "root" of the server.
 						CGI::SCRIPT_NAME => "",
 						
-						# The remainder of the request URL's “path”, designating the virtual “location” of the request's target within the application. This may be an empty string, if the request URL targets the application root and does not have a trailing slash. This value may be percent-encoded when originating from a URL.
+						# The remainder of the request URL's "path", designating the virtual "location" of the request's target within the application. This may be an empty string, if the request URL targets the application root and does not have a trailing slash. This value may be percent-encoded when originating from a URL.
 						CGI::PATH_INFO => request_path,
 						CGI::REQUEST_PATH => request_path,
 						CGI::REQUEST_URI => request.path,
@@ -57,7 +76,7 @@ module Protocol
 						# I'm not sure what sane defaults should be here:
 						CGI::SERVER_NAME => server_name,
 					}
-
+					
 					# SERVER_PORT is optional but must not be set if it is not present.
 					if server_port
 						env[CGI::SERVER_PORT] = server_port
@@ -68,8 +87,11 @@ module Protocol
 					return env
 				end
 				
-				# Process the rack response headers into into a {Protocol::HTTP::Headers} instance, along with any extra `rack.` metadata.
-				# @returns [Tuple(Protocol::HTTP::Headers, Hash)]
+				# Process the rack response headers into a {Protocol::HTTP::Headers} instance, along with any extra `rack.` metadata.
+				# Unlike Rack 2, this adapter handles array values directly without splitting on newlines.
+				# 
+				# @parameter fields [Hash] The raw response headers.
+				# @returns [Tuple(Protocol::HTTP::Headers, Hash)] The processed headers and metadata.
 				def wrap_headers(fields)
 					headers = ::Protocol::HTTP::Headers.new
 					meta = {}
@@ -91,6 +113,13 @@ module Protocol
 					return headers, meta
 				end
 				
+				# Convert a {Protocol::HTTP::Response} into a Rack 3 response tuple.
+				# Handles protocol upgrades and streaming responses.
+				# Unlike Rack 2, this adapter forces streaming responses by converting the body to a callable.
+				# 
+				# @parameter env [Hash] The rack environment.
+				# @parameter response [Protocol::HTTP::Response] The HTTP response.
+				# @returns [Tuple(Integer, Hash, Object)] The Rack 3 response tuple [status, headers, body].
 				def self.make_response(env, response)
 					# These interfaces should be largely compatible:
 					headers = response.headers.to_h

data/lib/protocol/rack/adapter/rack31.rb

@@ -11,7 +11,19 @@ require_relative "rack3"
 module Protocol
 	module Rack
 		module Adapter
+			# The Rack 3.1 adapter provides compatibility with Rack 3.1.x applications.
+			# It extends the Rack 3 adapter with improved request body handling and protocol support.
+			# Key improvements include:
+			# - Better handling of empty request bodies
+			# - Direct protocol support via {RACK_PROTOCOL}
+			# - More efficient body streaming
 			class Rack31 < Rack3
+				# Create a Rack 3.1 environment hash for the request.
+				# Sets up all required Rack 3.1 environment variables and processes the request.
+				# Unlike Rack 3, this adapter has improved body handling and protocol support.
+				# 
+				# @parameter request [Protocol::HTTP::Request] The incoming request.
+				# @returns [Hash] The Rack 3.1 environment hash.
 				def make_environment(request)
 					request_path, query_string = request.path.split("?", 2)
 					server_name, server_port = (request.authority || "").split(":", 2)
@@ -25,13 +37,13 @@ module Protocol
 						# The response finished callbacks:
 						RACK_RESPONSE_FINISHED => [],
 						
-						# The HTTP request method, such as “GET” or “POST”. This cannot ever be an empty string, and so is always required.
+						# The HTTP request method, such as "GET" or "POST". This cannot ever be an empty string, and so is always required.
 						CGI::REQUEST_METHOD => request.method,
 						
-						# The initial portion of the request URL's “path” that corresponds to the application object, so that the application knows its virtual “location”. This may be an empty string, if the application corresponds to the “root” of the server.
+						# The initial portion of the request URL's "path" that corresponds to the application object, so that the application knows its virtual "location". This may be an empty string, if the application corresponds to the "root" of the server.
 						CGI::SCRIPT_NAME => "",
 						
-						# The remainder of the request URL's “path”, designating the virtual “location” of the request's target within the application. This may be an empty string, if the request URL targets the application root and does not have a trailing slash. This value may be percent-encoded when originating from a URL.
+						# The remainder of the request URL's "path", designating the virtual "location" of the request's target within the application. This may be an empty string, if the request URL targets the application root and does not have a trailing slash. This value may be percent-encoded when originating from a URL.
 						CGI::PATH_INFO => request_path,
 						CGI::REQUEST_PATH => request_path,
 						CGI::REQUEST_URI => request.path,
@@ -48,7 +60,7 @@ module Protocol
 						# I'm not sure what sane defaults should be here:
 						CGI::SERVER_NAME => server_name,
 					}
-
+					
 					# SERVER_PORT is optional but must not be set if it is not present.
 					if server_port
 						env[CGI::SERVER_PORT] = server_port

data/lib/protocol/rack/adapter.rb

@@ -1,13 +1,22 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 require "rack"
 
 module Protocol
 	module Rack
+		# The Rack adapter provides a bridge between Protocol::HTTP and Rack applications.
+		# It automatically selects the appropriate implementation based on the installed Rack version.
+		# 
+		# ```ruby
+		# app = ->(env) { [200, {"content-type" => "text/plain"}, ["Hello World"]] }
+		# adapter = Protocol::Rack::Adapter.new(app)
+		# response = adapter.call(request)
+		# ```
 		module Adapter
+			# The version of Rack being used. Can be overridden using the PROTOCOL_RACK_ADAPTER_VERSION environment variable.
 			VERSION = ENV.fetch("PROTOCOL_RACK_ADAPTER_VERSION", ::Rack.release)
 			
 			if VERSION >= "3.1"
@@ -21,14 +30,27 @@ module Protocol
 				IMPLEMENTATION = Rack2
 			end
 			
+			# Creates a new adapter instance for the given Rack application.
+			# 
+			# @parameter app [Interface(:call)] A Rack application that responds to #call
+			# @returns [Protocol::HTTP::Middleware] An adapter that can handle HTTP requests
 			def self.new(app)
 				IMPLEMENTATION.wrap(app)
 			end
 			
+			# Converts a Rack response into a Protocol::HTTP response.
+			# 
+			# @parameter env [Hash] The Rack environment
+			# @parameter response [Array] The Rack response [status, headers, body]
+			# @returns [Protocol::HTTP::Response] A Protocol::HTTP response
 			def self.make_response(env, response)
 				IMPLEMENTATION.make_response(env, response)
 			end
 			
+			# Parses a file path from the Rack environment.
+			# 
+			# @parameter env [Hash] The Rack environment
+			# @returns [String | Nil] The parsed file path or nil if not found
 			def self.parse_file(...)
 				IMPLEMENTATION.parse_file(...)
 			end

data/lib/protocol/rack/body/enumerable.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 require "protocol/http/body/readable"
 require "protocol/http/body/file"
@@ -9,14 +9,19 @@ require "protocol/http/body/file"
 module Protocol
 	module Rack
 		module Body
-			# Wraps the rack response body.
-			#
-			# The `rack` body must respond to `each` and must only yield `String` values. If the body responds to `close`, it will be called after iteration.
+			# Wraps a Rack response body that responds to `each`.
+			# The body must only yield `String` values and may optionally respond to `close`.
+			# This class provides both streaming and buffered access to the response body.
 			class Enumerable < ::Protocol::HTTP::Body::Readable
+				# The content-length header key.
 				CONTENT_LENGTH = "content-length".freeze
 				
-				# Wraps an array into a buffered body.
-				# @parameter body [Object] The `rack` response body.
+				# Wraps a Rack response body into an {Enumerable} instance.
+				# If the body is an Array, its total size is calculated automatically.
+				# 
+				# @parameter body [Object] The Rack response body that responds to `each`.
+				# @parameter length [Integer] Optional content length of the response body.
+				# @returns [Enumerable] A new enumerable body instance.
 				def self.wrap(body, length = nil)
 					if body.is_a?(Array)
 						length ||= body.sum(&:bytesize)
@@ -26,9 +31,10 @@ module Protocol
 					end
 				end
 				
-				# Initialize the output wrapper.
-				# @parameter body [Object] The rack response body.
-				# @parameter length [Integer] The rack response length.
+				# Initialize the enumerable body wrapper.
+				# 
+				# @parameter body [Object] The Rack response body that responds to `each`.
+				# @parameter length [Integer] The content length of the response body.
 				def initialize(body, length)
 					@length = length
 					@body = body
@@ -36,23 +42,32 @@ module Protocol
 					@chunks = nil
 				end
 				
-				# The rack response body.
+				# @attribute [Object] The wrapped Rack response body.
 				attr :body
 				
-				# The content length of the rack response body.
+				# @attribute [Integer] The total size of the response body in bytes.
 				attr :length
 				
-				# Whether the body is empty.
+				# Check if the response body is empty.
+				# A body is considered empty if its length is 0 or if it responds to `empty?` and is empty.
+				# 
+				# @returns [Boolean] True if the body is empty.
 				def empty?
 					@length == 0 or (@body.respond_to?(:empty?) and @body.empty?)
 				end
 				
-				# Whether the body can be read immediately.
+				# Check if the response body can be read immediately.
+				# A body is ready if it's an Array or responds to `to_ary`.
+				# 
+				# @returns [Boolean] True if the body can be read immediately.
 				def ready?
 					body.is_a?(Array) or body.respond_to?(:to_ary)
 				end
 				
 				# Close the response body.
+				# If the body responds to `close`, it will be called.
+				# 
+				# @parameter error [Exception] Optional error that occurred during processing.
 				def close(error = nil)
 					if @body and @body.respond_to?(:close)
 						@body.close
@@ -65,26 +80,43 @@ module Protocol
 				end
 				
 				# Enumerate the response body.
+				# Each chunk yielded must be a String.
+				# The body is automatically closed after enumeration.
+				# 
 				# @yields {|chunk| ...}
-				# 	@parameter chunk [String]
+				# 	@parameter chunk [String] A chunk of the response body.
 				def each(&block)
 					@body.each(&block)
+				rescue => error
+					raise
 				ensure
-					self.close($!)
+					self.close(error)
 				end
 				
+				# Check if the body is a streaming response.
+				# A body is streaming if it doesn't respond to `each`.
+				# 
+				# @returns [Boolean] True if the body is streaming.
 				def stream?
 					!@body.respond_to?(:each)
 				end
 
+				# Stream the response body to the given stream.
+				# The body is automatically closed after streaming.
+				# 
+				# @parameter stream [Object] The stream to write the body to.
 				def call(stream)
 					@body.call(stream)
+				rescue => error
+					raise
 				ensure
-					self.close($!)
+					self.close(error)
 				end
 
 				# Read the next chunk from the response body.
-				# @returns [String | Nil]
+				# Returns nil when there are no more chunks.
+				# 
+				# @returns [String | Nil] The next chunk or nil if there are no more chunks.
 				def read
 					@chunks ||= @body.to_enum(:each)
 					
@@ -93,6 +125,9 @@ module Protocol
 					return nil
 				end
 				
+				# Get a string representation of the body.
+				# 
+				# @returns [String] A string describing the body's class and length.
 				def inspect
 					"\#<#{self.class} length=#{@length.inspect} body=#{@body.class}>"
 				end

data/lib/protocol/rack/body/input_wrapper.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 require "protocol/http/body/readable"
 require "protocol/http/body/stream"
@@ -9,10 +9,17 @@ require "protocol/http/body/stream"
 module Protocol
 	module Rack
 		module Body
-			# Used for wrapping a generic `rack.input` object into a readable body.
+			# Wraps a Rack input object into a readable body.
+			# This class provides a consistent interface for reading from Rack input streams,
+			# which may be any IO-like object that responds to `read` and `close`.
 			class InputWrapper < Protocol::HTTP::Body::Readable
+				# The default block size for reading from the input stream.
 				BLOCK_SIZE = 1024*4
 				
+				# Initialize the input wrapper.
+				# 
+				# @parameter io [Object] The input object that responds to `read` and `close`.
+				# @parameter block_size [Integer] The size of chunks to read at a time.
 				def initialize(io, block_size: BLOCK_SIZE)
 					@io = io
 					@block_size = block_size
@@ -20,6 +27,10 @@ module Protocol
 					super()
 				end
 				
+				# Close the input stream.
+				# If the input object responds to `close`, it will be called.
+				# 
+				# @parameter error [Exception] Optional error that occurred during processing.
 				def close(error = nil)
 					if @io
 						@io.close
@@ -27,12 +38,10 @@ module Protocol
 					end
 				end
 				
-				# def join
-				# 	@io.read.tap do |buffer|
-				# 		buffer.force_encoding(Encoding::BINARY)
-				# 	end
-				# end
-				
+				# Read the next chunk from the input stream.
+				# Returns nil when there is no more data to read.
+				# 
+				# @returns [String | Nil] The next chunk of data or nil if there is no more data.
 				def read
 					@io&.read(@block_size)
 				end

data/lib/protocol/rack/body.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 require_relative "body/streaming"
 require_relative "body/enumerable"
@@ -10,13 +10,34 @@ require "protocol/http/body/completable"
 
 module Protocol
 	module Rack
+		# The Body module provides functionality for handling Rack response bodies.
+		# It includes methods for wrapping different types of response bodies and handling completion callbacks.
 		module Body
+			# The `content-length` header key.
 			CONTENT_LENGTH = "content-length"
 			
+			# Check if the given status code indicates no content should be returned.
+			# Status codes 204 (No Content), 205 (Reset Content), and 304 (Not Modified) should not include a response body.
+			# 
+			# @parameter status [Integer] The HTTP status code.
+			# @returns [Boolean] True if the status code indicates no content.
 			def self.no_content?(status)
 				status == 204 or status == 205 or status == 304
 			end
 			
+			# Wrap a Rack response body into a {Protocol::HTTP::Body} instance.
+			# Handles different types of response bodies:
+			# - {Protocol::HTTP::Body::Readable} instances are returned as-is.
+			# - Bodies that respond to `to_path` are wrapped in {Protocol::HTTP::Body::File}.
+			# - Enumerable bodies are wrapped in {Body::Enumerable}.
+			# - Other bodies are wrapped in {Body::Streaming}.
+			# 
+			# @parameter env [Hash] The Rack environment.
+			# @parameter status [Integer] The HTTP status code.
+			# @parameter headers [Hash] The response headers.
+			# @parameter body [Object] The response body to wrap.
+			# @parameter input [Object] Optional input for streaming bodies.
+			# @returns [Protocol::HTTP::Body] The wrapped response body.
 			def self.wrap(env, status, headers, body, input = nil)
 				# In no circumstance do we want this header propagating out:
 				if length = headers.delete(CONTENT_LENGTH)
@@ -66,6 +87,14 @@ module Protocol
 				return body
 			end
 			
+			# Create a completion callback for response finished handlers.
+			# The callback is called with any error that occurred during response processing.
+			# 
+			# @parameter response_finished [Array] Array of response finished callbacks.
+			# @parameter env [Hash] The Rack environment.
+			# @parameter status [Integer] The HTTP status code.
+			# @parameter headers [Hash] The response headers.
+			# @returns [Proc] A callback that calls all response finished handlers.
 			def self.completion_callback(response_finished, env, status, headers)
 				proc do |error|
 					response_finished.each do |callback|

data/lib/protocol/rack/input.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 # Copyright, 2023, by Genki Takiuchi.
 
 require "protocol/http/body/stream"
@@ -64,8 +64,10 @@ module Protocol
 				if @body and @body.respond_to?(:rewind)
 					# If the body is not rewindable, this will fail.
 					@body.rewind
+					
 					@buffer = nil
 					@finished = false
+					@closed = false
 					
 					return true
 				end
@@ -93,14 +95,18 @@ module Protocol
 						# https://github.com/socketry/async-http/issues/183
 						if @body.empty?
 							@body.close
-							@body = nil
+							@closed = true
 						end
 						
 						return chunk
 					else
-						# So if we are at the end of the stream, we close it automatically:
-						@body.close
-						@body = nil
+						unless @closed
+							# So if we are at the end of the stream, we close it automatically:
+							@body.close
+							@closed = true
+						end
+						
+						return nil
 					end
 				elsif @closed
 					raise IOError, "Stream is not readable, input has been closed!"

data/lib/protocol/rack/request.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 require "protocol/http/request"
 require "protocol/http/headers"
@@ -11,11 +11,22 @@ require_relative "body/input_wrapper"
 
 module Protocol
 	module Rack
+		# A Rack-compatible HTTP request wrapper.
+		# This class provides a bridge between Rack's environment hash and Protocol::HTTP::Request.
+		# It handles conversion of Rack environment variables to HTTP request properties.
 		class Request < ::Protocol::HTTP::Request
+			# Get or create a Request instance for the given Rack environment.
+			# The request is cached in the environment to avoid creating multiple instances.
+			# 
+			# @parameter env [Hash] The Rack environment hash.
+			# @returns [Request] A Request instance for the environment.
 			def self.[](env)
 				env["protocol.http.request"] ||= new(env)
 			end
 
+			# Initialize a new Request instance from a Rack environment.
+			# 
+			# @parameter env [Hash] The Rack environment hash.
 			def initialize(env)
 				@env = env
 
@@ -31,6 +42,11 @@ module Protocol
 				)
 			end
 
+			# Extract the protocol list from the Rack environment.
+			# Checks both `rack.protocol` and `HTTP_UPGRADE` headers.
+			# 
+			# @parameter env [Hash] The Rack environment hash.
+			# @returns [Array(String) | Nil] The list of protocols or `nil` if none specified.
 			def self.protocol(env)
 				if protocols = env["rack.protocol"]
 					return Array(protocols)
@@ -39,6 +55,11 @@ module Protocol
 				end
 			end
 
+			# Extract HTTP headers from the Rack environment.
+			# Converts Rack's `HTTP_*` environment variables to proper HTTP headers.
+			# 
+			# @parameter env [Hash] The Rack environment hash.
+			# @returns [Protocol::HTTP::Headers] The extracted HTTP headers.
 			def self.headers(env)
 				headers = ::Protocol::HTTP::Headers.new
 				env.each do |key, value|

data/lib/protocol/rack/response.rb

@@ -5,10 +5,10 @@
 
 require_relative "body"
 require_relative "constants"
-# require 'time'
 
 require "protocol/http/response"
 require "protocol/http/headers"
+require "protocol/http/body/head"
 
 module Protocol
 	module Rack

data/lib/protocol/rack/rewindable.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 require "protocol/http/body/rewindable"
 require "protocol/http/middleware"
@@ -9,8 +9,12 @@ require "protocol/http/middleware"
 module Protocol
 	module Rack
 		# Content-type driven input buffering, specific to the needs of `rack`.
+		# This middleware ensures that request bodies for certain content types
+		# can be read multiple times, which is required by Rack's specification.
 		class Rewindable < ::Protocol::HTTP::Middleware
 			# Media types that require buffering.
+			# These types typically contain form data or file uploads that may need
+			# to be read multiple times by Rack applications.
 			BUFFERED_MEDIA_TYPES = %r{
 				application/x-www-form-urlencoded|
 				multipart/form-data|
@@ -18,17 +22,23 @@ module Protocol
 				multipart/mixed
 			}x
 			
+			# The HTTP POST method.
 			POST = "POST"
 			
 			# Initialize the rewindable middleware.
+			# 
 			# @parameter app [Protocol::HTTP::Middleware] The middleware to wrap.
 			def initialize(app)
 				super(app)
 			end
 			
 			# Determine whether the request needs a rewindable body.
-			# @parameter request [Protocol::HTTP::Request]
-			# @returns [Boolean]
+			# A request needs a rewindable body if:
+			# - It's a POST request with no content type (legacy behavior)
+			# - It has a content type that matches BUFFERED_MEDIA_TYPES
+			# 
+			# @parameter request [Protocol::HTTP::Request] The request to check.
+			# @returns [Boolean] True if the request body should be rewindable.
 			def needs_rewind?(request)
 				content_type = request.headers["content-type"]
 				
@@ -43,13 +53,20 @@ module Protocol
 				return false
 			end
 			
+			# Create a Rack environment from the request.
+			# Delegates to the wrapped middleware.
+			# 
+			# @parameter request [Protocol::HTTP::Request] The request to create an environment from.
+			# @returns [Hash] The Rack environment hash.
 			def make_environment(request)
 				@delegate.make_environment(request)
 			end
 			
 			# Wrap the request body in a rewindable buffer if required.
-			# @parameter request [Protocol::HTTP::Request]
-			# @returns [Protocol::HTTP::Response] the response.
+			# If the request needs a rewindable body, wraps it in a {Protocol::HTTP::Body::Rewindable}.
+			# 
+			# @parameter request [Protocol::HTTP::Request] The request to process.
+			# @returns [Protocol::HTTP::Response] The response from the wrapped middleware.
 			def call(request)
 				if body = request.body and needs_rewind?(request)
 					request.body = Protocol::HTTP::Body::Rewindable.new(body)

data/lib/protocol/rack/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module Rack
-		VERSION = "0.12.0"
+		VERSION = "0.13.0"
 	end
 end

data/lib/protocol/rack.rb

@@ -1,9 +1,16 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 require_relative "rack/version"
 require_relative "rack/adapter"
 require_relative "rack/request"
 require_relative "rack/response"
+
+# @namespace
+module Protocol
+	# @namespace
+	module Rack
+	end
+end

data/readme.md

@@ -67,6 +67,16 @@ run proc{|env|
 
 Please see the [project releases](https://socketry.github.io/protocol-rack/releases/index) for all releases.
 
+### v0.13.0
+
+  - 100% test and documentation coverage.
+  - `Protocol::Rack::Input#rewind` now works when the entire input is already read.
+  - `Protocol::Rack::Adapter::Rack2` has stricter validation of the application response.
+
+### v0.12.0
+
+  - Ignore (and close) response bodies for status codes that don't allow them.
+
 ### v0.11.2
 
   - Stop setting `env["SERVER_PORT"]` to `nil` if not present.

data/releases.md

@@ -1,5 +1,15 @@
 # Releases
 
+## v0.13.0
+
+  - 100% test and documentation coverage.
+  - {Protocol::Rack::Input\#rewind} now works when the entire input is already read.
+  - {Protocol::Rack::Adapter::Rack2} has stricter validation of the application response.
+
+## v0.12.0
+
+  - Ignore (and close) response bodies for status codes that don't allow them.
+
 ## v0.11.2
 
   - Stop setting `env["SERVER_PORT"]` to `nil` if not present.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-rack
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -38,7 +38,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-04-29 00:00:00.000000000 Z
+date: 2025-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: protocol-http