zyre 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5946a8a32c3932017f3c6fc60d6a54e3a2196a5e193a769975a1c4b47cbb405e
-  data.tar.gz: 5e51339b1fbc508dd0de7f3abc921aa7c2912cc243fda3a059d9057648c6acb9
+  metadata.gz: bc86fa098a17006c4e470186fb0f98910f0d443ef62351f18aa2c1f8962c9bcc
+  data.tar.gz: aac8d6fa401e07df184f74fa0f9ef4e31e46bb91997b5af9eafe71f8048460c8
 SHA512:
-  metadata.gz: 5177153a30ea6f2f28ebfb7372e3055a51ec793ea5a5bd51c3afde8b41ba1909b88a5daae334ab5fd52db9858e10b1f0184e7a4f566f7f8ee7240311748e1ab4
-  data.tar.gz: 61057878f14e360a57bf233ee5649dec9659686090d20f72461fcb955e387fa204e1afdcbadb8b5112e517a64547a27df5aa18eeea2706a9d65221724fbc89a5
+  metadata.gz: 6d44fcc7a7c5b63a6e471957d5361ea9595b34b2d35f458f61cb6ee5e19db8f624e5e857203fac49992dab6160937e57571069057894ec2d8e2c51801744e88f
+  data.tar.gz: d5be9dc4fd921a16679850d505bb8d81ad1bcd3029ad7b1ec84277957653c345f0ebdcedf3e7a9139111a7320fccdc797f1a316ff74c2860b3b56c098ffc546f

data/History.md

@@ -1,6 +1,13 @@
 # Release History for zyre
 
 ---
+## v0.2.0 [2020-11-09] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Add multipart messaging.
+- Allow positional args for testing factory SHOUTs and WHISPERs
+
 
 ## v0.1.0 [2020-11-05] Michael Granger <ged@faeriemud.org>
 

data/README.md

@@ -21,20 +21,84 @@ reliable group messaging over local area networks, an implementation of [the Zer
 
 ### Examples
 
-    # Join the Zyre network on the network associated with the given interface
-    # and dump events from the 'global' group to stderr.
+Zyre is a P2P library which has two modes: pub/sub and direct messaging. To use it, you create a node, optionally join some groups (subscribing), and start it. Then you can send broadcast messages to all other nodes in a group, or direct messages to a particular node.
+
+This example joins the Zyre network and dumps messages it sees in the 'global' group to stderr:
+
     node = Zyre::Node.new
-    node.interface = 'igb0'
+    node.join( 'global' )
     node.start
     
-    while event = node.recv
+    node.each_event do |event|
       event.print
     end
 
+To send a direct message to a different node you need to know its `UUID`. There are number of ways to discover this:
+
+    # The UUIDs of all connected peers
+    node.peers
+    # The UUIDs of all the peers which have joined the `general` group
+    node.peers_by_group( 'general' )
+    # The UUID of the peer that sent the event
+    received_event.peer_uuid
+
+You read events from the network with the Zyre::Node#recv method, but it blocks until an event arrives:
+
+    event = node.recv
+
+You can also iterate over arriving events:
+
+    node.each do |event|
+        ...
+    end
+
+or use Zyre::Node#each as an Enumerator:
+
+    five_events = node.each_event.take( 5 )
+
+You can also wait for a certain type of event:
+
+    event = node.wait_for( :SHOUT )
+
+and time out if it doesn't arrive within a certain length of time:
+
+    event = node.wait_for( :ENTER, timeout: 2.0 ) or
+        raise "No one else on the network!"
+
+You can join a group with Zyre::Node#join:
+
+    node.join( 'alerts' )
+
+and you can detect other nodes joining one of your groups by looking for JOIN events (Zyre::Event::Join objects):
+
+    node.wait_for( :JOIN )
+
+You can publish a message to all nodes in a group with Zyre::Node#shout:
+
+    node.shout( "group1", "This is a message." )
+
+and read it:
+
+    event = other_node.recv
+    event.is_multipart?  # => false
+    event.msg            # => "This is a message."
+    event.multipart_msg  # => ["This is a message."]
+
+
+Or publish a message with multiple parts:
+
+    node.shout( "group1", 'message.type', "This is a message." )
+
+and read it:
+
+    event = other_node.recv
+    event.is_multipart?  # => true
+    event.msg            # => "message.type"
+    event.multipart_msg  # => ["message.type", "This is a message."]
+
 
 ### To-Do
 
-* Implement Zyre::Node#peer_groups and Zyre::Node#peer_address
 * Implement the draft API methods on Zyre::Node
 * Hook up logging via `zsys_set_logsender`
 * Add richer matching to Zyre::Event#match.

data/ext/zyre_ext/event.c

@@ -121,6 +121,7 @@ rzyre_copy_string( VALUE string )
 	const char *c_string = StringValueCStr( string );
 	char *copy = (char *) zmalloc( strnlen(c_string, BUFSIZ) + 1 );
 
+	rzyre_log( "debug", "Copying string `%s`.", c_string );
 	assert( copy );
 	stpncpy( copy, c_string, strnlen(c_string, BUFSIZ) + 1 );
 
@@ -134,6 +135,7 @@ rzyre_copy_required_string( VALUE string, const char *field_name )
 	if ( RB_TYPE_P(string, T_UNDEF) ) {
 		rb_raise( rb_eArgError, "missing required field :%s", field_name );
 	} else {
+		rzyre_log( "debug", "Required field %s is defined.", field_name );
 		return rzyre_copy_string( string );
 	}
 }
@@ -182,27 +184,37 @@ static VALUE
 rzyre_event_s_synthesize( int argc, VALUE *argv, VALUE klass )
 {
 	VALUE rval, event_type, peer_uuid, kwargs, event_class;
-	static VALUE kwvals[5];
+	VALUE kwvals[5] = { Qundef, Qundef, Qundef, Qundef, Qundef };
 	static ID keyword_ids[5];
 	zyre_event_t *ptr = NULL;
 
 	// Parse the arguments + keyword arguments
 	if ( !keyword_ids[0] ) {
-		CONST_ID( keyword_ids[0], "peer_name");
-		CONST_ID( keyword_ids[1], "headers");
-		CONST_ID( keyword_ids[2], "peer_addr");
-		CONST_ID( keyword_ids[3], "group");
-		CONST_ID( keyword_ids[4], "msg");
+		CONST_ID( keyword_ids[0], "peer_name" );
+		CONST_ID( keyword_ids[1], "headers" );
+		CONST_ID( keyword_ids[2], "peer_addr" );
+		CONST_ID( keyword_ids[3], "group" );
+		CONST_ID( keyword_ids[4], "msg" );
 	}
 
+	rzyre_log( "debug", "Scanning %d synthesize args.", argc );
 	rb_scan_args( argc, argv, "2:", &event_type, &peer_uuid, &kwargs );
 	if ( RTEST(kwargs) ) {
+		rzyre_log( "debug", "  scanning keyword args: %s", RSTRING_PTR(rb_inspect(kwargs)) );
 		rb_get_kwargs( kwargs, keyword_ids, 0, 5, kwvals );
 	}
 
 	// Translate the event type argument into the appropriate class and instantiate it
+	rzyre_log( "debug", "Creating an instance of a %s event.", RSTRING_PTR(rb_inspect(event_type )) );
 	event_class = rb_funcall( klass, rb_intern("type_by_name"), 1, event_type );
-	event_type = rb_funcall( event_class, rb_intern("type_name"), 0 );
+
+	if ( RTEST(event_class) ) {
+		event_type = rb_funcall( event_class, rb_intern("type_name"), 0 );
+	} else {
+		rb_raise( rb_eArgError, "don't know how to create %s events",
+			RSTRING_PTR(rb_inspect(event_type)) );
+	}
+
 	rval = rb_class_new_instance( 0, NULL, event_class );
 
 	// Set up the zyre_event memory for the object
@@ -213,6 +225,7 @@ rzyre_event_s_synthesize( int argc, VALUE *argv, VALUE klass )
 	ptr->peer_uuid = rzyre_copy_string( peer_uuid );
 
 	// Set the peer_name or default it if it wasn't specified
+	rzyre_log( "debug", "Starting type-specific setup." );
 	if ( !RB_TYPE_P(kwvals[0], T_UNDEF) ) {
 		ptr->peer_name = rzyre_copy_string( kwvals[0] );
 	} else {
@@ -234,27 +247,25 @@ rzyre_event_s_synthesize( int argc, VALUE *argv, VALUE klass )
 		ptr->group = rzyre_copy_required_string( kwvals[3], "group" );
 	}
 	else if ( streq(ptr->type, "WHISPER") ) {
-		const char *msg_str = rzyre_copy_required_string( kwvals[4], "msg" );
-		zmsg_t *msg = zmsg_new();
+		if ( RB_TYPE_P(kwvals[4], T_UNDEF) )
+			rb_raise( rb_eArgError, "missing required field :msg" );
 
-		zmsg_addstr( msg, msg_str );
-		ptr->msg = msg;
-		msg = NULL;
+		rzyre_log( "debug", "Making a WHISPER zmsg from the :msg value: %s",
+			RSTRING_PTR(rb_inspect(kwvals[4])) );
+		ptr->msg = rzyre_make_zmsg_from( kwvals[4] );
 	}
 	else if ( streq(ptr->type, "SHOUT") ) {
-		const char *msg_str = rzyre_copy_required_string( kwvals[4], "msg" );
-		zmsg_t *msg = zmsg_new();
-
-		zmsg_addstr( msg, msg_str );
+		if ( RB_TYPE_P(kwvals[4], T_UNDEF) )
+			rb_raise( rb_eArgError, "missing required field :msg" );
 
+		rzyre_log( "debug", "Making a SHOUT zmsg from the :msg value: %s",
+			RSTRING_PTR(rb_inspect(kwvals[4])) );
 		ptr->group = rzyre_copy_required_string( kwvals[3], "group" );
-		ptr->msg = msg;
-		msg = NULL;
-	}
-	else if ( streq(ptr->type, "LEADER") ) {
-		ptr->group = rzyre_copy_required_string( kwvals[3], "group" );
+		ptr->msg = rzyre_make_zmsg_from( kwvals[4] );
 	}
 
+	rzyre_log_obj( rval, "debug", "Synthesized a %s event.", ptr->type );
+
 	return rval;
 }
 
@@ -397,9 +408,32 @@ rzyre_event_group( VALUE self ) {
 
 /*
  * call-seq:
- *    event.event_msg
+ *    event.msg_size   -> int
+ *
+ * Return the number of frames present in the event's message (if it has one). Returns
+ * nil if there is no message.
+ *
+ */
+static VALUE
+rzyre_event_msg_size( VALUE self )
+{
+	zyre_event_t *ptr = rzyre_get_event( self );
+	zmsg_t *msg = zyre_event_msg( ptr );
+	VALUE rval = Qnil;
+
+	if ( msg ) {
+		rval = INT2FIX( zmsg_size(msg) );
+	}
+
+	return rval;
+}
+
+
+/*
+ * call-seq:
+ *    event.msg
  *
- * Returns the incoming message payload.
+ * Returns the data from the first frame of the message from the receiver.
  */
 static VALUE
 rzyre_event_msg( VALUE self ) {
@@ -407,12 +441,11 @@ rzyre_event_msg( VALUE self ) {
 	zmsg_t *msg = zyre_event_msg( ptr );
 	VALUE rval = Qnil;
 
-	// :TODO: Support multipart messages when Zyre does.
 	if ( msg ) {
 		zframe_t *frame = zmsg_first( msg );
 		char *str = zframe_strdup( frame );
 
-		rval = rb_utf8_str_new( str, zframe_size(frame) );
+		rval = rb_enc_str_new( str, zframe_size(frame), rb_ascii8bit_encoding() );
 		rb_obj_freeze( rval );
 
 		free( str );
@@ -422,6 +455,37 @@ rzyre_event_msg( VALUE self ) {
 }
 
 
+/*
+ * call-seq:
+ *    event.multipart_msg
+ *
+ * Returns the data from every frame of the message from the receiver.
+ */
+static VALUE
+rzyre_event_multipart_msg( VALUE self ) {
+	zyre_event_t *ptr = rzyre_get_event( self );
+	zmsg_t *msg = zyre_event_msg( ptr );
+	VALUE rval = rb_ary_new();
+
+	if ( msg ) {
+		zframe_t *frame = zmsg_first( msg );
+
+		while ( frame ) {
+			char *str = zframe_strdup( frame );
+			VALUE data = rb_enc_str_new( str, zframe_size(frame), rb_ascii8bit_encoding() );
+
+			rb_obj_freeze( data );
+			rb_ary_push( rval, data );
+
+			free( str );
+			frame = zmsg_next( msg );
+		}
+	}
+
+	return rval;
+}
+
+
 /*
  * call-seq:
  *    event.print
@@ -471,7 +535,9 @@ rzyre_init_event( void ) {
 	rb_define_method( rzyre_cZyreEvent, "headers", rzyre_event_headers, 0 );
 	rb_define_method( rzyre_cZyreEvent, "header", rzyre_event_header, 1 );
 	rb_define_method( rzyre_cZyreEvent, "group", rzyre_event_group, 0 );
+	rb_define_method( rzyre_cZyreEvent, "msg_size", rzyre_event_msg_size, 0 );
 	rb_define_method( rzyre_cZyreEvent, "msg", rzyre_event_msg, 0 );
+	rb_define_method( rzyre_cZyreEvent, "multipart_msg", rzyre_event_multipart_msg, 0 );
 	rb_define_method( rzyre_cZyreEvent, "print", rzyre_event_print, 0 );
 
 	rb_require( "zyre/event" );

data/ext/zyre_ext/node.c

@@ -526,23 +526,26 @@ rzyre_node_recv( VALUE self )
 
 /*
  * call-seq:
- *    node.whisper( peer_uuid, message )  -> int
+ *    node.whisper( peer_uuid, *messages )  -> int
  *
  * Send a +message+ to a single +peer+ specified as a UUID string.
  *
  */
 static VALUE
-rzyre_node_whisper( VALUE self, VALUE peer_uuid, VALUE msg )
+rzyre_node_whisper( int argc, VALUE *argv, VALUE self )
 {
 	zyre_t *ptr = rzyre_get_node( self );
-	const char *peer_str = StringValueCStr( peer_uuid ),
-		*msg_str = StringValueCStr( msg );
+	VALUE peer_uuid, msg_parts;
+	char *peer_uuid_str;
+	zmsg_t *msg;
 	int rval;
 
-	assert( peer_str );
-	assert( msg_str );
+	rb_scan_args( argc, argv, "1*", &peer_uuid, &msg_parts );
 
-	rval = zyre_whispers( ptr, peer_str, "%s", msg_str );
+	peer_uuid_str = StringValueCStr( peer_uuid );
+	msg = rzyre_make_zmsg_from( msg_parts );
+
+	rval = zyre_whisper( ptr, peer_uuid_str, &msg );
 
 	return rval ? Qtrue : Qfalse;
 }
@@ -550,23 +553,26 @@ rzyre_node_whisper( VALUE self, VALUE peer_uuid, VALUE msg )
 
 /*
  * call-seq:
- *    node.shout( group, message )   -> int
+ *    node.shout( group, *messages )   -> int
  *
  * Send +message+ to a named +group+.
  *
  */
 static VALUE
-rzyre_node_shout( VALUE self, VALUE group, VALUE msg )
+rzyre_node_shout( int argc, VALUE *argv, VALUE self )
 {
 	zyre_t *ptr = rzyre_get_node( self );
-	const char *group_str = StringValueCStr( group ),
-		*msg_str = StringValueCStr( msg );
+	VALUE group, msg_parts;
+	char *group_str;
+	zmsg_t *msg;
 	int rval;
 
-	assert( group_str );
-	assert( msg_str );
+	rb_scan_args( argc, argv, "1*", &group, &msg_parts );
+
+	group_str = StringValueCStr( group );
+	msg = rzyre_make_zmsg_from( msg_parts );
 
-	rval = zyre_shouts( ptr, group_str, "%s", msg_str );
+	rval = zyre_shout( ptr, group_str, &msg );
 
 	return rval ? Qtrue : Qfalse;
 }
@@ -819,8 +825,8 @@ rzyre_init_node( void )
 
 	rb_define_method( rzyre_cZyreNode, "recv", rzyre_node_recv, 0 );
 
-	rb_define_method( rzyre_cZyreNode, "whisper", rzyre_node_whisper, 2 );
-	rb_define_method( rzyre_cZyreNode, "shout", rzyre_node_shout, 2 );
+	rb_define_method( rzyre_cZyreNode, "whisper", rzyre_node_whisper, -1 );
+	rb_define_method( rzyre_cZyreNode, "shout", rzyre_node_shout, -1 );
 
 	rb_define_method( rzyre_cZyreNode, "peers", rzyre_node_peers, 0 );
 	rb_define_method( rzyre_cZyreNode, "peers_by_group", rzyre_node_peers_by_group, 1 );

data/ext/zyre_ext/zyre_ext.c

@@ -68,6 +68,64 @@ rzyre_log( const char *level, const char *fmt, va_dcl )
 }
 
 
+/* --------------------------------------------------------------
+ * Utility functions
+ * -------------------------------------------------------------- */
+
+// Struct for passing arguments through rb_protect to rzyre_add_frames_to_zmsg()
+struct add_frames_to_zmsg_call {
+	zmsg_t *msg;
+	VALUE msg_parts;
+};
+typedef struct add_frames_to_zmsg_call add_frames_to_zmsg_call_t;
+
+
+/*
+ * Add a frame for each object in an Array.
+ */
+static VALUE
+rzyre_add_frames_to_zmsg( VALUE call )
+{
+	add_frames_to_zmsg_call_t *call_ptr = (add_frames_to_zmsg_call_t *)call;
+	VALUE msg_part;
+
+	for ( long i = 0 ; i < RARRAY_LEN(call_ptr->msg_parts) ; i++ ) {
+		msg_part = rb_ary_entry( call_ptr->msg_parts, i );
+		zmsg_addstr( call_ptr->msg, StringValueCStr(msg_part) );
+	}
+
+	return Qtrue;
+}
+
+
+/*
+ * Make and return a zmsg, with one frame per object in +messages+. Caller owns the returned
+ * zmsg. Can raise a TypeError if one of the +messages+ can't be stringified.
+ */
+zmsg_t *
+rzyre_make_zmsg_from( VALUE messages )
+{
+	VALUE msgarray = rb_Array( messages );
+	zmsg_t *msg = zmsg_new();
+	static add_frames_to_zmsg_call_t call;
+	int state;
+
+	call.msg = msg;
+	call.msg_parts = msgarray;
+
+	rb_protect( rzyre_add_frames_to_zmsg, (VALUE)&call, &state );
+
+	if ( state ) {
+		zmsg_destroy( &msg );
+		rb_jump_tag( state );
+	}
+
+	return msg;
+}
+
+
+
+
 
 /* --------------------------------------------------------------
  * Module methods

data/ext/zyre_ext/zyre_ext.h

@@ -13,6 +13,7 @@
 #include <ruby.h>
 #include <ruby/intern.h>
 #include <ruby/thread.h>
+#include <ruby/encoding.h>
 
 #include "zyre.h"
 #include "czmq.h"
@@ -83,6 +84,11 @@ extern VALUE rzyre_cZyrePoller;
 #define IsZyreEvent( obj ) rb_obj_is_kind_of( (obj), rzyre_cZyreEvent )
 #define IsZyrePoller( obj ) rb_obj_is_kind_of( (obj), rzyre_cZyrePoller )
 
+/* --------------------------------------------------------------
+ * Utility functions
+ * -------------------------------------------------------------- */
+extern zmsg_t * rzyre_make_zmsg_from _(( VALUE ));
+
 
 /* -------------------------------------------------------
  * Initializer functions

data/lib/observability/instrumentation/zyre.rb

@@ -38,14 +38,14 @@ module Observability::Instrumentation::Zyre
 	###############
 
 	### Observer callback for the #whisper method.
-	def observe_whisper( peer_uuid, msg )
-		Observability.observer.add( peer_uuid: peer_uuid, message: msg )
+	def observe_whisper( peer_uuid, *msgs )
+		Observability.observer.add( peer_uuid: peer_uuid, messages: msgs )
 	end
 
 
 	### Observer callback for the #shout method.
-	def observe_shout( group, msg )
-		Observability.observer.add( group: group, message: msg )
+	def observe_shout( group, *msgs )
+		Observability.observer.add( group: group, messages: msgs )
 	end
 
 end # module Observability::Instrumentation::Zyre

data/lib/zyre.rb

@@ -12,7 +12,7 @@ module Zyre
 
 
 	# Gem version (semver)
-	VERSION = '0.1.0'
+	VERSION = '0.2.0'
 
 
 	# Set up a logger for Zyre classes

data/lib/zyre/event.rb

@@ -60,6 +60,14 @@ class Zyre::Event
 	end
 
 
+	### Returns +true+ if the receiving event has a multipart message.
+	def multipart?
+		size = self.msg_size
+		return size && size > 1
+	end
+	alias_method :is_multipart?, :multipart?
+
+
 	### Return a string describing this event, suitable for debugging.
 	def inspect
 		details = self.inspect_details

data/lib/zyre/testing.rb

@@ -154,8 +154,12 @@ module Zyre::Testing
 
 
 		### Generate a SHOUT event.
-		def shout( **overrides )
+		def shout( group=nil, *msg, **overrides )
 			uuid = overrides.delete( :peer_uuid ) || self.peer_uuid
+
+			overrides[:group] = group if group
+			overrides[:msg] = msg if !msg.empty?
+
 			config = {
 				peer_name: self.peer_name,
 				group: self.group,
@@ -166,9 +170,14 @@ module Zyre::Testing
 		end
 
 
-		### Generate a WHISPER event.
-		def whisper( **overrides )
+		### Generate a WHISPER event. The first positional argument, which would
+		### normally be the UUID of the peer to WHISPER to is ignored, since the
+		### generated event's +peer_uuid+ is the sending node's not the receiving one's.
+		def whisper( _ignored=nil, *msg, **overrides )
 			uuid = overrides.delete( :peer_uuid ) || self.peer_uuid
+
+			overrides[:msg] = msg if !msg.empty?
+
 			config = {
 				peer_name: self.peer_name,
 				msg: self.msg

data/spec/observability/instrumentation/zyre_spec.rb

@@ -31,7 +31,7 @@ RSpec.describe 'Observability::Instrumentation::Zyre', :observability do
 		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' )
+		expect( events.first[:messages] ).to eq( ['a peer-to-peer message'] )
 
 	end
 
@@ -49,7 +49,7 @@ RSpec.describe 'Observability::Instrumentation::Zyre', :observability do
 		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' )
+		expect( events.first[:messages] ).to eq( ['a peer-to-peer message'] )
 	end
 
 end

data/spec/zyre/event_spec.rb

@@ -135,6 +135,55 @@ RSpec.describe( Zyre::Event ) do
 			expect( result.peer_name ).to eq( 'S-' + peer_uuid[0, 6] )
 		end
 
+
+		it "raises when creating a WHISPER with no msg" do
+			expect {
+				described_class.synthesize( :WHISPER, peer_uuid )
+			}.to raise_error( ArgumentError, /missing required field :msg/i )
+		end
+
+
+		it "raises when creating a SHOUT with no msg" do
+			expect {
+				described_class.synthesize( :SHOUT, peer_uuid, group: 'agroup' )
+			}.to raise_error( ArgumentError, /missing required field :msg/i )
+		end
+
+
+		it "raises when creating a SHOUT with no group" do
+			expect {
+				described_class.synthesize( :SHOUT, peer_uuid, msg: 'amsg' )
+			}.to raise_error( ArgumentError, /missing required field :group/i )
+		end
+
+
+		it "raises when creating an ENTER with no peer_addr" do
+			expect {
+				described_class.synthesize( :ENTER, peer_uuid )
+			}.to raise_error( ArgumentError, /missing required field :peer_addr/i )
+		end
+
+
+		it "raises when creating a JOIN with no group" do
+			expect {
+				described_class.synthesize( :JOIN, peer_uuid )
+			}.to raise_error( ArgumentError, /missing required field :group/i )
+		end
+
+
+		it "raises when creating a LEAVE with no group" do
+			expect {
+				described_class.synthesize( :LEAVE, peer_uuid )
+			}.to raise_error( ArgumentError, /missing required field :group/i )
+		end
+
+
+		it "raises when creating an unknown type of event" do
+			expect {
+				described_class.synthesize( :BACKUP, peer_uuid )
+			}.to raise_error( ArgumentError, /don't know how to create :BACKUP events/i )
+		end
+
 	end
 
 end

data/spec/zyre/node_spec.rb

@@ -162,13 +162,30 @@ RSpec.describe( Zyre::Node ) do
 		node1.wait_for( :ENTER, peer_uuid: node2.uuid )
 		node1.whisper( node2.uuid, TEST_WHISPER )
 
-		ev = node2.recv
-		expect( ev.type ).to eq( :ENTER )
+		ev = node2.wait_for( :WHISPER )
+		expect( ev ).to be_a( Zyre::Event::Whisper )
+		expect( ev ).to_not be_multipart
+		msg = ev.msg
+		expect( msg.encoding ).to eq( Encoding::ASCII_8BIT )
+		msg = msg.dup.force_encoding( 'utf-8' )
+		expect( msg ).to eq( TEST_WHISPER )
+		expect( ev.multipart_msg ).to eq( [TEST_WHISPER.b] )
+	end
 
-		ev = node2.recv
-		expect( ev.type ).to eq( :WHISPER )
-		expect( ev.msg.encoding ).to eq( Encoding::UTF_8 )
-		expect( ev.msg ).to eq( TEST_WHISPER )
+
+	it "can whisper a multipart message to another node" do
+		node1 = started_node()
+		node2 = started_node()
+
+		node1.wait_for( :ENTER, peer_uuid: node2.uuid )
+		node1.whisper( node2.uuid, 'poetry.snippet', TEST_WHISPER )
+
+		ev = node2.wait_for( :WHISPER, peer_uuid: node1.uuid )
+		expect( ev ).to be_a( Zyre::Event::Whisper )
+		expect( ev ).to be_multipart
+		expect( ev.msg.encoding ).to eq( Encoding::ASCII_8BIT )
+		expect( ev.msg ).to eq( 'poetry.snippet' )
+		expect( ev.multipart_msg ).to eq( ['poetry.snippet', TEST_WHISPER] )
 	end
 
 
@@ -190,8 +207,42 @@ RSpec.describe( Zyre::Node ) do
 
 		ev = node2.recv
 		expect( ev ).to be_a( Zyre::Event::Shout )
-		expect( ev.msg.encoding ).to eq( Encoding::UTF_8 )
-		expect( ev.msg ).to eq( TEST_SHOUT )
+		expect( ev ).to_not be_multipart
+		expect( ev.msg.encoding ).to eq( Encoding::ASCII_8BIT )
+		expect( ev.msg ).to eq( TEST_SHOUT.b )
+		expect( ev.multipart_msg ).to eq( [TEST_SHOUT.b] )
+	end
+
+
+	it "can shout a multipart message to a group of nodes" do
+		node1 = started_node()
+		node2 = started_node()
+		node3 = started_node()
+
+		node1.join( 'ROOFTOP' )
+		node2.join( 'ROOFTOP' )
+		node3.join( 'ROOFTOP' )
+
+		2.times do
+			node1.wait_for( :JOIN, group: 'ROOFTOP' )
+		end
+		node1.shout( 'ROOFTOP', "random.poetry", TEST_SHOUT )
+
+		ev = node2.wait_for( :SHOUT, group: 'ROOFTOP' )
+		expect( ev ).to be_a( Zyre::Event::Shout )
+		expect( ev ).to be_multipart
+		expect( ev.msg ).to eq( 'random.poetry'.b )
+		expect( ev.multipart_msg ).to eq( ['random.poetry'.b, TEST_SHOUT.b] )
+	end
+
+
+	it "handles unstringifiable messages gracefully" do
+		node1 = started_node()
+		node1.join( 'ROOFTOP' )
+
+		expect {
+			node1.shout( 'ROOFTOP', nil )
+		}.to raise_error( TypeError, /nil/i )
 	end
 
 
@@ -236,6 +287,22 @@ RSpec.describe( Zyre::Node ) do
 	end
 
 
+	it "knows what the headers of its peers are" do
+		node1 = started_node()
+		node2 = started_node() do |node|
+			node.headers = {
+				protocol_version: 2,
+				content_type: 'application/javascript',
+				start_time: Time.now.to_f
+			}
+		end
+
+		node1.wait_for( :enter, peer_uuid: node2.uuid )
+
+		expect( node1.peer_header_value(node2.uuid, 'Protocol-version') ).to eq( '2' )
+	end
+
+
 	it "has a blocking iterator" do
 		node = described_class.new
 

data/spec/zyre/testing_spec.rb

@@ -181,6 +181,20 @@ RSpec.describe( Zyre::Testing ) do
 		end
 
 
+		it "can override SHOUT event message and group using positional parameters" do
+			event = factory.shout( 'control', 'data1', 'data2' )
+
+			expect( event ).to be_a( Zyre::Event::Shout )
+			expect( event.peer_uuid ).to eq( factory.peer_uuid )
+			expect( event.peer_name ).to eq( 'lancer-6' )
+			expect( event.headers ).to be_empty
+			expect( event.msg ).to eq( 'data1' )
+			expect( event ).to be_multipart
+			expect( event.multipart_msg ).to eq( ['data1'.b, 'data2'.b] )
+			expect( event.group ).to eq( 'control' )
+		end
+
+
 		it "can create a valid WHISPER event" do
 			event = factory.whisper
 
@@ -193,6 +207,14 @@ RSpec.describe( Zyre::Testing ) do
 		end
 
 
+		it "can create a valid WHISPER event with a multipart msg" do
+			event = factory.whisper( msg: %w[three times fool] )
+
+			expect( event ).to be_multipart
+			expect( event.multipart_msg ).to eq( %w[three times fool] )
+		end
+
+
 		it "can create a valid WHISPER event with overridden config" do
 			uuid = SecureRandom.uuid.tr( '-', '' )
 			event = factory.whisper( peer_uuid: uuid, msg: 'stop' )
@@ -206,6 +228,20 @@ RSpec.describe( Zyre::Testing ) do
 		end
 
 
+		it "can override WHISPER event message using positional parameters" do
+			event = factory.whisper( 'ignored', 'data1', 'data2' )
+
+			expect( event ).to be_a( Zyre::Event::Whisper )
+			expect( event.peer_uuid ).to eq( factory.peer_uuid )
+			expect( event.peer_name ).to eq( 'lancer-6' )
+			expect( event.headers ).to be_empty
+			expect( event.msg ).to eq( 'data1' )
+			expect( event ).to be_multipart
+			expect( event.multipart_msg ).to eq( ['data1', 'data2'] )
+			expect( event.group ).to be_nil
+		end
+
+
 		it "can create a valid LEAVE event" do
 			event = factory.leave
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zyre
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Michael Granger
@@ -33,7 +33,7 @@ cert_chain:
   83uuAYSy65yXDGXXPVBeKPVnYrqp91pqpS5Nh7wfuiCrE8lgU8PATh7K4BV1UhAT
   0MHbAT42wTYkfUj3
   -----END CERTIFICATE-----
-date: 2020-11-05 00:00:00.000000000 Z
+date: 2020-11-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: loggability