path: root/src/lib/process/d_controller.h

// Copyright (C) 2013-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 D_CONTROLLER_H
#define D_CONTROLLER_H

#include <asiolink/io_service.h>
#include <asiolink/io_service_signal.h>
#include <cc/data.h>
#include <exceptions/exceptions.h>
#include <log/logger_support.h>
#include <process/daemon.h>
#include <process/d_log.h>
#include <process/d_process.h>

#include <boost/shared_ptr.hpp>
#include <boost/noncopyable.hpp>

#include <string>
#include <set>

namespace isc {
namespace process {

/// @brief Exception thrown when the command line is invalid.
/// Can be used to transmit negative messages too.
class InvalidUsage : public isc::Exception {
public:
    InvalidUsage(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) { };
};

/// @brief Exception used to convey version info upwards.
/// Since command line argument parsing is done as part of
/// DControllerBase::launch(), it uses this exception to propagate
/// version information up to main(), when command line argument
/// -v, -V or -W is given. Can be used to transmit positive messages too.
class VersionMessage : public isc::Exception {
public:
    VersionMessage(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) { };
};

/// @brief Exception thrown when the controller launch fails.
class LaunchError: public isc::Exception {
public:
    LaunchError (const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) { };
};

/// @brief Exception thrown when the application process fails.
class ProcessInitError: public isc::Exception {
public:
    ProcessInitError (const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) { };
};

/// @brief Exception thrown when the application process encounters an
/// operation in its event loop (i.e. run method).
class ProcessRunError: public isc::Exception {
public:
    ProcessRunError (const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) { };
};

/// @brief Exception thrown when the controller encounters an operational error.
class DControllerBaseError : public isc::Exception {
public:
    DControllerBaseError (const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) { };
};

/// @brief Defines a shared pointer to DControllerBase.
class DControllerBase;
typedef boost::shared_ptr<DControllerBase> DControllerBasePtr;

/// @brief Application Controller
///
/// DControllerBase is an abstract singleton which provides the framework and
/// services for managing an application process that implements the
/// DProcessBase interface.  It runs the process like a stand-alone, command
/// line driven executable, which must be supplied a configuration file at
/// startup. It coordinates command line argument parsing, process
/// instantiation and initialization, and runtime control through external
/// command and configuration event handling.
/// It creates the IOService instance which is used for runtime control
/// events and passes the IOService into the application process at process
/// creation.
/// It provides the callback handlers for command and configuration events
/// which could be triggered by an external source.  Such sources are intended
/// to be registered with and monitored by the controller's IOService such that
/// the appropriate handler can be invoked.
///
/// DControllerBase provides dynamic configuration file reloading upon receipt
/// of SIGHUP, and graceful shutdown upon receipt of either SIGINT or SIGTERM.
///
/// NOTE: Derivations must supply their own static singleton instance method(s)
/// for creating and fetching the instance. The base class declares the instance
/// member in order for it to be available for static callback functions.
class DControllerBase : public Daemon {
public:
    /// @brief Constructor
    ///
    /// @param app_name is display name of the application under control. This
    /// name appears in log statements.
    /// @param bin_name is the name of the application executable.
    DControllerBase(const char* app_name, const char* bin_name);

    /// @brief Destructor
    virtual ~DControllerBase();

    /// @brief returns Kea version on stdout and exit.
    /// redeclaration/redefinition. @ref isc::process::Daemon::getVersion()
    std::string getVersion(bool extended);

    /// @brief Acts as the primary entry point into the controller execution
    /// and provides the outermost application control logic:
    ///
    /// 1. parse command line arguments
    /// 2. instantiate and initialize the application process
    /// 3. load the configuration file
    /// 4. record the start timestamp
    /// 5. initialize signal handling
    /// 6. start and wait on the application process event loop
    /// 7. exit to the caller
    ///
    /// It is intended to be called from main() and be given the command line
    /// arguments.
    ///
    /// This function can be run in "test mode". It prevents initialization
    /// of module logger. This is used in unit tests which initialize logger
    /// in their main function. Such a logger uses environmental variables to
    /// control severity, verbosity etc.
    ///
    /// @param argc  is the number of command line arguments supplied
    /// @param argv  is the array of string (char *) command line arguments
    /// @param test_mode is a bool value which indicates if
    /// @c DControllerBase::launch should be run in the test mode (if true).
    /// This parameter doesn't have default value to force test implementers to
    /// enable test mode explicitly.
    ///
    /// @throw throws one of the following exceptions:
    /// InvalidUsage - Indicates invalid command line.
    /// ProcessInitError  - Failed to create and initialize application
    /// process object.
    /// ProcessRunError - A fatal error occurred while in the application
    /// process event loop.
    /// @return The value from @c Daemon::getExitValue().
    virtual int launch(int argc, char* argv[], const bool test_mode);

    /// @brief Instance method invoked by the configuration event handler and
    /// which processes the actual configuration update.  Provides behavioral
    /// path for both integrated and stand-alone modes. The current
    /// implementation will merge the configuration update into the existing
    /// configuration and then invoke the application process' configure method.
    ///
    /// @param  new_config is the new configuration
    ///
    /// @return returns an Element that contains the results of configuration
    /// update composed of an integer status value (0 means successful,
    /// non-zero means failure), and a string explanation of the outcome.
    virtual isc::data::ConstElementPtr updateConfig(isc::data::ConstElementPtr
                                                    new_config);

    /// @brief Instance method invoked by the configuration event handler and
    /// which processes the actual configuration check.  Provides behavioral
    /// path for both integrated and stand-alone modes. The current
    /// implementation will merge the configuration update into the existing
    /// configuration and then invoke the application process' configure method
    /// with a final rollback.
    ///
    /// @param  new_config is the new configuration
    ///
    /// @return returns an Element that contains the results of configuration
    /// update composed of an integer status value (0 means successful,
    /// non-zero means failure), and a string explanation of the outcome.
    virtual isc::data::ConstElementPtr checkConfig(isc::data::ConstElementPtr
                                                   new_config);

    /// @brief Reconfigures the process from a configuration file
    ///
    /// By default the file is assumed to be a JSON text file whose contents
    /// include at least:
    ///
    /// @code
    ///  { "<module-name>": {<module-config>}
    ///  }
    ///
    ///  where:
    ///     module-name : is a label which uniquely identifies the
    ///                   configuration data for this controller's application
    ///
    ///     module-config: a set of zero or more JSON elements which comprise
    ///                    the application's configuration values
    /// @endcode
    ///
    /// To translate the JSON content into Elements, @c parseFile() is called
    /// first.  This virtual method provides derivations a means to parse the
    /// file content using an alternate parser.  If it returns an empty pointer
    /// than the JSON parsing providing by Element::fromJSONFile() is called.
    ///
    /// Once parsed, the method extracts the set of configuration
    /// elements for the module-name that matches the controller's app_name_,
    /// looks for the loggers entry and, if present uses it to configure
    /// logging. It then passes that set into @c updateConfig() (or
    /// @c checkConfig()).
    ///
    /// The file may contain an arbitrary number of other modules.
    ///
    /// @return returns an Element that contains the results of configuration
    /// update composed of an integer status value (0 means successful,
    /// non-zero means failure), and a string explanation of the outcome.
    virtual isc::data::ConstElementPtr configFromFile();

    /// @brief Fetches the name of the application under control.
    ///
    /// @return returns the controller service name string
    std::string getAppName() const {
        return (app_name_);
    }

    /// @brief Fetches the name of the application executable.
    ///
    /// @return returns the controller logger name string
    std::string getBinName() const {
        return (bin_name_);
    }

    /// @brief handler for version-get command
    ///
    /// This method handles the version-get command. It returns the basic and
    /// extended version.
    ///
    /// @param command (ignored)
    /// @param args (ignored)
    /// @return answer with version details.
    isc::data::ConstElementPtr
    versionGetHandler(const std::string& command,
                      isc::data::ConstElementPtr args);

    /// @brief handler for 'build-report' command
    ///
    /// This method handles build-report command. It returns the output printed
    /// by configure script which contains most compilation parameters.
    ///
    /// @param command (ignored)
    /// @param args (ignored)
    /// @return answer with build report
    isc::data::ConstElementPtr
    buildReportHandler(const std::string& command,
                       isc::data::ConstElementPtr args);

    /// @brief handler for config-get command
    ///
    /// This method handles the config-get command, which retrieves
    /// the current configuration and returns it in response.
    ///
    /// @param command (ignored)
    /// @param args (ignored)
    /// @return current configuration wrapped in a response
    isc::data::ConstElementPtr
    configGetHandler(const std::string& command,
                     isc::data::ConstElementPtr args);

    /// @brief handler for config-hash-get command
    ///
    /// This method handles the config-hash-get command, which retrieves
    /// the current configuration and returns it in response.
    ///
    /// @param command (ignored)
    /// @param args (ignored)
    /// @return hash of current configuration wrapped in a response
    isc::data::ConstElementPtr
    configHashGetHandler(const std::string& command,
                         isc::data::ConstElementPtr args);

    /// @brief handler for config-write command
    ///
    /// This handle processes write-config command, which writes the
    /// current configuration to disk. This command takes one optional
    /// parameter called filename. If specified, the current configuration
    /// will be written to that file. If not specified, the file used during
    /// Kea start-up will be used. To avoid any exploits, the path is
    /// always relative and .. is not allowed in the filename. This is
    /// a security measure against exploiting file writes remotely.
    ///
    /// @param command (ignored)
    /// @param args may contain optional string argument filename
    /// @return status of the configuration file write
    isc::data::ConstElementPtr
    configWriteHandler(const std::string& command,
                       isc::data::ConstElementPtr args);

    /// @brief handler for config-test command
    ///
    /// This method handles the config-test command, which checks
    /// configuration specified in args parameter.
    ///
    /// @param command (ignored)
    /// @param args configuration to be checked.
    /// @return status of the command
    isc::data::ConstElementPtr
    configTestHandler(const std::string& command,
                      isc::data::ConstElementPtr args);

    /// @brief handler for config-reload command
    ///
    /// This method handles the config-reload command, which reloads
    /// the configuration file.
    ///
    /// @param command (ignored)
    /// @param args (ignored)
    /// @return status of the command
    isc::data::ConstElementPtr
    configReloadHandler(const std::string& command,
                        isc::data::ConstElementPtr args);

    /// @brief handler for config-set command
    ///
    /// This method handles the config-set command, which loads
    /// configuration specified in args parameter.
    ///
    /// @param command (ignored)
    /// @param args configuration to be checked.
    /// @return status of the command
    isc::data::ConstElementPtr
    configSetHandler(const std::string& command,
                     isc::data::ConstElementPtr args);

    /// @brief handler for 'shutdown' command
    ///
    /// This method handles shutdown command. It initiates the shutdown procedure
    /// using CPL methods.
    /// @param command (ignored)
    /// @param args (ignored)
    /// @return answer confirming that the shutdown procedure is started
    isc::data::ConstElementPtr
    shutdownHandler(const std::string& command,
                    isc::data::ConstElementPtr args);

    /// @brief handler for server-tag-get command
    ///
    /// This method handles the server-tag-get command, which retrieves
    /// the current server tag and returns it in response.
    ///
    /// @param command (ignored)
    /// @param args (ignored)
    /// @return current configuration wrapped in a response
    isc::data::ConstElementPtr
    serverTagGetHandler(const std::string& command,
                        isc::data::ConstElementPtr args);

    /// @brief handler for status-get command
    ///
    /// This method handles the status-get command, which retrieves
    /// the server process information i.e. the pid and returns it in
    /// response.
    ///
    /// @param command (ignored)
    /// @param args (ignored)
    /// @return process information wrapped in a response
    isc::data::ConstElementPtr
    statusGetHandler(const std::string& command,
                     isc::data::ConstElementPtr args);

protected:
    /// @brief Virtual method that provides derivations the opportunity to
    /// support additional command line options.  It is invoked during command
    /// line argument parsing (see parseArgs method) if the option is not
    /// recognized as a stock DControllerBase option.
    ///
    /// @param option is the option "character" from the command line, without
    /// any prefixing hyphen(s)
    /// @param optarg is the argument value (if one) associated with the option
    ///
    /// @return must return true if the option was valid, false if it is
    /// invalid. (Note the default implementation always returns false.)
    virtual bool customOption(int option, char *optarg);

    /// @brief Abstract method that is responsible for instantiating the
    /// application process object. It is invoked by the controller after
    /// command line argument parsing as part of the process initialization
    /// (see initProcess method).
    ///
    /// @return returns a pointer to the new process object (DProcessBase*)
    /// or NULL if the create fails.
    /// Note this value is subsequently wrapped in a smart pointer.
    virtual DProcessBase* createProcess() = 0;

    /// @brief Virtual method which can be used to contribute derivation
    /// specific usage text.  It is invoked by the usage() method under
    /// invalid usage conditions.
    ///
    /// @return returns the desired text.
    virtual const std::string getUsageText() const {
        return ("");
    }

    /// @brief Virtual method which returns a string containing the option
    /// letters for any custom command line options supported by the derivation.
    /// These are added to the stock options of "c", "d", ..., during command
    /// line interpretation.
    ///
    /// @return returns a string containing the custom option letters.
    virtual const std::string getCustomOpts() const {
        return ("");
    }

    /// @brief Check the configuration
    ///
    /// Called by @c launch() when @c check_only_ mode is enabled
    /// @throw VersionMessage when successful but a message should be displayed
    /// @throw InvalidUsage when an error was detected
    void checkConfigOnly();

    /// @brief Application-level signal processing method.
    ///
    /// This method is the last step in processing a OS signal occurrence.
    /// It currently supports the following signals as follows:
    /// -# SIGHUP - instigates reloading the configuration file
    /// -# SIGINT - instigates a graceful shutdown
    /// -# SIGTERM - instigates a graceful shutdown
    /// If it receives any other signal, it will issue a debug statement and
    /// discard it.
    /// Derivations wishing to support additional signals could override this
    /// method with one that: processes the signal if it is one of additional
    /// signals, otherwise invoke this method (DControllerBase::processSignal())
    /// with the signal value.
    /// @todo Provide a convenient way for derivations to register additional
    /// signals.
    virtual void processSignal(int signum);

    /// @brief Supplies whether or not verbose logging is enabled.
    ///
    /// @return returns true if verbose logging is enabled.
    bool isVerbose() const {
        return (verbose_);
    }

    /// @brief Method for enabling or disabling verbose logging.
    ///
    /// @param value is the new value to assign the flag.
    void setVerbose(bool value) {
        verbose_ = value;
    }

    /// @brief Supplies whether or not check only mode is enabled.
    ///
    /// @return returns true if check only is enabled.
    bool isCheckOnly() const {
        return (check_only_);
    }

    /// @brief Method for enabling or disabling check only mode.
    ///
    /// @todo this method and @c setVerbose are currently not used.
    ///
    /// @param value is the new value to assign the flag.
    void setCheckOnly(bool value) {
        check_only_ = value;
    }

    /// @brief Getter for fetching the controller's IOService
    ///
    /// @return returns a pointer reference to the IOService.
    asiolink::IOServicePtr& getIOService() {
        return (io_service_);
    }

    /// @brief Static getter which returns the singleton instance.
    ///
    /// @return returns a pointer reference to the private singleton instance
    /// member.
    static DControllerBasePtr& getController() {
        return (controller_);
    }

    /// @brief Static setter which sets the singleton instance.
    ///
    /// @param controller is a pointer to the singleton instance.
    ///
    /// @throw throws DControllerBase error if an attempt is made to set the
    /// instance a second time.
    static void setController(const DControllerBasePtr& controller);

    /// @brief Processes the command line arguments. It is the first step
    /// taken after the controller has been launched.  It combines the stock
    /// list of options with those returned by getCustomOpts(), and uses
    /// cstdlib's getopt to loop through the command line.
    /// It handles stock options directly, and passes any custom options into
    /// the customOption method.  Currently there are only some stock options
    /// -c/t for specifying the configuration file, -d for verbose logging,
    /// and -v/V/W for version reports.
    ///
    /// @param argc  is the number of command line arguments supplied
    /// @param argv  is the array of string (char *) command line arguments
    ///
    /// @throw InvalidUsage when there are usage errors.
    /// @throw VersionMessage if the -v, -V or -W arguments is given.
    void parseArgs(int argc, char* argv[]);

    ///@brief Parse a given file into Elements
    ///
    /// This method provides a means for deriving classes to use alternate
    /// parsing mechanisms to parse configuration files into the corresponding
    /// isc::data::Elements. The elements produced must be equivalent to those
    /// which would be produced by the original JSON parsing.  Implementations
    /// should throw when encountering errors.
    ///
    /// The default implementation returns an empty pointer, signifying to
    /// callers that they should submit the file to the original parser.
    ///
    /// @param file_name pathname of the file to parse
    ///
    /// @return pointer to the elements created
    ///
    virtual isc::data::ConstElementPtr parseFile(const std::string& file_name);

    ///@brief Parse text into Elements
    ///
    /// This method provides a means for deriving classes to use alternate
    /// parsing mechanisms to parse configuration text into the corresponding
    /// isc::data::Elements. The elements produced must be equivalent to those
    /// which would be produced by the original JSON parsing.  Implementations
    /// should throw when encountering errors.
    ///
    /// The default implementation returns an empty pointer, signifying to
    /// callers that they should submit the text to the original parser.
    ///
    /// @param input text to parse
    ///
    /// @return pointer to the elements created
    ///
    virtual isc::data::ConstElementPtr parseText(const std::string& input) {
        static_cast<void>(input); // just tu shut up the unused parameter warning
        isc::data::ConstElementPtr elements;
        return (elements);
    }

    /// @brief Instantiates the application process and then initializes it.
    /// This is the second step taken during launch, following successful
    /// command line parsing. It is used to invoke the derivation-specific
    /// implementation of createProcess, following by an invoking of the
    /// newly instantiated process's init method.
    ///
    /// @throw throws DControllerBaseError or indirectly DProcessBaseError
    /// if there is a failure creating or initializing the application process.
    void initProcess();

    /// @brief Invokes the application process's event loop,(DBaseProcess::run).
    /// It is called during launch only after successfully completing the
    /// requested setup: command line parsing, application initialization,
    /// and session establishment (if not stand-alone).
    /// The process event loop is expected to only return upon application
    /// shutdown either in response to the shutdown command or due to an
    /// unrecoverable error.
    ///
    // @throw throws DControllerBaseError or indirectly DProcessBaseError
    void runProcess();

    /// @brief Initiates shutdown procedure.  This method is invoked
    /// by executeCommand in response to the shutdown command. It will invoke
    /// the application process's shutdown method which causes the process to
    /// to begin its shutdown process.
    ///
    /// Note, it is assumed that the process of shutting down is neither
    /// instantaneous nor synchronous.  This method does not "block" waiting
    /// until the process has halted.  Rather it is used to convey the
    /// need to shutdown.  A successful return indicates that the shutdown
    /// has successfully commenced, but does not indicate that the process
    /// has actually exited.
    ///
    /// @return returns an Element that contains the results of shutdown
    /// command composed of an integer status value (0 means successful,
    /// non-zero means failure), and a string explanation of the outcome.
    ///
    /// @param args is a set of derivation-specific arguments (if any)
    /// for the shutdown command.
    isc::data::ConstElementPtr shutdownProcess(isc::data::ConstElementPtr args);

    /// @brief Initializes signal handling
    ///
    /// This method configures the controller to catch and handle signals.
    /// It instantiates a IOSignalSet which listens for SIGHUP, SIGINT, and
    /// SIGTERM.
    void initSignalHandling();

    /// @brief Fetches the current process
    ///
    /// @return a pointer to the current process instance.
    DProcessBasePtr getProcess() {
        return (process_);
    }

    /// @brief Prints the program usage text to std error.
    ///
    /// @param text is a string message which will preceded the usage text.
    /// This is intended to be used for specific usage violation messages.
    void usage(const std::string& text);

    /// @brief Fetches text containing additional version specifics
    ///
    /// This method is provided so derivations can append any additional
    /// desired information such as library dependencies to the extended
    /// version text returned when DControllerBase::getVersion(true) is
    /// invoked.
    /// @return a string containing additional version info
    virtual std::string getVersionAddendum() { return (""); }

    /// @brief Deals with other (i.e. not application name) global objects.
    ///
    /// Code shared between configuration handlers:
    ///  - check obsolete or unknown (aka unsupported) objects.
    ///
    /// @param args Command arguments.
    /// @return Error message or empty string.
    std::string handleOtherObjects(isc::data::ConstElementPtr args);

private:
    /// @brief Name of the service under control.
    /// This name is used as the configuration module name and appears in log
    /// statements.
    std::string app_name_;

    /// @brief Name of the service executable.
    /// By convention this matches the executable name. It is also used to
    /// establish the logger name.
    std::string bin_name_;

    /// @brief Indicates if the verbose logging mode is enabled.
    bool verbose_;

    /// @brief Indicates if the check only mode for the configuration
    /// is enabled (usually specified by the command line -t argument).
    bool check_only_;

    /// @brief Pointer to the instance of the process.
    ///
    /// This is required for config and command handlers to gain access to
    /// the process
    DProcessBasePtr process_;

    /// @brief Shared pointer to an IOService object, used for ASIO operations.
    isc::asiolink::IOServicePtr io_service_;

    /// @brief ASIO signal set.
    isc::asiolink::IOSignalSetPtr io_signal_set_;

    /// @brief Singleton instance value.
    static DControllerBasePtr controller_;

    // DControllerTest is named a friend class to facilitate unit testing while
    // leaving the intended member scopes intact.
    friend class DControllerTest;

    /// @brief Structure used in parseArgs() to reset arguments in case parseArgs() is called again.
    struct ExhaustOptions {
        ExhaustOptions(int argc, char* argv[], std::string opts)
            : argc_(argc), argv_(argv), opts_(opts) {
        }
        ~ExhaustOptions() {
            while (getopt(argc_, argv_, opts_.c_str()) != -1) {
            }
        }

    private:
        int argc_;
        char** argv_;
        std::string opts_;
    };
};

}  // namespace process
}  // namespace isc

#endif