Current File : //backups/router/usr/local/include/kea/database/audit_entry.h
// Copyright (C) 2019-2020 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 AUDIT_ENTRY_H
#define AUDIT_ENTRY_H
#include <boost/date_time/posix_time/posix_time.hpp>
#include <boost/multi_index/composite_key.hpp>
#include <boost/multi_index_container.hpp>
#include <boost/multi_index/hashed_index.hpp>
#include <boost/multi_index/mem_fun.hpp>
#include <boost/multi_index/ordered_index.hpp>
#include <boost/shared_ptr.hpp>
#include <cstdint>
#include <string>
namespace isc {
namespace db {
class AuditEntry;
/// @brief Pointer to the @c AuditEntry object.
typedef boost::shared_ptr<AuditEntry> AuditEntryPtr;
/// @brief Represents a single entry in the audit table.
///
/// The audit tables are used in the databases to track incremental
/// changes, e.g. configuration changes applied via the configuration
/// backend. The backend can query for the entries in the audit table
/// to identify the SQL table in which the records were modified, the
/// identifiers of the modified objects, type of the modifications,
/// time of the modifications and optional log messages associated
/// with the modifications.
///
/// The server should remember the most recent modification time out of
/// all audit entries it has fetched. During the next attempt to fetch
/// the most recent modifications in the database it will query for all
/// entries with later modification time than stored. That way the
/// server queries only for the audit entries it hasn't fetched yet.
/// In the case two (or more) successive audit entries have the same
/// modification time the strictly increasing modification id is used.
///
/// When the modification type of the entry is set to
/// @c AuditEntry::ModificationType::DELETE, the corresponding
/// configuration entry is already gone from the database. For example:
/// when a subnet with ID of 123 is deleted from the dhcp4_subnet
/// table, the audit entry similar to this will be stored in the audit
/// table:
///
/// - object_type: "dhcp4_subnet"
/// - object_id: 123
/// - modification_type: 3 (DELETE)
/// - modification_time: "2019-01-15 15:45:23"
/// - revision id: 234
/// - log_message: "DHCPv4 subnet 123 deleted"
///
/// The subnet is instantly removed from the dhcp4_subnet table. When
/// the server finds such entry in the audit table, it removes the
/// subnet 123 from its (in-memory) configuration. There is no need
/// make additional queries to fetch updated data from the dhcp4_subnet
/// table, unless there are also audit entries indicating that some
/// new subnets have been added or some subnets have been updated.
class AuditEntry {
public:
/// @brief Types of the modifications.
///
/// The numbers representing those modification types correspond
/// to the values representing them in the database.
enum class ModificationType : uint8_t {
CREATE = 0,
UPDATE = 1,
DELETE = 2
};
/// @brief Constructor using explicit modification time and id.
///
/// @param object_type name of the table where data was modified.
/// @param object_id identifier of the modified record in this table.
/// @param modification_type type of the modification, e.g. DELETE.
/// @param modification_time time of modification for that record.
/// @param revision_id identifier of the revision.
/// @param log_message optional log message associated with the
/// modification.
AuditEntry(const std::string& object_type,
const uint64_t object_id,
const ModificationType& modification_type,
const boost::posix_time::ptime& modification_time,
const uint64_t revision_id,
const std::string& log_message);
/// @brief Constructor using default modification time.
///
/// @param object_type name of the table where data was modified.
/// @param object_id identifier of the modified record in this table.
/// @param modification_type type of the modification, e.g. DELETE.
/// @param revision_id identifier of the revision.
/// @param log_message optional log message associated with the
/// modification.
AuditEntry(const std::string& object_type,
const uint64_t object_id,
const ModificationType& modification_type,
const uint64_t revision_id,
const std::string& log_message);
/// @brief Factory function creating an instance of @c AuditEntry.
///
/// This function should be used to create an instance of the audit
/// entry within a hooks library in cases when the library may be
/// unloaded before the object is destroyed. This ensures that the
/// ownership of the object by the Kea process is retained.
///
/// @param object_type name of the table where data was modified.
/// @param object_id identifier of the modified record in this table.
/// @param modification_type type of the modification, e.g. DELETE.
/// @param modification_time time of modification for that record.
/// @param revision_id identifier of the revision.
/// @param log_message optional log message associated with the
/// modification.
///
/// @return Pointer to the @c AuditEntry instance.
static AuditEntryPtr create(const std::string& object_type,
const uint64_t object_id,
const ModificationType& modification_type,
const boost::posix_time::ptime& modification_time,
const uint64_t revision_id,
const std::string& log_message);
/// @brief Factory function creating an instance of @c AuditEntry.
///
/// This function should be used to create an instance of the audit
/// entry within a hooks library in cases when the library may be
/// unloaded before the object is destroyed. This ensures that the
/// ownership of the object by the Kea process is retained.
///
/// @param object_type name of the table where data was modified.
/// @param object_id identifier of the modified record in this table.
/// @param modification_type type of the modification, e.g. DELETE.
/// @param revision_id identifier of the revision.
/// @param log_message optional log message associated with the
/// modification.
///
/// @return Pointer to the @c AuditEntry instance.
static AuditEntryPtr create(const std::string& object_type,
const uint64_t object_id,
const ModificationType& modification_type,
const uint64_t revision_id,
const std::string& log_message);
/// @brief Returns object type.
///
/// @return Name of the table in which the modification is present.
std::string getObjectType() const {
return (object_type_);
}
/// @brief Returns object id.
///
/// @return Identifier of the added, updated or deleted object.
uint64_t getObjectId() const {
return (object_id_);
}
/// @brief Returns modification type.
///
/// @return Type of the modification, e.g. DELETE.
ModificationType getModificationType() const {
return (modification_type_);
}
/// @brief Returns modification time.
///
/// @return Modification time of the corresponding record.
boost::posix_time::ptime getModificationTime() const {
return (modification_time_);
}
/// @brief Returns revision id.
///
/// The revision id is used when two audit entries have the same
/// modification time.
///
/// @return Identifier of the revision.
uint64_t getRevisionId() const {
return (revision_id_);
}
/// @brief Returns log message.
///
/// @return Optional log message corresponding to the changes.
std::string getLogMessage() const {
return (log_message_);
}
private:
/// @brief Validates the values specified for the audit entry.
///
/// @throw BadValue if the object type is empty or if the
/// modification time is not a date time value.
void validate() const;
/// @brief Object type.
std::string object_type_;
/// @brief Object id.
uint64_t object_id_;
/// @brief Modification type.
ModificationType modification_type_;
/// @brief Modification time.
boost::posix_time::ptime modification_time_;
/// @brief Revision id.
///
/// The revision id is used when two audit entries have the same
/// modification time.
uint64_t revision_id_;
/// @brief Log message.
std::string log_message_;
};
/// @brief Tag used to access index by object type.
struct AuditEntryObjectTypeTag { };
/// @brief Tag used to access index by modification time.
struct AuditEntryModificationTimeIdTag { };
/// @brief Tag used to access index by object id.
struct AuditEntryObjectIdTag { };
/// @brief Multi index container holding @c AuditEntry instances.
///
/// This container provides indexes to access the audit entries
/// by object type and modification time.
typedef boost::multi_index_container<
// The container holds pointers to @c AuditEntry objects.
AuditEntryPtr,
// First index allows for accessing by the object type.
boost::multi_index::indexed_by<
boost::multi_index::ordered_non_unique<
boost::multi_index::tag<AuditEntryObjectTypeTag>,
boost::multi_index::composite_key<
AuditEntry,
boost::multi_index::const_mem_fun<
AuditEntry,
std::string,
&AuditEntry::getObjectType
>,
boost::multi_index::const_mem_fun<
AuditEntry,
AuditEntry::ModificationType,
&AuditEntry::getModificationType
>
>
>,
// Second index allows for accessing by the modification time and id.
boost::multi_index::ordered_non_unique<
boost::multi_index::tag<AuditEntryModificationTimeIdTag>,
boost::multi_index::composite_key<
AuditEntry,
boost::multi_index::const_mem_fun<
AuditEntry,
boost::posix_time::ptime,
&AuditEntry::getModificationTime
>,
boost::multi_index::const_mem_fun<
AuditEntry,
uint64_t,
&AuditEntry::getRevisionId
>
>
>,
// Third index allows for accessing by the object id.
boost::multi_index::hashed_non_unique<
boost::multi_index::tag<AuditEntryObjectIdTag>,
boost::multi_index::const_mem_fun<
AuditEntry,
uint64_t,
&AuditEntry::getObjectId
>
>
>
> AuditEntryCollection;
//// @brief Pointer to the @c AuditEntryCollection object.
typedef boost::shared_ptr<AuditEntryCollection> AuditEntryCollectionPtr;
} // end of namespace isc::db
} // end of namespace isc
#endif
Mini Shell