class Falcon::Adapters::Input
Wraps a streaming input body into the interface required by `rack.input`.
The input stream is an `IO`-like object which contains the raw HTTP POST data. When applicable, its external encoding must be `ASCII-8BIT` and it must be opened in binary mode, for Ruby 1.9 compatibility. The input stream must respond to `gets`, `each`, `read` and `rewind`.
This implementation is not always rewindable, to avoid buffering the input when handling large uploads. See {Rewindable} for more details.
Attributes
The input body. @attribute [Protocol::HTTP::Body::Readable]
Public Class Methods
Initialize the input wrapper. @parameter body [Protocol::HTTP::Body::Readable]
# File lib/falcon/adapters/input.rb, line 36 def initialize(body) @body = body # Will hold remaining data in `#read`. @buffer = nil @finished = @body.nil? end
Public Instance Methods
Close and discard the remainder of the input stream.
# File lib/falcon/adapters/input.rb, line 134 def close @body&.close end
Enumerate chunks of the request body. @yields {|chunk| …}
@parameter chunk [String]
# File lib/falcon/adapters/input.rb, line 51 def each(&block) return to_enum unless block_given? while chunk = gets yield chunk end end
Has the input stream been read completely? @returns [Boolean]
# File lib/falcon/adapters/input.rb, line 114 def eof? @finished and @buffer.nil? end
Read the next chunk of data from the input stream.
`gets` must be called without arguments and return a `String`, or `nil` when the input stream has no more data.
@returns [String | Nil] The next chunk from the body.
# File lib/falcon/adapters/input.rb, line 123 def gets if @buffer.nil? return read_next else buffer = @buffer @buffer = nil return buffer end end
Read data from the input stream.
`read` behaves like `IO#read`. Its signature is `read(length = nil, buffer = nil)`. If given, length must be a non-negative `Integer` (>= 0) or `nil`, and buffer must be a `String` and may not be nil. If `length` is given and not `nil`, then this method reads at most `length` bytes from the input stream. If `length` is not given or `nil`, then this method reads all data. When the end is reached, this method returns `nil` if `length` is given and not `nil`, or an empty `String` if `length` is not given or is `nil`. If `buffer` is given, then the read data will be placed into the `buffer` instead of a newly created `String` object.
@parameter length [Integer] the amount of data to read @parameter buffer [String] the buffer which will receive the data @returns a buffer containing the data
# File lib/falcon/adapters/input.rb, line 84 def read(length = nil, buffer = nil) buffer ||= Async::IO::Buffer.new buffer.clear until buffer.bytesize == length @buffer = read_next if @buffer.nil? break if @buffer.nil? remaining_length = length - buffer.bytesize if length if remaining_length && remaining_length < @buffer.bytesize # We know that we are not going to reuse the original buffer. # But byteslice will generate a hidden copy. So let's freeze it first: @buffer.freeze buffer << @buffer.byteslice(0, remaining_length) @buffer = @buffer.byteslice(remaining_length, @buffer.bytesize) else buffer << @buffer @buffer = nil end end return nil if buffer.empty? && length && length > 0 return buffer end
Rewind the input stream back to the start.
`rewind` must be called without arguments. It rewinds the input stream back to the beginning. It must not raise Errno::ESPIPE: that is, it may not be a pipe or a socket. Therefore, handler developers must buffer the input data into some rewindable object if the underlying input stream is not rewindable.
@returns [Boolean] Whether the body could be rewound.
# File lib/falcon/adapters/input.rb, line 64 def rewind if @body and @body.respond_to? :rewind # If the body is not rewindable, this will fail. @body.rewind @buffer = nil @finished = false return true end return false end
Private Instance Methods
# File lib/falcon/adapters/input.rb, line 140 def read_next return nil if @finished if chunk = @body.read return chunk else @finished = true return nil end end