problem: ZMQ_HEARTBEAT is not useful without sending an hello message

When using ZMQ_HEARTBEAT one still needs to implement application-level heartbeat in order to know when to send a hello message.
For example, with the majordomo protocol, the worker needs to send a READY message when connecting to a broker. If the connection to the broker drops, and the heartbeat recognizes it the worker won't know about it and won't send the READY msg.
To solve that, the majordomo worker still has to implement heartbeat. With this new option, whenever the connection drops and reconnects the hello message will be sent, greatly simplify the majordomo protocol, as now READY and HEARTBEAT can be handled by zeromq.

Makefile.am

@@ -1041,7 +1041,8 @@ test_apps += tests/test_poller \
 	tests/test_router_notify \
 	tests/test_peer \
 	tests/test_reconnect_options \
-	tests/test_msg_init
+	tests/test_msg_init \
+	tests/test_hello_msg
 
 tests_test_poller_SOURCES = tests/test_poller.cpp
 tests_test_poller_LDADD = ${TESTUTIL_LIBS} src/libzmq.la
@@ -1094,6 +1095,10 @@ tests_test_reconnect_options_CPPFLAGS = ${TESTUTIL_CPPFLAGS}
 tests_test_msg_init_SOURCES = tests/test_msg_init.cpp
 tests_test_msg_init_LDADD = ${TESTUTIL_LIBS} src/libzmq.la
 tests_test_msg_init_CPPFLAGS = ${TESTUTIL_CPPFLAGS}
+
+tests_test_hello_msg_SOURCES = tests/test_hello_msg.cpp
+tests_test_hello_msg_LDADD = ${TESTUTIL_LIBS} src/libzmq.la
+tests_test_hello_msg_CPPFLAGS = ${TESTUTIL_CPPFLAGS}
 endif
 
 if ENABLE_STATIC

doc/zmq_setsockopt.txt

@@ -322,6 +322,18 @@ Option value unit:: milliseconds
 Default value:: 30000
 Applicable socket types:: all but ZMQ_STREAM, only for connection-oriented transports
 
+ZMQ_HELLO_MSG: set an hello message that will be sent when a new peer connect
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When set, the socket will automatically send an hello message when a new connection is made or accepted.
+You may set this on DEALER, ROUTER, CLIENT, SERVER and PEER sockets.
+The combination with ZMQ_HEARTBEAT_IVL is powerful and simplify protocols,
+as now heartbeat and sending the hello message can be left out of protocols and be handled by zeromq.
+
+[horizontal]
+Option value type:: binary data
+Option value unit:: N/A
+Default value:: NULL
+Applicable socket types:: ZMQ_ROUTER, ZMQ_DEALER, ZMQ_CLIENT, ZMQ_SERVER and ZMQ_PEER
 
 ZMQ_HEARTBEAT_IVL: Set interval between sending ZMTP heartbeats
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

include/zmq.h

@@ -678,6 +678,7 @@ ZMQ_EXPORT void zmq_threadclose (void *thread_);
 #define ZMQ_WSS_TRUST_SYSTEM 107
 #define ZMQ_ONLY_FIRST_SUBSCRIBE 108
 #define ZMQ_RECONNECT_STOP 109
+#define ZMQ_HELLO_MSG 110
 
 /*  DRAFT ZMQ_RECONNECT_STOP options                                          */
 #define ZMQ_RECONNECT_STOP_CONN_REFUSED 0x1

src/client.cpp

@@ -37,6 +37,7 @@ zmq::client_t::client_t (class ctx_t *parent_, uint32_t tid_, int sid_) :
     socket_base_t (parent_, tid_, sid_, true)
 {
     options.type = ZMQ_CLIENT;
+    options.can_send_hello_msg = true;
 }
 
 zmq::client_t::~client_t ()

src/ctx.cpp

@@ -848,6 +848,14 @@ void zmq::ctx_t::connect_inproc_sockets (
         && pending_connection_.endpoint.socket->check_tag ()) {
         send_routing_id (pending_connection_.bind_pipe, bind_options_);
     }
+
+#ifdef ZMQ_BUILD_DRAFT_API
+    //  If set, send the hello msg of the bind socket to the pending connection.
+    if (bind_options_.can_send_hello_msg
+        && bind_options_.hello_msg.size () > 0) {
+        send_hello_msg (pending_connection_.bind_pipe, bind_options_);
+    }
+#endif
 }
 
 #ifdef ZMQ_HAVE_VMCI

src/dealer.cpp

@@ -38,6 +38,7 @@ zmq::dealer_t::dealer_t (class ctx_t *parent_, uint32_t tid_, int sid_) :
     _probe_router (false)
 {
     options.type = ZMQ_DEALER;
+    options.can_send_hello_msg = true;
 }
 
 zmq::dealer_t::~dealer_t ()

src/options.cpp

@@ -249,7 +249,9 @@ zmq::options_t::options_t () :
     zero_copy (true),
     router_notify (0),
     monitor_event_version (1),
-    wss_trust_system (false)
+    wss_trust_system (false),
+    hello_msg (),
+    can_send_hello_msg (false)
 {
     memset (curve_public_key, 0, CURVE_KEYSIZE);
     memset (curve_secret_key, 0, CURVE_KEYSIZE);
@@ -813,6 +815,19 @@ int zmq::options_t::setsockopt (int option_,
             return do_setsockopt_int_as_bool_strict (optval_, optvallen_,
                                                      &wss_trust_system);
 #endif
+
+        case ZMQ_HELLO_MSG:
+            if (optvallen_ > 0) {
+                unsigned char *bytes = (unsigned char *) optval_;
+                hello_msg =
+                  std::vector<unsigned char> (bytes, bytes + optvallen_);
+            } else {
+                hello_msg = std::vector<unsigned char> ();
+            }
+
+
+            return 0;
+
 #endif
 
         default:

src/options.hpp

@@ -297,6 +297,10 @@ struct options_t
     std::string wss_trust_pem;
     std::string wss_hostname;
     bool wss_trust_system;
+
+    //  Hello msg
+    std::vector<unsigned char> hello_msg;
+    bool can_send_hello_msg;
 };
 
 inline bool get_effective_conflate_option (const options_t &options)

src/peer.cpp

@@ -40,6 +40,7 @@ zmq::peer_t::peer_t (class ctx_t *parent_, uint32_t tid_, int sid_) :
     server_t (parent_, tid_, sid_)
 {
     options.type = ZMQ_PEER;
+    options.can_send_hello_msg = true;
 }
 
 uint32_t zmq::peer_t::connect_peer (const char *endpoint_uri_)

src/pipe.cpp

@@ -88,6 +88,17 @@ void zmq::send_routing_id (pipe_t *pipe_, const options_t &options_)
     pipe_->flush ();
 }
 
+void zmq::send_hello_msg (pipe_t *pipe_, const options_t &options_)
+{
+    zmq::msg_t hello;
+    const int rc =
+      hello.init_buffer (&options_.hello_msg[0], options_.hello_msg.size ());
+    errno_assert (rc == 0);
+    const bool written = pipe_->write (&hello);
+    zmq_assert (written);
+    pipe_->flush ();
+}
+
 zmq::pipe_t::pipe_t (object_t *parent_,
                      upipe_t *inpipe_,
                      upipe_t *outpipe_,

src/pipe.hpp

@@ -261,6 +261,8 @@ class pipe_t ZMQ_FINAL : public object_t,
 };
 
 void send_routing_id (pipe_t *pipe_, const options_t &options_);
+
+void send_hello_msg (pipe_t *pipe_, const options_t &options_);
 }
 
 #endif

src/router.cpp

@@ -55,6 +55,7 @@ zmq::router_t::router_t (class ctx_t *parent_, uint32_t tid_, int sid_) :
     options.type = ZMQ_ROUTER;
     options.recv_routing_id = true;
     options.raw_socket = false;
+    options.can_send_hello_msg = true;
 
     _prefetched_id.init ();
     _prefetched_msg.init ();

src/server.cpp

@@ -41,6 +41,7 @@ zmq::server_t::server_t (class ctx_t *parent_, uint32_t tid_, int sid_) :
     _next_routing_id (generate_random ())
 {
     options.type = ZMQ_SERVER;
+    options.can_send_hello_msg = true;
 }
 
 zmq::server_t::~server_t ()

src/session_base.cpp

@@ -88,9 +88,21 @@ zmq::session_base_t *zmq::session_base_t::create (class io_thread_t *io_thread_,
         case ZMQ_SCATTER:
         case ZMQ_DGRAM:
         case ZMQ_PEER:
+#ifdef ZMQ_BUILD_DRAFT_API
+            if (options_.can_send_hello_msg && options_.hello_msg.size () > 0)
+                s = new (std::nothrow) hello_msg_session_t (
+                  io_thread_, active_, socket_, options_, addr_);
+            else
+                s = new (std::nothrow) session_base_t (
+                  io_thread_, active_, socket_, options_, addr_);
+
+            break;
+#else
             s = new (std::nothrow)
               session_base_t (io_thread_, active_, socket_, options_, addr_);
             break;
+#endif
+
         default:
             errno = EINVAL;
             return NULL;
@@ -807,3 +819,39 @@ void zmq::session_base_t::start_connecting_udp (io_thread_t * /*io_thread_*/)
 
     send_attach (this, engine);
 }
+
+zmq::hello_msg_session_t::hello_msg_session_t (io_thread_t *io_thread_,
+                                               bool connect_,
+                                               socket_base_t *socket_,
+                                               const options_t &options_,
+                                               address_t *addr_) :
+    session_base_t (io_thread_, connect_, socket_, options_, addr_),
+    _new_pipe (true)
+{
+}
+
+zmq::hello_msg_session_t::~hello_msg_session_t ()
+{
+}
+
+
+int zmq::hello_msg_session_t::pull_msg (msg_t *msg_)
+{
+    if (_new_pipe) {
+        _new_pipe = false;
+
+        const int rc =
+          msg_->init_buffer (&options.hello_msg[0], options.hello_msg.size ());
+        errno_assert (rc == 0);
+
+        return 0;
+    }
+
+    return session_base_t::pull_msg (msg_);
+}
+
+void zmq::hello_msg_session_t::reset ()
+{
+    session_base_t::reset ();
+    _new_pipe = true;
+}

src/session_base.hpp

@@ -201,6 +201,26 @@ class session_base_t : public own_t, public io_object_t, public i_pipe_events
 
     ZMQ_NON_COPYABLE_NOR_MOVABLE (session_base_t)
 };
+
+class hello_msg_session_t ZMQ_FINAL : public session_base_t
+{
+  public:
+    hello_msg_session_t (zmq::io_thread_t *io_thread_,
+                         bool connect_,
+                         zmq::socket_base_t *socket_,
+                         const options_t &options_,
+                         address_t *addr_);
+    ~hello_msg_session_t ();
+
+    //  Overrides of the functions from session_base_t.
+    int pull_msg (msg_t *msg_);
+    void reset ();
+
+  private:
+    bool _new_pipe;
+
+    ZMQ_NON_COPYABLE_NOR_MOVABLE (hello_msg_session_t)
+};
 }
 
 #endif

src/socket_base.cpp

@@ -833,6 +833,13 @@ int zmq::socket_base_t::connect_internal (const char *endpoint_uri_)
             //  the peer doesn't expect it.
             send_routing_id (new_pipes[0], options);
 
+#ifdef ZMQ_BUILD_DRAFT_API
+            //  If set, send the hello msg of the local socket to the peer.
+            if (options.can_send_hello_msg && options.hello_msg.size () > 0) {
+                send_hello_msg (new_pipes[0], options);
+            }
+#endif
+
             const endpoint_t endpoint = {this, options};
             pend_connection (std::string (endpoint_uri_), endpoint, new_pipes);
         } else {
@@ -846,6 +853,19 @@ int zmq::socket_base_t::connect_internal (const char *endpoint_uri_)
                 send_routing_id (new_pipes[1], peer.options);
             }
 
+#ifdef ZMQ_BUILD_DRAFT_API
+            //  If set, send the hello msg of the local socket to the peer.
+            if (options.can_send_hello_msg && options.hello_msg.size () > 0) {
+                send_hello_msg (new_pipes[0], options);
+            }
+
+            //  If set, send the hello msg of the peer to the local socket.
+            if (options.can_send_hello_msg
+                && peer.options.hello_msg.size () > 0) {
+                send_hello_msg (new_pipes[1], peer.options);
+            }
+#endif
+
             //  Attach remote end of the pipe to the peer socket. Note that peer's
             //  seqnum was incremented in find_endpoint function. We don't need it
             //  increased here.

src/zmq_draft.h

@@ -65,6 +65,7 @@
 #define ZMQ_WSS_TRUST_SYSTEM 107
 #define ZMQ_ONLY_FIRST_SUBSCRIBE 108
 #define ZMQ_RECONNECT_STOP 109
+#define ZMQ_HELLO_MSG 110
 
 /*  DRAFT ZMQ_RECONNECT_STOP options                                          */
 #define ZMQ_RECONNECT_STOP_CONN_REFUSED 0x1

tests/test_hello_msg.cpp

+/*
+    Copyright (c) 2007-2020 Contributors as noted in the AUTHORS file
+
+    This file is part of libzmq, the ZeroMQ core engine in C++.
+
+    libzmq is free software; you can redistribute it and/or modify it under
+    the terms of the GNU Lesser General Public License (LGPL) as published
+    by the Free Software Foundation; either version 3 of the License, or
+    (at your option) any later version.
+
+    As a special exception, the Contributors give you permission to link
+    this library with independent modules to produce an executable,
+    regardless of the license terms of these independent modules, and to
+    copy and distribute the resulting executable under terms of your choice,
+    provided that you also meet, for each linked independent module, the
+    terms and conditions of the license of that module. An independent
+    module is a module which is not derived from or based on this library.
+    If you modify this library, you must extend this exception to your
+    version of the library.
+
+    libzmq is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
+    License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+#include "testutil.hpp"
+#include "testutil_unity.hpp"
+
+SETUP_TEARDOWN_TESTCONTEXT
+
+void test (const char *address)
+{
+    //  Create a router
+    void *router = test_context_socket (ZMQ_ROUTER);
+
+    //  set router socket options
+    TEST_ASSERT_SUCCESS_ERRNO (zmq_setsockopt (router, ZMQ_HELLO_MSG, "H", 1));
+
+    //  bind router
+    TEST_ASSERT_SUCCESS_ERRNO (zmq_bind (router, address));
+
+    //  Create a dealer
+    void *dealer = test_context_socket (ZMQ_DEALER);
+    TEST_ASSERT_SUCCESS_ERRNO (zmq_connect (dealer, address));
+
+    // Receive the hello message
+    recv_string_expect_success (dealer, "H", 0);
+
+    //  Clean up.
+    test_context_socket_close (dealer);
+    test_context_socket_close (router);
+}
+
+void test_tcp ()
+{
+    test ("tcp://127.0.0.1:5569");
+}
+
+void test_inproc ()
+{
+    test ("inproc://hello-msg");
+}
+
+void test_inproc_late_bind ()
+{
+    char address[] = "inproc://late-hello-msg";
+
+    //  Create a server
+    void *server = test_context_socket (ZMQ_SERVER);
+
+    //  set server socket options
+    TEST_ASSERT_SUCCESS_ERRNO (zmq_setsockopt (server, ZMQ_HELLO_MSG, "W", 1));
+
+    //  Create a dealer
+    void *client = test_context_socket (ZMQ_CLIENT);
+    TEST_ASSERT_SUCCESS_ERRNO (zmq_setsockopt (client, ZMQ_HELLO_MSG, "H", 1));
+    TEST_ASSERT_SUCCESS_ERRNO (zmq_connect (client, address));
+
+    //  bind server after the dealer
+    TEST_ASSERT_SUCCESS_ERRNO (zmq_bind (server, address));
+
+    // Receive the welcome message from server
+    recv_string_expect_success (client, "W", 0);
+
+    // Receive the hello message from client
+    recv_string_expect_success (server, "H", 0);
+
+    //  Clean up.
+    test_context_socket_close (client);
+    test_context_socket_close (server);
+}
+
+int main ()
+{
+    setup_test_environment ();
+
+    UNITY_BEGIN ();
+    RUN_TEST (test_tcp);
+    RUN_TEST (test_inproc);
+    RUN_TEST (test_inproc_late_bind);
+    return UNITY_END ();
+}