async-http 0.94.2 → 0.94.3

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

@@ -10,7 +10,12 @@ module Async
 	module HTTP
 		module Protocol
 			module HTTP1
+				# An HTTP/1 response received from a server.
 				class Response < Protocol::Response
+					# Read the response from the connection, handling interim responses.
+					# @parameter connection [Connection] The HTTP/1 connection to read from.
+					# @parameter request [Request] The original request.
+					# @returns [Response | Nil] The final response.
 					def self.read(connection, request)
 						while parts = connection.read_response(request.method)
 							response = self.new(connection, *parts)
@@ -39,6 +44,8 @@ module Async
 						super(version, status, headers, body, protocol)
 					end
 					
+					# Assign the connection pool, releasing the connection if it is already idle or closed.
+					# @parameter pool [Async::Pool::Controller] The connection pool.
 					def pool=(pool)
 						if @connection.idle? or @connection.closed?
 							pool.release(@connection)
@@ -47,14 +54,17 @@ module Async
 						end
 					end
 					
+					# @returns [Connection] The underlying HTTP/1 connection.
 					def connection
 						@connection
 					end
 					
+					# @returns [Boolean] Whether connection hijacking is available (when the body is `nil`).
 					def hijack?
 						@body.nil?
 					end
 					
+					# Hijack the underlying connection for bidirectional communication.
 					def hijack!
 						@connection.hijack!
 					end

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

@@ -16,19 +16,24 @@ module Async
 	module HTTP
 		module Protocol
 			module HTTP1
+				# An HTTP/1 server connection that receives requests and sends responses.
 				class Server < Connection
+					# Initialize the HTTP/1 server connection.
 					def initialize(...)
 						super
 						
 						@ready = Async::Notification.new
 					end
 					
+					# Called when the connection is closed, signalling any waiting tasks.
 					def closed(error = nil)
 						super
 						
 						@ready.signal
 					end
 					
+					# Write a failure response with the given status code.
+					# @parameter status [Integer] The HTTP status code to send.
 					def fail_request(status)
 						@persistent = false
 						write_response(@version, status, {})
@@ -38,6 +43,8 @@ module Async
 						Console.debug(self, "Failed to write failure response!", error)
 					end
 					
+					# Read the next incoming request from the connection.
+					# @returns [Request | Nil] The next request, or `nil` if the connection is closed.
 					def next_request
 						if closed?
 							return nil

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

@@ -14,6 +14,7 @@ require "io/stream"
 module Async
 	module HTTP
 		module Protocol
+			# Provides HTTP/1.0 and HTTP/1.1 client and server implementations.
 			module HTTP1
 				extend Configurable
 				

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

@@ -9,6 +9,7 @@ require_relative "http1"
 module Async
 	module HTTP
 		module Protocol
+			# Provides an HTTP/1.0 client and server protocol implementation.
 			module HTTP10
 				extend Configurable
 				

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

@@ -10,6 +10,7 @@ require_relative "http1"
 module Async
 	module HTTP
 		module Protocol
+			# Provides an HTTP/1.1 client and server protocol implementation.
 			module HTTP11
 				extend Configurable
 				

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

@@ -12,9 +12,12 @@ module Async
 	module HTTP
 		module Protocol
 			module HTTP2
+				# An HTTP/2 client connection that sends requests and reads responses.
 				class Client < ::Protocol::HTTP2::Client
 					include Connection
 					
+					# Initialize the HTTP/2 client with an IO stream.
+					# @parameter stream [IO::Stream] The underlying stream.
 					def initialize(stream)
 						@stream = stream
 						
@@ -23,6 +26,8 @@ module Async
 						super(framer)
 					end
 					
+					# Create a new response stream for the next request.
+					# @returns [Response] The response object to be populated.
 					def create_response
 						Response::Stream.create(self, self.next_stream_id).response
 					end
@@ -38,10 +43,15 @@ module Async
 						return response
 					end
 					
+					# Write a request to the remote server via the given response stream.
+					# @parameter response [Response] The response stream to write through.
+					# @parameter request [Protocol::HTTP::Request] The request to send.
 					def write_request(response, request)
 						response.send_request(request)
 					end
 					
+					# Wait for the response headers to arrive.
+					# @parameter response [Response] The response to wait on.
 					def read_response(response)
 						response.wait
 					end

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

@@ -26,7 +26,9 @@ module Async
 				CONNECTION = "connection".freeze
 				TRAILER = "trailer".freeze
 				
+				# Provides shared connection behaviour for HTTP/2 client and server connections.
 				module Connection
+					# Initialize the connection state.
 					def initialize(...)
 						super
 						
@@ -36,36 +38,45 @@ module Async
 						@write_frame_guard = Async::Semaphore.new(1)
 					end
 					
+					# Synchronize write access to the connection.
+					# @yields {|...| ...} The block to execute while holding the write lock.
 					def synchronize(&block)
 						@write_frame_guard.acquire(&block)
 					end
 					
+					# @returns [String] A string representation of this connection.
 					def to_s
 						"\#<#{self.class} #{@streams.count} active streams>"
 					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 :stream
 					
+					# @returns [Boolean] Whether this is an HTTP/1 connection.
 					def http1?
 						false
 					end
 					
+					# @returns [Boolean] Whether this is an HTTP/2 connection.
 					def http2?
 						true
 					end
 					
+					# Start the background reader task if it is not already running.
 					def start_connection
 						@reader || read_in_background
 					end
 					
+					# Close the connection and stop the background reader.
 					def close(error = nil)
 						# Ensure the reader task is stopped.
 						if @reader
@@ -77,6 +88,7 @@ module Async
 						super
 					end
 					
+					# Start a transient background task that reads frames from the connection.
 					def read_in_background(parent: Task.current)
 						raise RuntimeError, "Connection is closed!" if closed?
 						
@@ -106,12 +118,14 @@ module Async
 					
 					attr :promises
 					
+					# @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 streams allowed.
 					def concurrency
 						self.maximum_concurrent_streams
 					end
@@ -121,10 +135,12 @@ module Async
 						@stream&.readable?
 					end
 					
+					# @returns [Boolean] Whether the connection can be reused.
 					def reusable?
 						!self.closed?
 					end
 					
+					# @returns [String] The HTTP version string.
 					def version
 						VERSION
 					end

data/lib/async/http/protocol/http2/input.rb

@@ -11,6 +11,9 @@ module Async
 			module HTTP2
 				# A writable body which requests window updates when data is read from it.
 				class Input < ::Protocol::HTTP::Body::Writable
+					# Initialize the input body.
+					# @parameter stream [Stream] The HTTP/2 stream to read from.
+					# @parameter length [Integer | Nil] The expected content length.
 					def initialize(stream, length)
 						super(length)
 						
@@ -18,6 +21,8 @@ module Async
 						@remaining = length
 					end
 					
+					# Read the next chunk of data, requesting window updates as needed.
+					# @returns [String | Nil] The next chunk, or `nil` if the body is complete.
 					def read
 						if chunk = super
 							# If we read a chunk fron the stream, we want to extend the window if required so more data will be provided.

data/lib/async/http/protocol/http2/output.rb

@@ -9,7 +9,12 @@ module Async
 	module HTTP
 		module Protocol
 			module HTTP2
+				# Writes body data to an HTTP/2 stream, respecting flow control windows.
 				class Output
+					# Initialize the output handler.
+					# @parameter stream [Stream] The HTTP/2 stream to write to.
+					# @parameter body [Protocol::HTTP::Body::Readable] The body to read from.
+					# @parameter trailer [Protocol::HTTP::Headers | Nil] Optional trailing headers.
 					def initialize(stream, body, trailer = nil)
 						@stream = stream
 						@body = body
@@ -23,6 +28,7 @@ module Async
 					
 					attr :trailer
 					
+					# Start an asynchronous task to write the body to the stream.
 					def start(parent: Task.current)
 						raise "Task already started!" if @task
 						
@@ -33,6 +39,9 @@ module Async
 						end
 					end
 					
+					# Signal that the flow control window has been updated.
+					# @parameter size [Integer] The new window size.
+					# @returns [Boolean] Always returns `true`.
 					def window_updated(size)
 						@guard.synchronize do
 							@window_updated.signal
@@ -41,6 +50,8 @@ module Async
 						return true
 					end
 					
+					# Write a chunk of data to the HTTP/2 stream, respecting flow control.
+					# @parameter chunk [String] The data to write.
 					def write(chunk)
 						until chunk.empty?
 							maximum_size = @stream.available_frame_size
@@ -62,6 +73,8 @@ module Async
 						end
 					end
 					
+					# Finish writing to the stream.
+					# @parameter error [Exception | Nil] An optional error that caused the close.
 					def close_write(error = nil)
 						if stream = @stream
 							@stream = nil

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

@@ -12,7 +12,9 @@ module Async
 			module HTTP2
 				# Typically used on the server side to represent an incoming request, and write the response.
 				class Request < Protocol::Request
+					# Represents the HTTP/2 stream associated with an incoming server-side request.
 					class Stream < HTTP2::Stream
+						# Initialize the request stream.
 						def initialize(*)
 							super
 							
@@ -22,6 +24,9 @@ module Async
 						
 						attr :request
 						
+						# Process the initial headers received from the client and construct the request.
+						# @parameter headers [Array] The list of header key-value pairs.
+						# @parameter end_stream [Boolean] Whether the stream is complete after these headers.
 						def receive_initial_headers(headers, end_stream)
 							@headers = ::Protocol::HTTP::Headers.new
 							
@@ -79,6 +84,8 @@ module Async
 							return headers
 						end
 						
+						# Called when the stream is closed.
+						# @parameter error [Exception | Nil] The error that caused the close, if any.
 						def closed(error)
 							@request = nil
 							
@@ -86,6 +93,8 @@ module Async
 						end
 					end
 					
+					# Initialize the request from an HTTP/2 stream.
+					# @parameter stream [Stream] The HTTP/2 stream for this request.
 					def initialize(stream)
 						super(nil, nil, nil, nil, VERSION, nil, nil, nil, self.public_method(:write_interim_response))
 						
@@ -94,14 +103,17 @@ module Async
 					
 					attr :stream
 					
+					# @returns [Connection] The underlying HTTP/2 connection.
 					def connection
 						@stream.connection
 					end
 					
+					# @returns [Boolean] Whether the request has the required pseudo-headers.
 					def valid?
 						@scheme and @method and (@path or @method == ::Protocol::HTTP::Methods::CONNECT)
 					end
 					
+					# @returns [Boolean] Whether connection hijacking is supported (not available for HTTP/2).
 					def hijack?
 						false
 					end
@@ -110,6 +122,8 @@ module Async
 						[STATUS, "500"],
 					]
 					
+					# Send a response back to the client via the HTTP/2 stream.
+					# @parameter response [Protocol::HTTP::Response | Nil] The response to send.
 					def send_response(response)
 						if response.nil?
 							return @stream.send_headers(NO_RESPONSE, ::Protocol::HTTP2::END_STREAM)
@@ -143,6 +157,9 @@ module Async
 						end
 					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)
 						interim_response_headers = [
 							[STATUS, status]

data/lib/async/http/protocol/http2/response.rb

@@ -12,7 +12,9 @@ module Async
 			module HTTP2
 				# Typically used on the client side for writing a request and reading the incoming response.
 				class Response < Protocol::Response
+					# Represents the HTTP/2 stream associated with an outgoing client-side response.
 					class Stream < HTTP2::Stream
+						# Initialize the response stream.
 						def initialize(*)
 							super
 							
@@ -24,6 +26,8 @@ module Async
 						
 						attr :response
 						
+						# Wait for the response headers and return the response body.
+						# @returns [Protocol::HTTP::Body::Readable | Nil] The response body.
 						def wait_for_input
 							# The input isn't ready until the response headers have been received:
 							@response.wait
@@ -32,6 +36,9 @@ module Async
 							return @response.body
 						end
 						
+						# Handle a push promise stream from the server.
+						# @parameter promised_stream_id [Integer] The stream ID for the promised resource.
+						# @parameter headers [Array] The promise headers.
 						def accept_push_promise_stream(promised_stream_id, headers)
 							raise ProtocolError, "Cannot accept push promise stream!"
 						end
@@ -86,6 +93,9 @@ module Async
 							return headers
 						end
 						
+						# Process interim (1xx) response headers.
+						# @parameter status [Integer] The interim status code.
+						# @parameter headers [Array] The interim response headers.
 						def receive_interim_headers(status, headers)
 							if headers.any?
 								headers = ::Protocol::HTTP::Headers[headers]
@@ -114,6 +124,8 @@ module Async
 							end
 						end
 						
+						# Called when the stream is closed.
+						# @parameter error [Exception | Nil] The error that caused the close, if any.
 						def closed(error)
 							super
 							
@@ -127,6 +139,8 @@ module Async
 						end
 					end
 					
+					# Initialize the response from an HTTP/2 stream.
+					# @parameter stream [Stream] The HTTP/2 stream for this response.
 					def initialize(stream)
 						super(stream.connection.version, nil, nil)
 						
@@ -137,6 +151,8 @@ module Async
 					attr :stream
 					attr :request
 					
+					# Assign the connection pool, releasing the connection when the stream is closed.
+					# @parameter pool [Async::Pool::Controller] The connection pool.
 					def pool=(pool)
 						# If we are already closed, the stream can be released now:
 						if @stream.closed?
@@ -147,22 +163,29 @@ module Async
 						end
 					end
 					
+					# @returns [Connection] The underlying HTTP/2 connection.
 					def connection
 						@stream.connection
 					end
 					
+					# Wait for the response headers to be received.
 					def wait
 						@stream.wait
 					end
 					
+					# @returns [Boolean] Whether the original request was a HEAD request.
 					def head?
 						@request&.head?
 					end
 					
+					# @returns [Boolean] Whether the response has a valid status.
 					def valid?
 						!!@status
 					end
 					
+					# Build a request object from push promise headers.
+					# @parameter headers [Array] The push promise pseudo-headers and headers.
+					# @returns [Protocol::HTTP::Request] The constructed request.
 					def build_request(headers)
 						request = ::Protocol::HTTP::Request.new
 						request.headers = ::Protocol::HTTP::Headers.new

data/lib/async/http/protocol/http2/server.rb

@@ -12,9 +12,12 @@ module Async
 	module HTTP
 		module Protocol
 			module HTTP2
+				# An HTTP/2 server connection that receives requests and sends responses.
 				class Server < ::Protocol::HTTP2::Server
 					include Connection
 					
+					# Initialize the HTTP/2 server with an IO stream.
+					# @parameter stream [IO::Stream] The underlying stream.
 					def initialize(stream)
 						# Used by some generic methods in Connetion:
 						@stream = stream
@@ -28,12 +31,15 @@ module Async
 					
 					attr :requests
 					
+					# Accept a new stream from a client.
+					# @parameter stream_id [Integer] The stream ID assigned by the client.
 					def accept_stream(stream_id)
 						super do
 							Request::Stream.create(self, stream_id)
 						end
 					end
 					
+					# Close the server connection and stop accepting requests.
 					def close(error = nil)
 						if @requests
 							# Stop the request loop:
@@ -44,6 +50,9 @@ module Async
 						super
 					end
 					
+					# Enumerate incoming requests, yielding each one for processing.
+					# @yields {|request| ...} Each incoming request.
+					# 	@parameter request [Request] The incoming HTTP/2 request.
 					def each(task: Task.current)
 						task.annotate("Reading #{version} requests for #{self.class}.")
 						
@@ -51,6 +60,8 @@ module Async
 						@requests&.async do |task, request|
 							task.annotate("Incoming request: #{request.method} #{request.path.inspect}.")
 							
+							response = nil
+							
 							task.defer_stop do
 								response = yield(request)
 							rescue
@@ -60,6 +71,11 @@ module Async
 								raise
 							else
 								request.send_response(response)
+								# If send response is successful, we clear it so that we don't close it below.
+								response = nil
+							ensure
+								# If some failure occurs and we didn't send the response correctly, ensure that it's closed:
+								response&.close
 							end
 						end
 						

data/lib/async/http/protocol/http2/stream.rb

@@ -14,7 +14,9 @@ module Async
 	module HTTP
 		module Protocol
 			module HTTP2
+				# An HTTP/2 stream that manages headers, input data, and output data for a single request/response exchange.
 				class Stream < ::Protocol::HTTP2::Stream
+					# Initialize the stream state.
 					def initialize(*)
 						super
 						
@@ -36,6 +38,9 @@ module Async
 					
 					attr :input
 					
+					# Add a header to the stream, validating against HTTP/2 constraints.
+					# @parameter key [String] The header name.
+					# @parameter value [String] The header value.
 					def add_header(key, value, trailer: false)
 						if key == CONNECTION
 							raise ::Protocol::HTTP2::HeaderError, "Connection header is not allowed!"
@@ -48,12 +53,17 @@ module Async
 						end
 					end
 					
+					# Process trailing headers received after the body.
+					# @parameter headers [Array] The trailing header key-value pairs.
+					# @parameter end_stream [Boolean] Whether the stream ends after these headers.
 					def receive_trailing_headers(headers, end_stream)
 						headers.each do |key, value|
 							add_header(key, value, trailer: true)
 						end
 					end
 					
+					# Process an incoming HEADERS frame, dispatching to initial or trailing header handling.
+					# @parameter frame [Protocol::HTTP2::HeadersFrame] The headers frame to process.
 					def process_headers(frame)
 						if @headers and frame.end_stream?
 							self.receive_trailing_headers(super, frame.end_stream?)
@@ -74,6 +84,7 @@ module Async
 						send_reset_stream(error.code)
 					end
 					
+					# @returns [Input | Nil] The input body for this stream, if available.
 					def wait_for_input
 						return @input
 					end
@@ -88,6 +99,8 @@ module Async
 						end
 					end
 					
+					# Update the local flow control window after receiving data.
+					# @parameter frame [Protocol::HTTP2::DataFrame] The received data frame.
 					def update_local_window(frame)
 						consume_local_window(frame)
 						
@@ -95,6 +108,9 @@ module Async
 						# request_window_update
 					end
 					
+					# Process an incoming DATA frame and write it to the input body.
+					# @parameter frame [Protocol::HTTP2::DataFrame] The data frame to process.
+					# @returns [String] The unpacked data.
 					def process_data(frame)
 						data = frame.unpack
 						
@@ -142,6 +158,9 @@ module Async
 						end
 					end
 					
+					# Called when the flow control window is updated.
+					# @parameter size [Integer] The new window size.
+					# @returns [Boolean] Always returns `true`.
 					def window_updated(size)
 						super
 						

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

@@ -14,6 +14,7 @@ require "io/stream"
 module Async
 	module HTTP
 		module Protocol
+			# Provides an HTTP/2 client and server protocol implementation.
 			module HTTP2
 				extend Configurable
 				

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

@@ -23,11 +23,18 @@ module Async
 					nil => HTTP11,
 				}
 				
+				# Initialize the HTTPS protocol negotiator.
+				# @parameter handlers [Hash] A mapping of ALPN protocol names to protocol classes.
+				# @parameter options [Hash] Per-protocol options keyed by protocol class.
 				def initialize(handlers = HANDLERS, **options)
 					@handlers = handlers
 					@options = options
 				end
 				
+				# Register a protocol handler for a given ALPN protocol name.
+				# @parameter name [String] The ALPN protocol name.
+				# @parameter protocol [Class] The protocol class to handle connections.
+				# @parameter options [Hash] Options to pass when creating client or server instances.
 				def add(name, protocol, **options)
 					@handlers[name] = protocol
 					@options[protocol] = options

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

@@ -15,27 +15,35 @@ module Async
 			class RequestFailed < StandardError
 			end
 			
-			# This is generated by server protocols.
+			# An incoming HTTP request generated by server protocol implementations.
 			class Request < ::Protocol::HTTP::Request
+				# @returns [Connection | Nil] The underlying protocol connection.
 				def connection
 					nil
 				end
 				
+				# @returns [Boolean] Whether this request supports connection hijacking.
 				def hijack?
 					false
 				end
 				
+				# Write an interim (1xx) response back to the client.
+				# @parameter status [Integer] The interim HTTP status code.
+				# @parameter headers [Hash | Nil] Optional headers to include.
 				def write_interim_response(status, headers = nil)
 				end
 				
+				# @returns [Protocol::HTTP::Peer | Nil] The peer associated with this connection.
 				def peer
 					self.connection&.peer
 				end
 				
+				# @returns [Addrinfo | Nil] The remote address of the peer.
 				def remote_address
 					self.peer&.address
 				end
 				
+				# @returns [String] A string representation of the request.
 				def inspect
 					"#<#{self.class}:0x#{self.object_id.to_s(16)} method=#{method} path=#{path} version=#{version}>"
 				end

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

@@ -10,24 +10,29 @@ require_relative "../body/writable"
 module Async
 	module HTTP
 		module Protocol
-			# This is generated by client protocols.
+			# An HTTP response received from a server via client protocol implementations.
 			class Response < ::Protocol::HTTP::Response
+				# @returns [Connection | Nil] The underlying protocol connection.
 				def connection
 					nil
 				end
 				
+				# @returns [Boolean] Whether this response supports connection hijacking.
 				def hijack?
 					false
 				end
 				
+				# @returns [Protocol::HTTP::Peer | Nil] The peer associated with this connection.
 				def peer
 					self.connection&.peer
 				end
 				
+				# @returns [Addrinfo | Nil] The remote address of the peer.
 				def remote_address
 					self.peer&.remote_address
 				end
 				
+				# @returns [String] A string representation of the response.
 				def inspect
 					"#<#{self.class}:0x#{self.object_id.to_s(16)} status=#{status}>"
 				end