zyre 0.1.0

data/lib/observability/instrumentation/zyre.rb

@@ -0,0 +1,52 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'observability'
+require 'observability/instrumentation' unless defined?( Observability::Instrumentation )
+
+
+# Instrumentation for the Zyre library
+# Refs:
+# - https://github.com/zeromq/zyre
+# - https://gitlab.com/ravngroup/open-source/ruby-zyre
+module Observability::Instrumentation::Zyre
+	extend Observability::Instrumentation
+
+	depends_on 'Zyre'
+
+
+	when_installed( 'Zyre::Node' ) do
+		Zyre::Node.extend( Observability )
+		Zyre::Node.observe_class_method( :new )
+		Zyre::Node.observe_method( :port= )
+		Zyre::Node.observe_method( :evasive_timeout= )
+		Zyre::Node.observe_method( :interface= )
+		Zyre::Node.observe_method( :endpoint= )
+		Zyre::Node.observe_method( :set_header )
+		Zyre::Node.observe_method( :start )
+		Zyre::Node.observe_method( :stop )
+		Zyre::Node.observe_method( :join )
+		Zyre::Node.observe_method( :leave )
+		Zyre::Node.observe_method( :recv )
+		Zyre::Node.observe_method( :whisper, &self.method(:observe_whisper) )
+		Zyre::Node.observe_method( :shout, &self.method(:observe_shout) )
+	end
+
+
+	###############
+	module_function
+	###############
+
+	### Observer callback for the #whisper method.
+	def observe_whisper( peer_uuid, msg )
+		Observability.observer.add( peer_uuid: peer_uuid, message: msg )
+	end
+
+
+	### Observer callback for the #shout method.
+	def observe_shout( group, msg )
+		Observability.observer.add( group: group, message: msg )
+	end
+
+end # module Observability::Instrumentation::Zyre
+

data/lib/zyre.rb

@@ -0,0 +1,53 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'loggability'
+
+require_relative 'zyre_ext'
+
+
+# A binding to libzyre
+module Zyre
+	extend Loggability
+
+
+	# Gem version (semver)
+	VERSION = '0.1.0'
+
+
+	# Set up a logger for Zyre classes
+	log_as :zyre
+
+
+	### Wait on one or more +nodes+ to become readable, returning the first one that does
+	### or +nil+ if the +timeout+ is zero or greater and at least that many seconds elapse.
+	### Specify a +timeout+ of -1 to wait indefinitely. The timeout is in floating-point
+	### seconds.
+	###
+	### Raises an Interrupt if the call is interrupted or the ZMQ context is destroyed.
+	def self::wait( *nodes, timeout: -1 )
+		nodes = nodes.flatten
+		return nil if nodes.empty?
+		return self.wait2( nodes, timeout )
+	end
+
+
+	### If the given +key+ is a Symbol, transform it into an RFC822-style header key. If
+	### it's not a Symbol, returns it unchanged.
+	def self::transform_header_key( key )
+		if key.is_a?( Symbol )
+			key = key.to_s.gsub( /_/, '-' ).capitalize
+		end
+
+		return key
+	end
+
+
+	### Transform the given +headers+ hash into a form that can be passed to Zyre.
+	def self::normalize_headers( headers )
+		return headers.
+			transform_keys {|k| Zyre.transform_header_key(k) }.
+			transform_values {|v| v.to_s.encode('us-ascii') }
+	end
+
+end # module Zyre

data/lib/zyre/event.rb

@@ -0,0 +1,82 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'loggability'
+
+require 'zyre' unless defined?( Zyre )
+
+
+#--
+# See also: ext/zyre_ext/event.c
+class Zyre::Event
+	extend Loggability
+
+
+	# Send logging to the 'zyre' logger
+	log_to :zyre
+
+	# Don't allow direct instantiation
+	private_class_method :new
+
+
+	# Autoload concrete event types
+	autoload :Enter, 'zyre/event/enter'
+	autoload :Evasive, 'zyre/event/evasive'
+	autoload :Exit, 'zyre/event/exit'
+	autoload :Join, 'zyre/event/join'
+	autoload :Leave, 'zyre/event/leave'
+	autoload :Shout, 'zyre/event/shout'
+	autoload :Silent, 'zyre/event/silent'
+	autoload :Stop, 'zyre/event/stop'
+	autoload :Whisper, 'zyre/event/whisper'
+
+
+	### Given the +name+ of an event type, return the Zyre::Event subclass that
+	### corresponds to it.
+	def self::type_by_name( name )
+		capname = name.to_s.capitalize
+		classobj = self.const_get( capname )
+	rescue NameError => err
+		self.log.debug( err )
+		return nil
+	end
+
+
+	### Return the event type as Zyre refers to it.
+	def self::type_name
+		return self.name[ /.*::(\w+)/, 1 ].upcase
+	end
+
+
+	# Some convenience aliases
+	alias_method :message, :msg
+
+
+	### Returns +true+ if the specified +criteria+ match attribute of the event.
+	def match( criteria )
+		return criteria.all? do |key, val|
+			self.respond_to?( key ) && self.public_send( key ) == val
+		end
+	end
+
+
+	### Return a string describing this event, suitable for debugging.
+	def inspect
+		details = self.inspect_details
+		details = ' ' + details unless details.start_with?( ' ' )
+
+		return "#<%p:%#016x%s>" % [
+			self.class,
+			self.object_id,
+			details,
+		]
+	end
+
+
+	### Provide the details of the inspect message. Defaults to an empty string.
+	def inspect_details
+		return ''
+	end
+
+end # class Zyre::Event
+

data/lib/zyre/event/enter.rb

@@ -0,0 +1,19 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'zyre/event' unless defined?( Zyre::Event )
+
+
+class Zyre::Event::Enter < Zyre::Event
+
+	### Provide the details of the inspect message.
+	def inspect_details
+		return "%s (%s at %s) has entered the network: %p" % [
+			self.peer_uuid,
+			self.peer_name,
+			self.peer_addr,
+			self.headers,
+		]
+	end
+
+end # class Zyre::Event::Enter

data/lib/zyre/event/evasive.rb

@@ -0,0 +1,17 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'zyre/event' unless defined?( Zyre::Event )
+
+
+class Zyre::Event::Evasive < Zyre::Event
+
+	### Provide the details of the inspect message.
+	def inspect_details
+		return "%s (%s) is being evasive and will be pinged manually" % [
+			self.peer_uuid,
+			self.peer_name,
+		]
+	end
+
+end # class Zyre::Event::Evasive

data/lib/zyre/event/exit.rb

@@ -0,0 +1,18 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'zyre/event' unless defined?( Zyre::Event )
+
+
+class Zyre::Event::Exit < Zyre::Event
+
+	### Provide the details of the inspect message.
+	def inspect_details
+		return "%s (%s) has left the network" % [
+			self.peer_uuid,
+			self.peer_name,
+			self.headers,
+		]
+	end
+
+end # class Zyre::Event::Exit

data/lib/zyre/event/join.rb

@@ -0,0 +1,18 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'zyre/event' unless defined?( Zyre::Event )
+
+
+class Zyre::Event::Join < Zyre::Event
+
+	### Provide the details of the inspect message.
+	def inspect_details
+		return "%s (%s) joined «%s»" % [
+			self.peer_uuid,
+			self.peer_name,
+			self.group
+		]
+	end
+
+end # class Zyre::Event::Join

data/lib/zyre/event/leave.rb

@@ -0,0 +1,18 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'zyre/event' unless defined?( Zyre::Event )
+
+
+class Zyre::Event::Leave < Zyre::Event
+
+	### Provide the details of the inspect message.
+	def inspect_details
+		return "%s (%s) left «%s»" % [
+			self.peer_uuid,
+			self.peer_name,
+			self.group
+		]
+	end
+
+end # class Zyre::Event::Leave

data/lib/zyre/event/shout.rb

@@ -0,0 +1,19 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'zyre/event' unless defined?( Zyre::Event )
+
+
+class Zyre::Event::Shout < Zyre::Event
+
+	### Provide the details of the inspect message.
+	def inspect_details
+		return "shout from %s (%s) on «%s»: %p" % [
+			self.peer_uuid,
+			self.peer_name,
+			self.group,
+			self.msg,
+		]
+	end
+
+end # class Zyre::Event::Shout

data/lib/zyre/event/silent.rb

@@ -0,0 +1,18 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'zyre/event' unless defined?( Zyre::Event )
+
+
+class Zyre::Event::Silent < Zyre::Event
+
+	### Provide the details of the inspect message.
+	def inspect_details
+		return "%s (%s) isn't responding to pings" % [
+			self.peer_uuid,
+			self.peer_name,
+			self.headers,
+		]
+	end
+
+end # class Zyre::Event::Silent

data/lib/zyre/event/stop.rb

@@ -0,0 +1,9 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'zyre/event' unless defined?( Zyre::Event )
+
+
+class Zyre::Event::Stop < Zyre::Event
+
+end # class Zyre::Event::Stop

data/lib/zyre/event/whisper.rb

@@ -0,0 +1,18 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'zyre/event' unless defined?( Zyre::Event )
+
+
+class Zyre::Event::Whisper < Zyre::Event
+
+	### Provide the details of the inspect message.
+	def inspect_details
+		return "whisper from %s (%s): %p" % [
+			self.peer_uuid,
+			self.peer_name,
+			self.msg,
+		]
+	end
+
+end # class Zyre::Event::Whisper

data/lib/zyre/node.rb

@@ -0,0 +1,147 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'loggability'
+
+require 'zyre' unless defined?( Zyre )
+
+
+#--
+# See also: ext/zyre_ext/node.c
+class Zyre::Node
+	extend Loggability
+
+
+	# Use the Zyre logger
+	log_to :zyre
+
+
+
+	### Yield each incoming event to the block. If no block is given, returns an
+	### enumerator instead.
+	def each_event( &block )
+		iter = self.make_event_enum
+		return iter.each( &block ) if block
+		return iter
+	end
+	alias_method :each, :each_event
+
+
+	### Wait for an event of a given +event_type+ (e.g., :JOIN) and matching any
+	### optional +criteria+, returning the event if a matching one was seen. If a
+	### +timeout+ is given and the event hasn't been seen after the +timeout+
+	### seconds have elapsed, return +nil+. If a block is given, call the block
+	### for each (non-matching) event that arrives in the interim. Note that the
+	### execution time of the block is counted in the timeout.
+	def wait_for( event_type, timeout: nil, **criteria, &block )
+		expected_type = Zyre::Event.type_by_name( event_type ) or
+			raise ArgumentError, "no such event type %p" % [ event_type ]
+
+		if timeout
+			return self.wait_for_with_timeout( expected_type, timeout, **criteria, &block )
+		else
+			return self.wait_for_indefinitely( expected_type, **criteria, &block )
+		end
+	end
+
+
+	### Set headers from the given +hash+. Convenience wrapper for #set_header. Symbol
+	### keys will have `_` characters converted to `-` and will be capitalized when
+	### converted into Strings. E.g.,
+	###
+	###   headers = { content_type: 'application/json' }
+	###
+	### will call:
+	###
+	###   .set_header( 'Content-type', 'application/json' )
+	###
+	def headers=( hash )
+		hash.each do |key, val|
+			key = Zyre.transform_header_key( key )
+			self.set_header( key.to_s, val.to_s )
+		end
+	end
+
+
+	### Return a string describing the node suitable for debugging.
+	def inspect
+		return "#<%p:%#016x %s[%s]>" % [
+			self.class,
+			self.object_id,
+			self.name,
+			self.uuid,
+		]
+	end
+
+
+
+	#########
+	protected
+	#########
+
+	### Create an Enumerator that yields each event as it comes in. If there is
+	### no event to read, block until there is one.
+	def make_event_enum
+		return Enumerator.new do |yielder|
+			while event = self.recv
+				yielder.yield( event )
+			end
+		end
+	end
+
+
+	### Wait for an event of the given +event_class+ and +criteria+, returning it when it
+	### arrives. Blocks indefinitely until it arrives or interrupted.
+	def wait_for_indefinitely( event_class, **criteria, &block )
+		poller = Zyre::Poller.new( self )
+		while poller.wait
+			event = self.recv
+			if event.kind_of?( event_class ) && event.match( criteria )
+				return event
+			else
+				block.call( event ) if block
+			end
+		end
+	end
+
+
+	### Wait for an event of the given +event_class+ and +criteria+, returning it if
+	### it arrives before +timeout+ seconds elapses. If the timeout elapses first,
+	### return +nil+.
+	def wait_for_with_timeout( event_class, timeout, **criteria, &block )
+		start_time = get_monotime()
+		timeout_at = start_time + timeout
+
+		poller = Zyre::Poller.new( self )
+
+		timeout = timeout_at - get_monotime()
+		while timeout > 0
+			if poller.wait( timeout )
+				event = self.recv
+				if event.kind_of?( event_class ) && event.match( criteria )
+					return event
+				else
+					block.call( event ) if block
+				end
+			else
+				break
+			end
+
+			timeout = timeout_at - get_monotime()
+		end
+
+		return nil
+
+	end
+
+
+	#######
+	private
+	#######
+
+	### Return the monotonic time.
+	def get_monotime
+		return Process.clock_gettime( Process::CLOCK_MONOTONIC )
+	end
+
+end # class Zyre::Node