100% documentation coverage.

Author: samuel-williams-shopify

lib/async/http.rb

@@ -4,10 +4,7 @@
 # Copyright, 2017-2024, by Samuel Williams.
 
 require_relative "http/version"
-
 require_relative "http/client"
 require_relative "http/server"
-
 require_relative "http/internet"
-
 require_relative "http/endpoint"

lib/async/http/body.rb

@@ -6,8 +6,11 @@
 require "protocol/http/body/buffered"
 require_relative "body/writable"
 
+# @namespace
 module Async
+	# @namespace
 	module HTTP
+		# @namespace
 		module Body
 			include ::Protocol::HTTP::Body
 		end

lib/async/http/body/hijack.rb

@@ -13,14 +13,25 @@ module HTTP
 		module Body
 			# A body which is designed for hijacked server responses - a response which uses a block to read and write the request and response bodies respectively.
 			class Hijack < ::Protocol::HTTP::Body::Readable
+				# Create a response with this hijacked body.
+				# @parameter request [Protocol::HTTP::Request] The request to hijack.
+				# @parameter status [Integer] The HTTP status code.
+				# @parameter headers [Hash] The response headers.
+				# @returns [Protocol::HTTP::Response] The response with the hijacked body.
 				def self.response(request, status, headers, &block)
 					::Protocol::HTTP::Response[status, headers, self.wrap(request, &block)]
 				end
 
+				# Wrap a request body with a hijacked body.
+				# @parameter request [Protocol::HTTP::Request | Nil] The request to hijack.
+				# @returns [Hijack] The hijacked body instance.
 				def self.wrap(request = nil, &block)
 					self.new(block, request&.body)
 				end
 
+				# Initialize the hijacked body.
+				# @parameter block [Proc] The block to call with the stream.
+				# @parameter input [Protocol::HTTP::Body::Readable | Nil] The input body to read from.
 				def initialize(block, input = nil)
 					@block = block
 					@input = input
@@ -35,6 +46,8 @@ def stream?
 					true
 				end
 
+				# Invoke the block with the given stream for bidirectional communication.
+				# @parameter stream [Protocol::HTTP::Body::Stream] The stream to pass to the block.
 				def call(stream)
 					@block.call(stream)
 				end
@@ -46,6 +59,8 @@ def empty?
 					@output&.empty?
 				end
 
+				# Whether the body has output ready to be read.
+				# @returns [Boolean | Nil]
 				def ready?
 					@output&.ready?
 				end
@@ -66,10 +81,12 @@ def read
 					return @output.read
 				end
 
+				# @returns [String] A detailed representation of this body.
 				def inspect
 					"\#<#{self.class} #{@block.inspect}>"
 				end
 
+				# @returns [String] A short summary of this body.
 				def to_s
 					"<Hijack #{@block.class}>"
 				end

lib/async/http/body/pipe.rb

@@ -9,6 +9,7 @@
 module Async
 	module HTTP
 		module Body
+			# A bidirectional pipe that connects an input body to an output body using a Unix socket pair.
 			class Pipe
 				# If the input stream is closed first, it's likely the output stream will also be closed.
 				def initialize(input, output = Writable.new, task: Task.current)
@@ -27,10 +28,12 @@ def initialize(input, output = Writable.new, task: Task.current)
 					task.async(transient: true, &self.method(:writer))
 				end
 
+				# @returns [IO] The underlying IO object for the tail of the pipe.
 				def to_io
 					@tail
 				end
 
+				# Close the pipe and stop the reader and writer tasks.
 				def close
 					@reader&.stop
 					@writer&.stop

lib/async/http/client.rb

@@ -17,6 +17,7 @@ module Async
 	module HTTP
 		DEFAULT_RETRIES = 3
 
+		# An HTTP client that manages persistent connections to a specific endpoint, with automatic retries for idempotent requests.
 		class Client < ::Protocol::HTTP::Methods
 			# Provides a robust interface to a server.
 			# * If there are no connections, it will create one.
@@ -38,16 +39,18 @@ def initialize(endpoint, protocol: endpoint.protocol, scheme: endpoint.scheme, a
 				@authority = authority
 			end
 
+			# @returns [Hash] A JSON-compatible representation of this client.
 			def as_json(...)
 				{
 					endpoint: @endpoint.to_s,
-					protocol: @protocol,
-					retries: @retries,
-					scheme: @scheme,
-					authority: @authority,
+						protocol: @protocol,
+						retries: @retries,
+						scheme: @scheme,
+						authority: @authority,
 				}
 			end
 
+			# @returns [String] A JSON string representation of this client.
 			def to_json(...)
 				as_json.to_json(...)
 			end
@@ -61,10 +64,14 @@ def to_json(...)
 			attr :scheme
 			attr :authority
 
+			# @returns [Boolean] Whether the client uses a secure (TLS) connection.
 			def secure?
 				@endpoint.secure?
 			end
 
+			# Open a client and optionally yield it, ensuring it is closed afterwards.
+			# @parameter arguments [Array] Arguments to pass to {initialize}.
+			# @parameter options [Hash] Options to pass to {initialize}.
 			def self.open(*arguments, **options, &block)
 				client = self.new(*arguments, **options)
 
@@ -77,6 +84,7 @@ def self.open(*arguments, **options, &block)
 				end
 			end
 
+			# Close the client and all associated connections.
 			def close
 				@pool.wait_until_free do
 					Console.warn(self){"Waiting for #{@protocol} pool to drain: #{@pool}"}
@@ -85,6 +93,9 @@ def close
 				@pool.close
 			end
 
+			# Send a request to the remote server, with automatic retries for idempotent requests.
+			# @parameter request [Protocol::HTTP::Request] The request to send.
+			# @returns [Protocol::HTTP::Response] The response from the server.
 			def call(request)
 				request.scheme ||= self.scheme
 				request.authority ||= self.authority
@@ -133,6 +144,7 @@ def call(request)
 				end
 			end
 
+			# @returns [String] A summary of this client.
 			def inspect
 				"#<#{self.class} authority=#{@authority.inspect}>"
 			end

lib/async/http/endpoint.rb

@@ -28,6 +28,11 @@ class Endpoint < ::IO::Endpoint::Generic
 				"wss" => URI::WSS,
 			}
 
+			# Parse a URL string into an endpoint.
+			# @parameter string [String] The URL to parse.
+			# @parameter endpoint [IO::Endpoint::Generic | Nil] An optional underlying endpoint to use.
+			# @parameter options [Hash] Additional options to pass to {initialize}.
+			# @returns [Endpoint] The parsed endpoint.
 			def self.parse(string, endpoint = nil, **options)
 				url = URI.parse(string).normalize
 
@@ -80,6 +85,7 @@ def initialize(url, endpoint = nil, **options)
 				end
 			end
 
+			# @returns [URI] The URL representation of this endpoint, including port if non-default.
 			def to_url
 				url = @url.dup
 
@@ -90,24 +96,29 @@ def to_url
 				return url
 			end
 
+			# @returns [String] A short string representation of this endpoint.
 			def to_s
 				"\#<#{self.class} #{self.to_url} #{@options}>"
 			end
 
+			# @returns [String] A detailed string representation of this endpoint.
 			def inspect
 				"\#<#{self.class} #{self.to_url} #{@options.inspect}>"
 			end
 
 			attr :url
 
+			# @returns [Addrinfo] The address of the underlying endpoint.
 			def address
 				endpoint.address
 			end
 
+			# @returns [Boolean] Whether this endpoint uses a secure protocol (HTTPS or WSS).
 			def secure?
 				["https", "wss"].include?(self.scheme)
 			end
 
+			# @returns [Protocol] The protocol to use for this endpoint.
 			def protocol
 				@options.fetch(:protocol) do
 					if secure?
@@ -118,14 +129,17 @@ def protocol
 				end
 			end
 
+			# @returns [Integer] The default port for this endpoint's scheme.
 			def default_port
 				secure? ? 443 : 80
 			end
 
+			# @returns [Boolean] Whether the endpoint's port is the default for its scheme.
 			def default_port?
 				port == default_port
 			end
 
+			# @returns [Integer] The port number for this endpoint.
 			def port
 				@options[:port] || @url.port || default_port
 			end
@@ -135,10 +149,12 @@ def hostname
 				@options[:hostname] || @url.hostname
 			end
 
+			# @returns [String] The URL scheme, e.g. `"http"` or `"https"`.
 			def scheme
 				@options[:scheme] || @url.scheme
 			end
 
+			# @returns [String] The authority component (hostname and optional port).
 			def authority(ignore_default_port = true)
 				if ignore_default_port and default_port?
 					@url.hostname
@@ -158,10 +174,12 @@ def path
 				return buffer
 			end
 
+			# @returns [Array(String)] The ALPN protocol names for TLS negotiation.
 			def alpn_protocols
 				@options.fetch(:alpn_protocols){self.protocol.names}
 			end
 
+			# @returns [Boolean] Whether the endpoint refers to a localhost address.
 			def localhost?
 				@url.hostname =~ /^(.*?\.)?localhost\.?$/
 			end
@@ -175,6 +193,7 @@ def ssl_verify_mode
 				end
 			end
 
+			# @returns [OpenSSL::SSL::SSLContext] The SSL context for TLS connections.
 			def ssl_context
 				@options[:ssl_context] || OpenSSL::SSL::SSLContext.new.tap do |context|
 					if alpn_protocols = self.alpn_protocols
@@ -187,6 +206,9 @@ def ssl_context
 				end
 			end
 
+			# Build a suitable endpoint, optionally wrapping in TLS for secure connections.
+			# @parameter endpoint [IO::Endpoint::Generic | Nil] An optional underlying endpoint to wrap.
+			# @returns [IO::Endpoint::Generic] The constructed endpoint.
 			def build_endpoint(endpoint = nil)
 				endpoint ||= tcp_endpoint
 
@@ -202,22 +224,30 @@ def build_endpoint(endpoint = nil)
 				return endpoint
 			end
 
+			# @returns [IO::Endpoint::Generic] The resolved endpoint, built on demand.
 			def endpoint
 				@endpoint ||= build_endpoint
 			end
 
+			# Set the underlying endpoint, wrapping it as needed.
+			# @parameter endpoint [IO::Endpoint::Generic] The endpoint to assign.
 			def endpoint=(endpoint)
 				@endpoint = build_endpoint(endpoint)
 			end
 
+			# Bind to the endpoint.
 			def bind(*arguments, &block)
 				endpoint.bind(*arguments, &block)
 			end
 
+			# Connect to the endpoint.
 			def connect(&block)
 				endpoint.connect(&block)
 			end
 
+			# Enumerate all resolved endpoints.
+			# @yields {|endpoint| ...} Each resolved endpoint.
+			# 	@parameter endpoint [Endpoint] The resolved endpoint.
 			def each
 				return to_enum unless block_given?
 
@@ -226,14 +256,17 @@ def each
 				end
 			end
 
+			# @returns [Array] A key suitable for identifying this endpoint in a hash.
 			def key
 				[@url, @options]
 			end
 
+			# @returns [Boolean] Whether two endpoints are equal.
 			def eql? other
 				self.key.eql? other.key
 			end
 
+			# @returns [Integer] The hash code for this endpoint.
 			def hash
 				self.key.hash
 			end

lib/async/http/internet.rb

@@ -13,7 +13,10 @@
 
 module Async
 	module HTTP
+		# A high-level HTTP client for making requests to any URL, managing a pool of persistent connections keyed by host.
 		class Internet
+			# Initialize the internet client.
+			# @parameter options [Hash] Options to pass to the underlying {Client} instances.
 			def initialize(**options)
 				@clients = Hash.new
 				@options = options
@@ -23,6 +26,9 @@ def initialize(**options)
 			# @attribute [Hash(URI, Client)]
 			attr :clients
 
+			# Get or create a client for the given endpoint.
+			# @parameter endpoint [Endpoint] The endpoint to connect to.
+			# @returns [Client] A client suitable for making requests to the endpoint.
 			def client_for(endpoint)
 				key = host_key(endpoint)
 
@@ -59,6 +65,7 @@ def call(verb, url, *arguments, **options, &block)
 				end
 			end
 
+			# Close all cached clients and release their resources.
 			def close
 				# The order of operations here is to avoid a race condition between iterating over clients (#close may yield) and creating new clients.
 				clients = @clients.values

lib/async/http/middleware/location_redirector.rb

@@ -9,6 +9,7 @@
 
 module Async
 	module HTTP
+		# @namespace
 		module Middleware
 			# A client wrapper which transparently handles redirects to a given maximum number of hops.
 			#
@@ -28,6 +29,7 @@ module Middleware
 			# - <https://datatracker.ietf.org/doc/html/rfc7231#section-6-4-7> 307 Temporary Redirect.
 			#
 			class LocationRedirector < ::Protocol::HTTP::Middleware
+				# Raised when the maximum number of redirects has been exceeded.
 				class TooManyRedirects < StandardError
 				end
 
@@ -49,6 +51,10 @@ def initialize(app, maximum_hops = 3)
 				# The maximum number of hops which will limit the number of redirects until an error is thrown.
 				attr :maximum_hops
 
+				# Determine whether the redirect should switch the request method to GET.
+				# @parameter request [Protocol::HTTP::Request] The original request.
+				# @parameter response [Protocol::HTTP::Response] The redirect response.
+				# @returns [Boolean] Whether the method should be changed to GET.
 				def redirect_with_get?(request, response)
 					# We only want to switch to GET if the request method is something other than get, e.g. POST.
 					if request.method != GET
@@ -76,6 +82,9 @@ def handle_redirect(request, location)
 					return true
 				end
 
+				# Make a request, transparently following redirects up to {maximum_hops} times.
+				# @parameter request [Protocol::HTTP::Request] The request to send.
+				# @returns [Protocol::HTTP::Response] The final response.
 				def call(request)
 					# We don't want to follow redirects for HEAD requests:
 					return super if request.head?