serve_byte_range 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 699a0639bd7b8667bba8cb9b53ff26bfd55aaabfec562cfed332979aef0a3702
+  data.tar.gz: 07e18c40f407e2abd4c46cc2e808bcc42bafda180fc18bda1078d3d6e5c1e394
+SHA512:
+  metadata.gz: 14b9ec669046f734e515d0211ee56342bd372ff7ac9d5e9b974b01835340cdb3f58a58caba4e23e82e8de9cb0ddb27a71dc36442f4e07862087bc88a51ee8510
+  data.tar.gz: cf3260ffd5b00d9c82d6dfc4eccf802506c8247c595ac26e479641c3bfb526ef3baea8434d4f0672d14dafc323456b3d9157950cc9e4005d2eac1840ac487940

data/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  - push
+
+env:
+  BUNDLE_PATH: vendor/bundle
+
+jobs:
+  test_and_lint_minimum_ruby:
+    name: Tests/Lint (2.7)
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.7
+          bundler-cache: true
+      - name: "Tests"
+        run: bundle exec rake test --backtrace
+      - name: "Lint"
+        run: bundle exec rake standard
+  test_recent_ruby:
+    name: Tests (3.4)
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.4
+          bundler-cache: true
+      - name: "Tests"
+        run: bundle exec rake test --backtrace

data/.gitignore

@@ -0,0 +1,58 @@
+# rcov generated
+coverage
+coverage.data
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# Rubocop
+rubocop.html
+
+# bundler
+.bundle
+Gemfile.lock
+
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore:
+#
+# * Create a file at ~/.gitignore
+# * Include files you want ignored
+# * Run: git config --global core.excludesfile ~/.gitignore
+#
+# After doing this, these files will be ignored in all your git projects,
+# saving you from having to 'pollute' every project you touch with them
+#
+# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
+#
+# For MacOS:
+#
+.DS_Store
+
+tmp
+.ruby-version
+
+# For TextMate
+#*.tmproj
+#tmtags
+
+# For emacs:
+#*~
+#\#*
+#.\#*
+
+# For vim:
+#*.swp
+
+# For redcar:
+#.redcar
+
+# For rubinius:
+#*.rbc
+
+# Rubocop report
+rubocop.html
+
+pkg/*.gem

data/.standard.yml

@@ -0,0 +1 @@
+ruby_version: 2.7

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,30 @@
+# serve_byte_range
+
+is a small utility for serving HTTP `Range` responses (partial content responses) from your Rails or Rack app. It will allow you to output partial content in a lazy manner without buffering, and perform correct encoding of `multipart/byte-range` responses. It will also make serving byte ranges safer because it coalesces the requested byte ranges into larger, consecutive ranges - reducing overhead.
+
+## Installation and usage
+
+Add it to your Gemfile:
+
+```shell
+bundle add serve_byte_range
+```
+
+and use code like this to serve a large `File` object:
+
+```ruby
+status, headers, body = serve_ranges(env, resource_size: File.size(path_to_large_file)) do |range_in_file, io|
+  File.open(path_to_large_file, "rb") do |file|
+    file.seek(range_in_file.begin)
+    # `io` is an object that responds to `#write` and yields bytes to the Rack-compatible webserver
+    IO.copy_stream(file, io, range_in_file.size)
+  end
+end
+[status, headers, body] # And return the Rack response "triplet"
+```
+
+You can also retrieve the `range_in_file` from an external resource, you can also do it in chunks - whatever you prefer. The important thing is that your response - even for multiple ranges:
+
+* Will be correctly pre-sized with `Content-Length`
+* Will not be generated and buffered eagerly, but will get generated as you serve the content out
+

data/Rakefile

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "standard/rake"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :format do
+  `bundle exec standardrb --fix`
+  `bundle exec magic_frozen_string_literal .`
+end
+
+task :generate_typedefs do
+  `bundle exec sord rbi/serve_byte_range.rbi`
+end
+
+# When building the gem, generate typedefs beforehand,
+# so that they get included
+Rake::Task["build"].enhance(["generate_typedefs"])
+
+task default: [:test, :standard, :generate_typedefs]

data/lib/serve_byte_range/version.rb

@@ -0,0 +1,3 @@
+module ServeByteRange
+  VERSION = "1.0.0"
+end

data/lib/serve_byte_range.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+require "rack"
+
+module ServeByteRange
+  class BlockWritableWithLimit
+    def initialize(limit, &block_that_accepts_writes)
+      @limit = limit
+      @written = 0
+      @block_that_accepts_bytes = block_that_accepts_writes
+    end
+
+    def write(string)
+      return 0 if string.empty?
+      would_have_output = @written + string.bytesize
+      raise "You are trying to write more than advertised - #{would_have_output} bytes, the limit for this range is #{@limit}" if @limit < would_have_output
+      @written += string.bytesize
+      @block_that_accepts_bytes.call(string.b)
+      string.bytesize
+    end
+
+    def verify!
+      raise "You wrote #{@written} bytes but the range requires #{@limit} bytes" unless @written == @limit
+    end
+  end
+
+  class ByteRangeBody
+    def initialize(http_range:, resource_size:, resource_content_type: "binary/octet-stream", &serving_block)
+      @http_range = http_range
+      @resource_size = resource_size
+      @resource_content_type = resource_content_type
+      @serving_block = serving_block
+    end
+
+    def status
+      206
+    end
+
+    def each(&blk)
+      writable_for_range_bytes = BlockWritableWithLimit.new(@http_range.size, &blk)
+      @serving_block.call(@http_range, writable_for_range_bytes)
+      writable_for_range_bytes.verify!
+    end
+
+    def content_length
+      @http_range.size
+    end
+
+    def content_type
+      @resource_content_type
+    end
+
+    def headers
+      {
+        "Accept-Ranges" => "bytes",
+        "Content-Length" => content_length.to_s,
+        "Content-Type" => content_type,
+        "Content-Range" => "bytes %d-%d/%d" % [@http_range.begin, @http_range.end, @resource_size]
+      }
+    end
+  end
+
+  class EmptyBody
+    def status
+      200
+    end
+
+    def content_length
+      0
+    end
+
+    def each(&blk)
+      # write nothing
+    end
+
+    def headers
+      {
+        "Accept-Ranges" => "bytes",
+        "Content-Length" => content_length.to_s
+      }
+    end
+  end
+
+  class NotModifiedBody < EmptyBody
+    def status
+      304
+    end
+  end
+
+  class WholeBody < ByteRangeBody
+    def initialize(resource_size:, **more, &serving_block)
+      super(http_range: Range.new(0, resource_size - 1), resource_size: resource_size, **more, &serving_block)
+    end
+
+    def status
+      200
+    end
+
+    def headers
+      super.tap { |hh| hh.delete("Content-Range") }
+    end
+  end
+
+  class Unsatisfiable < EmptyBody
+    def initialize(resource_size:)
+      @resource_size = resource_size
+    end
+
+    def status
+      416
+    end
+
+    def headers
+      super.tap do |hh|
+        hh["Content-Range"] = "bytes */%s" % @resource_size
+      end
+    end
+  end
+
+  # See https://www.ietf.org/archive/id/draft-ietf-httpbis-p5-range-09.html
+  class MultipartByteRangesBody < ByteRangeBody
+    # @param http_ranges[Array<Range>]
+    def initialize(http_ranges:, boundary:, **params_for_single_range, &serving_block)
+      super(http_range: http_ranges.first, **params_for_single_range)
+      @http_ranges = http_ranges
+      @boundary = boundary
+    end
+
+    def each(&blk)
+      @http_ranges.each_with_index do |range, part_i|
+        yield(part_header(range, part_i))
+        writable_for_range_bytes = BlockWritableWithLimit.new(range.size, &blk)
+        @serving_block.call(range, writable_for_range_bytes)
+        writable_for_range_bytes.verify!
+      end
+      yield(trailer)
+    end
+
+    def content_length
+      # The Content-Length of a multipart response includes the length
+      # of all the ranges of the resource, but also the lengths of the
+      # multipart part headers - which we need to precompute. To do it
+      # we need to run through all of our ranges and output some strings,
+      # and if a lot of ranges are involved this can get expensive. So
+      # memoize the envelope size (it never changes between calls)
+      @envelope_size ||= compute_envelope_size
+    end
+
+    def content_type
+      "multipart/byteranges; boundary=#{@boundary}"
+    end
+
+    def headers
+      super.tap do |hh|
+        hh.delete("Content-Range")
+      end
+    end
+
+    private
+
+    def compute_envelope_size
+      @http_ranges.each_with_index.inject(0) do |size_sum, (http_range, part_index)|
+        # Generate the header for this multipart part ahead of time - we can do this
+        # since we know the boundary and can generate the part headers, without retrieving
+        # the actual bytes of the resource
+        header_bytes = part_header(http_range, part_index)
+        # The amount of output contributed by the part is:
+        # size of the header for the part + bytes of the part itself
+        part_size = header_bytes.bytesize + http_range.size
+        size_sum + part_size
+      end + trailer.bytesize # Account for the trailer as well
+    end
+
+    def trailer
+      "\r\n--%s--\r\n" % @boundary
+    end
+
+    def part_header(http_range, part_index)
+      [
+        (part_index > 0) ? "\r\n" : "", # Parts follwing the first have to be delimited "at the top"
+        "--%s\r\n" % @boundary,
+        "Content-Type: #{@resource_content_type}\r\n",
+        "Content-Range: bytes %d-%d/%d\r\n" % [http_range.begin, http_range.end, @resource_size],
+        "\r\n"
+      ].join
+    end
+  end
+
+  # Strictly - the boundary is supposed to not appear in any of the parts of the multipart response, so _first_
+  # you need to scan the response, pick a byte sequence that does not occur in it, and then use that. In practice,
+  # nobody does that - and a well-behaved HTTP client should honor the Content-Range header when extracting
+  # the byte range from the response. See https://stackoverflow.com/questions/37413715
+  def self.generate_boundary
+    Random.bytes(12).unpack1("H*")
+  end
+
+  # The RFC specifically gives an example of non-canonical, but still
+  # valid request for overlapping ranges:
+  #   > Several legal but not canonical specifications of the second 500
+  #   > bytes (byte offsets 500-999, inclusive):
+  #   >  bytes=500-600,601-999
+  #   >  bytes=500-700,601-999
+  # In such cases, ranges need to be collapsed together. First, to avoid serving
+  # a tiny byte range over and over - causing excessive requests to upstream,
+  # second - to optimize for doing less requests in total.
+  #
+  # @param ranges[Array<Range>] an array of inclusive, limited ranges of integers
+  # @return [Array] ranges squashed together honoring their overlaps
+  def self.coalesce_ranges(ranges)
+    return [] if ranges.empty?
+    # The RFC says https://www.rfc-editor.org/rfc/rfc7233#section-6.1
+    #
+    # > Servers ought to ignore, coalesce, or reject
+    # > egregious range requests, such as requests for more than two
+    # > overlapping ranges or for many small ranges in a single set,
+    # > particularly when the ranges are requested out of order for no
+    # > apparent reason.
+    sorted_ranges = ranges.sort_by(&:begin)
+    first = sorted_ranges.shift
+    coalesced_sorted_ranges = sorted_ranges.each_with_object([first]) do |next_range, acc|
+      prev_range = acc.pop
+      if prev_range.end >= next_range.begin # Range#overlap? can be used on 3.3+
+        new_begin = [prev_range.begin, next_range.begin].min
+        new_end = [prev_range.end, next_range.end].max
+        acc << Range.new(new_begin, new_end)
+      else
+        acc << prev_range << next_range
+      end
+    end
+    # Sort the ranges according to the order the client requested.
+    # The spec says that a client _may_ want to get a certain byte range first,
+    # and it seems a legitimate use case, not ill intent.
+    #
+    # > A client that is requesting multiple ranges SHOULD list those ranges
+    # > in ascending order (the order in which they would typically be
+    # > received in a complete representation) unless there is a specific
+    # > need to request a later part earlier.  For example, a user agent
+    # > processing a large representation with an internal catalog of parts
+    # > might need to request later parts first, particularly if the
+    # > representation consists of pages stored in reverse order and the user
+    # > agent wishes to transfer one page at a time.
+    indices = ranges.map do |r|
+      coalesced_sorted_ranges.find_index { |cr| cr.begin <= r.begin && cr.end >= r.end }
+    end
+    indices.uniq.map { |i| coalesced_sorted_ranges.fetch(i) }
+  end
+
+  # @param env[Hash] the Rack env
+  # @param resource_size[Integer] the size of the complete resource in bytes
+  # @param etag[String] the current ETag of the resource, or nil if none
+  # @param resource_content_type[String] the MIME type string of the resource
+  # @param multipart_boundary[String] The string to use as multipart boundary. Default is an automatically generated pseudo-random string.
+  # @yield [range[Range], io[IO]] The HTTP range being requested and the IO(ish) object to `write()` the bytes into
+  # @example
+  #     status, headers, body = serve_ranges(env, resource_size: file.size) do |range, io|
+  #       file.seek(range.begin)
+  #       IO.copy_stream(file, io, range.size)
+  #     end
+  #     [status, headers, body]
+  # @return [Array] the Rack response triplet of `[status, header_hash, enumerable_body]`
+  def self.serve_ranges(env, resource_size:, etag: nil, resource_content_type: "binary/octet-stream", multipart_boundary: generate_boundary, &range_serving_block)
+    # As per RFC:
+    # If the entity tag given in the If-Range header matches the current cache validator for the entity,
+    # then the server SHOULD provide the specified sub-range of the entity using a 206 (Partial Content)
+    # response. If the cache validator does not match, then the server SHOULD return the entire entity
+    # using a 200 (OK) response.
+    wants_ranges_and_etag_valid = env["HTTP_IF_RANGE"] && env["HTTP_IF_RANGE"] == etag && env["HTTP_RANGE"]
+    wants_ranges_and_no_etag = !env["HTTP_IF_RANGE"] && env["HTTP_RANGE"]
+    wants_no_ranges_and_supplies_etag = env["HTTP_IF_NONE_MATCH"] && !env["HTTP_RANGE"] && !env["HTTP_IF_RANGE"]
+
+    # Very old Rack versions do not have get_byte_ranges and have just byte_ranges
+    http_ranges_from_header = Rack::Utils.respond_to?(:get_byte_ranges) ? Rack::Utils.get_byte_ranges(env["HTTP_RANGE"], resource_size) : Rack::Utils.byte_ranges(env, resource_size)
+    http_ranges_from_header = coalesce_ranges(http_ranges_from_header) if http_ranges_from_header
+
+    body = if wants_no_ranges_and_supplies_etag && env["HTTP_IF_NONE_MATCH"] == etag
+      NotModifiedBody.new
+    elsif resource_size.zero?
+      EmptyBody.new
+    elsif http_ranges_from_header && (wants_ranges_and_no_etag || wants_ranges_and_etag_valid)
+      if http_ranges_from_header.none?
+        Unsatisfiable.new(resource_size: resource_size)
+      elsif http_ranges_from_header.one?
+        ByteRangeBody.new(http_range: http_ranges_from_header.first, resource_size: resource_size, resource_content_type: resource_content_type, &range_serving_block)
+      else
+        MultipartByteRangesBody.new(http_ranges: http_ranges_from_header, resource_size: resource_size, resource_content_type: resource_content_type, boundary: multipart_boundary, &range_serving_block)
+      end
+    else
+      WholeBody.new(resource_size: resource_size, resource_content_type: resource_content_type, &range_serving_block)
+    end
+    headers = body.headers
+
+    etag = etag.inspect if etag && !etag.match?(/^".+"$/)
+    headers["ETag"] = etag if etag
+
+    [body.status, headers, body]
+  end
+end

data/rbi/serve_byte_range.rbi

@@ -0,0 +1,208 @@
+# typed: strong
+module ServeByteRange
+  VERSION = T.let("1.0.0", T.untyped)
+
+  # sord omit - no YARD return type given, using untyped
+  # Strictly - the boundary is supposed to not appear in any of the parts of the multipart response, so _first_
+  # you need to scan the response, pick a byte sequence that does not occur in it, and then use that. In practice,
+  # nobody does that - and a well-behaved HTTP client should honor the Content-Range header when extracting
+  # the byte range from the response. See https://stackoverflow.com/questions/37413715
+  sig { returns(T.untyped) }
+  def self.generate_boundary; end
+
+  # The RFC specifically gives an example of non-canonical, but still
+  # valid request for overlapping ranges:
+  #   > Several legal but not canonical specifications of the second 500
+  #   > bytes (byte offsets 500-999, inclusive):
+  #   >  bytes=500-600,601-999
+  #   >  bytes=500-700,601-999
+  # In such cases, ranges need to be collapsed together. First, to avoid serving
+  # a tiny byte range over and over - causing excessive requests to upstream,
+  # second - to optimize for doing less requests in total.
+  # 
+  # _@param_ `ranges` — an array of inclusive, limited ranges of integers
+  # 
+  # _@return_ — ranges squashed together honoring their overlaps
+  sig { params(ranges: T::Array[T::Range[T.untyped]]).returns(T::Array[T.untyped]) }
+  def self.coalesce_ranges(ranges); end
+
+  # _@param_ `env` — the Rack env
+  # 
+  # _@param_ `resource_size` — the size of the complete resource in bytes
+  # 
+  # _@param_ `etag` — the current ETag of the resource, or nil if none
+  # 
+  # _@param_ `resource_content_type` — the MIME type string of the resource
+  # 
+  # _@param_ `multipart_boundary` — The string to use as multipart boundary. Default is an automatically generated pseudo-random string.
+  # 
+  # _@return_ — the Rack response triplet of `[status, header_hash, enumerable_body]`
+  # 
+  # ```ruby
+  # status, headers, body = serve_ranges(env, resource_size: file.size) do |range, io|
+  #   file.seek(range.begin)
+  #   IO.copy_stream(file, io, range.size)
+  # end
+  # [status, headers, body]
+  # ```
+  sig do
+    params(
+      env: T::Hash[T.untyped, T.untyped],
+      resource_size: Integer,
+      etag: T.nilable(String),
+      resource_content_type: String,
+      multipart_boundary: String,
+      range_serving_block: T.untyped
+    ).returns(T::Array[T.untyped])
+  end
+  def self.serve_ranges(env, resource_size:, etag: nil, resource_content_type: "binary/octet-stream", multipart_boundary: generate_boundary, &range_serving_block); end
+
+  class BlockWritableWithLimit
+    # sord omit - no YARD type given for "limit", using untyped
+    sig { params(limit: T.untyped, block_that_accepts_writes: T.untyped).void }
+    def initialize(limit, &block_that_accepts_writes); end
+
+    # sord omit - no YARD type given for "string", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(string: T.untyped).returns(T.untyped) }
+    def write(string); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def verify!; end
+  end
+
+  class ByteRangeBody
+    # sord omit - no YARD type given for "http_range:", using untyped
+    # sord omit - no YARD type given for "resource_size:", using untyped
+    # sord omit - no YARD type given for "resource_content_type:", using untyped
+    sig do
+      params(
+        http_range: T.untyped,
+        resource_size: T.untyped,
+        resource_content_type: T.untyped,
+        serving_block: T.untyped
+      ).void
+    end
+    def initialize(http_range:, resource_size:, resource_content_type: "binary/octet-stream", &serving_block); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def status; end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { params(blk: T.untyped).returns(T.untyped) }
+    def each(&blk); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def content_length; end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def content_type; end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def headers; end
+  end
+
+  class EmptyBody
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def status; end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def content_length; end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { params(blk: T.untyped).returns(T.untyped) }
+    def each(&blk); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def headers; end
+  end
+
+  class NotModifiedBody < ServeByteRange::EmptyBody
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def status; end
+  end
+
+  class WholeBody < ServeByteRange::ByteRangeBody
+    # sord omit - no YARD type given for "resource_size:", using untyped
+    # sord omit - no YARD type given for "**more", using untyped
+    sig { params(resource_size: T.untyped, more: T.untyped, serving_block: T.untyped).void }
+    def initialize(resource_size:, **more, &serving_block); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def status; end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def headers; end
+  end
+
+  class Unsatisfiable < ServeByteRange::EmptyBody
+    # sord omit - no YARD type given for "resource_size:", using untyped
+    sig { params(resource_size: T.untyped).void }
+    def initialize(resource_size:); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def status; end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def headers; end
+  end
+
+  # See https://www.ietf.org/archive/id/draft-ietf-httpbis-p5-range-09.html
+  class MultipartByteRangesBody < ServeByteRange::ByteRangeBody
+    # sord omit - no YARD type given for "boundary:", using untyped
+    # sord omit - no YARD type given for "**params_for_single_range", using untyped
+    # _@param_ `http_ranges`
+    sig do
+      params(
+        http_ranges: T::Array[T::Range[T.untyped]],
+        boundary: T.untyped,
+        params_for_single_range: T.untyped,
+        serving_block: T.untyped
+      ).void
+    end
+    def initialize(http_ranges:, boundary:, **params_for_single_range, &serving_block); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { params(blk: T.untyped).returns(T.untyped) }
+    def each(&blk); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def content_length; end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def content_type; end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def headers; end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def compute_envelope_size; end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def trailer; end
+
+    # sord omit - no YARD type given for "http_range", using untyped
+    # sord omit - no YARD type given for "part_index", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(http_range: T.untyped, part_index: T.untyped).returns(T.untyped) }
+    def part_header(http_range, part_index); end
+  end
+end

data/serve_byte_range.gemspec

@@ -0,0 +1,31 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "serve_byte_range/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "serve_byte_range"
+  spec.version = ServeByteRange::VERSION
+  spec.authors = ["Julik Tarkhanov", "Sebastian van Hesteren"]
+  spec.email = ["me@julik.nl"]
+  spec.license = "MIT"
+  spec.summary = "Serve byte range HTTP responses lazily"
+  spec.description = "Serve byte range HTTP responses lazily"
+  spec.homepage = "https://github.com/julik/serve_byte_range"
+
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.files = `git ls-files -z`.split("\x0")
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rack", ">= 1.0"
+
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "standard", "1.28.5" # Needed for 2.6
+  spec.add_development_dependency "yard", "~> 0.9"
+  spec.add_development_dependency "sord"
+  spec.add_development_dependency "redcarpet"
+end

data/test/range_server_test.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "bundler"
+Bundler.setup
+
+require_relative "../lib/serve_byte_range"
+require "minitest"
+require "minitest/autorun"
+
+class ServeByteRangeTest < Minitest::Test
+  def test_serves_whole_body
+    rng = Random.new(Minitest.seed)
+    bytes = rng.bytes(474)
+    serve_proc = ->(range, io) {
+      io.write(bytes[range])
+    }
+
+    env = {}
+    status, headers, body = ServeByteRange.serve_ranges(env, resource_size: bytes.bytesize, etag: "AbCehZ", resource_content_type: "x-foo/ba", &serve_proc)
+
+    assert_equal 200, status
+    assert_equal({"Accept-Ranges" => "bytes", "Content-Length" => "474", "Content-Type" => "x-foo/ba", "ETag" => "\"AbCehZ\""}, headers)
+
+    output = StringIO.new.binmode
+    body.each { |chunk| output.write(chunk) }
+    assert_equal bytes, output.string
+  end
+
+  def test_serves_single_range
+    rng = Random.new(Minitest.seed)
+    bytes = rng.bytes(474)
+    serve_proc = ->(range, io) {
+      io.write(bytes[range])
+    }
+
+    env = {"HTTP_RANGE" => "bytes=1-2"}
+    status, headers, body = ServeByteRange.serve_ranges(env, resource_size: bytes.bytesize, etag: "AbCehZ", resource_content_type: "x-foo/ba", &serve_proc)
+
+    assert_equal 206, status
+    assert_equal({"Accept-Ranges" => "bytes", "Content-Length" => "2", "Content-Range" => "bytes 1-2/474", "Content-Type" => "x-foo/ba", "ETag" => "\"AbCehZ\""}, headers)
+
+    output = StringIO.new.binmode
+    body.each { |chunk| output.write(chunk) }
+    assert_equal bytes[1..2], output.string
+
+    env = {"HTTP_RANGE" => "bytes=319-"}
+    status, headers, body = ServeByteRange.serve_ranges(env, resource_size: bytes.bytesize, etag: "AbCehZ", resource_content_type: "x-foo/ba", &serve_proc)
+
+    assert_equal 206, status
+    assert_equal({"Accept-Ranges" => "bytes", "Content-Length" => "155", "Content-Range" => "bytes 319-473/474", "Content-Type" => "x-foo/ba", "ETag" => "\"AbCehZ\""}, headers)
+
+    output = StringIO.new.binmode
+    body.each { |chunk| output.write(chunk) }
+    assert_equal bytes[319..], output.string
+
+    env = {"HTTP_RANGE" => "bytes=0-0"}
+    status, headers, body = ServeByteRange.serve_ranges(env, resource_size: bytes.bytesize, etag: "AbCehZ", resource_content_type: "x-foo/ba", &serve_proc)
+
+    assert_equal 206, status
+    assert_equal({"Accept-Ranges" => "bytes", "Content-Length" => "1", "Content-Range" => "bytes 0-0/474", "Content-Type" => "x-foo/ba", "ETag" => "\"AbCehZ\""}, headers)
+
+    output = StringIO.new.binmode
+    body.each { |chunk| output.write(chunk) }
+    assert_equal bytes[0..0], output.string
+  end
+
+  def test_serves_single_range_of_same_range_supplied_multiple_times_just_once
+    rng = Random.new(Minitest.seed)
+    bytes = rng.bytes(474)
+    serve_proc = ->(range, io) {
+      io.write(bytes[range])
+    }
+
+    env = {"HTTP_RANGE" => "bytes=1-2,1-2,1-2,1-2"}
+    status, headers, body = ServeByteRange.serve_ranges(env, resource_size: bytes.bytesize, etag: "AbCehZ", resource_content_type: "x-foo/ba", &serve_proc)
+
+    assert_equal 206, status
+    assert_equal({"Accept-Ranges" => "bytes", "Content-Length" => "2", "Content-Range" => "bytes 1-2/474", "Content-Type" => "x-foo/ba", "ETag" => "\"AbCehZ\""}, headers)
+
+    output = StringIO.new.binmode
+    body.each { |chunk| output.write(chunk) }
+    assert_equal bytes[1..2], output.string
+  end
+
+  def test_unions_overlapping_ranges
+    rng = Random.new(Minitest.seed)
+    bytes = rng.bytes(474)
+    serve_proc = ->(range, io) {
+      io.write(bytes[range])
+    }
+
+    env = {"HTTP_RANGE" => "bytes=1-2,2-8,4-9"}
+    status, headers, body = ServeByteRange.serve_ranges(env, resource_size: bytes.bytesize, etag: "AbCehZ", resource_content_type: "x-foo/ba", &serve_proc)
+
+    assert_equal 206, status
+    assert_equal({"Accept-Ranges" => "bytes", "Content-Length" => "9", "Content-Range" => "bytes 1-9/474", "Content-Type" => "x-foo/ba", "ETag" => "\"AbCehZ\""}, headers)
+
+    output = StringIO.new.binmode
+    body.each { |chunk| output.write(chunk) }
+    assert_equal bytes[1..9], output.string
+  end
+
+  def test_serves_multiple_ranges
+    rng = Random.new(Minitest.seed)
+    bytes = rng.bytes(474)
+    serve_proc = ->(range, io) {
+      io.write(bytes[range])
+    }
+
+    env = {"HTTP_RANGE" => "bytes=1-2,4-9,472-"}
+    status, headers, body = ServeByteRange.serve_ranges(env, resource_size: bytes.bytesize, etag: "AbCehZ", multipart_boundary: "azuleju", resource_content_type: "x-foo/bar", &serve_proc)
+
+    assert_equal 206, status
+    assert_equal({"Accept-Ranges" => "bytes", "Content-Length" => "237", "Content-Type" => "multipart/byteranges; boundary=azuleju", "ETag" => "\"AbCehZ\""}, headers)
+
+    reference_lines = [
+      "--azuleju",
+      "Content-Type: x-foo/bar",
+      "Content-Range: bytes 1-2/474",
+      "",
+      bytes[1..2],
+      "--azuleju",
+      "Content-Type: x-foo/bar",
+      "Content-Range: bytes 4-9/474",
+      "",
+      bytes[4..9],
+      "--azuleju",
+      "Content-Type: x-foo/bar",
+      "Content-Range: bytes 472-473/474",
+      "",
+      bytes[472..473],
+      "--azuleju--"
+    ]
+
+    output = StringIO.new.binmode
+    body.each { |chunk| output.write(chunk) }
+    lines = output.string.split("\r\n")
+
+    assert_equal reference_lines, lines
+  end
+
+  def test_serves_not_modified_with_just_an_if_none_match
+    rng = Random.new(Minitest.seed)
+    bytes = rng.bytes(474)
+    serve_proc = ->(range, io) {
+      io.write(bytes[range])
+    }
+
+    env = {"HTTP_IF_NONE_MATCH" => "\"woof\""}
+    status, headers, _ = ServeByteRange.serve_ranges(env, resource_size: bytes.bytesize, etag: "\"woof\"", resource_content_type: "x-foo/bar", &serve_proc)
+
+    assert_equal 304, status
+    assert_equal({"Accept-Ranges" => "bytes", "Content-Length" => "0", "ETag" => "\"woof\""}, headers)
+  end
+
+  def test_serves_entire_document_on_if_range_header_mismatch
+    rng = Random.new(Minitest.seed)
+    bytes = rng.bytes(474)
+    serve_proc = ->(range, io) {
+      io.write(bytes[range])
+    }
+
+    env = {"HTTP_RANGE" => "bytes=1-2,4-9,472-", "HTTP_IF_RANGE" => "\"v2\""}
+    status, headers, _ = ServeByteRange.serve_ranges(env, resource_size: bytes.bytesize, etag: "\"v3\"", multipart_boundary: "azuleju", resource_content_type: "x-foo/bar", &serve_proc)
+
+    assert_equal 200, status
+    assert_equal({"Accept-Ranges" => "bytes", "Content-Length" => "474", "Content-Type" => "x-foo/bar", "ETag" => "\"v3\""}, headers)
+  end
+
+  def test_generates_boundary_for_multiple_ranges
+    rng = Random.new(Minitest.seed)
+    bytes = rng.bytes(474)
+    serve_proc = ->(range, io) {
+      io.write(bytes[range])
+    }
+
+    env = {"HTTP_RANGE" => "bytes=1-2,4-9,472-"}
+    status, headers, _ = ServeByteRange.serve_ranges(env, resource_size: bytes.bytesize, etag: "AbCehZ", &serve_proc)
+
+    assert_equal 206, status
+    assert_equal "335", headers["Content-Length"]
+    assert headers["Content-Type"].start_with?("multipart/byteranges; boundary=")
+  end
+
+  def test_refuses_invalid_range
+    rng = Random.new(Minitest.seed)
+    bytes = rng.bytes(474)
+    serve_proc = ->(range, io) {
+      io.write(bytes[range])
+    }
+
+    env = {"HTTP_RANGE" => "bytes=474-"}
+    status, headers, body = ServeByteRange.serve_ranges(env, resource_size: bytes.bytesize, etag: "AbCehZ", multipart_boundary: "azuleju", resource_content_type: "x-foo/bar", &serve_proc)
+
+    assert_equal 416, status
+    assert_equal({"Accept-Ranges" => "bytes", "Content-Length" => "0", "ETag" => "\"AbCehZ\"", "Content-Range" => "bytes */474"}, headers)
+
+    body.each { |chunk| raise "Should never be called" }
+  end
+
+  def test_coalesce_ranges
+    assert_equal [], ServeByteRange.coalesce_ranges([])
+
+    ranges = [1..1]
+    assert_equal [1..1], ServeByteRange.coalesce_ranges(ranges)
+
+    ranges = [0..0, 0..0, 145..900, 1..12, 3..78, 0..8].shuffle(random: Random.new(Minitest.seed))
+    assert_equal [0..78, 145..900], ServeByteRange.coalesce_ranges(ranges).sort_by(&:begin)
+
+    ordered_ranges = [14..32, 0..0, 145..900, 5..16, 4..4]
+    # Ordering should be maintained (roughly) in the coalesced ranges
+    assert_equal [5..32, 0..0, 145..900, 4..4], ServeByteRange.coalesce_ranges(ordered_ranges)
+  end
+end

metadata

@@ -0,0 +1,154 @@
+--- !ruby/object:Gem::Specification
+name: serve_byte_range
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Julik Tarkhanov
+- Sebastian van Hesteren
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-03-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.28.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.28.5
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: sord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Serve byte range HTTP responses lazily
+email:
+- me@julik.nl
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".standard.yml"
+- Gemfile
+- README.md
+- Rakefile
+- lib/serve_byte_range.rb
+- lib/serve_byte_range/version.rb
+- rbi/serve_byte_range.rbi
+- serve_byte_range.gemspec
+- test/range_server_test.rb
+homepage: https://github.com/julik/serve_byte_range
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: Serve byte range HTTP responses lazily
+test_files: []