Class: HTTP::Response::Body

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable
Defined in:
lib/http/response/body.rb,
sig/http.rbs

Overview

A streamable response body, also easily converted into a string

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(stream, encoding: Encoding::BINARY) ⇒ Body

Create a new Body instance

Examples:

Body.new(stream, encoding: Encoding::UTF_8)

Parameters:

  • stream (#readpartial) —

    the response stream

  • encoding (Encoding) (defaults to: Encoding::BINARY) —

    the encoding to use

  • encoding: (String, Encoding) (defaults to: Encoding::BINARY) 


42
43
44
45
46
47
48
 
# File 'lib/http/response/body.rb', line 42

def initialize(stream, encoding: Encoding::BINARY)
  @stream     = stream
  @connection = stream.respond_to?(:connection) ? stream.connection : stream
  @streaming  = nil
  @contents   = nil
  @encoding   = find_encoding(encoding)
end

Instance Attribute Details

#connection ⇒ HTTP::Connection (readonly)

The connection object for the request

Examples:

body.connection

Returns:



22
23
24
 
# File 'lib/http/response/body.rb', line 22

def connection
  @connection
end

#encoding ⇒ Encoding (readonly)

The encoding used for the body content

Examples:

body.encoding # => Encoding::UTF_8

Returns:

  • (Encoding) 


31
32
33
 
# File 'lib/http/response/body.rb', line 31

def encoding
  @encoding
end

Instance Method Details

#each ⇒ void #each ⇒ Enumerator[String, void]

This method returns an undefined value.

Iterate over the body, allowing it to be enumerable

Examples:

body.each { |chunk| puts chunk }

Overloads:

  • #each ⇒ void

    This method returns an undefined value.

  • #each ⇒ Enumerator[String, void]

    Returns:

    • (Enumerator[String, void])

Yields:

  • (chunk) —

    Passes each chunk to the block

Yield Parameters:

  • chunk (String) 


74
75
76
77
78
79
 
# File 'lib/http/response/body.rb', line 74

def each
  loop do
    yield readpartial
  end
rescue EOFError # rubocop:disable Lint/SuppressedException
end

#find_encoding(encoding) ⇒ Encoding

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Retrieve encoding by name

Parameters:

  • encoding (String, Encoding)

Returns:

  • (Encoding) 


165
166
167
168
169
 
# File 'lib/http/response/body.rb', line 165

def find_encoding(encoding)
  Encoding.find encoding
rescue ArgumentError
  Encoding::BINARY
end

#inspect ⇒ String

Easier to interpret string inspect

Examples:

body.inspect # => "#<HTTP::Response::Body:3ff2 @streaming=false>"

Returns:

  • (String) 


139
140
141
 
# File 'lib/http/response/body.rb', line 139

def inspect
  "#<#{self.class}:#{object_id.to_s(16)} @streaming=#{!!@streaming}>"
end

#loggable? ⇒ Boolean

Whether the body content is suitable for logging

Returns true when the body encoding is not binary. Binary responses (images, audio, compressed data) produce unreadable log output.

Examples:

body.loggable? # => true

Returns:

  • (Boolean) 


128
129
130
 
# File 'lib/http/response/body.rb', line 128

def loggable?
  @encoding != Encoding::BINARY
end

#read_contents ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Read all chunks into a single string

Returns:

  • (String) 


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

def read_contents
  contents = String.new("", encoding: @encoding)

  loop do
    contents << String.new(@stream.readpartial, encoding: @encoding)
  rescue EOFError
    break
  end

  contents
end

#readpartial ⇒ String

Read a chunk of the body

(see HTTP::Client#readpartial)

Examples:

body.readpartial # => "chunk of data"

Parameters:

  • size (Integer)
  • outbuf (String, nil)

Returns:

  • (String)

Raises:

  • (EOFError) —

    when no more data left



59
60
61
62
63
 
# File 'lib/http/response/body.rb', line 59

def readpartial(*)
  stream!
  chunk = @stream.readpartial(*)
  String.new(chunk, encoding: @encoding)
end

#stream! ⇒ true

Assert that the body is actively being streamed

Examples:

body.stream!

Returns:

  • (true)

Raises:



112
113
114
115
116
 
# File 'lib/http/response/body.rb', line 112

def stream!
  raise StateError, "body has already been consumed" if @streaming.eql?(false)

  @streaming = true
end

#to_s ⇒ String Also known as: to_str

Eagerly consume the entire body as a string

Examples:

body.to_s # => "full response body"

Returns:

  • (String)

Raises:



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/http/response/body.rb', line 88

def to_s
  return @contents if @contents

  raise StateError, "body is being streamed" unless @streaming.nil?

  begin
    @streaming = false
    @contents = read_contents
  rescue
    @contents = nil
    raise
  end

  @contents
end