Refactoring in the base classes of the Qserv REST services

Class http::Module was split into two modules: http::BaseModule
and a reduced version of http::Module. The new hierarchy is meant
to prepare ground for introducing an intermediate base class that
will support data streaming (and file uploading requests) in which
the request body can't be read at once. The new class will inherit
from http::BaseModule.

src/http/BaseModule.cc

@@ -0,0 +1,160 @@
+/*
+ * LSST Data Management System
+ *
+ * This product includes software developed by the
+ * LSST Project (http://www.lsst.org/).
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the LSST License Statement and
+ * the GNU General Public License along with this program.  If not,
+ * see <http://www.lsstcorp.org/LegalNotices/>.
+ */
+
+// Class header
+#include "http/BaseModule.h"
+
+// Qserv headers
+#include "http/Exceptions.h"
+#include "http/MetaModule.h"
+#include "http/RequestQuery.h"
+
+// LSST headers
+#include "lsst/log/Log.h"
+
+// System headers
+#include <stdexcept>
+
+using namespace std;
+using json = nlohmann::json;
+
+namespace {
+LOG_LOGGER _log = LOG_GET("lsst.qserv.http.BaseModule");
+
+string packWarnings(list<string> const& warnings) {
+    string packed;
+    for (auto const& msg : warnings) {
+        if (!packed.empty()) packed += "; ";
+        packed += msg;
+    }
+    return packed;
+}
+}  // namespace
+
+namespace lsst::qserv::http {
+
+BaseModule::BaseModule(string const& authKey, string const& adminAuthKey)
+        : _authKey(authKey), _adminAuthKey(adminAuthKey) {}
+
+void BaseModule::checkApiVersion(string const& func, unsigned int minVersion, string const& warning) const {
+    unsigned int const maxVersion = MetaModule::version;
+    unsigned int version = 0;
+    string const versionAttrName = "version";
+    json const errorEx = json::object({{"min_version", minVersion}, {"max_version", maxVersion}});
+
+    // Intercept exceptions thrown when converting the attribute's value (if provided)
+    // in order to inject the allowed range of the version numbers into the extended
+    // error sent back to the caller.
+    //
+    // Note that requests sent w/o explicitly specified API version will still be
+    // processed. In this case a warning will be sent in the response object.
+    try {
+        if (method() == "GET") {
+            if (!query().has(versionAttrName)) {
+                warn("No version number was provided in the request's query.");
+                return;
+            }
+            version = query().requiredUInt(versionAttrName);
+        } else {
+            if (!body().has(versionAttrName)) {
+                warn("No version number was provided in the request's body.");
+                return;
+            }
+            version = body().required<unsigned int>(versionAttrName);
+        }
+    } catch (...) {
+        throw http::Error(func, "The required parameter " + versionAttrName + " is not a number.", errorEx);
+    }
+    if (!(minVersion <= version && version <= maxVersion)) {
+        if (!warning.empty()) warn(warning);
+        throw http::Error(func,
+                          "The requested version " + to_string(version) +
+                                  " of the API is not in the range supported by the service.",
+                          errorEx);
+    }
+}
+
+void BaseModule::enforceInstanceId(string const& func, string const& requiredInstanceId) const {
+    string const instanceId = method() == "GET" ? query().requiredString("instance_id")
+                                                : body().required<string>("instance_id");
+    debug(func, "instance_id: " + instanceId);
+    if (instanceId != requiredInstanceId) {
+        throw invalid_argument(context() + func + " Qserv instance identifier mismatch. Client sent '" +
+                               instanceId + "' instead of '" + requiredInstanceId + "'.");
+    }
+}
+
+void BaseModule::info(string const& msg) const { LOGS(_log, LOG_LVL_INFO, context() << msg); }
+
+void BaseModule::debug(string const& msg) const { LOGS(_log, LOG_LVL_DEBUG, context() << msg); }
+
+void BaseModule::warn(string const& msg) const {
+    LOGS(_log, LOG_LVL_WARN, context() << msg);
+    _warnings.push_back(msg);
+}
+
+void BaseModule::error(string const& msg) const { LOGS(_log, LOG_LVL_ERROR, context() << msg); }
+
+void BaseModule::sendError(string const& func, string const& errorMsg, json const& errorExt) {
+    error(func, errorMsg);
+    json result;
+    result["success"] = 0;
+    result["error"] = errorMsg;
+    result["error_ext"] = errorExt.is_null() ? json::object() : errorExt;
+    result["warning"] = ::packWarnings(_warnings);
+    sendResponse(result.dump(), "application/json");
+}
+
+void BaseModule::sendData(json& result) {
+    result["success"] = 1;
+    result["error"] = "";
+    result["error_ext"] = json::object();
+    result["warning"] = ::packWarnings(_warnings);
+    sendResponse(result.dump(), "application/json");
+}
+
+void BaseModule::enforceAuthorization(http::AuthType const authType) {
+    if (authType != http::AuthType::REQUIRED) return;
+    if (body().has("admin_auth_key")) {
+        auto const adminAuthKey = body().required<string>("admin_auth_key");
+        if (adminAuthKey != _adminAuthKey) {
+            throw AuthError(context() +
+                            "administrator's authorization key 'admin_auth_key' in the request"
+                            " doesn't match the one in server configuration");
+        }
+        _isAdmin = true;
+        return;
+    }
+    if (body().has("auth_key")) {
+        auto const authKey = body().required<string>("auth_key");
+        if (authKey != _authKey) {
+            throw AuthError(context() +
+                            "authorization key 'auth_key' in the request doesn't match"
+                            " the one in server configuration");
+        }
+        return;
+    }
+    throw AuthError(context() +
+                    "none of the authorization keys 'auth_key' or 'admin_auth_key' was found"
+                    " in the request. Please, provide one.");
+}
+
+}  // namespace lsst::qserv::http

src/http/BaseModule.h

@@ -0,0 +1,216 @@
+
+/*
+ * LSST Data Management System
+ *
+ * This product includes software developed by the
+ * LSST Project (http://www.lsst.org/).
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the LSST License Statement and
+ * the GNU General Public License along with this program.  If not,
+ * see <http://www.lsstcorp.org/LegalNotices/>.
+ */
+#ifndef LSST_QSERV_HTTP_BASEMODULE_H
+#define LSST_QSERV_HTTP_BASEMODULE_H
+
+// System headers
+#include <list>
+#include <memory>
+#include <stdexcept>
+#include <string>
+#include <unordered_map>
+
+// Third party headers
+#include "nlohmann/json.hpp"
+
+// Qserv headers
+#include "http/RequestBodyJSON.h"
+
+// Forward declarations
+namespace lsst::qserv::http {
+class RequestQuery;
+}  // namespace lsst::qserv::http
+
+// This header declarations
+namespace lsst::qserv::http {
+
+/// The enumeration type which is used for configuring/enforcing
+/// module's authorization requirements.
+enum class AuthType { REQUIRED, NONE };
+
+/// Class AuthError represent exceptions thrown when the authorization
+/// requirements aren't met.
+class AuthError : public std::invalid_argument {
+public:
+    using std::invalid_argument::invalid_argument;
+};
+
+/**
+ * Class BaseModule is the very base class for the request processing modules of the HTTP servers.
+ */
+class BaseModule {
+public:
+    BaseModule() = delete;
+    BaseModule(BaseModule const&) = delete;
+    BaseModule& operator=(BaseModule const&) = delete;
+
+    virtual ~BaseModule() = default;
+
+protected:
+    /**
+     * @param authKey  An authorization key for operations which require extra security.
+     * @param adminAuthKey  An administrator-level authorization key.
+     */
+    BaseModule(std::string const& authKey, std::string const& adminAuthKey);
+
+    /// @return Authorization level of the request.
+    bool isAdmin() const { return _isAdmin; }
+
+    /// @return The method of a request.
+    virtual std::string method() const = 0;
+
+    /// @return Captured URL path elements.
+    virtual std::unordered_map<std::string, std::string> params() const = 0;
+
+    /// @return Parameters of the request's query captured from the request's URL.
+    virtual RequestQuery query() const = 0;
+
+    /// @return Optional parameters of a request extracted from the request's body (if any).
+    RequestBodyJSON const& body() const { return _body; }
+
+    /// @return A reference to the modifiable object that stores optional parameters of a request
+    /// extracted from the request's body (if any). The method is used by subclasses to set the
+    /// body of a request.
+    RequestBodyJSON& body() { return _body; }
+
+    // Message loggers for the corresponding log levels
+
+    void info(std::string const& msg) const;
+    void info(std::string const& context, std::string const& msg) const { info(context + "  " + msg); }
+
+    void debug(std::string const& msg) const;
+    void debug(std::string const& context, std::string const& msg) const { debug(context + "  " + msg); }
+
+    void warn(std::string const& msg) const;
+    void warn(std::string const& context, std::string const& msg) const { warn(context + "  " + msg); }
+
+    void error(std::string const& msg) const;
+    void error(std::string const& context, std::string const& msg) const { error(context + "  " + msg); }
+
+    /**
+     * @return A context in which a module runs. This is used for error adn info reporting.
+     *   The method is required to be implemented by a subclass.
+     */
+    virtual std::string context() const = 0;
+
+    /**
+     * @brief Check the API version in the request's query or its body.
+     *
+     * The version is specified in the optional attribute 'version'. If the attribute
+     * was found present in the request then its value would be required to be within
+     * the specified minimum and the implied maximum, that's the current version number
+     * of the REST API. In case if no version info was found in the request the method
+     * will simply note this and the service will report a lack of the version number
+     * in the "warning" attribute at the returned JSON object.
+     *
+     * The method will look for th eversion attribute in the query string of the "GET"
+     * requests. For requests that are called using methods "POST", "PUT" or "DELETE"
+     * the attribute will be located in the requests's body.
+     *
+     * @note Services that are calling the method should adjust the minimum version
+     *   number to be the same as the current value in the implementation of
+     *   http::MetaModule::version if the expected JSON schema of the corresponding
+     *   request changes.
+     * @see http::MetaModule::version
+     *
+     * @param func The name of the calling context (it's used for error reporting).
+     * @param minVersion The minimum version number of the valid version range.
+     * @param warning The optional warning to be sent to a client along with the usual
+     *   error if the minimum version requirement won't be satisfied. This mechanism
+     *   allows REST serivices to notify clients on possible problems encountered
+     *   when validating parameters of a request.
+     *
+     * @throw http::Error if a value of the attribute is not within the expected range.
+     */
+    void checkApiVersion(std::string const& func, unsigned int minVersion,
+                         std::string const& warning = std::string()) const;
+
+    /**
+     * @brief Check if the specified identifier of the Qserv instance that was received
+     *   from a client matches the one that is required in the service context. Throw
+     *   an exception in case of mismatch.
+     *
+     * @param func The name of the calling context (it's used for error reporting).
+     * @param requiredInstanceId An instance identifier required in the service context.
+     * @throws std::invalid_argument If the dentifiers didn't match.
+     */
+    void enforceInstanceId(std::string const& func, std::string const& requiredInstanceId) const;
+
+    /**
+     * Send a response back to a requester of a service.
+     * @param content The content to be sent back.
+     * @param contentType The type of the content to be sent back.
+     */
+    virtual void sendResponse(std::string const& content, std::string const& contentType) = 0;
+
+    /**
+     * Inspect the body of a request or a presence of a user-supplied authorization key.
+     * Its value will be compared against a value of the corresponding configuration
+     * parameter of the service (processorConfig) passed into the constructor of the class.
+     * In the absence of the message body, or in the absence of the key in the body, or
+     * in case of any mismatch between the keys would result in an exception thrown.
+     *
+     * @param authType  Authorization requirements of the module. If 'http::AuthType::REQUIRED' is
+     *   requested then the method will enforce the authorization. A lack of required
+     *   authorization key in a request, or an incorrect value of such key would result
+     *   in a error sent back to a client.
+     * @throw AuthError This exception is thrown if the authorization requirements weren't met.
+     */
+    void enforceAuthorization(http::AuthType const authType = http::AuthType::NONE);
+
+    /**
+     * Report a error condition and send an error message back to a requester
+     * of a service.
+     *
+     * @param func The name of a context from which the operation was initiated.
+     * @param errorMsg An error condition to be reported.
+     * @param errorExt (optional) The additional information on the error.
+     */
+    void sendError(std::string const& func, std::string const& errorMsg,
+                   nlohmann::json const& errorExt = nlohmann::json::object());
+
+    /**
+     * Report a result back to a requester of a service upon its successful
+     * completion.
+     * @param result A JSON object to be sent back.
+     */
+    void sendData(nlohmann::json& result);
+
+private:
+    // Input parameters
+    std::string const _authKey;
+    std::string const _adminAuthKey;
+
+    /// The flag indicating if a request has been granted the "administrator"-level privileges.
+    bool _isAdmin = false;
+
+    /// The body of a request is initialized by BaseModule::execute().
+    RequestBodyJSON _body;
+
+    /// The optional warning message to be sent to a caller if the API version
+    /// number wasn't mentoned in the request.
+    mutable std::list<std::string> _warnings;
+};
+
+}  // namespace lsst::qserv::http
+
+#endif  // LSST_QSERV_HTTP_BASEMODULE_H

src/http/CMakeLists.txt

@@ -2,6 +2,7 @@ add_library(http SHARED)
 
 target_sources(http PRIVATE
     AsyncReq.cc
+    BaseModule.cc
     BinaryEncoding.cc
     ChttpMetaModule.cc
     ChttpModule.cc