docs: Fix graceful_period description (#2791)

Co-authored-by: Ayaz Salikhov <mathbunnyru@users.noreply.github.com>

.github/scripts/conan/generate_matrix.py

@@ -4,7 +4,7 @@ import json
 
 LINUX_OS = ["heavy", "heavy-arm64"]
 LINUX_CONTAINERS = [
-    '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
+    '{ "image": "ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7" }'
 ]
 LINUX_COMPILERS = ["gcc", "clang"]
 

.github/workflows/build.yml

@@ -49,7 +49,7 @@ jobs:
         build_type: [Release, Debug]
         container:
           [
-            '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }',
+            '{ "image": "ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7" }',
           ]
         static: [true]
 
@@ -79,7 +79,7 @@ jobs:
     uses: ./.github/workflows/reusable-build.yml
     with:
       runs_on: heavy
-      container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
+      container: '{ "image": "ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7" }'
       conan_profile: gcc
       build_type: Debug
       download_ccache: true
@@ -98,7 +98,7 @@ jobs:
     uses: ./.github/workflows/reusable-build.yml
     with:
       runs_on: heavy
-      container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
+      container: '{ "image": "ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7" }'
       conan_profile: gcc
       build_type: Release
       download_ccache: true
@@ -115,7 +115,7 @@ jobs:
     needs: build-and-test
     runs-on: heavy
     container:
-      image: ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
+      image: ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7
 
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0

.github/workflows/check-libxrpl.yml

@@ -21,7 +21,7 @@ jobs:
     name: Build Clio / `libXRPL ${{ github.event.client_payload.version }}`
     runs-on: heavy
     container:
-      image: ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
+      image: ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7
 
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
@@ -69,7 +69,7 @@ jobs:
     needs: build
     runs-on: heavy
     container:
-      image: ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
+      image: ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7
 
     steps:
       - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0

.github/workflows/clang-tidy.yml

@@ -31,7 +31,7 @@ jobs:
     if: github.event_name != 'push' || contains(github.event.head_commit.message, 'clang-tidy auto fixes')
     runs-on: heavy
     container:
-      image: ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
+      image: ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7
 
     permissions:
       contents: write

.github/workflows/docs.yml

@@ -18,7 +18,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     container:
-      image: ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
+      image: ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7
 
     steps:
       - name: Checkout

.github/workflows/nightly.yml

@@ -43,17 +43,17 @@ jobs:
             conan_profile: gcc
             build_type: Release
             static: true
-            container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
+            container: '{ "image": "ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7" }'
           - os: heavy
             conan_profile: gcc
             build_type: Debug
             static: true
-            container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
+            container: '{ "image": "ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7" }'
           - os: heavy
             conan_profile: gcc.ubsan
             build_type: Release
             static: false
-            container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
+            container: '{ "image": "ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7" }'
 
     uses: ./.github/workflows/reusable-build-test.yml
     with:
@@ -77,7 +77,7 @@ jobs:
         include:
           - os: heavy
             conan_profile: clang
-            container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
+            container: '{ "image": "ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7" }'
             static: true
           - os: macos15
             conan_profile: apple-clang

.github/workflows/release.yml

@@ -29,7 +29,7 @@ jobs:
             conan_profile: gcc
             build_type: Release
             static: true
-            container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
+            container: '{ "image": "ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7" }'
 
     uses: ./.github/workflows/reusable-build-test.yml
     with:

.github/workflows/reusable-release.yml

@@ -46,7 +46,7 @@ jobs:
   release:
     runs-on: heavy
     container:
-      image: ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
+      image: ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7
     env:
       GH_REPO: ${{ github.repository }}
       GH_TOKEN: ${{ github.token }}

.github/workflows/sanitizers.yml

@@ -44,14 +44,13 @@ jobs:
     uses: ./.github/workflows/reusable-build-test.yml
     with:
       runs_on: heavy
-      container: '{ "image": "ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8" }'
+      container: '{ "image": "ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7" }'
       download_ccache: false
       upload_ccache: false
       conan_profile: ${{ matrix.compiler }}${{ matrix.sanitizer_ext }}
       build_type: ${{ matrix.build_type }}
       static: false
-      # Currently, both gcc.tsan and clang.tsan unit tests hang
-      run_unit_tests: ${{ matrix.sanitizer_ext != '.tsan' }}
+      run_unit_tests: true
       run_integration_tests: false
       upload_clio_server: false
       targets: clio_tests clio_integration_tests

CMakeLists.txt

@@ -75,11 +75,6 @@ if (san)
   endif ()
   target_compile_options(clio_options INTERFACE ${SAN_OPTIMIZATION_FLAG} ${SAN_FLAG} -fno-omit-frame-pointer)
 
-  if (san STREQUAL "address")
-    # ASAN needs these definitions as well as correct b2 flags in conan profile for sanitizers
-    target_compile_definitions(clio_options INTERFACE BOOST_USE_ASAN=1 BOOST_USE_UCONTEXT=1)
-  endif ()
-
   target_link_libraries(clio_options INTERFACE ${SAN_FLAG} ${SAN_LIB})
 endif ()
 

docker/ci/conan/sanitizer_template.profile

@@ -3,7 +3,11 @@
 {% set sanitizer_opt_map = {"asan": "address", "tsan": "thread", "ubsan": "undefined"} %}
 {% set sanitizer = sanitizer_opt_map[sani] %}
 
-{% set sanitizer_b2_flags_map = {"address": "define=BOOST_USE_ASAN=1 context-impl=ucontext address-sanitizer=on", "thread": "thread-sanitizer=on", "undefined": "undefined-sanitizer=on"} %}
+{% set sanitizer_b2_flags_map = {
+    "address": "context-impl=ucontext address-sanitizer=norecover",
+    "thread": "context-impl=ucontext thread-sanitizer=norecover",
+    "undefined": "undefined-sanitizer=norecover"
+} %}
 {% set sanitizer_b2_flags_str = sanitizer_b2_flags_map[sanitizer] %}
 
 {% set sanitizer_build_flags_str = "-fsanitize=" ~ sanitizer ~ " -g -O1 -fno-omit-frame-pointer" %}
@@ -24,4 +28,10 @@ tools.build:cxxflags+={{ sanitizer_build_flags }}
 tools.build:exelinkflags+={{ sanitizer_link_flags }}
 tools.build:sharedlinkflags+={{ sanitizer_link_flags }}
 
-tools.info.package_id:confs+=["tools.build:cflags", "tools.build:cxxflags", "tools.build:exelinkflags", "tools.build:sharedlinkflags"]
+{% if sanitizer == "address" %}
+    tools.build:defines+=["BOOST_USE_ASAN", "BOOST_USE_UCONTEXT"]
+{% elif sanitizer == "thread" %}
+    tools.build:defines+=["BOOST_USE_TSAN", "BOOST_USE_UCONTEXT"]
+{% endif %}
+
+tools.info.package_id:confs+=["tools.build:cflags", "tools.build:cxxflags", "tools.build:exelinkflags", "tools.build:sharedlinkflags", "tools.build:defines"]

docker/develop/compose.yaml

@@ -1,6 +1,6 @@
 services:
   clio_develop:
-    image: ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
+    image: ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7
     volumes:
       - clio_develop_conan_data:/root/.conan2/p
       - clio_develop_ccache:/root/.ccache

docs/build-clio.md

@@ -191,7 +191,7 @@ Open the `index.html` file in your browser to see the documentation pages.
 It is also possible to build Clio using [Docker](https://www.docker.com/) if you don't want to install all the dependencies on your machine.
 
 ```sh
-docker run -it ghcr.io/xrplf/clio-ci:62369411404eb32b0140603a785ff05e1dc36ce8
+docker run -it ghcr.io/xrplf/clio-ci:77387d8f9f13aea8f23831d221ac3e7683bb69b7
 git clone https://github.com/XRPLF/clio
 cd clio
 ```

docs/config-description.md

@@ -391,7 +391,7 @@ This document provides a list of all available Clio configuration properties in
 - **Type**: double
 - **Default value**: `10`
 - **Constraints**: The value must be a positive double number.
-- **Description**: The number of milliseconds the server waits to shutdown gracefully. If Clio does not shutdown gracefully after the specified value, it will be killed instead.
+- **Description**: The number of seconds the server waits to shutdown gracefully. If Clio does not shutdown gracefully after the specified value, it will be killed instead.
 
 ### cache.num_diffs
 

src/app/ClioApplication.cpp

@@ -25,6 +25,7 @@
 #include "data/AmendmentCenter.hpp"
 #include "data/BackendFactory.hpp"
 #include "data/LedgerCache.hpp"
+#include "data/LedgerCacheSaver.hpp"
 #include "etl/ETLService.hpp"
 #include "etl/LoadBalancer.hpp"
 #include "etl/NetworkValidatedLedgers.hpp"
@@ -98,14 +99,15 @@ ClioApplication::run(bool const useNgWebServer)
     auto const threads = config_.get<uint16_t>("io_threads");
     LOG(util::LogService::info()) << "Number of io threads = " << threads;
 
+    // Similarly we need a context to run ETL on
+    // In the future we can remove the raw ioc and use ctx instead
+    // This context should be above ioc because its reference is getting into tasks inside ioc
+    util::async::CoroExecutionContext ctx{threads};
+
     // IO context to handle all incoming requests, as well as other things.
     // This is not the only io context in the application.
     boost::asio::io_context ioc{threads};
 
-    // Similarly we need a context to run ETL on
-    // In the future we can remove the raw ioc and use ctx instead
-    util::async::CoroExecutionContext ctx{threads};
-
     // Rate limiter, to prevent abuse
     auto whitelistHandler = web::dosguard::WhitelistHandler{config_};
     auto const dosguardWeights = web::dosguard::Weights::make(config_);
@@ -113,21 +115,7 @@ ClioApplication::run(bool const useNgWebServer)
     auto sweepHandler = web::dosguard::IntervalSweepHandler{config_, ioc, dosGuard};
 
     auto cache = data::LedgerCache{};
-    appStopper_.setOnStop([&cache, this](auto&&) {
-        // TODO(kuznetsss): move this into Stopper::makeOnStopCallback()
-        auto const cacheFilePath = config_.maybeValue<std::string>("cache.file.path");
-        if (not cacheFilePath.has_value()) {
-            return;
-        }
-
-        LOG(util::LogService::info()) << "Saving ledger cache to " << *cacheFilePath;
-        if (auto const [success, duration_ms] = util::timed([&]() { return cache.saveToFile(*cacheFilePath); });
-            success.has_value()) {
-            LOG(util::LogService::info()) << "Successfully saved ledger cache in " << duration_ms << " ms";
-        } else {
-            LOG(util::LogService::error()) << "Error saving LedgerCache to file";
-        }
-    });
+    auto cacheSaver = data::LedgerCacheSaver{config_, cache};
 
     // Interface to the database
     auto backend = data::makeBackend(config_, cache);
@@ -208,7 +196,7 @@ ClioApplication::run(bool const useNgWebServer)
         }
 
         appStopper_.setOnStop(
-            Stopper::makeOnStopCallback(httpServer.value(), *balancer, *etl, *subscriptions, *backend, ioc)
+            Stopper::makeOnStopCallback(httpServer.value(), *balancer, *etl, *subscriptions, *backend, cacheSaver, ioc)
         );
 
         // Blocks until stopped.
@@ -223,6 +211,9 @@ ClioApplication::run(bool const useNgWebServer)
     auto handler = std::make_shared<web::RPCServerHandler<RPCEngineType>>(config_, backend, rpcEngine, etl, dosGuard);
 
     auto const httpServer = web::makeHttpServer(config_, ioc, dosGuard, handler, cache);
+    appStopper_.setOnStop(
+        Stopper::makeOnStopCallback(*httpServer, *balancer, *etl, *subscriptions, *backend, cacheSaver, ioc)
+    );
 
     // Blocks until stopped.
     // When stopped, shared_ptrs fall out of scope

src/app/Stopper.hpp

@@ -20,12 +20,13 @@
 #pragma once
 
 #include "data/BackendInterface.hpp"
+#include "data/LedgerCacheSaver.hpp"
 #include "etl/ETLServiceInterface.hpp"
 #include "etl/LoadBalancerInterface.hpp"
 #include "feed/SubscriptionManagerInterface.hpp"
 #include "util/CoroutineGroup.hpp"
 #include "util/log/Logger.hpp"
-#include "web/ng/Server.hpp"
+#include "web/interface/Concepts.hpp"
 
 #include <boost/asio/executor_work_guard.hpp>
 #include <boost/asio/io_context.hpp>
@@ -71,10 +72,11 @@ public:
      * @param etl The ETL service to stop.
      * @param subscriptions The subscription manager to stop.
      * @param backend The backend to stop.
+     * @param cacheSaver The ledger cache saver
      * @param ioc The io_context to stop.
      * @return The callback to be called on application stop.
      */
-    template <web::ng::SomeServer ServerType>
+    template <web::SomeServer ServerType, data::SomeLedgerCacheSaver LedgerCacheSaverType>
     static std::function<void(boost::asio::yield_context)>
     makeOnStopCallback(
         ServerType& server,
@@ -82,10 +84,13 @@ public:
         etl::ETLServiceInterface& etl,
         feed::SubscriptionManagerInterface& subscriptions,
         data::BackendInterface& backend,
+        LedgerCacheSaverType& cacheSaver,
         boost::asio::io_context& ioc
     )
     {
         return [&](boost::asio::yield_context yield) {
+            cacheSaver.save();
+
             util::CoroutineGroup coroutineGroup{yield};
             coroutineGroup.spawn(yield, [&server](auto innerYield) {
                 server.stop(innerYield);
@@ -106,6 +111,8 @@ public:
             backend.waitForWritesToFinish();
             LOG(util::LogService::info()) << "Backend writes finished";
 
+            cacheSaver.waitToFinish();
+
             ioc.stop();
             LOG(util::LogService::info()) << "io_context stopped";
 

src/data/CMakeLists.txt

@@ -5,6 +5,7 @@ target_sources(
           BackendCounters.cpp
           BackendInterface.cpp
           LedgerCache.cpp
+          LedgerCacheSaver.cpp
           LedgerHeaderCache.cpp
           cassandra/impl/Future.cpp
           cassandra/impl/Cluster.cpp

src/data/LedgerCache.cpp

@@ -265,7 +265,7 @@ LedgerCache::saveToFile(std::string const& path) const
     }
 
     impl::LedgerCacheFile file{path};
-    std::unique_lock const lock{mtx_};
+    std::shared_lock const lock{mtx_};
     impl::LedgerCacheFile::DataView const data{.latestSeq = latestSeq_, .map = map_, .deleted = deleted_};
     return file.write(data);
 }

src/data/LedgerCache.hpp

@@ -145,15 +145,8 @@ public:
     void
     waitUntilCacheContainsSeq(uint32_t seq) override;
 
-    /**
-     * @brief Save the cache to file
-     * @note This operation takes about 7 seconds and it keeps mtx_ exclusively locked
-     *
-     * @param path The file path to save the cache to
-     * @return An error as a string if any
-     */
     std::expected<void, std::string>
-    saveToFile(std::string const& path) const;
+    saveToFile(std::string const& path) const override;
 
     std::expected<void, std::string>
     loadFromFile(std::string const& path, uint32_t minLatestSequence) override;

src/data/LedgerCacheInterface.hpp

@@ -171,6 +171,16 @@ public:
     virtual void
     waitUntilCacheContainsSeq(uint32_t seq) = 0;
 
+    /**
+     * @brief Save the cache to file
+     * @note This operation takes about 7 seconds and it keeps a shared lock of mtx_
+     *
+     * @param path The file path to save the cache to
+     * @return An error as a string if any
+     */
+    [[nodiscard]] virtual std::expected<void, std::string>
+    saveToFile(std::string const& path) const = 0;
+
     /**
      * @brief Load the cache from file
      * @note This operation takes about 7 seconds and it keeps mtx_ exclusively locked

src/data/LedgerCacheSaver.cpp

@@ -0,0 +1,70 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and 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 THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH  REGARD  TO  THIS  SOFTWARE  INCLUDING  ALL  IMPLIED  WARRANTIES  OF
+    MERCHANTABILITY  AND  FITNESS. IN NO EVENT SHALL THE AUTHOR 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 "data/LedgerCacheSaver.hpp"
+
+#include "data/LedgerCacheInterface.hpp"
+#include "util/Assert.hpp"
+#include "util/Profiler.hpp"
+#include "util/log/Logger.hpp"
+
+#include <string>
+#include <thread>
+
+namespace data {
+
+LedgerCacheSaver::LedgerCacheSaver(util::config::ClioConfigDefinition const& config, LedgerCacheInterface const& cache)
+    : cacheFilePath_(config.maybeValue<std::string>("cache.file.path")), cache_(cache)
+{
+}
+
+LedgerCacheSaver::~LedgerCacheSaver()
+{
+    waitToFinish();
+}
+
+void
+LedgerCacheSaver::save()
+{
+    ASSERT(not savingThread_.has_value(), "Multiple save() calls are not allowed");
+    savingThread_ = std::thread([this]() {
+        if (not cacheFilePath_.has_value()) {
+            return;
+        }
+
+        LOG(util::LogService::info()) << "Saving ledger cache to " << *cacheFilePath_;
+        if (auto const [success, durationMs] = util::timed([&]() { return cache_.get().saveToFile(*cacheFilePath_); });
+            success.has_value()) {
+            LOG(util::LogService::info()) << "Successfully saved ledger cache in " << durationMs << " ms";
+        } else {
+            LOG(util::LogService::error()) << "Error saving LedgerCache to file";
+        }
+    });
+}
+
+void
+LedgerCacheSaver::waitToFinish()
+{
+    if (savingThread_.has_value() and savingThread_->joinable()) {
+        savingThread_->join();
+    }
+    savingThread_.reset();
+}
+
+}  // namespace data

src/data/LedgerCacheSaver.hpp

@@ -0,0 +1,93 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and 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 THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH  REGARD  TO  THIS  SOFTWARE  INCLUDING  ALL  IMPLIED  WARRANTIES  OF
+    MERCHANTABILITY  AND  FITNESS. IN NO EVENT SHALL THE AUTHOR 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.
+*/
+//==============================================================================
+
+#pragma once
+
+#include "data/LedgerCacheInterface.hpp"
+#include "util/config/ConfigDefinition.hpp"
+
+#include <concepts>
+#include <functional>
+#include <optional>
+#include <string>
+#include <thread>
+
+namespace data {
+
+/**
+ * @brief A concept for a class that can save ledger cache asynchronously.
+ *
+ * This concept defines the interface requirements for any type that manages
+ * asynchronous saving of ledger cache to persistent storage.
+ */
+template <typename T>
+concept SomeLedgerCacheSaver = requires(T a) {
+    { a.save() } -> std::same_as<void>;
+    { a.waitToFinish() } -> std::same_as<void>;
+};
+
+/**
+ * @brief Manages asynchronous saving of ledger cache to a file.
+ *
+ * This class provides functionality to save the ledger cache to a file in a separate thread,
+ * allowing the main application to continue without blocking. The file path is configured
+ * through the application's configuration system.
+ */
+class LedgerCacheSaver {
+    std::optional<std::string> cacheFilePath_;
+    std::reference_wrapper<LedgerCacheInterface const> cache_;
+    std::optional<std::thread> savingThread_;
+
+public:
+    /**
+     * @brief Constructs a LedgerCacheSaver instance.
+     *
+     * @param config The configuration object containing the cache file path setting
+     * @param cache Reference to the ledger cache interface to be saved
+     */
+    LedgerCacheSaver(util::config::ClioConfigDefinition const& config, LedgerCacheInterface const& cache);
+
+    /**
+     * @brief Destructor that ensures the saving thread is properly joined.
+     *
+     * Waits for any ongoing save operation to complete before destruction.
+     */
+    ~LedgerCacheSaver();
+
+    /**
+     * @brief Initiates an asynchronous save operation of the ledger cache.
+     *
+     * Spawns a new thread that saves the ledger cache to the configured file path.
+     * If no file path is configured, the operation is skipped. Logs the progress
+     * and result of the save operation.
+     */
+    void
+    save();
+
+    /**
+     * @brief Waits for the saving thread to complete.
+     *
+     * Blocks until the saving operation finishes if a thread is currently active.
+     * Safe to call multiple times or when no save operation is in progress.
+     */
+    void
+    waitToFinish();
+};
+
+}  // namespace data

src/util/StopHelper.cpp

@@ -19,6 +19,8 @@
 
 #include "util/StopHelper.hpp"
 
+#include "util/Spawn.hpp"
+
 #include <boost/asio/spawn.hpp>
 #include <boost/asio/steady_timer.hpp>
 
@@ -37,7 +39,7 @@ void
 StopHelper::asyncWaitForStop(boost::asio::yield_context yield)
 {
     boost::asio::steady_timer timer{yield.get_executor(), std::chrono::steady_clock::duration::max()};
-    onStopReady_.connect([&timer]() { timer.cancel(); });
+    onStopReady_.connect([&]() { util::spawn(yield, [&timer](auto&&) { timer.cancel(); }); });
     boost::system::error_code error;
     if (!*stopped_)
         timer.async_wait(yield[error]);

src/util/StopHelper.hpp

@@ -36,6 +36,16 @@ class StopHelper {
     std::unique_ptr<std::atomic_bool> stopped_ = std::make_unique<std::atomic_bool>(false);
 
 public:
+    StopHelper() = default;
+    ~StopHelper() = default;
+
+    StopHelper(StopHelper&&) = delete;
+    StopHelper&
+    operator=(StopHelper&&) = delete;
+    StopHelper(StopHelper const&) = delete;
+    StopHelper&
+    operator=(StopHelper const&) = delete;
+
     /**
      * @brief Notify that the class is ready to stop.
      */

src/util/config/ConfigDescription.hpp

@@ -255,7 +255,7 @@ This document provides a list of all available Clio configuration properties in
            .value = "The number of worker threads or processes that are responsible for managing and processing "
                     "subscription-based tasks from `rippled`."},
         KV{.key = "graceful_period",
-           .value = "The number of milliseconds the server waits to shutdown gracefully. If Clio does not shutdown "
+           .value = "The number of seconds the server waits to shutdown gracefully. If Clio does not shutdown "
                     "gracefully after the specified value, it will be killed instead."},
         KV{.key = "cache.num_diffs",
            .value = "The number of cursors generated is the number of changed (without counting deleted) objects in "

src/web/Server.hpp

@@ -34,6 +34,7 @@
 #include <boost/asio/ip/address.hpp>
 #include <boost/asio/ip/tcp.hpp>
 #include <boost/asio/socket_base.hpp>
+#include <boost/asio/spawn.hpp>
 #include <boost/asio/ssl/context.hpp>
 #include <boost/asio/ssl/error.hpp>
 #include <boost/asio/strand.hpp>
@@ -43,6 +44,7 @@
 #include <boost/beast/core/tcp_stream.hpp>
 #include <fmt/format.h>
 
+#include <atomic>
 #include <chrono>
 #include <cstdint>
 #include <exception>
@@ -221,7 +223,8 @@ template <
     template <typename> class PlainSessionType,
     template <typename> class SslSessionType,
     SomeServerHandler HandlerType>
-class Server : public std::enable_shared_from_this<Server<PlainSessionType, SslSessionType, HandlerType>> {
+class Server : public ServerTag,
+               public std::enable_shared_from_this<Server<PlainSessionType, SslSessionType, HandlerType>> {
     using std::enable_shared_from_this<Server<PlainSessionType, SslSessionType, HandlerType>>::shared_from_this;
 
     util::Logger log_{"WebServer"};
@@ -235,6 +238,7 @@ class Server : public std::enable_shared_from_this<Server<PlainSessionType, SslS
     std::shared_ptr<AdminVerificationStrategy> adminVerification_;
     std::uint32_t maxWsSendingQueueSize_;
     std::shared_ptr<ProxyIpResolver> proxyIpResolver_;
+    std::atomic_bool isStopped_{false};
 
 public:
     /**
@@ -308,6 +312,13 @@ public:
         doAccept();
     }
 
+    /** @brief Stop accepting new connections */
+    void
+    stop(boost::asio::yield_context)
+    {
+        isStopped_ = true;
+    }
+
 private:
     void
     doAccept()
@@ -321,6 +332,10 @@ private:
     void
     onAccept(boost::beast::error_code ec, tcp::socket socket)
     {
+        if (isStopped_) {
+            return;
+        }
+
         if (!ec) {
             auto ctxRef =
                 ctx_ ? std::optional<std::reference_wrapper<boost::asio::ssl::context>>{ctx_.value()} : std::nullopt;

src/web/interface/Concepts.hpp

@@ -22,6 +22,7 @@
 #include <boost/beast.hpp>
 #include <boost/beast/core/error.hpp>
 
+#include <concepts>
 #include <memory>
 #include <string>
 
@@ -39,4 +40,14 @@ concept SomeServerHandler =
         { handler(req, ws) };
     };
 
+/**
+ * @brief A tag class for server to help identify Server in templated code.
+ */
+struct ServerTag {
+    virtual ~ServerTag() = default;
+};
+
+template <typename T>
+concept SomeServer = std::derived_from<T, ServerTag>;
+
 }  // namespace web

src/web/ng/Server.hpp

@@ -23,6 +23,7 @@
 #include "util/config/ConfigDefinition.hpp"
 #include "util/log/Logger.hpp"
 #include "web/ProxyIpResolver.hpp"
+#include "web/interface/Concepts.hpp"
 #include "web/ng/Connection.hpp"
 #include "web/ng/MessageHandler.hpp"
 #include "web/ng/ProcessingPolicy.hpp"
@@ -34,7 +35,6 @@
 #include <boost/asio/spawn.hpp>
 #include <boost/asio/ssl/context.hpp>
 
-#include <concepts>
 #include <cstddef>
 #include <functional>
 #include <optional>
@@ -42,16 +42,6 @@
 
 namespace web::ng {
 
-/**
- * @brief A tag class for server to help identify Server in templated code.
- */
-struct ServerTag {
-    virtual ~ServerTag() = default;
-};
-
-template <typename T>
-concept SomeServer = std::derived_from<T, ServerTag>;
-
 /**
  * @brief Web server class.
  */

tests/common/util/MockLedgerCache.hpp

@@ -79,6 +79,9 @@ struct MockLedgerCache : data::LedgerCacheInterface {
 
     MOCK_METHOD(void, waitUntilCacheContainsSeq, (uint32_t), (override));
 
+    using SaveToFileReturnType = std::expected<void, std::string>;
+    MOCK_METHOD(SaveToFileReturnType, saveToFile, (std::string const& path), (const, override));
+
     using LoadFromFileReturnType = std::expected<void, std::string>;
     MOCK_METHOD(
         LoadFromFileReturnType,

tests/unit/CMakeLists.txt

@@ -11,6 +11,7 @@ target_sources(
           data/BackendCountersTests.cpp
           data/BackendInterfaceTests.cpp
           data/LedgerCacheTests.cpp
+          data/LedgerCacheSaverTests.cpp
           data/cassandra/AsyncExecutorTests.cpp
           data/cassandra/ExecutionStrategyTests.cpp
           data/cassandra/LedgerHeaderCacheTests.cpp

tests/unit/app/StopperTests.cpp

@@ -24,7 +24,7 @@
 #include "util/MockPrometheus.hpp"
 #include "util/MockSubscriptionManager.hpp"
 #include "util/config/ConfigDefinition.hpp"
-#include "web/ng/Server.hpp"
+#include "web/interface/Concepts.hpp"
 
 #include <boost/asio/executor_work_guard.hpp>
 #include <boost/asio/io_context.hpp>
@@ -61,16 +61,22 @@ TEST_F(StopperTest, stopCalledMultipleTimes)
 }
 
 struct StopperMakeCallbackTest : util::prometheus::WithPrometheus, SyncAsioContextTest {
-    struct ServerMock : web::ng::ServerTag {
+    struct ServerMock : web::ServerTag {
         MOCK_METHOD(void, stop, (boost::asio::yield_context), ());
     };
 
+    struct MockLedgerCacheSaver {
+        MOCK_METHOD(void, save, ());
+        MOCK_METHOD(void, waitToFinish, ());
+    };
+
 protected:
     testing::StrictMock<ServerMock> serverMock_;
     testing::StrictMock<MockLoadBalancer> loadBalancerMock_;
     testing::StrictMock<MockETLService> etlServiceMock_;
     testing::StrictMock<MockSubscriptionManager> subscriptionManagerMock_;
     testing::StrictMock<MockBackend> backendMock_{util::config::ClioConfigDefinition{}};
+    testing::StrictMock<MockLedgerCacheSaver> cacheSaverMock_;
     boost::asio::io_context ioContextToStop_;
 
     bool
@@ -86,10 +92,17 @@ TEST_F(StopperMakeCallbackTest, makeCallbackTest)
     std::thread t{[this]() { ioContextToStop_.run(); }};
 
     auto callback = Stopper::makeOnStopCallback(
-        serverMock_, loadBalancerMock_, etlServiceMock_, subscriptionManagerMock_, backendMock_, ioContextToStop_
+        serverMock_,
+        loadBalancerMock_,
+        etlServiceMock_,
+        subscriptionManagerMock_,
+        backendMock_,
+        cacheSaverMock_,
+        ioContextToStop_
     );
 
     testing::Sequence const s1, s2;
+    EXPECT_CALL(cacheSaverMock_, save).InSequence(s1).WillOnce([this]() { EXPECT_FALSE(isContextStopped()); });
     EXPECT_CALL(serverMock_, stop).InSequence(s1).WillOnce([this]() { EXPECT_FALSE(isContextStopped()); });
     EXPECT_CALL(loadBalancerMock_, stop).InSequence(s2).WillOnce([this]() { EXPECT_FALSE(isContextStopped()); });
     EXPECT_CALL(etlServiceMock_, stop).InSequence(s1, s2).WillOnce([this]() { EXPECT_FALSE(isContextStopped()); });
@@ -99,6 +112,7 @@ TEST_F(StopperMakeCallbackTest, makeCallbackTest)
     EXPECT_CALL(backendMock_, waitForWritesToFinish).InSequence(s1, s2).WillOnce([this]() {
         EXPECT_FALSE(isContextStopped());
     });
+    EXPECT_CALL(cacheSaverMock_, waitToFinish).InSequence(s1).WillOnce([this]() { EXPECT_FALSE(isContextStopped()); });
 
     runSpawn([&](boost::asio::yield_context yield) {
         callback(yield);

tests/unit/data/LedgerCacheSaverTests.cpp

@@ -0,0 +1,156 @@
+//------------------------------------------------------------------------------
+/*
+    This file is part of clio: https://github.com/XRPLF/clio
+    Copyright (c) 2025, the clio developers.
+
+    Permission to use, copy, modify, and 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 THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH  REGARD  TO  THIS  SOFTWARE  INCLUDING  ALL  IMPLIED  WARRANTIES  OF
+    MERCHANTABILITY  AND  FITNESS. IN NO EVENT SHALL THE AUTHOR 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 "data/LedgerCacheSaver.hpp"
+#include "util/MockAssert.hpp"
+#include "util/MockLedgerCache.hpp"
+#include "util/config/ConfigDefinition.hpp"
+#include "util/config/ConfigFileJson.hpp"
+#include "util/config/ConfigValue.hpp"
+#include "util/config/Types.hpp"
+
+#include <boost/json/object.hpp>
+#include <boost/json/parse.hpp>
+#include <boost/json/value.hpp>
+#include <fmt/format.h>
+#include <gmock/gmock.h>
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <chrono>
+#include <expected>
+#include <semaphore>
+#include <string>
+#include <thread>
+
+using namespace data;
+using namespace util::config;
+
+struct LedgerCacheSaverTest : virtual testing::Test {
+    testing::StrictMock<MockLedgerCache> cache;
+    constexpr static auto kFILE_PATH = "./cache.bin";
+
+    static ClioConfigDefinition
+    generateConfig(bool cacheFilePathHasValue)
+    {
+        auto config = ClioConfigDefinition{{
+            {"cache.file.path", ConfigValue{ConfigType::String}.optional()},
+        }};
+
+        ConfigFileJson jsonFile{boost::json::object{}};
+        if (cacheFilePathHasValue) {
+            auto const jsonObject =
+                boost::json::parse(fmt::format(R"JSON({{"cache": {{"file": {{"path": "{}"}}}}}})JSON", kFILE_PATH))
+                    .as_object();
+            jsonFile = ConfigFileJson{jsonObject};
+        }
+        auto const errors = config.parse(jsonFile);
+        EXPECT_FALSE(errors.has_value());
+        return config;
+    }
+};
+
+TEST_F(LedgerCacheSaverTest, SaveSuccessfully)
+{
+    auto const config = generateConfig(true);
+    LedgerCacheSaver saver{config, cache};
+
+    EXPECT_CALL(cache, saveToFile(kFILE_PATH)).WillOnce(testing::Return(std::expected<void, std::string>{}));
+
+    saver.save();
+    saver.waitToFinish();
+}
+
+TEST_F(LedgerCacheSaverTest, SaveWithError)
+{
+    auto const config = generateConfig(true);
+    LedgerCacheSaver saver{config, cache};
+
+    EXPECT_CALL(cache, saveToFile(kFILE_PATH))
+        .WillOnce(testing::Return(std::expected<void, std::string>(std::unexpected("Failed to save"))));
+
+    saver.save();
+    saver.waitToFinish();
+}
+
+TEST_F(LedgerCacheSaverTest, NoSaveWhenPathNotConfigured)
+{
+    auto const config = generateConfig(false);
+
+    LedgerCacheSaver saver{config, cache};
+    saver.save();
+    saver.waitToFinish();
+}
+
+TEST_F(LedgerCacheSaverTest, DestructorWaitsForCompletion)
+{
+    auto const config = generateConfig(true);
+
+    std::binary_semaphore semaphore{1};
+    std::atomic_bool saveCompleted{false};
+
+    EXPECT_CALL(cache, saveToFile(kFILE_PATH)).WillOnce([&]() {
+        semaphore.release();
+        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+        saveCompleted = true;
+        return std::expected<void, std::string>{};
+    });
+
+    {
+        LedgerCacheSaver saver{config, cache};
+        saver.save();
+        EXPECT_TRUE(semaphore.try_acquire_for(std::chrono::seconds{5}));
+    }
+
+    EXPECT_TRUE(saveCompleted);
+}
+
+TEST_F(LedgerCacheSaverTest, WaitToFinishCanBeCalledMultipleTimes)
+{
+    auto const config = generateConfig(true);
+    LedgerCacheSaver saver{config, cache};
+
+    EXPECT_CALL(cache, saveToFile(kFILE_PATH));
+
+    saver.save();
+    saver.waitToFinish();
+    EXPECT_NO_THROW(saver.waitToFinish());
+}
+
+TEST_F(LedgerCacheSaverTest, WaitToFinishWithoutSaveIsSafe)
+{
+    auto const config = generateConfig(true);
+    LedgerCacheSaver saver{config, cache};
+    EXPECT_NO_THROW(saver.waitToFinish());
+}
+
+struct LedgerCacheSaverAssertTest : LedgerCacheSaverTest, common::util::WithMockAssert {};
+
+TEST_F(LedgerCacheSaverAssertTest, MultipleSavesNotAllowed)
+{
+    auto const config = generateConfig(true);
+
+    LedgerCacheSaver saver{config, cache};
+
+    EXPECT_CALL(cache, saveToFile(kFILE_PATH));
+    saver.save();
+    EXPECT_CLIO_ASSERT_FAIL({ saver.save(); });
+
+    saver.waitToFinish();
+}