Correct LocalResponseCache behaviour w/ "no-cache", "must-revalidate", "max-age" and "no-store" directives

summary:

1. Inputs / expected result in order assuming Cache TTL configured to 120s
* Request contains `no-store` or `private`
  * (done) Cache is skipped without storing response and `Cache-Control` will come from upstream
* Request contains `no-cache`
  * The cached response is ignored by SCG dispatching to upstream(we cannot return 304 - imagine a client sends no-cache waiting for the server to revalidate and returns fresh data but instead it receives a bodyless response 304)
    * A) Fresh response coming from upstream is renewed in the SCG cache and `Cache-Control: max-age=120s`. Other clients will see max-age increased
    * B) Fresh response coming from upstream is not stored. Other clients will not be affected.
* Otherwise (ignoring `ETag`, `If-Modified-Since` and other request directives
  * if Response is not cached in SCG yet
    * `Cache-Control: max-age=120` (no-cache, no-store and must-revalidate doesn't make sense)
  * if Response is cached in SCG with remaining TTL = 30s
    * `Cache-Control: max-age=30` (no-cache, no-store and must-revalidate doesn't make sense)
  * if Response is cached in SCG with remaining TTL = 0s
    * `Cache-Control: max-age=0,no-cache,must-revalidate` (max-age=0+must-revalidate is equivalent to no-cache)

2. Revalidation is out of scope but it can be added in the future (ETag, If-Modified-Since, Modified-Since)

Author: spring-builds

README.adoc

@@ -6,7 +6,7 @@ Edit the files in the src/main/asciidoc/ directory instead.
 
 
 image::https://github.com/spring-cloud/spring-cloud-gateway/workflows/Build/badge.svg?style=svg["Actions Status", link="https://github.com/spring-cloud/spring-cloud-gateway/actions"]
-image::https://codecov.io/gh/spring-cloud/spring-cloud-gateway/branch/main/graph/badge.svg["Codecov", link="https://codecov.io/gh/spring-cloud/spring-cloud-gateway/branch/main"]
+image::https://codecov.io/gh/spring-cloud/spring-cloud-gateway/branch/4.0.x/graph/badge.svg["Codecov", link="https://codecov.io/gh/spring-cloud/spring-cloud-gateway/branch/main"]
 
 
 This project provides an API Gateway built on top of the Spring Ecosystem, including: Spring 6, Spring Boot 3 and Project Reactor. Spring Cloud Gateway aims to provide a simple, yet effective way to route to APIs and provide cross cutting concerns to them such as: security, monitoring/metrics, and resiliency.
@@ -109,7 +109,7 @@ from the `file` menu.
 
 == Contributing
 
-:spring-cloud-build-branch: 4.0.x
+:spring-cloud-build-branch: master
 
 Spring Cloud is released under the non-restrictive Apache 2.0 license,
 and follows a very standard Github development process, using Github
@@ -126,7 +126,7 @@ author credit if we do.  Active contributors might be asked to join the core tea
 given the ability to merge pull requests.
 
 === Code of Conduct
-This project adheres to the Contributor Covenant https://github.com/spring-cloud/spring-cloud-build/blob/master/docs/src/main/asciidoc/code-of-conduct.adoc[code of
+This project adheres to the Contributor Covenant https://github.com/spring-cloud/spring-cloud-build/blob/{spring-cloud-build-branch}/docs/src/main/asciidoc/code-of-conduct.adoc[code of
 conduct]. By participating, you  are expected to uphold this code. Please report
 unacceptable behavior to [email protected].
 
@@ -137,7 +137,7 @@ added after the original pull request but before a merge.
 * Use the Spring Framework code format conventions. If you use Eclipse
   you can import formatter settings using the
   `eclipse-code-formatter.xml` file from the
-  https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-dependencies-parent/eclipse-code-formatter.xml[Spring
+  https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/spring-cloud-dependencies-parent/eclipse-code-formatter.xml[Spring
   Cloud Build] project. If using IntelliJ, you can use the
   https://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter
   Plugin] to import the same file.

spring-cloud-gateway-server/src/main/java/org/springframework/cloud/gateway/config/LocalResponseCacheAutoConfiguration.java

@@ -65,7 +65,7 @@ public GlobalLocalResponseCacheGatewayFilter globalLocalResponseCacheGatewayFilt
 			@Qualifier(RESPONSE_CACHE_MANAGER_NAME) CacheManager cacheManager,
 			LocalResponseCacheProperties properties) {
 		return new GlobalLocalResponseCacheGatewayFilter(responseCacheManagerFactory, responseCache(cacheManager),
-				properties.getTimeToLive());
+				properties.getTimeToLive(), properties.getRequest());
 	}
 
 	@Bean(name = RESPONSE_CACHE_MANAGER_NAME)
@@ -78,7 +78,7 @@ public CacheManager gatewayCacheManager(LocalResponseCacheProperties cacheProper
 	public LocalResponseCacheGatewayFilterFactory localResponseCacheGatewayFilterFactory(
 			ResponseCacheManagerFactory responseCacheManagerFactory, LocalResponseCacheProperties properties) {
 		return new LocalResponseCacheGatewayFilterFactory(responseCacheManagerFactory, properties.getTimeToLive(),
-				properties.getSize());
+				properties.getSize(), properties.getRequest());
 	}
 
 	@Bean

spring-cloud-gateway-server/src/main/java/org/springframework/cloud/gateway/filter/factory/cache/GlobalLocalResponseCacheGatewayFilter.java

@@ -41,9 +41,9 @@ public class GlobalLocalResponseCacheGatewayFilter implements GlobalFilter, Orde
 	private final ResponseCacheGatewayFilter responseCacheGatewayFilter;
 
 	public GlobalLocalResponseCacheGatewayFilter(ResponseCacheManagerFactory cacheManagerFactory, Cache globalCache,
-			Duration configuredTimeToLive) {
+			Duration configuredTimeToLive, LocalResponseCacheRequestOptions requestOptions) {
 		responseCacheGatewayFilter = new ResponseCacheGatewayFilter(
-				cacheManagerFactory.create(globalCache, configuredTimeToLive));
+				cacheManagerFactory.create(globalCache, configuredTimeToLive, requestOptions));
 	}
 
 	@Override

spring-cloud-gateway-server/src/main/java/org/springframework/cloud/gateway/filter/factory/cache/LocalResponseCacheGatewayFilterFactory.java

@@ -30,11 +30,9 @@
 
 /**
  * {@link org.springframework.cloud.gateway.filter.factory.GatewayFilterFactory} of
- * {@link ResponseCacheGatewayFilter}.
- *
- * By default, a global cache (defined as properties in the application) is used. For
- * specific route configuration, parameters can be added following
- * {@link RouteCacheConfiguration} class.
+ * {@link ResponseCacheGatewayFilter}. By default, a global cache (defined as properties
+ * in the application) is used. For specific route configuration, parameters can be added
+ * following {@link RouteCacheConfiguration} class.
  *
  * @author Marta Medio
  * @author Ignacio Lozano
@@ -49,23 +47,21 @@ public class LocalResponseCacheGatewayFilterFactory
 	 */
 	public static final String LOCAL_RESPONSE_CACHE_FILTER_APPLIED = "LocalResponseCacheGatewayFilter-Applied";
 
-	private ResponseCacheManagerFactory cacheManagerFactory;
+	private final ResponseCacheManagerFactory cacheManagerFactory;
 
-	private Duration defaultTimeToLive;
+	private final Duration defaultTimeToLive;
 
-	private DataSize defaultSize;
+	private final DataSize defaultSize;
 
-	public LocalResponseCacheGatewayFilterFactory(ResponseCacheManagerFactory cacheManagerFactory,
-			Duration defaultTimeToLive) {
-		this(cacheManagerFactory, defaultTimeToLive, null);
-	}
+	private final LocalResponseCacheRequestOptions requestOptions;
 
 	public LocalResponseCacheGatewayFilterFactory(ResponseCacheManagerFactory cacheManagerFactory,
-			Duration defaultTimeToLive, DataSize defaultSize) {
+			Duration defaultTimeToLive, DataSize defaultSize, LocalResponseCacheRequestOptions requestOptions) {
 		super(RouteCacheConfiguration.class);
 		this.cacheManagerFactory = cacheManagerFactory;
 		this.defaultTimeToLive = defaultTimeToLive;
 		this.defaultSize = defaultSize;
+		this.requestOptions = requestOptions;
 	}
 
 	@Override
@@ -74,7 +70,8 @@ public GatewayFilter apply(RouteCacheConfiguration config) {
 
 		Cache routeCache = LocalResponseCacheAutoConfiguration.createGatewayCacheManager(cacheProperties)
 				.getCache(config.getRouteId() + "-cache");
-		return new ResponseCacheGatewayFilter(cacheManagerFactory.create(routeCache, cacheProperties.getTimeToLive()));
+		return new ResponseCacheGatewayFilter(
+				cacheManagerFactory.create(routeCache, cacheProperties.getTimeToLive(), requestOptions));
 
 	}
 

spring-cloud-gateway-server/src/main/java/org/springframework/cloud/gateway/filter/factory/cache/LocalResponseCacheProperties.java

@@ -40,6 +40,8 @@ public class LocalResponseCacheProperties {
 
 	private Duration timeToLive;
 
+	private LocalResponseCacheRequestOptions request = new LocalResponseCacheRequestOptions();
+
 	public DataSize getSize() {
 		return size;
 	}
@@ -64,9 +66,18 @@ public void setTimeToLive(Duration timeToLive) {
 		this.timeToLive = timeToLive;
 	}
 
+	public LocalResponseCacheRequestOptions getRequest() {
+		return request;
+	}
+
+	public void setRequest(LocalResponseCacheRequestOptions request) {
+		this.request = request;
+	}
+
 	@Override
 	public String toString() {
-		return "LocalResponseCacheProperties{" + "timeToLive=" + getTimeToLive() + '\'' + ", size='" + getSize() + '}';
+		return "LocalResponseCacheProperties{" + "size=" + size + ", timeToLive=" + timeToLive + ", request=" + request
+				+ '}';
 	}
 
 }

spring-cloud-gateway-server/src/main/java/org/springframework/cloud/gateway/filter/factory/cache/LocalResponseCacheRequestOptions.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2013-2023 the original author or authors.
+ *
+ * Licensed 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
+ *
+ *      https://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.springframework.cloud.gateway.filter.factory.cache;
+
+public class LocalResponseCacheRequestOptions {
+
+	private RequestNoCacheDirectiveStrategy noCache = RequestNoCacheDirectiveStrategy.SKIP_UPDATE_CACHE_ENTRY;
+
+	public RequestNoCacheDirectiveStrategy getNoCache() {
+		return noCache;
+	}
+
+	public void setNoCache(RequestNoCacheDirectiveStrategy noCache) {
+		this.noCache = noCache;
+	}
+
+}

spring-cloud-gateway-server/src/main/java/org/springframework/cloud/gateway/filter/factory/cache/LocalResponseCacheUtils.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2013-2020 the original author or authors.
+ *
+ * Licensed 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
+ *
+ *      https://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.springframework.cloud.gateway.filter.factory.cache;
+
+import java.util.Optional;
+
+import org.springframework.http.server.reactive.ServerHttpRequest;
+
+public final class LocalResponseCacheUtils {
+
+	private LocalResponseCacheUtils() {
+	}
+
+	public static boolean isNoCacheRequest(ServerHttpRequest request) {
+		return Optional.ofNullable(request.getHeaders().getCacheControl())
+				.filter(cc -> cc.matches(".*(\s|,|^)no-cache(\\s|,|$).*")).isPresent();
+	}
+
+}

spring-cloud-gateway-server/src/main/java/org/springframework/cloud/gateway/filter/factory/cache/RequestNoCacheDirectiveStrategy.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2013-2022 the original author or authors.
+ *
+ * Licensed 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
+ *
+ *      https://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.springframework.cloud.gateway.filter.factory.cache;
+
+/**
+ * When client sends "no-cache" directive in "Cache-Control" header, the response should
+ * be re-validated from upstream. There are several strategies that indicates what to do
+ * with the new fresh response.
+ */
+public enum RequestNoCacheDirectiveStrategy {
+
+	/**
+	 * Update the cache entry by the fresh response coming from upstream with a new time
+	 * to live.
+	 */
+	UPDATE_CACHE_ENTRY,
+	/**
+	 * Skip the update. The client will receive the fresh response, other clients will
+	 * receive the old entry in cache.
+	 */
+	SKIP_UPDATE_CACHE_ENTRY
+
+}

spring-cloud-gateway-server/src/main/java/org/springframework/cloud/gateway/filter/factory/cache/ResponseCacheGatewayFilter.java

@@ -66,7 +66,7 @@ public int getOrder() {
 
 	private Mono<Void> filterWithCache(ServerWebExchange exchange, GatewayFilterChain chain) {
 		final String metadataKey = responseCacheManager.resolveMetadataKey(exchange);
-		Optional<CachedResponse> cached = responseCacheManager.getFromCache(exchange.getRequest(), metadataKey);
+		Optional<CachedResponse> cached = getCachedResponse(exchange, metadataKey);
 
 		if (cached.isPresent()) {
 			return responseCacheManager.processFromCache(exchange, metadataKey, cached.get());
@@ -77,6 +77,22 @@ private Mono<Void> filterWithCache(ServerWebExchange exchange, GatewayFilterChai
 		}
 	}
 
+	private Optional<CachedResponse> getCachedResponse(ServerWebExchange exchange, String metadataKey) {
+		Optional<CachedResponse> cached;
+		if (shouldRevalidate(exchange)) {
+			cached = Optional.empty();
+		}
+		else {
+			cached = responseCacheManager.getFromCache(exchange.getRequest(), metadataKey);
+		}
+
+		return cached;
+	}
+
+	private boolean shouldRevalidate(ServerWebExchange exchange) {
+		return LocalResponseCacheUtils.isNoCacheRequest(exchange.getRequest());
+	}
+
 	private class CachingResponseDecorator extends ServerHttpResponseDecorator {
 
 		private final String metadataKey;
@@ -94,7 +110,8 @@ public Mono<Void> writeWith(Publisher<? extends DataBuffer> body) {
 			final ServerHttpResponse response = exchange.getResponse();
 
 			Flux<DataBuffer> decoratedBody;
-			if (responseCacheManager.isResponseCacheable(response)) {
+			if (responseCacheManager.isResponseCacheable(response)
+					&& !responseCacheManager.isNoCacheRequestWithoutUpdate(exchange.getRequest())) {
 				decoratedBody = responseCacheManager.processFromUpstream(metadataKey, exchange, Flux.from(body));
 			}
 			else {

spring-cloud-gateway-server/src/main/java/org/springframework/cloud/gateway/filter/factory/cache/ResponseCacheManager.java

@@ -32,6 +32,7 @@
 import org.springframework.cache.Cache;
 import org.springframework.cloud.gateway.filter.factory.cache.keygenerator.CacheKeyGenerator;
 import org.springframework.cloud.gateway.filter.factory.cache.postprocessor.AfterCacheExchangeMutator;
+import org.springframework.cloud.gateway.filter.factory.cache.postprocessor.SetCacheDirectivesByMaxAgeAfterCacheExchangeMutator;
 import org.springframework.cloud.gateway.filter.factory.cache.postprocessor.SetMaxAgeHeaderAfterCacheExchangeMutator;
 import org.springframework.cloud.gateway.filter.factory.cache.postprocessor.SetResponseHeadersAfterCacheExchangeMutator;
 import org.springframework.cloud.gateway.filter.factory.cache.postprocessor.SetStatusCodeAfterCacheExchangeMutator;
@@ -63,12 +64,23 @@ public class ResponseCacheManager {
 
 	private final Cache cache;
 
-	public ResponseCacheManager(CacheKeyGenerator cacheKeyGenerator, Cache cache, Duration configuredTimeToLive) {
+	private final boolean ignoreNoCacheUpdate;
+
+	public ResponseCacheManager(CacheKeyGenerator cacheKeyGenerator, Cache cache, Duration configuredTimeToLive,
+			LocalResponseCacheRequestOptions requestOptions) {
 		this.cacheKeyGenerator = cacheKeyGenerator;
 		this.cache = cache;
+		this.ignoreNoCacheUpdate = isSkipNoCacheUpdateActive(requestOptions);
 		this.afterCacheExchangeMutators = List.of(new SetResponseHeadersAfterCacheExchangeMutator(),
 				new SetStatusCodeAfterCacheExchangeMutator(),
-				new SetMaxAgeHeaderAfterCacheExchangeMutator(configuredTimeToLive, Clock.systemDefaultZone()));
+				new SetMaxAgeHeaderAfterCacheExchangeMutator(configuredTimeToLive, Clock.systemDefaultZone(),
+						ignoreNoCacheUpdate),
+				new SetCacheDirectivesByMaxAgeAfterCacheExchangeMutator());
+	}
+
+	private static boolean isSkipNoCacheUpdateActive(LocalResponseCacheRequestOptions requestOptions) {
+		return Optional.ofNullable(requestOptions).map(LocalResponseCacheRequestOptions::getNoCache)
+				.filter(RequestNoCacheDirectiveStrategy.SKIP_UPDATE_CACHE_ENTRY::equals).isPresent();
 	}
 
 	private static final List<HttpStatusCode> statusesToCache = Arrays.asList(HttpStatus.OK, HttpStatus.PARTIAL_CONTENT,
@@ -132,13 +144,8 @@ Mono<Void> processFromCache(ServerWebExchange exchange, String metadataKey, Cach
 		afterCacheExchangeMutators.forEach(processor -> processor.accept(exchange, cachedResponse));
 		saveMetadataInCache(metadataKey, new CachedResponseMetadata(cachedResponse.headers().getVary()));
 
-		if (HttpStatus.NOT_MODIFIED.equals(response.getStatusCode())) {
-			return response.writeWith(Mono.empty());
-		}
-		else {
-			return response.writeWith(
-					Flux.fromIterable(cachedResponse.body()).map(data -> response.bufferFactory().wrap(data)));
-		}
+		return response
+				.writeWith(Flux.fromIterable(cachedResponse.body()).map(data -> response.bufferFactory().wrap(data)));
 	}
 
 	private CachedResponseMetadata retrieveMetadata(String metadataKey) {
@@ -157,6 +164,10 @@ boolean isResponseCacheable(ServerHttpResponse response) {
 		return isStatusCodeToCache(response) && isCacheControlAllowed(response) && !isVaryWildcard(response);
 	}
 
+	boolean isNoCacheRequestWithoutUpdate(ServerHttpRequest request) {
+		return LocalResponseCacheUtils.isNoCacheRequest(request) && ignoreNoCacheUpdate;
+	}
+
 	private boolean isStatusCodeToCache(ServerHttpResponse response) {
 		return statusesToCache.contains(response.getStatusCode());
 	}