Module: Protocol::HTTP::Body::Stream::Reader

Included in:
Protocol::HTTP::Body::Stream
Defined in:
lib/protocol/http/body/stream.rb

Overview

This provides a read-only interface for data, which is surprisingly tricky to implement correctly.

Instance Method Summary collapse

Instance Method Details

#each(&block) ⇒ Object

Iterate over each chunk of data from the input stream.



149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/protocol/http/body/stream.rb', line 149

def each(&block)
	return to_enum unless block_given?
	
	if @buffer
		yield @buffer
		@buffer = nil
	end
	
	while chunk = read_next
		yield chunk
	end
end

#gets(separator = NEWLINE, limit = nil, chomp: false) ⇒ Object

Read a single line from the stream.



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/protocol/http/body/stream.rb', line 229

def gets(separator = NEWLINE, limit = nil, chomp: false)
	# If the separator is an integer, it is actually the limit:
	if separator.is_a?(Integer)
		limit = separator
		separator = NEWLINE
	end
	
	# If no separator is given, this is the same as a read operation:
	if separator.nil?
		# I tried using `read(limit)` here but it will block until the limit is reached, which is not usually desirable behaviour.
		return read_partial(limit)
	end
	
	# We don't want to split on the separator, so we subtract the size of the separator:
	split_offset = separator.bytesize - 1
	
	@buffer ||= read_next
	return nil if @buffer.nil?
	
	offset = 0
	until index = @buffer.index(separator, offset)
		offset = @buffer.bytesize - split_offset
		offset = 0 if offset < 0
		
		# If we have gone past the limit, we are done:
		if limit and offset >= limit
			@buffer.freeze
			matched = @buffer.byteslice(0, limit)
			@buffer = @buffer.byteslice(limit, @buffer.bytesize)
			return matched
		end
		
		# Read more data:
		if chunk = read_next
			@buffer << chunk
		else
			# No more data could be read, return the remaining data:
			buffer = @buffer
			@buffer = nil
			
			# Return nil for empty buffers, otherwise return the content:
			if buffer && !buffer.empty?
				return buffer
			else
				return nil
			end
		end
	end
	
	# Freeze the buffer, as this enables us to use byteslice without generating a hidden copy:
	@buffer.freeze
	
	if limit and index > limit
		line = @buffer.byteslice(0, limit)
		@buffer = @buffer.byteslice(limit, @buffer.bytesize)
	else
		line = @buffer.byteslice(0, index+(chomp ? 0 : separator.bytesize))
		@buffer = @buffer.byteslice(index+separator.bytesize, @buffer.bytesize)
	end
	
	return line
end

#read(length = nil, buffer = nil) ⇒ Object

Read data from the underlying stream.

If given a non-negative length, it will read at most that many bytes from the stream. If the stream is at EOF, it will return nil.

If the length is not given, it will read all data until EOF, or return an empty string if the stream is already at EOF.

If buffer is given, then the read data will be placed into buffer instead of a newly created String object.



54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/protocol/http/body/stream.rb', line 54

def read(length = nil, buffer = nil)
	if length == 0
		return (buffer ? buffer.clear : String.new(encoding: Encoding::BINARY))
	end
	
	buffer ||= String.new(encoding: Encoding::BINARY)
	
	# Take any previously buffered data and replace it into the given buffer.
	if @buffer
		buffer.replace(@buffer)
		@buffer = nil
	else
		buffer.clear
	end
	
	if length
		while buffer.bytesize < length and chunk = read_next
			buffer << chunk
		end
		
		# This ensures the subsequent `slice!` works correctly.
		buffer.force_encoding(Encoding::BINARY)
		
		# This will be at least one copy:
		@buffer = buffer.byteslice(length, buffer.bytesize)
		
		# This should be zero-copy:
		buffer.slice!(length, buffer.bytesize)
		
		if buffer.empty?
			return nil
		else
			return buffer
		end
	else
		while chunk = read_next
			buffer << chunk
		end
		
		return buffer
	end
end

#read_nonblock(length, buffer = nil, exception: nil) ⇒ Object

Read data from the stream without blocking if possible.



166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/protocol/http/body/stream.rb', line 166

def read_nonblock(length, buffer = nil, exception: nil)
	@buffer ||= read_next
	chunk = nil
	
	unless @buffer
		buffer&.clear
		return
	end
	
	if @buffer.bytesize > length
		chunk = @buffer.byteslice(0, length)
		@buffer = @buffer.byteslice(length, @buffer.bytesize)
	else
		chunk = @buffer
		@buffer = nil
	end
	
	if buffer
		buffer.replace(chunk)
	else
		buffer = chunk
	end
	
	return buffer
end

#read_partial(length = nil, buffer = nil) ⇒ Object

Read some bytes from the stream.

If the length is given, at most length bytes will be read. Otherwise, one chunk of data from the underlying stream will be read.

Will avoid reading from the underlying stream if there is buffered data available.



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/protocol/http/body/stream.rb', line 104

def read_partial(length = nil, buffer = nil)
	if @buffer
		if buffer
			buffer.replace(@buffer)
		else
			buffer = @buffer
		end
		@buffer = nil
	else
		if chunk = read_next
			if buffer
				buffer.replace(chunk)
			else
				buffer = chunk
			end
		else
			buffer&.clear
			buffer = nil
		end
	end
	
	if buffer and length
		if buffer.bytesize > length
			# This ensures the subsequent `slice!` works correctly.
			buffer.force_encoding(Encoding::BINARY)
			
			@buffer = buffer.byteslice(length, buffer.bytesize)
			buffer.slice!(length, buffer.bytesize)
		end
	end
	
	return buffer
end

#read_until(pattern, offset = 0, chomp: false) ⇒ Object

Read data from the stream until encountering pattern.



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/protocol/http/body/stream.rb', line 198

def read_until(pattern, offset = 0, chomp: false)
	# We don't want to split on the pattern, so we subtract the size of the pattern.
	split_offset = pattern.bytesize - 1
	
	@buffer ||= read_next
	return nil if @buffer.nil?
	
	until index = @buffer.index(pattern, offset)
		offset = @buffer.bytesize - split_offset
		
		offset = 0 if offset < 0
		
		if chunk = read_next
			@buffer << chunk
		else
			return nil
		end
	end
	
	@buffer.freeze
	matched = @buffer.byteslice(0, index+(chomp ? 0 : pattern.bytesize))
	@buffer = @buffer.byteslice(index+pattern.bytesize, @buffer.bytesize)
	
	return matched
end

#readpartial(length, buffer = nil) ⇒ Object

Similar to #read_partial but raises an ‘EOFError` if the stream is at EOF.



142
143
144
 
# File 'lib/protocol/http/body/stream.rb', line 142

def readpartial(length, buffer = nil)
	read_partial(length, buffer) or raise EOFError, "End of file reached!"
end