Current File : //backups/router/usr/local/include/kea/config/base_command_mgr.h
// Copyright (C) 2017-2023 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 BASE_COMMAND_MGR_H
#define BASE_COMMAND_MGR_H
#include <cc/data.h>
#include <exceptions/exceptions.h>
#include <functional>
#include <map>
#include <string>
namespace isc {
namespace config {
/// @brief Exception indicating that the handler specified is not valid
class InvalidCommandHandler : public Exception {
public:
InvalidCommandHandler(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) { };
};
/// @brief Exception indicating that the command name is not valid
class InvalidCommandName : public Exception {
public:
InvalidCommandName(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) { };
};
/// @brief Commands Manager, responsible for processing external commands.
///
/// Commands Manager is a generic interface for handling external commands.
/// Commands are received over control sockets. Derivations of this class
/// provide implementations of the control socket layers, e.g. unix domain
/// sockets, TCP sockets etc. This base class merely provides methods to manage
/// command handling functions, i.e. register commands, deregister commands.
/// It also includes a @ref BaseCommandMgr::processCommand method which
/// uses the command as an input and invokes appropriate handlers.
///
/// The commands and responses are formatted using JSON.
/// See https://gitlab.isc.org/isc-projects/kea/wikis/designs/Stats-design
/// for details.
///
/// Below is an example of the command using JSON format:
/// @code
/// {
/// "command": "statistic-get",
/// "arguments": {
/// "name": "received-packets"
/// }
/// }
/// @endcode
///
/// And the response is:
///
/// @code
/// {
/// "result": 0,
/// "arguments": {
/// "received-packets": [ [ 1234, "2015-04-15 12:34:45.123" ] ]
/// }
/// }
/// @endcode
///
/// BaseCommandsMgr does not implement the commands (except one,
/// "list-commands") itself, but rather provides an interface
/// (see @ref registerCommand, @ref deregisterCommand, @ref processCommand)
/// for other components to use it.
class BaseCommandMgr {
public:
/// @brief Defines command handler type
///
/// Command handlers are expected to use this format.
///
/// @param name name of the commands
/// @param params parameters specific to the command
/// @return response (created with createAnswer())
typedef std::function<isc::data::ConstElementPtr (const std::string& name,
const isc::data::ConstElementPtr& params)> CommandHandler;
/// @brief Defines extended command handler type.
///
/// This command handler includes third parameter which holds the
/// entire command control message. The handler can retrieve
/// additional information from this parameter, e.g. 'service'.
///
/// @param name name of the commands
/// @param params parameters specific to the command
/// @param original original control command.
/// @return response (created with createAnswer())
typedef std::function<isc::data::ConstElementPtr (const std::string& name,
const isc::data::ConstElementPtr& params,
const isc::data::ConstElementPtr& original)> ExtendedCommandHandler;
/// @brief Constructor.
///
/// Registers hookpoint "command-processed"
/// Registers "list-commands" command.
BaseCommandMgr();
/// @brief Destructor.
virtual ~BaseCommandMgr() { };
/// @brief Triggers command processing.
///
/// This method processes specified command. The command is specified using
/// a single Element. See @ref BaseCommandMgr for description of its syntax.
/// After the command has been handled, callouts for the hook point,
/// "command-processed" will be invoked.
///
/// This method is virtual so it can be overridden in derived classes to
/// pre-process command and post-process response if necessary.
///
/// This method is an entry point for dealing with a command. Internally
/// it calls @c BaseCommandMgr::handleCommand.
///
/// @param cmd Pointer to the data element representing command in JSON
/// format.
virtual isc::data::ConstElementPtr
processCommand(const isc::data::ConstElementPtr& cmd);
/// @brief Registers specified command handler for a given command
///
/// @param cmd Name of the command to be handled.
/// @param handler Pointer to the method that will handle the command.
void registerCommand(const std::string& cmd, CommandHandler handler);
/// @brief Registers specified command handler for a given command.
///
/// This variant of the method uses extended command handler which, besides
/// command name and arguments, also has a third parameter 'original_cmd'
/// in its signature. Such handlers can retrieve additional parameters from
/// the command, e.g. 'service' indicating where the command should be
/// routed.
///
/// @param cmd Name of the command to be handled.
/// @param handler Pointer to the method that will handle the command.
void registerExtendedCommand(const std::string& cmd,
ExtendedCommandHandler handler);
/// @brief Deregisters specified command handler.
///
/// @param cmd Name of the command that's no longer handled.
void deregisterCommand(const std::string& cmd);
/// @brief Auxiliary method that removes all installed commands.
///
/// The only unwipeable method is list-commands, which is internally
/// handled at all times.
void deregisterAll();
/// @brief returns a hash of a given Element structure
///
/// The hash is currently implemented as SHA256 on the string
// representation of the structure.
///
/// @param config typically full config, but hash can be calculated on any structure
/// @return hash of string representation
static std::string getHash(const isc::data::ConstElementPtr& config);
protected:
/// @brief Handles the command having a given name and arguments.
///
/// This method can be overridden in the derived classes to provide
/// custom logic for processing commands. For example, the
/// @ref HookedCommandMgr extends this method to delegate commands
/// processing to a hook library.
///
/// @param cmd_name Command name.
/// @param params Command arguments.
/// @param original_cmd Pointer to the entire command received. It may
/// be sometimes useful to retrieve additional parameters from this
/// command.
///
/// @return Pointer to the const data element representing response
/// to a command.
virtual isc::data::ConstElementPtr
handleCommand(const std::string& cmd_name,
const isc::data::ConstElementPtr& params,
const isc::data::ConstElementPtr& original_cmd);
struct HandlersPair {
CommandHandler handler;
ExtendedCommandHandler extended_handler;
};
/// @brief Type of the container for command handlers.
typedef std::map<std::string, HandlersPair> HandlerContainer;
/// @brief Container for command handlers.
HandlerContainer handlers_;
private:
/// @brief 'list-commands' command handler.
///
/// This method implements command 'list-commands'. It returns a list of all
/// currently supported commands.
///
/// @param name Name of the command (should always be 'list-commands').
/// @param params Additional parameters (ignored).
///
/// @return Pointer to the structure that includes all currently supported
/// commands.
isc::data::ConstElementPtr
listCommandsHandler(const std::string& name,
const isc::data::ConstElementPtr& params);
};
} // end of namespace isc::config
} // end of namespace isc
#endif
Mini Shell