ChronoKVS: connect to remote visors via a config file (#470) (#628) (#652)

* feat(chronokvs): support config file path in constructors (#470)

ChronoKVS was hardcoded to the ChronoLog client defaults (localhost:5555),
limiting it to local deployments. Add an optional config_path parameter to
ChronoKVS, ChronoKVSMapper and ChronoKVSClientAdapter constructors so callers
can point at a ChronoLog client JSON configuration and connect to remote
deployments. Default-constructed instances keep their previous behavior.

The adapter loads the file via ClientConfiguration::load_from_file() before
connecting and throws std::runtime_error if loading fails, matching the
acceptance criteria in the issue.

The writer/reader examples accept --config/-c (parse_conf_path_arg) so the
plumbing can be exercised end-to-end. Adds a unit test that verifies the
constructor throws on missing or section-less config files without requiring
a running ChronoLog deployment.

* ci(local-pipeline): sanitize branch name for artifact uploads

actions/upload-artifact rejects names containing '/'. Branch names like
'feature/470-...' caused the ctest-results upload step to fail. Compute
a slugified branch name (slashes replaced with dashes) once and reuse it
for both artifact uploads and the job summary references.

* refactor(chronokvs): rename confManager to client_config

Per review feedback on PR #628: confManager is a remnant of the old
ConfigurationManager class. Use a clearer client-facing name.

* refactor(chronokvs): replace throwing constructors with noexcept Create() factory

Per review feedback on PR #628 (Inna): throwing exceptions across a
client-library boundary forces callers to wrap construction in try/catch
without an obvious set of exception types to catch. Convert the public
ChronoKVS API to a factory pattern instead:

- Make ChronoKVS constructors private.
- Add static std::unique_ptr<ChronoKVS> Create(...) noexcept overloads
  that catch any construction-path exception, log it via the configured
  log level, and return nullptr to signal failure.
- Update examples, integration test, and unit tests to use the factory
  and check for nullptr instead of catching std::runtime_error.

Internal layers (ChronoKVSMapper, ChronoKVSClientAdapter) keep using
exceptions for clarity; they are now caught at the library boundary
inside Create() rather than escaping to user code.

Author: iameneko

.github/workflows/local-pipeline.yml

@@ -36,6 +36,13 @@ jobs:
         with:
           ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.ref }}
 
+      - name: Compute sanitized branch slug
+        id: branch-slug
+        run: |
+          RAW="${{ github.head_ref || github.ref_name }}"
+          SAFE="${RAW//\//-}"
+          echo "slug=${SAFE}" >> "$GITHUB_OUTPUT"
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 
@@ -372,7 +379,7 @@ jobs:
         if: always()
         uses: actions/upload-artifact@v7
         with:
-          name: ctest-results-${{ github.head_ref || github.ref_name }}
+          name: ctest-results-${{ steps.branch-slug.outputs.slug }}
           path: ./ctest-results
           retention-days: 14
 
@@ -439,7 +446,7 @@ jobs:
       - name: Upload chronolog-install artifact
         uses: actions/upload-artifact@v7
         with:
-          name: chronolog-install-${{ github.head_ref || github.ref_name }}
+          name: chronolog-install-${{ steps.branch-slug.outputs.slug }}
           path: ./chronolog-install
           retention-days: 7
 
@@ -484,6 +491,7 @@ jobs:
           )
 
           BRANCH="${{ github.head_ref || github.ref_name }}"
+          BRANCH_SLUG="${{ steps.branch-slug.outputs.slug }}"
 
           {
             echo "## 🧪 ChronoLog Local Pipeline"
@@ -519,13 +527,13 @@ jobs:
                 echo "</details>"
                 echo ""
               fi
-              echo "_ctest is non-gating while the suite is being refactored. Full logs in the_ \`ctest-results-${BRANCH}\` _artifact._"
+              echo "_ctest is non-gating while the suite is being refactored. Full logs in the_ \`ctest-results-${BRANCH_SLUG}\` _artifact._"
             else
-              echo "⚠️ No ctest results captured (see \`ctest-results-${BRANCH}\` artifact)."
+              echo "⚠️ No ctest results captured (see \`ctest-results-${BRANCH_SLUG}\` artifact)."
             fi
             echo ""
             echo "### 📦 Artifacts"
             echo ""
-            echo "- \`chronolog-install-${BRANCH}\` — Release install tree with test binaries"
-            echo "- \`ctest-results-${BRANCH}\` — ctest JUnit XML, log, and \`Testing/\` directory"
+            echo "- \`chronolog-install-${BRANCH_SLUG}\` — Release install tree with test binaries"
+            echo "- \`ctest-results-${BRANCH_SLUG}\` — ctest JUnit XML, log, and \`Testing/\` directory"
           } >> "$GITHUB_STEP_SUMMARY"

plugins/chrono-kvs/examples/CMakeLists.txt

@@ -5,6 +5,16 @@ add_executable(chronokvs_reader_example chronokvs_reader_example.cpp)
 target_link_libraries(chronokvs_writer_example PRIVATE chronokvs)
 target_link_libraries(chronokvs_reader_example PRIVATE chronokvs)
 
+# cmd_arg_parse.h lives in chronolog_client's public include dir.
+# chronokvs consumes chronolog_client privately, so pull its include
+# interface in directly here for the examples that use the helper.
+target_include_directories(chronokvs_writer_example PRIVATE
+    $<TARGET_PROPERTY:chronolog_client,INTERFACE_INCLUDE_DIRECTORIES>
+)
+target_include_directories(chronokvs_reader_example PRIVATE
+    $<TARGET_PROPERTY:chronolog_client,INTERFACE_INCLUDE_DIRECTORIES>
+)
+
 set_target_properties(chronokvs_writer_example PROPERTIES
     OUTPUT_NAME chrono-chronokvs-example-writer
     BUILD_WITH_INSTALL_RPATH TRUE

plugins/chrono-kvs/examples/chronokvs_reader_example.cpp

@@ -4,6 +4,7 @@
 #include <iostream>
 #include <fstream>
 #include <vector>
+#include <cmd_arg_parse.h>
 #include "chronokvs.h"
 
 std::vector<std::uint64_t> readTimestampsFromFile(const std::string& filename)
@@ -24,10 +25,20 @@ std::vector<std::uint64_t> readTimestampsFromFile(const std::string& filename)
     return timestamps;
 }
 
-int main()
+int main(int argc, char** argv)
 {
-    // Create ChronoKVS instance
-    chronokvs::ChronoKVS chronoKVS;
+    // Optional ChronoLog client config file (-c/--config). When omitted,
+    // ChronoKVS uses the built-in defaults (localhost deployment).
+    std::string conf_file_path = parse_conf_path_arg(argc, argv);
+
+    // Create ChronoKVS instance: with config file when provided, otherwise defaults.
+    auto chronoKVS =
+            conf_file_path.empty() ? chronokvs::ChronoKVS::Create() : chronokvs::ChronoKVS::Create(conf_file_path);
+    if(!chronoKVS)
+    {
+        std::cerr << "Failed to initialize ChronoKVS\n";
+        return 1;
+    }
 
     // Read timestamps from file
     std::vector<std::uint64_t> timestamps = readTimestampsFromFile("chronokvs_timestamps.txt");
@@ -48,7 +59,7 @@ int main()
 
     // Read and display history for key2
     std::cout << "\nReading history for key2:\n";
-    auto historyForKey2 = chronoKVS.get_history(key2);
+    auto historyForKey2 = chronoKVS->get_history(key2);
 
     if(historyForKey2.empty())
     {
@@ -65,8 +76,8 @@ int main()
 
     // Read specific values for key2 at both timestamps
     std::cout << "Reading specific values for key2:\n";
-    std::string value2_t1 = chronoKVS.get(key2, timestamps[1]);
-    std::string value2_t2 = chronoKVS.get(key2, timestamps[2]);
+    std::string value2_t1 = chronoKVS->get(key2, timestamps[1]);
+    std::string value2_t2 = chronoKVS->get(key2, timestamps[2]);
 
     std::cout << "Value at timestamp " << timestamps[1] << ": " << (value2_t1.empty() ? "Not found" : value2_t1)
               << "\n";
@@ -75,7 +86,7 @@ int main()
 
     // Read and display value for key1
     std::cout << "\nReading value for key1 at timestamp " << timestamps[0] << ":\n";
-    std::string value1 = chronoKVS.get(key1, timestamps[0]);
+    std::string value1 = chronoKVS->get(key1, timestamps[0]);
     if(!value1.empty())
     {
         std::cout << "Value: " << value1 << "\n";
@@ -87,7 +98,7 @@ int main()
 
     // Read and display events in a time range for key2
     std::cout << "\nReading events for key2 in time range [" << timestamps[1] << ", " << timestamps[2] + 1 << "):\n";
-    auto rangeEvents = chronoKVS.get_range(key2, timestamps[1], timestamps[2] + 1);
+    auto rangeEvents = chronoKVS->get_range(key2, timestamps[1], timestamps[2] + 1);
     if(rangeEvents.empty())
     {
         std::cout << "No events found in the specified time range\n";
@@ -103,7 +114,7 @@ int main()
 
     // Read and display the earliest event for key2
     std::cout << "Reading earliest event for key2:\n";
-    auto earliestEvent = chronoKVS.get_earliest(key2);
+    auto earliestEvent = chronoKVS->get_earliest(key2);
     if(earliestEvent.has_value())
     {
         std::cout << "Earliest event - Timestamp: " << earliestEvent->timestamp
@@ -116,7 +127,7 @@ int main()
 
     // Read and display the latest event for key2
     std::cout << "\nReading latest event for key2:\n";
-    auto latestEvent = chronoKVS.get_latest(key2);
+    auto latestEvent = chronoKVS->get_latest(key2);
     if(latestEvent.has_value())
     {
         std::cout << "Latest event - Timestamp: " << latestEvent->timestamp << "\nValue    : " << latestEvent->value

plugins/chrono-kvs/examples/chronokvs_writer_example.cpp

@@ -2,12 +2,23 @@
 #include <string>
 #include <iostream>
 #include <fstream>
+#include <cmd_arg_parse.h>
 #include "chronokvs.h"
 
-int main()
+int main(int argc, char** argv)
 {
-    // Create ChronoKVS instance
-    chronokvs::ChronoKVS chronoKVS;
+    // Optional ChronoLog client config file (-c/--config). When omitted,
+    // ChronoKVS uses the built-in defaults (localhost deployment).
+    std::string conf_file_path = parse_conf_path_arg(argc, argv);
+
+    // Create ChronoKVS instance: with config file when provided, otherwise defaults.
+    auto chronoKVS =
+            conf_file_path.empty() ? chronokvs::ChronoKVS::Create() : chronokvs::ChronoKVS::Create(conf_file_path);
+    if(!chronoKVS)
+    {
+        std::cerr << "Failed to initialize ChronoKVS\n";
+        return 1;
+    }
 
     // Define key-value pairs
     std::string key1 = "key1";
@@ -18,9 +29,9 @@ int main()
 
     // Insert key-value pairs and store timestamps
     std::cout << "Putting key-value pairs into ChronoKVS...\n";
-    std::uint64_t timestamp1 = chronoKVS.put(key1, value1);
-    std::uint64_t timestamp2 = chronoKVS.put(key2, value2);
-    std::uint64_t timestamp3 = chronoKVS.put(key2, value3);
+    std::uint64_t timestamp1 = chronoKVS->put(key1, value1);
+    std::uint64_t timestamp2 = chronoKVS->put(key2, value2);
+    std::uint64_t timestamp3 = chronoKVS->put(key2, value3);
 
     std::cout << "Inserted values with timestamps:\n";
     std::cout << "1. key1=" << value1 << " timestamp=" << timestamp1 << "\n";

plugins/chrono-kvs/include/chronokvs.h

@@ -22,12 +22,52 @@ class ChronoKVS
     std::unique_ptr<ChronoKVSMapper> mapper;
     LogLevel logLevel_;
 
+    // Private constructors. May throw on configuration or connection failure;
+    // the public Create() factories catch those exceptions at the library
+    // boundary and signal failure via a nullptr return.
+    explicit ChronoKVS(LogLevel level);
+    explicit ChronoKVS(const std::string& config_path, LogLevel level);
+
 public:
     /**
-     * @brief Construct a ChronoKVS instance with optional log level
-     * @param level The logging level to use. Default is DEBUG in debug builds, ERROR in release builds.
+     * @brief Create a ChronoKVS instance using built-in default ChronoLog
+     *        client configuration (localhost deployment).
+     *
+     * This factory does not propagate exceptions across the library boundary:
+     * any failure during configuration loading or ChronoLog connection is
+     * logged at the configured @p level and signalled by returning nullptr.
+     *
+     * @param level
+     *     The logging level to use. Default is DEBUG in debug builds, ERROR in release builds.
+     *
+     * @return std::unique_ptr<ChronoKVS>
+     *     A connected ChronoKVS instance, or nullptr if construction failed.
+     */
+    static std::unique_ptr<ChronoKVS> Create(LogLevel level = getDefaultLogLevel()) noexcept;
+
+    /**
+     * @brief Create a ChronoKVS instance using a ChronoLog client configuration file.
+     *
+     * Loads the JSON configuration at @p config_path and uses the resulting portal,
+     * query and logging settings to connect to ChronoLog. Pass an empty string to
+     * fall back to the built-in defaults (localhost deployment).
+     *
+     * This factory does not propagate exceptions across the library boundary:
+     * any failure during configuration loading or ChronoLog connection is
+     * logged at the configured @p level and signalled by returning nullptr.
+     *
+     * @param config_path
+     *     Path to a ChronoLog client configuration JSON file. Empty means
+     *     "use defaults".
+     * @param level
+     *     The logging level to use. Default is DEBUG in debug builds, ERROR in release builds.
+     *
+     * @return std::unique_ptr<ChronoKVS>
+     *     A connected ChronoKVS instance, or nullptr if @p config_path could
+     *     not be loaded or the ChronoLog connection failed.
      */
-    explicit ChronoKVS(LogLevel level = getDefaultLogLevel());
+    static std::unique_ptr<ChronoKVS> Create(const std::string& config_path,
+                                             LogLevel level = getDefaultLogLevel()) noexcept;
 
     /**
      * @brief Get the current log level

plugins/chrono-kvs/src/chronokvs.cpp

@@ -15,6 +15,47 @@ ChronoKVS::ChronoKVS(LogLevel level)
     , logLevel_(level)
 {}
 
+ChronoKVS::ChronoKVS(const std::string& config_path, LogLevel level)
+    : mapper(std::make_unique<ChronoKVSMapper>(config_path, level))
+    , logLevel_(level)
+{}
+
+std::unique_ptr<ChronoKVS> ChronoKVS::Create(LogLevel level) noexcept
+{
+    try
+    {
+        return std::unique_ptr<ChronoKVS>(new ChronoKVS(level));
+    }
+    catch(const std::exception& e)
+    {
+        CHRONOKVS_ERROR(level, "ChronoKVS construction failed: ", e.what());
+        return nullptr;
+    }
+    catch(...)
+    {
+        CHRONOKVS_ERROR(level, "ChronoKVS construction failed: unknown exception");
+        return nullptr;
+    }
+}
+
+std::unique_ptr<ChronoKVS> ChronoKVS::Create(const std::string& config_path, LogLevel level) noexcept
+{
+    try
+    {
+        return std::unique_ptr<ChronoKVS>(new ChronoKVS(config_path, level));
+    }
+    catch(const std::exception& e)
+    {
+        CHRONOKVS_ERROR(level, "ChronoKVS construction failed (config_path='", config_path, "'): ", e.what());
+        return nullptr;
+    }
+    catch(...)
+    {
+        CHRONOKVS_ERROR(level, "ChronoKVS construction failed (config_path='", config_path, "'): unknown exception");
+        return nullptr;
+    }
+}
+
 ChronoKVS::~ChronoKVS() = default;
 
 std::uint64_t ChronoKVS::put(const std::string& key, const std::string& value)

plugins/chrono-kvs/src/chronokvs_client_adapter.cpp

@@ -18,18 +18,38 @@ static int DEFAULT_FLAGS = 0;
 ChronoKVSClientAdapter::ChronoKVSClientAdapter(LogLevel level)
     : logLevel_(level)
 {
-    chronolog::ClientConfiguration confManager;
-
-    // Configure portal and query services from the configuration manager
-    chronolog::ClientPortalServiceConf portalConf{confManager.PORTAL_CONF.PROTO_CONF,
-                                                  confManager.PORTAL_CONF.IP,
-                                                  confManager.PORTAL_CONF.PORT,
-                                                  confManager.PORTAL_CONF.PROVIDER_ID};
-
-    chronolog::ClientQueryServiceConf queryConf{confManager.QUERY_CONF.PROTO_CONF,
-                                                confManager.QUERY_CONF.IP,
-                                                confManager.QUERY_CONF.PORT,
-                                                confManager.QUERY_CONF.PROVIDER_ID};
+    chronolog::ClientConfiguration client_config;
+    initialize(client_config);
+}
+
+ChronoKVSClientAdapter::ChronoKVSClientAdapter(const std::string& config_path, LogLevel level)
+    : logLevel_(level)
+{
+    chronolog::ClientConfiguration client_config;
+    if(!config_path.empty())
+    {
+        CHRONOKVS_INFO(logLevel_, "Loading ChronoLog client configuration from '", config_path, "'");
+        if(!client_config.load_from_file(config_path))
+        {
+            CHRONOKVS_ERROR(logLevel_, "Failed to load configuration file: ", config_path);
+            throw std::runtime_error("Failed to load config file: " + config_path);
+        }
+    }
+    initialize(client_config);
+}
+
+void ChronoKVSClientAdapter::initialize(const chronolog::ClientConfiguration& client_config)
+{
+    // Configure portal and query services from the client configuration
+    chronolog::ClientPortalServiceConf portalConf{client_config.PORTAL_CONF.PROTO_CONF,
+                                                  client_config.PORTAL_CONF.IP,
+                                                  client_config.PORTAL_CONF.PORT,
+                                                  client_config.PORTAL_CONF.PROVIDER_ID};
+
+    chronolog::ClientQueryServiceConf queryConf{client_config.QUERY_CONF.PROTO_CONF,
+                                                client_config.QUERY_CONF.IP,
+                                                client_config.QUERY_CONF.PORT,
+                                                client_config.QUERY_CONF.PROVIDER_ID};
 
     // Initialize and connect the ChronoLog client
     CHRONOKVS_INFO(logLevel_, "Connecting to ChronoLog at ", portalConf.IP, ":", portalConf.PORT);

plugins/chrono-kvs/src/chronokvs_client_adapter.h

@@ -11,6 +11,11 @@
 
 #include <chronolog_client.h>
 
+namespace chronolog
+{
+class ClientConfiguration;
+}
+
 #include "chronokvs_types.h"
 #include "chronokvs_logger.h"
 
@@ -37,9 +42,15 @@ class ChronoKVSClientAdapter
     // Helper method to release and remove a cached handle for a key (before reads)
     void flushCachedHandle(const std::string& key);
 
+    // Connect to ChronoLog using the already-populated configuration and ensure
+    // the default chronicle exists. Used by all constructors.
+    void initialize(const chronolog::ClientConfiguration& client_config);
+
 public:
     explicit ChronoKVSClientAdapter(LogLevel level);
 
+    explicit ChronoKVSClientAdapter(const std::string& config_path, LogLevel level);
+
     ~ChronoKVSClientAdapter();
 
     std::uint64_t storeEvent(const std::string& key, const std::string& value);

plugins/chrono-kvs/src/chronokvs_mapper.cpp

@@ -20,6 +20,12 @@ ChronoKVSMapper::ChronoKVSMapper(LogLevel level)
     chronoClientAdapter = std::make_unique<ChronoKVSClientAdapter>(level);
 }
 
+ChronoKVSMapper::ChronoKVSMapper(const std::string& config_path, LogLevel level)
+    : logLevel_(level)
+{
+    chronoClientAdapter = std::make_unique<ChronoKVSClientAdapter>(config_path, level);
+}
+
 std::uint64_t ChronoKVSMapper::storeKeyValue(const std::string& key, const std::string& value)
 {
     // Input validation