diff --git a/server/src/main/java/org/elasticsearch/rest/DeprecationRestHandler.java b/server/src/main/java/org/elasticsearch/rest/DeprecationRestHandler.java
index 98ab7d53ffbe6..8d363f6e63511 100644
--- a/server/src/main/java/org/elasticsearch/rest/DeprecationRestHandler.java
+++ b/server/src/main/java/org/elasticsearch/rest/DeprecationRestHandler.java
@@ -13,7 +13,6 @@
import org.elasticsearch.common.Strings;
import org.elasticsearch.common.logging.DeprecationCategory;
import org.elasticsearch.common.logging.DeprecationLogger;
-import org.elasticsearch.core.Nullable;
import java.util.Objects;
@@ -29,7 +28,6 @@ public class DeprecationRestHandler extends FilterRestHandler implements RestHan
private final DeprecationLogger deprecationLogger;
private final boolean compatibleVersionWarning;
private final String deprecationKey;
- @Nullable
private final Level deprecationLevel;
/**
@@ -39,6 +37,8 @@ public class DeprecationRestHandler extends FilterRestHandler implements RestHan
* @param handler The rest handler to deprecate (it's possible that the handler is reused with a different name!)
* @param method a method of a deprecated endpoint
* @param path a path of a deprecated endpoint
+ * @param deprecationLevel The level of the deprecation warning, must be non-null
+ * and either {@link Level#WARN} or {@link DeprecationLogger#CRITICAL}
* @param deprecationMessage The message to warn users with when they use the {@code handler}
* @param deprecationLogger The deprecation logger
* @param compatibleVersionWarning set to false so that a deprecation warning will be issued for the handled request,
@@ -51,7 +51,7 @@ public DeprecationRestHandler(
RestHandler handler,
RestRequest.Method method,
String path,
- @Nullable Level deprecationLevel,
+ Level deprecationLevel,
String deprecationMessage,
DeprecationLogger deprecationLogger,
boolean compatibleVersionWarning
@@ -61,7 +61,7 @@ public DeprecationRestHandler(
this.deprecationLogger = Objects.requireNonNull(deprecationLogger);
this.compatibleVersionWarning = compatibleVersionWarning;
this.deprecationKey = DEPRECATED_ROUTE_KEY + "_" + method + "_" + path;
- if (deprecationLevel != null && (deprecationLevel != Level.WARN && deprecationLevel != DeprecationLogger.CRITICAL)) {
+ if (deprecationLevel != Level.WARN && deprecationLevel != DeprecationLogger.CRITICAL) {
throw new IllegalArgumentException(
"unexpected deprecation logger level: " + deprecationLevel + ", expected either 'CRITICAL' or 'WARN'"
);
@@ -77,19 +77,18 @@ public DeprecationRestHandler(
@Override
public void handleRequest(RestRequest request, RestChannel channel, NodeClient client) throws Exception {
if (compatibleVersionWarning == false) {
- // The default value for deprecated requests without a version warning is WARN
- if (deprecationLevel == null || deprecationLevel == Level.WARN) {
+ // emit a standard deprecation warning
+ if (Level.WARN == deprecationLevel) {
deprecationLogger.warn(DeprecationCategory.API, deprecationKey, deprecationMessage);
- } else {
+ } else if (DeprecationLogger.CRITICAL == deprecationLevel) {
deprecationLogger.critical(DeprecationCategory.API, deprecationKey, deprecationMessage);
}
} else {
- // The default value for deprecated requests with a version warning is CRITICAL,
- // because they have a specific version where the endpoint is removed
- if (deprecationLevel == null || deprecationLevel == DeprecationLogger.CRITICAL) {
- deprecationLogger.compatibleCritical(deprecationKey, deprecationMessage);
- } else {
+ // emit a compatibility warning
+ if (Level.WARN == deprecationLevel) {
deprecationLogger.compatible(Level.WARN, deprecationKey, deprecationMessage);
+ } else if (DeprecationLogger.CRITICAL == deprecationLevel) {
+ deprecationLogger.compatibleCritical(deprecationKey, deprecationMessage);
}
}
@@ -139,4 +138,9 @@ public static String requireValidHeader(String value) {
return value;
}
+
+ // test only
+ Level getDeprecationLevel() {
+ return deprecationLevel;
+ }
}
diff --git a/server/src/main/java/org/elasticsearch/rest/RestController.java b/server/src/main/java/org/elasticsearch/rest/RestController.java
index 924cd361c671d..c2064fdd931de 100644
--- a/server/src/main/java/org/elasticsearch/rest/RestController.java
+++ b/server/src/main/java/org/elasticsearch/rest/RestController.java
@@ -144,25 +144,6 @@ public ServerlessApiProtections getApiProtections() {
return apiProtections;
}
- /**
- * Registers a REST handler to be executed when the provided {@code method} and {@code path} match the request.
- *
- * @param method GET, POST, etc.
- * @param path Path to handle (e.g. "/{index}/{type}/_bulk")
- * @param version API version to handle (e.g. RestApiVersion.V_8)
- * @param handler The handler to actually execute
- * @param deprecationMessage The message to log and send as a header in the response
- */
- protected void registerAsDeprecatedHandler(
- RestRequest.Method method,
- String path,
- RestApiVersion version,
- RestHandler handler,
- String deprecationMessage
- ) {
- registerAsDeprecatedHandler(method, path, version, handler, deprecationMessage, null);
- }
-
/**
* Registers a REST handler to be executed when the provided {@code method} and {@code path} match the request.
*
@@ -179,40 +160,23 @@ protected void registerAsDeprecatedHandler(
RestApiVersion version,
RestHandler handler,
String deprecationMessage,
- @Nullable Level deprecationLevel
+ Level deprecationLevel
) {
assert (handler instanceof DeprecationRestHandler) == false;
- if (version == RestApiVersion.current()) {
- // e.g. it was marked as deprecated in 8.x, and we're currently running 8.x
- registerHandler(
- method,
- path,
- version,
- new DeprecationRestHandler(handler, method, path, deprecationLevel, deprecationMessage, deprecationLogger, false)
- );
- } else if (version == RestApiVersion.minimumSupported()) {
- // e.g. it was marked as deprecated in 7.x, and we're currently running 8.x
+ if (RestApiVersion.onOrAfter(RestApiVersion.minimumSupported()).test(version)) {
registerHandler(
method,
path,
version,
- new DeprecationRestHandler(handler, method, path, deprecationLevel, deprecationMessage, deprecationLogger, true)
- );
- } else {
- // e.g. it was marked as deprecated in 7.x, and we're currently running *9.x*
- logger.debug(
- "Deprecated route ["
- + method
- + " "
- + path
- + "] for handler ["
- + handler.getClass()
- + "] "
- + "with version ["
- + version
- + "], which is less than the minimum supported version ["
- + RestApiVersion.minimumSupported()
- + "]"
+ new DeprecationRestHandler(
+ handler,
+ method,
+ path,
+ deprecationLevel,
+ deprecationMessage,
+ deprecationLogger,
+ version != RestApiVersion.current()
+ )
);
}
}
@@ -250,21 +214,12 @@ protected void registerAsReplacedHandler(
RestHandler handler,
RestRequest.Method replacedMethod,
String replacedPath,
- RestApiVersion replacedVersion
+ RestApiVersion replacedVersion,
+ String replacedMessage,
+ Level deprecationLevel
) {
- // e.g. [POST /_optimize] is deprecated! Use [POST /_forcemerge] instead.
- final String replacedMessage = "["
- + replacedMethod.name()
- + " "
- + replacedPath
- + "] is deprecated! Use ["
- + method.name()
- + " "
- + path
- + "] instead.";
-
registerHandler(method, path, version, handler);
- registerAsDeprecatedHandler(replacedMethod, replacedPath, replacedVersion, handler, replacedMessage);
+ registerAsDeprecatedHandler(replacedMethod, replacedPath, replacedVersion, handler, replacedMessage, deprecationLevel);
}
/**
@@ -284,7 +239,15 @@ protected void registerHandler(RestRequest.Method method, String path, RestApiVe
private void registerHandlerNoWrap(RestRequest.Method method, String path, RestApiVersion version, RestHandler handler) {
assert RestApiVersion.minimumSupported() == version || RestApiVersion.current() == version
- : "REST API compatibility is only supported for version " + RestApiVersion.minimumSupported().major;
+ : "REST API compatibility is only supported for version "
+ + RestApiVersion.minimumSupported().major
+ + " [method="
+ + method
+ + ", path="
+ + path
+ + ", handler="
+ + handler.getClass().getCanonicalName()
+ + "]";
if (RESERVED_PATHS.contains(path)) {
throw new IllegalArgumentException("path [" + path + "] is a reserved path and may not be registered");
@@ -299,7 +262,7 @@ private void registerHandlerNoWrap(RestRequest.Method method, String path, RestA
}
public void registerHandler(final Route route, final RestHandler handler) {
- if (route.isReplacement()) {
+ if (route.hasReplacement()) {
Route replaced = route.getReplacedRoute();
registerAsReplacedHandler(
route.getMethod(),
@@ -308,7 +271,9 @@ public void registerHandler(final Route route, final RestHandler handler) {
handler,
replaced.getMethod(),
replaced.getPath(),
- replaced.getRestApiVersion()
+ replaced.getRestApiVersion(),
+ replaced.getDeprecationMessage(),
+ replaced.getDeprecationLevel()
);
} else if (route.isDeprecated()) {
registerAsDeprecatedHandler(
diff --git a/server/src/main/java/org/elasticsearch/rest/RestHandler.java b/server/src/main/java/org/elasticsearch/rest/RestHandler.java
index ede295fee9f4d..0e3b8d37dd25c 100644
--- a/server/src/main/java/org/elasticsearch/rest/RestHandler.java
+++ b/server/src/main/java/org/elasticsearch/rest/RestHandler.java
@@ -11,6 +11,7 @@
import org.apache.logging.log4j.Level;
import org.elasticsearch.client.internal.node.NodeClient;
+import org.elasticsearch.common.logging.DeprecationLogger;
import org.elasticsearch.core.Nullable;
import org.elasticsearch.core.RestApiVersion;
import org.elasticsearch.rest.RestRequest.Method;
@@ -136,11 +137,10 @@ class Route {
private final Method method;
private final String path;
private final RestApiVersion restApiVersion;
-
- private final String deprecationMessage;
@Nullable
+ private final String deprecationMessage;
private final Level deprecationLevel;
-
+ @Nullable
private final Route replacedRoute;
private Route(
@@ -153,12 +153,16 @@ private Route(
) {
this.method = Objects.requireNonNull(method);
this.path = Objects.requireNonNull(path);
+ // the last version in which this route was fully supported
this.restApiVersion = Objects.requireNonNull(restApiVersion);
- // a deprecated route will have a deprecation message, and the restApiVersion
- // will represent the version when the route was deprecated
+ // a route marked as deprecated to keep or remove will have a deprecation message and level (warn for keep, critical for remove)
this.deprecationMessage = deprecationMessage;
- this.deprecationLevel = deprecationLevel;
+ this.deprecationLevel = Objects.requireNonNull(deprecationLevel);
+
+ if (deprecationMessage == null && deprecationLevel != Level.OFF) {
+ throw new IllegalArgumentException("deprecationMessage must be set if deprecationLevel is not OFF");
+ }
// a route that replaces another route will have a reference to the route that was replaced
this.replacedRoute = replacedRoute;
@@ -173,7 +177,7 @@ private Route(
* @param path the path, e.g. "/"
*/
public Route(Method method, String path) {
- this(method, path, RestApiVersion.current(), null, null, null);
+ this(method, path, RestApiVersion.current(), null, Level.OFF, null);
}
public static class RouteBuilder {
@@ -183,7 +187,6 @@ public static class RouteBuilder {
private RestApiVersion restApiVersion;
private String deprecationMessage;
- @Nullable
private Level deprecationLevel;
private Route replacedRoute;
@@ -194,6 +197,16 @@ private RouteBuilder(Method method, String path) {
this.restApiVersion = RestApiVersion.current();
}
+ /**
+ * @deprecated Use {@link #deprecatedForRemoval(String, RestApiVersion)} if the intent is deprecate the path and remove in the
+ * next major version. Use {@link #deprecateAndKeep(String)} if the intent is to deprecate the path but not remove it.
+ * This method will delegate to {@link #deprecatedForRemoval(String, RestApiVersion)}.
+ */
+ @Deprecated(since = "9.0.0", forRemoval = true)
+ public RouteBuilder deprecated(String deprecationMessage, RestApiVersion lastFullySupportedVersion) {
+ return deprecatedForRemoval(deprecationMessage, lastFullySupportedVersion);
+ }
+
/**
* Marks that the route being built has been deprecated (for some reason -- the deprecationMessage) for removal. Notes the last
* major version in which the path is fully supported without compatibility headers. If this path is being replaced by another
@@ -202,7 +215,7 @@ private RouteBuilder(Method method, String path) {
* For example:
* {@code
* Route.builder(GET, "_upgrade")
- * .deprecated("The _upgrade API is no longer useful and will be removed.", RestApiVersion.V_7)
+ * .deprecatedForRemoval("The _upgrade API is no longer useful and will be removed.", RestApiVersion.V_7)
* .build()}
*
* @param deprecationMessage the user-visible explanation of this deprecation
@@ -211,10 +224,12 @@ private RouteBuilder(Method method, String path) {
* The next major version (i.e. 9) will have no support whatsoever for this route.
* @return a reference to this object.
*/
- public RouteBuilder deprecated(String deprecationMessage, RestApiVersion lastFullySupportedVersion) {
+ public RouteBuilder deprecatedForRemoval(String deprecationMessage, RestApiVersion lastFullySupportedVersion) {
assert this.replacedRoute == null;
this.restApiVersion = Objects.requireNonNull(lastFullySupportedVersion);
this.deprecationMessage = Objects.requireNonNull(deprecationMessage);
+ // if being deprecated for removal in the current version, then it's a warning, otherwise it's critical
+ this.deprecationLevel = lastFullySupportedVersion == RestApiVersion.current() ? Level.WARN : DeprecationLogger.CRITICAL;
return this;
}
@@ -227,16 +242,38 @@ public RouteBuilder deprecated(String deprecationMessage, RestApiVersion lastFul
* Route.builder(GET, "/_security/user/")
* .replaces(GET, "/_xpack/security/user/", RestApiVersion.V_7).build()}
*
- * @param method the method being replaced
- * @param path the path being replaced
+ * @param replacedMethod the method being replaced
+ * @param replacedPath the path being replaced
* @param lastFullySupportedVersion the last {@link RestApiVersion} (i.e. 7) for which this route is fully supported.
* The next major version (i.e. 8) will require compatibility header(s). (;compatible-with=7)
* The next major version (i.e. 9) will have no support whatsoever for this route.
* @return a reference to this object.
*/
- public RouteBuilder replaces(Method method, String path, RestApiVersion lastFullySupportedVersion) {
+ public RouteBuilder replaces(Method replacedMethod, String replacedPath, RestApiVersion lastFullySupportedVersion) {
assert this.deprecationMessage == null;
- this.replacedRoute = new Route(method, path, lastFullySupportedVersion, null, null, null);
+
+ // if being replaced in the current version, then it's a warning, otherwise it's critical
+ Level deprecationLevel = lastFullySupportedVersion == RestApiVersion.current() ? Level.WARN : DeprecationLogger.CRITICAL;
+
+ // e.g. [POST /_optimize] is deprecated! Use [POST /_forcemerge] instead.
+ final String replacedMessage = "["
+ + replacedMethod.name()
+ + " "
+ + replacedPath
+ + "] is deprecated! Use ["
+ + this.method.name()
+ + " "
+ + this.path
+ + "] instead.";
+
+ this.replacedRoute = new Route(
+ replacedMethod,
+ replacedPath,
+ lastFullySupportedVersion,
+ replacedMessage,
+ deprecationLevel,
+ null
+ );
return this;
}
@@ -246,7 +283,7 @@ public RouteBuilder replaces(Method method, String path, RestApiVersion lastFull
* For example:
* {@code
* Route.builder(GET, "_upgrade")
- * .deprecated("The _upgrade API is no longer useful but will not be removed.")
+ * .deprecateAndKeep("The _upgrade API is no longer useful but will not be removed.")
* .build()}
*
* @param deprecationMessage the user-visible explanation of this deprecation
@@ -261,14 +298,15 @@ public RouteBuilder deprecateAndKeep(String deprecationMessage) {
}
public Route build() {
- if (replacedRoute != null) {
- return new Route(method, path, restApiVersion, null, null, replacedRoute);
- } else if (deprecationMessage != null) {
- return new Route(method, path, restApiVersion, deprecationMessage, deprecationLevel, null);
- } else {
- // this is a little silly, but perfectly legal
- return new Route(method, path, restApiVersion, null, null, null);
- }
+ assert (deprecationMessage != null) == (deprecationLevel != null); // both must be set or neither
+ return new Route(
+ method,
+ path,
+ restApiVersion,
+ deprecationMessage,
+ deprecationLevel == null ? Level.OFF : deprecationLevel,
+ replacedRoute
+ );
}
}
@@ -288,11 +326,11 @@ public RestApiVersion getRestApiVersion() {
return restApiVersion;
}
+ @Nullable
public String getDeprecationMessage() {
return deprecationMessage;
}
- @Nullable
public Level getDeprecationLevel() {
return deprecationLevel;
}
@@ -301,11 +339,12 @@ public boolean isDeprecated() {
return deprecationMessage != null;
}
+ @Nullable
public Route getReplacedRoute() {
return replacedRoute;
}
- public boolean isReplacement() {
+ public boolean hasReplacement() {
return replacedRoute != null;
}
}
diff --git a/server/src/test/java/org/elasticsearch/rest/DeprecationRestHandlerTests.java b/server/src/test/java/org/elasticsearch/rest/DeprecationRestHandlerTests.java
index 4e0fe14fb1def..b534a6be0dc5f 100644
--- a/server/src/test/java/org/elasticsearch/rest/DeprecationRestHandlerTests.java
+++ b/server/src/test/java/org/elasticsearch/rest/DeprecationRestHandlerTests.java
@@ -73,7 +73,7 @@ public void testHandleRequestLogsThenForwards() throws Exception {
RestChannel channel = mock(RestChannel.class);
NodeClient client = mock(NodeClient.class);
- final Level deprecationLevel = randomBoolean() ? null : randomFrom(Level.WARN, DeprecationLogger.CRITICAL);
+ final Level deprecationLevel = randomFrom(Level.WARN, DeprecationLogger.CRITICAL);
DeprecationRestHandler deprecatedHandler = new DeprecationRestHandler(
handler,
@@ -159,17 +159,55 @@ public void testInvalidHeaderValueEmpty() {
public void testSupportsBulkContentTrue() {
when(handler.supportsBulkContent()).thenReturn(true);
assertTrue(
- new DeprecationRestHandler(handler, METHOD, PATH, null, deprecationMessage, deprecationLogger, false).supportsBulkContent()
+ new DeprecationRestHandler(handler, METHOD, PATH, Level.WARN, deprecationMessage, deprecationLogger, false)
+ .supportsBulkContent()
);
}
public void testSupportsBulkContentFalse() {
when(handler.supportsBulkContent()).thenReturn(false);
assertFalse(
- new DeprecationRestHandler(handler, METHOD, PATH, null, deprecationMessage, deprecationLogger, false).supportsBulkContent()
+ new DeprecationRestHandler(handler, METHOD, PATH, Level.WARN, deprecationMessage, deprecationLogger, false)
+ .supportsBulkContent()
);
}
+ public void testDeprecationLevel() {
+ DeprecationRestHandler handler = new DeprecationRestHandler(
+ this.handler,
+ METHOD,
+ PATH,
+ Level.WARN,
+ deprecationMessage,
+ deprecationLogger,
+ false
+ );
+ assertEquals(Level.WARN, handler.getDeprecationLevel());
+
+ handler = new DeprecationRestHandler(
+ this.handler,
+ METHOD,
+ PATH,
+ DeprecationLogger.CRITICAL,
+ deprecationMessage,
+ deprecationLogger,
+ false
+ );
+ assertEquals(DeprecationLogger.CRITICAL, handler.getDeprecationLevel());
+
+ IllegalArgumentException exception = expectThrows(
+ IllegalArgumentException.class,
+ () -> new DeprecationRestHandler(this.handler, METHOD, PATH, null, deprecationMessage, deprecationLogger, false)
+ );
+ assertEquals(exception.getMessage(), "unexpected deprecation logger level: null, expected either 'CRITICAL' or 'WARN'");
+
+ exception = expectThrows(
+ IllegalArgumentException.class,
+ () -> new DeprecationRestHandler(this.handler, METHOD, PATH, Level.OFF, deprecationMessage, deprecationLogger, false)
+ );
+ assertEquals(exception.getMessage(), "unexpected deprecation logger level: OFF, expected either 'CRITICAL' or 'WARN'");
+ }
+
/**
* {@code ASCIIHeaderGenerator} only uses characters expected to be valid in headers (simplified US-ASCII).
*/
diff --git a/server/src/test/java/org/elasticsearch/rest/RestControllerTests.java b/server/src/test/java/org/elasticsearch/rest/RestControllerTests.java
index 1d946681661e7..8f1904ce42438 100644
--- a/server/src/test/java/org/elasticsearch/rest/RestControllerTests.java
+++ b/server/src/test/java/org/elasticsearch/rest/RestControllerTests.java
@@ -9,6 +9,7 @@
package org.elasticsearch.rest;
+import org.apache.logging.log4j.Level;
import org.elasticsearch.ElasticsearchStatusException;
import org.elasticsearch.client.internal.node.NodeClient;
import org.elasticsearch.common.breaker.CircuitBreaker;
@@ -17,6 +18,7 @@
import org.elasticsearch.common.component.AbstractLifecycleComponent;
import org.elasticsearch.common.io.stream.BytesStream;
import org.elasticsearch.common.io.stream.RecyclerBytesStreamOutput;
+import org.elasticsearch.common.logging.DeprecationLogger;
import org.elasticsearch.common.settings.ClusterSettings;
import org.elasticsearch.common.settings.Settings;
import org.elasticsearch.common.transport.BoundTransportAddress;
@@ -85,6 +87,7 @@
import static org.mockito.ArgumentMatchers.anyMap;
import static org.mockito.ArgumentMatchers.anyString;
import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.clearInvocations;
import static org.mockito.Mockito.doCallRealMethod;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.spy;
@@ -349,18 +352,22 @@ public void testRegisterAsDeprecatedHandler() {
String path = "/_" + randomAlphaOfLengthBetween(1, 6);
RestHandler handler = (request, channel, client) -> {};
String deprecationMessage = randomAlphaOfLengthBetween(1, 10);
- RestApiVersion deprecatedInVersion = RestApiVersion.current();
- Route route = Route.builder(method, path).deprecated(deprecationMessage, deprecatedInVersion).build();
+ List replacedInVersions = List.of(RestApiVersion.current(), RestApiVersion.minimumSupported());
+ for (RestApiVersion replacedInVersion : replacedInVersions) {
+ Level level = replacedInVersion == RestApiVersion.current() ? Level.WARN : DeprecationLogger.CRITICAL;
+ clearInvocations(controller);
+ Route route = Route.builder(method, path).deprecatedForRemoval(deprecationMessage, replacedInVersion).build();
- // don't want to test everything -- just that it actually wraps the handler
- doCallRealMethod().when(controller).registerHandler(route, handler);
- doCallRealMethod().when(controller)
- .registerAsDeprecatedHandler(method, path, deprecatedInVersion, handler, deprecationMessage, null);
+ // don't want to test everything -- just that it actually wraps the handler
+ doCallRealMethod().when(controller).registerHandler(route, handler);
+ doCallRealMethod().when(controller)
+ .registerAsDeprecatedHandler(method, path, replacedInVersion, handler, deprecationMessage, level);
- controller.registerHandler(route, handler);
+ controller.registerHandler(route, handler);
- verify(controller).registerHandler(eq(method), eq(path), eq(deprecatedInVersion), any(DeprecationRestHandler.class));
+ verify(controller).registerHandler(eq(method), eq(path), eq(replacedInVersion), any(DeprecationRestHandler.class));
+ }
}
public void testRegisterAsReplacedHandler() {
@@ -383,17 +390,40 @@ public void testRegisterAsReplacedHandler() {
+ path
+ "] instead.";
- final Route route = Route.builder(method, path).replaces(replacedMethod, replacedPath, previous).build();
-
- // don't want to test everything -- just that it actually wraps the handlers
- doCallRealMethod().when(controller).registerHandler(route, handler);
- doCallRealMethod().when(controller)
- .registerAsReplacedHandler(method, path, current, handler, replacedMethod, replacedPath, previous);
-
- controller.registerHandler(route, handler);
+ List replacedInVersions = List.of(current, previous);
+ for (RestApiVersion replacedInVersion : replacedInVersions) {
+ clearInvocations(controller);
+ Route route = Route.builder(method, path).replaces(replacedMethod, replacedPath, replacedInVersion).build();
+ // don't want to test everything -- just that it actually wraps the handler
+ doCallRealMethod().when(controller).registerHandler(route, handler);
+ Level level = replacedInVersion == current ? Level.WARN : DeprecationLogger.CRITICAL;
+ doCallRealMethod().when(controller)
+ .registerAsReplacedHandler(
+ method,
+ path,
+ current,
+ handler,
+ replacedMethod,
+ replacedPath,
+ replacedInVersion,
+ deprecationMessage,
+ level
+ );
- verify(controller).registerHandler(method, path, current, handler);
- verify(controller).registerAsDeprecatedHandler(replacedMethod, replacedPath, previous, handler, deprecationMessage);
+ controller.registerHandler(route, handler);
+
+ // verify we registered the primary handler
+ verify(controller).registerHandler(method, path, current, handler);
+ // verify we register the replaced handler with the correct deprecation message and level
+ verify(controller).registerAsDeprecatedHandler(
+ replacedMethod,
+ replacedPath,
+ replacedInVersion,
+ handler,
+ deprecationMessage,
+ level
+ );
+ }
}
public void testRegisterSecondMethodWithDifferentNamedWildcard() {
diff --git a/x-pack/plugin/deprecation/qa/rest/src/javaRestTest/java/org/elasticsearch/xpack/deprecation/DeprecationHttpIT.java b/x-pack/plugin/deprecation/qa/rest/src/javaRestTest/java/org/elasticsearch/xpack/deprecation/DeprecationHttpIT.java
index f6dd43164e387..3fb9573dd7b62 100644
--- a/x-pack/plugin/deprecation/qa/rest/src/javaRestTest/java/org/elasticsearch/xpack/deprecation/DeprecationHttpIT.java
+++ b/x-pack/plugin/deprecation/qa/rest/src/javaRestTest/java/org/elasticsearch/xpack/deprecation/DeprecationHttpIT.java
@@ -477,6 +477,111 @@ public void testDeprecationWarnMessagesCanBeIndexed() throws Exception {
}
+ public void testDeprecateAndKeep() throws Exception {
+ final Request request = new Request("GET", "/_test_cluster/deprecated_but_dont_remove");
+ request.setEntity(buildSettingsRequest(Collections.singletonList(TEST_NOT_DEPRECATED_SETTING), "settings"));
+ Response response = performScopedRequest(request);
+
+ final List deprecatedWarnings = getWarningHeaders(response.getHeaders());
+ assertThat(
+ extractWarningValuesFromWarningHeaders(deprecatedWarnings),
+ containsInAnyOrder("[/_test_cluster/deprecated_but_dont_remove] is deprecated, but no plans to remove quite yet")
+ );
+
+ assertBusy(() -> {
+ List> documents = DeprecationTestUtils.getIndexedDeprecations(client(), xOpaqueId());
+
+ logger.warn(documents);
+
+ // only assert the relevant fields: level, message, and category
+ assertThat(
+ documents,
+ containsInAnyOrder(
+ allOf(
+ hasEntry("elasticsearch.event.category", "api"),
+ hasEntry("log.level", "WARN"),
+ hasEntry("message", "[/_test_cluster/deprecated_but_dont_remove] is deprecated, but no plans to remove quite yet")
+ )
+ )
+ );
+ }, 30, TimeUnit.SECONDS);
+ }
+
+ public void testReplacesInCurrentVersion() throws Exception {
+ final Request request = new Request("GET", "/_test_cluster/old_name1"); // deprecated in current version
+ request.setEntity(buildSettingsRequest(Collections.singletonList(TEST_NOT_DEPRECATED_SETTING), "settings"));
+ Response response = performScopedRequest(request);
+
+ final List deprecatedWarnings = getWarningHeaders(response.getHeaders());
+ assertThat(
+ extractWarningValuesFromWarningHeaders(deprecatedWarnings),
+ containsInAnyOrder("[GET /_test_cluster/old_name1] is deprecated! Use [GET /_test_cluster/new_name1] instead.")
+ );
+
+ assertBusy(() -> {
+ List> documents = DeprecationTestUtils.getIndexedDeprecations(client(), xOpaqueId());
+
+ logger.warn(documents);
+
+ // only assert the relevant fields: level, message, and category
+ assertThat(
+ documents,
+ containsInAnyOrder(
+ allOf(
+ hasEntry("elasticsearch.event.category", "api"),
+ hasEntry("log.level", "WARN"),
+ hasEntry("message", "[GET /_test_cluster/old_name1] is deprecated! Use [GET /_test_cluster/new_name1] instead.")
+ )
+ )
+ );
+ }, 30, TimeUnit.SECONDS);
+ }
+
+ public void testReplacesInCompatibleVersion() throws Exception {
+ final Request request = new Request("GET", "/_test_cluster/old_name2"); // deprecated in minimum supported version
+ request.setEntity(buildSettingsRequest(Collections.singletonList(TEST_DEPRECATED_SETTING_TRUE1), "deprecated_settings"));
+ final RequestOptions compatibleOptions = request.getOptions()
+ .toBuilder()
+ .addHeader("Accept", "application/vnd.elasticsearch+json;compatible-with=" + RestApiVersion.minimumSupported().major)
+ .addHeader("Content-Type", "application/vnd.elasticsearch+json;compatible-with=" + RestApiVersion.minimumSupported().major)
+ .build();
+ request.setOptions(compatibleOptions);
+ Response response = performScopedRequest(request);
+
+ final List deprecatedWarnings = getWarningHeaders(response.getHeaders());
+ assertThat(
+ extractWarningValuesFromWarningHeaders(deprecatedWarnings),
+ containsInAnyOrder(
+ "[GET /_test_cluster/old_name2] is deprecated! Use [GET /_test_cluster/new_name2] instead.",
+ "You are using a compatible API for this request"
+ )
+ );
+ assertBusy(() -> {
+ List> documents = DeprecationTestUtils.getIndexedDeprecations(client(), xOpaqueId());
+
+ logger.warn(documents);
+
+ // only assert the relevant fields: level, message, and category
+ assertThat(
+ documents,
+ containsInAnyOrder(
+ allOf(
+
+ hasEntry("elasticsearch.event.category", "compatible_api"),
+ hasEntry("log.level", "CRITICAL"),
+ hasEntry("message", "[GET /_test_cluster/old_name2] is deprecated! Use [GET /_test_cluster/new_name2] instead.")
+ ),
+ allOf(
+ hasEntry("elasticsearch.event.category", "compatible_api"),
+ hasEntry("log.level", "CRITICAL"),
+ // this message comes from the test, not production code. this is the message for setting the deprecated setting
+ hasEntry("message", "You are using a compatible API for this request")
+ )
+ )
+ );
+ }, 30, TimeUnit.SECONDS);
+ }
+
/**
* Check that log messages about REST API compatibility are recorded to an index
*/
diff --git a/x-pack/plugin/deprecation/qa/rest/src/main/java/org/elasticsearch/xpack/deprecation/TestDeprecationHeaderRestAction.java b/x-pack/plugin/deprecation/qa/rest/src/main/java/org/elasticsearch/xpack/deprecation/TestDeprecationHeaderRestAction.java
index 70942b04f85b8..9e5f999d1f825 100644
--- a/x-pack/plugin/deprecation/qa/rest/src/main/java/org/elasticsearch/xpack/deprecation/TestDeprecationHeaderRestAction.java
+++ b/x-pack/plugin/deprecation/qa/rest/src/main/java/org/elasticsearch/xpack/deprecation/TestDeprecationHeaderRestAction.java
@@ -97,10 +97,23 @@ public List routes() {
return List.of(
// note: RestApiVersion.current() is acceptable here because this is test code -- ordinary callers of `.deprecated(...)`
// should use an actual version
- Route.builder(GET, "/_test_cluster/deprecated_settings").deprecated(DEPRECATED_ENDPOINT, RestApiVersion.current()).build(),
+ Route.builder(GET, "/_test_cluster/deprecated_settings")
+ .deprecatedForRemoval(DEPRECATED_ENDPOINT, RestApiVersion.current())
+ .build(),
+ // TODO: s/deprecated/deprecatedForRemoval when removing `deprecated` method
Route.builder(POST, "/_test_cluster/deprecated_settings").deprecated(DEPRECATED_ENDPOINT, RestApiVersion.current()).build(),
- Route.builder(GET, "/_test_cluster/compat_only").deprecated(DEPRECATED_ENDPOINT, RestApiVersion.minimumSupported()).build(),
- Route.builder(GET, "/_test_cluster/only_deprecated_setting").build()
+ Route.builder(GET, "/_test_cluster/compat_only")
+ .deprecatedForRemoval(DEPRECATED_ENDPOINT, RestApiVersion.minimumSupported())
+ .build(),
+ Route.builder(GET, "/_test_cluster/only_deprecated_setting").build(),
+ Route.builder(GET, "/_test_cluster/deprecated_but_dont_remove")
+ .deprecateAndKeep("[/_test_cluster/deprecated_but_dont_remove] is deprecated, but no plans to remove quite yet")
+ .build(),
+ Route.builder(GET, "/_test_cluster/new_name1").replaces(GET, "/_test_cluster/old_name1", RestApiVersion.current()).build(),
+ Route.builder(GET, "/_test_cluster/new_name2")
+ .replaces(GET, "/_test_cluster/old_name2", RestApiVersion.minimumSupported())
+ .build()
+
);
}