protocol-http 0.45.0 → 0.46.0

data/lib/protocol/http/headers.rb

@@ -13,9 +13,14 @@ require_relative "header/etags"
 require_relative "header/vary"
 require_relative "header/authorization"
 require_relative "header/date"
+require_relative "header/priority"
 
 module Protocol
 	module HTTP
+		# @namespace
+		module Header
+		end
+		
 		# Headers are an array of key-value pairs. Some header keys represent multiple values.
 		class Headers
 			Split = Header::Split
@@ -24,6 +29,7 @@ module Protocol
 			TRAILER = "trailer"
 			
 			# Construct an instance from a headers Array or Hash. No-op if already an instance of `Headers`. If the underlying array is frozen, it will be duped.
+			#
 			# @return [Headers] an instance of headers.
 			def self.[] headers
 				if headers.nil?
@@ -47,6 +53,10 @@ module Protocol
 				return self.new(fields)
 			end
 			
+			# Initialize the headers with the specified fields.
+			#
+			# @parameter fields [Array] An array of `[key, value]` pairs.
+			# @parameter indexed [Hash] A hash table of normalized headers, if available.
 			def initialize(fields = [], indexed = nil)
 				@fields = fields
 				@indexed = indexed
@@ -55,6 +65,9 @@ module Protocol
 				@tail = nil
 			end
 			
+			# Initialize a copy of the headers.
+			#
+			# @parameter other [Headers] The headers to copy.
 			def initialize_dup(other)
 				super
 				
@@ -62,13 +75,14 @@ module Protocol
 				@indexed = @indexed.dup
 			end
 			
+			# Clear all headers.
 			def clear
 				@fields.clear
 				@indexed = nil
 				@tail = nil
 			end
 			
-			# Flatten trailer into the headers.
+			# Flatten trailer into the headers, in-place.
 			def flatten!
 				if @tail
 					self.delete(TRAILER)
@@ -78,29 +92,27 @@ module Protocol
 				return self
 			end
 			
+			# Flatten trailer into the headers, returning a new instance of {Headers}.
 			def flatten
 				self.dup.flatten!
 			end
 			
-			# An array of `[key, value]` pairs.
+			# @attribute [Array] An array of `[key, value]` pairs.
 			attr :fields
 			
-			# @returns Whether there are any trailers.
+			# @returns [Boolean] Whether there are any trailers.
 			def trailer?
 				@tail != nil
 			end
 			
 			# Record the current headers, and prepare to add trailers.
 			#
-			# This method is typically used after headers are sent to capture any
-			# additional headers which should then be sent as trailers.
+			# This method is typically used after headers are sent to capture any additional headers which should then be sent as trailers.
 			#
-			# A sender that intends to generate one or more trailer fields in a
-			# message should generate a trailer header field in the header section of
-			# that message to indicate which fields might be present in the trailers.
+			# A sender that intends to generate one or more trailer fields in a message should generate a trailer header field in the header section of that message to indicate which fields might be present in the trailers.
 			#
 			# @parameter names [Array] The trailer header names which will be added later.
-			# @yields block {|name, value| ...} The trailer headers if any.
+			# @yields {|name, value| ...} the trailing headers if a block is given.
 			# @returns An enumerator which is suitable for iterating over trailers.
 			def trailer!(&block)
 				@tail ||= @fields.size
@@ -117,6 +129,7 @@ module Protocol
 				end
 			end
 			
+			# Freeze the headers, and ensure the indexed hash is generated.
 			def freeze
 				return if frozen?
 				
@@ -129,24 +142,35 @@ module Protocol
 				super
 			end
 			
+			# @returns [Boolean] Whether the headers are empty.
 			def empty?
 				@fields.empty?
 			end
 			
+			# Enumerate all header keys and values.
+			#
+			# @yields {|key, value| ...}
+			# 	@parameter key [String] The header key.
+			# 	@parameter value [String] The header value.
 			def each(&block)
 				@fields.each(&block)
 			end
 			
+			# @returns [Boolean] Whether the headers include the specified key.
 			def include? key
 				self[key] != nil
 			end
 			
 			alias key? include?
 			
+			# @returns [Array] All the keys of the headers.
 			def keys
 				self.to_h.keys
 			end
 			
+			# Extract the specified keys from the headers.
+			#
+			# @parameter keys [Array] The keys to extract.
 			def extract(keys)
 				deleted, @fields = @fields.partition do |field|
 					keys.include?(field.first.downcase)
@@ -163,21 +187,23 @@ module Protocol
 			
 			# Add the specified header key value pair.
 			#
-			# @param key [String] the header key.
-			# @param value [String] the header value to assign.
+			# @parameter key [String] the header key.
+			# @parameter value [String] the header value to assign.
 			def add(key, value)
 				self[key] = value
 			end
 			
 			# Set the specified header key to the specified value, replacing any existing header keys with the same name.
-			# @param key [String] the header key to replace.
-			# @param value [String] the header value to assign.
+			#
+			# @parameter key [String] the header key to replace.
+			# @parameter value [String] the header value to assign.
 			def set(key, value)
 				# TODO This could be a bit more efficient:
 				self.delete(key)
 				self.add(key, value)
 			end
 			
+			# Merge the headers into this instance.
 			def merge!(headers)
 				headers.each do |key, value|
 					self[key] = value
@@ -186,13 +212,15 @@ module Protocol
 				return self
 			end
 			
+			# Merge the headers into a new instance of {Headers}.
 			def merge(headers)
 				self.dup.merge!(headers)
 			end
 			
 			# Append the value to the given key. Some values can be appended multiple times, others can only be set once.
-			# @param key [String] The header key.
-			# @param value The header value.
+			#
+			# @parameter key [String] The header key.
+			# @parameter value [String] The header value.
 			def []= key, value
 				if @indexed
 					merge_into(@indexed, key.downcase, value)
@@ -201,8 +229,9 @@ module Protocol
 				@fields << [key, value]
 			end
 			
+			# The policy for various headers, including how they are merged and normalized.
 			POLICY = {
-				# Headers which may only be specified once.
+				# Headers which may only be specified once:
 				"content-type" => false,
 				"content-disposition" => false,
 				"content-length" => false,
@@ -218,6 +247,7 @@ module Protocol
 				"connection" => Header::Connection,
 				"cache-control" => Header::CacheControl,
 				"vary" => Header::Vary,
+				"priority" => Header::Priority,
 				
 				# Headers specifically for proxies:
 				"via" => Split,
@@ -249,7 +279,10 @@ module Protocol
 				"if-unmodified-since" => Header::Date,
 			}.tap{|hash| hash.default = Split}
 			
-			# Delete all headers with the given key, and return the merged value.
+			# Delete all header values for the given key, and return the merged value.
+			#
+			# @parameter key [String] The header key.
+			# @returns [String | Array | Object] The merged header value.
 			def delete(key)
 				deleted, @fields = @fields.partition do |field|
 					field.first.downcase == key
@@ -274,6 +307,11 @@ module Protocol
 				end
 			end
 			
+			# Merge the value into the hash according to the policy for the given key.
+			# 
+			# @parameter hash [Hash] The hash to merge into.
+			# @parameter key [String] The header key.
+			# @parameter value [String] The raw header value.
 			protected def merge_into(hash, key, value)
 				if policy = POLICY[key]
 					if current_value = hash[key]
@@ -287,11 +325,17 @@ module Protocol
 				end
 			end
 			
+			# Get the value of the specified header key.
+			#
+			# @parameter key [String] The header key.
+			# @returns [String | Array | Object] The header value.
 			def [] key
 				to_h[key]
 			end
 			
-			# A hash table of `{key, policy[key].map(values)}`
+			# Compute a hash table of headers, where the keys are normalized to lower case and the values are normalized according to the policy for that header.
+			#
+			# @returns [Hash] A hash table of `{key, value}` pairs.
 			def to_h
 				@indexed ||= @fields.inject({}) do |hash, (key, value)|
 					merge_into(hash, key.downcase, value)
@@ -302,10 +346,16 @@ module Protocol
 			
 			alias as_json to_h
 			
+			# Inspect the headers.
+			#
+			# @returns [String] A string representation of the headers.
 			def inspect
 				"#<#{self.class} #{@fields.inspect}>"
 			end
 			
+			# Compare this object to another object. May depend on the order of the fields.
+			#
+			# @returns [Boolean] Whether the other object is equal to this one.
 			def == other
 				case other
 				when Hash
@@ -321,29 +371,42 @@ module Protocol
 			class Merged
 				include Enumerable
 				
+				# Construct a merged list of headers.
+				#
+				# @parameter *all [Array] An array of all headers to merge.
 				def initialize(*all)
 					@all = all
 				end
 				
+				# @returns [Array] A list of all headers, in the order they were added, as `[key, value]` pairs.
 				def fields
 					each.to_a
 				end
 				
+				# @returns [Headers] A new instance of {Headers} containing all the merged headers.
 				def flatten
 					Headers.new(fields)
 				end
 				
+				# Clear the references to all headers.
 				def clear
 					@all.clear
 				end
 				
+				# Add a new set of headers to the merged list.
+				#
+				# @parameter headers [Headers | Array | Hash] A list of headers to add.
 				def << headers
 					@all << headers
 					
 					return self
 				end
 				
-				# @yields [String, String] header key (lower case string) and value (as string).
+				# Enumerate all headers in the merged list.
+				#
+				# @yields {|key, value| ...} The header key and value.
+				# 	@parameter key [String] The header key (lower case).
+				# 	@parameter value [String] The header value.
 				def each(&block)
 					return to_enum unless block_given?
 					

data/lib/protocol/http/methods.rb

@@ -50,6 +50,11 @@ module Protocol
 			# The PATCH method applies partial modifications to a resource.
 			PATCH = "PATCH"
 			
+			# Check if the given name is a valid HTTP method, according to this module.
+			#
+			# Note that this method only knows about the methods defined in this module, however there are many other methods defined in different specifications.
+			#
+			# @returns [Boolean] True if the name is a valid HTTP method.
 			def self.valid?(name)
 				const_defined?(name)
 			rescue NameError

data/lib/protocol/http/middleware/builder.rb

@@ -8,25 +8,42 @@ require_relative "../middleware"
 module Protocol
 	module HTTP
 		class Middleware
+			# A convenient interface for constructing middleware stacks.
 			class Builder
+				# Initialize the builder with the given default application.
+				#
+				# @parameter default_app [Object] The default application to use if no middleware is specified.
 				def initialize(default_app = NotFound)
 					@use = []
 					@app = default_app
 				end
 				
+				# Use the given middleware with the given arguments and options.
+				#
+				# @parameter middleware [Class | Object] The middleware class to use.
+				# @parameter arguments [Array] The arguments to pass to the middleware constructor.
+				# @parameter options [Hash] The options to pass to the middleware constructor.
+				# @parameter block [Proc] The block to pass to the middleware constructor.
 				def use(middleware, *arguments, **options, &block)
 					@use << proc {|app| middleware.new(app, *arguments, **options, &block)}
 				end
 				
+				# Specify the (default) middleware application to use.
+				#
+				# @parameter app [Middleware] The application to use if no middleware is able to handle the request.
 				def run(app)
 					@app = app
 				end
 				
+				# Convert the builder to an application by chaining the middleware together.
+				#
+				# @returns [Middleware] The application.
 				def to_app
 					@use.reverse.inject(@app) {|app, use| use.call(app)}
 				end
 			end
 			
+			# Build a middleware application using the given block.
 			def self.build(&block)
 				builder = Builder.new
 				

data/lib/protocol/http/middleware.rb

@@ -22,49 +22,77 @@ module Protocol
 		# You do not need to use the Middleware class to implement middleware. You can implement the interface directly.
 		class Middleware < Methods
 			# Convert a block to a middleware delegate.
+			#
+			# @parameter block [Proc] The block to convert to a middleware delegate.
+			# @returns [Middleware] The middleware delegate.
 			def self.for(&block)
+				# Add a close method to the block.
 				def block.close
 				end
 				
 				return self.new(block)
 			end
 			
+			# Initialize the middleware with the given delegate.
+			#
+			# @parameter delegate [Object] The delegate object. A delegate is used for passing along requests that are not handled by *this* middleware.
 			def initialize(delegate)
 				@delegate = delegate
 			end
 			
+			# @attribute [Object] The delegate object that is used for passing along requests that are not handled by *this* middleware.
 			attr :delegate
 			
+			# Close the middleware. Invokes the close method on the delegate.
 			def close
 				@delegate.close
 			end
 			
+			# Call the middleware with the given request. Invokes the call method on the delegate.
 			def call(request)
 				@delegate.call(request)
 			end
 			
+			# A simple middleware that always returns a 200 response.
 			module Okay
+				# Close the middleware - idempotent no-op.
 				def self.close
 				end
 				
+				# Call the middleware with the given request, always returning a 200 response.
+				#
+				# @parameter request [Request] The request object.
+				# @returns [Response] The response object, which always contains a 200 status code.
 				def self.call(request)
 					Response[200]
 				end
 			end
 			
+			# A simple middleware that always returns a 404 response.
 			module NotFound
+				# Close the middleware - idempotent no-op.
 				def self.close
 				end
 				
+				# Call the middleware with the given request, always returning a 404 response. This middleware is useful as a default.
+				#
+				# @parameter request [Request] The request object.
+				# @returns [Response] The response object, which always contains a 404 status code.
 				def self.call(request)
 					Response[404]
 				end
 			end
 			
+			# A simple middleware that always returns "Hello World!".
 			module HelloWorld
+				# Close the middleware - idempotent no-op.
 				def self.close
 				end
 				
+				# Call the middleware with the given request.
+				#
+				# @parameter request [Request] The request object.
+				# @returns [Response] The response object, whihc always contains "Hello World!".
 				def self.call(request)
 					Response[200, Headers["content-type" => "text/plain"], ["Hello World!"]]
 				end

data/lib/protocol/http/peer.rb

@@ -7,12 +7,18 @@ module Protocol
 	module HTTP
 		# Provide a well defined, cached representation of a peer (address).
 		class Peer
+			# Create a new peer object for the given IO object, using the remote address if available.
+			#
+			# @returns [Peer | Nil] The peer object, or nil if the remote address is not available.
 			def self.for(io)
 				if address = io.remote_address
 					return new(address)
 				end
 			end
 			
+			# Initialize the peer with the given address.
+			#
+			# @parameter address [Addrinfo] The remote address of the peer.
 			def initialize(address)
 				@address = address
 				
@@ -21,7 +27,10 @@ module Protocol
 				end
 			end
 			
+			# @attribute [Addrinfo] The remote address of the peer.
 			attr :address
+			
+			# @attribute [String] The IP address of the peer, if available.
 			attr :ip_address
 			
 			alias remote_address address

data/lib/protocol/http/reference.rb

@@ -19,6 +19,12 @@ module Protocol
 				self.new(path, query, fragment, parameters)
 			end
 			
+			# Initialize the reference.
+			#
+			# @parameter path [String] The path component, e.g. `/foo/bar/index.html`.
+			# @parameter query [String | Nil] The un-parsed query string, e.g. 'x=10&y=20'.
+			# @parameter fragment [String | Nil] The fragment, the part after the '#'.
+			# @parameter parameters [Hash | Nil] User supplied parameters that will be appended to the query part.
 			def initialize(path = "/", query = nil, fragment = nil, parameters = nil)
 				@path = path
 				@query = query
@@ -26,18 +32,21 @@ module Protocol
 				@parameters = parameters
 			end
 			
-			# The path component, e.g. /foo/bar/index.html
+			# @attribute [String] The path component, e.g. `/foo/bar/index.html`.
 			attr_accessor :path
 			
-			# The un-parsed query string, e.g. 'x=10&y=20'
+			# @attribute [String] The un-parsed query string, e.g. 'x=10&y=20'.
 			attr_accessor :query
 			
-			# A fragment, the part after the '#'
+			# @attribute [String] The fragment, the part after the '#'.
 			attr_accessor :fragment
 			
-			# User supplied parameters that will be appended to the query part.
+			# @attribute [Hash] User supplied parameters that will be appended to the query part.
 			attr_accessor :parameters
 			
+			# Freeze the reference.
+			#
+			#	@returns [Reference] The frozen reference.
 			def freeze
 				return self if frozen?
 				
@@ -49,14 +58,25 @@ module Protocol
 				super
 			end
 			
+			# Implicit conversion to an array.
+			#
+			# @returns [Array] The reference as an array, `[path, query, fragment, parameters]`.
 			def to_ary
 				[@path, @query, @fragment, @parameters]
 			end
 			
+			# Compare two references.
+			#
+			# @parameter other [Reference] The other reference to compare.
+			# @returns [Integer] -1, 0, 1 if the reference is less than, equal to, or greater than the other reference.
 			def <=> other
 				to_ary <=> other.to_ary
 			end
 			
+			# Type-cast a reference.
+			#
+			# @parameter reference [Reference | String] The reference to type-cast.
+			# @returns [Reference] The type-casted reference.
 			def self.[] reference
 				if reference.is_a? self
 					return reference
@@ -65,19 +85,23 @@ module Protocol
 				end
 			end
 			
+			# @returns [Boolean] Whether the reference has parameters.
 			def parameters?
 				@parameters and !@parameters.empty?
 			end
 			
+			# @returns [Boolean] Whether the reference has a query string.
 			def query?
 				@query and !@query.empty?
 			end
 			
+			# @returns [Boolean] Whether the reference has a fragment.
 			def fragment?
 				@fragment and !@fragment.empty?
 			end
 			
-			def append(buffer)
+			# Append the reference to the given buffer.
+			def append(buffer = String.new)
 				if query?
 					buffer << URL.escape_path(@path) << "?" << @query
 					buffer << "&" << URL.encode(@parameters) if parameters?
@@ -93,8 +117,11 @@ module Protocol
 				return buffer
 			end
 			
+			# Convert the reference to a string, e.g. `/foo/bar/index.html?x=10&y=20#section`
+			#
+			# @returns [String] The reference as a string.
 			def to_s
-				append(String.new)
+				append
 			end
 			
 			# Merges two references as specified by RFC2396, similar to `URI.join`.

data/lib/protocol/http/request.rb

@@ -25,6 +25,17 @@ module Protocol
 		class Request
 			prepend Body::Reader
 			
+			# Initialize the request.
+			#
+			# @parameter scheme [String | Nil] The request scheme, usually `"http"` or `"https"`.
+			# @parameter authority [String | Nil] The request authority, usually a hostname and port number, e.g. `"example.com:80"`.
+			# @parameter method [String | Nil] The request method, usually one of `"GET"`, `"HEAD"`, `"POST"`, `"PUT"`, `"DELETE"`, `"CONNECT"` or `"OPTIONS"`, etc.
+			# @parameter path [String | Nil] The request path, usually a path and query string, e.g. `"/index.html"`, `"/search?q=hello"`, etc.
+			# @parameter version [String | Nil] The request version, usually `"http/1.0"`, `"http/1.1"`, `"h2"`, or `"h3"`.
+			# @parameter headers [Headers] The request headers, usually containing metadata associated with the request such as the `"user-agent"`, `"accept"` (content type), `"accept-language"`, etc.
+			# @parameter body [Body::Readable] The request body.
+			# @parameter protocol [String | Array(String) | Nil] The request protocol, usually empty, but occasionally `"websocket"` or `"webtransport"`.
+			# @parameter interim_response [Proc] A callback which is called when an interim response is received.
 			def initialize(scheme = nil, authority = nil, method = nil, path = nil, version = nil, headers = Headers.new, body = nil, protocol = nil, interim_response = nil)
 				@scheme = scheme
 				@authority = authority
@@ -81,6 +92,11 @@ module Protocol
 				@interim_response&.call(status, headers)
 			end
 			
+			# Register a callback to be called when an interim response is received.
+			#
+			# @yields {|status, headers| ...} The callback to be called when an interim response is received.
+			# 	@parameter status [Integer] The HTTP status code, e.g. `100`, `101`, etc.
+			# 	@parameter headers [Hash] The headers, e.g. `{"link" => "</style.css>; rel=stylesheet"}`, etc.
 			def on_interim_response(&block)
 				if interim_response = @interim_response
 					@interim_response = ->(status, headers) do
@@ -120,6 +136,9 @@ module Protocol
 				@method != Methods::POST && (@body.nil? || @body.empty?)
 			end
 			
+			# Convert the request to a hash, suitable for serialization.
+			#
+			# @returns [Hash] The request as a hash.
 			def as_json(...)
 				{
 					scheme: @scheme,
@@ -133,10 +152,16 @@ module Protocol
 				}
 			end
 			
+			# Convert the request to JSON.
+			#
+			# @returns [String] The request as JSON.
 			def to_json(...)
 				as_json.to_json(...)
 			end
 			
+			# Summarize the request as a string.
+			#
+			# @returns [String] The request as a string.
 			def to_s
 				"#{@scheme}://#{@authority}: #{@method} #{@path} #{@version}"
 			end

data/lib/protocol/http/response.rb

@@ -151,6 +151,9 @@ module Protocol
 				Response[500, Headers["content-type" => "text/plain"], ["#{exception.class}: #{exception.message}"]]
 			end
 			
+			# Convert the response to a hash suitable for serialization.
+			#
+			# @returns [Hash] The response as a hash.
 			def as_json(...)
 				{
 					version: @version,
@@ -161,14 +164,23 @@ module Protocol
 				}
 			end
 			
+			# Convert the response to JSON.
+			#
+			# @returns [String] The response as JSON.
 			def to_json(...)
 				as_json.to_json(...)
 			end
 			
+			# Summarise the response as a string.
+			#
+			# @returns [String] The response as a string.
 			def to_s
 				"#{@status} #{@version}"
 			end
 			
+			# Implicit conversion to an array.
+			#
+			# @returns [Array] The response as an array, e.g. `[status, headers, body]`.
 			def to_ary
 				return @status, @headers, @body
 			end