Line data    Source code

       1              : // Copyright (c) 2021-present The Bitcoin Core developers
       2              : // Distributed under the MIT software license, see the accompanying
       3              : // file COPYING or http://www.opensource.org/licenses/mit-license.php.
       4              : 
       5              : #ifndef BITCOIN_IPC_PROTOCOL_H
       6              : #define BITCOIN_IPC_PROTOCOL_H
       7              : 
       8              : #include <interfaces/init.h>
       9              : #include <ipc/util.h>
      10              : 
      11              : #include <cstddef>
      12              : #include <functional>
      13              : #include <memory>
      14              : #include <optional>
      15              : #include <typeindex>
      16              : 
      17              : namespace ipc {
      18              : struct Context;
      19              : 
      20              : //! IPC protocol interface for calling IPC methods over sockets.
      21              : //!
      22              : //! There may be different implementations of this interface for different IPC
      23              : //! protocols (e.g. Cap'n Proto, gRPC, JSON-RPC, or custom protocols).
      24            3 : class Protocol
      25              : {
      26              : public:
      27            3 :     virtual ~Protocol() = default;
      28              : 
      29              :     //! Return Init interface that forwards requests over given connection
      30              :     //! stream. Socket communication is handled on a background thread.
      31              :     //!
      32              :     //! @note It could be potentially useful in the future to add
      33              :     //! std::function<void()> on_disconnect callback argument here. But there
      34              :     //! isn't an immediate need, because the protocol implementation can clean
      35              :     //! up its own state (calling ProxyServer destructors, etc) on disconnect,
      36              :     //! and any client calls will just throw ipc::Exception errors after a
      37              :     //! disconnect.
      38              :     virtual std::unique_ptr<interfaces::Init> connect(mp::Stream stream) = 0;
      39              : 
      40              :     //! Listen for connections on provided socket id, accept them, and handle
      41              :     //! requests on accepted connections. This method doesn't block, and
      42              :     //! performs I/O on a background thread.
      43              :     virtual void listen(mp::SocketId listen_fd, interfaces::Init& init, std::optional<size_t> max_connections = std::nullopt) = 0;
      44              : 
      45              :     //! Handle requests from a stream provided by the make_stream callback,
      46              :     //! forwarding them to the provided Init interface. Socket communication is
      47              :     //! handled on the current thread, and this call blocks until the socket is
      48              :     //! closed. A callback is used to specify the stream because this method
      49              :     //! initializes the event loop and it may not be possible to create the
      50              :     //! stream before the event loop is initialized.
      51              :     //!
      52              :     //! @note: If this method is called, it needs to be called before connect()
      53              :     //! or listen() methods, because for ease of implementation this method is
      54              :     //! inflexible and always runs the event loop in the foreground thread. It
      55              :     //! can share its event loop with the other methods but can't share an event
      56              :     //! loop that was created by them. This isn't a problem because serve() is
      57              :     //! only called by spawned child processes that call it immediately to
      58              :     //! communicate back with parent processes.
      59              :     virtual void serve(interfaces::Init& init, const std::function<mp::Stream()>& make_stream) = 0;
      60              : 
      61              :     //! Make stream object from socket id.
      62              :     virtual mp::Stream makeStream(mp::SocketId socket) = 0;
      63              : 
      64              :     //! Disconnect any incoming connections that are still connected.
      65              :     virtual void disconnectIncoming() = 0;
      66              : 
      67              :     //! Add cleanup callback to interface that will run when the interface is
      68              :     //! deleted.
      69              :     virtual void addCleanup(std::type_index type, void* iface, std::function<void()> cleanup) = 0;
      70              : 
      71              :     //! Context accessor.
      72              :     virtual Context& context() = 0;
      73              : };
      74              : } // namespace ipc
      75              : 
      76              : #endif // BITCOIN_IPC_PROTOCOL_H