Add support for multiplexing protocol configurations.

Author: ioquatix

lib/async/http/protocol/http.rb

@@ -16,6 +16,10 @@ module HTTP
 				HTTP2_PREFACE = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
 				HTTP2_PREFACE_SIZE = HTTP2_PREFACE.bytesize
 
+				# Determine if the inbound connection is HTTP/1 or HTTP/2.
+				#
+				# @parameter stream [IO::Stream] The stream to detect the protocol for.
+				# @returns [Class] The protocol class to use.
 				def self.protocol_for(stream)
 					# Detect HTTP/2 connection preface
 					# https://www.rfc-editor.org/rfc/rfc9113.html#section-3.4
@@ -35,18 +39,29 @@ def self.protocol_for(stream)
 					end
 				end
 
-				# Only inbound connections can detect HTTP1 vs HTTP2 for http://.
-				# Outbound connections default to HTTP1.
+				# Create a client for an outbound connection. Defaults to HTTP/1 for plaintext connections.
+				#
+				# @parameter peer [IO] The peer to communicate with.
+				# @parameter options [Hash] Options to pass to the protocol, keyed by protocol class.
 				def self.client(peer, **options)
+					options = options[protocol] || {}
+					
 					HTTP1.client(peer, **options)
 				end
 
+				# Create a server for an inbound connection. Able to detect HTTP1 vs HTTP2.
+				#
+				# @parameter peer [IO] The peer to communicate with.
+				# @parameter options [Hash] Options to pass to the protocol, keyed by protocol class.
 				def self.server(peer, **options)
 					stream = ::IO::Stream(peer)
+					protocol = protocol_for(stream)
+					options = options[protocol] || {}
 
-					return protocol_for(stream).server(stream, **options)
+					return protocol.server(stream, **options)
 				end
 
+				# @returns [Array] The names of the supported protocols.
 				def self.names
 					["h2", "http/1.1", "http/1.0"]
 				end

lib/async/http/protocol/http1.rb

@@ -15,26 +15,37 @@ module Protocol
 			module HTTP1
 				VERSION = "HTTP/1.1"
 
+				# @returns [Boolean] Whether the protocol supports bidirectional communication.
 				def self.bidirectional?
 					true
 				end
 
+				# @returns [Boolean] Whether the protocol supports trailers.
 				def self.trailer?
 					true
 				end
 
+				# Create a client for an outbound connection.
+				#
+				# @parameter peer [IO] The peer to communicate with.
+				# @parameter options [Hash] Options to pass to the client instance.
 				def self.client(peer, **options)
 					stream = ::IO::Stream(peer)
 
 					return HTTP1::Client.new(stream, VERSION, **options)
 				end
 
+				# Create a server for an inbound connection.
+				#
+				# @parameter peer [IO] The peer to communicate with.
+				# @parameter options [Hash] Options to pass to the server instance.
 				def self.server(peer, **options)
 					stream = ::IO::Stream(peer)
 
 					return HTTP1::Server.new(stream, VERSION, **options)
 				end
 
+				# @returns [Array] The names of the supported protocol.
 				def self.names
 					["http/1.1", "http/1.0"]
 				end

lib/async/http/protocol/http10.rb

@@ -12,26 +12,37 @@ module Protocol
 			module HTTP10
 				VERSION = "HTTP/1.0"
 
+				# @returns [Boolean] Whether the protocol supports bidirectional communication.
 				def self.bidirectional?
 					false
 				end
 
+				# @returns [Boolean] Whether the protocol supports trailers.
 				def self.trailer?
 					false
 				end
 
+				# Create a client for an outbound connection.
+				#
+				# @parameter peer [IO] The peer to communicate with.
+				# @parameter options [Hash] Options to pass to the client instance.
 				def self.client(peer, **options)
 					stream = ::IO::Stream(peer)
 
 					return HTTP1::Client.new(stream, VERSION, **options)
 				end
 
+				# Create a server for an inbound connection.
+				#
+				# @parameter peer [IO] The peer to communicate with.
+				# @parameter options [Hash] Options to pass to the server instance.
 				def self.server(peer, **options)
 					stream = ::IO::Stream(peer)
 
 					return HTTP1::Server.new(stream, VERSION, **options)
 				end
 
+				# @returns [Array] The names of the supported protocol.
 				def self.names
 					["http/1.0"]
 				end

lib/async/http/protocol/http11.rb

@@ -13,26 +13,37 @@ module Protocol
 			module HTTP11
 				VERSION = "HTTP/1.1"
 
+				# @returns [Boolean] Whether the protocol supports bidirectional communication.
 				def self.bidirectional?
 					true
 				end
 
+				# @returns [Boolean] Whether the protocol supports trailers.
 				def self.trailer?
 					true
 				end
 
+				# Create a client for an outbound connection.
+				#
+				# @parameter peer [IO] The peer to communicate with.
+				# @parameter options [Hash] Options to pass to the client instance.
 				def self.client(peer, **options)
 					stream = ::IO::Stream(peer)
 
 					return HTTP1::Client.new(stream, VERSION, **options)
 				end
 
+				# Create a server for an inbound connection.
+				#
+				# @parameter peer [IO] The peer to communicate with.
+				# @parameter options [Hash] Options to pass to the server instance.
 				def self.server(peer, **options)
 					stream = ::IO::Stream(peer)
 
 					return HTTP1::Server.new(stream, VERSION, **options)
 				end
 
+				# @returns [Array] The names of the supported protocol.
 				def self.names
 					["http/1.1"]
 				end

lib/async/http/protocol/http2.rb

@@ -15,21 +15,25 @@ module Protocol
 			module HTTP2
 				VERSION = "HTTP/2"
 
+				# @returns [Boolean] Whether the protocol supports bidirectional communication.
 				def self.bidirectional?
 					true
 				end
 
+				# @returns [Boolean] Whether the protocol supports trailers.
 				def self.trailer?
 					true
 				end
 
+				# The default settings for the client.
 				CLIENT_SETTINGS = {
 					::Protocol::HTTP2::Settings::ENABLE_PUSH => 0,
 					::Protocol::HTTP2::Settings::MAXIMUM_FRAME_SIZE => 0x100000,
 					::Protocol::HTTP2::Settings::INITIAL_WINDOW_SIZE => 0x800000,
 					::Protocol::HTTP2::Settings::NO_RFC7540_PRIORITIES => 1,
 				}
 
+				# The default settings for the server.
 				SERVER_SETTINGS = {
 					# We choose a lower maximum concurrent streams to avoid overloading a single connection/thread.
 					::Protocol::HTTP2::Settings::MAXIMUM_CONCURRENT_STREAMS => 128,
@@ -39,6 +43,10 @@ def self.trailer?
 					::Protocol::HTTP2::Settings::NO_RFC7540_PRIORITIES => 1,
 				}
 
+				# Create a client for an outbound connection.
+				#
+				# @parameter peer [IO] The peer to communicate with.
+				# @parameter options [Hash] Options to pass to the client instance.
 				def self.client(peer, settings: CLIENT_SETTINGS)
 					stream = ::IO::Stream(peer)
 					client = Client.new(stream)
@@ -49,6 +57,10 @@ def self.client(peer, settings: CLIENT_SETTINGS)
 					return client
 				end
 
+				# Create a server for an inbound connection.
+				#
+				# @parameter peer [IO] The peer to communicate with.
+				# @parameter options [Hash] Options to pass to the server instance.
 				def self.server(peer, settings: SERVER_SETTINGS)
 					stream = ::IO::Stream(peer)
 					server = Server.new(stream)
@@ -59,6 +71,7 @@ def self.server(peer, settings: SERVER_SETTINGS)
 					return server
 				end
 
+				# @returns [Array] The names of the supported protocol.
 				def self.names
 					["h2"]
 				end

lib/async/http/protocol/https.rb

@@ -14,13 +14,20 @@ module HTTP
 		module Protocol
 			# A server that supports both HTTP1.0 and HTTP1.1 semantics by detecting the version of the request.
 			module HTTPS
+				# The protocol classes for each supported protocol.
 				HANDLERS = {
 					"h2" => HTTP2,
 					"http/1.1" => HTTP11,
 					"http/1.0" => HTTP10,
 					nil => HTTP11,
 				}
 
+				# Determine the protocol of the peer and return the appropriate protocol class.
+				#
+				# Use TLS Application Layer Protocol Negotiation (ALPN) to determine the protocol.
+				#
+				# @parameter peer [IO] The peer to communicate with.
+				# @returns [Class] The protocol class to use.
 				def self.protocol_for(peer)
 					# alpn_protocol is only available if openssl v1.0.2+
 					name = peer.alpn_protocol
@@ -34,15 +41,29 @@ def self.protocol_for(peer)
 					end
 				end
 
-				def self.client(peer)
-					protocol_for(peer).client(peer)
+				# Create a client for an outbound connection.
+				#
+				# @parameter peer [IO] The peer to communicate with.
+				# @parameter options [Hash] Options to pass to the client instance.
+				def self.client(peer, **options)
+					protocol = protocol_for(peer)
+					options = options[protocol] || {}
+					
+					protocol.client(peer, **options)
 				end
 
-				def self.server(peer)
-					protocol_for(peer).server(peer)
+				# Create a server for an inbound connection.
+				#
+				# @parameter peer [IO] The peer to communicate with.
+				# @parameter options [Hash] Options to pass to the server instance.
+				def self.server(peer, **options)
+					protocol = protocol_for(peer)
+					options = options[protocol] || {}
+					
+					protocol.server(peer, **options)
 				end
 
-				# Supported Application Layer Protocol Negotiation names:
+				# @returns [Array] The names of the supported protocol, used for Application Layer Protocol Negotiation (ALPN).
 				def self.names
 					HANDLERS.keys.compact
 				end