Salticidae: minimal C++ asynchronous network library. ===================================================== .. image:: https://img.shields.io/badge/License-MIT-yellow.svg :target: https://opensource.org/licenses/MIT Features -------- - Simplicity. The library is self-contained, small in code base, and only relies on libuv and libssl/libcrypto (OpenSSL, for SHA256 purpose). Despite the multi-threaded nature of the library, a user only needs to understand the callbacks are invoked in a sequential order driven by a single user-initiated event loop. - Clarity. With moderate use of C++ template and new features, the vast majority of the code is self-documenting. - Layered design. You can use network abstraction from the lowest socket connection level to the highest P2P network level. - Performance. Based on a hybrid solution that combines both thread-based and event-driven concurrency paradigms, it gets the best of both worlds. The implementation strives to incur very little overhead in processing network I/O, and avoid unnecessary memory copies thanks to the move semantics. - Utilities. The library also provides with some useful gadgets, such as command-line parser, libuv abstraction, etc. - Security. It supports SSL/TLS, with customized certificate verification (as part of the connection callback). - Bindings for other languages. The library itself supports C APIs and the other project ``salticidae-go`` supports invoking the library in Go through cgo. Functionalities --------------- - ``ConnPool``: byte level connection pool implementation, ``ConnPool::Conn`` (or ``ConnPool::conn_t``) objects represent connections to which one can send/receive a stream of binary data asynchronously. - ``MsgNetwork``: message level network pool implementation, ``MsgNetwork::Conn`` (or ``MsgNetwork::cont_t``) objects represent channels to which one can send/receive predefined messages asynchronously. Message handler functions are registered by ``reg_handler()`` and invoked upon receiving a new message. ``OpcodeType`` is the type used for identifying message types. A valid message class must have: - a static member ``opcode`` typed ``OpcodeType`` as the message type identifier - a member ``serialized`` typed ``DataStream`` which contains the serialized data of the message. - a constructor ``MsgType(DataStream &&)`` that parse the message from stream. Based on ``MsgNetwork``, salticidae provides the following higher level abstractions: - ``PeerNetwork``: simple P2P network pool implementation. It will ensure exactly one underlying bi-directional connection is established per added peer, and retry the connection when it is broken. Ping-pong messages are utilized to test the connectivity periodically. - ``ClientNetwork``: simple client-server network pool implementation. A server who initially calls ``listen()`` will accept the incoming client messages, while a client simply calls ``connect()`` to connect to a known server. Dependencies ------------ - CMake >= 3.9 - C++14 - libuv >= 1.10.0 - openssl >= 1.1.0 Minimal working P2P network --------------------------- .. code-block:: cpp #include #include "salticidae/event.h" #include "salticidae/network.h" using Net = salticidae::PeerNetwork; int main() { /* example of 4 peer nodes pinging each other */ std::vector>> nodes; Net::Config config; salticidae::EventContext ec; config.ping_period(2); nodes.resize(4); for (size_t i = 0; i < nodes.size(); i++) { salticidae::NetAddr addr("127.0.0.1:" + std::to_string(10000 + i)); auto &net = (nodes[i] = std::make_pair(addr, std::make_unique(ec, config))).second; net->start(); net->listen(addr); } for (size_t i = 0; i < nodes.size(); i++) for (size_t j = 0; j < nodes.size(); j++) if (i != j) nodes[i].second->add_peer(nodes[j].first); ec.dispatch(); return 0; } Using MsgNetwork class ---------------------- .. code-block:: cpp #include #include #include #include "salticidae/msg.h" #include "salticidae/event.h" #include "salticidae/network.h" #include "salticidae/stream.h" using salticidae::NetAddr; using salticidae::DataStream; using salticidae::MsgNetwork; using salticidae::htole; using salticidae::letoh; using std::placeholders::_1; using std::placeholders::_2; /** Hello Message. */ struct MsgHello { static const uint8_t opcode = 0x0; DataStream serialized; std::string name; std::string text; /** Defines how to serialize the msg. */ MsgHello(const std::string &name, const std::string &text) { serialized << htole((uint32_t)name.length()); serialized << name << text; } /** Defines how to parse the msg. */ MsgHello(DataStream &&s) { uint32_t len; s >> len; len = letoh(len); name = std::string((const char *)s.get_data_inplace(len), len); len = s.size(); text = std::string((const char *)s.get_data_inplace(len), len); } }; /** Acknowledgement Message. */ struct MsgAck { static const uint8_t opcode = 0x1; DataStream serialized; MsgAck() {} MsgAck(DataStream &&s) {} }; const uint8_t MsgHello::opcode; const uint8_t MsgAck::opcode; using MsgNetworkByteOp = MsgNetwork; struct MyNet: public MsgNetworkByteOp { const std::string name; const NetAddr peer; MyNet(const salticidae::EventContext &ec, const std::string name, const NetAddr &peer): MsgNetwork(ec, MsgNetwork::Config()), name(name), peer(peer) { /* message handler could be a bound method */ reg_handler( salticidae::generic_bind(&MyNet::on_receive_hello, this, _1, _2)); reg_conn_handler([this](const ConnPool::conn_t &conn, bool connected) { if (connected) { if (conn->get_mode() == ConnPool::Conn::ACTIVE) { printf("[%s] connected, sending hello.\n", this->name.c_str()); /* send the first message through this connection */ send_msg(MsgHello(this->name, "Hello there!"), salticidae::static_pointer_cast(conn)); } else printf("[%s] accepted, waiting for greetings.\n", this->name.c_str()); } else { printf("[%s] disconnected, retrying.\n", this->name.c_str()); /* try to reconnect to the same address */ connect(conn->get_addr(), false); } return true; }); } void on_receive_hello(MsgHello &&msg, const MyNet::conn_t &conn) { printf("[%s] %s says %s\n", name.c_str(), msg.name.c_str(), msg.text.c_str()); /* send acknowledgement */ send_msg(MsgAck(), conn); } }; void on_receive_ack(MsgAck &&msg, const MyNet::conn_t &conn) { auto net = static_cast(conn->get_net()); printf("[%s] the peer knows\n", net->name.c_str()); } int main() { salticidae::EventContext ec; NetAddr alice_addr("127.0.0.1:12345"); NetAddr bob_addr("127.0.0.1:12346"); /* test two nodes in the same main loop */ MyNet alice(ec, "alice", bob_addr); MyNet bob(ec, "bob", alice_addr); /* message handler could be a normal function */ alice.reg_handler(on_receive_ack); bob.reg_handler(on_receive_ack); /* start all threads */ alice.start(); bob.start(); /* accept incoming connections */ alice.listen(alice_addr); bob.listen(bob_addr); /* try to connect once */ alice.connect(bob_addr, false); bob.connect(alice_addr, false); /* the main loop can be shutdown by ctrl-c or kill */ auto shutdown = [&](int) {ec.stop();}; salticidae::SigEvent ev_sigint(ec, shutdown); salticidae::SigEvent ev_sigterm(ec, shutdown); ev_sigint.add(SIGINT); ev_sigterm.add(SIGTERM); /* enter the main loop */ ec.dispatch(); return 0; }