ca_process.h 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152
  1. // Copyright (C) 2016-2017 Internet Systems Consortium, Inc. ("ISC")
  2. //
  3. // This Source Code Form is subject to the terms of the Mozilla Public
  4. // License, v. 2.0. If a copy of the MPL was not distributed with this
  5. // file, You can obtain one at http://mozilla.org/MPL/2.0/.
  6. #ifndef CTRL_AGENT_PROCESS_H
  7. #define CTRL_AGENT_PROCESS_H
  8. #include <agent/ca_cfg_mgr.h>
  9. #include <http/listener.h>
  10. #include <process/d_process.h>
  11. #include <vector>
  12. namespace isc {
  13. namespace agent {
  14. /// @brief Kea Control Agent Application Process
  15. ///
  16. /// CtrlAgentProcess provides top level application logic for the Control
  17. /// Agent, a process managing Kea servers.
  18. ///
  19. /// The Control Agent receives JSON control commands over HTTP and forwards
  20. /// the JSON commands to the respective Kea servers. The JSON command
  21. /// includes a name of the server to which the command pertains. After
  22. /// receiving a response from the Kea server it is sent back over HTTP
  23. /// to the control API client.
  24. ///
  25. /// Some commands are handled by the Control Agent process itself, rather than
  26. /// forwarded to the Kea servers. An example of such command is the one that
  27. /// instructs the agent to start a specific service.
  28. class CtrlAgentProcess : public process::DProcessBase {
  29. public:
  30. /// @brief Constructor
  31. ///
  32. /// @param name name is a text label for the process. Generally used
  33. /// in log statements, but otherwise arbitrary.
  34. /// @param io_service is the io_service used by the caller for
  35. /// asynchronous event handling.
  36. CtrlAgentProcess(const char* name, const asiolink::IOServicePtr& io_service);
  37. /// @brief Destructor
  38. virtual ~CtrlAgentProcess();
  39. /// @brief Initialize the Control Agent process.
  40. ///
  41. /// This is invoked by the controller after command line arguments but
  42. /// prior to configuration reception. The base class provides this method
  43. /// as a place to perform any derivation-specific initialization steps
  44. /// that are inappropriate for the constructor but necessary prior to
  45. /// launch.
  46. virtual void init();
  47. /// @brief Implements the process's event loop.
  48. ///
  49. /// @throw DProcessBaseError if an operational error is encountered.
  50. virtual void run();
  51. /// @brief Initiates the process's shutdown process.
  52. ///
  53. /// This is last step in the shutdown event callback chain, that is
  54. /// intended to notify the process it is to begin its shutdown process.
  55. ///
  56. /// @param args an Element set of shutdown arguments (if any) that are
  57. /// supported by the process derivation.
  58. ///
  59. /// @return an Element that contains the results of argument processing,
  60. /// consisting of an integer status value (0 means successful,
  61. /// non-zero means failure), and a string explanation of the outcome.
  62. ///
  63. /// @throw DProcessBaseError if an operational error is encountered.
  64. virtual isc::data::ConstElementPtr
  65. shutdown(isc::data::ConstElementPtr args);
  66. /// @brief Processes the given configuration.
  67. ///
  68. /// This method may be called multiple times during the process lifetime.
  69. /// Certainly once during process startup, and possibly later if the user
  70. /// alters configuration. This method must not throw, it should catch any
  71. /// processing errors and return a success or failure answer as described
  72. /// below.
  73. ///
  74. /// A usual problem related to the system reconfiguration is how to preserve
  75. /// configuration integrity in case of errors. In this case, when the
  76. /// HTTP listener's configuration is modified there is a need to close all
  77. /// existing connections and gracefully shutdown the listener's instance.
  78. /// This, however, makes it possible that the control agent looses
  79. /// connectivity if opening a new listener is unsuccessful. In fact, this
  80. /// is quite possible scenario when the user is setting up the listener to
  81. /// use a restricted port range or non-existing IP address. In this case,
  82. /// the configuration parser will not signal the problem because IP address
  83. /// and/or port are syntactically correcect.
  84. ///
  85. /// This method deals with this problem by opening a new listener aside of
  86. /// the currently running listener (if the new listener settings are
  87. /// different than current settings). Both instances are held until the
  88. /// CtrlAgentProcess::garbageCollectListeners is invoked, which
  89. /// removes any listeners which are no longer used.
  90. ///
  91. /// @param config_set a new configuration (JSON) for the process
  92. /// @param check_only true if configuration is to be verified only, not applied
  93. /// @return an Element that contains the results of configuration composed
  94. /// of an integer status value (0 means successful, non-zero means failure),
  95. /// and a string explanation of the outcome.
  96. virtual isc::data::ConstElementPtr
  97. configure(isc::data::ConstElementPtr config_set,
  98. bool check_only = false);
  99. /// @brief Returns a pointer to the configuration manager.
  100. CtrlAgentCfgMgrPtr getCtrlAgentCfgMgr();
  101. /// @brief Returns a const pointer to the HTTP listener used by the process.
  102. ///
  103. /// @return Const pointer to the currently used listener or null pointer if
  104. /// we're not listening. In fact, the latter should never be the case given
  105. /// that we provide default listener configuration.
  106. http::ConstHttpListenerPtr getHttpListener() const;
  107. /// @brief Checks if the process is listening to the HTTP requests.
  108. ///
  109. /// @return true if the process is listening.
  110. bool isListening() const;
  111. private:
  112. /// @brief Removes listeners which are no longer in use.
  113. ///
  114. /// This method should be called after executing
  115. /// @ref CtrlAgentProcess::configure to remove listeners used previously
  116. /// (no longer used because the listening address and port has changed as
  117. // a result of the reconfiguration). If there are no listeners additional
  118. /// to the one that is currently in use, the method has no effect.
  119. void garbageCollectListeners();
  120. /// @brief Polls all ready handlers and then runs one handler if none
  121. /// handlers have been executed as a result of polling.
  122. ///
  123. /// @return Number of executed handlers.
  124. size_t runIO();
  125. /// @brief Holds a list of pointers to the active listeners.
  126. std::vector<http::HttpListenerPtr> http_listeners_;
  127. };
  128. /// @brief Defines a shared pointer to CtrlAgentProcess.
  129. typedef boost::shared_ptr<CtrlAgentProcess> CtrlAgentProcessPtr;
  130. }; // namespace isc::agent
  131. }; // namespace isc
  132. #endif // CTRL_AGENT_PROCESS_H