Class: TCPClient::Configuration

Inherits:

Object

Object
TCPClient::Configuration

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

#configure(options) ⇒ Configuration
Configures the instance with given options Hash.
#initialize(options = nil) ⇒ Configuration constructor
Initializes and optionally configures the instance with given options.
#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
  self.timeout = @ssl_params = nil
  @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



62
63
64

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

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



131
132
133

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

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



144
145
146

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

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



74
75
76

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

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)



252
253
254

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

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



158
159
160

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

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



171
172
173

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

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



86
87
88

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

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

96	# File 'lib/tcp-client/configuration.rb', line 96 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)



105
106
107

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

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:



215
216
217

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

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 232

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



185
186
187

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

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



198
199
200

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

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

#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 312

def configure(options)
  options.each_pair { set(*_1) }
  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

288	# File 'lib/tcp-client/configuration.rb', line 288 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 265

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

.default ⇒ Configuration

Instance Method Details

#configure(options) ⇒ Configuration

#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`

#configure(options) ⇒ `Configuration`

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

#to_hash ⇒ `{Symbol => Object}`