SOLR-16398: Add V2 JAX-RS APIs for GET replication restore status and commits.

changelog/unreleased/SOLR-16398-replication-restore-status-commits.yml

@@ -0,0 +1,8 @@
+title: Add V2 JAX-RS APIs for GET replication restore status and commits.
+type: added
+authors:
+  - name: Jalaz Kumar
+    nick: jaykay12
+links:
+  - name: SOLR-16398
+    url: https://issues.apache.org/jira/browse/SOLR-16398

solr/api/src/java/org/apache/solr/client/api/endpoint/ReplicationApis.java

@@ -29,9 +29,11 @@
 import jakarta.ws.rs.QueryParam;
 import jakarta.ws.rs.core.StreamingOutput;
 import java.io.IOException;
+import org.apache.solr.client.api.model.CommitsResponse;
 import org.apache.solr.client.api.model.FileListResponse;
 import org.apache.solr.client.api.model.IndexVersionResponse;
 import org.apache.solr.client.api.model.ReplicationDetailsResponse;
+import org.apache.solr.client.api.model.RestoreStatusResponse;
 import org.apache.solr.client.api.util.CoreApiParameters;
 
 @Path("/cores/{coreName}/replication")
@@ -50,6 +52,22 @@ ReplicationDetailsResponse fetchReplicationDetails(
           @DefaultValue("true")
           Boolean follower);
 
+  @GET
+  @CoreApiParameters
+  @Path("/restore/status")
+  @Operation(
+      summary = "Return the status of the most recent restore operation.",
+      tags = {"replication"})
+  RestoreStatusResponse fetchRestoreStatus();
+
+  @GET
+  @CoreApiParameters
+  @Path("/commits")
+  @Operation(
+      summary = "Return the index commit points retained by the specified core.",
+      tags = {"replication"})
+  CommitsResponse fetchCommits();
+
   @GET
   @CoreApiParameters
   @Path("/indexversion")

solr/api/src/java/org/apache/solr/client/api/model/CommitsResponse.java

@@ -0,0 +1,54 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.client.api.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
+import java.util.List;
+import org.apache.solr.client.api.util.ReflectWritable;
+
+/** Response body for the `GET /api/cores/coreName/replication/commits` API */
+public class CommitsResponse extends SolrJerseyResponse {
+
+  @JsonProperty("commits")
+  @Schema(description = "Index commit points currently retained by the deletion policy")
+  public List<CommitDetails> commits;
+
+  @JsonProperty("status")
+  @Schema(description = "Request status, typically OK")
+  public String status;
+
+  /** Details of a single index commit point. */
+  public static class CommitDetails implements ReflectWritable {
+    @JsonProperty("indexVersion")
+    public Long indexVersion;
+
+    @JsonProperty("generation")
+    public Long generation;
+
+    @JsonProperty("filelist")
+    public List<String> filelist;
+
+    public CommitDetails() {}
+
+    public CommitDetails(long indexVersion, long generation, List<String> filelist) {
+      this.indexVersion = indexVersion;
+      this.generation = generation;
+      this.filelist = filelist;
+    }
+  }
+}

solr/api/src/java/org/apache/solr/client/api/model/ReplicationDetailsResponse.java

@@ -19,6 +19,7 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 import io.swagger.v3.oas.annotations.media.Schema;
 import java.util.List;
+import org.apache.solr.client.api.model.CommitsResponse.CommitDetails;
 import org.apache.solr.client.api.util.ReflectWritable;
 
 public class ReplicationDetailsResponse extends SolrJerseyResponse {
@@ -72,17 +73,6 @@ public static class ReplicationDetails implements ReflectWritable {
     public Object backup;
   }
 
-  public static class CommitDetails implements ReflectWritable {
-    @JsonProperty("indexVersion")
-    public Long indexVersion;
-
-    @JsonProperty("generation")
-    public Long generation;
-
-    @JsonProperty("filelist")
-    public List<String> filelist;
-  }
-
   public static class LeaderDetails implements ReflectWritable {
     @JsonProperty("confFiles")
     public String confFiles;

solr/api/src/java/org/apache/solr/client/api/model/RestoreStatusResponse.java

@@ -0,0 +1,67 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.client.api.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonValue;
+import io.swagger.v3.oas.annotations.media.Schema;
+import org.apache.solr.client.api.util.ReflectWritable;
+
+/** Response body for the `GET /api/cores/coreName/replication/restore` API */
+public class RestoreStatusResponse extends SolrJerseyResponse {
+
+  @JsonProperty("restorestatus")
+  @Schema(description = "State of the most recent restore operation")
+  public RestoreStatus restoreStatus;
+
+  @JsonProperty("status")
+  @Schema(description = "Request status, typically OK")
+  public String status;
+
+  /** State of a restore operation. */
+  public static class RestoreStatus implements ReflectWritable {
+    @JsonProperty("snapshotName")
+    public String snapshotName;
+
+    @JsonProperty("status")
+    @Schema(description = "State of the restore operation")
+    public RestoreState status;
+
+    @JsonProperty("exception")
+    @Schema(description = "Failure message, present only when the restore failed with an exception")
+    public String exception;
+  }
+
+  /** State of a restore operation. */
+  public enum RestoreState {
+    NOT_STARTED("No restore actions in progress"),
+    IN_PROGRESS("In Progress"),
+    SUCCESS("success"),
+    FAILED("failed");
+
+    private final String key;
+
+    RestoreState(String key) {
+      this.key = key;
+    }
+
+    @JsonValue
+    public String getKey() {
+      return key;
+    }
+  }
+}

solr/core/src/java/org/apache/solr/handler/ReplicationHandler.java

@@ -75,13 +75,17 @@
 import org.apache.lucene.store.IndexInput;
 import org.apache.solr.api.Api;
 import org.apache.solr.api.JerseyResource;
+import org.apache.solr.client.api.model.CommitsResponse;
+import org.apache.solr.client.api.model.CommitsResponse.CommitDetails;
 import org.apache.solr.client.api.model.FileMetaData;
 import org.apache.solr.client.api.model.IndexVersionResponse;
 import org.apache.solr.client.api.model.ReplicationDetailsResponse;
-import org.apache.solr.client.api.model.ReplicationDetailsResponse.CommitDetails;
 import org.apache.solr.client.api.model.ReplicationDetailsResponse.FollowerDetails;
 import org.apache.solr.client.api.model.ReplicationDetailsResponse.LeaderDetails;
 import org.apache.solr.client.api.model.ReplicationDetailsResponse.ReplicationDetails;
+import org.apache.solr.client.api.model.RestoreStatusResponse;
+import org.apache.solr.client.api.model.RestoreStatusResponse.RestoreState;
+import org.apache.solr.client.api.model.RestoreStatusResponse.RestoreStatus;
 import org.apache.solr.client.api.model.SolrJerseyResponse;
 import org.apache.solr.common.SolrException;
 import org.apache.solr.common.SolrException.ErrorCode;
@@ -311,7 +315,17 @@ public void handleRequestBody(SolrQueryRequest req, SolrQueryResponse rsp) throw
     } else if (command.equalsIgnoreCase(CMD_RESTORE)) {
       restore(new ModifiableSolrParams(solrParams), rsp, req);
     } else if (command.equalsIgnoreCase(CMD_RESTORE_STATUS)) {
-      populateRestoreStatus(rsp);
+      final CoreReplication coreReplicationAPI = new CoreReplication(core, req, rsp);
+      final RestoreStatusResponse restoreStatus = coreReplicationAPI.fetchRestoreStatus();
+      V2ApiUtils.squashIntoSolrResponseWithoutHeader(rsp, restoreStatus);
+      if (restoreStatus.restoreStatus.exception != null) {
+        // V1 reports a failed restore as an error response
+        rsp.getValues().remove(STATUS);
+        reportErrorOnResponse(
+            rsp,
+            "Unable to read restorestatus",
+            new Exception(restoreStatus.restoreStatus.exception));
+      }
     } else if (command.equalsIgnoreCase(CMD_DELETE_BACKUP)) {
       deleteSnapshot(new ModifiableSolrParams(solrParams), rsp);
     } else if (command.equalsIgnoreCase(CMD_FETCH_INDEX)) {
@@ -327,7 +341,8 @@ public void handleRequestBody(SolrQueryRequest req, SolrQueryResponse rsp) throw
         reportErrorOnResponse(rsp, "No follower configured", null);
       }
     } else if (command.equals(CMD_SHOW_COMMITS)) {
-      populateCommitInfo(rsp);
+      final CoreReplication coreReplicationAPI = new CoreReplication(core, req, rsp);
+      V2ApiUtils.squashIntoSolrResponseWithoutHeader(rsp, coreReplicationAPI.fetchCommits());
     } else if (command.equals(CMD_DETAILS)) {
       final CoreReplication coreReplicationAPI = new CoreReplication(core, req, rsp);
       // stringifyBooleans=true: V1's command=details has always rendered isLeader/isFollower/etc.
@@ -642,42 +657,35 @@ private void restore(SolrParams params, SolrQueryResponse rsp, SolrQueryRequest
     }
   }
 
-  private void populateRestoreStatus(SolrQueryResponse rsp) {
-    NamedList<Object> restoreStatus = new SimpleOrderedMap<>();
-    if (restoreFuture == null) {
-      restoreStatus.add(STATUS, "No restore actions in progress");
-      rsp.add(CMD_RESTORE_STATUS, restoreStatus);
-      rsp.add(STATUS, OK_STATUS);
-      return;
+  public RestoreStatusResponse getRestoreStatusResponse() {
+    RestoreStatusResponse response = new RestoreStatusResponse();
+    response.restoreStatus = new RestoreStatus();
+    response.status = OK_STATUS;
+    Future<Boolean> future = restoreFuture;
+    if (future == null) {
+      response.restoreStatus.status = RestoreState.NOT_STARTED;
+      return response;
     }
 
-    restoreStatus.add("snapshotName", currentRestoreName);
-    if (restoreFuture.isDone()) {
+    response.restoreStatus.snapshotName = currentRestoreName;
+    if (future.isDone()) {
       try {
-        boolean success = restoreFuture.get();
-        if (success) {
-          restoreStatus.add(STATUS, SUCCESS);
-        } else {
-          restoreStatus.add(STATUS, FAILED);
-        }
+        response.restoreStatus.status = future.get() ? RestoreState.SUCCESS : RestoreState.FAILED;
       } catch (Exception e) {
-        restoreStatus.add(STATUS, FAILED);
-        restoreStatus.add(EXCEPTION, e.getMessage());
-        rsp.add(CMD_RESTORE_STATUS, restoreStatus);
-        reportErrorOnResponse(rsp, "Unable to read restorestatus", e);
-        return;
+        response.restoreStatus.status = RestoreState.FAILED;
+        response.restoreStatus.exception = e.getMessage() != null ? e.getMessage() : e.toString();
       }
     } else {
-      restoreStatus.add(STATUS, "In Progress");
+      response.restoreStatus.status = RestoreState.IN_PROGRESS;
     }
-
-    rsp.add(CMD_RESTORE_STATUS, restoreStatus);
-    rsp.add(STATUS, OK_STATUS);
+    return response;
   }
 
-  private void populateCommitInfo(SolrQueryResponse rsp) {
-    rsp.add(CMD_SHOW_COMMITS, getCommits());
-    rsp.add(STATUS, OK_STATUS);
+  public CommitsResponse getCommitsResponse() {
+    CommitsResponse response = new CommitsResponse();
+    response.commits = getCommitDetails();
+    response.status = OK_STATUS;
+    return response;
   }
 
   private void doSnapShoot(SolrParams params, SolrQueryResponse rsp, SolrQueryRequest req) {
@@ -1685,10 +1693,6 @@ public static Long readIntervalNs(String interval) {
     }
   }
 
-  private static final String SUCCESS = "success";
-
-  private static final String FAILED = "failed";
-
   public static final String EXCEPTION = "exception";
 
   public static final String LEADER_URL = "leaderUrl";

solr/core/src/java/org/apache/solr/handler/admin/api/CoreReplication.java

@@ -22,9 +22,11 @@
 import jakarta.ws.rs.core.StreamingOutput;
 import java.io.IOException;
 import org.apache.solr.client.api.endpoint.ReplicationApis;
+import org.apache.solr.client.api.model.CommitsResponse;
 import org.apache.solr.client.api.model.FileListResponse;
 import org.apache.solr.client.api.model.IndexVersionResponse;
 import org.apache.solr.client.api.model.ReplicationDetailsResponse;
+import org.apache.solr.client.api.model.RestoreStatusResponse;
 import org.apache.solr.common.SolrException;
 import org.apache.solr.core.SolrCore;
 import org.apache.solr.jersey.PermissionName;
@@ -51,6 +53,18 @@ public ReplicationDetailsResponse fetchReplicationDetails(Boolean follower) {
     return doFetchReplicationDetails(follower == null || follower);
   }
 
+  @Override
+  @PermissionName(CORE_READ_PERM)
+  public RestoreStatusResponse fetchRestoreStatus() {
+    return doFetchRestoreStatus();
+  }
+
+  @Override
+  @PermissionName(CORE_READ_PERM)
+  public CommitsResponse fetchCommits() {
+    return doFetchCommits();
+  }
+
   @Override
   @PermissionName(CORE_READ_PERM)
   public IndexVersionResponse fetchIndexVersion() throws IOException {

solr/core/src/java/org/apache/solr/handler/admin/api/ReplicationAPIBase.java

@@ -45,10 +45,12 @@
 import org.apache.lucene.store.IndexInput;
 import org.apache.lucene.store.RateLimiter;
 import org.apache.solr.api.JerseyResource;
+import org.apache.solr.client.api.model.CommitsResponse;
 import org.apache.solr.client.api.model.FileListResponse;
 import org.apache.solr.client.api.model.FileMetaData;
 import org.apache.solr.client.api.model.IndexVersionResponse;
 import org.apache.solr.client.api.model.ReplicationDetailsResponse;
+import org.apache.solr.client.api.model.RestoreStatusResponse;
 import org.apache.solr.common.SolrException;
 import org.apache.solr.common.util.FastOutputStream;
 import org.apache.solr.common.util.IOUtils;
@@ -100,6 +102,18 @@ protected ReplicationDetailsResponse doFetchReplicationDetails(boolean showFollo
     return replicationHandler.getReplicationDetails(showFollowerDetails);
   }
 
+  protected RestoreStatusResponse doFetchRestoreStatus() {
+    ReplicationHandler replicationHandler =
+        (ReplicationHandler) solrCore.getRequestHandler(ReplicationHandler.PATH);
+    return replicationHandler.getRestoreStatusResponse();
+  }
+
+  protected CommitsResponse doFetchCommits() {
+    ReplicationHandler replicationHandler =
+        (ReplicationHandler) solrCore.getRequestHandler(ReplicationHandler.PATH);
+    return replicationHandler.getCommitsResponse();
+  }
+
   protected IndexVersionResponse doFetchIndexVersion() throws IOException {
     ReplicationHandler replicationHandler =
         (ReplicationHandler) solrCore.getRequestHandler(ReplicationHandler.PATH);

solr/core/src/java/org/apache/solr/handler/api/V2ApiUtils.java

@@ -34,6 +34,7 @@
 import org.apache.solr.common.util.SimpleOrderedMap;
 import org.apache.solr.common.util.StrUtils;
 import org.apache.solr.common.util.Utils;
+import org.apache.solr.jersey.SolrJacksonMapper;
 import org.apache.solr.response.PrometheusResponseWriter;
 import org.apache.solr.response.RawResponseWriter;
 import org.apache.solr.response.SolrQueryResponse;
@@ -157,6 +158,9 @@ private static Object convertReflectWriteableValue(Object value, boolean stringi
     if (stringifyBooleans && value instanceof Boolean bool) {
       return bool.toString();
     }
+    if (value instanceof Enum<?> e) {
+      return SolrJacksonMapper.getObjectMapper().convertValue(e, Object.class);
+    }
     if (value instanceof ReflectWritable) {
       NamedList<Object> result = new SimpleOrderedMap<>();
       squashObjectIntoNamedList(result, value, true, stringifyBooleans);