Class: CZTop::ZsockOptions::OptionsAccessor

Inherits:
Object
  • Object
show all
Includes:
CZMQ::FFI
Defined in:
lib/cztop/zsock_options.rb

Overview

Used to access the options of a Socket or Actor.

Security Mechanisms collapse

MECHANISMS =

supported security mechanisms and their macro value equivalent

{
  0 => :NULL,  # ZMQ_NULL
  1 => :PLAIN, # ZMQ_PLAIN
  2 => :CURVE, # ZMQ_CURVE
  3 => :GSSAPI # ZMQ_GSSAPI
}.freeze

Instance Attribute Summary collapse

High Water Marks collapse

Security Mechanisms collapse

Send and Receive Timeouts collapse

Instance Method Summary collapse

Constructor Details

#initialize(zocket) ⇒ OptionsAccessor

Returns a new instance of OptionsAccessor.

Parameters:



60
61
62
 
# File 'lib/cztop/zsock_options.rb', line 60

def initialize(zocket)
  @zocket = zocket
end

Instance Attribute Details

#zocket ⇒ Socket, Actor (readonly)

Returns whose options this CZTop::ZsockOptions::OptionsAccessor instance is accessing.

Returns:



57
58
59
 
# File 'lib/cztop/zsock_options.rb', line 57

def zocket
  @zocket
end

Instance Method Details

#[](option_name) ⇒ Object

Fuzzy option getter. This is to make it easier when porting applications from CZMQ libraries to CZTop.

Parameters:

  • option_name (Symbol, String) —

    case insensitive option name

Raises:

  • (NoMethodError) —

    if option name can’t be recognized



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/cztop/zsock_options.rb', line 70

def [](option_name)
  meth1 = :"#{option_name}"
  meth2 = :"#{option_name}?"

  if respond_to? meth1
    meth = meth1
  elsif respond_to? meth2
    meth = meth2
  else
    # NOTE: beware of predicates, especially #CURVE_server? & friends
    meth = public_methods.grep_v(/=$/)
                         .find { |m| m =~ /^#{option_name}\??$/i }
    raise NoMethodError, option_name if meth.nil?
  end

  __send__(meth)
end

#[]=(option_name, new_value) ⇒ Object

Fuzzy option setter. This is to make it easier when porting applications from CZMQ libraries to CZTop.

Parameters:

  • option_name (Symbol, String) —

    case insensitive option name

  • new_value (String, Integer) —

    new value

Raises:

  • (NoMethodError) —

    if option name can’t be recognized



95
96
97
98
99
100
101
102
103
104
 
# File 'lib/cztop/zsock_options.rb', line 95

def []=(option_name, new_value)
  meth = :"#{option_name}="

  unless respond_to? meth
    meth = public_methods.find { |m| m =~ /^#{option_name}=$/i }
    raise NoMethodError, option_name if meth.nil?
  end

  __send__(meth, new_value)
end

#CURVE_publickey ⇒ String?

Returns:

  • (String) —

    Z85 encoded public key set

  • (nil) —

    if the current mechanism isn’t CURVE or CURVE isn’t supported



220
221
222
 
# File 'lib/cztop/zsock_options.rb', line 220

def CURVE_publickey
  CURVE_key(:curve_publickey)
end

#CURVE_secretkey ⇒ String?

Returns:

  • (String) —

    Z85 encoded secret key set

  • (nil) —

    if the current mechanism isn’t CURVE or CURVE isn’t supported



212
213
214
 
# File 'lib/cztop/zsock_options.rb', line 212

def CURVE_secretkey
  CURVE_key(:curve_secretkey)
end

#CURVE_server= ⇒ Object

Note:

You’ll have to use a Authenticator.

Make this zocket a CURVE server.

Parameters:

  • bool (Boolean) 


166
167
168
 
# File 'lib/cztop/zsock_options.rb', line 166

def CURVE_server=(bool)
  Zsock.set_curve_server(@zocket, bool ? 1 : 0)
end

#CURVE_server? ⇒ Boolean

Returns whether this zocket is a CURVE server.

Returns:

  • (Boolean) —

    whether this zocket is a CURVE server



158
159
160
 
# File 'lib/cztop/zsock_options.rb', line 158

def CURVE_server?
  Zsock.curve_server(@zocket).positive?
end

#CURVE_serverkey ⇒ String?

Returns:

  • (String) —

    Z85 encoded server key set

  • (nil) —

    if the current mechanism isn’t CURVE or CURVE isn’t supported



174
175
176
 
# File 'lib/cztop/zsock_options.rb', line 174

def CURVE_serverkey
  CURVE_key(:curve_serverkey)
end

#CURVE_serverkey= ⇒ Object

Sets the server’s public key, so the zocket can authenticate the remote server.

Parameters:

  • key (String) —

    Z85 (40 bytes) or binary (32 bytes) server key

Raises:

  • (ArgumentError) —

    if key has wrong size



196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/cztop/zsock_options.rb', line 196

def CURVE_serverkey=(key)
  case key.bytesize
  when 40
    Zsock.set_curve_serverkey(@zocket, key)
  when 32
    ptr = ::FFI::MemoryPointer.from_string(key)
    Zsock.set_curve_serverkey_bin(@zocket, ptr)
  else
    raise ArgumentError, format('invalid server key: %p', key)
  end
end

#events ⇒ Integer

Returns socket events (readable/writable).

Returns:

  • (Integer) —

    socket events (readable/writable)

See Also:



480
481
482
 
# File 'lib/cztop/zsock_options.rb', line 480

def events
  Zsock.events(@zocket)
end

#fd ⇒ Integer

Returns socket file descriptor.

Returns:

  • (Integer) —

    socket file descriptor



473
474
475
 
# File 'lib/cztop/zsock_options.rb', line 473

def fd
  Zsock.fd(@zocket)
end

#heartbeat_ivl ⇒ Integer

Returns current value of Heartbeat IVL.

Returns:

  • (Integer) —

    current value of Heartbeat IVL



391
392
393
 
# File 'lib/cztop/zsock_options.rb', line 391

def heartbeat_ivl
  Zsock.heartbeat_ivl(@zocket)
end

#heartbeat_ivl=(new_value) ⇒ Object

Parameters:

  • new_value (Integer) —

    new value for Heartbeat IVL

Raises:

  • (ArgumentError) 


397
398
399
400
401
 
# File 'lib/cztop/zsock_options.rb', line 397

def heartbeat_ivl=(new_value)
  raise ArgumentError, 'invalid IVL' unless new_value >= 0

  Zsock.set_heartbeat_ivl(@zocket, new_value)
end

#heartbeat_timeout ⇒ Integer

Returns current value of Heartbeat Timeout.

Returns:

  • (Integer) —

    current value of Heartbeat Timeout



423
424
425
 
# File 'lib/cztop/zsock_options.rb', line 423

def heartbeat_timeout
  Zsock.heartbeat_timeout(@zocket)
end

#heartbeat_timeout=(new_value) ⇒ Object

Parameters:

  • new_value (Integer) —

    new value for Heartbeat Timeout

Raises:

  • (ArgumentError) 


429
430
431
432
433
 
# File 'lib/cztop/zsock_options.rb', line 429

def heartbeat_timeout=(new_value)
  raise ArgumentError, 'invalid timeout' unless new_value >= 0

  Zsock.set_heartbeat_timeout(@zocket, new_value)
end

#heartbeat_ttl ⇒ Integer

Returns current value of Heartbeat TTL, in milliseconds.

Returns:

  • (Integer) —

    current value of Heartbeat TTL, in milliseconds



405
406
407
 
# File 'lib/cztop/zsock_options.rb', line 405

def heartbeat_ttl
  Zsock.heartbeat_ttl(@zocket)
end

#heartbeat_ttl=(new_value) ⇒ Object

Note:

The value will internally be rounded to the nearest decisecond. So a value of less than 100 will have no effect.

Parameters:

  • new_value (Integer) —

    new value for Heartbeat TTL, in milliseconds

Raises:

  • (ArgumentError) 


414
415
416
417
418
419
 
# File 'lib/cztop/zsock_options.rb', line 414

def heartbeat_ttl=(new_value)
  raise ArgumentError, "invalid TTL: #{new_value}" unless new_value.is_a? Integer
  raise ArgumentError, "TTL out of range: #{new_value}" unless (0..65_536).include? new_value

  Zsock.set_heartbeat_ttl(@zocket, new_value)
end

#identity ⇒ String

Returns current socket identity.

Returns:

  • (String) —

    current socket identity



360
361
362
 
# File 'lib/cztop/zsock_options.rb', line 360

def identity
  Zsock.identity(@zocket).read_string
end

#identity=(identity) ⇒ Object

Parameters:

  • identity (String) —

    new socket identity

Raises:

  • (ArgumentError) —

    if identity is invalid



367
368
369
370
371
372
373
 
# File 'lib/cztop/zsock_options.rb', line 367

def identity=(identity)
  raise ArgumentError, 'zero-length identity' if identity.bytesize.zero?
  raise ArgumentError, 'identity too long' if identity.bytesize > 255
  raise ArgumentError, 'invalid identity' if identity.start_with? "\0"

  Zsock.set_identity(@zocket, identity)
end

#ipv6=(new_value) ⇒ Object

Set the IPv6 option for the socket. A value of true means IPv6 is enabled on the socket, while false means the socket will use only IPv4. When IPv6 is enabled the socket will connect to, or accept connections from, both IPv4 and IPv6 hosts. Default is false.

Parameters:

  • new_value (Boolean) —

    new value for ipv6



467
468
469
 
# File 'lib/cztop/zsock_options.rb', line 467

def ipv6=(new_value)
  Zsock.set_ipv6(@zocket, new_value ? 1 : 0)
end

#ipv6? ⇒ Boolean

Returns current value of ipv6.

Returns:

  • (Boolean) —

    current value of ipv6



456
457
458
 
# File 'lib/cztop/zsock_options.rb', line 456

def ipv6?
  Zsock.ipv6(@zocket) != 0
end

#linger ⇒ Integer

Returns current value of LINGER.

Returns:

  • (Integer) —

    current value of LINGER



437
438
439
 
# File 'lib/cztop/zsock_options.rb', line 437

def linger
  Zsock.linger(@zocket)
end

#linger=(new_value) ⇒ Object

This defines the number of milliseconds to wait while closing/disconnecting a socket if there are outstanding messages to send.

Default is 0, which means to not wait at all. -1 means to wait indefinitely

Parameters:

  • new_value (Integer) —

    new value for LINGER



450
451
452
 
# File 'lib/cztop/zsock_options.rb', line 450

def linger=(new_value)
  Zsock.set_linger(@zocket, new_value)
end

#mechanism ⇒ Symbol

Note:

This is automatically set through the use of CURVE certificates, etc

Returns the current security mechanism in use.

Returns:

  • (Symbol) —

    the current security mechanism in use



149
150
151
152
153
154
 
# File 'lib/cztop/zsock_options.rb', line 149

def mechanism
  # int zsock_mechanism (void *self);
  code = Zsock.mechanism(@zocket)
  MECHANISMS[code] or
    raise format('unknown ZMQ security mechanism code: %i', code)
end

#PLAIN_password ⇒ String?

Returns:

  • (String) —

    password set for PLAIN mechanism

  • (nil) —

    if the current mechanism isn’t PLAIN



294
295
296
297
298
 
# File 'lib/cztop/zsock_options.rb', line 294

def PLAIN_password
  return nil if mechanism != :PLAIN

  Zsock.plain_password(@zocket).read_string
end

#PLAIN_password=(password) ⇒ Object

Parameters:

  • password (String) —

    password for PLAIN mechanism



302
303
304
 
# File 'lib/cztop/zsock_options.rb', line 302

def PLAIN_password=(password)
  Zsock.set_plain_password(@zocket, password)
end

#PLAIN_server=(bool) ⇒ Object

Note:

You’ll have to use a Authenticator.

Make this zocket a PLAIN server.

Parameters:

  • bool (Boolean) 


271
272
273
 
# File 'lib/cztop/zsock_options.rb', line 271

def PLAIN_server=(bool)
  Zsock.set_plain_server(@zocket, bool ? 1 : 0)
end

#PLAIN_server? ⇒ Boolean

Returns whether this zocket is a PLAIN server.

Returns:

  • (Boolean) —

    whether this zocket is a PLAIN server



263
264
265
 
# File 'lib/cztop/zsock_options.rb', line 263

def PLAIN_server?
  Zsock.plain_server(@zocket).positive?
end

#PLAIN_username ⇒ String?

Returns:

  • (String) —

    username set for PLAIN mechanism

  • (nil) —

    if the current mechanism isn’t PLAIN



278
279
280
281
282
 
# File 'lib/cztop/zsock_options.rb', line 278

def PLAIN_username
  return nil if mechanism != :PLAIN

  Zsock.plain_username(@zocket).read_string
end

#PLAIN_username=(username) ⇒ Object

Note:

You’ll have to use a Authenticator.

Parameters:

  • username (String) —

    username for PLAIN mechanism



287
288
289
 
# File 'lib/cztop/zsock_options.rb', line 287

def PLAIN_username=(username)
  Zsock.set_plain_username(@zocket, username)
end

#rcvhwm ⇒ Integer

Returns the receive high water mark.

Returns:

  • (Integer) —

    the receive high water mark



123
124
125
 
# File 'lib/cztop/zsock_options.rb', line 123

def rcvhwm
  Zsock.rcvhwm(@zocket)
end

#rcvhwm=(value) ⇒ Object

Parameters:

  • value (Integer) —

    the new receive high water mark



129
130
131
 
# File 'lib/cztop/zsock_options.rb', line 129

def rcvhwm=(value)
  Zsock.set_rcvhwm(@zocket, value)
end

#rcvtimeo ⇒ Integer

Note:

-1 means infinite, 0 means nonblocking

Returns the timeout in milliseconds when receiving a message.

Returns:

  • (Integer) —

    the timeout in milliseconds when receiving a message

See Also:



313
314
315
 
# File 'lib/cztop/zsock_options.rb', line 313

def rcvtimeo
  Zsock.rcvtimeo(@zocket)
end

#rcvtimeo=(timeout) ⇒ Object

Note:

-1 means infinite, 0 means nonblocking

Parameters:

  • timeout (Integer) —

    new timeout in milliseconds

See Also:



321
322
323
 
# File 'lib/cztop/zsock_options.rb', line 321

def rcvtimeo=(timeout)
  Zsock.set_rcvtimeo(@zocket, timeout)
end

#reconnect_ivl ⇒ Integer

Returns current value of RECONNECT_IVL.

Returns:

  • (Integer) —

    current value of RECONNECT_IVL



486
487
488
 
# File 'lib/cztop/zsock_options.rb', line 486

def reconnect_ivl
  Zsock.reconnect_ivl(@zocket)
end

#reconnect_ivl=(new_value) ⇒ Object

This defines the number of milliseconds to wait while closing/disconnecting a socket if there are outstanding messages to send.

Default is 0, which means to not wait at all. -1 means to wait indefinitely

Parameters:

  • new_value (Integer) —

    new value for RECONNECT_IVL



499
500
501
 
# File 'lib/cztop/zsock_options.rb', line 499

def reconnect_ivl=(new_value)
  Zsock.set_reconnect_ivl(@zocket, new_value)
end

#router_mandatory=(bool) ⇒ Object

ZMQ_ROUTER_MANDATORY: Accept only routable messages on ROUTER sockets. Default is off.

Parameters:

  • bool (Boolean) —

    whether to raise a SocketError if a message isn’t routable (either if the that peer isn’t connected or its SNDHWM is reached)

See Also:



347
348
349
350
 
# File 'lib/cztop/zsock_options.rb', line 347

def router_mandatory=(bool)
  Zsock.set_router_mandatory(@zocket, bool ? 1 : 0)
  @router_mandatory = bool # NOTE: no way to read this option, so we need to remember
end

#router_mandatory? ⇒ Boolean

Returns whether ZMQ_ROUTER_MANDATORY has been set.

Returns:

  • (Boolean) —

    whether ZMQ_ROUTER_MANDATORY has been set



354
355
356
 
# File 'lib/cztop/zsock_options.rb', line 354

def router_mandatory?
  @router_mandatory
end

#sndhwm ⇒ Integer

Returns the send high water mark.

Returns:

  • (Integer) —

    the send high water mark



111
112
113
 
# File 'lib/cztop/zsock_options.rb', line 111

def sndhwm
  Zsock.sndhwm(@zocket)
end

#sndhwm=(value) ⇒ Object

Parameters:

  • value (Integer) —

    the new send high water mark.



117
118
119
 
# File 'lib/cztop/zsock_options.rb', line 117

def sndhwm=(value)
  Zsock.set_sndhwm(@zocket, value)
end

#sndtimeo ⇒ Integer

Note:

-1 means infinite, 0 means nonblocking

Returns the timeout in milliseconds when sending a message.

Returns:

  • (Integer) —

    the timeout in milliseconds when sending a message

See Also:



329
330
331
 
# File 'lib/cztop/zsock_options.rb', line 329

def sndtimeo
  Zsock.sndtimeo(@zocket)
end

#sndtimeo=(timeout) ⇒ Object

Note:

-1 means infinite, 0 means nonblocking

Parameters:

  • timeout (Integer) —

    new timeout in milliseconds

See Also:



337
338
339
 
# File 'lib/cztop/zsock_options.rb', line 337

def sndtimeo=(timeout)
  Zsock.set_sndtimeo(@zocket, timeout)
end

#tos ⇒ Integer

Returns current value of Type of Service.

Returns:

  • (Integer) —

    current value of Type of Service



377
378
379
 
# File 'lib/cztop/zsock_options.rb', line 377

def tos
  Zsock.tos(@zocket)
end

#tos=(new_value) ⇒ Object

Parameters:

  • new_value (Integer) —

    new value for Type of Service

Raises:

  • (ArgumentError) 


383
384
385
386
387
 
# File 'lib/cztop/zsock_options.rb', line 383

def tos=(new_value)
  raise ArgumentError, 'invalid TOS' unless new_value >= 0

  Zsock.set_tos(@zocket, new_value)
end

#zap_domain ⇒ String

Gets the ZAP domain used for authentication.

Returns:

  • (String)

See Also:



248
249
250
 
# File 'lib/cztop/zsock_options.rb', line 248

def zap_domain
  Zsock.zap_domain(@zocket).read_string
end

#zap_domain=(domain) ⇒ Object

Sets the ZAP domain used for authentication.

Parameters:

  • domain (String) —

    the new ZAP domain

Raises:

  • (ArgumentError) 


255
256
257
258
259
 
# File 'lib/cztop/zsock_options.rb', line 255

def zap_domain=(domain)
  raise ArgumentError, 'domain too long' if domain.bytesize > 254

  Zsock.set_zap_domain(@zocket, domain)
end