100% documentation coverage.

Author: ioquatix

lib/protocol/rack.rb

@@ -7,3 +7,10 @@
 require_relative "rack/adapter"
 require_relative "rack/request"
 require_relative "rack/response"
+
+# @namespace
+module Protocol
+	# @namespace
+	module Rack
+	end
+end

lib/protocol/rack/adapter.rb

@@ -7,7 +7,16 @@
 
 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/adapter/generic.rb

@@ -12,28 +12,40 @@
 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
 
-				def self.streaming?
-					false
-				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
@@ -112,6 +124,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
@@ -121,6 +137,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)
 
@@ -152,12 +170,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/rack2.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,6 +82,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)
 
@@ -110,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 = {}
@@ -133,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

lib/protocol/rack/adapter/rack3.rb

@@ -11,19 +11,42 @@
 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
 
+				# Whether this adapter supports streaming responses.
+				# Rack 3 supports streaming responses by default.
+				# 
+				# @returns [Boolean] Always true for the Rack 3 adapter.
 				def self.streaming?
 					true
 				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)
@@ -38,13 +61,13 @@ def make_environment(request)
 						# 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,
@@ -72,8 +95,11 @@ def make_environment(request)
 					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 = {}
@@ -95,6 +121,13 @@ def wrap_headers(fields)
 					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

lib/protocol/rack/adapter/rack31.rb

@@ -11,7 +11,19 @@
 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 @@ def make_environment(request)
 						# 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,

lib/protocol/rack/body.rb

@@ -10,13 +10,34 @@
 
 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 @@ def self.wrap(env, status, headers, body, input = nil)
 				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|