Skip to content

Commit 0fcb4cf

Browse files
committed
RFC 9211: optional Cache-Status response header
Adds optional support for the RFC 9211 Cache-Status response header. When enabled through CacheConfig the caching executors record how each exchange was handled in a per-exchange CacheStatus, and CacheStatusHeaderGenerator serialises it into the Cache-Status header. CacheStatus is the single source of truth for the disposition of an exchange. The coarse CacheResponseStatus exposed on HttpCacheContext is now derived from it on the fly instead of being stored as a separate attribute, so the two can no longer drift apart. A locally generated response and a stale response served by the module under stale-while-revalidate or stale-if-error map to a module response, an internal error that falls back to the origin maps to a failure, a successful revalidation of a stored entry maps to validated, a response served from a stored entry to a hit, and any other forwarded response to a miss.
1 parent a890ec7 commit 0fcb4cf

12 files changed

Lines changed: 1002 additions & 54 deletions

File tree

‎httpclient5-cache/src/main/java/org/apache/hc/client5/http/cache/HttpCacheContext.java‎

Lines changed: 36 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@
4242
import org.apache.hc.client5.http.cookie.CookieSpec;
4343
import org.apache.hc.client5.http.cookie.CookieSpecFactory;
4444
import org.apache.hc.client5.http.cookie.CookieStore;
45+
import org.apache.hc.client5.http.impl.cache.CacheStatus;
4546
import org.apache.hc.client5.http.protocol.HttpClientContext;
4647
import org.apache.hc.client5.http.protocol.RedirectLocations;
4748
import org.apache.hc.core5.annotation.Internal;
@@ -73,6 +74,7 @@ public class HttpCacheContext extends HttpClientContext {
7374
static final String REQUEST_CACHE_CONTROL = "http.cache.request-control";
7475
static final String RESPONSE_CACHE_CONTROL = "http.cache.response-control";
7576
static final String CACHE_ENTRY = "http.cache.entry";
77+
static final String CACHE_STATUS = "http.cache.status";
7678

7779
/**
7880
* @deprecated Use {@link #castOrCreate(HttpContext)}.
@@ -118,10 +120,10 @@ public static HttpCacheContext create() {
118120
return new HttpCacheContext();
119121
}
120122

121-
private CacheResponseStatus responseStatus;
122123
private RequestCacheControl requestCacheControl;
123124
private ResponseCacheControl responseCacheControl;
124125
private HttpCacheEntry cacheEntry;
126+
private CacheStatus cacheStatus;
125127

126128
public HttpCacheContext(final HttpContext context) {
127129
super(context);
@@ -133,20 +135,12 @@ public HttpCacheContext() {
133135

134136
/**
135137
* Represents an outcome of the cache operation and the way the response has been
136-
* generated.
137-
* <p>
138-
* This context attribute is expected to be populated by the protocol handler.
138+
* generated. The value is derived on the fly from the {@link CacheStatus} recorded for the
139+
* exchange, which is the single source of truth for how the request was handled.
139140
*/
140141
public CacheResponseStatus getCacheResponseStatus() {
141-
return responseStatus;
142-
}
143-
144-
/**
145-
* @since 5.4
146-
*/
147-
@Internal
148-
public void setCacheResponseStatus(final CacheResponseStatus responseStatus) {
149-
this.responseStatus = responseStatus;
142+
final CacheStatus status = getCacheStatus();
143+
return status != null ? status.toResponseStatus() : null;
150144
}
151145

152146
/**
@@ -228,6 +222,25 @@ public void setCacheEntry(final HttpCacheEntry cacheEntry) {
228222
this.cacheEntry = cacheEntry;
229223
}
230224

225+
/**
226+
* Records how the cache handled the current exchange, used to render the RFC 9211
227+
* {@code Cache-Status} response header.
228+
*
229+
* @since 5.7
230+
*/
231+
@Internal
232+
public CacheStatus getCacheStatus() {
233+
return cacheStatus;
234+
}
235+
236+
/**
237+
* @since 5.7
238+
*/
239+
@Internal
240+
public void setCacheStatus(final CacheStatus cacheStatus) {
241+
this.cacheStatus = cacheStatus;
242+
}
243+
231244
/**
232245
* Internal adaptor class that delegates all its method calls to {@link HttpClientContext}.
233246
* To be removed in the future.
@@ -243,16 +256,6 @@ static class Delegate extends HttpCacheContext {
243256
this.clientContext = clientContext;
244257
}
245258

246-
@Override
247-
public CacheResponseStatus getCacheResponseStatus() {
248-
return clientContext.getAttribute(CACHE_RESPONSE_STATUS, CacheResponseStatus.class);
249-
}
250-
251-
@Override
252-
public void setCacheResponseStatus(final CacheResponseStatus responseStatus) {
253-
clientContext.setAttribute(CACHE_RESPONSE_STATUS, responseStatus);
254-
}
255-
256259
@Override
257260
public RequestCacheControl getRequestCacheControl() {
258261
return clientContext.getAttribute(REQUEST_CACHE_CONTROL, RequestCacheControl.class);
@@ -283,6 +286,16 @@ public void setCacheEntry(final HttpCacheEntry cacheEntry) {
283286
clientContext.setAttribute(CACHE_ENTRY, cacheEntry);
284287
}
285288

289+
@Override
290+
public CacheStatus getCacheStatus() {
291+
return clientContext.getAttribute(CACHE_STATUS, CacheStatus.class);
292+
}
293+
294+
@Override
295+
public void setCacheStatus(final CacheStatus cacheStatus) {
296+
clientContext.setAttribute(CACHE_STATUS, cacheStatus);
297+
}
298+
286299
@Override
287300
public RouteInfo getHttpRoute() {
288301
return clientContext.getHttpRoute();

‎httpclient5-cache/src/main/java/org/apache/hc/client5/http/impl/cache/AsyncCachingExec.java‎

Lines changed: 46 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,6 @@
4747
import org.apache.hc.client5.http.async.methods.SimpleHttpRequest;
4848
import org.apache.hc.client5.http.async.methods.SimpleHttpResponse;
4949
import org.apache.hc.client5.http.async.methods.SimpleRequestBuilder;
50-
import org.apache.hc.client5.http.cache.CacheResponseStatus;
5150
import org.apache.hc.client5.http.cache.HttpCacheContext;
5251
import org.apache.hc.client5.http.cache.HttpCacheEntry;
5352
import org.apache.hc.client5.http.cache.RequestCacheControl;
@@ -215,6 +214,7 @@ public AsyncDataConsumer handleResponse(
215214
final EntityDetails entityDetails) throws HttpException, IOException {
216215
context.setRequest(request);
217216
context.setResponse(response);
217+
applyCacheStatus(response, HttpCacheContext.cast(context));
218218
return asyncExecCallback.handleResponse(response, entityDetails);
219219
}
220220

@@ -253,11 +253,13 @@ public void doExecute(
253253
LOG.debug("{} request via cache: {} {}", exchangeId, request.getMethod(), request.getRequestUri());
254254
}
255255

256-
context.setCacheResponseStatus(CacheResponseStatus.CACHE_MISS);
257256
context.setCacheEntry(null);
257+
final CacheStatus cacheStatus = new CacheStatus();
258+
cacheStatus.forward(CacheStatus.ForwardReason.MISS);
259+
context.setCacheStatus(cacheStatus);
258260

259261
if (clientRequestsOurOptions(request)) {
260-
context.setCacheResponseStatus(CacheResponseStatus.CACHE_MODULE_RESPONSE);
262+
cacheStatus.suppress();
261263
triggerResponse(SimpleHttpResponse.create(HttpStatus.SC_NOT_IMPLEMENTED), scope, asyncExecCallback);
262264
return;
263265
}
@@ -267,6 +269,12 @@ public void doExecute(
267269
if (LOG.isDebugEnabled()) {
268270
LOG.debug("{} request cannot be correctly executed and cached", exchangeId);
269271
}
272+
// The request could not be represented for caching. A cache-supported method whose
273+
// body/representation prevents processing is a bypass; any other method is not handled
274+
// by the cache at all.
275+
cacheStatus.forward(CacheSupport.isMethodCacheSupported(request.getMethod())
276+
? CacheStatus.ForwardReason.BYPASS
277+
: CacheStatus.ForwardReason.METHOD);
270278
chain.proceed(request, entityProducer, scope, asyncExecCallback);
271279
return;
272280
}
@@ -288,6 +296,11 @@ public void doExecute(
288296
if (LOG.isDebugEnabled()) {
289297
LOG.debug("{} request cannot be served from cache", exchangeId);
290298
}
299+
// The cache lookup is bypassed here (non-cacheable method, or a no-store / no-cache
300+
// request), so no stored response was ever selected; this is not fwd=request.
301+
cacheStatus.forward(CacheSupport.isMethodCacheSupported(cacheRequest.getMethod())
302+
? CacheStatus.ForwardReason.BYPASS
303+
: CacheStatus.ForwardReason.METHOD);
291304
callChain(cacheRequest, scope, chain, asyncExecCallback);
292305
return;
293306
}
@@ -937,7 +950,6 @@ private void handleCacheHit(
937950
LOG.debug("{} cache hit: {} {}", exchangeId, request.getMethod(), request.getRequestUri());
938951
}
939952

940-
context.setCacheResponseStatus(CacheResponseStatus.CACHE_HIT);
941953
cacheHits.getAndIncrement();
942954

943955
final Instant now = getCurrentDate();
@@ -953,17 +965,18 @@ private void handleCacheHit(
953965
try {
954966
final SimpleHttpResponse cacheResponse = generateCachedResponse(request, hit.entry, now);
955967
context.setCacheEntry(hit.entry);
968+
cacheStatus(context).hit();
956969
triggerResponse(cacheResponse, scope, asyncExecCallback);
957970
} catch (final ResourceIOException ex) {
958971
if (requestCacheControl.isOnlyIfCached()) {
959972
if (LOG.isDebugEnabled()) {
960973
LOG.debug("{} request marked only-if-cached", exchangeId);
961974
}
962-
context.setCacheResponseStatus(CacheResponseStatus.CACHE_MODULE_RESPONSE);
975+
cacheStatus(context).suppress();
963976
final SimpleHttpResponse cacheResponse = generateGatewayTimeout();
964977
triggerResponse(cacheResponse, scope, asyncExecCallback);
965978
} else {
966-
context.setCacheResponseStatus(CacheResponseStatus.FAILURE);
979+
cacheStatus(context).fail();
967980
callChain(request, scope, chain, asyncExecCallback);
968981
}
969982
}
@@ -972,7 +985,7 @@ private void handleCacheHit(
972985
if (LOG.isDebugEnabled()) {
973986
LOG.debug("{} cache entry not is not fresh and only-if-cached requested", exchangeId);
974987
}
975-
context.setCacheResponseStatus(CacheResponseStatus.CACHE_MODULE_RESPONSE);
988+
cacheStatus(context).suppress();
976989
final SimpleHttpResponse cacheResponse = generateGatewayTimeout();
977990
triggerResponse(cacheResponse, scope, asyncExecCallback);
978991
} else if (cacheSuitability == CacheSuitability.MISMATCH) {
@@ -989,6 +1002,16 @@ private void handleCacheHit(
9891002
if (LOG.isDebugEnabled()) {
9901003
LOG.debug("{} revalidation required; revalidating cache entry", exchangeId);
9911004
}
1005+
// fwd=request only when a still-fresh stored response could not be used because of
1006+
// request semantics; a stale entry that must be revalidated is fwd=stale.
1007+
final boolean stale = validityPolicy.getCurrentAge(hit.entry, now)
1008+
.compareTo(validityPolicy.getFreshnessLifetime(responseCacheControl, hit.entry)) >= 0;
1009+
final boolean requestForced = requestCacheControl.isNoCache()
1010+
|| requestCacheControl.getMaxAge() >= 0
1011+
|| requestCacheControl.getMinFresh() >= 0;
1012+
cacheStatus(context).forward(!stale && requestForced
1013+
? CacheStatus.ForwardReason.REQUEST
1014+
: CacheStatus.ForwardReason.STALE);
9921015
revalidateCacheEntryWithoutFallback(requestCacheControl, responseCacheControl, hit, target, request, scope, chain, asyncExecCallback);
9931016
} else if (cacheSuitability == CacheSuitability.STALE_WHILE_REVALIDATED) {
9941017
if (cacheRevalidator != null) {
@@ -1014,9 +1037,10 @@ private void handleCacheHit(
10141037
hit.getEntryKey(),
10151038
asyncExecCallback,
10161039
c -> revalidateCacheEntry(requestCacheControl, responseCacheControl, hit, target, request, fork, chain, c));
1017-
context.setCacheResponseStatus(CacheResponseStatus.CACHE_MODULE_RESPONSE);
10181040
final SimpleHttpResponse cacheResponse = responseGenerator.generateResponse(request, hit.entry);
10191041
context.setCacheEntry(hit.entry);
1042+
cacheStatus(context).hit();
1043+
cacheStatus(context).moduleResponse();
10201044
triggerResponse(cacheResponse, scope, asyncExecCallback);
10211045
} catch (final IOException ex) {
10221046
asyncExecCallback.failed(ex);
@@ -1098,7 +1122,7 @@ public void cancelled() {
10981122
AsyncExecCallback evaluateResponse(final HttpResponse backendResponse, final Instant responseDate) {
10991123
final int statusCode = backendResponse.getCode();
11001124
if (statusCode == HttpStatus.SC_NOT_MODIFIED || statusCode == HttpStatus.SC_OK) {
1101-
context.setCacheResponseStatus(CacheResponseStatus.VALIDATED);
1125+
cacheStatus(context).forwardStatus(statusCode);
11021126
cacheUpdates.getAndIncrement();
11031127
}
11041128
if (statusCode == HttpStatus.SC_NOT_MODIFIED) {
@@ -1241,7 +1265,7 @@ public void failed(final Exception cause) {
12411265
LOG.debug("{} I/O error while revalidating cache entry", exchangeId, cause);
12421266
}
12431267
final SimpleHttpResponse cacheResponse = generateGatewayTimeout();
1244-
context.setCacheResponseStatus(CacheResponseStatus.CACHE_MODULE_RESPONSE);
1268+
cacheStatus(context).suppress();
12451269
triggerResponse(cacheResponse, scope, asyncExecCallback);
12461270
} else {
12471271
asyncExecCallback.failed(cause);
@@ -1262,6 +1286,7 @@ void revalidateCacheEntryWithFallback(
12621286
final AsyncExecCallback asyncExecCallback) {
12631287
final String exchangeId = scope.exchangeId;
12641288
final HttpCacheContext context = HttpCacheContext.cast(scope.clientContext);
1289+
cacheStatus(context).forward(CacheStatus.ForwardReason.STALE);
12651290
revalidateCacheEntry(requestCacheControl, responseCacheControl, hit, target, request, scope, chain, new AsyncExecCallback() {
12661291

12671292
private final AtomicReference<HttpResponse> committed = new AtomicReference<>();
@@ -1274,6 +1299,8 @@ public AsyncDataConsumer handleResponse(final HttpResponse response, final Entit
12741299
if (LOG.isDebugEnabled()) {
12751300
LOG.debug("{} serving stale response due to {} status and stale-if-error enabled", exchangeId, status);
12761301
}
1302+
cacheStatus(context).forwardStatus(status);
1303+
cacheStatus(context).moduleResponse();
12771304
return null;
12781305
}
12791306
committed.set(response);
@@ -1290,7 +1317,6 @@ public void completed() {
12901317
final HttpResponse response = committed.get();
12911318
if (response == null) {
12921319
try {
1293-
context.setCacheResponseStatus(CacheResponseStatus.CACHE_MODULE_RESPONSE);
12941320
final SimpleHttpResponse cacheResponse = responseGenerator.generateResponse(request, hit.entry);
12951321
context.setCacheEntry(hit.entry);
12961322
triggerResponse(cacheResponse, scope, asyncExecCallback);
@@ -1309,7 +1335,6 @@ public void failed(final Exception cause) {
13091335
if (LOG.isDebugEnabled()) {
13101336
LOG.debug("{} I/O error while revalidating cache entry", exchangeId, cause);
13111337
}
1312-
context.setCacheResponseStatus(CacheResponseStatus.CACHE_MODULE_RESPONSE);
13131338
if (cause instanceof IOException &&
13141339
suitabilityChecker.isSuitableIfError(requestCacheControl, responseCacheControl, hit.entry, getCurrentDate())) {
13151340
if (LOG.isDebugEnabled()) {
@@ -1318,11 +1343,13 @@ public void failed(final Exception cause) {
13181343
try {
13191344
final SimpleHttpResponse cacheResponse = responseGenerator.generateResponse(request, hit.entry);
13201345
context.setCacheEntry(hit.entry);
1346+
cacheStatus(context).moduleResponse();
13211347
triggerResponse(cacheResponse, scope, asyncExecCallback);
13221348
} catch (final IOException ex) {
13231349
asyncExecCallback.failed(cause);
13241350
}
13251351
} else {
1352+
cacheStatus(context).suppress();
13261353
final SimpleHttpResponse cacheResponse = generateGatewayTimeout();
13271354
triggerResponse(cacheResponse, scope, asyncExecCallback);
13281355
}
@@ -1354,7 +1381,7 @@ private void handleCacheMiss(
13541381
LOG.debug("{} request marked only-if-cached", exchangeId);
13551382
}
13561383
final HttpCacheContext context = HttpCacheContext.cast(scope.clientContext);
1357-
context.setCacheResponseStatus(CacheResponseStatus.CACHE_MODULE_RESPONSE);
1384+
cacheStatus(context).suppress();
13581385
final SimpleHttpResponse cacheResponse = generateGatewayTimeout();
13591386
triggerResponse(cacheResponse, scope, asyncExecCallback);
13601387
return;
@@ -1370,6 +1397,7 @@ public void completed(final Collection<CacheHit> variants) {
13701397
if (variants != null && !variants.isEmpty()) {
13711398
negotiateResponseFromVariants(requestCacheControl, target, request, scope, chain, asyncExecCallback, variants);
13721399
} else {
1400+
cacheStatus(HttpCacheContext.cast(scope.clientContext)).forward(CacheStatus.ForwardReason.VARY_MISS);
13731401
callBackend(requestCacheControl, target, request, scope, chain, asyncExecCallback);
13741402
}
13751403
}
@@ -1386,6 +1414,9 @@ public void cancelled() {
13861414

13871415
}));
13881416
} else {
1417+
cacheStatus(HttpCacheContext.cast(scope.clientContext)).forward(partialMatch != null
1418+
? CacheStatus.ForwardReason.VARY_MISS
1419+
: CacheStatus.ForwardReason.URI_MISS);
13891420
callBackend(requestCacheControl, target, request, scope, chain, asyncExecCallback);
13901421
}
13911422
}
@@ -1400,6 +1431,7 @@ void negotiateResponseFromVariants(
14001431
final Collection<CacheHit> variants) {
14011432
final String exchangeId = scope.exchangeId;
14021433
final CancellableDependency operation = scope.cancellableDependency;
1434+
cacheStatus(HttpCacheContext.cast(scope.clientContext)).forward(CacheStatus.ForwardReason.VARY_MISS);
14031435
final Map<ETag, CacheHit> variantMap = new HashMap<>();
14041436
for (final CacheHit variant : variants) {
14051437
final ETag eTag = variant.entry.getETag();
@@ -1419,8 +1451,8 @@ void negotiateResponseFromVariants(
14191451

14201452
void updateVariantCacheEntry(final HttpResponse backendResponse, final Instant responseDate, final CacheHit match) {
14211453
final HttpCacheContext context = HttpCacheContext.cast(scope.clientContext);
1422-
context.setCacheResponseStatus(CacheResponseStatus.VALIDATED);
14231454
cacheUpdates.getAndIncrement();
1455+
cacheStatus(context).forwardStatus(HttpStatus.SC_NOT_MODIFIED);
14241456

14251457
operation.setDependency(responseCache.storeFromNegotiated(
14261458
match,

0 commit comments

Comments
 (0)