Class: X::StreamError

Inherits:
X::Streaming::Error show all
Defined in:
x-streaming/lib/x/streaming/stream_error.rb

Overview

Raised for a line of a stream that holds errors and no data

A stream sends the problems it has in a line of their own, such as the operational-disconnect X sends before it closes a stream. The line is not an object the stream delivers, so the stream raises this error in place of passing it to its block, whether the objects are Hashes or are built by an object_class.

A stream reconnects after a line that holds operational-disconnects alone, as it does after a connection that dropped, and raises this error once it has no reconnects left. After any other problems it stops, and the error reaches the caller, who decides whether to open the stream again. The message names the request, and each problem, and #problems holds them, as X::HTTPError#problems holds those of a response the API refused. #http_method and #uri are the request of the stream.

Examples:

Report the problems that stopped a stream

begin
  client.streaming.stream("tweets/search/stream") { |post| handle(post) }
rescue X::StreamError => e
  warn e.problems.map(&:title).join(", ")
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(message = nil, problems: [], http_method: nil, uri: nil) ⇒ StreamError

Initialize a new StreamError

Public, so that code that rescues a StreamError can be tested with one built by hand, as StreamParser builds one for a line of a stream, and raised with a message alone, as any exception is. The message is the one given, or else the title and detail of each problem, and names the request, when given its method and URI, as the errors of x-core name the request that raised them.

Examples:

Create an error

error = X::StreamError.new(problems: X::Problem.all_from(body), http_method: :get, uri: stream_uri)

Raise the error with a message alone, as a test stub may

raise X::StreamError, "The stream dropped"

Parameters:

  • message (String, nil) (defaults to: nil) —

    the message, or nil for the one the problems give

  • problems (Array<Problem>) (defaults to: []) —

    the problems the line held

  • http_method (Symbol, String, nil) (defaults to: nil) —

    the method of the request of the stream, in any case

  • uri (URI::Generic, nil) (defaults to: nil) —

    the URI of the request of the stream



69
70
71
72
73
74
 
# File 'x-streaming/lib/x/streaming/stream_error.rb', line 69

def initialize(message = nil, problems: [], http_method: nil, uri: nil)
  @problems = problems.dup.freeze
  @http_method = http_method&.downcase&.to_sym
  @uri = uri
  super(naming_request(message || describe(problems)))
end

Instance Attribute Details

#http_method ⇒ Symbol? (readonly)

The HTTP method the request of the stream was sent with

Examples:

Read the method of the stream

error.http_method # => :get

Returns:

  • (Symbol, nil) —

    the method, as :get, or nil for an error built without one, such as one a test built



34
35
36
 
# File 'x-streaming/lib/x/streaming/stream_error.rb', line 34

def http_method
  @http_method
end

#problems ⇒ Array<Problem> (readonly)

The problems the line of the stream held

Examples:

Read the title of each problem

error.problems.map(&:title) # => ["operational-disconnect"]

Returns:

  • (Array<Problem>) —

    the problems, frozen, in the order the line held them



50
51
52
 
# File 'x-streaming/lib/x/streaming/stream_error.rb', line 50

def problems
  @problems
end

#uri ⇒ URI::Generic? (readonly)

The URI the request of the stream was sent to

Examples:

Read the path of the stream

error.uri.path # => "/2/tweets/search/stream"

Returns:

  • (URI::Generic, nil) —

    the URI, or nil for an error built without one



42
43
44
 
# File 'x-streaming/lib/x/streaming/stream_error.rb', line 42

def uri
  @uri
end