fix: Improve concurrent path_find

API-CHANGELOG.md

@@ -26,6 +26,14 @@ This version is supported by all `xrpld` versions. For WebSocket and HTTP JSON-R
 
 This section contains changes targeting a future version.
 
+### Changes
+
+- `path_find` / `ripple_path_find`: Path selection no longer reserves a full-liquidity "covering" (spare) path and no longer requires the last alternative to alone fill the payment. The server returns up to **six** ranked path alternatives per source asset (`paths_computed`), filled by quality and liquidity only. Previously, the set was capped at four paths, the final slot had to be able to complete the payment by itself (assuming no liquidity overlap), and if the combined set failed with `tecPATH_PARTIAL` / `terNO_LINE` the calculation could be retried with an extra covering path. That retry path is removed. Pathfinding remains best-effort. This is an intentional product tradeoff: under concurrent load, clients benefit more from a fuller set of real alternatives than from a reserved single full-liquidity spare. See implementation comments in `Pathfinder::getBestPaths` / `findPaths` and `PathRequest`. ([#7962](https://github.com/XRPLF/rippled/pull/7962))
+  - **Optional new field:** WebSocket `path_find` updates may include `warning` values:
+    - `"path_lines_partial"` — trust lines for accounts used by **this** subscription are still being filled progressively (owner-directory chunk load).
+    - `"path_revalidate_failed"` — incremental revalidate found no live paths; the server re-sent the previous `alternatives` for display only. `full_reply` is `false` in this case. Treat as best-effort / possibly stale; a later closed-ledger update may full-search again.
+      Clients that ignore unknown fields are unaffected. The field is omitted when neither condition applies (or on errors).
+
 ### Additions
 
 - `account_tx`: Added an optional `delegate` request object to filter delegated transactions. The object requires `delegate_filter`, which must be either `actor` for transactions owned by the requested account but signed by another account, or `authorizer` for transactions signed by the requested account on behalf of another account. The optional `counter_party` account narrows the results to a specific signer/delegate for `actor` or a specific owner/delegator for `authorizer`. Malformed `delegate`, `delegate_filter`, and `counter_party` values return standard invalid field errors, and invalid account IDs return `actMalformed`.

cfg/xrpld-example.cfg

@@ -851,6 +851,34 @@
 #
 #   The default is: 2
 #
+# [path_find]
+#   Optional knobs for concurrent WebSocket path_find / shared AssetCache.
+#   Pathfinding remains best-effort; these only tune cost vs freshness.
+#
+#   # Ledgers a cached trust-line vector may be reused without reload.
+#   # Larger = less owner-dir thrash under load; smaller = fresher lines.
+#   # Range: 0–64. Default: 6
+#   cache_reuse_ledgers=6
+#
+#   # Trust lines loaded per account per WS load/expand step (slow fill).
+#   # One-shot ripple_path_find still loads up to max_lines_per_account.
+#   # Range: 1–1024. Default: 64
+#   line_chunk_size=64
+#
+#   # Closed-ledger interval between full Pathfinder rediscoveries (staggered
+#   # per session). Range: 1–100. Default: 3
+#   full_search_interval=3
+#
+#   # Open-ledger revalidate-only tick period while path_find sessions are live
+#   # (milliseconds). Range: 50–10000. Default: 500
+#   mid_close_ms=500
+#
+#   # Soft caps on PathFindTrustLine objects retained in the shared cache.
+#   # max_total_lines minimum 1000. Default: 1000000
+#   max_total_lines=1000000
+#   # max_lines_per_account range: 64–max_total_lines. Default: 50000
+#   max_lines_per_account=50000
+#
 #
 #
 # [fee_default]

include/xrpl/config/Constants.h

@@ -33,6 +33,7 @@ struct Sections
     static constexpr auto kNodeSeed = "node_seed";
     static constexpr auto kNodeSize = "node_size";
     static constexpr auto kOverlay = "overlay";
+    static constexpr auto kPathFind = "path_find";
     static constexpr auto kPathSearch = "path_search";
     static constexpr auto kPathSearchFast = "path_search_fast";
     static constexpr auto kPathSearchMax = "path_search_max";
@@ -96,6 +97,7 @@ struct Keys
     static constexpr auto kBlockSize = "block_size";
     static constexpr auto kCacheAge = "cache_age";
     static constexpr auto kCacheMb = "cache_mb";
+    static constexpr auto kCacheReuseLedgers = "cache_reuse_ledgers";
     static constexpr auto kCacheSize = "cache_size";
     static constexpr auto kClientMaxWindowBits = "client_max_window_bits";
     static constexpr auto kClientNoContextTakeover = "client_no_context_takeover";
@@ -108,6 +110,7 @@ struct Keys
     static constexpr auto kFileSizeMult = "file_size_mult";
     static constexpr auto kFilterBits = "filter_bits";
     static constexpr auto kFilterFull = "filter_full";
+    static constexpr auto kFullSearchInterval = "full_search_interval";
     static constexpr auto kHardSet = "hard_set";
     static constexpr auto kHighThreads = "high_threads";
     static constexpr auto kHoldTime = "hold_time";
@@ -116,15 +119,19 @@ struct Keys
     static constexpr auto kJournalSizeLimit = "journal_size_limit";
     static constexpr auto kLedgersInQueue = "ledgers_in_queue";
     static constexpr auto kLimit = "limit";
+    static constexpr auto kLineChunkSize = "line_chunk_size";
     static constexpr auto kLogInterval = "log_interval";
     static constexpr auto kMaxDivergedTime = "max_diverged_time";
     static constexpr auto kMaxLedgerCountsToStore = "max_ledger_counts_to_store";
+    static constexpr auto kMaxLinesPerAccount = "max_lines_per_account";
+    static constexpr auto kMaxTotalLines = "max_total_lines";
     static constexpr auto kMaxTrustedCount = "max_trusted_count";
     static constexpr auto kMaxUnknownTime = "max_unknown_time";
     static constexpr auto kMaxUntrustedCount = "max_untrusted_count";
     static constexpr auto kMaximumTxnInLedger = "maximum_txn_in_ledger";
     static constexpr auto kMaximumTxnPerAccount = "maximum_txn_per_account";
     static constexpr auto kMemoryLevel = "memory_level";
+    static constexpr auto kMidCloseMs = "mid_close_ms";
     static constexpr auto kMinLedgersToComputeSizeLimit = "min_ledgers_to_compute_size_limit";
     static constexpr auto kMinimumEscalationMultiplier = "minimum_escalation_multiplier";
     static constexpr auto kMinimumLastLedgerBuffer = "minimum_last_ledger_buffer";

include/xrpl/core/Job.h

@@ -39,7 +39,8 @@ enum JobType {
     JtSweep,            // Sweep for stale structures
     JtValidationUt,     // A validation from an untrusted source
     JtManifest,         // A validator's manifest
-    JtUpdatePf,         // Update pathfinding requests
+    JtUpdatePf,         // Update pathfinding requests (orchestrator; limit 1)
+    JtPathFindWork,     // Parallel path_find revalidate unit of work
     JtTransactionL,     // A local transaction
     JtReplayReq,        // Peer request a ledger delta or a skip list
     JtLedgerReq,        // Peer request ledger/txnset data
@@ -78,6 +79,12 @@ enum JobType {
     JtNsWrite,
 };
 
+/**
+ * Concurrent JtPathFindWork slots (JobTypes limit and PathRequestManager fan-out).
+ * rpc::tuning::kPathSteadyUpdateParallelism must equal this value.
+ */
+inline constexpr int kPathFindWorkLimit = 32;
+
 class Job : public CountedObject<Job>
 {
 public:

include/xrpl/core/JobTypes.h

@@ -70,6 +70,9 @@ class JobTypes
         add(JtClientWebsocket,  "clientWebsocket",      maxLimit,  2000ms,  5000ms);
         add(JtRpc,               "RPC",                  maxLimit,     0ms,     0ms);
         add(JtUpdatePf,         "updatePaths",                 1,     0ms,     0ms);
+        // Parallel path_find revalidate workers (path_find subscriptions).
+        // Limit is kPathFindWorkLimit (== kPathSteadyUpdateParallelism).
+        add(JtPathFindWork,     "pathFindWork", kPathFindWorkLimit,   0ms,     0ms);
         add(JtTransaction,       "transaction",          maxLimit,   250ms,  1000ms);
         add(JtBatch,             "batch",                maxLimit,   250ms,  1000ms);
         add(JtAdvance,           "advanceLedger",        maxLimit,     0ms,     0ms);

src/test/jtx/impl/paths.cpp

@@ -54,9 +54,8 @@ Paths::operator()(Env& env, JTx& jt) const
     if (!pf.findPaths(depth_))
         return;
 
-    STPath fp;
     pf.computePathRanks(limit_);
-    auto const found = pf.getBestPaths(limit_, fp, {}, in_.getIssuer());
+    auto const found = pf.getBestPaths(limit_, {}, in_.getIssuer());
 
     // VFALCO TODO API to allow caller to examine the STPathSet
     // VFALCO isDefault should be renamed to empty()