philiprehberger-header_kit 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d06951b5686f64b328c573fc16904e84eddfc61424ab8491fc2da817c7241fca
-  data.tar.gz: 9bdc24a4fc3dabc8d34ccdc105564e5669e9024ada60869c09317fdc11f1c1d6
+  metadata.gz: 8a240cb6bc501c7737d126492c7ef3d97eeb12dfde706a9223eb4e4021f0ded1
+  data.tar.gz: 1eda330a4c801573f6a96fa909562859e8636d5f015905a97cc298afad22cc8b
 SHA512:
-  metadata.gz: 82e06b0e3e146393f17782091fd76c5813be7c46df09c6366d9e892d40a4d05e652655b0017c2cd8242a8812961b428f853cb771e74721e08c46b778911dd124
-  data.tar.gz: f9970a177aa61fa120ea97eceeeda50f19d9517c143b2d91c4bce924a26466c13de2ca88f2a5e00375cadebae0cf2f804436ace824ac0fa3a53d00dbf8f4efec
+  metadata.gz: aa7df933af28801ee3819f973a69b8a4bc95fc6bb1129bc15821ca9454df21836e57874ecab24a7ff44eabd4618d3439dfb5e1fd9c8a83b1a459af80c0bfd0c8
+  data.tar.gz: 1583acd2a93ff399eaa4a559e86551b43788363305eb9f43066fe97eef353d012b575034416c2b09d5e950943e20d307d033c7595d9e7601868e43ff3c31ceb5

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-05-08
+
+### Added
+- `HeaderKit.parse_range(header)` — parses an RFC 7233 Range header into `{ unit:, ranges: [{ first:, last: }, ...] }`. Supports byte ranges, suffix ranges (`-N`), and open-ended ranges (`N-`). Returns `nil` for invalid input.
+- `HeaderKit.build_range(unit, ranges)` — builds a Range header value from an array of `{ first:, last: }` hashes, `[first, last]` arrays, or Ruby `Range` objects (inclusive/exclusive both supported)
+
+## [0.6.0] - 2026-04-23
+
+### Added
+- `HeaderKit.build_accept_encoding(encodings)` for constructing Accept-Encoding headers from an array of `{encoding:, quality:}` hashes, mirroring the existing `build_accept` builder
+
 ## [0.5.0] - 2026-04-17
 
 ### Added

data/README.md

@@ -66,6 +66,17 @@ Philiprehberger::HeaderKit.parse_accept_encoding("gzip, deflate;q=0.5, br;q=0.8"
 # => [{encoding: "gzip", quality: 1.0}, {encoding: "br", quality: 0.8}, {encoding: "deflate", quality: 0.5}]
 ```
 
+### Build Accept-Encoding
+
+```ruby
+Philiprehberger::HeaderKit.build_accept_encoding([
+  {encoding: "gzip"},
+  {encoding: "br", quality: 0.9},
+  {encoding: "deflate", quality: 0.5}
+])
+# => "gzip, br;q=0.9, deflate;q=0.5"
+```
+
 ### Parse Authorization
 
 ```ruby
@@ -207,6 +218,23 @@ Philiprehberger::HeaderKit.parse_retry_after("Fri, 04 Apr 2026 12:00:00 GMT")
 # => {date: 2026-04-04 12:00:00 UTC}
 ```
 
+### Parse and Build Range
+
+```ruby
+Philiprehberger::HeaderKit.parse_range("bytes=0-499")
+# => { unit: "bytes", ranges: [{ first: 0, last: 499 }] }
+
+Philiprehberger::HeaderKit.parse_range("bytes=0-99, 200-, -50")
+# => { unit: "bytes", ranges: [
+#      { first: 0, last: 99 },
+#      { first: 200, last: nil },
+#      { first: nil, last: 50 }
+#    ] }
+
+Philiprehberger::HeaderKit.build_range("bytes", [(0..99), { first: 200, last: nil }])
+# => "bytes=0-99, 200-"
+```
+
 ## API
 
 | Method | Description |
@@ -216,6 +244,7 @@ Philiprehberger::HeaderKit.parse_retry_after("Fri, 04 Apr 2026 12:00:00 GMT")
 | `HeaderKit.parse_accept_language(header)` | Parse Accept-Language into sorted entries |
 | `HeaderKit.negotiate_language(header, available)` | Language negotiation, returns best match or nil |
 | `HeaderKit.parse_accept_encoding(header)` | Parse Accept-Encoding into sorted entries |
+| `HeaderKit.build_accept_encoding(encodings)` | Build Accept-Encoding header string from encoding array |
 | `HeaderKit.parse_authorization(header)` | Parse Authorization header (Bearer, Basic, Digest) |
 | `HeaderKit.parse_cache_control(header)` | Parse Cache-Control into directive hash |
 | `HeaderKit.build_cache_control(directives)` | Build Cache-Control string from hash |
@@ -231,6 +260,8 @@ Philiprehberger::HeaderKit.parse_retry_after("Fri, 04 Apr 2026 12:00:00 GMT")
 | `HeaderKit.parse_forwarded(header)` | Parse RFC 7239 Forwarded header |
 | `HeaderKit.parse_via(header)` | Parse Via header into structured entries |
 | `HeaderKit.parse_retry_after(header)` | Parse Retry-After header (seconds or HTTP date) |
+| `HeaderKit.parse_range(header)` | Parse Range header into `{ unit:, ranges: }` (returns nil for invalid input) |
+| `HeaderKit.build_range(unit, ranges)` | Build a Range header from hashes, arrays, or Ruby Ranges |
 | `HeaderKit.etag_match?(header_value, resource_etag)` | Check If-None-Match / If-Match against a resource ETag (list, `W/` weak prefix, `*` wildcard) |
 
 ## Development

data/lib/philiprehberger/header_kit/accept_encoding.rb

@@ -50,7 +50,37 @@ module Philiprehberger
         value.to_f.clamp(0.0, 1.0)
       end
 
-      private_class_method :parse_entry, :parse_quality
+      # Build an Accept-Encoding header string from an array of encoding hashes.
+      #
+      # @param encodings [Array<Hash>] each with :encoding and optional :quality
+      # @return [String] formatted Accept-Encoding header value
+      def self.build(encodings)
+        return '' if encodings.nil? || encodings.empty?
+
+        parts = encodings.map do |entry|
+          encoding = entry[:encoding]
+          quality = entry[:quality]
+
+          if quality && quality < 1.0
+            "#{encoding};q=#{format_quality(quality)}"
+          else
+            encoding
+          end
+        end
+
+        parts.join(', ')
+      end
+
+      # Format a quality value, removing trailing zeros.
+      #
+      # @param quality [Float] the quality value
+      # @return [String] formatted quality string
+      def self.format_quality(quality)
+        formatted = format('%.3f', quality)
+        formatted.sub(/0+\z/, '').sub(/\.\z/, '.0')
+      end
+
+      private_class_method :parse_entry, :parse_quality, :format_quality
     end
   end
 end

data/lib/philiprehberger/header_kit/range.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HeaderKit
+    # Parses and builds the HTTP Range request header (RFC 7233 §3.1).
+    #
+    # Format: `<unit>=<start>-<end>[, <start>-<end>]*`
+    # Supports byte ranges, suffix ranges (`-N`), and open-ended ranges (`N-`).
+    module Range
+      module_function
+
+      # Parse a Range header value.
+      #
+      # @param header [String, nil] the raw header value
+      # @return [Hash{Symbol => Object}, nil] hash with :unit (String) and :ranges
+      #   (Array of Hash with :first/:last keys, where either may be nil for
+      #   open-ended), or nil for nil/blank/invalid input
+      # @example
+      #   parse('bytes=0-499')        # => { unit: 'bytes', ranges: [{ first: 0, last: 499 }] }
+      #   parse('bytes=500-')         # => { unit: 'bytes', ranges: [{ first: 500, last: nil }] }
+      #   parse('bytes=-500')         # => { unit: 'bytes', ranges: [{ first: nil, last: 500 }] }
+      #   parse('bytes=0-99, 200-')   # => { unit: 'bytes', ranges: [{ first: 0, last: 99 }, { first: 200, last: nil }] }
+      def parse(header)
+        return nil if header.nil?
+
+        header = header.to_s.strip
+        return nil if header.empty?
+
+        unit, _, spec = header.partition('=')
+        unit = unit.strip
+        spec = spec.strip
+        return nil if unit.empty? || spec.empty?
+
+        ranges = spec.split(',').map { |part| parse_range(part.strip) }
+        return nil if ranges.any?(&:nil?)
+
+        { unit: unit, ranges: ranges }
+      end
+
+      # Build a Range header value.
+      #
+      # @param unit [String] the range unit (e.g. 'bytes')
+      # @param ranges [Array<Hash, Array, Range>] each as `{ first:, last: }`,
+      #   a `[first, last]` array, or a Ruby `Range` (inclusive)
+      # @return [String] formatted Range header
+      # @example
+      #   build('bytes', [{ first: 0, last: 499 }])           # => "bytes=0-499"
+      #   build('bytes', [[0, 499], [500, nil]])              # => "bytes=0-499, 500-"
+      #   build('bytes', [(0..99), { first: nil, last: 50 }]) # => "bytes=0-99, -50"
+      def build(unit, ranges)
+        list = ranges.is_a?(Array) ? ranges : [ranges]
+        formatted = list.map { |r| format_range(r) }
+        "#{unit}=#{formatted.join(', ')}"
+      end
+
+      def parse_range(raw)
+        return nil unless raw.match?(/\A-?\d*-\d*\z/)
+        return nil if raw == '-'
+
+        first_str, _, last_str = raw.partition('-')
+        first = first_str.empty? ? nil : Integer(first_str, 10)
+        last = last_str.empty? ? nil : Integer(last_str, 10)
+        return nil if first.nil? && last.nil?
+        return nil if first && last && first > last
+
+        { first: first, last: last }
+      rescue ArgumentError
+        nil
+      end
+      private_class_method :parse_range
+
+      def format_range(spec)
+        first, last =
+          case spec
+          when ::Range then [spec.first, spec.exclude_end? ? spec.last - 1 : spec.last]
+          when Array then [spec[0], spec[1]]
+          when Hash then [spec[:first] || spec['first'], spec[:last] || spec['last']]
+          else raise ArgumentError, "Unsupported range entry: #{spec.inspect}"
+          end
+
+        "#{first}-#{last}"
+      end
+      private_class_method :format_range
+    end
+  end
+end

data/lib/philiprehberger/header_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module HeaderKit
-    VERSION = '0.5.0'
+    VERSION = '0.7.0'
   end
 end

data/lib/philiprehberger/header_kit.rb

@@ -15,6 +15,7 @@ require_relative 'header_kit/negotiation'
 require_relative 'header_kit/cors'
 require_relative 'header_kit/security'
 require_relative 'header_kit/forwarded'
+require_relative 'header_kit/range'
 require_relative 'header_kit/retry_after'
 
 module Philiprehberger
@@ -45,6 +46,14 @@ module Philiprehberger
       AcceptEncoding.parse(header)
     end
 
+    # Build an Accept-Encoding header string from an array of encoding hashes.
+    #
+    # @param encodings [Array<Hash>] each with :encoding and optional :quality
+    # @return [String] formatted Accept-Encoding header value
+    def self.build_accept_encoding(encodings)
+      AcceptEncoding.build(encodings)
+    end
+
     # Parse an Accept-Language header into structured entries sorted by quality.
     #
     # @param header [String] the Accept-Language header value
@@ -190,6 +199,23 @@ module Philiprehberger
       Etag.match?(header_value, resource_etag)
     end
 
+    # Parse a Range request header (RFC 7233 §3.1).
+    #
+    # @param header [String] the Range header value
+    # @return [Hash{Symbol => Object}, nil] hash with :unit and :ranges, or nil for invalid input
+    def self.parse_range(header)
+      Range.parse(header)
+    end
+
+    # Build a Range request header value.
+    #
+    # @param unit [String] the range unit (e.g. 'bytes')
+    # @param ranges [Array<Hash, Array, ::Range>] each as `{ first:, last: }`, `[first, last]`, or `::Range`
+    # @return [String] formatted Range header
+    def self.build_range(unit, ranges)
+      Range.build(unit, ranges)
+    end
+
     # Parse a Retry-After header.
     #
     # Returns a hash with :seconds (Integer) for numeric values,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-header_kit
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-18 00:00:00.000000000 Z
+date: 2026-05-08 00:00:00.000000000 Z
 dependencies: []
 description: Parse and build Accept, Accept-Language, Accept-Encoding, Authorization,
   Cache-Control, Content-Type, Cookie, Link, CORS, Forwarded, and Via HTTP headers.
@@ -36,6 +36,7 @@ files:
 - lib/philiprehberger/header_kit/forwarded.rb
 - lib/philiprehberger/header_kit/link.rb
 - lib/philiprehberger/header_kit/negotiation.rb
+- lib/philiprehberger/header_kit/range.rb
 - lib/philiprehberger/header_kit/retry_after.rb
 - lib/philiprehberger/header_kit/security.rb
 - lib/philiprehberger/header_kit/version.rb