SOLR-15751: Modify v2 GET /collections/collName to support full ColStatus response

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

@@ -0,0 +1,75 @@
+/*
+ * 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.endpoint;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.PathParam;
+import jakarta.ws.rs.QueryParam;
+import org.apache.solr.client.api.model.CollectionStatusResponse;
+
+/**
+ * V2 API definition for fetching collection metadata
+ *
+ * <p>This API (GET /v2/collections/collectionName) is analogous to the v1
+ * /admin/collections?action=COLSTATUS command.
+ */
+@Path("/collections/{collectionName}")
+public interface CollectionStatusApi {
+
+  // TODO Query parameters currently match those offered by the v1
+  // /admin/collections?action=COLSTATUS.  Should param names be updated/clarified?
+  @GET
+  @Operation(
+      summary = "Fetches metadata about the specified collection",
+      tags = {"collections"})
+  CollectionStatusResponse getCollectionStatus(
+      @Parameter(description = "The name of the collection return metadata for", required = true)
+          @PathParam("collectionName")
+          String collectionName,
+      @Parameter(description = SegmentsApi.CORE_INFO_PARAM_DESC) @QueryParam("coreInfo")
+          Boolean coreInfo,
+      @Parameter(
+              description =
+                  "Boolean flag to include metadata and statistics about the segments used by each shard leader.  Implicitly set to true by 'fieldInfo' and 'sizeInfo'")
+          @QueryParam("segments")
+          Boolean segments,
+      @Parameter(
+              description =
+                  SegmentsApi.FIELD_INFO_PARAM_DESC
+                      + " Implicitly sets the 'segments' flag to 'true'")
+          @QueryParam("fieldInfo")
+          Boolean fieldInfo,
+      @Parameter(description = SegmentsApi.RAW_SIZE_PARAM_DESC) @QueryParam("rawSize")
+          Boolean rawSize,
+      @Parameter(description = SegmentsApi.RAW_SIZE_SUMMARY_DESC) @QueryParam("rawSizeSummary")
+          Boolean rawSizeSummary,
+      @Parameter(description = SegmentsApi.RAW_SIZE_DETAILS_DESC) @QueryParam("rawSizeDetails")
+          Boolean rawSizeDetails,
+      @Parameter(description = SegmentsApi.RAW_SIZE_SAMPLING_PERCENT_DESC)
+          @QueryParam("rawSizeSamplingPercent")
+          Float rawSizeSamplingPercent,
+      @Parameter(
+              description =
+                  SegmentsApi.SIZE_INFO_PARAM_DESC
+                      + ". Implicitly sets the 'segment' flag to 'true'")
+          @QueryParam("sizeInfo")
+          Boolean sizeInfo)
+      throws Exception;
+}

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

@@ -0,0 +1,68 @@
+/*
+ * 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.endpoint;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.QueryParam;
+import org.apache.solr.client.api.model.GetSegmentDataResponse;
+import org.apache.solr.client.api.util.CoreApiParameters;
+
+/**
+ * V2 API definition for fetching metadata about a core's segments
+ *
+ * <p>This API (GET /v2/cores/coreName/segments) is analogous to the v1
+ * /solr/coreName/admin/segments API
+ */
+@Path("/cores/{coreName}/segments")
+public interface SegmentsApi {
+
+  String CORE_INFO_PARAM_DESC =
+      "Boolean flag to include metadata (e.g. index an data directories, IndexWriter configuration, etc.) about each shard leader's core";
+  String FIELD_INFO_PARAM_DESC =
+      "Boolean flag to include statistics about the indexed fields present on each shard leader.";
+  String RAW_SIZE_PARAM_DESC =
+      "Boolean flag to include simple estimates of the disk size taken up by each field (e.g. \"id\", \"_version_\") and by each index data structure (e.g. 'storedFields', 'docValues_numeric').";
+  String RAW_SIZE_SUMMARY_DESC =
+      "Boolean flag to include more involved estimates of the disk size taken up by index data structures, on a per-field basis (e.g. how much data does the \"id\" field contribute to 'storedField' index files).  More detail than 'rawSize', less detail than 'rawSizeDetails'.";
+  String RAW_SIZE_DETAILS_DESC =
+      "Boolean flag to include detailed statistics about the disk size taken up by various fields and data structures.  More detail than 'rawSize' and 'rawSizeSummary'.";
+  String RAW_SIZE_SAMPLING_PERCENT_DESC =
+      "Percentage (between 0 and 100) of data to read when estimating index size and statistics.  Defaults to 5.0 (i.e. 5%).";
+  String SIZE_INFO_PARAM_DESC =
+      "Boolean flag to include information about the largest index files for each Lucene segment.";
+
+  @GET
+  @CoreApiParameters
+  @Operation(
+      summary = "Fetches metadata about the segments in use by the specified core",
+      tags = {"segments"})
+  GetSegmentDataResponse getSegmentData(
+      @Parameter(description = CORE_INFO_PARAM_DESC) @QueryParam("coreInfo") Boolean coreInfo,
+      @Parameter(description = FIELD_INFO_PARAM_DESC) @QueryParam("fieldInfo") Boolean fieldInfo,
+      @Parameter(description = RAW_SIZE_PARAM_DESC) @QueryParam("rawSize") Boolean rawSize,
+      @Parameter(description = RAW_SIZE_SUMMARY_DESC) @QueryParam("rawSizeSummary")
+          Boolean rawSizeSummary,
+      @Parameter(description = RAW_SIZE_DETAILS_DESC) @QueryParam("rawSizeDetails")
+          Boolean rawSizeDetails,
+      @Parameter(description = RAW_SIZE_SAMPLING_PERCENT_DESC) @QueryParam("rawSizeSamplingPercent")
+          Float rawSizeSamplingPercent,
+      @Parameter(description = SIZE_INFO_PARAM_DESC) @QueryParam("sizeInfo") Boolean sizeInfo)
+      throws Exception;
+}

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

@@ -0,0 +1,141 @@
+/*
+ * 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.JsonAnyGetter;
+import com.fasterxml.jackson.annotation.JsonAnySetter;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Response of the CollectionStatusApi.getCollectionStatus() API
+ *
+ * <p>Note that the corresponding v1 API has a slightly different response format. Users should not
+ * attempt to convert a v1 response into this type.
+ */
+public class CollectionStatusResponse extends SolrJerseyResponse {
+
+  @JsonProperty public String name;
+  @JsonProperty public Integer znodeVersion;
+  // TODO - consider 'Instant' once SOLR-17608 is finished
+  @JsonProperty public Long creationTimeMillis;
+  @JsonProperty public CollectionMetadata properties;
+  @JsonProperty public Integer activeShards;
+  @JsonProperty public Integer inactiveShards;
+  @JsonProperty public List<String> schemaNonCompliant;
+
+  @JsonProperty public Map<String, ShardMetadata> shards;
+
+  // Always present in response
+  public static class CollectionMetadata {
+    @JsonProperty public String configName;
+    @JsonProperty public Integer nrtReplicas;
+    @JsonProperty public Integer pullReplicas;
+    @JsonProperty public Integer tlogReplicas;
+    @JsonProperty public Map<String, String> router;
+    @JsonProperty public Integer replicationFactor;
+
+    private Map<String, Object> unknownFields = new HashMap<>();
+
+    @JsonAnyGetter
+    public Map<String, Object> unknownProperties() {
+      return unknownFields;
+    }
+
+    @JsonAnySetter
+    public void setUnknownProperty(String field, Object value) {
+      unknownFields.put(field, value);
+    }
+  }
+
+  // Always present in response
+  public static class ShardMetadata {
+    @JsonProperty public String state; // TODO Make this an enum?
+    @JsonProperty public String range;
+    @JsonProperty public ReplicaSummary replicas;
+    @JsonProperty public LeaderSummary leader;
+  }
+
+  // Always present in response
+  public static class ReplicaSummary {
+    @JsonProperty public Integer total;
+    @JsonProperty public Integer active;
+    @JsonProperty public Integer down;
+    @JsonProperty public Integer recovering;
+
+    @JsonProperty("recovery_failed")
+    public Integer recoveryFailed;
+  }
+
+  // Always present in response unless otherwise specified
+  public static class LeaderSummary {
+    @JsonProperty public String coreNode;
+    @JsonProperty public String core;
+    @JsonProperty public Boolean leader;
+
+    @JsonProperty("node_name")
+    public String nodeName;
+
+    @JsonProperty("base_url")
+    public String baseUrl;
+
+    @JsonProperty public String state; // TODO Make this an enum?
+    @JsonProperty public String type; // TODO Make this an enum?
+
+    @JsonProperty("force_set_state")
+    public Boolean forceSetState;
+
+    // Present with coreInfo=true || sizeInfo=true unless otherwise specified
+    @JsonProperty public SegmentInfo segInfos;
+
+    private Map<String, Object> unknownFields = new HashMap<>();
+
+    @JsonAnyGetter
+    public Map<String, Object> unknownProperties() {
+      return unknownFields;
+    }
+
+    @JsonAnySetter
+    public void setUnknownProperty(String field, Object value) {
+      unknownFields.put(field, value);
+    }
+  }
+
+  // Present with segments=true || coreInfo=true || sizeInfo=true || fieldInfo=true unless otherwise
+  // specified
+
+  /**
+   * Same properties as {@link GetSegmentDataResponse}, but uses a different class to avoid
+   * inheriting "responseHeader", etc.
+   */
+  public static class SegmentInfo {
+    @JsonProperty public GetSegmentDataResponse.SegmentSummary info;
+
+    @JsonProperty public Map<String, Object> runningMerges;
+
+    // Present with segments=true || sizeInfo=true || fieldInfo=true
+    @JsonProperty public Map<String, GetSegmentDataResponse.SingleSegmentData> segments;
+
+    // Present with rawSize=true
+    @JsonProperty public GetSegmentDataResponse.RawSize rawSize;
+
+    // Present only with fieldInfo=true
+    @JsonProperty public List<String> fieldInfoLegend;
+  }
+}