4747import org .apache .hc .client5 .http .async .methods .SimpleHttpRequest ;
4848import org .apache .hc .client5 .http .async .methods .SimpleHttpResponse ;
4949import org .apache .hc .client5 .http .async .methods .SimpleRequestBuilder ;
50- import org .apache .hc .client5 .http .cache .CacheResponseStatus ;
5150import org .apache .hc .client5 .http .cache .HttpCacheContext ;
5251import org .apache .hc .client5 .http .cache .HttpCacheEntry ;
5352import 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