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

body[R]

The input body. @attribute [Protocol::HTTP::Body::Readable]

Public Class Methods

new(body) click to toggle source

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() click to toggle source

Close and discard the remainder of the input stream.

# File lib/falcon/adapters/input.rb, line 134
def close
        @body&.close
end
each() { |chunk| ... } click to toggle source

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
eof?() click to toggle source

Has the input stream been read completely? @returns [Boolean]

# File lib/falcon/adapters/input.rb, line 114
def eof?
        @finished and @buffer.nil?
end
gets() click to toggle source

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(length = nil, buffer = nil) click to toggle source

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() click to toggle source

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

read_next() click to toggle source
# 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