Support for functional routing by API version

See gh-35113

Author: rstoyanchev

spring-test/src/main/java/org/springframework/mock/web/reactive/function/server/MockServerRequest.java

@@ -50,6 +50,7 @@
 import org.springframework.util.LinkedMultiValueMap;
 import org.springframework.util.MultiValueMap;
 import org.springframework.web.bind.WebDataBinder;
+import org.springframework.web.reactive.accept.ApiVersionStrategy;
 import org.springframework.web.reactive.function.BodyExtractor;
 import org.springframework.web.reactive.function.server.HandlerStrategies;
 import org.springframework.web.reactive.function.server.ServerRequest;
@@ -94,6 +95,8 @@ public final class MockServerRequest implements ServerRequest {
 
 	private final List<HttpMessageReader<?>> messageReaders;
 
+	private final @Nullable ApiVersionStrategy versionStrategy;
+
 	private final @Nullable ServerWebExchange exchange;
 
 
@@ -102,7 +105,8 @@ private MockServerRequest(HttpMethod method, URI uri, String contextPath, MockHe
 			Map<String, Object> attributes, MultiValueMap<String, String> queryParams,
 			Map<String, String> pathVariables, @Nullable WebSession session, @Nullable Principal principal,
 			@Nullable InetSocketAddress remoteAddress, @Nullable InetSocketAddress localAddress,
-			List<HttpMessageReader<?>> messageReaders, @Nullable ServerWebExchange exchange) {
+			List<HttpMessageReader<?>> messageReaders, @Nullable ApiVersionStrategy versionStrategy,
+			@Nullable ServerWebExchange exchange) {
 
 		this.method = method;
 		this.uri = uri;
@@ -118,6 +122,7 @@ private MockServerRequest(HttpMethod method, URI uri, String contextPath, MockHe
 		this.remoteAddress = remoteAddress;
 		this.localAddress = localAddress;
 		this.messageReaders = messageReaders;
+		this.versionStrategy = versionStrategy;
 		this.exchange = exchange;
 	}
 
@@ -167,6 +172,11 @@ public List<HttpMessageReader<?>> messageReaders() {
 		return this.messageReaders;
 	}
 
+	@Override
+	public @Nullable ApiVersionStrategy apiVersionStrategy() {
+		return this.versionStrategy;
+	}
+
 	@Override
 	@SuppressWarnings("unchecked")
 	public <S> S body(BodyExtractor<S, ? super ServerHttpRequest> extractor) {
@@ -313,6 +323,8 @@ public interface Builder {
 
 		Builder messageReaders(List<HttpMessageReader<?>> messageReaders);
 
+		Builder apiVersionStrategy(@Nullable ApiVersionStrategy versionStrategy);
+
 		Builder exchange(ServerWebExchange exchange);
 
 		MockServerRequest body(Object body);
@@ -351,6 +363,8 @@ private static class BuilderImpl implements Builder {
 
 		private List<HttpMessageReader<?>> messageReaders = HandlerStrategies.withDefaults().messageReaders();
 
+		private @Nullable ApiVersionStrategy versionStrategy;
+
 		private @Nullable ServerWebExchange exchange;
 
 		@Override
@@ -483,6 +497,12 @@ public Builder messageReaders(List<HttpMessageReader<?>> messageReaders) {
 			return this;
 		}
 
+		@Override
+		public Builder apiVersionStrategy(@Nullable ApiVersionStrategy versionStrategy) {
+			this.versionStrategy = versionStrategy;
+			return this;
+		}
+
 		@Override
 		public Builder exchange(ServerWebExchange exchange) {
 			Assert.notNull(exchange, "'exchange' must not be null");
@@ -496,15 +516,15 @@ public MockServerRequest body(Object body) {
 			return new MockServerRequest(this.method, this.uri, this.contextPath, this.headers,
 					this.cookies, this.body, this.attributes, this.queryParams, this.pathVariables,
 					this.session, this.principal, this.remoteAddress, this.localAddress,
-					this.messageReaders, this.exchange);
+					this.messageReaders, this.versionStrategy, this.exchange);
 		}
 
 		@Override
 		public MockServerRequest build() {
 			return new MockServerRequest(this.method, this.uri, this.contextPath, this.headers,
 					this.cookies, null, this.attributes, this.queryParams, this.pathVariables,
 					this.session, this.principal, this.remoteAddress, this.localAddress,
-					this.messageReaders, this.exchange);
+					this.messageReaders, this.versionStrategy, this.exchange);
 		}
 	}
 

spring-web/src/main/java/org/springframework/web/accept/DefaultApiVersionStrategy.java

@@ -91,6 +91,16 @@ public DefaultApiVersionStrategy(
 		return this.defaultVersion;
 	}
 
+	/**
+	 * Whether the strategy is configured to detect supported versions.
+	 * If this is set to {@code false} then {@link #addMappedVersion} is ignored
+	 * and the list of supported versions can be built explicitly through calls
+	 * to {@link #addSupportedVersion}.
+	 */
+	public boolean detectSupportedVersions() {
+		return this.detectSupportedVersions;
+	}
+
 	/**
 	 * Add to the list of supported versions to check against in
 	 * {@link ApiVersionStrategy#validateVersion} before raising

spring-webflux/src/main/java/org/springframework/web/reactive/config/WebFluxConfigurationSupport.java

@@ -246,10 +246,13 @@ public void configurePathMatching(PathMatchConfigurer configurer) {
 	}
 
 	@Bean
-	public RouterFunctionMapping routerFunctionMapping(ServerCodecConfigurer serverCodecConfigurer) {
+	public RouterFunctionMapping routerFunctionMapping(
+			ServerCodecConfigurer serverCodecConfigurer, @Nullable ApiVersionStrategy apiVersionStrategy) {
+
 		RouterFunctionMapping mapping = createRouterFunctionMapping();
 		mapping.setOrder(-1);  // go before RequestMappingHandlerMapping
 		mapping.setMessageReaders(serverCodecConfigurer.getReaders());
+		mapping.setApiVersionStrategy(apiVersionStrategy);
 		configureAbstractHandlerMapping(mapping, getPathMatchConfigurer());
 		return mapping;
 	}

spring-webflux/src/main/java/org/springframework/web/reactive/function/server/DefaultServerRequest.java

@@ -57,6 +57,7 @@
 import org.springframework.validation.BindingResult;
 import org.springframework.web.bind.WebDataBinder;
 import org.springframework.web.bind.support.WebExchangeDataBinder;
+import org.springframework.web.reactive.accept.ApiVersionStrategy;
 import org.springframework.web.reactive.function.BodyExtractor;
 import org.springframework.web.reactive.function.BodyExtractors;
 import org.springframework.web.reactive.function.UnsupportedMediaTypeException;
@@ -92,10 +93,20 @@ class DefaultServerRequest implements ServerRequest {
 
 	private final List<HttpMessageReader<?>> messageReaders;
 
+	private final @Nullable ApiVersionStrategy versionStrategy;
+
 
 	DefaultServerRequest(ServerWebExchange exchange, List<HttpMessageReader<?>> messageReaders) {
+		this(exchange, messageReaders, null);
+	}
+
+	DefaultServerRequest(
+			ServerWebExchange exchange, List<HttpMessageReader<?>> messageReaders,
+			@Nullable ApiVersionStrategy versionStrategy) {
+
 		this.exchange = exchange;
 		this.messageReaders = List.copyOf(messageReaders);
+		this.versionStrategy = versionStrategy;
 		this.headers = new DefaultHeaders();
 	}
 
@@ -162,6 +173,11 @@ public List<HttpMessageReader<?>> messageReaders() {
 		return this.messageReaders;
 	}
 
+	@Override
+	public @Nullable ApiVersionStrategy apiVersionStrategy() {
+		return this.versionStrategy;
+	}
+
 	@Override
 	public <T> T body(BodyExtractor<T, ? super ServerHttpRequest> extractor) {
 		return bodyInternal(extractor, Hints.from(Hints.LOG_PREFIX_HINT, exchange().getLogPrefix()));

spring-webflux/src/main/java/org/springframework/web/reactive/function/server/DefaultServerRequestBuilder.java

@@ -54,6 +54,7 @@
 import org.springframework.util.LinkedMultiValueMap;
 import org.springframework.util.MultiValueMap;
 import org.springframework.util.StringUtils;
+import org.springframework.web.reactive.accept.ApiVersionStrategy;
 import org.springframework.web.server.ServerWebExchange;
 import org.springframework.web.server.WebSession;
 import org.springframework.web.util.UriUtils;
@@ -69,6 +70,8 @@ class DefaultServerRequestBuilder implements ServerRequest.Builder {
 
 	private final List<HttpMessageReader<?>> messageReaders;
 
+	private final @Nullable ApiVersionStrategy versionStrategy;
+
 	private final ServerWebExchange exchange;
 
 	private HttpMethod method;
@@ -89,6 +92,7 @@ class DefaultServerRequestBuilder implements ServerRequest.Builder {
 	DefaultServerRequestBuilder(ServerRequest other) {
 		Assert.notNull(other, "ServerRequest must not be null");
 		this.messageReaders = other.messageReaders();
+		this.versionStrategy = other.apiVersionStrategy();
 		this.exchange = other.exchange();
 		this.method = other.method();
 		this.uri = other.uri();
@@ -195,7 +199,7 @@ public ServerRequest build() {
 				this.method, this.uri, this.contextPath, this.headers, this.cookies, this.body, this.attributes);
 		ServerWebExchange exchange = new DelegatingServerWebExchange(
 				serverHttpRequest, this.attributes, this.exchange, this.messageReaders);
-		return new DefaultServerRequest(exchange, this.messageReaders);
+		return new DefaultServerRequest(exchange, this.messageReaders, this.versionStrategy);
 	}
 
 

spring-webflux/src/main/java/org/springframework/web/reactive/function/server/RequestPredicates.java

@@ -54,6 +54,8 @@
 import org.springframework.util.MultiValueMap;
 import org.springframework.web.bind.WebDataBinder;
 import org.springframework.web.cors.reactive.CorsUtils;
+import org.springframework.web.reactive.HandlerMapping;
+import org.springframework.web.reactive.accept.ApiVersionStrategy;
 import org.springframework.web.reactive.function.BodyExtractor;
 import org.springframework.web.server.ServerWebExchange;
 import org.springframework.web.server.WebSession;
@@ -182,6 +184,25 @@ public static RequestPredicate accept(MediaType... mediaTypes) {
 		}
 	}
 
+	/**
+	 * {@code RequestPredicate} to match to the request API version extracted
+	 * from and parsed with the configured {@link ApiVersionStrategy}.
+	 * <p>The version may be one of the following:
+	 * <ul>
+	 * <li>Fixed version ("1.2") -- match this version only.
+	 * <li>Baseline version ("1.2+") -- match this and subsequent versions.
+	 * </ul>
+	 * <p>A baseline version allows n endpoint route to continue to work in
+	 * subsequent versions if it remains compatible until an incompatible change
+	 * eventually leads to the creation of a new route.
+	 * @param version the version to use
+	 * @return the created predicate instance
+	 * @since 7.0
+	 */
+	public static RequestPredicate version(Object version) {
+		return new ApiVersionPredicate(version);
+	}
+
 	/**
 	 * Return a {@code RequestPredicate} that matches if request's HTTP method is {@code GET}
 	 * and the given {@code pattern} matches against the request path.
@@ -390,6 +411,14 @@ public interface Visitor {
 		 */
 		void queryParam(String name, String value);
 
+		/**
+		 * Receive notification of an API version predicate. The version could
+		 * be fixed ("1.2") or baseline ("1.2+").
+		 * @param version the configured version
+		 * @since 7.0
+		 */
+		void version(String version);
+
 		/**
 		 * Receive first notification of a logical AND predicate.
 		 * The first subsequent notification will contain the left-hand side of the AND-predicate;
@@ -831,6 +860,69 @@ public String toString() {
 	}
 
 
+	private static class ApiVersionPredicate implements RequestPredicate {
+
+		private final String version;
+
+		private final boolean baselineVersion;
+
+		private @Nullable Comparable<?> parsedVersion;
+
+		public ApiVersionPredicate(Object version) {
+			if (version instanceof String s) {
+				this.baselineVersion = s.endsWith("+");
+				this.version = initVersion(s, this.baselineVersion);
+			}
+			else {
+				this.baselineVersion = false;
+				this.version = version.toString();
+				this.parsedVersion = (Comparable<?>) version;
+			}
+		}
+
+		private static String initVersion(String version, boolean baselineVersion) {
+			return (baselineVersion ? version.substring(0, version.length() - 1) : version);
+		}
+
+		@Override
+		public boolean test(ServerRequest request) {
+			if (this.parsedVersion == null) {
+				ApiVersionStrategy strategy = request.apiVersionStrategy();
+				Assert.state(strategy != null, "No ApiVersionStrategy to parse version with");
+				this.parsedVersion = strategy.parseVersion(this.version);
+			}
+
+			Comparable<?> requestVersion =
+					(Comparable<?>) request.attribute(HandlerMapping.API_VERSION_ATTRIBUTE).orElse(null);
+
+			if (requestVersion == null) {
+				traceMatch("Version", this.version, null, true);
+				return true;
+			}
+
+			int result = compareVersions(this.parsedVersion, requestVersion);
+			boolean match = (this.baselineVersion ? result <= 0 : result == 0);
+			traceMatch("Version", this.version, requestVersion, match);
+			return match;
+		}
+
+		@SuppressWarnings("unchecked")
+		private <V extends Comparable<V>> int compareVersions(Object v1, Object v2) {
+			return ((V) v1).compareTo((V) v2);
+		}
+
+		@Override
+		public void accept(Visitor visitor) {
+			visitor.version(this.version + (this.baselineVersion ? "+" : ""));
+		}
+
+		@Override
+		public String toString() {
+			return this.version;
+		}
+	}
+
+
 	@Deprecated(since = "7.0", forRemoval = true)
 	private static class PathExtensionPredicate implements RequestPredicate {
 
@@ -1189,6 +1281,11 @@ public List<HttpMessageReader<?>> messageReaders() {
 			return this.delegate.messageReaders();
 		}
 
+		@Override
+		public @Nullable ApiVersionStrategy apiVersionStrategy() {
+			return this.delegate.apiVersionStrategy();
+		}
+
 		@Override
 		public <T> T body(BodyExtractor<T, ? super ServerHttpRequest> extractor) {
 			return this.delegate.body(extractor);

spring-webflux/src/main/java/org/springframework/web/reactive/function/server/ServerRequest.java

@@ -49,6 +49,7 @@
 import org.springframework.util.MultiValueMap;
 import org.springframework.validation.BindException;
 import org.springframework.web.bind.WebDataBinder;
+import org.springframework.web.reactive.accept.ApiVersionStrategy;
 import org.springframework.web.reactive.function.BodyExtractor;
 import org.springframework.web.server.ServerWebExchange;
 import org.springframework.web.server.WebSession;
@@ -130,6 +131,12 @@ default RequestPath requestPath() {
 	 */
 	List<HttpMessageReader<?>> messageReaders();
 
+	/**
+	 * Return the configured {@link ApiVersionStrategy}, or {@code null}.
+	 * @since 7.0
+	 */
+	@Nullable ApiVersionStrategy apiVersionStrategy();
+
 	/**
 	 * Extract the body with the given {@code BodyExtractor}.
 	 * @param extractor the {@code BodyExtractor} that reads from the request
@@ -424,6 +431,23 @@ static ServerRequest create(ServerWebExchange exchange, List<HttpMessageReader<?
 		return new DefaultServerRequest(exchange, messageReaders);
 	}
 
+	/**
+	 * Create a new {@code ServerRequest} based on the given {@code ServerWebExchange} and
+	 * message readers.
+	 * @param exchange the exchange
+	 * @param messageReaders the message readers
+	 * @param versionStrategy a strategy to use to parse version
+	 * @return the created {@code ServerRequest}
+	 * @since 7.0
+	 */
+	static ServerRequest create(
+			ServerWebExchange exchange, List<HttpMessageReader<?>> messageReaders,
+			@Nullable ApiVersionStrategy versionStrategy) {
+
+		return new DefaultServerRequest(exchange, messageReaders, versionStrategy);
+	}
+
+
 	/**
 	 * Create a builder with the {@linkplain HttpMessageReader message readers},
 	 * method name, URI, headers, cookies, and attributes of the given request.

spring-webflux/src/main/java/org/springframework/web/reactive/function/server/ToStringVisitor.java

@@ -119,6 +119,11 @@ public void queryParam(String name, String value) {
 		this.builder.append(String.format("?%s == %s", name, value));
 	}
 
+	@Override
+	public void version(String version) {
+		this.builder.append(String.format("version: %s", version));
+	}
+
 	@Override
 	public void startAnd() {
 		this.builder.append('(');