protocol-http 0.66.0 → 0.68.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92d72520175c17717320ecbee394b356a159c22d825f2b4e9c5cb5ef93aa2fed
-  data.tar.gz: d0fb84ab33b22734ef0aa72a0d1c5f3af36011106154e415aa1d9aed8f84c570
+  metadata.gz: a3428056fc04e13182008e3f50f457e9b63b688c887c528e4afc8606e447c620
+  data.tar.gz: e1c5a2b380ff917013e2cdf1e8c6bda8a4995d3850fa960bf933177ebc518295
 SHA512:
-  metadata.gz: d4ef6e02a8dc285cf609e5c5be4b3d0d214a4fa6a13e2a270ffbe49935e4253473cfe189d854bdd7c886fee802f5bba08710afe831ef601e0ea30051292b1987
-  data.tar.gz: 3986994c21ef7bafc0606f3b07f21678bddff510389bb4edd1111d79e10e702638002f1b5577d20cfac1a1c1a67144fc2ab0808d71ece4866dd3065b847d7a0d
+  metadata.gz: 6a0554e8f574add7c898db51ecccce34def388ba266c648487ef6f538c0db0d99966f2ee0c15d1462088587e29676ddf94f07531c257326442320cd2d30ab157
+  data.tar.gz: 4acaacb6205bc8dcdd5be3ed7a5993dff2012b7ac61ad3a8a1e6ea607c1f01b481218ef3b60efa6bc34a9a86f982077aabe9ec7bafe43b8659b9272cb1e11d6a

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

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../error"
+
+module Protocol
+	module HTTP
+		module Header
+			# Represents a `range` request header.
+			class Range
+				ParseError = Class.new(Error)
+				
+				TOKEN = /[!#$%&'*+\-.0-9A-Z^_`a-z|~]+/
+				HEADER = /\A(?<unit>#{TOKEN})=(?<ranges>.*)\z/
+				BYTE_RANGE = /\A(?:(?<first>\d+)-(?<last>\d*)|-(?<suffix>\d+))\z/
+				OTHER_RANGE = /\A[\x21-\x2B\x2D-\x7E]+\z/
+				SEPARATOR = /\s*,\s*/
+				
+				# Represents one byte-range-spec or suffix-byte-range-spec.
+				ByteRange = Struct.new(:first, :last) do
+					# Parse one byte range.
+					# @parameter value [String] The byte range to parse.
+					# @returns [ByteRange] The parsed byte range.
+					def self.parse(value)
+						unless match = BYTE_RANGE.match(value)
+							raise ParseError, "Invalid byte range: #{value.inspect}"
+						end
+						
+						if suffix = match[:suffix]
+							return self.new(nil, Integer(suffix))
+						else
+							first = Integer(match[:first])
+							last = match[:last]
+							last = last.empty? ? nil : Integer(last)
+							
+							if last && last < first
+								raise ParseError, "Invalid byte range: #{value.inspect}"
+							end
+							
+							return self.new(first, last)
+						end
+					end
+					
+					# Resolve this byte range against the selected representation size.
+					# @parameter size [Integer] The size of the selected representation.
+					# @returns [::Range | Nil] The resolved range, or `nil` when it is unsatisfiable.
+					def resolve(size)
+						if first
+							if first < size
+								return first..[last || size - 1, size - 1].min
+							end
+						elsif last > 0 && size > 0
+							return [0, size - last].max..size - 1
+						end
+						
+						return nil
+					end
+					
+					# Convert this byte range to its wire representation.
+					# @returns [String] The serialized byte range.
+					def to_s
+						if first
+							"#{first}-#{last}"
+						else
+							"-#{last}"
+						end
+					end
+				end
+				
+				# Parse a raw range header value.
+				# @parameter value [String] The raw header value.
+				# @returns [Range] The parsed range header.
+				def self.parse(value)
+					unless match = HEADER.match(value)
+						raise ParseError, "Invalid range header: #{value.inspect}"
+					end
+					
+					unit = match[:unit].downcase
+					ranges = match[:ranges].split(SEPARATOR, -1)
+					
+					if ranges.empty? || ranges.any?(&:empty?)
+						raise ParseError, "Invalid range set: #{match[:ranges].inspect}"
+					end
+					
+					if unit == "bytes"
+						ranges.map!{|range| ByteRange.parse(range)}
+					elsif ranges.any?{|range| !OTHER_RANGE.match?(range)}
+						raise ParseError, "Invalid range set: #{match[:ranges].inspect}"
+					end
+					
+					return self.new(unit, ranges)
+				end
+				
+				# Coerce a value into a range header.
+				# @parameter value [Object] The value to coerce.
+				# @returns [Range] The parsed range header.
+				def self.coerce(value)
+					self.parse(value.to_s)
+				end
+				
+				# Initialize a range header.
+				# @parameter unit [String] The range unit.
+				# @parameter ranges [Array] The range specifiers.
+				def initialize(unit, ranges)
+					@unit = unit
+					@ranges = ranges
+				end
+				
+				# @attribute [String] The range unit.
+				attr :unit
+				
+				# @attribute [Array] The range specifiers.
+				attr :ranges
+				
+				# Whether this header contains byte ranges.
+				# @returns [Boolean] Whether the range unit is `bytes`.
+				def bytes?
+					@unit == "bytes"
+				end
+				
+				# Resolve all byte ranges against the selected representation size.
+				# @parameter size [Integer] The size of the selected representation.
+				# @returns [Array(::Range)] The satisfiable byte ranges.
+				def resolve(size)
+					unless bytes?
+						raise ArgumentError, "Cannot resolve #{@unit.inspect} ranges as byte ranges!"
+					end
+					
+					size = Integer(size)
+					raise ArgumentError, "Size must not be negative!" if size < 0
+					
+					@ranges.filter_map{|range| range.resolve(size)}
+				end
+				
+				# Combine another raw range header value with this one.
+				# @parameter value [String] The raw range header value.
+				def <<(value)
+					other = self.class.parse(value)
+					
+					unless other.unit == @unit
+						raise ParseError, "Cannot combine range units: #{@unit.inspect} and #{other.unit.inspect}"
+					end
+					
+					@ranges.concat(other.ranges)
+					
+					return self
+				end
+				
+				# Convert this header to its wire representation.
+				# @returns [String] The serialized range header.
+				def to_s
+					"#{@unit}=#{@ranges.join(",")}"
+				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# @returns [Boolean] `false`, as range headers apply to a selected representation.
+				def self.trailer?
+					false
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http/headers.rb

@@ -18,6 +18,7 @@ require_relative "header/vary"
 require_relative "header/authorization"
 require_relative "header/date"
 require_relative "header/priority"
+require_relative "header/range"
 require_relative "header/trailer"
 require_relative "header/server_timing"
 require_relative "header/digest"
@@ -347,7 +348,7 @@ module Protocol
 				"host" => false,
 				"location" => false,
 				"max-forwards" => false,
-				"range" => false,
+				"range" => Header::Range,
 				"referer" => false,
 				"retry-after" => false,
 				"server" => false,

data/lib/protocol/http/status.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Protocol
+	module HTTP
+		# HTTP status codes and their human-readable descriptions.
+		module Status
+			# Human-readable descriptions for registered and conventional HTTP status codes.
+			DESCRIPTIONS = {
+				100 => "Continue",
+				101 => "Switching Protocols",
+				102 => "Processing",
+				103 => "Early Hints",
+				
+				200 => "OK",
+				201 => "Created",
+				202 => "Accepted",
+				203 => "Non-Authoritative Information",
+				204 => "No Content",
+				205 => "Reset Content",
+				206 => "Partial Content",
+				207 => "Multi-Status",
+				208 => "Already Reported",
+				226 => "IM Used",
+				
+				300 => "Multiple Choices",
+				301 => "Moved Permanently",
+				302 => "Found",
+				303 => "See Other",
+				304 => "Not Modified",
+				305 => "Use Proxy",
+				306 => "Switch Proxy",
+				307 => "Temporary Redirect",
+				308 => "Permanent Redirect",
+				
+				400 => "Bad Request",
+				401 => "Unauthorized",
+				402 => "Payment Required",
+				403 => "Forbidden",
+				404 => "Not Found",
+				405 => "Method Not Allowed",
+				406 => "Not Acceptable",
+				407 => "Proxy Authentication Required",
+				408 => "Request Timeout",
+				409 => "Conflict",
+				410 => "Gone",
+				411 => "Length Required",
+				412 => "Precondition Failed",
+				413 => "Content Too Large",
+				414 => "URI Too Long",
+				415 => "Unsupported Media Type",
+				416 => "Range Not Satisfiable",
+				417 => "Expectation Failed",
+				418 => "I'm a Teapot",
+				421 => "Misdirected Request",
+				422 => "Unprocessable Content",
+				423 => "Locked",
+				424 => "Failed Dependency",
+				425 => "Too Early",
+				426 => "Upgrade Required",
+				428 => "Precondition Required",
+				429 => "Too Many Requests",
+				431 => "Request Header Fields Too Large",
+				451 => "Unavailable For Legal Reasons",
+				
+				500 => "Internal Server Error",
+				501 => "Not Implemented",
+				502 => "Bad Gateway",
+				503 => "Service Unavailable",
+				504 => "Gateway Timeout",
+				505 => "HTTP Version Not Supported",
+				506 => "Variant Also Negotiates",
+				507 => "Insufficient Storage",
+				508 => "Loop Detected",
+				510 => "Not Extended",
+				511 => "Network Authentication Required",
+			}.freeze
+			
+			# Look up the human-readable description for a status code.
+			# @parameter code [Integer] The HTTP status code.
+			# @returns [String | Nil] The standard description, if known.
+			def self.description(code)
+				return DESCRIPTIONS[code]
+			end
+		end
+	end
+end

data/lib/protocol/http/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module HTTP
-		VERSION = "0.66.0"
+		VERSION = "0.68.0"
 	end
 end

data/lib/protocol/http.rb

@@ -5,6 +5,7 @@
 
 require_relative "http/version"
 
+require_relative "http/status"
 require_relative "http/headers"
 require_relative "http/request"
 require_relative "http/response"

data/readme.md

@@ -30,6 +30,14 @@ Please see the [project documentation](https://socketry.github.io/protocol-http/
 
 Please see the [project releases](https://socketry.github.io/protocol-http/releases/index) for all releases.
 
+### v0.68.0
+
+  - Add HTTP status descriptions.
+
+### v0.67.0
+
+  - Parse and resolve HTTP `Range` header values according to the default headers policy.
+
 ### v0.66.0
 
   - Introduce `Protocol::HTTP::RemoteError` for remote endpoint failures where application processing may have occurred.
@@ -64,16 +72,6 @@ Please see the [project releases](https://socketry.github.io/protocol-http/relea
   - Introduce `Protocol::HTTP::Middleware.load` method for loading middleware applications from files.
   - Prevent `ZLib::BufError` when deflating empty chunks by skipping deflation for empty chunks.
 
-### v0.58.1
-
-  - `Protocol::HTTP::DuplicateHeaderError` now includes the existing and new values for better debugging.
-
-### v0.58.0
-
-  - Move trailer validation to `Headers#add` method to ensure all additions are checked at the time of addition as this is a hard requirement.
-  - Introduce `Headers#header` method to enumerate only the main headers, excluding trailers. This can be used after invoking `Headers#trailer!` to avoid race conditions.
-  - Fix `Headers#to_h` so that indexed headers are not left in an inconsistent state if errors occur during processing.
-
 ## See Also
 
   - [protocol-http1](https://github.com/socketry/protocol-http1) — HTTP/1 client/server implementation using this

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.68.0
+
+  - Add HTTP status descriptions.
+
+## v0.67.0
+
+  - Parse and resolve HTTP `Range` header values according to the default headers policy.
+
 ## v0.66.0
 
   - Introduce `Protocol::HTTP::RemoteError` for remote endpoint failures where application processing may have occurred.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-http
 version: !ruby/object:Gem::Version
-  version: 0.66.0
+  version: 0.68.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -97,6 +97,7 @@ files:
 - lib/protocol/http/header/generic.rb
 - lib/protocol/http/header/multiple.rb
 - lib/protocol/http/header/priority.rb
+- lib/protocol/http/header/range.rb
 - lib/protocol/http/header/server_timing.rb
 - lib/protocol/http/header/set_cookie.rb
 - lib/protocol/http/header/split.rb
@@ -112,6 +113,7 @@ files:
 - lib/protocol/http/quoted_string.rb
 - lib/protocol/http/request.rb
 - lib/protocol/http/response.rb
+- lib/protocol/http/status.rb
 - lib/protocol/http/version.rb
 - license.md
 - readme.md