serve_byte_range 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.github/workflows/ci.yml +31 -7
- data/.gitignore +3 -2
- data/.standard.yml +4 -0
- data/README.md +58 -0
- data/Rakefile +19 -6
- data/Steepfile +10 -0
- data/gemfiles/rack_2.gemfile +5 -0
- data/gemfiles/rack_3.gemfile +5 -0
- data/gemfiles/typecheck.gemfile +7 -0
- data/lib/serve_byte_range/sequence.rb +152 -0
- data/lib/serve_byte_range/version.rb +5 -1
- data/lib/serve_byte_range.rb +222 -43
- data/serve_byte_range.gemspec +9 -4
- data/sig/serve_byte_range/sequence.rbs +91 -0
- data/sig/serve_byte_range/version.rbs +5 -0
- data/sig/serve_byte_range.rbs +256 -0
- data/sig_shims/rack.rbs +9 -0
- data/test/byte_comparator_test.rb +46 -0
- data/test/range_server_test.rb +123 -6
- data/test/sequence_test.rb +224 -0
- data/test/support/byte_comparator.rb +47 -0
- data/test/support/bytes_assertions.rb +10 -0
- metadata +36 -48
- data/rbi/serve_byte_range.rbi +0 -208
data/lib/serve_byte_range.rb
CHANGED
|
@@ -1,30 +1,102 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
+
# rbs_inline: enabled
|
|
4
|
+
|
|
3
5
|
require "rack"
|
|
6
|
+
require_relative "serve_byte_range/sequence"
|
|
4
7
|
|
|
8
|
+
# Serves HTTP `Range` requests lazily - see ServeByteRange.serve_ranges and ServeByteRange.serve_sequence
|
|
5
9
|
module ServeByteRange
|
|
10
|
+
# @rbs!
|
|
11
|
+
# type serving_block = ^(Range[Integer] range, BlockWritableWithLimit io) -> void
|
|
12
|
+
# type rack_response = [Integer, Hash[String, String], ByteRangeBody | EmptyBody]
|
|
13
|
+
|
|
14
|
+
# The IO-ish object the serving blocks write into. Passes the bytes on and makes sure the
|
|
15
|
+
# amount of bytes written matches what was advertised in `Content-Length`
|
|
6
16
|
class BlockWritableWithLimit
|
|
7
|
-
|
|
17
|
+
COPY_ON_WRITE_SAFE_WITH_COPY_STREAM = Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.2") #: bool
|
|
18
|
+
private_constant :COPY_ON_WRITE_SAFE_WITH_COPY_STREAM
|
|
19
|
+
|
|
20
|
+
# @rbs @limit: Integer
|
|
21
|
+
# @rbs @label: String | ^() -> String
|
|
22
|
+
# @rbs @written: Integer
|
|
23
|
+
# @rbs @block_that_accepts_bytes: ^(String) -> void
|
|
24
|
+
|
|
25
|
+
# Yields a writable which passes the bytes on to `sink`, and makes sure exactly `limit` bytes got written.
|
|
26
|
+
# The `label` can be a callable returning the String, so that it only gets built when there is an error.
|
|
27
|
+
#
|
|
28
|
+
# @rbs limit: Integer -- how many bytes have to be written
|
|
29
|
+
# @rbs sink: ^(String) -> void -- receives the written bytes
|
|
30
|
+
# @rbs label: String | ^() -> String -- what is being written, for the error messages
|
|
31
|
+
# @rbs &block: (BlockWritableWithLimit io) -> void
|
|
32
|
+
# @rbs return: void
|
|
33
|
+
def self.write_exactly(limit, sink, label: "range")
|
|
34
|
+
writable = new(limit, label: label, &sink)
|
|
35
|
+
yield(writable)
|
|
36
|
+
writable.verify!
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
# @rbs limit: Integer
|
|
40
|
+
# @rbs label: String | ^() -> String
|
|
41
|
+
# @rbs &block_that_accepts_writes: (String) -> void
|
|
42
|
+
def initialize(limit, label: "range", &block_that_accepts_writes)
|
|
8
43
|
@limit = limit
|
|
44
|
+
@label = label
|
|
9
45
|
@written = 0
|
|
10
46
|
@block_that_accepts_bytes = block_that_accepts_writes
|
|
11
47
|
end
|
|
12
48
|
|
|
49
|
+
# @rbs string: String
|
|
50
|
+
# @rbs return: Integer
|
|
13
51
|
def write(string)
|
|
14
52
|
return 0 if string.empty?
|
|
15
53
|
would_have_output = @written + string.bytesize
|
|
16
|
-
raise "You are trying to write more than advertised - #{would_have_output} bytes, the limit for this
|
|
54
|
+
raise "You are trying to write more than advertised - #{would_have_output} bytes, the limit for this #{label} is #{@limit}" if @limit < would_have_output
|
|
17
55
|
@written += string.bytesize
|
|
18
|
-
|
|
56
|
+
# Only a frozen string can be passed on without copying. IO.copy_stream reuses one buffer for all
|
|
57
|
+
# of its writes, and Rack::ETag and friends hold on to the chunks they get
|
|
58
|
+
binary_string = (string.frozen? && string.encoding == Encoding::BINARY) ? string : binary_copy(string)
|
|
59
|
+
@block_that_accepts_bytes.call(binary_string)
|
|
19
60
|
string.bytesize
|
|
20
61
|
end
|
|
21
62
|
|
|
63
|
+
# @rbs return: void
|
|
22
64
|
def verify!
|
|
23
|
-
raise "You wrote #{@written} bytes but the
|
|
65
|
+
raise "You wrote #{@written} bytes but the #{label} requires #{@limit} bytes" unless @written == @limit
|
|
66
|
+
end
|
|
67
|
+
|
|
68
|
+
private
|
|
69
|
+
|
|
70
|
+
# `b` and `dup` do not copy the bytes, they share the memory with the original until either gets
|
|
71
|
+
# modified. IO.copy_stream on Ruby 2.7 to 3.1 reads into its buffer without breaking that sharing,
|
|
72
|
+
# so our "copy" got overwritten while the webserver still held on to it. There we have to copy
|
|
73
|
+
# the bytes for real by appending, which may eat memory: every chunk gets duplicated, and so does a
|
|
74
|
+
# huge string written in one go (100MB of `body.read` briefly takes 200MB). Starting with 3.2
|
|
75
|
+
# IO.copy_stream un-shares its buffer before reading into it, so the cheap `b` is safe.
|
|
76
|
+
# @rbs string: String
|
|
77
|
+
# @rbs return: String
|
|
78
|
+
def binary_copy(string)
|
|
79
|
+
return string.b if COPY_ON_WRITE_SAFE_WITH_COPY_STREAM
|
|
80
|
+
(String.new(capacity: string.bytesize, encoding: Encoding::BINARY) << string).force_encoding(Encoding::BINARY)
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
# @rbs return: String
|
|
84
|
+
def label
|
|
85
|
+
lbl = @label
|
|
86
|
+
lbl.is_a?(String) ? lbl : lbl.call
|
|
24
87
|
end
|
|
25
88
|
end
|
|
26
89
|
|
|
27
90
|
class ByteRangeBody
|
|
91
|
+
# @rbs @http_range: Range[Integer]
|
|
92
|
+
# @rbs @resource_size: Integer
|
|
93
|
+
# @rbs @resource_content_type: String
|
|
94
|
+
# @rbs @serving_block: serving_block
|
|
95
|
+
|
|
96
|
+
# @rbs http_range: Range[Integer]
|
|
97
|
+
# @rbs resource_size: Integer
|
|
98
|
+
# @rbs resource_content_type: String
|
|
99
|
+
# @rbs &serving_block: (Range[Integer] range, BlockWritableWithLimit io) -> void
|
|
28
100
|
def initialize(http_range:, resource_size:, resource_content_type: "binary/octet-stream", &serving_block)
|
|
29
101
|
@http_range = http_range
|
|
30
102
|
@resource_size = resource_size
|
|
@@ -32,24 +104,29 @@ module ServeByteRange
|
|
|
32
104
|
@serving_block = serving_block
|
|
33
105
|
end
|
|
34
106
|
|
|
107
|
+
# @rbs return: Integer
|
|
35
108
|
def status
|
|
36
109
|
206
|
|
37
110
|
end
|
|
38
111
|
|
|
112
|
+
# @rbs &blk: (String) -> void
|
|
113
|
+
# @rbs return: void
|
|
39
114
|
def each(&blk)
|
|
40
|
-
|
|
41
|
-
@serving_block.call(@http_range,
|
|
42
|
-
writable_for_range_bytes.verify!
|
|
115
|
+
range_size = @http_range.size #: Integer
|
|
116
|
+
BlockWritableWithLimit.write_exactly(range_size, blk) { |io| @serving_block.call(@http_range, io) }
|
|
43
117
|
end
|
|
44
118
|
|
|
119
|
+
# @rbs return: Integer
|
|
45
120
|
def content_length
|
|
46
|
-
@http_range.size
|
|
121
|
+
@http_range.size #: Integer
|
|
47
122
|
end
|
|
48
123
|
|
|
124
|
+
# @rbs return: String
|
|
49
125
|
def content_type
|
|
50
126
|
@resource_content_type
|
|
51
127
|
end
|
|
52
128
|
|
|
129
|
+
# @rbs return: Hash[String, String]
|
|
53
130
|
def headers
|
|
54
131
|
{
|
|
55
132
|
"Accept-Ranges" => "bytes",
|
|
@@ -61,18 +138,23 @@ module ServeByteRange
|
|
|
61
138
|
end
|
|
62
139
|
|
|
63
140
|
class EmptyBody
|
|
141
|
+
# @rbs return: Integer
|
|
64
142
|
def status
|
|
65
143
|
200
|
|
66
144
|
end
|
|
67
145
|
|
|
146
|
+
# @rbs return: Integer
|
|
68
147
|
def content_length
|
|
69
148
|
0
|
|
70
149
|
end
|
|
71
150
|
|
|
151
|
+
# @rbs &blk: (String) -> void
|
|
152
|
+
# @rbs return: void
|
|
72
153
|
def each(&blk)
|
|
73
154
|
# write nothing
|
|
74
155
|
end
|
|
75
156
|
|
|
157
|
+
# @rbs return: Hash[String, String]
|
|
76
158
|
def headers
|
|
77
159
|
{
|
|
78
160
|
"Accept-Ranges" => "bytes",
|
|
@@ -82,34 +164,45 @@ module ServeByteRange
|
|
|
82
164
|
end
|
|
83
165
|
|
|
84
166
|
class NotModifiedBody < EmptyBody
|
|
167
|
+
# @rbs return: Integer
|
|
85
168
|
def status
|
|
86
169
|
304
|
|
87
170
|
end
|
|
88
171
|
end
|
|
89
172
|
|
|
90
173
|
class WholeBody < ByteRangeBody
|
|
91
|
-
|
|
92
|
-
|
|
174
|
+
# @rbs resource_size: Integer
|
|
175
|
+
# @rbs resource_content_type: String
|
|
176
|
+
# @rbs &serving_block: (Range[Integer] range, BlockWritableWithLimit io) -> void
|
|
177
|
+
def initialize(resource_size:, resource_content_type: "binary/octet-stream", &serving_block)
|
|
178
|
+
super(http_range: Range.new(0, resource_size - 1), resource_size: resource_size, resource_content_type: resource_content_type, &serving_block)
|
|
93
179
|
end
|
|
94
180
|
|
|
181
|
+
# @rbs return: Integer
|
|
95
182
|
def status
|
|
96
183
|
200
|
|
97
184
|
end
|
|
98
185
|
|
|
186
|
+
# @rbs return: Hash[String, String]
|
|
99
187
|
def headers
|
|
100
188
|
super.tap { |hh| hh.delete("Content-Range") }
|
|
101
189
|
end
|
|
102
190
|
end
|
|
103
191
|
|
|
104
192
|
class Unsatisfiable < EmptyBody
|
|
193
|
+
# @rbs @resource_size: Integer
|
|
194
|
+
|
|
195
|
+
# @rbs resource_size: Integer
|
|
105
196
|
def initialize(resource_size:)
|
|
106
197
|
@resource_size = resource_size
|
|
107
198
|
end
|
|
108
199
|
|
|
200
|
+
# @rbs return: Integer
|
|
109
201
|
def status
|
|
110
202
|
416
|
|
111
203
|
end
|
|
112
204
|
|
|
205
|
+
# @rbs return: Hash[String, String]
|
|
113
206
|
def headers
|
|
114
207
|
super.tap do |hh|
|
|
115
208
|
hh["Content-Range"] = "bytes */%s" % @resource_size
|
|
@@ -119,23 +212,33 @@ module ServeByteRange
|
|
|
119
212
|
|
|
120
213
|
# See https://www.ietf.org/archive/id/draft-ietf-httpbis-p5-range-09.html
|
|
121
214
|
class MultipartByteRangesBody < ByteRangeBody
|
|
122
|
-
# @
|
|
123
|
-
|
|
124
|
-
|
|
215
|
+
# @rbs @http_ranges: Array[Range[Integer]]
|
|
216
|
+
# @rbs @boundary: String
|
|
217
|
+
# @rbs @envelope_size: Integer?
|
|
218
|
+
|
|
219
|
+
# @rbs http_ranges: Array[Range[Integer]]
|
|
220
|
+
# @rbs boundary: String
|
|
221
|
+
# @rbs resource_size: Integer
|
|
222
|
+
# @rbs resource_content_type: String
|
|
223
|
+
# @rbs &serving_block: (Range[Integer] range, BlockWritableWithLimit io) -> void
|
|
224
|
+
def initialize(http_ranges:, boundary:, resource_size:, resource_content_type: "binary/octet-stream", &serving_block)
|
|
225
|
+
super(http_range: http_ranges.fetch(0), resource_size: resource_size, resource_content_type: resource_content_type, &serving_block)
|
|
125
226
|
@http_ranges = http_ranges
|
|
126
227
|
@boundary = boundary
|
|
127
228
|
end
|
|
128
229
|
|
|
230
|
+
# @rbs &blk: (String) -> void
|
|
231
|
+
# @rbs return: void
|
|
129
232
|
def each(&blk)
|
|
130
233
|
@http_ranges.each_with_index do |range, part_i|
|
|
131
234
|
yield(part_header(range, part_i))
|
|
132
|
-
|
|
133
|
-
@serving_block.call(range,
|
|
134
|
-
writable_for_range_bytes.verify!
|
|
235
|
+
range_size = range.size #: Integer
|
|
236
|
+
BlockWritableWithLimit.write_exactly(range_size, blk) { |io| @serving_block.call(range, io) }
|
|
135
237
|
end
|
|
136
238
|
yield(trailer)
|
|
137
239
|
end
|
|
138
240
|
|
|
241
|
+
# @rbs return: Integer
|
|
139
242
|
def content_length
|
|
140
243
|
# The Content-Length of a multipart response includes the length
|
|
141
244
|
# of all the ranges of the resource, but also the lengths of the
|
|
@@ -146,10 +249,12 @@ module ServeByteRange
|
|
|
146
249
|
@envelope_size ||= compute_envelope_size
|
|
147
250
|
end
|
|
148
251
|
|
|
252
|
+
# @rbs return: String
|
|
149
253
|
def content_type
|
|
150
254
|
"multipart/byteranges; boundary=#{@boundary}"
|
|
151
255
|
end
|
|
152
256
|
|
|
257
|
+
# @rbs return: Hash[String, String]
|
|
153
258
|
def headers
|
|
154
259
|
super.tap do |hh|
|
|
155
260
|
hh.delete("Content-Range")
|
|
@@ -158,6 +263,7 @@ module ServeByteRange
|
|
|
158
263
|
|
|
159
264
|
private
|
|
160
265
|
|
|
266
|
+
# @rbs return: Integer
|
|
161
267
|
def compute_envelope_size
|
|
162
268
|
@http_ranges.each_with_index.inject(0) do |size_sum, (http_range, part_index)|
|
|
163
269
|
# Generate the header for this multipart part ahead of time - we can do this
|
|
@@ -166,15 +272,20 @@ module ServeByteRange
|
|
|
166
272
|
header_bytes = part_header(http_range, part_index)
|
|
167
273
|
# The amount of output contributed by the part is:
|
|
168
274
|
# size of the header for the part + bytes of the part itself
|
|
169
|
-
|
|
275
|
+
range_size = http_range.size #: Integer
|
|
276
|
+
part_size = header_bytes.bytesize + range_size
|
|
170
277
|
size_sum + part_size
|
|
171
278
|
end + trailer.bytesize # Account for the trailer as well
|
|
172
279
|
end
|
|
173
280
|
|
|
281
|
+
# @rbs return: String
|
|
174
282
|
def trailer
|
|
175
283
|
"\r\n--%s--\r\n" % @boundary
|
|
176
284
|
end
|
|
177
285
|
|
|
286
|
+
# @rbs http_range: Range[Integer]
|
|
287
|
+
# @rbs part_index: Integer
|
|
288
|
+
# @rbs return: String
|
|
178
289
|
def part_header(http_range, part_index)
|
|
179
290
|
[
|
|
180
291
|
(part_index > 0) ? "\r\n" : "", # Parts follwing the first have to be delimited "at the top"
|
|
@@ -190,22 +301,27 @@ module ServeByteRange
|
|
|
190
301
|
# you need to scan the response, pick a byte sequence that does not occur in it, and then use that. In practice,
|
|
191
302
|
# nobody does that - and a well-behaved HTTP client should honor the Content-Range header when extracting
|
|
192
303
|
# the byte range from the response. See https://stackoverflow.com/questions/37413715
|
|
304
|
+
#
|
|
305
|
+
# @rbs return: String
|
|
193
306
|
def self.generate_boundary
|
|
194
|
-
Random.bytes(12).unpack1("H*")
|
|
307
|
+
Random.bytes(12).unpack1("H*") #: String
|
|
195
308
|
end
|
|
196
309
|
|
|
197
310
|
# The RFC specifically gives an example of non-canonical, but still
|
|
198
311
|
# valid request for overlapping ranges:
|
|
199
|
-
#
|
|
200
|
-
#
|
|
201
|
-
#
|
|
202
|
-
#
|
|
312
|
+
#
|
|
313
|
+
# > Several legal but not canonical specifications of the second 500
|
|
314
|
+
# > bytes (byte offsets 500-999, inclusive):
|
|
315
|
+
#
|
|
316
|
+
# bytes=500-600,601-999
|
|
317
|
+
# bytes=500-700,601-999
|
|
318
|
+
#
|
|
203
319
|
# In such cases, ranges need to be collapsed together. First, to avoid serving
|
|
204
320
|
# a tiny byte range over and over - causing excessive requests to upstream,
|
|
205
321
|
# second - to optimize for doing less requests in total.
|
|
206
322
|
#
|
|
207
|
-
#
|
|
208
|
-
#
|
|
323
|
+
# @rbs ranges: Array[Range[Integer]] -- inclusive, limited ranges of integers
|
|
324
|
+
# @rbs return: Array[Range[Integer]] -- ranges squashed together honoring their overlaps
|
|
209
325
|
def self.coalesce_ranges(ranges)
|
|
210
326
|
return [] if ranges.empty?
|
|
211
327
|
# The RFC says https://www.rfc-editor.org/rfc/rfc7233#section-6.1
|
|
@@ -216,9 +332,9 @@ module ServeByteRange
|
|
|
216
332
|
# > particularly when the ranges are requested out of order for no
|
|
217
333
|
# > apparent reason.
|
|
218
334
|
sorted_ranges = ranges.sort_by(&:begin)
|
|
219
|
-
first = sorted_ranges.shift
|
|
335
|
+
first = sorted_ranges.shift #: Range[Integer]
|
|
220
336
|
coalesced_sorted_ranges = sorted_ranges.each_with_object([first]) do |next_range, acc|
|
|
221
|
-
prev_range = acc.pop
|
|
337
|
+
prev_range = acc.pop #: Range[Integer]
|
|
222
338
|
if prev_range.end >= next_range.begin # Range#overlap? can be used on 3.3+
|
|
223
339
|
new_begin = [prev_range.begin, next_range.begin].min
|
|
224
340
|
new_end = [prev_range.end, next_range.end].max
|
|
@@ -240,39 +356,81 @@ module ServeByteRange
|
|
|
240
356
|
# > representation consists of pages stored in reverse order and the user
|
|
241
357
|
# > agent wishes to transfer one page at a time.
|
|
242
358
|
indices = ranges.map do |r|
|
|
243
|
-
coalesced_sorted_ranges.find_index { |cr| cr.begin <= r.begin && cr.end >= r.end }
|
|
359
|
+
coalesced_sorted_ranges.find_index { |cr| cr.begin <= r.begin && cr.end >= r.end } #: Integer
|
|
244
360
|
end
|
|
245
361
|
indices.uniq.map { |i| coalesced_sorted_ranges.fetch(i) }
|
|
246
362
|
end
|
|
247
363
|
|
|
248
|
-
#
|
|
249
|
-
#
|
|
250
|
-
#
|
|
251
|
-
#
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
364
|
+
# Quotes the ETag unless it already is a quoted strong or weak (`W/"..."`) entity tag
|
|
365
|
+
#
|
|
366
|
+
# @rbs etag: untyped -- the ETag, quoted or not
|
|
367
|
+
# @rbs return: String?
|
|
368
|
+
def self.quote_etag(etag)
|
|
369
|
+
return if etag.nil?
|
|
370
|
+
etag = etag.to_s
|
|
371
|
+
# A double quote is not allowed inside an entity tag, so stray ones from botched quoting get dropped
|
|
372
|
+
etag.match?(/\A(W\/)?"[^"]*"\z/) ? etag : %("#{etag.delete('"')}")
|
|
373
|
+
end
|
|
374
|
+
|
|
375
|
+
# If-Range must use the strong comparison, so a weak ETag never matches.
|
|
376
|
+
# See https://www.rfc-editor.org/rfc/rfc9110#section-13.1.5
|
|
377
|
+
#
|
|
378
|
+
# @rbs header_value: String -- the value of the If-Range header
|
|
379
|
+
# @rbs etag: String? -- the quoted current ETag
|
|
380
|
+
# @rbs return: bool
|
|
381
|
+
def self.strong_etag_match?(header_value, etag)
|
|
382
|
+
return false if etag.nil? || etag.start_with?("W/")
|
|
383
|
+
header_value.strip == etag
|
|
384
|
+
end
|
|
385
|
+
|
|
386
|
+
# If-None-Match is `*` or a list of entity tags, compared with the weak comparison.
|
|
387
|
+
# See https://www.rfc-editor.org/rfc/rfc9110#section-13.1.2
|
|
388
|
+
#
|
|
389
|
+
# @rbs header_value: String -- the value of the If-None-Match header
|
|
390
|
+
# @rbs etag: String? -- the quoted current ETag
|
|
391
|
+
# @rbs return: bool
|
|
392
|
+
def self.weak_etag_match?(header_value, etag)
|
|
393
|
+
return true if header_value.strip == "*" # we always have a representation
|
|
394
|
+
return false if etag.nil?
|
|
395
|
+
opaque_tag = etag.delete_prefix("W/")
|
|
396
|
+
# Scan instead of splitting on commas, since a comma is allowed inside an entity tag
|
|
397
|
+
tags = header_value.scan(/(?:W\/)?"[^"]*"/) #: Array[String]
|
|
398
|
+
tags.any? { |tag| tag.delete_prefix("W/") == opaque_tag }
|
|
399
|
+
end
|
|
400
|
+
|
|
401
|
+
# Serves a resource of `resource_size` bytes, yielding every range that has to be sent along with
|
|
402
|
+
# the IO-ish object to `write()` the bytes of that range into. Returns the Rack response triplet:
|
|
403
|
+
#
|
|
404
|
+
# status, headers, body = ServeByteRange.serve_ranges(env, resource_size: file.size) do |range, io|
|
|
405
|
+
# IO.copy_stream(file, io, range.size, range.begin)
|
|
258
406
|
# end
|
|
259
407
|
# [status, headers, body]
|
|
260
|
-
#
|
|
408
|
+
#
|
|
409
|
+
# @rbs env: Hash[String, untyped] -- the Rack env
|
|
410
|
+
# @rbs resource_size: Integer -- the size of the complete resource in bytes
|
|
411
|
+
# @rbs etag: untyped -- the current ETag of the resource, or nil if none
|
|
412
|
+
# @rbs resource_content_type: String -- the MIME type string of the resource
|
|
413
|
+
# @rbs multipart_boundary: String -- defaults to an automatically generated pseudo-random string
|
|
414
|
+
# @rbs &range_serving_block: (Range[Integer] range, BlockWritableWithLimit io) -> void
|
|
415
|
+
# @rbs return: rack_response
|
|
261
416
|
def self.serve_ranges(env, resource_size:, etag: nil, resource_content_type: "binary/octet-stream", multipart_boundary: generate_boundary, &range_serving_block)
|
|
417
|
+
etag = quote_etag(etag)
|
|
418
|
+
|
|
262
419
|
# As per RFC:
|
|
263
420
|
# If the entity tag given in the If-Range header matches the current cache validator for the entity,
|
|
264
421
|
# then the server SHOULD provide the specified sub-range of the entity using a 206 (Partial Content)
|
|
265
422
|
# response. If the cache validator does not match, then the server SHOULD return the entire entity
|
|
266
423
|
# using a 200 (OK) response.
|
|
267
|
-
wants_ranges_and_etag_valid = env["HTTP_IF_RANGE"] && env["HTTP_IF_RANGE"]
|
|
424
|
+
wants_ranges_and_etag_valid = env["HTTP_IF_RANGE"] && strong_etag_match?(env["HTTP_IF_RANGE"], etag) && env["HTTP_RANGE"]
|
|
268
425
|
wants_ranges_and_no_etag = !env["HTTP_IF_RANGE"] && env["HTTP_RANGE"]
|
|
269
|
-
wants_no_ranges_and_supplies_etag = env["HTTP_IF_NONE_MATCH"] && !env["HTTP_RANGE"] && !env["HTTP_IF_RANGE"]
|
|
270
426
|
|
|
271
427
|
# Very old Rack versions do not have get_byte_ranges and have just byte_ranges
|
|
272
428
|
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)
|
|
273
429
|
http_ranges_from_header = coalesce_ranges(http_ranges_from_header) if http_ranges_from_header
|
|
274
430
|
|
|
275
|
-
|
|
431
|
+
# If-None-Match gets evaluated before Range, and a match means there is nothing to send
|
|
432
|
+
# at all - see https://www.rfc-editor.org/rfc/rfc9110#section-13.2.2
|
|
433
|
+
body = if env["HTTP_IF_NONE_MATCH"] && weak_etag_match?(env["HTTP_IF_NONE_MATCH"], etag)
|
|
276
434
|
NotModifiedBody.new
|
|
277
435
|
elsif resource_size.zero?
|
|
278
436
|
EmptyBody.new
|
|
@@ -288,10 +446,31 @@ module ServeByteRange
|
|
|
288
446
|
WholeBody.new(resource_size: resource_size, resource_content_type: resource_content_type, &range_serving_block)
|
|
289
447
|
end
|
|
290
448
|
headers = body.headers
|
|
291
|
-
|
|
292
|
-
etag = etag.inspect if etag && !etag.match?(/^".+"$/)
|
|
293
449
|
headers["ETag"] = etag if etag
|
|
294
450
|
|
|
295
451
|
[body.status, headers, body]
|
|
296
452
|
end
|
|
453
|
+
|
|
454
|
+
# Serves a Sequence, yielding every segment that a requested range touches, the range of bytes within
|
|
455
|
+
# that segment and the IO-ish object to `write()` those bytes into. Writes for every segment are checked
|
|
456
|
+
# against the size of the range within that segment.
|
|
457
|
+
#
|
|
458
|
+
# @rbs env: Hash[String, untyped] -- the Rack env
|
|
459
|
+
# @rbs sequence: Sequence -- the Sequence to serve
|
|
460
|
+
# @rbs etag: untyped -- defaults to the ETag of the Sequence, pass nil to not send one
|
|
461
|
+
# @rbs resource_content_type: String -- the MIME type string of the resource
|
|
462
|
+
# @rbs multipart_boundary: String -- defaults to an automatically generated pseudo-random string
|
|
463
|
+
# @rbs &segment_serving_block: (untyped segment, Range[Integer] range_in_segment, BlockWritableWithLimit io) -> void
|
|
464
|
+
# @rbs return: rack_response
|
|
465
|
+
def self.serve_sequence(env, sequence, etag: sequence.etag, resource_content_type: "binary/octet-stream", multipart_boundary: generate_boundary, &segment_serving_block)
|
|
466
|
+
serve_ranges(env, resource_size: sequence.size, etag: etag, resource_content_type: resource_content_type, multipart_boundary: multipart_boundary) do |range, io|
|
|
467
|
+
sequence.each_in_range(range) do |segment, range_in_segment|
|
|
468
|
+
label = -> { "segment (#{segment.class}, bytes #{range_in_segment.begin}-#{range_in_segment.end} of it)" }
|
|
469
|
+
segment_size = range_in_segment.size #: Integer
|
|
470
|
+
BlockWritableWithLimit.write_exactly(segment_size, ->(bytes) { io.write(bytes) }, label: label) do |segment_io|
|
|
471
|
+
segment_serving_block.call(segment, range_in_segment, segment_io)
|
|
472
|
+
end
|
|
473
|
+
end
|
|
474
|
+
end
|
|
475
|
+
end
|
|
297
476
|
end
|
data/serve_byte_range.gemspec
CHANGED
|
@@ -10,7 +10,12 @@ Gem::Specification.new do |spec|
|
|
|
10
10
|
spec.license = "MIT"
|
|
11
11
|
spec.summary = "Serve byte range HTTP responses lazily"
|
|
12
12
|
spec.description = "Serve byte range HTTP responses lazily"
|
|
13
|
+
|
|
13
14
|
spec.homepage = "https://github.com/julik/serve_byte_range"
|
|
15
|
+
# The homepage link on rubygems.org only appears if you add homepage_uri. Just spec.homepage is not enough.
|
|
16
|
+
spec.metadata["homepage_uri"] = spec.homepage
|
|
17
|
+
spec.metadata["source_code_uri"] = spec.homepage
|
|
18
|
+
# spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
|
|
14
19
|
|
|
15
20
|
spec.required_ruby_version = ">= 2.7.0"
|
|
16
21
|
|
|
@@ -19,13 +24,13 @@ Gem::Specification.new do |spec|
|
|
|
19
24
|
spec.bindir = "exe"
|
|
20
25
|
spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
|
|
21
26
|
spec.require_paths = ["lib"]
|
|
27
|
+
spec.rdoc_options = ["--markup", "markdown", "--main", "README.md"]
|
|
28
|
+
spec.extra_rdoc_files = ["README.md"]
|
|
22
29
|
|
|
23
|
-
spec.add_dependency "rack", ">=
|
|
30
|
+
spec.add_dependency "rack", ">= 2.0"
|
|
31
|
+
spec.add_dependency "base64"
|
|
24
32
|
|
|
25
33
|
spec.add_development_dependency "minitest"
|
|
26
34
|
spec.add_development_dependency "rake"
|
|
27
35
|
spec.add_development_dependency "standard", "1.28.5" # Needed for 2.6
|
|
28
|
-
spec.add_development_dependency "yard", "~> 0.9"
|
|
29
|
-
spec.add_development_dependency "sord"
|
|
30
|
-
spec.add_development_dependency "redcarpet"
|
|
31
36
|
end
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Generated from lib/serve_byte_range/sequence.rb with RBS::Inline
|
|
2
|
+
|
|
3
|
+
module ServeByteRange
|
|
4
|
+
# A resource composed of several segments glued together - for example, byte ranges of objects
|
|
5
|
+
# in remote storage interleaved with literal strings. A segment can be any object, since its
|
|
6
|
+
# size is given explicitly. A Sequence can also be a segment of another Sequence.
|
|
7
|
+
#
|
|
8
|
+
# seq = ServeByteRange::Sequence.new
|
|
9
|
+
# seq.add_segment(s3_object, size: 1024, etag: s3_object.etag)
|
|
10
|
+
# seq << "Literal text"
|
|
11
|
+
# ServeByteRange.serve_sequence(env, seq) do |segment, range_in_segment, io|
|
|
12
|
+
# io.write(segment.is_a?(String) ? segment.byteslice(range_in_segment) : fetch_range(segment, range_in_segment))
|
|
13
|
+
# end
|
|
14
|
+
class Sequence
|
|
15
|
+
class Interval < Struct[untyped | Integer | String | bool]
|
|
16
|
+
attr_accessor segment(): untyped
|
|
17
|
+
|
|
18
|
+
attr_accessor size(): Integer
|
|
19
|
+
|
|
20
|
+
attr_accessor offset(): Integer
|
|
21
|
+
|
|
22
|
+
attr_accessor etag(): String
|
|
23
|
+
|
|
24
|
+
attr_accessor weak(): bool
|
|
25
|
+
|
|
26
|
+
def self.new: (?untyped segment, ?Integer size, ?Integer offset, ?String etag, ?bool weak) -> instance
|
|
27
|
+
| (?segment: untyped, ?size: Integer, ?offset: Integer, ?etag: String, ?weak: bool) -> instance
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
@intervals: Array[Interval]
|
|
31
|
+
|
|
32
|
+
@etag: String?
|
|
33
|
+
|
|
34
|
+
# The total size of all segments in bytes
|
|
35
|
+
attr_reader size: Integer
|
|
36
|
+
|
|
37
|
+
# @rbs *segments: untyped -- segments to add with `<<`
|
|
38
|
+
def initialize: (*untyped segments) -> untyped
|
|
39
|
+
|
|
40
|
+
# Adds a segment of a given size. Segments of zero size are skipped. The size and ETag are taken
|
|
41
|
+
# as they are now, so a String gets copied and frozen, and a Sequence gets frozen when added.
|
|
42
|
+
#
|
|
43
|
+
# The `etag` goes into the ETag of the Sequence. Without it only the size is known, which won't catch
|
|
44
|
+
# content changes that keep the size the same - so the ETag of the Sequence becomes weak. It can be
|
|
45
|
+
# quoted (as S3 returns it) or not, and a weak one (`W/"..."`) makes the ETag of the Sequence weak too.
|
|
46
|
+
#
|
|
47
|
+
# @rbs segment: untyped -- any object, it gets yielded back when serving
|
|
48
|
+
# @rbs size: Integer -- the size of the segment in bytes
|
|
49
|
+
# @rbs etag: untyped -- a validator for the segment
|
|
50
|
+
# @rbs return: self
|
|
51
|
+
def add_segment: (untyped segment, size: Integer, ?etag: untyped) -> self
|
|
52
|
+
|
|
53
|
+
# Adds a String (sized in bytes and validated by its contents), a Sequence, an object responding
|
|
54
|
+
# to `bytesize`, or an IO-ish object (responding to `read` and `size`, like File, StringIO or Tempfile).
|
|
55
|
+
# Anything else needs an explicit size, so use #add_segment for it.
|
|
56
|
+
#
|
|
57
|
+
# @rbs segment: untyped
|
|
58
|
+
# @rbs return: self
|
|
59
|
+
def <<: (untyped segment) -> self
|
|
60
|
+
|
|
61
|
+
# A weak ETag stops If-Range from matching, so a client won't splice ranges taken from
|
|
62
|
+
# different versions of a segment whose content has changed but whose size has not
|
|
63
|
+
#
|
|
64
|
+
# Returns a quoted ETag derived from the ETags of all the segments, weak (`W/"..."`)
|
|
65
|
+
# if any segment was added without an `etag:`
|
|
66
|
+
#
|
|
67
|
+
# @rbs return: String
|
|
68
|
+
def etag: () -> String
|
|
69
|
+
|
|
70
|
+
# Freezes the Sequence, so that no more segments can be added
|
|
71
|
+
#
|
|
72
|
+
# @rbs return: self
|
|
73
|
+
def freeze: () -> self
|
|
74
|
+
|
|
75
|
+
# Tells whether every segment has an ETag of its own
|
|
76
|
+
#
|
|
77
|
+
# @rbs return: bool
|
|
78
|
+
def strong_etag?: () -> bool
|
|
79
|
+
|
|
80
|
+
# Yields every segment the range touches, along with the inclusive range of bytes within that segment.
|
|
81
|
+
# Nested Sequences are descended into, so only the leaf segments get yielded.
|
|
82
|
+
#
|
|
83
|
+
# The range must have both ends given, exclusive ranges are fine. The yielded ranges are always inclusive.
|
|
84
|
+
# Returns an Enumerator when called without a block.
|
|
85
|
+
#
|
|
86
|
+
# @rbs (Range[Integer] range) { (untyped segment, Range[Integer] range_in_segment) -> void } -> void
|
|
87
|
+
# | (Range[Integer] range) -> Enumerator[[untyped, Range[Integer]], void]
|
|
88
|
+
def each_in_range: (Range[Integer] range) { (untyped segment, Range[Integer] range_in_segment) -> void } -> void
|
|
89
|
+
| (Range[Integer] range) -> Enumerator[[ untyped, Range[Integer] ], void]
|
|
90
|
+
end
|
|
91
|
+
end
|