Pagination and Sorting for Get Snapshots API

docs/reference/snapshot-restore/apis/get-snapshot-api.asciidoc

@@ -98,6 +98,36 @@ comprising the number of shards in the index, the total size of the index in
 bytes, and the maximum number of segments per shard in the index. Defaults to
 `false`, meaning that this information is omitted.
 
+`sort`::
+(Optional, string)
+Allows setting a sort order for the result. Defaults to `start_time`, i.e. sorting by snapshot start time stamp.
++
+.Valid values for `sort`
+[%collapsible%open]
+====
+`start_time`::
+  Sort snapshots by their start time stamp and break ties by snapshot name.
+
+`duration`::
+  Sort snapshots by their duration and break ties by snapshot name.
+
+`name`::
+  Sort snapshots by their name.
+
+`indices`::
+  Sort snapshots by the number of indices they contain and break ties by snapshot name.
+====
+
+`size`::
+(Optional, integer)
+ Maximum number of snapshots to return. Defaults to `0` which means return all that match the request without limit.
+
+`after`::
+(Optional, string)
+  Offset from which to start the snapshot listing defined by sort value and snapshot name as a string of the form
+  `<sort_value>,<snapshot_name>`. Defaults to not set which means that listing will start from the first snapshot that matches the
+  request.
+
 [role="child_attributes"]
 [[get-snapshot-api-response-body]]
 ==== {api-response-body-title}

qa/smoke-test-http/src/test/java/org/elasticsearch/http/RestGetSnapshotsIT.java

@@ -0,0 +1,222 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+package org.elasticsearch.http;
+
+import org.apache.http.client.methods.HttpGet;
+import org.elasticsearch.action.ActionFuture;
+import org.elasticsearch.action.admin.cluster.snapshots.create.CreateSnapshotResponse;
+import org.elasticsearch.action.admin.cluster.snapshots.get.GetSnapshotsAction;
+import org.elasticsearch.action.admin.cluster.snapshots.get.GetSnapshotsRequest;
+import org.elasticsearch.action.admin.cluster.snapshots.get.GetSnapshotsResponse;
+import org.elasticsearch.client.Request;
+import org.elasticsearch.client.Response;
+import org.elasticsearch.common.settings.Settings;
+import org.elasticsearch.common.util.CollectionUtils;
+import org.elasticsearch.common.xcontent.DeprecationHandler;
+import org.elasticsearch.common.xcontent.NamedXContentRegistry;
+import org.elasticsearch.common.xcontent.XContentParser;
+import org.elasticsearch.common.xcontent.json.JsonXContent;
+import org.elasticsearch.plugins.Plugin;
+import org.elasticsearch.snapshots.AbstractSnapshotIntegTestCase;
+import org.elasticsearch.snapshots.SnapshotInfo;
+import org.elasticsearch.snapshots.mockstore.MockRepository;
+import org.elasticsearch.test.ESIntegTestCase;
+import org.elasticsearch.threadpool.ThreadPool;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.HashSet;
+import java.util.List;
+
+import static org.elasticsearch.snapshots.AbstractSnapshotIntegTestCase.assertSnapshotListSorted;
+import static org.hamcrest.Matchers.hasSize;
+import static org.hamcrest.Matchers.in;
+import static org.hamcrest.Matchers.is;
+
+// TODO: dry up duplication across this suite and org.elasticsearch.snapshots.GetSnapshotsIT more
+@ESIntegTestCase.ClusterScope(scope = ESIntegTestCase.Scope.TEST, numDataNodes = 0, numClientNodes = 0)
+public class RestGetSnapshotsIT extends HttpSmokeTestCase {
+
+    @Override
+    protected Collection<Class<? extends Plugin>> nodePlugins() {
+        return CollectionUtils.appendToCopy(super.nodePlugins(), MockRepository.Plugin.class);
+    }
+
+    @Override
+    protected Settings nodeSettings(int nodeOrdinal, Settings otherSettings) {
+        return Settings.builder().put(super.nodeSettings(nodeOrdinal, otherSettings))
+                .put(ThreadPool.ESTIMATED_TIME_INTERVAL_SETTING.getKey(), 0) // We have tests that check by-timestamp order
+                .build();
+    }
+
+    public void testSortOrder() throws Exception {
+        final String repoName = "test-repo";
+        AbstractSnapshotIntegTestCase.createRepository(logger, repoName, "fs");
+        final List<String> snapshotNamesWithoutIndex =
+            AbstractSnapshotIntegTestCase.createNSnapshots(logger, repoName, randomIntBetween(3, 20));
+
+        createIndexWithContent("test-index");
+
+        final List<String> snapshotNamesWithIndex =
+            AbstractSnapshotIntegTestCase.createNSnapshots(logger, repoName, randomIntBetween(3, 20));
+
+        final Collection<String> allSnapshotNames = new HashSet<>(snapshotNamesWithIndex);
+        allSnapshotNames.addAll(snapshotNamesWithoutIndex);
+
+        final List<SnapshotInfo> defaultSorting = clusterAdmin().prepareGetSnapshots(repoName).get().getSnapshots(repoName);
+        assertSnapshotListSorted(defaultSorting, null);
+        assertSnapshotListSorted(
+                allSnapshotsSorted(allSnapshotNames, repoName, GetSnapshotsAction.SortBy.NAME), GetSnapshotsAction.SortBy.NAME);
+        assertSnapshotListSorted(
+            allSnapshotsSorted(allSnapshotNames, repoName, GetSnapshotsAction.SortBy.DURATION), GetSnapshotsAction.SortBy.DURATION
+        );
+        assertSnapshotListSorted(
+                allSnapshotsSorted(allSnapshotNames, repoName, GetSnapshotsAction.SortBy.INDICES), GetSnapshotsAction.SortBy.INDICES);
+        assertSnapshotListSorted(
+            allSnapshotsSorted(allSnapshotNames, repoName, GetSnapshotsAction.SortBy.START_TIME), GetSnapshotsAction.SortBy.START_TIME
+        );
+    }
+
+    public void testResponseSizeLimit() throws Exception {
+        final String repoName = "test-repo";
+        AbstractSnapshotIntegTestCase.createRepository(logger, repoName, "fs");
+        final List<String> names = AbstractSnapshotIntegTestCase.createNSnapshots(logger, repoName, randomIntBetween(6, 20));
+        for (GetSnapshotsAction.SortBy sort : GetSnapshotsAction.SortBy.values()) {
+            logger.info("--> testing pagination for [{}]", sort);
+            final List<SnapshotInfo> allSnapshotsSorted = allSnapshotsSorted(names, repoName, sort);
+            final List<SnapshotInfo> batch1 = sortedWithLimit(repoName, sort, null, 2);
+            assertEquals(batch1, allSnapshotsSorted.subList(0, 2));
+            final List<SnapshotInfo> batch2 = sortedWithLimit(repoName, sort, batch1.get(1), 2);
+            assertEquals(batch2, allSnapshotsSorted.subList(2, 4));
+            final int lastBatch = names.size() - batch1.size() - batch2.size();
+            final List<SnapshotInfo> batch3 = sortedWithLimit(repoName, sort, batch2.get(1), lastBatch);
+            assertEquals(batch3, allSnapshotsSorted.subList(batch1.size() + batch2.size(), names.size()));
+            final List<SnapshotInfo> batch3NoLimit = sortedWithLimit(repoName, sort, batch2.get(1), 0);
+            assertEquals(batch3, batch3NoLimit);
+            final List<SnapshotInfo> batch3LargeLimit =
+                    sortedWithLimit(repoName, sort, batch2.get(1), lastBatch + randomIntBetween(1, 100));
+            assertEquals(batch3, batch3LargeLimit);
+        }
+    }
+
+    public void testSortAndPaginateWithInProgress() throws Exception {
+        final String repoName = "test-repo";
+        AbstractSnapshotIntegTestCase.createRepository(logger, repoName, "mock");
+        final Collection<String> allSnapshotNames =
+                new HashSet<>(AbstractSnapshotIntegTestCase.createNSnapshots(logger, repoName, randomIntBetween(3, 20)));
+        createIndexWithContent("test-index-1");
+        allSnapshotNames.addAll(AbstractSnapshotIntegTestCase.createNSnapshots(logger, repoName, randomIntBetween(3, 20)));
+        createIndexWithContent("test-index-2");
+
+        final int inProgressCount = randomIntBetween(6, 20);
+        final List<ActionFuture<CreateSnapshotResponse>> inProgressSnapshots = new ArrayList<>(inProgressCount);
+        AbstractSnapshotIntegTestCase.blockAllDataNodes(repoName);
+        for (int i = 0; i < inProgressCount; i++) {
+            final String snapshotName = "snap-" + i;
+            allSnapshotNames.add(snapshotName);
+            inProgressSnapshots.add(AbstractSnapshotIntegTestCase.startFullSnapshot(logger, repoName, snapshotName, false));
+        }
+        AbstractSnapshotIntegTestCase.awaitNumberOfSnapshotsInProgress(logger, inProgressCount);
+
+        assertStablePagination(repoName, allSnapshotNames, GetSnapshotsAction.SortBy.START_TIME);
+        assertStablePagination(repoName, allSnapshotNames, GetSnapshotsAction.SortBy.NAME);
+        assertStablePagination(repoName, allSnapshotNames, GetSnapshotsAction.SortBy.INDICES);
+
+        AbstractSnapshotIntegTestCase.unblockAllDataNodes(repoName);
+        for (ActionFuture<CreateSnapshotResponse> inProgressSnapshot : inProgressSnapshots) {
+            AbstractSnapshotIntegTestCase.assertSuccessful(logger, inProgressSnapshot);
+        }
+
+        assertStablePagination(repoName, allSnapshotNames, GetSnapshotsAction.SortBy.START_TIME);
+        assertStablePagination(repoName, allSnapshotNames, GetSnapshotsAction.SortBy.NAME);
+        assertStablePagination(repoName, allSnapshotNames, GetSnapshotsAction.SortBy.INDICES);
+    }
+
+    private void createIndexWithContent(String indexName) {
+        logger.info("--> creating index [{}]", indexName);
+        createIndex(indexName, AbstractSnapshotIntegTestCase.SINGLE_SHARD_NO_REPLICA);
+        ensureGreen(indexName);
+        indexDoc(indexName, "some_id", "foo", "bar");
+    }
+
+    private static void assertStablePagination(String repoName,
+                                               Collection<String> allSnapshotNames,
+                                               GetSnapshotsAction.SortBy sort) throws IOException {
+        final List<SnapshotInfo> allSorted = allSnapshotsSorted(allSnapshotNames, repoName, sort);
+
+        for (int i = 1; i <= allSnapshotNames.size(); i++) {
+            final List<SnapshotInfo> subsetSorted = sortedWithLimit(repoName, sort, i);
+            assertEquals(subsetSorted, allSorted.subList(0, i));
+        }
+
+        for (int j = 0; j < allSnapshotNames.size(); j++) {
+            final SnapshotInfo after = allSorted.get(j);
+            for (int i = 1; i < allSnapshotNames.size() - j; i++) {
+                final List<SnapshotInfo> subsetSorted = sortedWithLimit(repoName, sort, after, i);
+                assertEquals(subsetSorted, allSorted.subList(j + 1, j + i + 1));
+            }
+        }
+    }
+
+    private static List<SnapshotInfo> allSnapshotsSorted(Collection<String> allSnapshotNames,
+                                                  String repoName,
+                                                  GetSnapshotsAction.SortBy sortBy) throws IOException {
+        final Request request = baseGetSnapshotsRequest(repoName);
+        request.addParameter("sort", sortBy.toString());
+        final Response response = getRestClient().performRequest(request);
+        final List<SnapshotInfo> snapshotInfos = readSnapshotInfos(repoName, response);
+        assertEquals(snapshotInfos.size(), allSnapshotNames.size());
+        for (SnapshotInfo snapshotInfo : snapshotInfos) {
+            assertThat(snapshotInfo.snapshotId().getName(), is(in(allSnapshotNames)));
+        }
+        return snapshotInfos;
+    }
+
+    private static Request baseGetSnapshotsRequest(String repoName) {
+        return new Request(HttpGet.METHOD_NAME, "/_snapshot/" + repoName + "/*");
+    }
+
+    private static List<SnapshotInfo> sortedWithLimit(String repoName, GetSnapshotsAction.SortBy sortBy, int size) throws IOException {
+        final Request request = baseGetSnapshotsRequest(repoName);
+        request.addParameter("sort", sortBy.toString());
+        request.addParameter("size", String.valueOf(size));
+        final Response response = getRestClient().performRequest(request);
+        final List<SnapshotInfo> snapshotInfos = readSnapshotInfos(repoName, response);
+        assertThat(snapshotInfos, hasSize(size));
+        return snapshotInfos;
+    }
+
+    private static List<SnapshotInfo> readSnapshotInfos(String repoName, Response response) throws IOException {
+        final List<SnapshotInfo> snapshotInfos;
+        try (InputStream input = response.getEntity().getContent();
+             XContentParser parser = JsonXContent.jsonXContent.createParser(
+                     NamedXContentRegistry.EMPTY, DeprecationHandler.THROW_UNSUPPORTED_OPERATION, input)) {
+            snapshotInfos = GetSnapshotsResponse.fromXContent(parser).getSnapshots(repoName);
+        }
+        return snapshotInfos;
+    }
+
+    private static List<SnapshotInfo> sortedWithLimit(String repoName,
+                                                      GetSnapshotsAction.SortBy sortBy,
+                                                      SnapshotInfo after,
+                                                      int size) throws IOException {
+        final Request request = baseGetSnapshotsRequest(repoName);
+        request.addParameter("sort", sortBy.toString());
+        if (size != 0 || randomBoolean()) {
+            request.addParameter("size", String.valueOf(size));
+        }
+        if (after != null) {
+            request.addParameter("after", GetSnapshotsRequest.After.from(after, sortBy).value() + "," + after.snapshotId().getName());
+        }
+        final Response response = getRestClient().performRequest(request);
+        return readSnapshotInfos(repoName, response);
+    }
+}

server/src/internalClusterTest/java/org/elasticsearch/snapshots/DedicatedClusterSnapshotRestoreIT.java

@@ -923,7 +923,7 @@ public void onRequestSent(DiscoveryNode node, long requestId, String action, Tra
         logger.info("--> abort snapshot");
         final ActionFuture<AcknowledgedResponse> deleteResponse = startDeleteSnapshot(repoName, snapshotName);
 
-        awaitClusterState(otherDataNode, state -> state.custom(SnapshotsInProgress.TYPE, SnapshotsInProgress.EMPTY)
+        awaitClusterState(logger, otherDataNode, state -> state.custom(SnapshotsInProgress.TYPE, SnapshotsInProgress.EMPTY)
                 .entries().stream().anyMatch(entry -> entry.state() == SnapshotsInProgress.State.ABORTED));
 
         assertFalse("delete should not be able to finish until data node is unblocked", deleteResponse.isDone());