protocol-http 0.45.0 → 0.46.0

data/lib/protocol/http/content_encoding.rb

@@ -12,19 +12,30 @@ module Protocol
 	module HTTP
 		# Encode a response according the the request's acceptable encodings.
 		class ContentEncoding < Middleware
+			# The default wrappers to use for encoding content.
 			DEFAULT_WRAPPERS = {
 				"gzip" => Body::Deflate.method(:for)
 			}
 			
+			# The default content types to apply encoding to.
 			DEFAULT_CONTENT_TYPES = %r{^(text/.*?)|(.*?/json)|(.*?/javascript)$}
 			
-			def initialize(app, content_types = DEFAULT_CONTENT_TYPES, wrappers = DEFAULT_WRAPPERS)
-				super(app)
+			# Initialize the content encoding middleware.
+			#
+			# @parameter delegate [Middleware] The next middleware in the chain.
+			# @parameter content_types [Regexp] The content types to apply encoding to.
+			# @parameter wrappers [Hash] The encoding wrappers to use.
+			def initialize(delegate, content_types = DEFAULT_CONTENT_TYPES, wrappers = DEFAULT_WRAPPERS)
+				super(delegate)
 				
 				@content_types = content_types
 				@wrappers = wrappers
 			end
 			
+			# Encode the response body according to the request's acceptable encodings.
+			#
+			# @parameter request [Request] The request.
+			# @returns [Response] The response.
 			def call(request)
 				response = super
 				
@@ -40,7 +51,6 @@ module Protocol
 				
 				# TODO use http-accept and sort by priority
 				if !response.body.empty? and accept_encoding = request.headers["accept-encoding"]
-					
 					if content_type = response.headers["content-type"] and @content_types =~ content_type
 						body = response.body
 						

data/lib/protocol/http/cookie.rb

@@ -10,24 +10,39 @@ module Protocol
 	module HTTP
 		# Represents an individual cookie key-value pair.
 		class Cookie
+			# Initialize the cookie with the given name, value, and directives.
+			#
+			# @parameter name [String] The name of the cookiel, e.g. "session_id".
+			# @parameter value [String] The value of the cookie, e.g. "1234".
+			# @parameter directives [Hash] The directives of the cookie, e.g. `{"path" => "/"}`.
 			def initialize(name, value, directives)
 				@name = name
 				@value = value
 				@directives = directives
 			end
 			
+			# @attribute [String] The name of the cookie.
 			attr :name
+			
+			# @attribute [String] The value of the cookie.
 			attr :value
+			
+			# @attribute [Hash] The directives of the cookie.
 			attr :directives
 			
+			# Encode the name of the cookie.
 			def encoded_name
 				URL.escape(@name)
 			end
 			
+			# Encode the value of the cookie.
 			def encoded_value
 				URL.escape(@value)
 			end
 			
+			# Convert the cookie to a string.
+			#
+			# @returns [String] The string representation of the cookie.
 			def to_s
 				buffer = String.new.b
 				
@@ -49,6 +64,10 @@ module Protocol
 				return buffer
 			end
 			
+			# Parse a string into a cookie.
+			#
+			# @parameter string [String] The string to parse.
+			# @returns [Cookie] The parsed cookie.
 			def self.parse(string)
 				head, *directives = string.split(/\s*;\s*/)
 				
@@ -62,6 +81,10 @@ module Protocol
 				)
 			end
 			
+			# Parse a list of strings into a hash of directives.
+			#
+			# @parameter strings [Array(String)] The list of strings to parse.
+			# @returns [Hash] The hash of directives.
 			def self.parse_directives(strings)
 				strings.collect do |string|
 					key, value = string.split("=", 2)

data/lib/protocol/http/header/authorization.rb

@@ -12,13 +12,21 @@ module Protocol
 			# ~~~ ruby
 			# headers.add('authorization', Authorization.basic("my_username", "my_password"))
 			# ~~~
+			#
+			# TODO Support other authorization mechanisms, e.g. bearer token.
 			class Authorization < String
-				# Splits the header and 
-				# @return [Tuple(String, String)]
+				# Splits the header into the credentials.
+				#
+				# @returns [Tuple(String, String)] The username and password.
 				def credentials
 					self.split(/\s+/, 2)
 				end
 				
+				# Generate a new basic authorization header, encoding the given username and password.
+				#
+				# @parameter username [String] The username.
+				# @parameter password [String] The password.
+				# @returns [Authorization] The basic authorization header.
 				def self.basic(username, password)
 					strict_base64_encoded = ["#{username}:#{password}"].pack("m0")
 					

data/lib/protocol/http/header/cache_control.rb

@@ -9,86 +9,118 @@ require_relative "split"
 module Protocol
 	module HTTP
 		module Header
+			# Represents the `cache-control` header, which is a list of cache directives.
 			class CacheControl < Split
+				# The `private` directive indicates that the response is intended for a single user and must not be stored by shared caches.
 				PRIVATE = "private"
+				
+				# The `public` directive indicates that the response may be stored by any cache, even if it would normally be considered non-cacheable.
 				PUBLIC = "public"
+				
+				# The `no-cache` directive indicates that caches must revalidate the response with the origin server before serving it to clients.
 				NO_CACHE = "no-cache"
+				
+				# The `no-store` directive indicates that caches must not store the response under any circumstances.
 				NO_STORE = "no-store"
+				
+				# The `max-age` directive indicates the maximum amount of time, in seconds, that a response is considered fresh.
 				MAX_AGE = "max-age"
+				
+				# The `s-maxage` directive is similar to `max-age` but applies only to shared caches. If both `s-maxage` and `max-age` are present, `s-maxage` takes precedence in shared caches.
 				S_MAXAGE = "s-maxage"
 				
+				# The `static` directive is a custom directive often used to indicate that the resource is immutable or rarely changes, allowing longer caching periods.
 				STATIC = "static"
+				
+				# The `dynamic` directive is a custom directive used to indicate that the resource is generated dynamically and may change frequently, requiring shorter caching periods.
 				DYNAMIC = "dynamic"
+				
+				# The `streaming` directive is a custom directive used to indicate that the resource is intended for progressive or chunked delivery, such as live video streams.
 				STREAMING = "streaming"
 				
+				# The `must-revalidate` directive indicates that once a response becomes stale, caches must not use it to satisfy subsequent requests without revalidating it with the origin server.
 				MUST_REVALIDATE = "must-revalidate"
+				
+				# The `proxy-revalidate` directive is similar to `must-revalidate` but applies only to shared caches.
 				PROXY_REVALIDATE = "proxy-revalidate"
 				
+				# Initializes the cache control header with the given value. The value is expected to be a comma-separated string of cache directives.
+				#
+				# @parameter value [String | Nil] the raw Cache-Control header value.
 				def initialize(value = nil)
 					super(value&.downcase)
 				end
 				
+				# Adds a directive to the Cache-Control header. The value will be normalized to lowercase before being added.
+				#
+				# @parameter value [String] the directive to add.
 				def << value
 					super(value.downcase)
 				end
 				
+				# @returns [Boolean] whether the `static` directive is present.
 				def static?
 					self.include?(STATIC)
 				end
 				
+				# @returns [Boolean] whether the `dynamic` directive is present.
 				def dynamic?
 					self.include?(DYNAMIC)
 				end
 				
+				# @returns [Boolean] whether the `streaming` directive is present.
 				def streaming?
 					self.include?(STREAMING)
 				end
 				
+				# @returns [Boolean] whether the `private` directive is present.
 				def private?
 					self.include?(PRIVATE)
 				end
 				
+				# @returns [Boolean] whether the `public` directive is present.
 				def public?
 					self.include?(PUBLIC)
 				end
 				
+				# @returns [Boolean] whether the `no-cache` directive is present.
 				def no_cache?
 					self.include?(NO_CACHE)
 				end
 				
+				# @returns [Boolean] whether the `no-store` directive is present.
 				def no_store?
 					self.include?(NO_STORE)
 				end
 				
-				# Indicates that a response must not be used once it is stale.
-				# See https://www.rfc-editor.org/rfc/rfc9111.html#name-must-revalidate
+				# @returns [Boolean] whether the `must-revalidate` directive is present.
 				def must_revalidate?
 					self.include?(MUST_REVALIDATE)
 				end
 				
-				# Like must-revalidate, but for shared caches only.
-				# See https://www.rfc-editor.org/rfc/rfc9111.html#name-proxy-revalidate
+				# @returns [Boolean] whether the `proxy-revalidate` directive is present.
 				def proxy_revalidate?
 					self.include?(PROXY_REVALIDATE)
 				end
 				
-				# The maximum time, in seconds, a response should be considered fresh.
-				# See https://www.rfc-editor.org/rfc/rfc9111.html#name-max-age-2
+				# @returns [Integer | Nil] the value of the `max-age` directive in seconds, or `nil` if the directive is not present or invalid.
 				def max_age
 					find_integer_value(MAX_AGE)
 				end
 				
-				# Like max-age, but for shared caches only, which should use it before
-				# max-age when present.
-				# See https://www.rfc-editor.org/rfc/rfc9111.html#name-s-maxage
+				# @returns [Integer | Nil] the value of the `s-maxage` directive in seconds, or `nil` if the directive is not present or invalid.
 				def s_maxage
 					find_integer_value(S_MAXAGE)
 				end
 				
 				private
 				
+				# Finds and parses an integer value from a directive.
+				#
+				# @parameter value_name [String] the directive name to search for (e.g., "max-age").
+				# @returns [Integer | Nil] the parsed integer value, or `nil` if not found or invalid.
 				def find_integer_value(value_name)
-					if value = self.find{|value| value.start_with?(value_name)}
+					if value = self.find { |value| value.start_with?(value_name) }
 						_, age = value.split("=", 2)
 						
 						if age =~ /\A[0-9]+\z/

data/lib/protocol/http/header/connection.rb

@@ -9,31 +9,48 @@ require_relative "split"
 module Protocol
 	module HTTP
 		module Header
+			# Represents the `connection` HTTP header, which controls options for the current connection.
+			#
+			# The `connection` header is used to specify control options such as whether the connection should be kept alive, closed, or upgraded to a different protocol.
 			class Connection < Split
+				# The `keep-alive` directive indicates that the connection should remain open for future requests or responses, avoiding the overhead of opening a new connection.
 				KEEP_ALIVE = "keep-alive"
+				
+				# The `close` directive indicates that the connection should be closed after the current request and response are complete.
 				CLOSE = "close"
+				
+				# The `upgrade` directive indicates that the connection should be upgraded to a different protocol, as specified in the `Upgrade` header.
 				UPGRADE = "upgrade"
 				
+				# Initializes the connection header with the given value. The value is expected to be a comma-separated string of directives.
+				#
+				# @parameter value [String | Nil] the raw `connection` header value.
 				def initialize(value = nil)
 					super(value&.downcase)
 				end
 				
+				# Adds a directive to the `connection` header. The value will be normalized to lowercase before being added.
+				#
+				# @parameter value [String] the directive to add.
 				def << value
 					super(value.downcase)
 				end
 				
+				# @returns [Boolean] whether the `keep-alive` directive is present and the connection is not marked for closure with the `close` directive.
 				def keep_alive?
 					self.include?(KEEP_ALIVE) && !close?
 				end
 				
+				# @returns [Boolean] whether the `close` directive is present, indicating that the connection should be closed after the current request and response.
 				def close?
 					self.include?(CLOSE)
 				end
 				
+				# @returns [Boolean] whether the `upgrade` directive is present, indicating that the connection should be upgraded to a different protocol.
 				def upgrade?
 					self.include?(UPGRADE)
 				end
 			end
 		end
 	end
-end
+end

data/lib/protocol/http/header/cookie.rb

@@ -9,8 +9,13 @@ require_relative "../cookie"
 module Protocol
 	module HTTP
 		module Header
-			# The Cookie HTTP request header contains stored HTTP cookies previously sent by the server with the Set-Cookie header.
+			# The `cookie` header contains stored HTTP cookies previously sent by the server with the `set-cookie` header.
+			#
+			# It is used by clients to send key-value pairs representing stored cookies back to the server.
 			class Cookie < Multiple
+				# Parses the `cookie` header into a hash of cookie names and their corresponding cookie objects.
+				#
+				# @returns [Hash(String, HTTP::Cookie)] a hash where keys are cookie names and values are {HTTP::Cookie} objects.
 				def to_h
 					cookies = self.collect do |string|
 						HTTP::Cookie.parse(string)
@@ -20,9 +25,11 @@ module Protocol
 				end
 			end
 			
-			# The Set-Cookie HTTP response header sends cookies from the server to the user agent.
+			# The `set-cookie` header sends cookies from the server to the user agent.
+			#
+			# It is used to store cookies on the client side, which are then sent back to the server in subsequent requests using the `cookie` header.
 			class SetCookie < Cookie
 			end
 		end
 	end
-end
+end

data/lib/protocol/http/header/date.rb

@@ -8,11 +8,20 @@ require "time"
 module Protocol
 	module HTTP
 		module Header
+			# The `date` header represents the date and time at which the message was originated.
+			#
+			# This header is typically included in HTTP responses and follows the format defined in RFC 9110.
 			class Date < String
+				# Replaces the current value of the `date` header with the specified value.
+				#
+				# @parameter value [String] the new value for the `date` header.
 				def << value
 					replace(value)
 				end
 				
+				# Converts the `date` header value to a `Time` object.
+				#
+				# @returns [Time] the parsed time object corresponding to the `date` header value.
 				def to_time
 					::Time.parse(self)
 				end

data/lib/protocol/http/header/etag.rb

@@ -6,11 +6,22 @@
 module Protocol
 	module HTTP
 		module Header
+			# The `etag` header represents the entity tag for a resource.
+			#
+			# The `etag` header provides a unique identifier for a specific version of a resource, typically used for cache validation or conditional requests. It can be either a strong or weak validator as defined in RFC 9110.
 			class ETag < String
+				# Replaces the current value of the `etag` header with the specified value.
+				#
+				# @parameter value [String] the new value for the `etag` header.
 				def << value
 					replace(value)
 				end
 				
+				# Checks whether the `etag` is a weak validator.
+				#
+				# Weak validators indicate semantically equivalent content but may not be byte-for-byte identical.
+				#
+				# @returns [Boolean] whether the `etag` is weak.
 				def weak?
 					self.start_with?("W/")
 				end

data/lib/protocol/http/header/etags.rb

@@ -9,32 +9,63 @@ require_relative "split"
 module Protocol
 	module HTTP
 		module Header
+			# The `etags` header represents a list of entity tags (ETags) for resources.
+			#
+			# The `etags` header is used for conditional requests to compare the current version of a resource with previously stored versions. It supports both strong and weak validators, as well as the wildcard character (`*`) to indicate a match for any resource.
 			class ETags < Split
+				# Checks if the `etags` header contains the wildcard (`*`) character.
+				#
+				# The wildcard character matches any resource version, regardless of its actual value.
+				#
+				# @returns [Boolean] whether the wildcard is present.
 				def wildcard?
 					self.include?("*")
 				end
 				
-				# This implementation is not strictly correct according to the RFC-specified format.
+				# Checks if the specified ETag matches the `etags` header.
+				#
+				# This method returns `true` if the wildcard is present or if the exact ETag is found in the list. Note that this implementation is not strictly compliant with the RFC-specified format.
+				#
+				# @parameter etag [String] the ETag to compare against the `etags` header.
+				# @returns [Boolean] whether the specified ETag matches.
 				def match?(etag)
 					wildcard? || self.include?(etag)
 				end
 				
-				# Useful with If-Match
+				# Checks for a strong match with the specified ETag, useful with the `if-match` header.
+				#
+				# A strong match requires that the ETag in the header list matches the specified ETag and that neither is a weak validator.
+				#
+				# @parameter etag [String] the ETag to compare against the `etags` header.
+				# @returns [Boolean] whether a strong match is found.
 				def strong_match?(etag)
 					wildcard? || (!weak_tag?(etag) && self.include?(etag))
 				end
 				
-				# Useful with If-None-Match
+				# Checks for a weak match with the specified ETag, useful with the `if-none-match` header.
+				#
+				# A weak match allows for semantically equivalent content, including weak validators and their strong counterparts.
+				#
+				# @parameter etag [String] the ETag to compare against the `etags` header.
+				# @returns [Boolean] whether a weak match is found.
 				def weak_match?(etag)
 					wildcard? || self.include?(etag) || self.include?(opposite_tag(etag))
 				end
 				
 				private
-			
+				
+				# Converts a weak tag to its strong counterpart or vice versa.
+				#
+				# @parameter etag [String] the ETag to convert.
+				# @returns [String] the opposite form of the provided ETag.
 				def opposite_tag(etag)
 					weak_tag?(etag) ? etag[2..-1] : "W/#{etag}"
 				end
 				
+				# Checks if the given ETag is a weak validator.
+				#
+				# @parameter tag [String] the ETag to check.
+				# @returns [Boolean] whether the tag is weak.
 				def weak_tag?(tag)
 					tag&.start_with? "W/"
 				end

data/lib/protocol/http/header/multiple.rb

@@ -6,14 +6,22 @@
 module Protocol
 	module HTTP
 		module Header
-			# Header value which is split by newline charaters (e.g. cookies).
+			# Represents headers that can contain multiple distinct values separated by newline characters.
+			#
+			# This isn't a specific header but is used as a base for headers that store multiple values, such as cookies. The values are split and stored as an array internally, and serialized back to a newline-separated string when needed.
 			class Multiple < Array
+				# Initializes the multiple header with the given value. As the header key-value pair can only contain one value, the value given here is added to the internal array, and subsequent values can be added using the `<<` operator.
+				#
+				# @parameter value [String] the raw header value.
 				def initialize(value)
 					super()
 					
 					self << value
 				end
 				
+				# Serializes the stored values into a newline-separated string.
+				#
+				# @returns [String] the serialized representation of the header values.
 				def to_s
 					join("\n")
 				end

data/lib/protocol/http/header/priority.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require_relative "split"
+
+module Protocol
+	module HTTP
+		module Header
+			# Represents the `priority` header, used to indicate the relative importance of an HTTP request.
+			#
+			# The `priority` header allows clients to express their preference for how resources should be prioritized by the server. It can include directives like `urgency` to specify the importance of a request, and `progressive` to indicate whether a response can be delivered incrementally.
+			class Priority < Split
+				# Urgency levels as defined in RFC 9218:
+				#
+				# These levels indicate the relative importance of a request, helping servers and intermediaries allocate resources efficiently. Properly setting urgency can significantly improve user-perceived performance by prioritizing critical content and deferring less important tasks.
+				module Urgency
+					# `background` priority indicates a request that is not time-sensitive and can be processed with minimal impact to other tasks. It is ideal for requests like analytics or logging, which do not directly impact the user's current experience.
+					BACKGROUND = "background"
+					
+					# `low` priority indicates a request that is important but not critical. It is suitable for content like non-blocking images, videos, or scripts that enhance the experience but do not affect core functionality.
+					LOW = "low"
+					
+					# `normal` priority (default) indicates the standard priority for most requests. It is appropriate for content like text, CSS, or essential images that are necessary for the primary user experience but do not require urgent delivery.
+					NORMAL = "normal"
+					
+					# `high` priority indicates the highest priority, used for requests that are essential and time-critical to the user experience. Examples include content above-the-fold on a webpage, critical API calls, or resources required for rendering.
+					HIGH = "high"
+				end
+				
+				# The `progressive` flag indicates that the response can be delivered incrementally (progressively) as data becomes available. This is particularly useful for large resources like images or video streams, where partial delivery improves the user experience by allowing content to render or play before the full response is received.
+				PROGRESSIVE = "progressive"
+				
+				# Initialize the priority header with the given value.
+				#
+				# @parameter value [String | Nil] the value of the priority header, if any.
+				def initialize(value = nil)
+					super(value&.downcase)
+				end
+				
+				# Add a value to the priority header.
+				def << value
+					super(value.downcase)
+				end
+				
+				# Returns the urgency level if specified.
+				#
+				# @returns [String | Nil] the urgency level if specified, or `nil`.
+				def urgency
+					if value = self.find{|value| value.start_with?("urgency=")}
+						_, level = value.split("=", 2)
+						
+						return level
+					end
+				end
+				
+				# @returns [Boolean] whether the request should be delivered progressively.
+				def progressive?
+					self.include?(PROGRESSIVE)
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http/header/split.rb

@@ -6,22 +6,36 @@
 module Protocol
 	module HTTP
 		module Header
-			# Header value which is split by commas.
+			# Represents headers that can contain multiple distinct values separated by commas.
+			#
+			# This isn't a specific header  class is a utility for handling headers with comma-separated values, such as `accept`, `cache-control`, and other similar headers. The values are split and stored as an array internally, and serialized back to a comma-separated string when needed.
 			class Split < Array
+				# Regular expression used to split values on commas, with optional surrounding whitespace.
 				COMMA = /\s*,\s*/
 				
-				def initialize(value)
+				# Initializes a `Split` header with the given value. If the value is provided, it is split into distinct entries and stored as an array.
+				#
+				# @parameter value [String | Nil] the raw header value containing multiple entries separated by commas, or `nil` for an empty header.
+				def initialize(value = nil)
 					if value
 						super(value.split(COMMA))
 					else
-						super([])
+						super()
 					end
 				end
 				
+				# Adds one or more comma-separated values to the header.
+				#
+				# The input string is split into distinct entries and appended to the array.
+				#
+				# @parameter value [String] the value or values to add, separated by commas.
 				def << value
 					self.push(*value.split(COMMA))
 				end
 				
+				# Serializes the stored values into a comma-separated string.
+				#
+				# @returns [String] the serialized representation of the header values.
 				def to_s
 					join(",")
 				end

data/lib/protocol/http/header/vary.rb

@@ -8,15 +8,24 @@ require_relative "split"
 module Protocol
 	module HTTP
 		module Header
+			# Represents the `vary` header, which specifies the request headers a server considers when determining the response.
+			#
+			# The `vary` header is used in HTTP responses to indicate which request headers affect the selected response. It allows caches to differentiate stored responses based on specific request headers.
 			class Vary < Split
+				# Initializes a `Vary` header with the given value. The value is split into distinct entries and converted to lowercase for normalization.
+				#
+				# @parameter value [String] the raw header value containing request header names separated by commas.
 				def initialize(value)
 					super(value.downcase)
 				end
 				
+				# Adds one or more comma-separated values to the `vary` header. The values are converted to lowercase for normalization.
+				#
+				# @parameter value [String] the value or values to add, separated by commas.
 				def << value
 					super(value.downcase)
 				end
 			end
 		end
 	end
-end
+end