async-http 0.94.2 → 0.94.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e47e3773a940f0a7218dacb8f188531c1d5d42a12ad4708688011953135a6b1
-  data.tar.gz: 9cb9fa6ca50c1a31ca46f1c9bad7e678ae2bd78d041ae839714e92832e5b1fec
+  metadata.gz: 391e059d6c94805257b5e058b02987ad88ce8decaafafb6e7815faeaeb8a5079
+  data.tar.gz: 2a260bb8dba2ffb109f612400d9e05c03012f994c275f6c447a09d915cbd186e
 SHA512:
-  metadata.gz: aaa2d45e58a66255a71ab802e5a4706d8c09ac85665e7004c5c06e91bc38cc919f18229b5670e411df13364e09ad243bf8d45c3d68a361ad8653861f2527a8cb
-  data.tar.gz: 16a4894930c5a3ce0611de7b4840aecf9d050b9de59e8dc0da2b0803978bbd47933f9066850c7d0d596f1f6ed609047f31007b742ea2d822fd8b36499580dfb0
+  metadata.gz: a882c3dcb76b5b601c7601a1875a8708ec301e510cb74f77e9a4060ac5ae9e199fec3c41b3bcdc7d1eb125d81aea8c8f50ba70d9e5fb7d3c832aa8ebbc97d518
+  data.tar.gz: ce9455361a23462bec86b7a1272665e411d130dd994df79e2d1c7fc0769a11f33ae3eb6628b9a5ced3b197bfd0bb5dd06a0e252cd0475fd013ef90eaee767682

data/lib/async/http/body/hijack.rb

@@ -13,14 +13,25 @@ module Async
 		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 @@ module Async
 					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 @@ module Async
 					@output&.empty?
 				end
 				
+				# Whether the body has output ready to be read.
+				# @returns [Boolean | Nil]
 				def ready?
 					@output&.ready?
 				end
@@ -66,10 +81,12 @@ module Async
 					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

data/lib/async/http/body/pipe.rb

@@ -9,6 +9,7 @@ require_relative "writable"
 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 @@ module Async
 					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

data/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

data/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 @@ module Async
 				@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 @@ module Async
 			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 @@ module Async
 				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 @@ module Async
 				@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 @@ module Async
 				end
 			end
 			
+			# @returns [String] A summary of this client.
 			def inspect
 				"#<#{self.class} authority=#{@authority.inspect}>"
 			end

data/lib/async/http/endpoint.rb

@@ -28,6 +28,11 @@ module Async
 				"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 @@ module Async
 				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 @@ module Async
 				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 @@ module Async
 				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 @@ module Async
 				@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 @@ module Async
 				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 @@ module Async
 				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 @@ module Async
 				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 @@ module Async
 				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 @@ module Async
 				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

data/lib/async/http/internet.rb

@@ -13,7 +13,10 @@ require "protocol/http/accept_encoding"
 
 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 @@ module Async
 			# @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 @@ module Async
 				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

data/lib/async/http/middleware/location_redirector.rb

@@ -9,6 +9,7 @@ require "protocol/url/reference"
 
 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 Async
 			# - <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 @@ module Async
 				# 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 @@ module Async
 					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?

data/lib/async/http/mock/endpoint.rb

@@ -9,9 +9,14 @@ require "async/queue"
 
 module Async
 	module HTTP
+		# @namespace
 		module Mock
 			# This is an endpoint which bridges a client with a local server.
 			class Endpoint
+				# Initialize a mock endpoint for testing.
+				# @parameter protocol [Protocol] The protocol to use for connections.
+				# @parameter scheme [String] The URL scheme.
+				# @parameter authority [String] The hostname authority.
 				def initialize(protocol = Protocol::HTTP2, scheme = "http", authority = "localhost", queue: Queue.new)
 					@protocol = protocol
 					@scheme = scheme
@@ -36,6 +41,8 @@ module Async
 					end
 				end
 				
+				# Create a new client-side connection by enqueuing the server-side socket.
+				# @returns [Socket] The client-side socket.
 				def connect
 					local, remote = ::Socket.pair(Socket::AF_UNIX, Socket::SOCK_STREAM)
 					
@@ -44,6 +51,9 @@ module Async
 					return local
 				end
 				
+				# Create a new mock endpoint that shares the same connection queue but adopts another endpoint's scheme and authority.
+				# @parameter endpoint [Endpoint] The endpoint to mirror the scheme and authority from.
+				# @returns [Endpoint] A new mock endpoint.
 				def wrap(endpoint)
 					self.class.new(@protocol, endpoint.scheme, endpoint.authority, queue: @queue)
 				end

data/lib/async/http/protocol/configurable.rb

@@ -6,7 +6,11 @@
 module Async
 	module HTTP
 		module Protocol
+			# A protocol wrapper that forwards pre-configured options to client and server creation.
 			class Configured
+				# Initialize with a protocol and options.
+				# @parameter protocol [Protocol] The underlying protocol to configure.
+				# @parameter options [Hash] Options to forward to client and server creation.
 				def initialize(protocol, **options)
 					@protocol = protocol
 					@options = options
@@ -18,22 +22,33 @@ module Async
 				# @attribute [Hash] The options to pass to the protocol.
 				attr :options
 				
+				# Create a client connection using the configured protocol options.
+				# @parameter peer [IO] The peer to communicate with.
+				# @parameter options [Hash] Additional options merged with the configured defaults.
 				def client(peer, **options)
 					options = @options.merge(options)
 					@protocol.client(peer, **options)
 				end
 				
+				# Create a server connection using the configured protocol options.
+				# @parameter peer [IO] The peer to communicate with.
+				# @parameter options [Hash] Additional options merged with the configured defaults.
 				def server(peer, **options)
 					options = @options.merge(options)
 					@protocol.server(peer, **options)
 				end
 				
+				# @returns [Array(String)] The protocol names from the underlying protocol.
 				def names
 					@protocol.names
 				end
 			end
 			
+			# Provides a `new` method that creates a {Configured} wrapper, allowing protocols to be instantiated with custom options.
 			module Configurable
+				# Create a new {Configured} instance wrapping this protocol with the given options.
+				# @parameter options [Hash] Configuration options for client and server creation.
+				# @returns [Configured] A configured protocol instance.
 				def new(**options)
 					Configured.new(self, **options)
 				end

data/lib/async/http/protocol/http1/client.rb

@@ -9,7 +9,9 @@ module Async
 	module HTTP
 		module Protocol
 			module HTTP1
+				# An HTTP/1 client connection that sends requests and reads responses.
 				class Client < Connection
+					# Initialize the HTTP/1 client connection.
 					def initialize(...)
 						super
 						
@@ -18,6 +20,7 @@ module Async
 					
 					attr_accessor :pool
 					
+					# Called when the connection is closed, releasing it back to the pool.
 					def closed(error = nil)
 						super
 						

data/lib/async/http/protocol/http1/connection.rb

@@ -13,7 +13,12 @@ module Async
 	module HTTP
 		module Protocol
 			module HTTP1
+				# An HTTP/1 connection that wraps an IO stream with version and state tracking.
 				class Connection < ::Protocol::HTTP1::Connection
+					# Initialize the connection with an IO stream and HTTP version.
+					# @parameter stream [IO::Stream] The underlying stream.
+					# @parameter version [String] The negotiated HTTP version string.
+					# @parameter options [Hash] Additional options for the connection.
 					def initialize(stream, version, **options)
 						super(stream, **options)
 						
@@ -21,34 +26,41 @@ module Async
 						@version = version
 					end
 					
+					# @returns [String] A string representation of this connection.
 					def to_s
 						"\#<#{self.class} negotiated #{@version}, #{@state}>"
 					end
 					
+					# @returns [String] A JSON-compatible representation.
 					def as_json(...)
 						to_s
 					end
 					
+					# @returns [String] A JSON string representation.
 					def to_json(...)
 						as_json.to_json(...)
 					end
 					
 					attr :version
 					
+					# @returns [Boolean] Whether this is an HTTP/1 connection.
 					def http1?
 						true
 					end
 					
+					# @returns [Boolean] Whether this is an HTTP/2 connection.
 					def http2?
 						false
 					end
 					
+					# @returns [Protocol::HTTP::Peer] The peer information for this connection.
 					def peer
 						@peer ||= ::Protocol::HTTP::Peer.for(@stream.io)
 					end
 					
 					attr :count
 					
+					# @returns [Integer] The maximum number of concurrent requests (always 1 for HTTP/1).
 					def concurrency
 						1
 					end
@@ -58,6 +70,7 @@ module Async
 						self.idle? && @stream&.readable?
 					end
 					
+					# @returns [Boolean] Whether the connection can be reused for another request.
 					def reusable?
 						@persistent && @stream && !@stream.closed?
 					end

data/lib/async/http/protocol/http1/finishable.rb

@@ -12,6 +12,8 @@ module Async
 			module HTTP1
 				# Keeps track of whether a body is being read, and if so, waits for it to be closed.
 				class Finishable < ::Protocol::HTTP::Body::Wrapper
+					# Initialize the finishable wrapper.
+					# @parameter body [Protocol::HTTP::Body::Readable] The body to wrap.
 					def initialize(body)
 						super(body)
 						
@@ -21,16 +23,20 @@ module Async
 						@reading = false
 					end
 					
+					# @returns [Boolean] Whether the body has started reading.
 					def reading?
 						@reading
 					end
 					
+					# Read the next chunk from the body.
+					# @returns [String | Nil] The next chunk of data.
 					def read
 						@reading = true
 						
 						super
 					end
 					
+					# Close the body and signal any waiting tasks.
 					def close(error = nil)
 						super
 						
@@ -40,6 +46,8 @@ module Async
 						end
 					end
 					
+					# Wait for the body to be fully consumed or discard it.
+					# @parameter persistent [Boolean] Whether the connection will be reused.
 					def wait(persistent = true)
 						if @reading
 							@closed.wait
@@ -52,6 +60,7 @@ module Async
 						end
 					end
 					
+					# @returns [String] A detailed representation of this finishable body.
 					def inspect
 						"#<#{self.class} closed=#{@closed} error=#{@error}> | #{super}"
 					end

data/lib/async/http/protocol/http1/request.rb

@@ -9,7 +9,11 @@ module Async
 	module HTTP
 		module Protocol
 			module HTTP1
+				# An incoming HTTP/1 request parsed from the connection.
 				class Request < Protocol::Request
+					# Check whether the given request target is a valid path.
+					# @parameter target [String] The request target to validate.
+					# @returns [Boolean] Whether the target is a valid path.
 					def self.valid_path?(target)
 						if target.start_with?("/")
 							return true
@@ -22,6 +26,9 @@ module Async
 					
 					URI_PATTERN = %r{\A(?<scheme>[^:/]+)://(?<authority>[^/]+)(?<path>.*)\z}
 					
+					# Read and parse the next request from the connection.
+					# @parameter connection [Connection] The HTTP/1 connection to read from.
+					# @returns [Request | Nil] The parsed request, or `nil` if the connection is closed.
 					def self.read(connection)
 						connection.read_request do |authority, method, target, version, headers, body|
 							if method == ::Protocol::HTTP::Methods::CONNECT
@@ -42,6 +49,15 @@ module Async
 					
 					UPGRADE = "upgrade"
 					
+					# Initialize the request from the parsed components.
+					# @parameter connection [Connection] The underlying connection.
+					# @parameter scheme [String | Nil] The request scheme.
+					# @parameter authority [String | Nil] The request authority.
+					# @parameter method [String] The HTTP method.
+					# @parameter path [String | Nil] The request path.
+					# @parameter version [String] The HTTP version.
+					# @parameter headers [Protocol::HTTP::Headers] The request headers.
+					# @parameter body [Protocol::HTTP::Body::Readable | Nil] The request body.
 					def initialize(connection, scheme, authority, method, path, version, headers, body)
 						@connection = connection
 						
@@ -51,18 +67,24 @@ module Async
 						super(scheme, authority, method, path, version, headers, body, protocol, self.public_method(:write_interim_response))
 					end
 					
+					# @returns [Connection] The underlying HTTP/1 connection.
 					def connection
 						@connection
 					end
 					
+					# @returns [Boolean] Whether connection hijacking is supported.
 					def hijack?
 						true
 					end
 					
+					# Hijack the underlying connection for bidirectional communication.
 					def hijack!
 						@connection.hijack!
 					end
 					
+					# Write an interim (1xx) response to the client.
+					# @parameter status [Integer] The interim HTTP status code.
+					# @parameter headers [Hash | Nil] Optional interim response headers.
 					def write_interim_response(status, headers = nil)
 						@connection.write_interim_response(@version, status, headers)
 					end