SDManager.h

Go to the documentation of this file.

// ********************************************************************************
// Copyright (c) 2018-2024 Schlumberger. All Rights Reserved. Schlumberger Private.
// ********************************************************************************

#pragma once

#include "DLL_EXPORT.h"
#include "HttpContext.h"
#include "Types.h"

#include <cstdint>
#include <map>
#include <memory>
#include <string>
#include <vector>

namespace seismicdrive
{
    /*******************************************************************************
     * @class SDManager SDManager.h
     *
     * @brief Seismic Drive Manager class.
     *
     * This class will manage url and apikey for the seismic-drive service, authentication providers and gcsaccessors cache.
     *
     ******************************************************************************/
    class DLL_PUBLIC SDManager
    {
      public:
        /*******************************************************************************
         * @brief Constructor.
         *
         * If executed without parameters it will try to load the seismic-drive service url and apikey from the environment (SDURL, SDAPIKEY).
         *
         * @param sdurl is the url of the seismic-drive service.
         * @param sdapikey is the api key of the seismic-drive service.
         * @param logLevel is the desired sdapi logging level
         ******************************************************************************/
        // pragma: allowlist nextline secret
        SDManager(const std::string &sdurl = "", const std::string &sdapikey = "", const int16_t logLevel = 0);

        /*******************************************************************************
         * @brief Destructor.
         *
         * If the file is opened for writing (not READ_ONLY), it wll be closed.
         ******************************************************************************/
        ~SDManager();

        /*******************************************************************************
         * @brief Move Constructor.
         *
         *  This constructor moves the SDManager object from
         *  the source to the new object and destroy the source object.
         *
         ******************************************************************************/
        SDManager(SDManager &&sdsm) noexcept;

        /*******************************************************************************
         * @brief Move Assignment Operator.
         *
         *  Same functionality as the move constructor.
         *
         ******************************************************************************/
        SDManager &operator=(SDManager &&sdsm) noexcept;

        /*******************************************************************************
         * @brief Copy Constructor.
         *
         *  This constructor makes a copy of the SDManager object from
         *  the source to the new object without modifying the source object.
         *
         ******************************************************************************/
        SDManager(const SDManager &op);

        /*******************************************************************************
         * @brief Copy Assignment Operator.
         *
         *  Same functionality as the copy constructor.
         *
         ******************************************************************************/
        SDManager &operator=(const SDManager &op);

        /*******************************************************************************
         * @brief Authentication provider from impersonation token.
         *
         * If the impersonation_token param is not specified, it will try to load it from the environment (SD_IMP_AUTH_TOKEN)
         *
         * @param impersonation_token is the impersonation token
         ******************************************************************************/
        void setAuthProviderFromImpToken(const std::string &impersonation_token = "");

        /*******************************************************************************
         * @brief Authentication provider from string.
         *
         * This method will always provide the authentication token provided using the idtoken parameter.
         *
         * @param idtoken is the credential token
         ******************************************************************************/
        void setAuthProviderFromString(const std::string &idtoken);

        // Used with setAuthProviderCallback()
        //
        typedef std::string (*AuthProviderCallback)(const void *data);

        /*******************************************************************************
         * @brief Authentication provider will obtain token from callback (when expired).
         *
         * The authentication provider will always use the authentication token returned by the callback.
         *
         * @param callback is the callback function to be used
         *
         * @param data is passed to the callback, it can be anything.
         ******************************************************************************/
        void setAuthProviderCallback(AuthProviderCallback callback, const void *data = nullptr);

        /*******************************************************************************
         * @brief gets an ID token.
         *
         * This method gets an authentication ID token.
         *
         * @return an ID token.
         ******************************************************************************/
        std::string getIDToken() const;

        /*******************************************************************************
         * @brief gets the url of seismic store svc.
         *
         * This method gets the latest url of the seismic store service endpoint.
         *
         * @return the url of the seismic-drive service.
         ******************************************************************************/
        std::string getSDUrl() const;

        /*******************************************************************************
         * @brief gets the API Key of seismic store svc.
         *
         * This method gets the API Key of the seismic store service endpoint.
         *
         * @return the api key of the seismic-drive service.
         ******************************************************************************/
        std::string getSDApiKey() const;

        /*******************************************************************************
         * @brief Serialize the SDManager object
         *
         * This method serialize the SDManager object and returns the serialized string version.
         *
         * @return a serialized version of the SDManager object
         ******************************************************************************/
        std::string serialize() const;

        /*******************************************************************************
         * @brief Creates an SDManager object.
         *
         * This method creates an SDManager instance from a serialized string SDManager object.
         *
         * @param sd_manager_serialized is the serialized SDManager object
         *
         * @return a deserialized SDManager
         ******************************************************************************/
        static SDManager *create(const std::string &sd_manager_serialized);

        /*******************************************************************************
         * @brief Deprecated
         *
         * Use copyHttpHeaders() instead.
         ******************************************************************************/
        static const std::map<std::string, std::string> &getHttpHeaders();

        /*******************************************************************************
         * @brief Get HTTP headers
         *
         * Returns the HTTP headers set by previous calls to setHttpHeaders()
         ******************************************************************************/
        static std::map<std::string, std::string> copyHttpHeaders();

        /*******************************************************************************
         * @brief Set HTTP headers
         *
         * Sets the HTTP headers to use for subsequent calls to the seismic store service.
         *
         * @param httpHeaders contains the HTTP headers to use
         *
         * @param clearExistingHeaders if true, removes the HTTP headers set with previous calls to setHttpHeaders()
         *
         ******************************************************************************/
        static void setHttpHeaders(const std::map<std::string, std::string> &httpHeaders, bool clearExistingHeaders = true);

        /*******************************************************************************
         * @brief Clear HTTP headers
         *
         * Clears the HTTP headers set by previous calls to setHttpHeaders()
         ******************************************************************************/
        static void clearHttpHeaders();

        /*******************************************************************************
         * @brief Deprecated
         *
         * Use setLogLevel() instead.
         ******************************************************************************/
        void setLogStatus(const bool status);

        /*******************************************************************************
         * @brief Deprecated
         *
         * Use getLogLevel() instead.
         ******************************************************************************/
        bool getLogStatus() const;

        /*******************************************************************************
         * @brief Get value for the translate-user-info parameter in dataset_get()
         ******************************************************************************/
        bool isTranslateUserInfo() const;

        /*******************************************************************************
         * @brief Sets the translate-user-info parameter in dataset_get()
         *
         * @param status value of true or false
         ******************************************************************************/
        void translateUserInfo(bool status);

        /*******************************************************************************
         * @brief Sets the current logging level
         *
         * 0 --> only critical messages will be logged (default)
         * 1 --> some logging
         * 2 --> more detailed logging
         * 3 --> even more details
         * ...
         *
         ******************************************************************************/
        void setLogLevel(int level);

        /*******************************************************************************
         * @brief gets the current logging level
         *
         * @return the current logging level
         ******************************************************************************/
        int getLogLevel() const;

        DEPRECATED("Use versionMajor() instead")
        uint_least16_t getVersionMajor() const;

        DEPRECATED("Use versionMinor() instead")
        uint_least16_t getVersionMinor() const;

        DEPRECATED("Use versionPatch() instead")
        uint_least16_t getVersionPatch() const;

        DEPRECATED("Use version() instead")
        std::string getVersion() const;

        /*******************************************************************************
         * @brief gets major version number
         *
         * This method returns the sdapi major version number.
         *
         * @return the sdapi major version number
         ******************************************************************************/
        static uint_least16_t versionMajor();

        /*******************************************************************************
         * @brief gets minor version number
         *
         * This method returns the sdapi minor version number.
         *
         * @return the sdapi minor version number
         ******************************************************************************/
        static uint_least16_t versionMinor();

        /*******************************************************************************
         * @brief gets version patch number
         *
         * This method returns the sdapi version patch number.
         *
         * @return the sdapi version patch number
         ******************************************************************************/
        static uint_least16_t versionPatch();

        /*******************************************************************************
         * @brief gets version
         *
         * This method returns the sdapi version as a string.
         *
         * The format is major.minor.patch, e.g. "2.7.1"
         *
         * @return the sdapi version
         ******************************************************************************/
        static std::string version();

        /*******************************************************************************
         * @note Method should only be used before the manager is passed to create the
         *       dataset or utils objects
         *
         * @brief Sets the ExponentialRetryBackoffPolicy at SDManager level
         *
         * This method sets the ExponentialRetryBackoffPolicy at SDManager level for Both
         * the seismicstore and storage
         *
         * @param policy the retry policy that needs to be applied to the service
         * @param link the HttpConnectionLink that determines if the policy should be
         *             applied to SDMS and/or CLOUD_STORAGE
         *
         * usage example:
         *
         * ExponentialRetryBackoffPolicy policy;
         * policy.maxRetry = 3;
         *
         * SDManager manager;
         * manager.setExponentialRetryBackoffPolicy(&policy, HttpConnectionLink::ANY);
         * SDutils utils(&manager); OR SDGenericDataset dataset(&manager, path);
         ******************************************************************************/
        void setExponentialRetryBackoffPolicy(const ExponentialRetryBackoffPolicy *policy, HttpConnectionLink link);

        /*******************************************************************************
         * @note ExponentialRetryBackoffPolicy should have been set before the dataset
         *       or utils objects were created
         *
         * @brief Returns the retry policy for the HttpConnectionLink provided
         *
         * @return a shared_ptr that points to the policy. HttpConnectionLink::ANY will
         *         default to the HttpConnectionLink::SEISMIC_DMS option
         ******************************************************************************/
        std::shared_ptr<const ExponentialRetryBackoffPolicy> getExponentialRetryBackoffPolicy(HttpConnectionLink link) const;

        /*******************************************************************************
         * @brief Authentication Provider Setter
         *
         * @brief   This function sets the authentication provider required by the library to generate credentials.
         *
         * @param   authProvider The authentication provider to use.
         * @param   args         The list of arguments to be used with the authentication provider.
         *
         * @details This generic method is responsible for configuring the authentication provider for the library. The user needs
         *          to specify the desired authentication provider and provide any necessary arguments. This information is crucial for
         *          the library to generate the appropriate credentials.
         *
         * @note    Ensure that the authentication provider is compatible with the library, and provide the required arguments accordingly.
         *
         * @example
         *          // Example usage of setAuthProvider function
         *          setCredentialsProvider("ExampleProvider", {"arg1", "arg2"});
         *
         ******************************************************************************/
        void setCredentialsProvider(const std::string &authProvider, const std::vector<std::string> &args);

        // Slb proprietary code start ----------------------------------------------------------

        /*******************************************************************************
         * @brief Creates an SDManager object.
         *
         * This method creates an SDManager instance from a serialized string SDManager object.
         *
         * @param sd_manager_serialized is the serialized SDManager object
         *
         * @return a deserialized SDManager
         ******************************************************************************/
        static SDManager *create(const std::string &sd_manager_serialized, const std::string &clientId, const std::string &clientSecret);
        /*******************************************************************************
         * @brief Removed method.  Use setAuthProviderSauthV2() instead.
         ******************************************************************************/
        void setAuthProviderSauth(const std::string &clientID = "", const std::string &filepath = "");

        /*******************************************************************************
         * @brief Authentication provider from SAuth.
         *
         * This generic method will try to automatically generate a token from a PTS env or from a credential file
         * In a single sign on mode (PTS env) the clientID and filepath parameter can be omitted as are not required (they will be ignored in any case)
         * If using credentials file the ClientID must be specified and if the filepath is omitted the default one will be used (~/.sdcfg/slbauth.tk)
         *
         * @param clientID is the id of the client used to generate the tokens saved in the file.
         * @param clientCredentialsFile is the path of the file that contain the access and refresh token
         ******************************************************************************/
        void setAuthProviderSauthV2(const std::string &clientID, const std::string &clientSecret, const std::string &clientCredentialsFile = "");

        /*******************************************************************************
         * @brief Removed method.  Use setAuthProviderServiceSauthV2() instead.
         ******************************************************************************/
        void setAuthProviderServiceSauth(const std::string &projectID = "", const std::string &serviceID = "", const std::string &privateKey = "");

        /*******************************************************************************
         * @brief Authentication provider from SAuth Service Account.
         *
         * This generic method will try to automatically generate a token for an sauth service account.
         *
         * @param projectID is the id of the service account project.
         * @param serviceID is the id of the service account.
         * @param privateKey is the secret private key of the sauth service account.
         ******************************************************************************/
        void setAuthProviderServiceSauthV2(const std::string &clientID, const std::string &clientSecret);

        /*******************************************************************************
         * @brief Removed method.  Use setAuthProviderFromFileV2() instead.
         ******************************************************************************/
        void setAuthProviderFromFile(const std::string &clientID, const std::string &filepath = "");

        /*******************************************************************************
         * @brief Authentication provider from file. If the filepath param is not specified, it will use the default path ~/.sdcfg/slbauth.tk.
         *
         * The file must contain an access token and a refresh token comma separated [access_token],[refresh_token].
         *
         * @param filepath is the path of the file that contain the access and refresh token
         * @param clientID is the id of the client used to generate the tokens saved in the file.
         ******************************************************************************/
        void setAuthProviderFromFileV2(const std::string &clientID, const std::string &clientSecret, const std::string &filepath = "");

        /*******************************************************************************
         * @brief Authentication provider for impersonation credentials signed with sauth.
         *
         * This provider manage impersonation credentials, externally created and signed with sauth.
         * The impersonation credential is automatically refreshed when expired and dismissed at the end of usage.
         * If the impersonationToken argument is not specified, the library will try to load it from the environment (SD_IMP_AUTH_TOKEN).
         * If the impersonationTokenContext argument is not specified, the library will try to load it from the environemnt (SD_IMP_AUTH_TOKEN_CONTEXT)
         *
         * @param clientId  the client id of the trusted application that generates the impersonation token credential.
         * @param clientSecret the client secret of the trusted application that generates the impersonation token credential.
         * @param impersonationToken the impersonation token.
         * @param impersonationTokenContext the impersonation token context.
         ******************************************************************************/
        void setAuthProviderSauthImpersonationToken(
            const std::string &clientId,
            const std::string &clientSecret,
            const std::string &impersonationToken = "",
            const std::string &impersonationTokenContext = "");
        /*******************************************************************************
         * @brief Single page application credentials provider.
         *
         * This provider will automatically refresh client credentials.
         * It requires a single page application public client (enabled to handle refresh credentials).
         *
         * optional env settings:
         * 1. SDAPI_SAUTH_CREDENTIALS_FILENAME: string = if set the method will flush
         * refreshed credentials, comma separated, in the specified filename as "access-token,refresh-token"
         * 2. SDAPI_SAUTH_USE_PROD: switch "ON" or "OFF" = enforce the use of sauth prod endpoints,
         * by default it is disabled and sauth p4d is used.
         * 3. SDAPI_SAUTH_TOKEN_SERVICE_URL: string = specify the sauth token service endpoints url to use
         *
         * @param clientID is the single page application public client id
         * @param accessToken is the user access token
         * @param refreshToken is the user refresh token
         ******************************************************************************/
        void setAuthProviderSauthSinglePageApp(
            const std::string &clientID, const std::string &accessToken, const std::string &refreshToken);

        /*******************************************************************************
         * @brief Single page application credentials provider.
         *
         * This provider will automatically refresh client credentials.
         * It requires a single page application public client (enabled to handle refresh credentials).
         *
         * optional env settings:
         * 1. SDAPI_SAUTH_USE_PROD: switch "ON" or "OFF" = enforce the use of sauth prod endpoints,
         * by default it is disabled and sauth p4d is used.
         * 2. SDAPI_SAUTH_TOKEN_SERVICE_URL: string = specify the sauth token service endpoints url to use
         *
         * @param clientID is the single page application public client id
         * @param accessToken is the user access token
         * @param refreshToken is the user refresh token
         * @param credentialsFileName file where to load and save refreshed credentials.
         * If set as empty, the access-token and refresh-token argument will be used
         ******************************************************************************/
        void setAuthProviderSauthSinglePageApp(
            const std::string &clientID, const std::string &accessToken, const std::string &refreshToken, const std::string &credentialsFileName);

        /*******************************************************************************
         * @brief Single page application credentials provider.
         *
         * This provider will automatically refresh client credentials.
         * It requires a single page application public client (enabled to handle refresh credentials).
         *
         * optional env settings:
         * 1. SDAPI_SAUTH_USE_PROD: switch "ON" or "OFF" = enforce the use of sauth prod endpoints,
         * by default it is disabled and sauth p4d is used.
         * 2. SDAPI_SAUTH_TOKEN_SERVICE_URL: string = specify the sauth token service endpoints url to use
         *
         * @param clientID is the single page application public client id
         * @param credentialsFileName file where to load and save refreshed credentials
         ******************************************************************************/
        void setAuthProviderSauthSinglePageApp(
            const std::string &clientID, const std::string &credentialsFileName);

      private:
        SDManager(const std::string &managerSerialized, const std::string &clientId, const std::string &clientSecret);
        // Slb proprietary code end ----------------------------------------------------------

      private:
#ifdef _MSC_VER
    #pragma warning(push)
    #pragma warning(disable : 4251)
#endif

        class Impl;

        std::unique_ptr<Impl> _impl;

#ifdef _MSC_VER
    #pragma warning(pop)
#endif
        friend class SDDataset;
        friend class SDManagerImplTest;
        friend class SDReadOnlyGenericDatasetAccessor;
        friend class SeismicStore;
    };
}

// Slb proprietary code start ----------------------------------------------------------

#include "SDException.h"

namespace seismicdrive
{
    namespace error
    {
        namespace manager
        {
            class DLL_PUBLIC ClientSecretNotSet : public Error
            {
              public:
                class Impl;

                ClientSecretNotSet(const Impl &impl);

                ~ClientSecretNotSet();

              protected:
                ClientSecretNotSet(Impl *impl);

                Impl &impl;
            };
        }
    }
}

// Slb proprietary code end ----------------------------------------------------------