Headers#[]= handles Array values.

- `Header::*.new(value)` method expects the correct data type and does not coerce from String.
- Parsing logic was moved to `Header::*.parse(value)`.
- Coercion to header values is now handled by `Header::*.coerce(value)`.

Author: samuel-williams-shopify

lib/protocol/http/body/stream.rb

@@ -10,7 +10,7 @@
 module Protocol
 	module HTTP
 		module Body
-			# The input stream is an IO-like object which contains the raw HTTP POST data. When applicable, its external encoding must be “ASCII-8BIT” and it must be opened in binary mode, for Ruby 1.9 compatibility. The input stream must respond to gets, each, read and rewind.
+			# The input stream is an IO-like object which contains the raw HTTP POST data. When applicable, its external encoding must be "ASCII-8BIT" and it must be opened in binary mode, for Ruby 1.9 compatibility. The input stream must respond to gets, each, read and rewind.
 			class Stream
 				# The default line separator, used by {gets}.
 				NEWLINE = "\n"

lib/protocol/http/body/streamable.rb

@@ -127,10 +127,10 @@ def call(stream)
 
 						# Ownership of the stream is passed into the block, in other words, the block is responsible for closing the stream.
 						block.call(stream)
-					rescue => error
-						# If, for some reason, the block raises an error, we assume it may not have closed the stream, so we close it here:
-						stream.close
-						raise
+							rescue => error
+								# If, for some reason, the block raises an error, we assume it may not have closed the stream, so we close it here:
+								stream.close
+								raise
 					end
 
 					# Close the input. The streaming body will eventually read all the input.

lib/protocol/http/header/accept.rb

@@ -68,27 +68,54 @@ def quality_factor
 					end
 				end
 
-				# Parse the `accept` header value into a list of content types.
+				# Parses a raw header value from the wire.
 				#
-				# @parameter value [String] the value of the header.
+				# @parameter value [String] the raw header value containing comma-separated media types.
+				# @returns [Accept] a new instance containing the parsed media types.
+				def self.parse(value)
+					self.new(value.scan(SEPARATOR).map(&:strip))
+				end
+				
+				# Coerces a value into a parsed header object.
+				#
+				# @parameter value [String | Array] the value to coerce.
+				# @returns [Accept] a parsed header object.
+				def self.coerce(value)
+					case value
+					when Array
+						self.new(value)
+					else
+						self.parse(value.to_s)
+					end
+				end
+				
+				# Initializes an Accept header with already-parsed values.
+				#
+				# @parameter value [Array | Nil] an array of parsed media type strings, or `nil` for an empty header.
 				def initialize(value = nil)
-					if value
-						super(value.scan(SEPARATOR).map(&:strip))
+					if value.is_a?(Array)
+						super(value)
+					elsif value.is_a?(String)
+						# Compatibility with the old constructor, prefer to use `parse` instead:
+						super()
+						self << value
+					elsif value
+						raise ArgumentError, "Invalid value: #{value.inspect}"
 					end
 				end
 
-				# Adds one or more comma-separated values to the header.
+				# Adds one or more comma-separated values to the header from a raw wire-format string.
 				#
 				# 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.
+				# @parameter value [String] a raw wire-format value containing one or more media types separated by commas.
 				def << value
 					self.concat(value.scan(SEPARATOR).map(&:strip))
 				end
 
-				# Serializes the stored values into a comma-separated string.
+				# Converts the parsed header value into a raw wire-format string.
 				#
-				# @returns [String] the serialized representation of the header values.
+				# @returns [String] a raw wire-format value (comma-separated string) suitable for transmission.
 				def to_s
 					join(",")
 				end

lib/protocol/http/header/authorization.rb

@@ -15,6 +15,22 @@ module Header
 			#
 			# TODO Support other authorization mechanisms, e.g. bearer token.
 			class Authorization < String
+				# Parses a raw header value from the wire.
+				#
+				# @parameter value [String] the raw header value.
+				# @returns [Authorization] a new instance.
+				def self.parse(value)
+					self.new(value)
+				end
+				
+				# Coerces a value into a parsed header object.
+				#
+				# @parameter value [String] the value to coerce.
+				# @returns [Authorization] a parsed header object.
+				def self.coerce(value)
+					self.new(value.to_s)
+				end
+				
 				# Splits the header into the credentials.
 				#
 				# @returns [Tuple(String, String)] The username and password.

lib/protocol/http/header/cache_control.rb

@@ -44,16 +44,24 @@ class CacheControl < Split
 				# 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)
+			# Initializes the cache control header with already-parsed and normalized values.
+			#
+			# @parameter value [Array | Nil] an array of normalized (lowercase) directives, or `nil` for an empty header.
+			def initialize(value = nil)
+				if value.is_a?(Array)
+					super(value.map(&:downcase))
+				elsif value.is_a?(String)
+					# Compatibility with the old constructor, prefer to use `parse` instead:
+					super()
+					self << value
+				elsif value
+					raise ArgumentError, "Invalid value: #{value.inspect}"
 				end
+			end
 
-				# Adds a directive to the Cache-Control header. The value will be normalized to lowercase before being added.
+				# Adds a directive to the Cache-Control header from a raw wire-format string. The value will be normalized to lowercase before being added.
 				#
-				# @parameter value [String] the directive to add.
+				# @parameter value [String] a raw wire-format directive to add.
 				def << value
 					super(value.downcase)
 				end
@@ -132,3 +140,4 @@ def find_integer_value(value_name)
 		end
 	end
 end
+

lib/protocol/http/header/connection.rb

@@ -22,16 +22,24 @@ class Connection < Split
 				# 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)
+			# Initializes the connection header with already-parsed and normalized values.
+			#
+			# @parameter value [Array | Nil] an array of normalized (lowercase) directives, or `nil` for an empty header.
+			def initialize(value = nil)
+				if value.is_a?(Array)
+					super(value.map(&:downcase))
+				elsif value.is_a?(String)
+					# Compatibility with the old constructor, prefer to use `parse` instead:
+					super()
+					self << value
+				elsif value
+					raise ArgumentError, "Invalid value: #{value.inspect}"
 				end
+			end
 
-				# Adds a directive to the `connection` header. The value will be normalized to lowercase before being added.
+				# Adds a directive to the `connection` header from a raw wire-format string. The value will be normalized to lowercase before being added.
 				#
-				# @parameter value [String] the directive to add.
+				# @parameter value [String] a raw wire-format directive to add.
 				def << value
 					super(value.downcase)
 				end
@@ -61,3 +69,4 @@ def self.trailer?
 		end
 	end
 end
+

lib/protocol/http/header/date.rb

@@ -12,9 +12,25 @@ module Header
 			#
 			# 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.
+				# Parses a raw header value from the wire.
 				#
-				# @parameter value [String] the new value for the `date` header.
+				# @parameter value [String] the raw header value.
+				# @returns [Date] a new instance.
+				def self.parse(value)
+					self.new(value)
+				end
+				
+				# Coerces a value into a parsed header object.
+				#
+				# @parameter value [String] the value to coerce.
+				# @returns [Date] a parsed header object.
+				def self.coerce(value)
+					self.new(value.to_s)
+				end
+				
+				# Replaces the current value of the `date` header with a raw wire-format string.
+				#
+				# @parameter value [String] a raw wire-format value for the `date` header.
 				def << value
 					replace(value)
 				end

lib/protocol/http/header/etag.rb

@@ -10,9 +10,25 @@ module Header
 			#
 			# 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.
+				# Parses a raw header value from the wire.
 				#
-				# @parameter value [String] the new value for the `etag` header.
+				# @parameter value [String] the raw header value.
+				# @returns [ETag] a new instance.
+				def self.parse(value)
+					self.new(value)
+				end
+				
+				# Coerces a value into a parsed header object.
+				#
+				# @parameter value [String] the value to coerce.
+				# @returns [ETag] a parsed header object.
+				def self.coerce(value)
+					self.new(value.to_s)
+				end
+				
+				# Replaces the current value of the `etag` header with a raw wire-format string.
+				#
+				# @parameter value [String] a raw wire-format value for the `etag` header.
 				def << value
 					replace(value)
 				end

lib/protocol/http/header/etags.rb

@@ -52,7 +52,7 @@ def weak_match?(etag)
 					wildcard? || self.include?(etag) || self.include?(opposite_tag(etag))
 				end
 
-				private
+			private
 
 				# Converts a weak tag to its strong counterpart or vice versa.
 				#

lib/protocol/http/header/multiple.rb

@@ -10,18 +10,47 @@ module Header
 			#
 			# 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.
+				# Parses a raw header value from the wire.
 				#
-				# @parameter value [String] the raw header value.
-				def initialize(value)
+				# Multiple headers receive each value as a separate header entry on the wire, so this method takes a single string value and creates a new instance containing it.
+				#
+				# @parameter value [String] a single raw header value from the wire.
+				# @returns [Multiple] a new instance containing the parsed value.
+				def self.parse(value)
+					self.new([value])
+				end
+				
+				# Coerces a value into a parsed header object.
+				#
+				# This method is used by the Headers class when setting values via `[]=` to convert application values into the appropriate policy type.
+				#
+				# @parameter value [String | Array] the value to coerce.
+				# @returns [Multiple] a parsed header object.
+				def self.coerce(value)
+					case value
+					when Array
+						self.new(value)
+					else
+						self.parse(value.to_s)
+					end
+				end
+				
+				# Initializes the multiple header with already-parsed values.
+				#
+				# @parameter value [Array | Nil] an array of header values, or `nil` for an empty header.
+				def initialize(value = nil)
 					super()
 
-					self << value
+					if value
+						self.concat(value)
+					end
 				end
 
-				# Serializes the stored values into a newline-separated string.
+				# Converts the parsed header value into a raw wire-format string.
+				#
+				# Multiple headers are transmitted as separate header entries on the wire, so this serializes to a newline-separated string for storage.
 				#
-				# @returns [String] the serialized representation of the header values.
+				# @returns [String] a raw wire-format value (newline-separated string).
 				def to_s
 					join("\n")
 				end