Inside Bitcoin

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