interval_response 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 627cc1b428d5adbde188c9718a9fabeacf4d852126500439ec672f1caea8b88f
-  data.tar.gz: e42cae558b987ef86bc9bb351a3e5196bf68af9bfa2f0918a6f16d8fbbb52036
+  metadata.gz: 05cde032dcb1552e0814acf6904f300a840a9bca04399d932c4860f985adea1f
+  data.tar.gz: 8f04da33316e49efd6d15145ab19adec358f7035f7d5e07721b216e1f7ec9796
 SHA512:
-  metadata.gz: 991b923a00ccb2b510e45044cf578c19e38a6ce65669188c91c16b736dfee0aba1352126d5552e114acc6a30d8ecc322d478c1af3091e3b7761d395cd521d5ec
-  data.tar.gz: e229ea7a13015012c7ecf8125b0f401e8b24b236de19a5a65b9c67afac6121966c269d31062a1a84a713e5caa25485e30eaf9e7c73a6bf3e452c2dd25ea4f67c
+  metadata.gz: c74910d5332103d7240e28f848d092d70299178735a9ba38dcd5e307e5d11859890201bc0ba6072b0c94fe96885994fb9195d4b83a90316b10986dfd29d69ebf
+  data.tar.gz: 6835c6fc24fe5874de7b7b5e653b75b41cf2ef3c78d7909fb4194bee6dd764baf4bb7e4634ef7fc5ccdf7c720bc292152ac6b9d046d36bdb65140ccbede9e391

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 0.1.7
+
+* Move `RackResponseWrapper` into the main namespace
+* Add `#satisfied_with_first_interval?` so that certain Range: requests can be served using a redirect
+* Add `#multiple_ranges?` so that one can choose not to honor multipart Range requests
+
+# 0.1.6
+
+* Create a base response type (`Abstract`) which has the same interface as the rest of the responses
+
 # 0.1.5
 
 * Change the API of `IntervalResponse.new` to accept the Rack `env` hash directly, without having the caller extract the header values manually.

data/lib/interval_response.rb

@@ -5,6 +5,7 @@ module IntervalResponse
   class Error < StandardError; end
 
   require_relative "interval_response/version"
+  require_relative "interval_response/rack_body_wrapper"
   require_relative "interval_response/sequence"
   require_relative "interval_response/abstract"
   require_relative "interval_response/empty"

data/lib/interval_response/abstract.rb

@@ -1,70 +1,32 @@
 # Base class for all response types, primarily for ease of documentation
 class IntervalResponse::Abstract
-  # The Rack body wrapper is intended to return as the third element
-  # of the Rack response triplet. It supports the #each method
-  # and will call to the IntervalResponse object given to it
-  # at instantiation, filling up a pre-allocated String object
-  # with the bytes to be served out.
-  class RackBodyWrapper
-    # Default size of the chunk (String buffer) which is going to be
-    # yielded to the caller of the `each` method.
-    # Set toroughly one TCP kernel buffer
-    CHUNK_SIZE = 65 * 1024
-
-    def initialize(with_interval_response, chunk_size:)
-      @chunk_size = chunk_size
-      @interval_response = with_interval_response
-    end
-
-    def each
-      buf = String.new(capacity: @chunk_size)
-      @interval_response.each do |segment, range_in_segment|
-        case segment
-        when IntervalResponse::LazyFile
-          segment.with do |file_handle|
-            with_each_chunk(range_in_segment) do |offset, read_n|
-              file_handle.seek(offset, IO::SEEK_SET)
-              yield file_handle.read(read_n, buf)
-            end
-          end
-        when String
-          with_each_chunk(range_in_segment) do |offset, read_n|
-            yield segment.slice(offset, read_n)
-          end
-        when IO, Tempfile
-          with_each_chunk(range_in_segment) do |offset, read_n|
-            segment.seek(offset, IO::SEEK_SET)
-            yield segment.read(read_n, buf)
-          end
-        else
-          raise TypeError, "RackBodyWrapper only supports IOs or Strings"
-        end
-      end
-    ensure
-      buf.clear
-    end
-
-    private
-
-    def with_each_chunk(range_in_segment)
-      range_size = range_in_segment.end - range_in_segment.begin + 1
-      start_at_offset = range_in_segment.begin
-      n_whole_segments, remainder = range_size.divmod(@chunk_size)
-
-      n_whole_segments.times do |n|
-        unit_offset = start_at_offset + (n * @chunk_size)
-        yield unit_offset, @chunk_size
-      end
+  def to_rack_response_triplet(headers: nil, chunk_size: IntervalResponse::RackBodyWrapper::CHUNK_SIZE)
+    [status_code, headers.to_h.merge(self.headers), IntervalResponse::RackBodyWrapper.new(self, chunk_size: chunk_size)]
+  end
 
-      if remainder > 0
-        unit_offset = start_at_offset + (n_whole_segments * @chunk_size)
-        yield unit_offset, remainder
-      end
-    end
+  # Tells whether this response is responding with multiple ranges. If you want to simulate S3 for example,
+  # it might be relevant to deny a response from being served if it does respond with multiple ranges -
+  # IntervalResponse supports these responses just fine, but S3 doesn't.
+  def multiple_ranges?
+    false
   end
 
-  def to_rack_response_triplet(headers: nil, chunk_size: RackBodyWrapper::CHUNK_SIZE)
-    [status_code, headers.to_h.merge(self.headers), RackBodyWrapper.new(self, chunk_size: chunk_size)]
+  # Tells whether this entire requested range can be satisfied with the first available segment within the given Sequence.
+  # If it is, then you can redirect to the URL of the first segment instead of streaming the response
+  # through - which can be cheaper for your application server. Note that you can redirect to the resource of the first
+  # interval only, because otherwise your `Range` header will no longer match. Suppose you have a stitched resource
+  # consisting of two segments:
+  #
+  #   [bytes 0..456]
+  #   [bytes 457..890]
+  #
+  # and your client requests `Range: bytes=0-33`. You can redirect the client to the location of the first interval,
+  # and the `Range:` header will be retransmitted to that location and will be satisfied. However, imagine you are requesting
+  # the `Range: bytes=510-512` - you _could_ redirect just to the second interval, but the `Range` header is not going to be
+  # adjusted by the client, and you are not going to receive the correct slice of the resource. That's why you can only
+  # redirect to the first interval only.
+  def satisfied_with_first_interval?
+    false
   end
 
   # @param interval_sequence[IntervalResponse::Sequence] the sequence the response is built for

data/lib/interval_response/full.rb

@@ -1,9 +1,12 @@
 # Serves out a response that contains the entire resource
 class IntervalResponse::Full < IntervalResponse::Abstract
+  def initialize(*)
+    super
+    @http_range_for_entire_resource = 0..(@interval_sequence.size - 1)
+  end
+
   def each
-    # serve the part of the interval map
-    full_range = 0..(@interval_sequence.size - 1)
-    @interval_sequence.each_in_range(full_range) do |segment, range_in_segment|
+    @interval_sequence.each_in_range(@http_range_for_entire_resource) do |segment, range_in_segment|
       yield(segment, range_in_segment)
     end
   end
@@ -16,6 +19,14 @@ class IntervalResponse::Full < IntervalResponse::Abstract
     @interval_sequence.size
   end
 
+  def satisfied_with_first_interval?
+    @interval_sequence.first_interval_only?(@http_range_for_entire_resource)
+  end
+
+  def multiple_ranges?
+    false
+  end
+
   def headers
     {
       'Accept-Ranges' => 'bytes',

data/lib/interval_response/multi.rb

@@ -47,6 +47,14 @@ class IntervalResponse::Multi < IntervalResponse::Abstract
     }
   end
 
+  def satisfied_with_first_interval?
+    @interval_sequence.first_interval_only?(*@http_ranges)
+  end
+
+  def multiple_ranges?
+    true
+  end
+
   private
 
   def compute_envelope_size

data/lib/interval_response/rack_body_wrapper.rb

@@ -0,0 +1,65 @@
+# The Rack body wrapper is intended to be returned as the third element
+# of the Rack response triplet. It supports the #each method
+# and will call to the IntervalResponse object given to it
+# at instantiation, filling up a pre-allocated String object
+# with the bytes to be served out. The String object will then be repeatedly
+# yielded to the Rack webserver with the response data. Since Ruby strings
+# are mutable, the String object will be sized to a certain capacity and reused
+# across calls to save allocations.
+class IntervalResponse::RackBodyWrapper
+  # Default size of the chunk (String buffer) which is going to be
+  # yielded to the caller of the `each` method.
+  # Set toroughly one TCP kernel buffer
+  CHUNK_SIZE = 65 * 1024
+
+  def initialize(with_interval_response, chunk_size:)
+    @chunk_size = chunk_size
+    @interval_response = with_interval_response
+  end
+
+  def each
+    buf = String.new(capacity: @chunk_size)
+    @interval_response.each do |segment, range_in_segment|
+      case segment
+      when IntervalResponse::LazyFile
+        segment.with do |file_handle|
+          with_each_chunk(range_in_segment) do |offset, read_n|
+            file_handle.seek(offset, IO::SEEK_SET)
+            yield file_handle.read(read_n, buf)
+          end
+        end
+      when String
+        with_each_chunk(range_in_segment) do |offset, read_n|
+          yield segment.slice(offset, read_n)
+        end
+      when IO, Tempfile
+        with_each_chunk(range_in_segment) do |offset, read_n|
+          segment.seek(offset, IO::SEEK_SET)
+          yield segment.read(read_n, buf)
+        end
+      else
+        raise TypeError, "RackBodyWrapper only supports IOs or Strings"
+      end
+    end
+  ensure
+    buf.clear
+  end
+
+  private
+
+  def with_each_chunk(range_in_segment)
+    range_size = range_in_segment.end - range_in_segment.begin + 1
+    start_at_offset = range_in_segment.begin
+    n_whole_segments, remainder = range_size.divmod(@chunk_size)
+
+    n_whole_segments.times do |n|
+      unit_offset = start_at_offset + (n * @chunk_size)
+      yield unit_offset, @chunk_size
+    end
+
+    if remainder > 0
+      unit_offset = start_at_offset + (n_whole_segments * @chunk_size)
+      yield unit_offset, remainder
+    end
+  end
+end

data/lib/interval_response/sequence.rb

@@ -42,6 +42,8 @@ class IntervalResponse::Sequence
   def add_segment(segment, size:, etag: size)
     if size > 0
       etag_quoted = '"%s"' % etag
+      # We save the index of the interval inside the Struct so that we can
+      # use `bsearch` later instead of requiring `bsearch_index` to be available
       @intervals << Interval.new(segment, size, @size, @intervals.length, etag_quoted)
       @size += size
     end
@@ -58,31 +60,38 @@ class IntervalResponse::Sequence
   # need to retrieve data from the inner Sequence which is one of the segments, the call will
   # yield the segments from the inner Sequence, "drilling down" as deep as is appropriate.
   #
+  # Three arguments will be yielded to the block - the segment (the "meat" of an interval, which
+  # is the object given when the interval was added to the Sequence), the range within the interval
+  # (which is always going to be an inclusive `Range` of integers) and a boolean flag indicating whether
+  # this interval is the very first interval in the requested subset of the sequence. This flag honors nesting
+  # (if you have arbitrarily nested interval Sequences and you request something from the first interval of
+  # several Sequences deep it will still indicate `true`).
+  #
   # @param from_range_in_resource[Range] an inclusive Range that specifies the range within the segment map
-  # @yield segment[Object], range_in_segment[Range]
+  # @yield segment[Object], range_in_segment[Range], is_first_interval[Boolean]
   def each_in_range(from_range_in_resource)
     # Skip empty ranges
     requested_range_size = (from_range_in_resource.end - from_range_in_resource.begin) + 1
     return if requested_range_size < 1
 
-    # ...and if the range misses our intervals completely
+    # Then walk through included intervals. If the range misses
+    # our intervals completely included_intervals will be empty.
     included_intervals = intervals_within_range(from_range_in_resource)
-
-    # And normal case - walk through included intervals
     included_intervals.each do |interval|
       int_start = interval.offset
       int_end = interval.offset + interval.size - 1
       req_start = from_range_in_resource.begin
       req_end = from_range_in_resource.end
       range_within_interval = (max(int_start, req_start) - int_start)..(min(int_end, req_end) - int_start)
+      is_first_interval = interval.position == 0
 
       # Allow Sequences to be composed together
       if interval.segment.respond_to?(:each_in_range)
-        interval.segment.each_in_range(range_within_interval) do |sub_segment, sub_range|
-          yield(sub_segment, sub_range)
+        interval.segment.each_in_range(range_within_interval) do |sub_segment, sub_range, is_first_nested_interval|
+          yield(sub_segment, sub_range, is_first_interval && is_first_nested_interval)
         end
       else
-        yield(interval.segment, range_within_interval)
+        yield(interval.segment, range_within_interval, is_first_interval)
       end
     end
   end
@@ -132,6 +141,19 @@ class IntervalResponse::Sequence
     '"%s"' % d.hexdigest
   end
 
+  # Tells whether all of the given `ranges` will be satisfied from the first interval only. This can be used to
+  # redirect to the resource at that interval instead of proxying it through, since the `Range` header won't need to
+  # be adjusted
+  def first_interval_only?(*ranges)
+    ranges.map do |range|
+      each_in_range(range) do |_, _, is_first_interval|
+        return false unless is_first_interval
+      end
+    end
+
+    true
+  end
+
   private
 
   def max(a, b)
@@ -143,6 +165,10 @@ class IntervalResponse::Sequence
   end
 
   def interval_under(offset)
+    # For our purposes we would be better served by `bsearch_index`, but it is not available
+    # on older Ruby versions which we otherwise can splendidly support. Since when we retrieve
+    # the interval under offset we are going to need the index anyway, and since calling `Array#index`
+    # will incur another linear scan of the array, we save the index of the interval with the interval itself.
     @intervals.bsearch do |interval|
       # bsearch expects a 0 return value for "exact match".
       # -1 tells it "look to my left" and 1 "look to my right",

data/lib/interval_response/single.rb

@@ -32,4 +32,8 @@ class IntervalResponse::Single < IntervalResponse::Abstract
       'ETag' => etag,
     }
   end
+
+  def satisfied_with_first_interval?
+    @interval_sequence.first_interval_only?(@http_range)
+  end
 end

data/lib/interval_response/version.rb

@@ -1,3 +1,3 @@
 module IntervalResponse
-  VERSION = "0.1.6"
+  VERSION = "0.1.7"
 end

data/spec/interval_response/sequence_spec.rb

@@ -17,19 +17,35 @@ RSpec.describe IntervalResponse::Sequence do
       expect(seq.size).to eq(6 + 12 + 17)
       expect { |b|
         seq.each_in_range(0..0, &b)
-      }.to yield_with_args(a, 0..0)
+      }.to yield_with_args(a, 0..0, true)
 
       expect { |b|
         seq.each_in_range(0..7, &b)
-      }.to yield_successive_args([a, 0..5], [b, 0..1])
+      }.to yield_successive_args([a, 0..5, true], [b, 0..1, false])
 
       expect { |b|
         seq.each_in_range(7..27, &b)
-      }.to yield_successive_args([b, 1..11], [c, 0..9])
+      }.to yield_successive_args([b, 1..11, false], [c, 0..9, false])
 
       expect { |b|
         seq.each_in_range(0..(6 + 12 - 1), &b)
-      }.to yield_successive_args([a, 0..5], [b, 0..11])
+      }.to yield_successive_args([a, 0..5, true], [b, 0..11, false])
+    end
+
+    it 'indicates whether the first interval will satisfy a set of Ranges' do
+      seq = described_class.new
+
+      a = double(:a, size: 6)
+      b = double(:b, size: 12)
+      c = double(:c, size: 17)
+      seq << a << b << c
+
+      expect(seq).to be_first_interval_only(0..0)
+      expect(seq).to be_first_interval_only(0..0, 0..5)
+      expect(seq).not_to be_first_interval_only(0..6)
+      expect(seq).not_to be_first_interval_only(3..8)
+      expect(seq).not_to be_first_interval_only(15..16)
+      expect(seq).not_to be_first_interval_only(0..0, 15..16)
     end
 
     it 'generates the ETag for an empty sequence, and the etag contains data' do
@@ -91,7 +107,7 @@ RSpec.describe IntervalResponse::Sequence do
       seq = described_class.new(a, b, c)
       expect { |b|
         seq.each_in_range(0..27, &b)
-      }.to yield_successive_args([a, 0..2], [b, 0..3], [c, 0..0])
+      }.to yield_successive_args([a, 0..2, true], [b, 0..3, false], [c, 0..0, false])
     end
 
     it 'is composable' do
@@ -103,7 +119,7 @@ RSpec.describe IntervalResponse::Sequence do
 
       expect { |b|
         seq.each_in_range(0..27, &b)
-      }.to yield_successive_args([a, 0..2], [b, 0..3], [c, 0..0])
+      }.to yield_successive_args([a, 0..2, true], [b, 0..3, false], [c, 0..0, false])
     end
 
     it 'has close to linear performance with large number of ranges and intervals' do

data/spec/interval_response_spec.rb

@@ -56,6 +56,9 @@ RSpec.describe IntervalResponse do
         'ETag' => seq.etag,
       )
       expect(response.etag).to eq(seq.etag)
+      expect(response).not_to be_multiple_ranges
+      expect(response).not_to be_satisfied_with_first_interval
+
       expect { |b|
         response.each(&b)
       }.to yield_successive_args([segment_a, 0..2], [segment_b, 0..3], [segment_c, 0..0])
@@ -72,6 +75,8 @@ RSpec.describe IntervalResponse do
         'ETag' => seq.etag
       )
       expect(response.etag).to eq(seq.etag)
+      expect(response).not_to be_multiple_ranges
+      expect(response).not_to be_satisfied_with_first_interval
     end
 
     it 'returns a single HTTP range if the client asked for it and it can be satisfied' do
@@ -86,11 +91,34 @@ RSpec.describe IntervalResponse do
         'ETag' => seq.etag,
       )
       expect(response.etag).to eq(seq.etag)
+      expect(response).not_to be_multiple_ranges
+      expect(response).not_to be_satisfied_with_first_interval
+
       expect { |b|
         response.each(&b)
       }.to yield_successive_args([segment_a, 2..2], [segment_b, 0..1])
     end
 
+    it 'returns a single HTTP range if the client asked for it and hints it can be satisfied from the first interval' do
+      response = IntervalResponse.new(seq, "HTTP_RANGE" => "bytes=0-0")
+      expect(response.status_code).to eq(206)
+      expect(response.content_length).to eq(1)
+      expect(response.headers).to eq(
+        "Accept-Ranges" => "bytes",
+        "Content-Length" => "1",
+        "Content-Range" => "bytes 0-0/8",
+        "Content-Type" => "binary/octet-stream",
+        'ETag' => seq.etag,
+      )
+      expect(response.etag).to eq(seq.etag)
+      expect(response).not_to be_multiple_ranges
+      expect(response).to be_satisfied_with_first_interval
+
+      expect { |b|
+        response.each(&b)
+      }.to yield_successive_args([segment_a, 0..0])
+    end
+
     it 'returns a single HTTP range if the client asked for it and it can be satisfied, ETag matches' do
       response = IntervalResponse.new(seq, "HTTP_RANGE" => "bytes=2-4", "HTTP_IF_RANGE" => seq.etag)
       expect(response.status_code).to eq(206)
@@ -108,7 +136,7 @@ RSpec.describe IntervalResponse do
       }.to yield_successive_args([segment_a, 2..2], [segment_b, 0..1])
     end
 
-    it 'responss with the entier resource if the Range is satisfiable but the If-Range specifies a different ETag than the sequence' do
+    it 'responds with the entire resource if the Range is satisfiable but the If-Range specifies a different ETag than the sequence' do
       response = IntervalResponse.new(seq, "HTTP_RANGE" => "bytes=12901-", "HTTP_IF_RANGE" => '"different"')
       expect(response.status_code).to eq(200)
       expect(response.content_length).to eq(8)
@@ -119,6 +147,8 @@ RSpec.describe IntervalResponse do
         'ETag' => seq.etag,
       )
       expect(response.etag).to eq(seq.etag)
+      expect(response).not_to be_multiple_ranges
+      expect(response).not_to be_satisfied_with_first_interval
     end
 
     it 'responds with the range that can be satisfied if asked for 2, of which one is unsatisfiable' do
@@ -133,6 +163,8 @@ RSpec.describe IntervalResponse do
         'ETag' => seq.etag,
       )
       expect(response.etag).to eq(seq.etag)
+      expect(response).not_to be_multiple_ranges
+      expect(response).not_to be_satisfied_with_first_interval
 
       expect { |b|
         response.each(&b)
@@ -152,6 +184,8 @@ RSpec.describe IntervalResponse do
         'ETag' => seq.etag,
       )
       expect(response.etag).to eq(seq.etag)
+      expect(response).to be_multiple_ranges
+      expect(response).to be_satisfied_with_first_interval
 
       output = StringIO.new
       response.each do |segment, range|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: interval_response
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - Julik Tarkhanov
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-11-27 00:00:00.000000000 Z
+date: 2021-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -148,6 +148,7 @@ files:
 - lib/interval_response/invalid.rb
 - lib/interval_response/lazy_file.rb
 - lib/interval_response/multi.rb
+- lib/interval_response/rack_body_wrapper.rb
 - lib/interval_response/sequence.rb
 - lib/interval_response/single.rb
 - lib/interval_response/version.rb
@@ -162,7 +163,7 @@ metadata:
   homepage_uri: https://github.com/WeTransfer/interval_response
   source_code_uri: https://github.com/WeTransfer/interval_response
   changelog_uri: https://github.com/WeTransfer/interval_response
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -178,7 +179,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.0.3
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Assemble HTTP responses from spliced sequences of payloads
 test_files: []