protocol-http 0.45.0 → 0.47.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,55 @@
+# 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 supports directives like `u=` to specify the urgency level of a request, and `i` to indicate whether a response can be delivered incrementally. The urgency levels range from 0 (highest priority) to 7 (lowest priority), while the `i` directive is a boolean flag.
+			class Priority < Split
+				# Initialize the priority header with the given value.
+				#
+				# @parameter value [String | Nil] the value of the priority header, if any. The value should be a comma-separated string of directives.
+				def initialize(value = nil)
+					super(value&.downcase)
+				end
+				
+				# Add a value to the priority header.
+				#
+				# @parameter value [String] the directive to add to the header.
+				def << value
+					super(value.downcase)
+				end
+				
+				# The default urgency level if not specified.
+				DEFAULT_URGENCY = 3
+				
+				# Returns the urgency level if specified. 0 is the highest priority, and 7 is the lowest.
+				#
+				# @returns [Integer | Nil] the urgency level if specified, or `nil` if not present.
+				def urgency(default = DEFAULT_URGENCY)
+					if value = self.find { |value| value.start_with?("u=") }
+						_, level = value.split("=", 2)
+						return level.to_i
+					end
+					
+					return default
+				end
+				
+				# Checks if the response should be delivered incrementally.
+				#
+				# The `i` directive, when present, indicates that the response can be delivered incrementally as data becomes available.
+				#
+				# @returns [Boolean] whether the request should be delivered incrementally.
+				def incremental?
+					self.include?("i")
+				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