// Copyright (C) 2017-2024 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.

#ifndef CLIENT_CONNECTION_H
#define CLIENT_CONNECTION_H

#include <asiolink/io_service.h>
#include <cc/json_feed.h>
#include <boost/shared_ptr.hpp>
#include <functional>

namespace isc {
namespace config {

class ClientConnectionImpl;

/// @brief Represents client side connection over the unix domain socket.
///
/// This class represents a client side connection between the controlling
/// client and the server exposing control API over a unix domain socket.
/// In particular, this class is used by the Kea Control Agent to establish
/// connections with respective Kea services to forward received commands.
/// As of Kea 1.2 the servers can handle a single connection at the time.
/// In the future, we're planning to support multiple simulatenous connections.
/// In this case, each connection will be handled by a unique instance of the
/// @ref ClientConnection class.
///
/// The @ref ClientConnection supports asynchronous connections. A caller
/// creates an instance of the @ref ClientConnection and calls
/// @ref ClientConnection::start to start asynchronous communication with
/// a remote server. The caller provides a pointer to the callback function
/// (handler) which will be called when the communication with the server
/// completes, i.e. the command is sent to the server and the response
/// from the server is received. If an error occurs, the callback is
/// invoked with an error code indicating a reason for the failure.
///
/// The documentation of the @ref ClientConnection::start explains the
/// sequence of operations performed by this class.
///
/// Even though the @ref ClientConnection is asynchronous in nature, it
/// can also be used in cases requiring synchronous communication. As it
/// has been already mentioned, the servers in Kea 1.2 do not support
/// multiple concurrent connections. The following pseudo code demonstrates
/// how to perform synchronous transaction using this class.
///
/// @code
/// IOService io_service;
/// ClientConnection conn(io_service);
/// bool cb_invoked = false;
/// conn.start(ClientConnection::SocketPath("/tmp/kea.sock"),
///            ClientConnection::ControlCommand(command),
///            [this, &cb_invoked](const boost::system::error_code& ec,
///                   const ConstJSONFeedPtr& feed) {
///                cb_invoked = true;
///                if (ec) {
///                    ... handle error here ...
///                } else {
///                    ... use feed to retrieve the response ...
///                }
///            }
/// );
/// while (!cb_invoked) {
///     io_service.runOne();
/// }
/// @endcode
///
class ClientConnection {
public:

    /// @name Structures used for strong typing.
    ///
    //@{

    /// @brief Encapsulates socket path.
    struct SocketPath {
        explicit SocketPath(const std::string& socket_path)
            : socket_path_(socket_path) { }

        std::string socket_path_;
    };

    /// @brief Encapsulates control command.
    struct ControlCommand {
        explicit ControlCommand(const std::string control_command)
            : control_command_(control_command) { }

        std::string control_command_;
    };

    /// @brief Encapsulates timeout value.
    struct Timeout {
        explicit Timeout(const long timeout)
            : timeout_(timeout) { }

        long timeout_;
    };

    //@}

    /// @brief Type of the callback invoked when the communication with
    /// the server is complete or an error has occurred.
    typedef std::function<void(const boost::system::error_code& ec,
                               const ConstJSONFeedPtr& feed)> Handler;

    /// @brief Constructor.
    ///
    /// @param io_service Reference to the IO service.
    explicit ClientConnection(const asiolink::IOServicePtr& io_service);

    /// @brief Starts asynchronous transaction with a remote endpoint.
    ///
    /// Starts asynchronous connection with the remote endpoint. If the
    /// connection is successful, the control command is asynchronously
    /// sent to the remote endpoint. When the entire command has been sent,
    /// the response is read asynchronously, possibly in multiple chunks.
    ///
    /// The timeout is specified in milliseconds. The corresponding timer
    /// measures the connection idle time. If the transaction is progressing,
    /// the timer is updated accordingly. If the connection idle time is
    /// longer than the timeout value the connection is closed and the
    /// callback is called with the error code of
    /// @c boost::asio::error::timed_out.
    ///
    /// In other cases, the callback is called with the error code returned
    /// by the boost asynchronous operations. If the transaction is successful
    /// the 'success' status is indicated with the error code. In addition
    /// the instance of the @ref JSONFeed is returned to the caller. It can
    /// be used to retrieve parsed response from the server. Note that the
    /// response may still be malformed, even if no error is signalled in
    /// the handler. The @ref JSONFeed::toElement will return a parsing
    /// error if the JSON appears to be malformed.
    ///
    /// @param socket_path Path to the socket description that the server
    /// is bound to.
    /// @param command Control command to be sent to the server.
    /// @param handler Pointer to the user supplied callback function which
    /// should be invoked when transaction completes or when an error has
    /// occurred during the transaction.
    /// @param timeout Connection timeout in milliseconds.
    void start(const SocketPath& socket_path, const ControlCommand& command,
               Handler handler, const Timeout& timeout = Timeout(5000));

private:

    /// @brief Pointer to the implementation.
    boost::shared_ptr<ClientConnectionImpl> impl_;

};

/// @brief Type of the pointer to the @ref ClientConnection object.
typedef boost::shared_ptr<ClientConnection> ClientConnectionPtr;

} // end of namespace config
} // end of namespace isc

#endif // CLIENT_CONNECTION_H