Improved code and documentation coverage. (#26)

Author: ioquatix

fixtures/disable_console_context.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022-2025, by Samuel Williams.
+
+require "sus/fixtures/async/http/server_context"
+
+module Protocol
+	module Rack
+		module ServerContext
+			include Sus::Fixtures::Async::HTTP::ServerContext
+			
+			def app
+				->(env){[200, {}, ["Hello World!"]]}
+			end
+			
+			def middleware
+				Protocol::Rack::Adapter.new(app)
+			end
+		end
+	end
+end

fixtures/protocol/rack/server_context.rb

@@ -23,6 +23,7 @@
 
 	gem "sus-fixtures-async"
 	gem "sus-fixtures-async-http"
+	gem "sus-fixtures-console"
 
 	gem "bake-test"
 	gem "bake-test-external"

fixtures/server_context.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023, by Samuel Williams.
+# Copyright, 2023-2025, by Samuel Williams.
 
 source "https://rubygems.org"
 
@@ -10,4 +10,5 @@
 gem "bake-test-external"
 gem "sus"
 gem "sus-fixtures-async-http"
+gem "sus-fixtures-console"
 gem "covered"

gems.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

gems/gems.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 Adapter
 				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

lib/protocol/rack.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 @@ def unwrap_request(request, env)
 					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 @@ def make_environment(request)
 				# 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 @@ def call(request)
 				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:

lib/protocol/rack/adapter.rb

@@ -12,16 +12,23 @@
 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 @@ def make_environment(request)
 						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 @@ def make_environment(request)
 				# 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 @@ def call(request)
 					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 @@ def wrap_headers(fields)
 					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