kea/src/lib/hooks/tests/library_manager_unittest.cc.in

// Copyright (C) 2013  Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

#include <hooks/callout_handle.h>
#include <hooks/callout_manager.h>
#include <hooks/library_manager.h>
#include <hooks/server_hooks.h>
#include <hooks/tests/marker_file.h>

#include <gtest/gtest.h>

#include <algorithm>
#include <fstream>
#include <string>
#include <iostream>

#include <unistd.h>


using namespace isc;
using namespace isc::hooks;
using namespace std;

/// @brief Library manager test class

class LibraryManagerTest : public ::testing::Test {
public:
    /// @brief Constructor
    ///
    /// Sets up a collection of three LibraryHandle objects to use in the test.
    LibraryManagerTest() {

        // Set up the server hooks.  There is sone singleton for all tests,
        // so reset it and explicitly set up the hooks for the test.
        ServerHooks& hooks = ServerHooks::getServerHooks();
        hooks.reset();
        lm_one_index_ = hooks.registerHook("lm_one");
        lm_two_index_ = hooks.registerHook("lm_two");
        lm_three_index_ = hooks.registerHook("lm_three");

        // Set up the callout manager with these hooks.  Assume a maximum of
        // four libraries.
        callout_manager_.reset(new CalloutManager(4));

        // Set up the callout handle.
        callout_handle_.reset(new CalloutHandle(callout_manager_));

        // Ensure the marker file is not present
        static_cast<void>(unlink(MARKER_FILE));
    }

    /// @brief Destructor
    ///
    /// Ensures a marker file is removed after each test.
    ~LibraryManagerTest() {
        static_cast<void>(unlink(MARKER_FILE));
    }

    /// @brief Call callouts test
    ///
    /// All of the loaded libraries have four callouts: a context_create
    /// callout and three callouts that are attached to hooks lm_one,
    /// lm_two and lm_three.
    ///
    /// context_create initializes the calculation by setting a seed
    /// value of r0 say.
    ///
    /// Callout lm_one is passed a value d1 and performs a simple arithmetic
    /// operation on it yielding a result r1.  Hence we can say that
    /// @f[ r1 = lm1(r0, d1) @f]
    ///
    /// Callout lm_two is passed a value d2 and peforms another simple
    /// arithmetic operation on it and d2, yielding r2, i.e.
    /// @f[ r2 = lm2(d1, d2) @f]
    ///
    /// lm_three does a similar operation giving @f[ r3 = lm3(r2, d3) @f].
    ///
    /// The details of the operations lm1, lm2 and lm3 depend on the library.
    /// However the sequence of calls needed to do this set of calculations
    /// is identical regardless of the exact functions. This method performs
    /// those operations and checks the results.
    ///
    /// It is assumed that callout_manager_ and callout_handle_ have been
    /// set up appropriately.
    ///
    /// @param r0...r3, d1..d3 Values and intermediate values expected.  They
    ///        are ordered so that the variables are used in the order left to
    ///        right.
    void executeCallCallouts(int r0, int d1, int r1, int d2, int r2, int d3,
                             int r3) {
        static const char* COMMON_TEXT = " callout returned the wong value";
        int result;

        // Seed the calculation.
        callout_manager_->callCallouts(ServerHooks::CONTEXT_CREATE,
                                       *callout_handle_);
        callout_handle_->getArgument("result", result);
        EXPECT_EQ(r0, result) << "context_create" << COMMON_TEXT;

        // Perform the first calculation.
        callout_handle_->setArgument("data_1", d1);
        callout_manager_->callCallouts(lm_one_index_, *callout_handle_);
        callout_handle_->getArgument("result", result);
        EXPECT_EQ(r1, result) << "lm_one" << COMMON_TEXT;

        // ... the second ...
        callout_handle_->setArgument("data_2", d2);
        callout_manager_->callCallouts(lm_two_index_, *callout_handle_);
        callout_handle_->getArgument("result", result);
        EXPECT_EQ(r2, result) << "lm_two" << COMMON_TEXT;

        // ... and the third.
        callout_handle_->setArgument("data_3", d3);
        callout_manager_->callCallouts(lm_three_index_, *callout_handle_);
        callout_handle_->getArgument("result", result);
        EXPECT_EQ(r3, result) << "lm_three" << COMMON_TEXT;
    }

    /// Hook indexes.  These are somewhat ubiquitous, so are made public for
    /// ease of reference instead of being accessible by a function.
    int lm_one_index_;
    int lm_two_index_;
    int lm_three_index_;

    /// Callout handle used in calls
    boost::shared_ptr<CalloutHandle> callout_handle_;

    /// Callout manager used for the test
    boost::shared_ptr<CalloutManager> callout_manager_;
};


/// @brief Library manager class
///
/// This is an instance of the LibraryManager class but with the protected
/// methods made public for test purposes.

class PublicLibraryManager : public isc::hooks::LibraryManager {
public:
    /// @brief Constructor
    ///
    /// Stores the library name.  The actual loading is done in loadLibrary().
    ///
    /// @param name Name of the library to load.  This should be an absolute
    ///        path name.
    /// @param index Index of this library.  For all these tests, it will be
    ///        zero, as we are only using one library.
    /// @param manager CalloutManager object
    PublicLibraryManager(const std::string& name, int index,
                         const boost::shared_ptr<CalloutManager>& manager)
        : LibraryManager(name, index, manager)
    {}

    /// @brief Destructor
    ///
    /// Ensures that the library is closed after the test.
    ~PublicLibraryManager() {
        static_cast<void>(closeLibrary());
    }

    /// Public methods that call protected methods on the superclass.
    using LibraryManager::openLibrary;
    using LibraryManager::closeLibrary;
    using LibraryManager::checkVersion;
    using LibraryManager::registerStandardCallouts;
    using LibraryManager::runLoad;
    using LibraryManager::runUnload;
};

// Names of the libraries used in these tests.  These libraries are built using
// libtool, so we need to look in the hidden ".libs" directory to locate the
// .so file.  Note that we access the .so file - libtool creates this as a
// like to the real shared library.
static const char* BASIC_CALLOUT_LIBRARY = "@abs_builddir@/.libs/libbcl.so";
static const char* FULL_CALLOUT_LIBRARY = "@abs_builddir@/.libs/libfcl.so";
static const char* INCORRECT_VERSION_LIBRARY = "@abs_builddir@/.libs/libivl.so";
static const char* LOAD_CALLOUT_LIBRARY = "@abs_builddir@/.libs/liblcl.so";
static const char* LOAD_ERROR_CALLOUT_LIBRARY =
    "@abs_builddir@/.libs/liblecl.so";
static const char* NOT_PRESENT_LIBRARY = "@abs_builddir@/.libs/libnothere.so";
static const char* NO_VERSION_LIBRARY = "@abs_builddir@/.libs/libnvl.so";
static const char* UNLOAD_CALLOUT_LIBRARY = "@abs_builddir@/.libs/libucl.so";


namespace {

// Tests that OpenLibrary reports an error for an unknown library.

TEST_F(LibraryManagerTest, NoLibrary) {
    PublicLibraryManager lib_manager(std::string(NOT_PRESENT_LIBRARY),
                                     0, callout_manager_);
    EXPECT_FALSE(lib_manager.openLibrary());
}

// Tests that the openLibrary() and closeLibrary() methods work.

TEST_F(LibraryManagerTest, OpenClose) {
    PublicLibraryManager lib_manager(std::string(BASIC_CALLOUT_LIBRARY),
                                     0, callout_manager_);

    // Open and close the library
    EXPECT_TRUE(lib_manager.openLibrary());
    EXPECT_TRUE(lib_manager.closeLibrary());

    // Check that a second close does not report an error.
    EXPECT_TRUE(lib_manager.closeLibrary());
}

// Check that the code handles the case of a library with no version function.

TEST_F(LibraryManagerTest, NoVersion) {
    PublicLibraryManager lib_manager(std::string(NO_VERSION_LIBRARY),
                                     0, callout_manager_);
    // Open should succeed.
    EXPECT_TRUE(lib_manager.openLibrary());

    // Version check should fail.
    EXPECT_FALSE(lib_manager.checkVersion());

    // Tidy up.
    EXPECT_TRUE(lib_manager.closeLibrary());
}

// Check that the code handles the case of a library with a version function
// that returns an incorrect version number.

TEST_F(LibraryManagerTest, WrongVersion) {
    PublicLibraryManager lib_manager(std::string(INCORRECT_VERSION_LIBRARY),
                                     0, callout_manager_);
    // Open should succeed.
    EXPECT_TRUE(lib_manager.openLibrary());

    // Version check should fail.
    EXPECT_FALSE(lib_manager.checkVersion());

    // Tidy up.
    EXPECT_TRUE(lib_manager.closeLibrary());
}

// Tests that checkVersion() function succeeds in the case of a library with a
// version function that returns the correct version number.

TEST_F(LibraryManagerTest, CorrectVersionReturned) {
    PublicLibraryManager lib_manager(std::string(BASIC_CALLOUT_LIBRARY),
                                     0, callout_manager_);
    // Open should succeed.
    EXPECT_TRUE(lib_manager.openLibrary());

    // Version check should succeed.
    EXPECT_TRUE(lib_manager.checkVersion());

    // Tidy up.
    EXPECT_TRUE(lib_manager.closeLibrary());
}

// Checks the registration of standard callouts.

TEST_F(LibraryManagerTest, RegisterStandardCallouts) {

    // Load the only library, specifying the index of 0 as it's the only
    // library.  This should load all callouts.
    PublicLibraryManager lib_manager(std::string(BASIC_CALLOUT_LIBRARY),
                               0, callout_manager_);
    EXPECT_TRUE(lib_manager.openLibrary());

    // Check the version of the library.
    EXPECT_TRUE(lib_manager.checkVersion());

    // Load the standard callouts
    EXPECT_NO_THROW(lib_manager.registerStandardCallouts());

    // Now execute the callouts in the order expected.  The library performs
    // the calculation:
    //
    // r3 = (10 + d1) * d2 - d3
    executeCallCallouts(10, 5, 15, 7, 105, 17, 88);

    // Explicitly clear the callout_handle_ so that we can delete the library.
    // This is the only object to contain memory allocated by it.
    callout_handle_.reset();

    // Tidy up
    EXPECT_TRUE(lib_manager.closeLibrary());
}

// Test that the "load" function is called correctly.

TEST_F(LibraryManagerTest, CheckLoadCalled) {

    // Load the only library, specifying the index of 0 as it's the only
    // library.  This should load all callouts.
    PublicLibraryManager lib_manager(std::string(LOAD_CALLOUT_LIBRARY),
                                     0, callout_manager_);
    EXPECT_TRUE(lib_manager.openLibrary());

    // Check the version of the library.
    EXPECT_TRUE(lib_manager.checkVersion());

    // Load the standard callouts
    EXPECT_NO_THROW(lib_manager.registerStandardCallouts());

    int result = 0;

    // Check that only context_create and lm_one have callouts registered.
    EXPECT_TRUE(callout_manager_->calloutsPresent(
                ServerHooks::CONTEXT_CREATE));
    EXPECT_TRUE(callout_manager_->calloutsPresent(lm_one_index_));
    EXPECT_FALSE(callout_manager_->calloutsPresent(lm_two_index_));
    EXPECT_FALSE(callout_manager_->calloutsPresent(lm_three_index_));
    EXPECT_FALSE(callout_manager_->calloutsPresent(
                 ServerHooks::CONTEXT_DESTROY));

    // Call the runLoad() method to run the load() function.
    EXPECT_TRUE(lib_manager.runLoad());
    EXPECT_TRUE(callout_manager_->calloutsPresent(
                ServerHooks::CONTEXT_CREATE));
    EXPECT_TRUE(callout_manager_->calloutsPresent(lm_one_index_));
    EXPECT_TRUE(callout_manager_->calloutsPresent(lm_two_index_));
    EXPECT_TRUE(callout_manager_->calloutsPresent(lm_three_index_));
    EXPECT_FALSE(callout_manager_->calloutsPresent(
                 ServerHooks::CONTEXT_DESTROY));

    // Now execute the callouts in the order expected.  The library performs
    // the calculation:
    //
    // r3 = (5 * d1 + d2) * d3
    executeCallCallouts(5, 5, 25, 7, 32, 10, 320);

    // Explicitly clear the callout_handle_ so that we can delete the library.
    // This is the only object to contain memory allocated by it.
    callout_handle_.reset();

    // Tidy up
    EXPECT_TRUE(lib_manager.closeLibrary());
}

// Check handling of a "load" function that returns an error.

TEST_F(LibraryManagerTest, CheckLoadError) {

    // Load the only library, specifying the index of 0 as it's the only
    // library.  This should load all callouts.
    PublicLibraryManager lib_manager(std::string(LOAD_ERROR_CALLOUT_LIBRARY),
                                     0, callout_manager_);
    EXPECT_TRUE(lib_manager.openLibrary());

    // Check that we catch a load error
    EXPECT_FALSE(lib_manager.runLoad());

    // Explicitly clear the callout_handle_ so that we can delete the library.
    // This is the only object to contain memory allocated by it.
    callout_handle_.reset();

    // Tidy up
    EXPECT_TRUE(lib_manager.closeLibrary());
}

// No unload function

TEST_F(LibraryManagerTest, CheckNoUnload) {

    // Load the only library, specifying the index of 0 as it's the only
    // library.  This should load all callouts.
    PublicLibraryManager lib_manager(std::string(BASIC_CALLOUT_LIBRARY),
                                     0, callout_manager_);
    EXPECT_TRUE(lib_manager.openLibrary());

    // Check that no unload function returns true.
    EXPECT_TRUE(lib_manager.runUnload());

    // Explicitly clear the callout_handle_ so that we can delete the library.
    // This is the only object to contain memory allocated by it.
    callout_handle_.reset();

    // Tidy up
    EXPECT_TRUE(lib_manager.closeLibrary());
}

// Unload function returns an error

TEST_F(LibraryManagerTest, CheckUnloadError) {

    // Load the only library, specifying the index of 0 as it's the only
    // library.  This should load all callouts.
    PublicLibraryManager lib_manager(std::string(LOAD_ERROR_CALLOUT_LIBRARY),
                                     0, callout_manager_);
    EXPECT_TRUE(lib_manager.openLibrary());

    // Check that unload function returning an error returns false.
    EXPECT_FALSE(lib_manager.runUnload());

    // Explicitly clear the callout_handle_ so that we can delete the library.
    // This is the only object to contain memory allocated by it.
    callout_handle_.reset();

    // Tidy up
    EXPECT_TRUE(lib_manager.closeLibrary());
}

// Check that the case of the library's unload() function returning a
// success is handled correcty.

TEST_F(LibraryManagerTest, CheckUnload) {

    // Load the only library, specifying the index of 0 as it's the only
    // library.  This should load all callouts.
    PublicLibraryManager lib_manager(std::string(UNLOAD_CALLOUT_LIBRARY),
                                     0, callout_manager_);
    EXPECT_TRUE(lib_manager.openLibrary());

    // Check that the marker file is not present (at least that the file
    // open fails).
    fstream marker;
    marker.open(MARKER_FILE, fstream::in);
    EXPECT_TRUE(marker.fail());

    // Check that unload function runs and returns a success
    EXPECT_TRUE(lib_manager.runUnload());

    // Check that the open succeeded
    marker.open(MARKER_FILE, fstream::in);
    EXPECT_TRUE(marker.is_open());

    // Tidy up
    marker.close();

    // Explicitly clear the callout_handle_ so that we can delete the library.
    // This is the only object to contain memory allocated by it.
    callout_handle_.reset();

    // Tidy up
    EXPECT_TRUE(lib_manager.closeLibrary());
}

// Test the operation of unloadLibrary().  We load a library with a set
// of callouts then unload it.  We need to check that the callouts have been
// removed.  We'll also check that the library's unload() function was called
// as well.

TEST_F(LibraryManagerTest, LibUnload) {

    // Load the only library, specifying the index of 0 as it's the only
    // library.  This should load all callouts.
    PublicLibraryManager lib_manager(std::string(FULL_CALLOUT_LIBRARY),
                               0, callout_manager_);
    EXPECT_TRUE(lib_manager.openLibrary());

    // Check the version of the library.
    EXPECT_TRUE(lib_manager.checkVersion());

    // No callouts should be registered at the moment.
    EXPECT_FALSE(callout_manager_->calloutsPresent(lm_one_index_));
    EXPECT_FALSE(callout_manager_->calloutsPresent(lm_two_index_));
    EXPECT_FALSE(callout_manager_->calloutsPresent(lm_three_index_));

    // Load the single standard callout and check it is registered correctly.
    EXPECT_NO_THROW(lib_manager.registerStandardCallouts());
    EXPECT_TRUE(callout_manager_->calloutsPresent(lm_one_index_));
    EXPECT_FALSE(callout_manager_->calloutsPresent(lm_two_index_));
    EXPECT_FALSE(callout_manager_->calloutsPresent(lm_three_index_));

    // Call the load function to load the other callouts.
    EXPECT_TRUE(lib_manager.runLoad());
    EXPECT_TRUE(callout_manager_->calloutsPresent(lm_one_index_));
    EXPECT_TRUE(callout_manager_->calloutsPresent(lm_two_index_));
    EXPECT_TRUE(callout_manager_->calloutsPresent(lm_three_index_));

    // Unload the library and check that the callouts have been removed from
    // the CalloutManager.
    lib_manager.unloadLibrary();
    EXPECT_FALSE(callout_manager_->calloutsPresent(lm_one_index_));
    EXPECT_FALSE(callout_manager_->calloutsPresent(lm_two_index_));
    EXPECT_FALSE(callout_manager_->calloutsPresent(lm_three_index_));
}

// Now come the loadLibrary() tests that make use of all the methods tested
// above.  These tests are really to make sure that the methods have been
// tied toget correctly.

// First test the basic error cases - no library, no version function, version
// function returning an error.

TEST_F(LibraryManagerTest, LoadLibraryNoLibrary) {
    LibraryManager lib_manager(std::string(NOT_PRESENT_LIBRARY), 0,
                                           callout_manager_);
    EXPECT_FALSE(lib_manager.loadLibrary());
}

// Check that the code handles the case of a library with no version function.

TEST_F(LibraryManagerTest, LoadLibraryNoVersion) {
    LibraryManager lib_manager(std::string(NO_VERSION_LIBRARY), 0,
                                           callout_manager_);
    EXPECT_FALSE(lib_manager.loadLibrary());
}

// Check that the code handles the case of a library with a version function
// that returns an incorrect version number.

TEST_F(LibraryManagerTest, LoadLibraryWrongVersion) {
    LibraryManager lib_manager(std::string(INCORRECT_VERSION_LIBRARY), 0,
                                           callout_manager_);
    EXPECT_FALSE(lib_manager.loadLibrary());
}

// Check that the full loadLibrary call works.

TEST_F(LibraryManagerTest, LoadLibrary) {
    LibraryManager lib_manager(std::string(FULL_CALLOUT_LIBRARY), 0,
                                           callout_manager_);
    EXPECT_TRUE(lib_manager.loadLibrary());

    // Now execute the callouts in the order expected.  The library performs
    // the calculation:
    //
    // r3 = (7 * d1 - d2) * d3
    executeCallCallouts(7, 5, 35, 9, 26, 3, 78);

    // All done, so unload the library.  First we have to delete the
    // CalloutHandle as it may contain memory allocated by that library.
    callout_handle_.reset();

    EXPECT_TRUE(lib_manager.unloadLibrary());

    // Check that the callouts have been removed from the callout manager.
    EXPECT_FALSE(callout_manager_->calloutsPresent(lm_one_index_));
    EXPECT_FALSE(callout_manager_->calloutsPresent(lm_two_index_));
    EXPECT_FALSE(callout_manager_->calloutsPresent(lm_three_index_));
}

// Now test for multiple libraries.  We'll load the full callout library
// first, then load some of the libraries with missing framework functions.
// This will check that when searching for framework functions, only the
// specified library is checked, not other loaded libraries. We will
// load a second library with suitable callouts and check that the callouts
// are added correctly. Finally, we'll unload one of the libraries and
// check that only the callouts belonging to that library were removed.

TEST_F(LibraryManagerTest, LoadMultipleLibraries) {
    // Load a library with all framework functions.
    LibraryManager lib_manager_1(std::string(FULL_CALLOUT_LIBRARY), 0,
                                 callout_manager_);
    EXPECT_TRUE(lib_manager_1.loadLibrary());

    // Attempt to load a library with no version() function.  We should detect
    // this and not end up calling the function from the already loaded
    // library.
    LibraryManager lib_manager_2(std::string(NO_VERSION_LIBRARY), 1,
                                 callout_manager_);
    EXPECT_FALSE(lib_manager_2.loadLibrary());

    // Attempt to load the library with an incorrect version.  This should
    // be detected.
    LibraryManager lib_manager_3(std::string(INCORRECT_VERSION_LIBRARY), 1,
                                 callout_manager_);
    EXPECT_FALSE(lib_manager_3.loadLibrary());

    // Load the basic callout library.  This only has standard callouts so,
    // if the first library's load() function gets called, some callouts
    // will be registered twice and lead to incorrect results.
    LibraryManager lib_manager_4(std::string(BASIC_CALLOUT_LIBRARY), 1,
                                 callout_manager_);
    EXPECT_TRUE(lib_manager_4.loadLibrary());

    // Execute the callouts.  The first library implements the calculation.
    //
    // r3 = (7 * d1 - d2) * d3
    // 
    // The last-loaded library implements the calculation
    //
    // r3 = (10 + d1) * d2 - d3
    //
    // Putting the processing for each library together in the appropriate
    // order, we get:
    //
    // r3 = ((10 * d1 + d1) - d2) * d2 * d3 - d3
    executeCallCallouts(10, 3, 33, 2, 62, 3, 183);

    // All done, so unload the first library.  First we have to delete the
    // CalloutHandle as it may contain memory allocated by that library.
    callout_handle_.reset();
    EXPECT_TRUE(lib_manager_1.unloadLibrary());
    //EXPECT_TRUE(lib_manager_4.unloadLibrary());

    // Now execute the callouts again and check that the results are as
    // expected for the new calculation.
    callout_handle_.reset(new CalloutHandle(callout_manager_));
    executeCallCallouts(10, 5, 15, 7, 105, 17, 88);

    // ... and tidy up.
    callout_handle_.reset();
    EXPECT_TRUE(lib_manager_4.unloadLibrary());
}

} // Anonymous namespace