getledgerentry endpoint for RPC (#4721)

# Description

This PR adds an HTTP endpoint that can query ledger state and provide an
entry's archival status. This can be used by RPC for preflighting TXs
without needing to maintain a redundant ledger state database. The
endpoint API can be found in `docs/software/commands.md`.

# Checklist
- [x] Reviewed the
[contributing](https://github.com/stellar/stellar-core/blob/master/CONTRIBUTING.md#submitting-changes)
document
- [x] Rebased on top of master (no merge commits)
- [x] Ran `clang-format` v8.0.0 (via `make format` or the Visual Studio
extension)
- [x] Compiles
- [x] Ran all tests
- [ ] If change impacts performance, include supporting evidence per the
[performance
document](https://github.com/stellar/stellar-core/blob/master/performance-eval/performance-eval.md)

Author: SirTyson

docs/software/commands.md

@@ -619,11 +619,11 @@ enabled by specifying a port via the HTTP_QUERY_PORT config setting.
 
   A JSON payload is returned as follows:
 
-  ```
+  ```js
   {
     "entries": [
-      {"le": "Base64-LedgerEntry"},
-      {"le": "Base64-LedgerEntry"},
+      {"entry": "Base64-LedgerEntry"},
+      {"entry": "Base64-LedgerEntry"},
       ...
     ],
     "ledgerSeq": ledgerSeq
@@ -638,3 +638,57 @@ enabled by specifying a port via the HTTP_QUERY_PORT config setting.
   value of the `TTL` entry to the current ledger sequence number.
 
   `ledgerSeq` gives the ledger number on which the query was performed.
+
+* **`getledgerentry`**<br>
+  A POST request with the following body:<br>
+
+  ```
+  ledgerSeq=NUM&k=Base64&k=Base64...
+  ```
+- `ledgerSeq`: An optional parameter, specifying the ledger snapshot to base the query on.
+  If the specified ledger is not available, a 404 error will be returned with "Ledger not found\n" message.
+  If this parameter is not set, the current ledger is used.
+- `key`: A series of Base64 encoded XDR strings specifying the `LedgerKey` to query. Keys must be
+  unique and must not be TTL entries, as TTL data is automatically returned when querying a Soroban key.
+
+A JSON payload is returned as follows:
+
+```js
+{
+"entries": [
+     {"entry": "Base64-LedgerEntry", "state": "live", /*optional*/ "liveUntilLedgerSeq": uint32},
+     {"state": "not-found"}, // Given key is not found
+     {"entry": "Base64-LedgerEntry", "state": "archived"}
+],
+"ledgerSeq": uint32
+}
+```
+
+- `entries`: A list of entries for each queried LedgerKey, ordered by the order of the keys in the request.
+Every key queried is guaranteed to have a corresponding `state` field while the `entry` and `ledgerSeq` fields are optional.
+- `entry`: Present only for `live` and `archived` states. Contains the `LedgerEntry` encoded as a Base64 string.
+  This field is omitted for entries with state `not-found`.
+- `state`: One of the following values:
+  - `live`: Entry is live.
+  - `not-found`: Entry does not exist. Either the entry has never existed or is an expired temp entry.
+  - `archived`: Entry is archived, counts towards disk resources.
+- `liveUntilLedgerSeq`: An optional value, only returned for live Soroban entries. Contains
+  a uint32 value for the entry's `liveUntilLedgerSeq`.
+- `ledgerSeq`: The ledger number on which the query was performed.
+
+Classic entries will always return a state of `live` or `not-found`.
+If a classic entry does not exist, it will have a state of `not-found`.
+
+Similarly, temporary Soroban entries will always return a state of `live` or
+`not-found`. If a temporary entry does not exist or has expired, it
+will have a state of `not-found`.
+
+This endpoint will always give correct information for archived entries. Even
+if an entry has been archived and evicted to the Hot Archive, this endpoint will
+still return the archived entry's full `LedgerEntry` as well as the proper state.
+
+The endpoint returns a 404 status code with the following error messages in these cases:
+- If no keys are provided: "Must specify key in POST body: key=<LedgerKey in base64 XDR format>\n"
+- If TTL keys are queried: "TTL keys are not allowed\n"
+- If duplicate keys are submitted: "Duplicate keys\n"
+- If the specified ledger is not found: "Ledger not found\n"

docs/stellar-core_example.cfg

@@ -57,7 +57,8 @@ PREFETCH_BATCH_SIZE=1000
 
 # HTTP_PORT (integer) default 11626
 # What port stellar-core listens for commands on.
-# If set to 0, disable HTTP interface entirely
+# If set to 0, disable HTTP commands interface entirely
+# (note that this does not disable HTTP query interface).
 # Must not be the same as HTTP_QUERY_PORT if not 0.
 HTTP_PORT=11626
 
@@ -80,7 +81,8 @@ COMMANDS=[
 # HTTP_QUERY_PORT (integer) default 0
 # What port stellar-core listens for query commands on,
 # such as getledgerentryraw.
-# If set to 0, disable HTTP query interface entirely.
+# If set to 0, disable HTTP query interface entirely
+# (note that this does not disable HTTP commands interface).
 # Must not be the same as HTTP_PORT if not 0.
 HTTP_QUERY_PORT=0
 

src/bucket/BucketSnapshotManager.cpp

@@ -74,6 +74,17 @@ BucketSnapshotManager::copySearchableHotArchiveBucketListSnapshot() const
             copyHistoricalSnapshots(mHotArchiveHistoricalSnapshots)));
 }
 
+namespace
+{
+template <typename T, typename U>
+bool
+needsUpdate(std::shared_ptr<T const> const& snapshot,
+            SnapshotPtrT<U> const& curr)
+{
+    return !snapshot || snapshot->getLedgerSeq() < curr->getLedgerSeq();
+}
+}
+
 void
 BucketSnapshotManager::maybeCopySearchableBucketListSnapshot(
     SearchableSnapshotConstPtr& snapshot)
@@ -82,9 +93,7 @@ BucketSnapshotManager::maybeCopySearchableBucketListSnapshot(
     // modified. Rather, a thread is checking it's copy against the canonical
     // snapshot, so use a shared lock.
     std::shared_lock<std::shared_mutex> lock(mSnapshotMutex);
-
-    if (!snapshot ||
-        snapshot->getLedgerSeq() < mCurrLiveSnapshot->getLedgerSeq())
+    if (needsUpdate(snapshot, mCurrLiveSnapshot))
     {
         snapshot = copySearchableLiveBucketListSnapshot();
     }
@@ -98,14 +107,33 @@ BucketSnapshotManager::maybeCopySearchableHotArchiveBucketListSnapshot(
     // modified. Rather, a thread is checking it's copy against the canonical
     // snapshot, so use a shared lock.
     std::shared_lock<std::shared_mutex> lock(mSnapshotMutex);
-
-    if (!snapshot ||
-        snapshot->getLedgerSeq() < mCurrHotArchiveSnapshot->getLedgerSeq())
+    if (needsUpdate(snapshot, mCurrHotArchiveSnapshot))
     {
         snapshot = copySearchableHotArchiveBucketListSnapshot();
     }
 }
 
+void
+BucketSnapshotManager::maybeCopyLiveAndHotArchiveSnapshots(
+    SearchableSnapshotConstPtr& liveSnapshot,
+    SearchableHotArchiveSnapshotConstPtr& hotArchiveSnapshot)
+{
+    // The canonical snapshot held by the BucketSnapshotManager is not being
+    // modified. Rather, a thread is checking it's copy against the canonical
+    // snapshot, so use a shared lock. For consistency we hold the lock while
+    // updating both snapshots.
+    std::shared_lock<std::shared_mutex> lock(mSnapshotMutex);
+    if (needsUpdate(liveSnapshot, mCurrLiveSnapshot))
+    {
+        liveSnapshot = copySearchableLiveBucketListSnapshot();
+    }
+
+    if (needsUpdate(hotArchiveSnapshot, mCurrHotArchiveSnapshot))
+    {
+        hotArchiveSnapshot = copySearchableHotArchiveBucketListSnapshot();
+    }
+}
+
 void
 BucketSnapshotManager::updateCurrentSnapshot(
     SnapshotPtrT<LiveBucket>&& liveSnapshot,

src/bucket/BucketSnapshotManager.h

@@ -89,5 +89,12 @@ class BucketSnapshotManager : NonMovableOrCopyable
     maybeCopySearchableBucketListSnapshot(SearchableSnapshotConstPtr& snapshot);
     void maybeCopySearchableHotArchiveBucketListSnapshot(
         SearchableHotArchiveSnapshotConstPtr& snapshot);
+
+    // This function is the same as snapshot refreshers above, but guarantees
+    // that both snapshots are consistent with the same lcl. This is required
+    // when querying both snapshot types as part of the same query.
+    void maybeCopyLiveAndHotArchiveSnapshots(
+        SearchableSnapshotConstPtr& liveSnapshot,
+        SearchableHotArchiveSnapshotConstPtr& hotArchiveSnapshot);
 };
 }

src/bucket/HotArchiveBucket.cpp

@@ -6,6 +6,8 @@
 #include "bucket/BucketInputIterator.h"
 #include "bucket/BucketOutputIterator.h"
 #include "bucket/BucketUtils.h"
+#include "ledger/LedgerTypeUtils.h"
+#include "util/GlobalChecks.h"
 
 namespace stellar
 {
@@ -51,13 +53,15 @@ HotArchiveBucket::convertToBucketEntry(
         HotArchiveBucketEntry be;
         be.type(HOT_ARCHIVE_ARCHIVED);
         be.archivedEntry() = e;
+        releaseAssertOrThrow(isPersistentEntry(e.data));
         bucket.push_back(be);
     }
     for (auto const& k : restoredEntries)
     {
         HotArchiveBucketEntry be;
         be.type(HOT_ARCHIVE_LIVE);
         be.key() = k;
+        releaseAssertOrThrow(isPersistentEntry(k));
         bucket.push_back(be);
     }
 

src/bucket/test/BucketIndexTests.cpp

@@ -1060,8 +1060,8 @@ TEST_CASE("hot archive bucket lookups", "[bucket][bucketindex][archive]")
         };
 
         auto archivedEntries =
-            LedgerTestUtils::generateValidUniqueLedgerEntriesWithTypes(
-                {CONTRACT_DATA, CONTRACT_CODE}, 10);
+            LedgerTestUtils::generateUniquePersistentLedgerEntries(
+                10, keysToSearch);
         for (auto const& e : archivedEntries)
         {
             auto k = LedgerEntryKey(e);
@@ -1071,8 +1071,8 @@ TEST_CASE("hot archive bucket lookups", "[bucket][bucketindex][archive]")
 
         // Note: keys to search automatically populated by these functions
         auto restoredEntries =
-            LedgerTestUtils::generateValidUniqueLedgerKeysWithTypes(
-                {CONTRACT_DATA, CONTRACT_CODE}, 10, keysToSearch);
+            LedgerTestUtils::generateUniquePersistentLedgerKeys(10,
+                                                                keysToSearch);
         for (auto const& k : restoredEntries)
         {
             expectedRestoredEntries.emplace(k);

src/bucket/test/BucketListTests.cpp

@@ -166,8 +166,6 @@ basicBucketListTest()
                     {
                         bl.addBatch(
                             *app, i, getAppLedgerVersion(app), {},
-                            LedgerTestUtils::generateValidUniqueLedgerEntries(
-                                8),
                             LedgerTestUtils::
                                 generateValidLedgerEntryKeysWithExclusions(
                                     {CONFIG_SETTING}, 5));
@@ -176,14 +174,11 @@ basicBucketListTest()
                     {
                         bl.addBatch(
                             *app, i, getAppLedgerVersion(app),
-                            stellar::LedgerTestUtils::
-                                generateValidUniqueLedgerEntriesWithTypes(
-                                    {CONTRACT_CODE, CONTRACT_DATA}, 8,
-                                    seenKeys),
-                            stellar::LedgerTestUtils::
-                                generateValidUniqueLedgerKeysWithTypes(
-                                    {CONTRACT_CODE, CONTRACT_DATA}, 5,
-                                    seenKeys));
+                            LedgerTestUtils::
+                                generateUniquePersistentLedgerEntries(8,
+                                                                      seenKeys),
+                            LedgerTestUtils::generateUniquePersistentLedgerKeys(
+                                5, seenKeys));
                     }
                 }
 
@@ -439,10 +434,8 @@ TEST_CASE_VERSIONS("hot archive bucket tombstones expire at bottom level",
         {
             bl.addBatch(
                 *app, ledger, getAppLedgerVersion(app),
-                LedgerTestUtils::generateValidUniqueLedgerEntriesWithTypes(
-                    {CONTRACT_DATA, CONTRACT_CODE}, 5, keys),
-                LedgerTestUtils::generateValidUniqueLedgerKeysWithTypes(
-                    {CONTRACT_CODE, CONTRACT_DATA}, 5, keys));
+                LedgerTestUtils::generateUniquePersistentLedgerEntries(5, keys),
+                LedgerTestUtils::generateUniquePersistentLedgerKeys(5, keys));
 
             // Once all entries merge to the bottom level, only deleted entries
             // should remain

src/ledger/test/LedgerTestUtils.cpp

@@ -688,6 +688,38 @@ generateUniqueValidSorobanLedgerEntryKeys(size_t n)
         n);
 }
 
+std::vector<LedgerEntry>
+generateUniquePersistentLedgerEntries(size_t n,
+                                      UnorderedSet<LedgerKey>& seenKeys)
+{
+    auto res = LedgerTestUtils::generateValidUniqueLedgerEntriesWithTypes(
+        {CONTRACT_DATA, CONTRACT_CODE}, n, seenKeys);
+    for (auto& le : res)
+    {
+        if (le.data.type() == CONTRACT_DATA)
+        {
+            seenKeys.erase(LedgerEntryKey(le));
+            le.data.contractData().durability = PERSISTENT;
+            seenKeys.insert(LedgerEntryKey(le));
+        }
+    }
+
+    return res;
+}
+
+std::vector<LedgerKey>
+generateUniquePersistentLedgerKeys(size_t n, UnorderedSet<LedgerKey>& seenKeys)
+{
+    auto entries = generateUniquePersistentLedgerEntries(n, seenKeys);
+    std::vector<LedgerKey> res;
+    for (auto const& le : entries)
+    {
+        res.push_back(LedgerEntryKey(le));
+    }
+
+    return res;
+}
+
 std::vector<LedgerKey>
 generateValidUniqueLedgerEntryKeysWithExclusions(
     std::unordered_set<LedgerEntryType> const& excludedTypes, size_t n)

src/ledger/test/LedgerTestUtils.h

@@ -51,6 +51,12 @@ std::vector<LedgerKey> generateValidUniqueLedgerKeysWithTypes(
     std::unordered_set<LedgerEntryType> const& types, size_t n,
     UnorderedSet<LedgerKey>& seenKeys);
 
+std::vector<LedgerEntry>
+generateUniquePersistentLedgerEntries(size_t n,
+                                      UnorderedSet<LedgerKey>& seenKeys);
+std::vector<LedgerKey>
+generateUniquePersistentLedgerKeys(size_t n, UnorderedSet<LedgerKey>& seenKeys);
+
 std::vector<LedgerKey> generateUniqueValidSorobanLedgerEntryKeys(size_t n);
 
 std::vector<LedgerKey> generateValidUniqueLedgerEntryKeysWithExclusions(

src/main/CommandHandler.cpp

@@ -50,7 +50,7 @@ namespace stellar
 {
 CommandHandler::CommandHandler(Application& app) : mApp(app)
 {
-    if (mApp.getConfig().HTTP_PORT)
+    if (mApp.getConfig().HTTP_PORT || mApp.getConfig().HTTP_QUERY_PORT)
     {
         std::string ipStr;
         if (mApp.getConfig().PUBLIC_HTTP_PORT)
@@ -66,9 +66,12 @@ CommandHandler::CommandHandler(Application& app) : mApp(app)
 
         int httpMaxClient = mApp.getConfig().HTTP_MAX_CLIENT;
 
-        mServer = std::make_unique<http::server::server>(
-            app.getClock().getIOContext(), ipStr, mApp.getConfig().HTTP_PORT,
-            httpMaxClient);
+        if (mApp.getConfig().HTTP_PORT)
+        {
+            mServer = std::make_unique<http::server::server>(
+                app.getClock().getIOContext(), ipStr,
+                mApp.getConfig().HTTP_PORT, httpMaxClient);
+        }
 
         if (mApp.getConfig().HTTP_QUERY_PORT)
         {
@@ -78,7 +81,8 @@ CommandHandler::CommandHandler(Application& app) : mApp(app)
                 mApp.getBucketManager().getBucketSnapshotManager());
         }
     }
-    else
+
+    if (!mApp.getConfig().HTTP_PORT)
     {
         mServer = std::make_unique<http::server::server>(
             app.getClock().getIOContext());