[REST Compatible API] Route refactoring (#69573)

Related to #51816

Makes `Route`s  `RestApiVersion` -aware (and `RestHandler`s `RestApiVersion` -agnostic). Refactors 
how `Route`s are constructed in the case of deprecation or replacement of routes.

Author: joegallo

server/src/main/java/org/elasticsearch/rest/BaseRestHandler.java

@@ -192,16 +192,6 @@ public List<Route> routes() {
             return delegate.routes();
         }
 
-        @Override
-        public List<DeprecatedRoute> deprecatedRoutes() {
-            return delegate.deprecatedRoutes();
-        }
-
-        @Override
-        public List<ReplacedRoute> replacedRoutes() {
-            return delegate.replacedRoutes();
-        }
-
         @Override
         protected RestChannelConsumer prepareRequest(RestRequest request, NodeClient client) throws IOException {
             return delegate.prepareRequest(request, client);

server/src/main/java/org/elasticsearch/rest/DeprecationRestHandler.java

@@ -23,6 +23,7 @@ public class DeprecationRestHandler implements RestHandler {
     private final RestHandler handler;
     private final String deprecationMessage;
     private final DeprecationLogger deprecationLogger;
+    private final boolean compatibleVersionWarning;
 
     /**
      * Create a {@link DeprecationRestHandler} that encapsulates the {@code handler} using the {@code deprecationLogger} to log
@@ -31,13 +32,18 @@ public class DeprecationRestHandler implements RestHandler {
      * @param handler The rest handler to deprecate (it's possible that the handler is reused with a different name!)
      * @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,
+     *                                 set to true to that a compatibility api warning will be issue for the handled request
+     *
      * @throws NullPointerException if any parameter except {@code deprecationMessage} is {@code null}
      * @throws IllegalArgumentException if {@code deprecationMessage} is not a valid header
      */
-    public DeprecationRestHandler(RestHandler handler, String deprecationMessage, DeprecationLogger deprecationLogger) {
+    public DeprecationRestHandler(RestHandler handler, String deprecationMessage, DeprecationLogger deprecationLogger,
+                                  boolean compatibleVersionWarning) {
         this.handler = Objects.requireNonNull(handler);
         this.deprecationMessage = requireValidHeader(deprecationMessage);
         this.deprecationLogger = Objects.requireNonNull(deprecationLogger);
+        this.compatibleVersionWarning = compatibleVersionWarning;
     }
 
     /**
@@ -47,7 +53,11 @@ public DeprecationRestHandler(RestHandler handler, String deprecationMessage, De
      */
     @Override
     public void handleRequest(RestRequest request, RestChannel channel, NodeClient client) throws Exception {
-        deprecationLogger.deprecate(DeprecationCategory.API, "deprecated_route", deprecationMessage);
+        if (compatibleVersionWarning == false) {
+            deprecationLogger.deprecate(DeprecationCategory.API, "deprecated_route", deprecationMessage);
+        } else {
+            deprecationLogger.compatibleApiWarning("deprecated_route", deprecationMessage);
+        }
 
         handler.handleRequest(request, channel, client);
     }

server/src/main/java/org/elasticsearch/rest/MethodHandlers.java

@@ -22,26 +22,28 @@ final class MethodHandlers {
     private final String path;
     private final Map<RestRequest.Method, Map<RestApiVersion, RestHandler>> methodHandlers;
 
-    MethodHandlers(String path, RestHandler handler, RestRequest.Method... methods) {
+    MethodHandlers(String path) {
         this.path = path;
-        this.methodHandlers = new HashMap<>(methods.length);
-        for (RestRequest.Method method : methods) {
-            methodHandlers.computeIfAbsent(method, k -> new HashMap<>())
-                .put(handler.compatibleWithVersion(), handler);
-        }
+
+        // by setting the loadFactor to 1, these maps are resized only when they *must* be, and the vast majority of these
+        // maps contain only 1 or 2 entries anyway, so most of these maps are never resized at all and waste only 1 or 0
+        // array references, while those few that contain 3 or 4 elements will have been resized just once and will still
+        // waste only 1 or 0 array references
+        this.methodHandlers = new HashMap<>(2, 1);
     }
 
     /**
      * Add a handler for an additional array of methods. Note that {@code MethodHandlers}
      * does not allow replacing the handler for an already existing method.
      */
-    MethodHandlers addMethods(RestHandler handler, RestRequest.Method... methods) {
-        for (RestRequest.Method method : methods) {
-            RestHandler existing = methodHandlers.computeIfAbsent(method, k -> new HashMap<>())
-                .putIfAbsent(handler.compatibleWithVersion(), handler);
-            if (existing != null) {
-                throw new IllegalArgumentException("Cannot replace existing handler for [" + path + "] for method: " + method);
-            }
+    MethodHandlers addMethod(RestRequest.Method method, RestApiVersion version, RestHandler handler) {
+        RestHandler existing = methodHandlers
+            // same sizing notes as 'methodHandlers' above, except that having a size here that's more than 1 is vanishingly
+            // rare, so an initialCapacity of 1 with a loadFactor of 1 is perfect
+            .computeIfAbsent(method, k -> new HashMap<>(1, 1))
+            .putIfAbsent(version, handler);
+        if (existing != null) {
+            throw new IllegalArgumentException("Cannot replace existing handler for [" + path + "] for method: " + method);
         }
         return this;
     }
@@ -61,7 +63,6 @@ RestHandler getHandler(RestRequest.Method method, RestApiVersion version) {
         }
         final RestHandler handler = versionToHandlers.get(version);
         return handler == null ? versionToHandlers.get(RestApiVersion.current()) : handler;
-
     }
 
     /**

server/src/main/java/org/elasticsearch/rest/RestController.java

@@ -28,6 +28,7 @@
 import org.elasticsearch.core.internal.io.Streams;
 import org.elasticsearch.http.HttpServerTransport;
 import org.elasticsearch.indices.breaker.CircuitBreakerService;
+import org.elasticsearch.rest.RestHandler.Route;
 import org.elasticsearch.usage.UsageService;
 
 import java.io.ByteArrayOutputStream;
@@ -92,91 +93,117 @@ public RestController(Set<RestHeaderDefinition> headersToCopy, UnaryOperator<Res
         this.handlerWrapper = handlerWrapper;
         this.client = client;
         this.circuitBreakerService = circuitBreakerService;
-        registerHandlerNoWrap(RestRequest.Method.GET, "/favicon.ico", (request, channel, clnt) ->
+        registerHandlerNoWrap(RestRequest.Method.GET, "/favicon.ico", RestApiVersion.current(),
+            (request, channel, clnt) ->
                 channel.sendResponse(new BytesRestResponse(RestStatus.OK, "image/x-icon", FAVICON_RESPONSE)));
     }
 
     /**
      * 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 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, RestHandler handler, String deprecationMessage) {
+    protected void registerAsDeprecatedHandler(RestRequest.Method method, String path, RestApiVersion version,
+                                               RestHandler handler, String deprecationMessage) {
         assert (handler instanceof DeprecationRestHandler) == false;
-
-        registerHandler(method, path, new DeprecationRestHandler(handler, deprecationMessage, deprecationLogger));
+        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, 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
+            registerHandler(method, path, version, new DeprecationRestHandler(handler, 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() + "]");
+        }
     }
 
     /**
      * Registers a REST handler to be executed when the provided {@code method} and {@code path} match the request, or when provided
-     * with {@code deprecatedMethod} and {@code deprecatedPath}. Expected usage:
+     * with {@code replacedMethod} and {@code replacedPath}. Expected usage:
      * <pre><code>
      * // remove deprecation in next major release
-     * controller.registerWithDeprecatedHandler(POST, "/_forcemerge", this,
-     *                                          POST, "/_optimize", deprecationLogger);
-     * controller.registerWithDeprecatedHandler(POST, "/{index}/_forcemerge", this,
-     *                                          POST, "/{index}/_optimize", deprecationLogger);
+     * controller.registerAsDeprecatedHandler(POST, "/_forcemerge", RestApiVersion.V_8, someHandler,
+     *                                        POST, "/_optimize", RestApiVersion.V_7);
+     * controller.registerAsDeprecatedHandler(POST, "/{index}/_forcemerge", RestApiVersion.V_8, someHandler,
+     *                                        POST, "/{index}/_optimize", RestApiVersion.V_7);
      * </code></pre>
      * <p>
      * The registered REST handler ({@code method} with {@code path}) is a normal REST handler that is not deprecated and it is
-     * replacing the deprecated REST handler ({@code deprecatedMethod} with {@code deprecatedPath}) that is using the <em>same</em>
+     * replacing the deprecated REST handler ({@code replacedMethod} with {@code replacedPath}) that is using the <em>same</em>
      * {@code handler}.
      * <p>
      * Deprecated REST handlers without a direct replacement should be deprecated directly using {@link #registerAsDeprecatedHandler}
      * and a specific message.
      *
      * @param method GET, POST, etc.
-     * @param path Path to handle (e.g., "/_forcemerge")
+     * @param path Path to handle (e.g. "/_forcemerge")
+     * @param version API version to handle (e.g. RestApiVersion.V_8)
      * @param handler The handler to actually execute
-     * @param deprecatedMethod GET, POST, etc.
-     * @param deprecatedPath <em>Deprecated</em> path to handle (e.g., "/_optimize")
+     * @param replacedMethod GET, POST, etc.
+     * @param replacedPath <em>Replaced</em> path to handle (e.g. "/_optimize")
+     * @param replacedVersion <em>Replaced</em> API version to handle (e.g. RestApiVersion.V_7)
      */
-    protected void registerWithDeprecatedHandler(RestRequest.Method method, String path, RestHandler handler,
-                                              RestRequest.Method deprecatedMethod, String deprecatedPath) {
-        // e.g., [POST /_optimize] is deprecated! Use [POST /_forcemerge] instead.
-        final String deprecationMessage =
-            "[" + deprecatedMethod.name() + " " + deprecatedPath + "] is deprecated! Use [" + method.name() + " " + path + "] instead.";
-
-        registerHandler(method, path, handler);
-        registerAsDeprecatedHandler(deprecatedMethod, deprecatedPath, handler, deprecationMessage);
+    protected void registerAsReplacedHandler(RestRequest.Method method, String path, RestApiVersion version, RestHandler handler,
+                                             RestRequest.Method replacedMethod, String replacedPath, RestApiVersion replacedVersion) {
+        // 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);
     }
 
     /**
      * Registers a REST handler to be executed when one of the provided methods and path match the request.
      *
-     * @param path Path to handle (e.g., "/{index}/{type}/_bulk")
-     * @param handler The handler to actually execute
      * @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
      */
-    protected void registerHandler(RestRequest.Method method, String path, RestHandler handler) {
+    protected void registerHandler(RestRequest.Method method, String path, RestApiVersion version, RestHandler handler) {
         if (handler instanceof BaseRestHandler) {
             usageService.addRestHandler((BaseRestHandler) handler);
         }
-        registerHandlerNoWrap(method, path, handlerWrapper.apply(handler));
+        registerHandlerNoWrap(method, path, version, handlerWrapper.apply(handler));
     }
 
-    private void registerHandlerNoWrap(RestRequest.Method method, String path, RestHandler maybeWrappedHandler) {
-        final RestApiVersion version = maybeWrappedHandler.compatibleWithVersion();
+    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;
 
-        handlers.insertOrUpdate(path, new MethodHandlers(path, maybeWrappedHandler, method),
-            (mHandlers, newMHandler) -> mHandlers.addMethods(maybeWrappedHandler, method));
+        handlers.insertOrUpdate(path,
+            new MethodHandlers(path).addMethod(method, version, handler),
+            (handlers, ignoredHandler) -> handlers.addMethod(method, version, handler));
+    }
+
+    public void registerHandler(final Route route, final RestHandler handler) {
+        if (route.isReplacement()) {
+            Route replaced = route.getReplacedRoute();
+            registerAsReplacedHandler(route.getMethod(), route.getPath(), route.getRestApiVersion(), handler,
+                replaced.getMethod(), replaced.getPath(), replaced.getRestApiVersion());
+        } else if (route.isDeprecated()) {
+            registerAsDeprecatedHandler(route.getMethod(), route.getPath(), route.getRestApiVersion(), handler,
+                route.getDeprecationMessage());
+        } else {
+            // it's just a normal route
+            registerHandler(route.getMethod(), route.getPath(), route.getRestApiVersion(), handler);
+        }
     }
 
     /**
      * Registers a REST handler with the controller. The REST handler declares the {@code method}
      * and {@code path} combinations.
      */
-    public void registerHandler(final RestHandler restHandler) {
-        restHandler.routes().forEach(route -> registerHandler(route.getMethod(), route.getPath(), restHandler));
-        restHandler.deprecatedRoutes().forEach(route ->
-            registerAsDeprecatedHandler(route.getMethod(), route.getPath(), restHandler, route.getDeprecationMessage()));
-        restHandler.replacedRoutes().forEach(route -> registerWithDeprecatedHandler(route.getMethod(), route.getPath(),
-            restHandler, route.getDeprecatedMethod(), route.getDeprecatedPath()));
+    public void registerHandler(final RestHandler handler) {
+        handler.routes().forEach(route -> registerHandler(route, handler));
     }
 
     @Override
@@ -320,7 +347,7 @@ private void tryAllHandlers(final RestRequest request, final RestChannel channel
         // we consume the error_trace parameter first to ensure that it is always consumed
         if (request.paramAsBoolean("error_trace", false) && channel.detailedErrorsEnabled() == false) {
             channel.sendResponse(
-                    BytesRestResponse.createSimpleErrorResponse(channel, BAD_REQUEST, "error traces in responses are disabled."));
+                BytesRestResponse.createSimpleErrorResponse(channel, BAD_REQUEST, "error traces in responses are disabled."));
             return;
         }
 
@@ -343,9 +370,9 @@ private void tryAllHandlers(final RestRequest request, final RestChannel channel
                     handler = handlers.getHandler(requestMethod, restApiVersion);
                 }
                 if (handler == null) {
-                  if (handleNoHandlerFound(rawPath, requestMethod, uri, channel)) {
-                      return;
-                  }
+                    if (handleNoHandlerFound(rawPath, requestMethod, uri, channel)) {
+                        return;
+                    }
                 } else {
                     dispatchRequest(request, channel, handler, restApiVersion);
                     return;
@@ -496,7 +523,7 @@ public XContentBuilder newBuilder(@Nullable XContentType xContentType, boolean u
 
         @Override
         public XContentBuilder newBuilder(XContentType xContentType, XContentType responseContentType, boolean useFiltering)
-                throws IOException {
+            throws IOException {
             return delegate.newBuilder(xContentType, responseContentType, useFiltering)
                 .withCompatibleVersion(restApiVersion);
         }