client_list.h 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565
  1. // Copyright (C) 2012-2013 Internet Systems Consortium, Inc. ("ISC")
  2. //
  3. // Permission to use, copy, modify, and/or distribute this software for any
  4. // purpose with or without fee is hereby granted, provided that the above
  5. // copyright notice and this permission notice appear in all copies.
  6. //
  7. // THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  8. // REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  9. // AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  10. // INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  11. // LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  12. // OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  13. // PERFORMANCE OF THIS SOFTWARE.
  14. #ifndef DATASRC_CONTAINER_H
  15. #define DATASRC_CONTAINER_H
  16. #include <util/memory_segment.h>
  17. #include <dns/name.h>
  18. #include <dns/rrclass.h>
  19. #include <cc/data.h>
  20. #include <exceptions/exceptions.h>
  21. #include "memory/zone_table_segment.h"
  22. #include <datasrc/zone_table_accessor.h>
  23. #include <vector>
  24. #include <boost/shared_ptr.hpp>
  25. #include <boost/scoped_ptr.hpp>
  26. #include <boost/noncopyable.hpp>
  27. namespace isc {
  28. namespace datasrc {
  29. class ZoneFinder;
  30. typedef boost::shared_ptr<ZoneFinder> ZoneFinderPtr;
  31. class DataSourceClient;
  32. typedef boost::shared_ptr<DataSourceClient> DataSourceClientPtr;
  33. class DataSourceClientContainer;
  34. typedef boost::shared_ptr<DataSourceClientContainer>
  35. DataSourceClientContainerPtr;
  36. // XXX: it's better to even hide the existence of the "memory" namespace.
  37. // We should probably consider pimpl for details of ConfigurableClientList
  38. // and hide real definitions except for itself and tests.
  39. namespace memory {
  40. class InMemoryClient;
  41. class ZoneWriter;
  42. }
  43. namespace internal {
  44. class CacheConfig;
  45. }
  46. /// \brief Segment status of the cache
  47. ///
  48. /// Describes the status in which the memory segment for the in-memory cache of
  49. // /given data source is.
  50. enum MemorySegmentState {
  51. /// \brief No segment used for this data source.
  52. ///
  53. /// This is usually a result of the cache being disabled.
  54. SEGMENT_UNUSED,
  55. /// \brief It is a mapped segment and we wait for information how to map
  56. /// it.
  57. SEGMENT_WAITING,
  58. /// \brief The segment is ready to be used.
  59. SEGMENT_INUSE
  60. };
  61. /// \brief Status of one data source.
  62. ///
  63. /// This indicates the status a data soure is in. It is used with segment
  64. /// and cache management, to discover the data sources that need external
  65. /// mapping or local loading.
  66. ///
  67. /// In future, it may be extended for other purposes, such as performing an
  68. /// operation on named data source.
  69. class DataSourceStatus {
  70. public:
  71. /// \brief Constructor
  72. ///
  73. /// Sets initial values. It doesn't matter what is provided for the type
  74. /// if state is SEGMENT_UNUSED, the value is effectively ignored.
  75. DataSourceStatus(const std::string& name, MemorySegmentState state,
  76. const std::string& type) :
  77. name_(name),
  78. type_(type),
  79. state_(state)
  80. {}
  81. /// \brief Get the segment state
  82. MemorySegmentState getSegmentState() const {
  83. return (state_);
  84. }
  85. /// \brief Get the segment type
  86. ///
  87. /// \note Specific values of the type are only meaningful for the
  88. /// corresponding memory segment implementation and modules that
  89. /// directly manage the segments. Other normal applications should
  90. /// treat them as opaque identifiers.
  91. ///
  92. /// \throw isc::InvalidOperation if called and state is SEGMENT_UNUSED.
  93. const std::string& getSegmentType() const {
  94. if (getSegmentState() == SEGMENT_UNUSED) {
  95. isc_throw(isc::InvalidOperation,
  96. "No segment used, no type therefore.");
  97. }
  98. return (type_);
  99. }
  100. /// \brief Get the name.
  101. const std::string& getName() const {
  102. return (name_);
  103. }
  104. private:
  105. std::string name_;
  106. std::string type_;
  107. MemorySegmentState state_;
  108. };
  109. typedef boost::shared_ptr<const ZoneTableAccessor> ConstZoneTableAccessorPtr;
  110. /// \brief The list of data source clients.
  111. ///
  112. /// The purpose of this class is to hold several data source clients and search
  113. /// through them to find one containing a zone best matching a request.
  114. ///
  115. /// All the data source clients should be for the same class. If you need
  116. /// to handle multiple classes, you need to create multiple separate lists.
  117. ///
  118. /// This is an abstract base class. It is not expected we would use multiple
  119. /// implementation inside the servers (but it is not forbidden either), we
  120. /// have it to allow easy testing. It is possible to create a mock-up class
  121. /// instead of creating a full-blown configuration. The real implementation
  122. /// is the ConfigurableClientList.
  123. class ClientList : public boost::noncopyable {
  124. protected:
  125. /// \brief Constructor.
  126. ///
  127. /// It is protected to prevent accidental creation of the abstract base
  128. /// class.
  129. ClientList() {}
  130. public:
  131. /// \brief Virtual destructor
  132. virtual ~ClientList() {}
  133. /// \brief Structure holding the (compound) result of find.
  134. ///
  135. /// As this is read-only structure, we don't bother to create accessors.
  136. /// Instead, all the member variables are defined as const and can be
  137. /// accessed directly.
  138. struct FindResult {
  139. /// \brief Internal class for holding a reference.
  140. ///
  141. /// This is used to make sure the data source client isn't released
  142. /// too soon.
  143. ///
  144. /// \see life_keeper_;
  145. class LifeKeeper {
  146. public:
  147. virtual ~LifeKeeper() {};
  148. };
  149. /// \brief Constructor.
  150. ///
  151. /// It simply fills in the member variables according to the
  152. /// parameters. See the member descriptions for their meaning.
  153. FindResult(DataSourceClient* dsrc_client, const ZoneFinderPtr& finder,
  154. bool exact_match,
  155. const boost::shared_ptr<LifeKeeper>& life_keeper) :
  156. dsrc_client_(dsrc_client),
  157. finder_(finder),
  158. exact_match_(exact_match),
  159. life_keeper_(life_keeper)
  160. {}
  161. /// \brief Negative answer constructor.
  162. ///
  163. /// This constructs a result for negative answer. Both pointers are
  164. /// NULL, and exact_match_ is false.
  165. FindResult() :
  166. dsrc_client_(NULL),
  167. exact_match_(false)
  168. {}
  169. /// \brief Comparison operator.
  170. ///
  171. /// It is needed for tests and it might be of some use elsewhere
  172. /// too.
  173. bool operator ==(const FindResult& other) const {
  174. return (dsrc_client_ == other.dsrc_client_ &&
  175. finder_ == other.finder_ &&
  176. exact_match_ == other.exact_match_);
  177. }
  178. /// \brief The found data source client.
  179. ///
  180. /// The client of the data source containing the best matching zone.
  181. /// If no such data source exists, this is NULL pointer.
  182. ///
  183. /// Note that the pointer is valid only as long the ClientList which
  184. /// returned the pointer is alive and was not reconfigured or you hold
  185. /// a reference to life_keeper_. The ownership is preserved within the
  186. /// ClientList.
  187. DataSourceClient* const dsrc_client_;
  188. /// \brief The finder for the requested zone.
  189. ///
  190. /// This is the finder corresponding to the best matching zone.
  191. /// This may be NULL even in case the datasrc_ is something
  192. /// else, depending on the find options.
  193. ///
  194. /// \see find
  195. const ZoneFinderPtr finder_;
  196. /// \brief If the result is an exact match.
  197. const bool exact_match_;
  198. /// \brief Something that holds the dsrc_client_ valid.
  199. ///
  200. /// As long as you hold the life_keeper_, the dsrc_client_ is
  201. /// guaranteed to be valid.
  202. const boost::shared_ptr<LifeKeeper> life_keeper_;
  203. };
  204. /// \brief Search for a zone through the data sources.
  205. ///
  206. /// This searches the contained data source clients for a one that best
  207. /// matches the zone name.
  208. ///
  209. /// There are two expected usage scenarios. One is answering queries. In
  210. /// this case, the zone finder is needed and the best matching superzone
  211. /// of the searched name is needed. Therefore, the call would look like:
  212. ///
  213. /// \code FindResult result(list->find(queried_name));
  214. /// if (result.dsrc_client_) {
  215. /// if (result.finder_) {
  216. /// createTheAnswer(result.finder_);
  217. /// } else { // broken zone, return SERVFAIL
  218. /// createErrorMessage(Rcode.SERVFAIL());
  219. /// }
  220. /// } else {
  221. /// createNotAuthAnswer();
  222. /// } \endcode
  223. ///
  224. /// Note that it is possible that \c finder_ is NULL while \c datasrc_
  225. /// is not. This happens if the zone is configured to be served from
  226. /// the data source but it is broken in some sense and doesn't hold any
  227. /// zone data, e.g., when the zone file has an error or the secondary
  228. /// zone hasn't been transferred yet. The caller needs to expect the case
  229. /// and handle it accordingly.
  230. ///
  231. /// The other scenario is manipulating zone data (XfrOut, XfrIn, DDNS,
  232. /// ...). In this case, the finder itself is not so important. However,
  233. /// we need an exact match (if we want to manipulate zone data, we must
  234. /// know exactly, which zone we are about to manipulate). Then the call
  235. ///
  236. /// \code FindResult result(list->find(zone_name, true, false));
  237. /// if (result.datasrc_) {
  238. /// ZoneUpdaterPtr updater(result.datasrc_->getUpdater(zone_name);
  239. /// ...
  240. /// } \endcode
  241. ///
  242. /// \param zone The name of the zone to look for.
  243. /// \param want_exact_match If it is true, it returns only exact matches.
  244. /// If the best possible match is partial, a negative result is
  245. /// returned instead. It is possible the caller could check it and
  246. /// act accordingly if the result would be partial match, but with this
  247. /// set to true, the find might be actually faster under some
  248. /// circumstances.
  249. /// \param want_finder If this is false, the finder_ member of FindResult
  250. /// might be NULL even if the corresponding data source is found. This
  251. /// is because of performance, in some cases the finder is a side
  252. /// result of the searching algorithm (therefore asking for it again
  253. /// would be a waste), but under other circumstances it is not, so
  254. /// providing it when it is not needed would also be wasteful.
  255. ///
  256. /// Other things are never the side effect of searching, therefore the
  257. /// caller can get them explicitly (the updater, journal reader and
  258. /// iterator).
  259. /// \return A FindResult describing the data source and zone with the
  260. /// longest match against the zone parameter.
  261. virtual FindResult find(const dns::Name& zone,
  262. bool want_exact_match = false,
  263. bool want_finder = true) const = 0;
  264. /// \brief Creates a ZoneTableAccessor object for the specified data
  265. /// source.
  266. ///
  267. /// \param datasrc_name If not empty, the name of the data source.
  268. /// \param use_cache If true, create a zone table for in-memory cache.
  269. /// \throw NotImplemented if this method is not implemented.
  270. /// \return A pointer to the accessor, or NULL if the requested data
  271. /// source is not found.
  272. virtual ConstZoneTableAccessorPtr
  273. getZoneTableAccessor(const std::string& datasrc_name,
  274. bool use_cache) const = 0;
  275. };
  276. /// \brief Shared pointer to the list.
  277. typedef boost::shared_ptr<ClientList> ClientListPtr;
  278. /// \brief Shared const pointer to the list.
  279. typedef boost::shared_ptr<const ClientList> ConstClientListPtr;
  280. /// \brief Concrete implementation of the ClientList, which is constructed
  281. /// based on configuration.
  282. ///
  283. /// This is the implementation which is expected to be used in the servers.
  284. /// However, it is expected most of the code will use it as the ClientList,
  285. /// only the creation is expected to be direct.
  286. ///
  287. /// While it is possible to inherit this class, it is not expected to be
  288. /// inherited except for tests.
  289. class ConfigurableClientList : public ClientList {
  290. public:
  291. /// \brief Constructor
  292. ///
  293. /// \param rrclass For which class the list should work.
  294. ConfigurableClientList(const isc::dns::RRClass& rrclass);
  295. /// \brief Exception thrown when there's an error in configuration.
  296. class ConfigurationError : public Exception {
  297. public:
  298. ConfigurationError(const char* file, size_t line, const char* what) :
  299. Exception(file, line, what)
  300. {}
  301. };
  302. /// \brief Sets the configuration.
  303. ///
  304. /// This fills the ClientList with data source clients corresponding to the
  305. /// configuration. The data source clients are newly created or recycled
  306. /// from previous configuration.
  307. ///
  308. /// If any error is detected, an exception is thrown and the current
  309. /// configuration is preserved.
  310. ///
  311. /// \param configuration The JSON element describing the configuration to
  312. /// use.
  313. /// \param allow_cache If it is true, the 'cache' option of the
  314. /// configuration is used and some zones are cached into an In-Memory
  315. /// data source according to it. If it is false, it is ignored and
  316. /// no In-Memory data sources are created.
  317. /// \throw DataSourceError if there's a problem creating a data source
  318. /// client.
  319. /// \throw ConfigurationError if the configuration is invalid in some
  320. /// sense.
  321. /// \throw BadValue if configuration is NULL
  322. /// \throw Unexpected if something misbehaves (like the data source
  323. /// returning NULL iterator).
  324. /// \throw NotImplemented if the auto-detection of list of zones is
  325. /// needed.
  326. /// \throw Whatever is propagated from within the data source.
  327. void configure(const isc::data::ConstElementPtr& configuration,
  328. bool allow_cache);
  329. /// \brief Returns the currently active configuration.
  330. ///
  331. /// In case configure was not called yet, it returns an empty
  332. /// list, which corresponds to the default content.
  333. const isc::data::ConstElementPtr& getConfiguration() const {
  334. return (configuration_);
  335. }
  336. private:
  337. /// \brief Convenience type shortcut
  338. typedef boost::shared_ptr<memory::ZoneWriter> ZoneWriterPtr;
  339. public:
  340. /// \brief Codes indicating in-memory cache status for a given zone name.
  341. ///
  342. /// This is used as a result of the getCachedZoneWriter() method.
  343. enum CacheStatus {
  344. CACHE_DISABLED, ///< The cache is not enabled in this list.
  345. ZONE_NOT_CACHED, ///< Zone is not to be cached (including the case
  346. /// where caching is disabled for the specific
  347. /// data source).
  348. ZONE_NOT_FOUND, ///< Zone does not exist in this list.
  349. CACHE_NOT_WRITABLE, ///< The cache is not writable (and zones can't
  350. /// be loaded)
  351. DATASRC_NOT_FOUND, ///< Specific data source for load is specified
  352. /// but it's not in the list
  353. ZONE_SUCCESS ///< Zone to be cached is successfully found and
  354. /// is ready to be loaded
  355. };
  356. /// \brief Return value of getCachedZoneWriter()
  357. ///
  358. /// A pair containing status and the zone writer, for the
  359. /// getCachedZoneWriter() method.
  360. typedef std::pair<CacheStatus, ZoneWriterPtr> ZoneWriterPair;
  361. /// \brief Return a zone writer that can be used to (re)load a zone.
  362. ///
  363. /// By default this method identifies the first data source in the list
  364. /// that should serve the zone of the given name, and returns a ZoneWriter
  365. /// object that can be used to load the content of the zone, in a specific
  366. /// way for that data source.
  367. ///
  368. /// If the optional \c datasrc_name parameter is provided with a non empty
  369. /// string, this method only tries to load the specified zone into or with
  370. /// the data source which has the given name, regardless where in the list
  371. /// that data source is placed. Even if the given name of zone doesn't
  372. /// exist in the data source, other data sources are not searched and
  373. /// this method simply returns ZONE_NOT_FOUND in the first element
  374. /// of the pair.
  375. ///
  376. /// \param zone The origin of the zone to load.
  377. /// \param datasrc_name If not empty, the name of the data source
  378. /// to be used for loading the zone (see above).
  379. /// \return The result has two parts. The first one is a status describing
  380. /// if it worked or not (and in case it didn't, also why). If the
  381. /// status is ZONE_SUCCESS, the second part contains a shared pointer
  382. /// to the writer. If the status is anything else, the second part is
  383. /// NULL.
  384. /// \throw DataSourceError or anything else that the data source
  385. /// containing the zone might throw is propagated.
  386. ZoneWriterPair getCachedZoneWriter(const dns::Name& zone,
  387. const std::string& datasrc_name = "");
  388. /// \brief Implementation of the ClientList::find.
  389. virtual FindResult find(const dns::Name& zone,
  390. bool want_exact_match = false,
  391. bool want_finder = true) const;
  392. /// \brief This holds one data source client and corresponding information.
  393. ///
  394. /// \todo The content yet to be defined.
  395. struct DataSourceInfo {
  396. DataSourceInfo(DataSourceClient* data_src_client,
  397. const DataSourceClientContainerPtr& container,
  398. boost::shared_ptr<internal::CacheConfig> cache_conf,
  399. const dns::RRClass& rrclass,
  400. const std::string& name);
  401. DataSourceClient* data_src_client_;
  402. DataSourceClientContainerPtr container_;
  403. // Accessor to cache_ in the form of DataSourceClient, hiding
  404. // the existence of InMemoryClient as much as possible. We should
  405. // really consider cleaner abstraction, but for now it works.
  406. // This is also only intended to be used in auth unit tests right now.
  407. // No other applications or tests may use it.
  408. const DataSourceClient* getCacheClient() const;
  409. boost::shared_ptr<memory::InMemoryClient> cache_;
  410. boost::shared_ptr<memory::ZoneTableSegment> ztable_segment_;
  411. std::string name_;
  412. // cache_conf_ can be accessed only from this read-only getter,
  413. // to protect its integrity as much as possible.
  414. const internal::CacheConfig* getCacheConfig() const {
  415. return (cache_conf_.get());
  416. }
  417. private:
  418. boost::shared_ptr<internal::CacheConfig> cache_conf_;
  419. };
  420. /// \brief The collection of data sources.
  421. typedef std::vector<DataSourceInfo> DataSources;
  422. /// \brief Convenience type alias.
  423. ///
  424. /// \see getDataSource
  425. typedef std::pair<DataSourceClient*, DataSourceClientContainerPtr>
  426. DataSourcePair;
  427. /// \brief Create a data source client of given type and configuration.
  428. ///
  429. /// This is a thin wrapper around the DataSourceClientContainer
  430. /// constructor. The function is here to make it possible for tests
  431. /// to replace the DataSourceClientContainer with something else.
  432. /// Also, derived classes could want to create the data source clients
  433. /// in a different way, though inheriting this class is not recommended.
  434. ///
  435. /// Some types of data sources can be internal to the \c ClientList
  436. /// implementation and do not require a corresponding dynamic module
  437. /// loaded via \c DataSourceClientContainer. In such a case, this method
  438. /// simply returns a pair of null pointers. It will help the caller reduce
  439. /// type dependent processing. Currently, "MasterFiles" is considered to
  440. /// be this type of data sources.
  441. ///
  442. /// The parameters are the same as of the constructor.
  443. /// \return Pair containing both the data source client and the container.
  444. /// The container might be NULL in the derived class, it is
  445. /// only stored so the data source client is properly destroyed when
  446. /// not needed. However, in such case, it is the caller's
  447. /// responsibility to ensure the data source client is deleted when
  448. /// needed.
  449. virtual DataSourcePair getDataSourceClient(const std::string& type,
  450. const data::ConstElementPtr&
  451. configuration);
  452. /// \brief Get status information of all internal data sources.
  453. ///
  454. /// Get a DataSourceStatus for current state of each data source client
  455. /// in this list.
  456. ///
  457. /// This may throw standard exceptions, such as std::bad_alloc. Otherwise,
  458. /// it is exception free.
  459. std::vector<DataSourceStatus> getStatus() const;
  460. public:
  461. /// \brief Access to the data source clients.
  462. ///
  463. /// It can be used to examine the loaded list of data sources clients
  464. /// directly. It is not known if it is of any use other than testing, but
  465. /// it might be, so it is just made public (there's no real reason to
  466. /// hide it).
  467. const DataSources& getDataSources() const { return (data_sources_); }
  468. /// \brief Creates a ZoneTableAccessor object for the specified data
  469. /// source.
  470. ///
  471. /// \param datasrc_name If not empty, the name of the data source
  472. /// \param use_cache If true, create a zone table for in-memory cache.
  473. /// \note At present, the only concrete implementation of
  474. /// ZoneTableAccessor is ZoneTableAccessorCache, so \c use_cache must be
  475. /// true.
  476. /// \throw NotImplemented if \c use_cache is false.
  477. /// \return A pointer to the accessor, or NULL if the requested data
  478. /// source is not found.
  479. ConstZoneTableAccessorPtr
  480. getZoneTableAccessor(const std::string& datasrc_name,
  481. bool use_cache) const;
  482. private:
  483. struct MutableResult;
  484. /// \brief Internal implementation of find.
  485. ///
  486. /// The class itself needs to do some internal searches in other methods,
  487. /// so the implementation is shared.
  488. ///
  489. /// The result is returned as parameter because MutableResult is not
  490. /// defined in the header file.
  491. ///
  492. /// If there's no match, the result is not modified. Therefore, this
  493. /// expects to get a fresh result object each time it is called, not
  494. /// to reuse it.
  495. void findInternal(MutableResult& result, const dns::Name& name,
  496. bool want_exact_match, bool want_finder) const;
  497. const isc::dns::RRClass rrclass_;
  498. /// \brief Currently active configuration.
  499. isc::data::ConstElementPtr configuration_;
  500. /// \brief The last set value of allow_cache.
  501. bool allow_cache_;
  502. protected:
  503. /// \brief The data sources held here.
  504. ///
  505. /// All our data sources are stored here. It is protected to let the
  506. /// tests in. You should consider it private if you ever want to
  507. /// derive this class (which is not really recommended anyway).
  508. DataSources data_sources_;
  509. };
  510. /// \brief Shortcut typedef for maps of client_lists.
  511. typedef boost::shared_ptr<std::map<
  512. isc::dns::RRClass, boost::shared_ptr<ConfigurableClientList> > >
  513. ClientListMapPtr;
  514. } // namespace datasrc
  515. } // namespace isc
  516. #endif // DATASRC_CONTAINER_H