philiprehberger-header_kit 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 255a0f1f4321e63ae82d6acaf028cddb9a041d4f1594b16dcbb8f2a51f54a286
-  data.tar.gz: 1a0ea312d1937e9e17c7cabe31f7822345d0de02f4627d09c597c5a71a5b7715
+  metadata.gz: 8a240cb6bc501c7737d126492c7ef3d97eeb12dfde706a9223eb4e4021f0ded1
+  data.tar.gz: 1eda330a4c801573f6a96fa909562859e8636d5f015905a97cc298afad22cc8b
 SHA512:
-  metadata.gz: ee48374d55f01e11ae5b499c31556037801082a6631ed60306d544109897715bf5510eff7403675e2e94795257903efe289469bd790181cc2c32fef70e65a975
-  data.tar.gz: 40cf00b3c4d3d9f88d50ab21f08fc2dfb2d75b9ee13e879f985d59b28a14e81c600376d13d8f13f9bafb4edd3ff9350d6c4f6d5766abf20e9dd94bd2fd9e706c
+  metadata.gz: aa7df933af28801ee3819f973a69b8a4bc95fc6bb1129bc15821ca9454df21836e57874ecab24a7ff44eabd4618d3439dfb5e1fd9c8a83b1a459af80c0bfd0c8
+  data.tar.gz: 1583acd2a93ff399eaa4a559e86551b43788363305eb9f43066fe97eef353d012b575034416c2b09d5e950943e20d307d033c7595d9e7601868e43ff3c31ceb5

data/CHANGELOG.md

@@ -7,6 +7,12 @@ 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

data/README.md

@@ -218,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 |
@@ -243,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/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.6.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
@@ -198,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.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-24 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