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



69
70
71
72
73
74
75
76
 
# File 'lib/cztop/zsock_options.rb', line 69

def [](option_name)
  # 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?

  __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



84
85
86
87
88
89
 
# File 'lib/cztop/zsock_options.rb', line 84

def []=(option_name, new_value)
  meth = public_methods.find { |m| m =~ /^#{option_name}=$/i }
  raise NoMethodError, option_name if meth.nil?

  __send__(meth, new_value)
end

#CURVE_key(key_name) ⇒ String? (private)

Get one of the CURVE keys.

Parameters:

  • key_name (Symbol) —

    something like :curve_serverkey

Returns:

  • (String, nil) —

    key, if CURVE is supported and active, or nil



167
168
169
170
171
172
173
174
 
# File 'lib/cztop/zsock_options.rb', line 167

def CURVE_key(key_name)
  return nil if mechanism != :CURVE

  ptr = Zsock.__send__(key_name, @zocket)
  return nil if ptr.null?

  ptr.read_string
end

#CURVE_publickey ⇒ String?

Returns:

  • (String) —

    Z85 encoded public key set

  • (nil) —

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



205
206
207
 
# File 'lib/cztop/zsock_options.rb', line 205

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



197
198
199
 
# File 'lib/cztop/zsock_options.rb', line 197

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) 


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

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



143
144
145
 
# File 'lib/cztop/zsock_options.rb', line 143

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



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

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



181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/cztop/zsock_options.rb', line 181

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:



465
466
467
 
# File 'lib/cztop/zsock_options.rb', line 465

def events
  Zsock.events(@zocket)
end

#fd ⇒ Integer

Returns socket file descriptor.

Returns:

  • (Integer) —

    socket file descriptor



458
459
460
 
# File 'lib/cztop/zsock_options.rb', line 458

def fd
  Zsock.fd(@zocket)
end

#heartbeat_ivl ⇒ Integer

Returns current value of Heartbeat IVL.

Returns:

  • (Integer) —

    current value of Heartbeat IVL



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

def heartbeat_ivl
  Zsock.heartbeat_ivl(@zocket)
end

#heartbeat_ivl=(new_value) ⇒ Object

Parameters:

  • new_value (Integer) —

    new value for Heartbeat IVL

Raises:

  • (ArgumentError) 


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

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



408
409
410
 
# File 'lib/cztop/zsock_options.rb', line 408

def heartbeat_timeout
  Zsock.heartbeat_timeout(@zocket)
end

#heartbeat_timeout=(new_value) ⇒ Object

Parameters:

  • new_value (Integer) —

    new value for Heartbeat Timeout

Raises:

  • (ArgumentError) 


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

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



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

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) 


399
400
401
402
403
404
 
# File 'lib/cztop/zsock_options.rb', line 399

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



345
346
347
 
# File 'lib/cztop/zsock_options.rb', line 345

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

#identity=(identity) ⇒ Object

Parameters:

  • identity (String) —

    new socket identity

Raises:

  • (ArgumentError) —

    if identity is invalid



352
353
354
355
356
357
358
 
# File 'lib/cztop/zsock_options.rb', line 352

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



452
453
454
 
# File 'lib/cztop/zsock_options.rb', line 452

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



441
442
443
 
# File 'lib/cztop/zsock_options.rb', line 441

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

#linger ⇒ Integer

Returns current value of LINGER.

Returns:

  • (Integer) —

    current value of LINGER



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

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



435
436
437
 
# File 'lib/cztop/zsock_options.rb', line 435

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



134
135
136
137
138
139
 
# File 'lib/cztop/zsock_options.rb', line 134

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



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

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



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

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) 


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

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



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

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



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

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



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

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



108
109
110
 
# File 'lib/cztop/zsock_options.rb', line 108

def rcvhwm
  Zsock.rcvhwm(@zocket)
end

#rcvhwm=(value) ⇒ Object

Parameters:

  • value (Integer) —

    the new receive high water mark



114
115
116
 
# File 'lib/cztop/zsock_options.rb', line 114

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:



298
299
300
 
# File 'lib/cztop/zsock_options.rb', line 298

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:



306
307
308
 
# File 'lib/cztop/zsock_options.rb', line 306

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



471
472
473
 
# File 'lib/cztop/zsock_options.rb', line 471

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



484
485
486
 
# File 'lib/cztop/zsock_options.rb', line 484

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:



332
333
334
335
 
# File 'lib/cztop/zsock_options.rb', line 332

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



339
340
341
 
# File 'lib/cztop/zsock_options.rb', line 339

def router_mandatory?
  @router_mandatory
end

#sndhwm ⇒ Integer

Returns the send high water mark.

Returns:

  • (Integer) —

    the send high water mark



96
97
98
 
# File 'lib/cztop/zsock_options.rb', line 96

def sndhwm
  Zsock.sndhwm(@zocket)
end

#sndhwm=(value) ⇒ Object

Parameters:

  • value (Integer) —

    the new send high water mark.



102
103
104
 
# File 'lib/cztop/zsock_options.rb', line 102

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:



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

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:



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

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



362
363
364
 
# File 'lib/cztop/zsock_options.rb', line 362

def tos
  Zsock.tos(@zocket)
end

#tos=(new_value) ⇒ Object

Parameters:

  • new_value (Integer) —

    new value for Type of Service

Raises:

  • (ArgumentError) 


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

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:



233
234
235
 
# File 'lib/cztop/zsock_options.rb', line 233

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) 


240
241
242
243
244
 
# File 'lib/cztop/zsock_options.rb', line 240

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

  Zsock.set_zap_domain(@zocket, domain)
end