Class: TCPClient::Configuration

Inherits:

Object

Object
TCPClient::Configuration

show all

Defined in:: lib/tcp-client/configuration.rb,
lib/tcp-client/default_configuration.rb

Overview

A Configuration is used to configure the behavior of a TCPClient instance.

It allows to specify the monitor timeout, how to handle exceptions, if SSL should be used and to setup the underlying Socket.

Instance Attributes Socket Level collapse

#buffered ⇒ Boolean
Enables/disables use of Socket-level buffering.
#keep_alive ⇒ Boolean
Enables/disables use of Socket-level keep alive handling.
#reverse_lookup ⇒ Boolean
Enables/disables address lookup.
#ssl? ⇒ Boolean readonly
Whether SSL is configured, see #ssl_params.
#ssl_params ⇒ {Symbol => Object}^?
Parameters used to initialize a SSL context.

Instance Attributes Timeout Monitoring collapse

#connect_timeout ⇒ Numeric^?
The maximum time in seconds to establish a connection.
#connect_timeout_error ⇒ Class<Exception>
The exception class which will be raised if #connect can not be finished in time.
#read_timeout ⇒ Numeric^?
The maximum time in seconds to read from a connection.
#read_timeout_error ⇒ Class<Exception>
The exception class which will be raised if #read can not be finished in time.
#timeout ⇒ Numeric^? writeonly
Shorthand to set maximum time in seconds for all timeout monitoring.
#timeout_error ⇒ Class<Exception> writeonly
Shorthand to set the exception class which will by raised by any reached timeout.
#write_timeout ⇒ Numeric^?
The maximum time in seconds to write to a connection.
#write_timeout_error ⇒ Class<Exception>
The exception class which will be raised if #write can not be finished in time.

Other Instance Attributes collapse

#normalize_network_errors ⇒ Boolean
Enables/disables if network exceptions should be raised as NetworkError.

Instance Attribute Summary collapse

#:default(: default) ⇒ Configuration readonly
Used by default if no dedicated configuration was specified.

Class Method Summary collapse

.create(options = nil) {|configuration| ... } ⇒ Configuration
Shorthand to create a new configuration.
.default ⇒ Configuration
Used by default if no dedicated configuration was specified.

Instance Method Summary collapse

#==(other) ⇒ Object (also: #eql?)
#configure(options) ⇒ Configuration
Configures the instance with given options Hash.
#equal?(other) ⇒ Boolean
#freeze ⇒ Object
#initialize(options = nil) ⇒ Configuration constructor
Initializes and optionally configures the instance with given options.
#initialize_copy(_org) ⇒ Object
#to_h(&block) ⇒ {Symbol => Object}
Hash containing all attributes.
#to_hash ⇒ {Symbol => Object}
Hash containing all attributes.

Constructor Details

#initialize(options = nil) ⇒ `Configuration`

Initializes and optionally configures the instance with given options.

See Also:

#configure

# File 'lib/tcp-client/configuration.rb', line 44

def initialize(options = nil)
  @buffered = @keep_alive = @reverse_lookup = true
  @connect_timeout_error = ConnectTimeoutError
  @read_timeout_error = ReadTimeoutError
  @write_timeout_error = WriteTimeoutError
  @normalize_network_errors = false
  configure(options) if options
end

Instance Attribute Details

#:default(: default) ⇒ `Configuration` (readonly)

Returns used by default if no dedicated configuration was specified.

Returns:

(Configuration) —
used by default if no dedicated configuration was specified

See Also:

49	# File 'lib/tcp-client/default_configuration.rb', line 49 def self.default = TCPClient.default_configuration

#buffered ⇒ `Boolean`

Enables/disables use of Socket-level buffering

Returns:

(Boolean) —
whether the connection is allowed to use internal buffers (default) or not



61
62
63

# File 'lib/tcp-client/configuration.rb', line 61

def buffered
  @buffered
end

#connect_timeout ⇒ `Numeric`^?

The maximum time in seconds to establish a connection.

Returns:

(Numeric) —
maximum time in seconds
(nil) —
if the connect time should not be monitored (default)

See Also:

TCPClient#connect



130
131
132

# File 'lib/tcp-client/configuration.rb', line 130

def connect_timeout
  @connect_timeout
end

#connect_timeout_error ⇒ `Class<Exception>`

The exception class which will be raised if TCPClient#connect can not be finished in time.

Returns:

(Class<Exception>) —
exception class raised

Raises:

(NotAnExceptionError) —
if given argument is not an Exception class



143
144
145

# File 'lib/tcp-client/configuration.rb', line 143

def connect_timeout_error
  @connect_timeout_error
end

#keep_alive ⇒ `Boolean`

Enables/disables use of Socket-level keep alive handling.

Returns:

(Boolean) —
whether the connection is allowed to use keep alive signals (default) or not



73
74
75

# File 'lib/tcp-client/configuration.rb', line 73

def keep_alive
  @keep_alive
end

#normalize_network_errors ⇒ `Boolean`

Enables/disables if network exceptions should be raised as NetworkError.

This allows to handle all network/socket related exceptions like SocketError, OpenSSL::SSL::SSLError, IOError, etc. in a uniform manner. If this option is set to true all these error cases are raised as NetworkError and can be easily captured.

Returns:

(Boolean) —
whether all network exceptions should be raised as NetworkError, or not (default)



251
252
253

# File 'lib/tcp-client/configuration.rb', line 251

def normalize_network_errors
  @normalize_network_errors
end

#read_timeout ⇒ `Numeric`^?

The maximum time in seconds to read from a connection.

Returns:

(Numeric) —
maximum time in seconds
(nil) —
if the read time should not be monitored (default)

See Also:

TCPClient#read



157
158
159

# File 'lib/tcp-client/configuration.rb', line 157

def read_timeout
  @read_timeout
end

#read_timeout_error ⇒ `Class<Exception>`

The exception class which will be raised if TCPClient#read can not be finished in time.

Returns:

(Class<Exception>) —
exception class raised

Raises:

(NotAnExceptionError) —
if given argument is not an Exception class



170
171
172

# File 'lib/tcp-client/configuration.rb', line 170

def read_timeout_error
  @read_timeout_error
end

#reverse_lookup ⇒ `Boolean`

Enables/disables address lookup.

Returns:

(Boolean) —
whether the connection is allowed to lookup the address (default) or not



85
86
87

# File 'lib/tcp-client/configuration.rb', line 85

def reverse_lookup
  @reverse_lookup
end

#ssl? ⇒ `Boolean` (readonly)

Returns whether SSL is configured, see #ssl_params.

Returns:

(Boolean) —
whether SSL is configured, see #ssl_params

95	# File 'lib/tcp-client/configuration.rb', line 95 def ssl? = @ssl_params ? true : false

#ssl_params ⇒ `{Symbol => Object}`^?

Parameters used to initialize a SSL context. SSL/TLS will only be used if this attribute is not nil.

Returns:

({Symbol => Object}) —
SSL parameters for the SSL context
(nil) —
if no SSL should be used (default)



104
105
106

# File 'lib/tcp-client/configuration.rb', line 104

def ssl_params
  @ssl_params
end

#timeout=(value) ⇒ `Numeric`^? (writeonly)

Shorthand to set maximum time in seconds for all timeout monitoring.

Returns:

(Numeric) —
maximum time in seconds for any action
(nil) —
if all timeout monitoring should be disabled (default)

See Also:



214
215
216

# File 'lib/tcp-client/configuration.rb', line 214

def timeout=(value)
  @connect_timeout = @write_timeout = @read_timeout = as_seconds(value)
end

#timeout_error=(value) ⇒ `Class<Exception>` (writeonly)

Shorthand to set the exception class which will by raised by any reached timeout.

Returns:

(Class<Exception>) —
exception class raised

Raises:

(NotAnExceptionError) —
if given argument is not an Exception class

See Also:

# File 'lib/tcp-client/configuration.rb', line 231

def timeout_error=(value)
  @connect_timeout_error =
    @read_timeout_error = @write_timeout_error = as_exception(value)
end

#write_timeout ⇒ `Numeric`^?

The maximum time in seconds to write to a connection.

Returns:

(Numeric) —
maximum time in seconds
(nil) —
if the write time should not be monitored (default)

See Also:

TCPClient#write



184
185
186

# File 'lib/tcp-client/configuration.rb', line 184

def write_timeout
  @write_timeout
end

#write_timeout_error ⇒ `Class<Exception>`

The exception class which will be raised if TCPClient#write can not be finished in time.

Returns:

(Class<Exception>) —
exception class raised

Raises:

(NotAnExceptionError) —
if given argument is not an Exception class



197
198
199

# File 'lib/tcp-client/configuration.rb', line 197

def write_timeout_error
  @write_timeout_error
end

Class Method Details

.create {|configuration| ... } ⇒ `Configuration` .create(options) ⇒ `Configuration`

Shorthand to create a new configuration.

Overloads:

.create {|configuration| ... } ⇒ Configuration

Examples:

config = TCPClient::Configuration.create do |cfg|
  cfg.buffered = false
  cfg.ssl_params = { min_version: :TLS1_2, max_version: :TLS1_3 }
end

Yield Parameters:

configuration (Configuration)

.create(options) ⇒ Configuration
Examples:
```
config = TCPClient::Configuration.create(buffered: false)
```
Parameters:
- options ({Symbol => Object}) —
  see #initialize for details

Yields:

(configuration)

Returns:

(Configuration) —
the initialized configuration

# File 'lib/tcp-client/configuration.rb', line 33

def self.create(options = nil)
  configuration = new(options)
  yield(configuration) if block_given?
  configuration
end

.default ⇒ `Configuration`

Returns used by default if no dedicated configuration was specified.

Returns:

(Configuration) —
used by default if no dedicated configuration was specified

See Also:

49	# File 'lib/tcp-client/default_configuration.rb', line 49 def self.default = TCPClient.default_configuration

Instance Method Details

#==(other) ⇒ `Object` Also known as: eql?

330	# File 'lib/tcp-client/configuration.rb', line 330 def ==(other) = to_hash == other.to_h

#configure(options) ⇒ `Configuration`

Configures the instance with given options Hash.

Parameters:

options ({Symbol => Object})

Options Hash (options):

:buffered, (Boolean) —
see #buffered
:keep_alive, (Boolean) —
see #keep_alive
:reverse_lookup, (Boolean) —
see #reverse_lookup
:ssl_params, ({Symbol => Object}) —
see #ssl_params
:connect_timeout, (Numeric) —
see #connect_timeout
:connect_timeout_error, (Class<Exception>) —
see #connect_timeout_error
:read_timeout, (Numeric) —
see #read_timeout
:read_timeout_error, (Class<Exception>) —
see #read_timeout_error
:write_timeout, (Numeric) —
see #write_timeout
:write_timeout_error, (Class<Exception>) —
see #write_timeout_error
:normalize_network_errors, (Boolean) —
see #normalize_network_errors

Returns:

(Configuration) —
self

# File 'lib/tcp-client/configuration.rb', line 311

def configure(options)
  options.each_pair { set(*_1) }
  self
end

#equal?(other) ⇒ `Boolean`

Returns:

(Boolean)

334	# File 'lib/tcp-client/configuration.rb', line 334 def equal?(other) = self.class == other.class && to_hash == other.to_hash

#freeze ⇒ `Object`

# File 'lib/tcp-client/configuration.rb', line 317

def freeze
  @ssl_params.freeze
  super
end

#initialize_copy(_org) ⇒ `Object`

# File 'lib/tcp-client/configuration.rb', line 323

def initialize_copy(_org)
  super
  @ssl_params = Hash[@ssl_params] if @ssl_params
  self
end

#to_h ⇒ `{Symbol => Object}` #to_h(&block) ⇒ `{Symbol => Object}`

Returns Hash containing all attributes.

Returns:

({Symbol => Object}) —
Hash containing all attributes

See Also:

#configure

287	# File 'lib/tcp-client/configuration.rb', line 287 def to_h(&block) = block ? to_hash.to_h(&block) : to_hash

#to_hash ⇒ `{Symbol => Object}`

Returns Hash containing all attributes.

Returns:

({Symbol => Object}) —
Hash containing all attributes

See Also:

#configure

# File 'lib/tcp-client/configuration.rb', line 264

def to_hash
  {
    buffered: @buffered,
    keep_alive: @keep_alive,
    reverse_lookup: @reverse_lookup,
    ssl_params: @ssl_params,
    connect_timeout: @connect_timeout,
    connect_timeout_error: @connect_timeout_error,
    read_timeout: @read_timeout,
    read_timeout_error: @read_timeout_error,
    write_timeout: @write_timeout,
    write_timeout_error: @write_timeout_error,
    normalize_network_errors: @normalize_network_errors
  }
end

Class: TCPClient::Configuration

Overview

Instance Attributes Socket Level collapse

Instance Attributes Timeout Monitoring collapse

Other Instance Attributes collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = nil) ⇒ Configuration

Instance Attribute Details

#:default(: default) ⇒ Configuration (readonly)

#buffered ⇒ Boolean

#connect_timeout ⇒ Numeric?

#connect_timeout_error ⇒ Class<Exception>

#keep_alive ⇒ Boolean

#normalize_network_errors ⇒ Boolean

#read_timeout ⇒ Numeric?

#read_timeout_error ⇒ Class<Exception>

#reverse_lookup ⇒ Boolean

#ssl? ⇒ Boolean (readonly)

#ssl_params ⇒ {Symbol => Object}?

#timeout=(value) ⇒ Numeric? (writeonly)

#timeout_error=(value) ⇒ Class<Exception> (writeonly)

#write_timeout ⇒ Numeric?

#write_timeout_error ⇒ Class<Exception>

Class Method Details

.create {|configuration| ... } ⇒ Configuration .create(options) ⇒ Configuration

Examples:

Examples:

.default ⇒ Configuration

Instance Method Details

#==(other) ⇒ Object Also known as: eql?

#configure(options) ⇒ Configuration

#equal?(other) ⇒ Boolean

#freeze ⇒ Object

#initialize_copy(_org) ⇒ Object

#to_h ⇒ {Symbol => Object} #to_h(&block) ⇒ {Symbol => Object}

#to_hash ⇒ {Symbol => Object}

#initialize(options = nil) ⇒ `Configuration`

#:default(: default) ⇒ `Configuration` (readonly)

#buffered ⇒ `Boolean`

#connect_timeout ⇒ `Numeric`^?

#connect_timeout_error ⇒ `Class<Exception>`

#keep_alive ⇒ `Boolean`

#normalize_network_errors ⇒ `Boolean`

#read_timeout ⇒ `Numeric`^?

#read_timeout_error ⇒ `Class<Exception>`

#reverse_lookup ⇒ `Boolean`

#ssl? ⇒ `Boolean` (readonly)

#ssl_params ⇒ `{Symbol => Object}`^?

#timeout=(value) ⇒ `Numeric`^? (writeonly)

#timeout_error=(value) ⇒ `Class<Exception>` (writeonly)

#write_timeout ⇒ `Numeric`^?

#write_timeout_error ⇒ `Class<Exception>`

.create {|configuration| ... } ⇒ `Configuration` .create(options) ⇒ `Configuration`

.default ⇒ `Configuration`

#==(other) ⇒ `Object` Also known as: eql?

#configure(options) ⇒ `Configuration`

#equal?(other) ⇒ `Boolean`

#freeze ⇒ `Object`

#initialize_copy(_org) ⇒ `Object`

#to_h ⇒ `{Symbol => Object}` #to_h(&block) ⇒ `{Symbol => Object}`

#to_hash ⇒ `{Symbol => Object}`