/**
 * A socket manager class which handles socket operations.
 * To use this class, inherit from it and implement the pure virtual methods.
 * Handled operations:
 * - binding and listening on sockets
 * - starting of necessary threads to process socket operations
 * - accepting incoming connections
 * - making outbound connections
 * - closing connections
 * - waiting for IO readiness on sockets and doing send/recv accordingly
 */
class SockMan
{
public:

    //
    // Non-virtual functions, to be reused by children classes.
    //

    /**
     * Bind to a new address:port, start listening and add the listen socket to `m_listen`.
     * Should be called before `StartSocketsThreads()`.
     * @param[in] to Where to bind.
     * @param[out] errmsg Error string if an error occurs.
     * @retval true Success.
     * @retval false Failure, `strError` will be set.
     */
    bool BindAndStartListening(const CService& to, bilingual_str& errmsg);

    /**
     * Start the necessary threads for sockets IO.
     */
    void StartSocketsThreads(const Options& options);

    /**
     * Join (wait for) the threads started by `StartSocketsThreads()` to exit.
     */
    void JoinSocketsThreads();

    /**
     * Make an outbound connection, save the socket internally and return a newly generated node id.
     * @param[in] to The address to connect to, either as CService or a host as string and port as
     * an integer, if the later is used, then `proxy` must be valid.
     * @param[in] is_important If true, then log failures with higher severity.
     * @param[in] proxy Proxy to connect through if `proxy.IsValid()` is true.
     * @param[out] proxy_failed If `proxy` is valid and the connection failed because of the
     * proxy, then it will be set to true.
     * @param[out] me If the connection was successful then this is set to the address on the
     * local side of the socket.
     * @return Newly generated node id, or std::nullopt if the operation fails.
     */
    std::optional<NodeId> ConnectAndMakeNodeId(const std::variant<CService, StringHostIntPort>& to,
                                               bool is_important,
                                               const Proxy& proxy,
                                               bool& proxy_failed,
                                               CService& me);

    /**
     * Disconnect a given peer by closing its socket and release resources occupied by it.
     * @return Whether the peer existed and its socket was closed by this call.
     */
    bool CloseConnection(NodeId node_id);

    /**
     * Try to send some data to the given node.
     * @param[in] node_id Identifier of the node to send to.
     * @param[in] data The data to send, it might happen that only a prefix of this is sent.
     * @param[in] will_send_more Used as an optimization if the caller knows that they will
     * be sending more data soon after this call.
     * @param[out] errmsg If <0 is returned then this will contain a human readable message
     * explaining the error.
     * @retval >=0 The number of bytes actually sent.
     * @retval <0 A permanent error has occurred.
     */
    ssize_t SendBytes(NodeId node_id,
                      Span<const unsigned char> data,
                      bool will_send_more,
                      std::string& errmsg) const;

    /**
     * Close all sockets.
     */
    void CloseSockets();

    //
    // Pure virtual functions must be implemented by children classes.
    //

    /**
     * Be notified when a new connection has been accepted.
     * @param[in] node_id Id of the newly accepted connection.
     * @param[in] me The address and port at our side of the connection.
     * @param[in] them The address and port at the peer's side of the connection.
     * @retval true The new connection was accepted at the higher level.
     * @retval false The connection was refused at the higher level, so the
     * associated socket and node_id should be discarded by `SockMan`.
     */
    virtual bool EventNewConnectionAccepted(NodeId node_id,
                                            const CService& me,
                                            const CService& them) = 0;

    /**
     * Called when the socket is ready to send data and `ShouldTryToSend()` has
     * returned true. This is where the higher level code serializes its messages
     * and calls `SockMan::SendBytes()`.
     * @param[in] node_id Id of the node whose socket is ready to send.
     * @param[out] cancel_recv Should always be set upon return and if it is true,
     * then the next attempt to receive data from that node will be omitted.
     */
    virtual void EventReadyToSend(NodeId node_id, bool& cancel_recv) = 0;

    /**
     * Called when new data has been received.
     * @param[in] node_id Node for which the data arrived.
     * @param[in] data Data buffer.
     * @param[in] n Number of bytes in `data`.
     */
    virtual void EventGotData(NodeId node_id, const uint8_t* data, size_t n) = 0;

    /**
     * Called when the remote peer has sent an EOF on the socket. This is a graceful
     * close of their writing side, we can still send and they will receive, if it
     * makes sense at the application level.
     * @param[in] node_id Node whose socket got EOF.
     */
    virtual void EventGotEOF(NodeId node_id) = 0;

    /**
     * Called when we get an irrecoverable error trying to read from a socket.
     * @param[in] node_id Node whose socket got an error.
     * @param[in] errmsg Message describing the error.
     */
    virtual void EventGotPermanentReadError(NodeId node_id, const std::string& errmsg) = 0;

    //
    // Non-pure virtual functions can be overridden by children classes or left
    // alone to use the default implementation from SockMan.
    //

    /**
     * SockMan would only call EventReadyToSend() if this returns true.
     * Can be used to temporary pause sends for a node.
     * The implementation in SockMan always returns true.
     * @param[in] node_id Node for which to confirm or cancel a call to EventReadyToSend().
     */
    virtual bool ShouldTryToSend(NodeId node_id) const;

    /**
     * SockMan would only call Recv() on a node's socket if this returns true.
     * Can be used to temporary pause receives for a node.
     * The implementation in SockMan always returns true.
     * @param[in] node_id Node for which to confirm or cancel a receive.
     */
    virtual bool ShouldTryToRecv(NodeId node_id) const;

    /**
     * SockMan has completed the current send+recv iteration for a node.
     * It will do another send+recv for this node after processing all other nodes.
     * Can be used to execute periodic tasks for a given node.
     * The implementation in SockMan does nothing.
     * @param[in] node_id Node for which send+recv has been done.
     */
    virtual void EventIOLoopCompletedForNode(NodeId node_id);

    /**
     * SockMan has completed send+recv for all nodes.
     * Can be used to execute periodic tasks for all nodes.
     * The implementation in SockMan does nothing.
     */
    virtual void EventIOLoopCompletedForAllPeers();

    /**
     * Be notified of a change in the state of listening for incoming I2P connections.
     * The default behavior, implemented by `SockMan`, is to ignore this event.
     * @param[in] addr Our listening address.
     * @param[in] success If true then the listen succeeded and we are now
     * listening for incoming I2P connections at `addr`. If false then the
     * call failed and now we are not listening (even if this was invoked
     * before with `true`).
     */
    virtual void EventI2PListen(const CService& addr, bool success);
};