zyre 0.1.0

data/lib/zyre/poller.rb

@@ -0,0 +1,16 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'loggability'
+
+require 'zyre' unless defined?( Zyre )
+
+
+#--
+# See also: ext/zyre_ext/poller.c
+class Zyre::Poller
+	extend Loggability
+
+	log_to :zyre
+
+end # class Zyre::Poller

data/lib/zyre/testing.rb

@@ -0,0 +1,296 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'loggability'
+
+require 'zyre' unless defined?( Zyre )
+
+
+# A collection of testing facilities, mostly for RSpec.
+module Zyre::Testing
+
+	# The minimum number of file descriptors required for testing
+	TESTING_FILE_DESCRIPTORS = 4096
+
+
+	# A Factory for generating synthesized ZRE events for testing
+	class EventFactory
+		extend Loggability
+
+
+		# Default config values
+		DEFAULT_HEADERS = {}
+		DEFAULT_GROUP = 'default'
+		DEFAULT_MSG = 'A message.'
+
+		# Default config values to use to construct events
+		DEFAULT_CONFIG = {
+			headers: DEFAULT_HEADERS,
+			group: DEFAULT_GROUP,
+			msg: DEFAULT_MSG,
+		}
+
+		# The network to pretend events are sent over
+		DEFAULT_NETWORK = '10.18.4.0'
+
+
+		# Use the Zyre logger
+		log_to :zyre
+
+
+		### Return the Hash of default config options.
+		def self::default_config
+			return const_get( :DEFAULT_CONFIG )
+		end
+
+
+		### Return the Hash of default headers to use to construct events which have
+		### them.
+		def self::default_headers
+			return const_get( :DEFAULT_HEADERS ).dup
+		end
+
+
+		### Return a random network address that's in the DEFAULT_NETWORK
+		def self::random_network_address
+			last_quad = rand( 1..254 )
+			return DEFAULT_NETWORK.sub( /(?<=\.)0$/, last_quad.to_s )
+		end
+
+
+		### Return a port number that's in the ephemeral range.
+		def self::random_ephemeral_port
+			return rand( 49152 ... 65535)
+		end
+
+
+		### Return a random ZeroMQ-style address that points to an ephemeral port on the
+		### DEFAULT_NETWORK.
+		def self::random_addr
+			return "tcp://%s:%d" % [ self.random_network_address, self.random_ephemeral_port ]
+		end
+
+
+		### Create a new factory that will use the values from the specified +config+
+		### as defaults when constructing events.
+		def initialize( **config )
+			config = self.class.default_config.merge( config )
+			self.log.debug "Setting up a factory with the config: %p" % [ config ]
+
+			@peer_uuid = config[:peer_uuid] || SecureRandom.uuid
+			@peer_name = config[:peer_name] || "S-%s" % [ @peer_uuid[0, 6] ]
+			@peer_addr = config[:peer_addr] || self.class.random_addr
+
+			@headers = config[:headers]
+			@group = config[:group]
+			@msg = config[:msg]
+			self.log.debug( self )
+		end
+
+
+		######
+		public
+		######
+
+		##
+		# The peer_uuid that's assigned to any events created by this factory
+		attr_accessor :peer_uuid
+
+		##
+		# The peer_name that's assigned to any events created by this factory
+		attr_accessor :peer_name
+
+		##
+		# The peer_addr that's assigned to any events created by this factory
+		attr_accessor :peer_addr
+
+		##
+		# The Hash of headers to set on any events created by this factory which have
+		# headers
+		attr_accessor :headers
+
+		##
+		# The name of the group set on any events created by this factory which have a
+		# group
+		attr_accessor :group
+
+		##
+		# The message data to set on any events create by this factory that have a
+		# `msg`.
+		attr_accessor :msg
+
+
+		### Returns a Hash of the configured #headers with stringified keys and values.
+		def normalized_headers
+			return Zyre.normalize_headers( self.headers )
+		end
+
+
+		### Generate an ENTER event.
+		def enter( **overrides )
+			headers = overrides.delete( :headers ) || self.headers
+			uuid = overrides.delete( :peer_uuid ) || self.peer_uuid
+			config = {
+				peer_name: self.peer_name,
+				peer_addr: self.peer_addr,
+				headers: Zyre.normalize_headers( headers )
+			}.merge( overrides )
+
+			return Zyre::Event.synthesize( :enter, uuid, **config )
+		end
+
+
+		### Generate a JOIN event.
+		def join( **overrides )
+			uuid = overrides.delete( :peer_uuid ) || self.peer_uuid
+			config = {
+				peer_name: self.peer_name,
+				group: self.group
+			}.merge( overrides )
+
+			return Zyre::Event.synthesize( :join, uuid, **config )
+		end
+
+
+		### Generate a SHOUT event.
+		def shout( **overrides )
+			uuid = overrides.delete( :peer_uuid ) || self.peer_uuid
+			config = {
+				peer_name: self.peer_name,
+				group: self.group,
+				msg: self.msg
+			}.merge( overrides )
+
+			return Zyre::Event.synthesize( :shout, uuid, **config )
+		end
+
+
+		### Generate a WHISPER event.
+		def whisper( **overrides )
+			uuid = overrides.delete( :peer_uuid ) || self.peer_uuid
+			config = {
+				peer_name: self.peer_name,
+				msg: self.msg
+			}.merge( overrides )
+
+			return Zyre::Event.synthesize( :whisper, uuid, **config )
+		end
+
+
+		### Generate an EVASIVE event.
+		def evasive( **overrides )
+			uuid = overrides.delete( :peer_uuid ) || self.peer_uuid
+			config = {
+				peer_name: self.peer_name
+			}.merge( overrides )
+
+			return Zyre::Event.synthesize( :evasive, uuid, **config )
+		end
+
+
+		### Generate a SILENT event.
+		def silent( **overrides )
+			uuid = overrides.delete( :peer_uuid ) || self.peer_uuid
+			config = {
+				peer_name: self.peer_name
+			}.merge( overrides )
+
+			return Zyre::Event.synthesize( :silent, uuid, **config )
+		end
+
+
+		### Generate a LEAVE event.
+		def leave( **overrides )
+			uuid = overrides.delete( :peer_uuid ) || self.peer_uuid
+			config = {
+				peer_name: self.peer_name,
+				group: self.group
+			}.merge( overrides )
+
+			return Zyre::Event.synthesize( :leave, uuid, **config )
+		end
+
+
+		### Generate an EXIT event.
+		def exit( **overrides )
+			uuid = overrides.delete( :peer_uuid ) || self.peer_uuid
+			config = {
+				peer_name: self.peer_name
+			}.merge( overrides )
+
+			return Zyre::Event.synthesize( :exit, uuid, **config )
+		end
+
+	end # class EventFactory
+
+
+	### Add hooks when the given +context+ has helpers added to it.
+	def self::included( context )
+
+		context.let( :gossip_hub ) { "inproc://gossip-hub-%s" % [ SecureRandom.hex(16) ] }
+
+		context.before( :each ) do
+			@gossip_endpoint = nil
+			@started_zyre_nodes = []
+		end
+
+		context.after( :each ) do
+			@started_zyre_nodes.each( &:stop )
+		end
+
+		super
+	end
+
+
+	###############
+	module_function
+	###############
+
+	### Return a node that's been configured and started.
+	def started_node( name=nil )
+		node = Zyre::Node.new( name )
+		node.endpoint = 'inproc://node-test-%s' % [ SecureRandom.hex(16) ]
+		yield( node ) if block_given?
+
+		if @gossip_endpoint
+			# $stderr.puts "Connecting to %p" % [ @gossip_endpoint ]
+			node.gossip_connect( @gossip_endpoint )
+		else
+			@gossip_endpoint = gossip_hub()
+			# $stderr.puts "Binding to %p" % [ @gossip_endpoint ]
+			node.gossip_bind( @gossip_endpoint )
+			sleep 0.25
+		end
+
+		# $stderr.puts "Starting %p" % [ node ]
+		node.start
+		@started_zyre_nodes << node
+
+		return node
+	end
+
+
+	### Reset file descriptor limit higher for OSes that have low limits, e.g., OSX.
+	### Refs:
+	### - http://wiki.zeromq.org/docs:tuning-zeromq#toc1
+	def check_fdmax
+		current_fdmax, max_fdmax = Process.getrlimit( :NOFILE )
+
+		if max_fdmax < TESTING_FILE_DESCRIPTORS
+			warn <<~END_WARNING
+			>>>
+			>>> Can't set file-descriptor ulimit to #{TESTING_FILE_DESCRIPTORS}. Later specs
+			>>> might fail due to lack of file descriptors.
+			>>>
+			END_WARNING
+		else
+			Process.setrlimit( :NOFILE, TESTING_FILE_DESCRIPTORS ) if
+				current_fdmax < TESTING_FILE_DESCRIPTORS
+		end
+	end
+
+
+
+end # module Zyre::Testing
+

data/spec/observability/instrumentation/zyre_spec.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env rspec -cfd
+
+require_relative '../../spec_helper'
+
+
+RSpec.describe 'Observability::Instrumentation::Zyre', :observability do
+
+	before( :all ) do
+		Observability.install_instrumentation( :zyre )
+	end
+
+	before( :each ) do
+		Observability.observer.sender.enqueued_events.clear
+	end
+
+
+	let( :described_class ) { Observability::Instrumentation::Zyre }
+
+
+	it "is available" do
+		expect( described_class ).to be_available
+	end
+
+
+	it "records the peer ID and message when a whisper is sent" do
+		node1 = started_node()
+		node2 = started_node()
+
+		node1.whisper( node2.uuid, "a peer-to-peer message" )
+
+		events = Observability.observer.sender.find_events( 'zyre.node.whisper' )
+		expect( events.length ).to eq( 1 )
+		expect( events.first[:peer_uuid] ).to eq( node2.uuid )
+		expect( events.first[:message] ).to eq( 'a peer-to-peer message' )
+
+	end
+
+
+	it "records the group and message when a shout is sent" do
+		node1 = started_node()
+		node1.join( 'observer-testing' )
+		node2 = started_node()
+		node2.join( 'observer-testing' )
+
+		node1.wait_for( :JOIN, timeout: 2.0, peer_uuid: node2.uuid )
+
+		node1.shout( 'observer-testing', "a peer-to-peer message" )
+
+		events = Observability.observer.sender.find_events( 'zyre.node.shout' )
+		expect( events.length ).to eq( 1 )
+		expect( events.first[:group] ).to eq( 'observer-testing' )
+		expect( events.first[:message] ).to eq( 'a peer-to-peer message' )
+	end
+
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,62 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+if ENV['COVERAGE'] || ENV['CI']
+	require 'simplecov'
+	if ENV['CI']
+		require 'simplecov-cobertura'
+		SimpleCov.formatter = SimpleCov::Formatter::CoberturaFormatter
+	end
+end
+
+require 'rspec'
+require 'rspec/wait'
+require 'zyre'
+require 'zyre/testing'
+
+require 'securerandom'
+require 'loggability/spechelpers'
+
+
+begin
+	require 'observability'
+	$have_observability = true
+
+	Observability::Sender.configure( type: :testing )
+rescue LoadError => err
+	$have_observability = false
+end
+
+
+### Mock with RSpec
+RSpec.configure do |config|
+	config.expect_with :rspec do |expectations|
+		expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+		expectations.syntax = :expect
+	end
+
+	config.mock_with( :rspec ) do |mock|
+		mock.syntax = :expect
+		mock.verify_partial_doubles = true
+	end
+
+	config.disable_monkey_patching!
+	config.example_status_persistence_file_path = "spec/.status"
+	config.filter_run :focus
+	config.filter_run_excluding :observability unless $have_observability
+	config.filter_run_when_matching :focus
+	config.order = :random
+	config.profile_examples = 5
+	config.run_all_when_everything_filtered = true
+	config.shared_context_metadata_behavior = :apply_to_host_groups
+	# config.warnings = true
+
+	config.before( :suite ) do
+		Zyre::Testing.check_fdmax
+	end
+
+	config.include( Zyre::Testing )
+	config.include( Loggability::SpecHelpers )
+end
+
+

data/spec/zyre/event_spec.rb

@@ -0,0 +1,141 @@
+#!/usr/bin/env rspec -cfd
+
+require_relative '../spec_helper'
+
+require 'securerandom'
+require 'zyre'
+
+
+RSpec.describe( Zyre::Event ) do
+
+	describe "concrete event classes" do
+
+		it "can look up subtypes by upcased String name" do
+			expect( described_class.type_by_name('ENTER') ).to eq( described_class::Enter )
+			expect( described_class.type_by_name('EVASIVE') ).to eq( described_class::Evasive )
+			expect( described_class.type_by_name('SILENT') ).to eq( described_class::Silent )
+			expect( described_class.type_by_name('EXIT') ).to eq( described_class::Exit )
+			expect( described_class.type_by_name('JOIN') ).to eq( described_class::Join )
+			expect( described_class.type_by_name('LEAVE') ).to eq( described_class::Leave )
+			expect( described_class.type_by_name('WHISPER') ).to eq( described_class::Whisper )
+			expect( described_class.type_by_name('SHOUT') ).to eq( described_class::Shout )
+		end
+
+
+		it "can look up subtypes by downcased String name" do
+			expect( described_class.type_by_name('enter') ).to eq( described_class::Enter )
+			expect( described_class.type_by_name('evasive') ).to eq( described_class::Evasive )
+			expect( described_class.type_by_name('silent') ).to eq( described_class::Silent )
+			expect( described_class.type_by_name('exit') ).to eq( described_class::Exit )
+			expect( described_class.type_by_name('join') ).to eq( described_class::Join )
+			expect( described_class.type_by_name('leave') ).to eq( described_class::Leave )
+			expect( described_class.type_by_name('whisper') ).to eq( described_class::Whisper )
+			expect( described_class.type_by_name('shout') ).to eq( described_class::Shout )
+		end
+
+
+		it "can look up subtypes by upcased Symbol name" do
+			expect( described_class.type_by_name(:Enter) ).to eq( described_class::Enter )
+			expect( described_class.type_by_name(:Evasive) ).to eq( described_class::Evasive )
+			expect( described_class.type_by_name(:Silent) ).to eq( described_class::Silent )
+			expect( described_class.type_by_name(:Exit) ).to eq( described_class::Exit )
+			expect( described_class.type_by_name(:Join) ).to eq( described_class::Join )
+			expect( described_class.type_by_name(:Leave) ).to eq( described_class::Leave )
+			expect( described_class.type_by_name(:Whisper) ).to eq( described_class::Whisper )
+			expect( described_class.type_by_name(:Shout) ).to eq( described_class::Shout )
+		end
+
+
+		it "can look up subtypes by downcased Symbol name" do
+			expect( described_class.type_by_name(:enter) ).to eq( described_class::Enter )
+			expect( described_class.type_by_name(:evasive) ).to eq( described_class::Evasive )
+			expect( described_class.type_by_name(:silent) ).to eq( described_class::Silent )
+			expect( described_class.type_by_name(:exit) ).to eq( described_class::Exit )
+			expect( described_class.type_by_name(:join) ).to eq( described_class::Join )
+			expect( described_class.type_by_name(:leave) ).to eq( described_class::Leave )
+			expect( described_class.type_by_name(:whisper) ).to eq( described_class::Whisper )
+			expect( described_class.type_by_name(:shout) ).to eq( described_class::Shout )
+		end
+
+
+		it "can return its type as a String" do
+			expect( described_class.type_by_name(:enter).type_name ).to eq( 'ENTER' )
+			expect( described_class.type_by_name(:evasive).type_name ).to eq( 'EVASIVE' )
+			expect( described_class.type_by_name(:silent).type_name ).to eq( 'SILENT' )
+			expect( described_class.type_by_name(:exit).type_name ).to eq( 'EXIT' )
+			expect( described_class.type_by_name(:join).type_name ).to eq( 'JOIN' )
+			expect( described_class.type_by_name(:leave).type_name ).to eq( 'LEAVE' )
+			expect( described_class.type_by_name(:whisper).type_name ).to eq( 'WHISPER' )
+			expect( described_class.type_by_name(:shout).type_name ).to eq( 'SHOUT' )
+		end
+
+
+		it "returns nil for non-existent subtypes" do
+			expect( described_class.type_by_name(:boom) ).to be_nil
+		end
+
+	end
+
+
+	describe "matching API" do
+
+		it "matches on a single criterion" do
+			node1 = started_node()
+			node1.join( 'matching-test' )
+
+			node2 = started_node()
+			node2.join( 'matching-test' )
+
+			event = node1.wait_for( :JOIN )
+
+			expect( event ).to match( peer_uuid: node2.uuid )
+			expect( event ).not_to match( peer_uuid: node1.uuid )
+		end
+
+
+		it "matches on multiple criterion" do
+			node1 = started_node( 'badger-2' )
+			node1.join( 'matching-test2' )
+
+			node2 = started_node( 'badger-6' )
+			node2.join( 'matching-test2' )
+
+			event = node1.wait_for( :JOIN )
+
+			expect( event ).to match( peer_uuid: node2.uuid, peer_name: 'badger-6' )
+			expect( event ).not_to match( peer_uuid: node2.uuid, peer_name: 'badger-2' )
+		end
+
+
+		it "matches Regexp patterns as values"
+
+	end
+
+
+	describe "synthesis API" do
+
+		let( :peer_uuid ) { '8D9B6F67-2B40-4E56-B352-39029045B568' }
+
+
+		it "can generate events without a node" do
+			result = described_class.synthesize( :ENTER,
+				peer_uuid, peer_name: 'node1', peer_addr: 'in-proc:/synthesized' )
+
+			expect( result ).to be_a( described_class::Enter )
+			expect( result.peer_uuid ).to eq( peer_uuid )
+			expect( result.peer_name ).to eq( 'node1' )
+			expect( result.peer_addr ).to eq( 'in-proc:/synthesized' )
+		end
+
+
+		it "defaults its peer_name to S- + six characters of the peer_uuid" do
+			result = described_class.synthesize( :ENTER,
+				peer_uuid, peer_addr: 'in-proc:/synthesized' )
+
+			expect( result.peer_name ).to eq( 'S-' + peer_uuid[0, 6] )
+		end
+
+	end
+
+end
+