Repository navigation
SOLR-18212: Migrate PackageAPI endpoints from @EndPoint/@Command to JAX-RS #4178
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| title: The package management API now has OpenAPI and SolrJ support. As part of this migration, the (experimental v2) API path moved from `/api/cluster/package` to `/api/cluster/packages`, and requests for a non-existent package or package version now return HTTP 404 instead of 400. | ||
| type: changed | ||
| authors: | ||
| - name: Eric Pugh | ||
| links: | ||
| - name: PR#4178 | ||
| url: https://github.com/apache/solr/pull/4178 | ||
| - name: SOLR-18212 | ||
| url: https://issues.apache.org/jira/browse/SOLR-18212 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,116 @@ | ||
| /* | ||
| * 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 io.swagger.v3.oas.annotations.parameters.RequestBody; | ||
| import jakarta.ws.rs.DELETE; | ||
| import jakarta.ws.rs.GET; | ||
| import jakarta.ws.rs.POST; | ||
| import jakarta.ws.rs.Path; | ||
| import jakarta.ws.rs.PathParam; | ||
| import jakarta.ws.rs.QueryParam; | ||
| import org.apache.solr.client.api.model.AddPackageVersionRequestBody; | ||
| import org.apache.solr.client.api.model.GetPackageResponse; | ||
| import org.apache.solr.client.api.model.ListPackagesResponse; | ||
| import org.apache.solr.client.api.model.SolrJerseyResponse; | ||
|
|
||
| /** V2 API definitions for managing Solr packages. */ | ||
| @Path("/cluster/packages") | ||
| public interface PackageApis { | ||
|
|
||
| @GET | ||
| @Operation( | ||
| summary = "List all packages registered in this Solr cluster.", | ||
| tags = {"package"}) | ||
| ListPackagesResponse listPackages( | ||
| @Parameter( | ||
| description = | ||
| "If provided, the node waits until its package data matches this ZooKeeper version.") | ||
| @QueryParam("expectedVersion") | ||
| Integer expectedVersion); | ||
|
|
||
| @GET | ||
| @Path("/{packageName}") | ||
| @Operation( | ||
| summary = "Get information about a specific package in this Solr cluster.", | ||
| tags = {"package"}) | ||
| GetPackageResponse getPackage( | ||
| @Parameter(description = "The name of the package.", required = true) | ||
| @PathParam("packageName") | ||
| String packageName, | ||
| @Parameter( | ||
| description = | ||
| "If provided, the node waits until its package data matches this ZooKeeper version before responding.") | ||
| @QueryParam("expectedVersion") | ||
| Integer expectedVersion); | ||
|
|
||
| @POST | ||
| @Path("/{packageName}/versions") | ||
| @Operation( | ||
| summary = "Add a version of a package to this Solr cluster.", | ||
| tags = {"package"}) | ||
| SolrJerseyResponse addPackageVersion( | ||
| @Parameter(description = "The name of the package.", required = true) | ||
| @PathParam("packageName") | ||
| String packageName, | ||
| @RequestBody(description = "Details of the package version to add.", required = true) | ||
| AddPackageVersionRequestBody requestBody); | ||
|
|
||
| @DELETE | ||
| @Path("/{packageName}/versions/{version}") | ||
| @Operation( | ||
| summary = "Delete a specific version of a package from this Solr cluster.", | ||
| tags = {"package"}) | ||
| SolrJerseyResponse deletePackageVersion( | ||
| @Parameter(description = "The name of the package.", required = true) | ||
| @PathParam("packageName") | ||
| String packageName, | ||
| @Parameter(description = "The version of the package to delete.", required = true) | ||
| @PathParam("version") | ||
| String version); | ||
|
|
||
| @POST | ||
| @Path("/{packageName}/refresh") | ||
| @Operation( | ||
| summary = "Refresh a package on all nodes in this Solr cluster.", | ||
| tags = {"package"}) | ||
| SolrJerseyResponse refreshPackage( | ||
| @Parameter(description = "The name of the package to refresh.", required = true) | ||
| @PathParam("packageName") | ||
| String packageName, | ||
| @Parameter( | ||
| description = | ||
| "Indicates whether the refresh should only be done on the receiving node. For internal use only.") | ||
| @QueryParam("localOnly") | ||
| Boolean localOnly); | ||
|
|
||
| @POST | ||
| @Path("/sync") | ||
| @Operation( | ||
| summary = | ||
| "Block until the receiving node's package data matches the given ZooKeeper version. " | ||
| + "Used internally for inter-node fan-out after a package change; not normally invoked directly.", | ||
| tags = {"package"}) | ||
| SolrJerseyResponse syncPackages( | ||
| @Parameter( | ||
| description = "The ZooKeeper version that the receiving node should catch up to.", | ||
| required = true) | ||
| @QueryParam("expectedVersion") | ||
| Integer expectedVersion); | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| /* | ||
| * 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; | ||
|
|
||
| /** Request body for adding a version of a package. */ | ||
| public class AddPackageVersionRequestBody { | ||
|
|
||
| @JsonProperty("version") | ||
| @Schema(description = "The version string for this package version.", required = true) | ||
|
Contributor
There was a problem hiding this comment. my local IntelliJ showed this warning. 
please see, if applicable here.
Contributor
Author
There was a problem hiding this comment. thanks, going to look....
Contributor
Author
There was a problem hiding this comment. Confirmed via the compiler (
|
||
| public String version; | ||
|
|
||
| @JsonProperty("files") | ||
| @Schema( | ||
| description = "File paths from the file store to include in this version.", | ||
| required = true) | ||
| public List<String> files; | ||
|
|
||
| @JsonProperty("manifest") | ||
| @Schema(description = "Optional path to a manifest file in the file store.") | ||
| public String manifest; | ||
|
|
||
| @JsonProperty("manifestSHA512") | ||
| @Schema(description = "Optional SHA-512 hash of the manifest file.") | ||
| public String manifestSHA512; | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,57 @@ | ||
| /* | ||
| * 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 java.util.Map; | ||
|
|
||
| /** Response for the package listing API. */ | ||
| public class ListPackagesResponse extends SolrJerseyResponse { | ||
|
|
||
| @JsonProperty("packages") | ||
| @Schema(description = "Map from package name to list of package versions.") | ||
| public Map<String, List<PackageVersion>> packages; | ||
|
|
||
| @JsonProperty("znodeVersion") | ||
| @Schema(description = "The ZooKeeper version of the packages.json node.") | ||
| public int znodeVersion; | ||
|
|
||
| /** Describes a single version of a package. */ | ||
| public static class PackageVersion { | ||
| @JsonProperty("package") | ||
| @Schema(description = "The package name.") | ||
| public String pkg; | ||
|
|
||
| @JsonProperty("version") | ||
| @Schema(description = "The version string.") | ||
| public String version; | ||
|
|
||
| @JsonProperty("files") | ||
| @Schema(description = "List of file paths from the file store included in this version.") | ||
| public List<String> files; | ||
|
|
||
| @JsonProperty("manifest") | ||
| @Schema(description = "Optional manifest reference.") | ||
| public String manifest; | ||
|
|
||
| @JsonProperty("manifestSHA512") | ||
| @Schema(description = "Optional SHA-512 hash of the manifest.") | ||
| public String manifestSHA512; | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Per
dev-docs/apis-v2-conventions.adoc's "Unproxied APIs" section: paths like/api/node/keyexist specifically to mark operations that only affect the receiving node and must never be proxied.syncPackages()fits that exactly -- it only ever touches the localPackageStore(seeClusterPackage.syncToVersion), and is invoked exclusively viabroadcastToLiveNodes()/processWithBaseUrl()targeting one specific node's base URL. The@Operationsummary here says as much: "Used internally for inter-node fan-out after a package change; not normally invoked directly."Recommend
POST /api/node/packages/syncinstead of/cluster/packages/sync, following the existing/node/{resource}pattern (NodeSystemInfoApi→/node/system,NodeHealthApi→/node/health, and especiallyGetNodeCommandStatusApi→/node/commands/, the closest precedent as another receiving-node-only, not-cluster-tracked concept) combined with the "command API" convention already used elsewhere in this PR (refreshPackage→.../refresh):packagesas the resource,syncas the appended command verb. Only this one endpoint would need to move --listPackages/getPackageare genuinely cluster-wide, proxy-friendly reads and should stay under/cluster/packages.