Deprecate Repository Stats API (#62297)

This commit deprecates the Repository Stats API added in 7.8.0 as 
an experimental API behind a feature flag. The goal is to deprecate 
this API in 7.10.0 and remove it in a follow up PR in 8.0.0.

This API is now superseded by the Repositories Metering API.

docs/reference/migration/migrate_8_0/snapshots.asciidoc

@@ -130,3 +130,16 @@ restore snapshot API now rejects requests that include a `settings` value.
 Discontinue use of the `settings` parameter in restore
 snapshot request. Requests that include these parameters will return an error.
 ====
+
+.Repository Stats API is deprecated
+[%collapsible]
+====
+*Details* +
+The Repository Stats API has been introduced in 7.8.0 as an experimental API
+and was never released. This API is superseded by the <<repositories-metering-apis,Repositories Metering APIs>>
+added in 7.10.0 which should be used instead. The Repository Stats API is
+deprecated starting 7.10.0 and will be removed in 8.0.0.
+
+*Impact* +
+Use the <<repositories-metering-apis,Repositories Metering APIs>>.
+====

x-pack/plugin/searchable-snapshots/qa/rest/src/test/resources/rest-api-spec/test/repository_stats.yml

@@ -66,8 +66,9 @@ teardown:
 ---
 "Tests repository stats":
   - skip:
-      version: " - 7.99.99"
-      reason:  searchable snapshots introduced in 7.8.0 (8.0.0 currently, but adapt after backport to 7.x)
+      version: " - 7.9.99"
+      reason:  Deprecated in 7.10.0 and removed in 8.0.0, will not issue warnings before 7.10.0
+      features: "warnings"
 
   - do:
       snapshot.restore:
@@ -76,6 +77,8 @@ teardown:
         wait_for_completion: true
 
   - do:
+      warnings:
+        - "[/_snapshot/{repository}/_stats] is deprecated, use the Repositories Metering API [/_nodes/{nodeId}/_repositories_metering] in the future."
       searchable_snapshots.repository_stats:
         repository: repository-fs
 

x-pack/plugin/searchable-snapshots/src/main/java/org/elasticsearch/xpack/searchablesnapshots/action/RepositoryStatsAction.java

@@ -8,6 +8,10 @@ package org.elasticsearch.xpack.searchablesnapshots.action;
 
 import org.elasticsearch.action.ActionType;
 
+/**
+ * @deprecated This action is superseded by the Repositories Metering action
+ */
+@Deprecated
 public class RepositoryStatsAction extends ActionType<RepositoryStatsResponse> {
 
     public static final RepositoryStatsAction INSTANCE = new RepositoryStatsAction();

x-pack/plugin/searchable-snapshots/src/main/java/org/elasticsearch/xpack/searchablesnapshots/action/RepositoryStatsNodeRequest.java

@@ -12,6 +12,7 @@ import org.elasticsearch.transport.TransportRequest;
 
 import java.io.IOException;
 
+@Deprecated
 public class RepositoryStatsNodeRequest extends TransportRequest {
 
     private final String repository;

x-pack/plugin/searchable-snapshots/src/main/java/org/elasticsearch/xpack/searchablesnapshots/action/RepositoryStatsNodeResponse.java

@@ -16,6 +16,7 @@ import org.elasticsearch.repositories.RepositoryStats;
 
 import java.io.IOException;
 
+@Deprecated
 public class RepositoryStatsNodeResponse extends BaseNodeResponse implements ToXContentObject {
 
     private final RepositoryStats repositoryStats;

x-pack/plugin/searchable-snapshots/src/main/java/org/elasticsearch/xpack/searchablesnapshots/action/RepositoryStatsRequest.java

@@ -12,6 +12,7 @@ import org.elasticsearch.common.io.stream.StreamOutput;
 
 import java.io.IOException;
 
+@Deprecated
 public class RepositoryStatsRequest extends BaseNodesRequest<RepositoryStatsRequest> {
 
     private final String repository;

x-pack/plugin/searchable-snapshots/src/main/java/org/elasticsearch/xpack/searchablesnapshots/action/RepositoryStatsResponse.java

@@ -18,6 +18,7 @@ import org.elasticsearch.repositories.RepositoryStats;
 import java.io.IOException;
 import java.util.List;
 
+@Deprecated
 public class RepositoryStatsResponse extends BaseNodesResponse<RepositoryStatsNodeResponse> implements ToXContentObject {
 
     private final RepositoryStats globalStats;

x-pack/plugin/searchable-snapshots/src/main/java/org/elasticsearch/xpack/searchablesnapshots/action/TransportRepositoryStatsAction.java

@@ -25,6 +25,10 @@ import java.io.IOException;
 import java.util.List;
 import java.util.Objects;
 
+/**
+ * @deprecated This API is superseded by the Repositories Metering API
+ */
+@Deprecated
 public class TransportRepositoryStatsAction extends TransportNodesAction<
     RepositoryStatsRequest,
     RepositoryStatsResponse,

x-pack/plugin/searchable-snapshots/src/main/java/org/elasticsearch/xpack/searchablesnapshots/rest/RestRepositoryStatsAction.java

@@ -19,8 +19,14 @@ import java.util.List;
 
 import static org.elasticsearch.rest.RestRequest.Method.GET;
 
+/**
+ * @deprecated This API is superseded by the Repositories Metering API
+ */
+@Deprecated
 public class RestRepositoryStatsAction extends BaseRestHandler {
 
+    private static final String ENDPOINT = "/_snapshot/{repository}/_stats";
+
     @Override
     public String getName() {
         return "repository_stats_action";
@@ -28,7 +34,20 @@ public class RestRepositoryStatsAction extends BaseRestHandler {
 
     @Override
     public List<RestHandler.Route> routes() {
-        return Collections.singletonList(new RestHandler.Route(GET, "/_snapshot/{repository}/_stats"));
+        return Collections.emptyList();
+    }
+
+    @Override
+    public List<DeprecatedRoute> deprecatedRoutes() {
+        return List.of(
+            new DeprecatedRoute(
+                GET,
+                ENDPOINT,
+                '['
+                    + ENDPOINT
+                    + "] is deprecated, use the Repositories Metering API [/_nodes/{nodeId}/_repositories_metering] in the future."
+            )
+        );
     }
 
     @Override

x-pack/plugin/src/test/resources/rest-api-spec/api/searchable_snapshots.repository_stats.json

@@ -2,7 +2,7 @@
   "searchable_snapshots.repository_stats": {
     "documentation": {
       "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/searchable-snapshots-apis.html",
-      "description": "Retrieve usage statistics about a snapshot repository."
+      "description": "DEPRECATED: This API is replaced by the Repositories Metering API."
     },
     "stability": "experimental",
     "url": {