vendor/symfony/http-kernel/HttpCache/HttpCache.php line 428

  1. <?php
  3. /*
  4.  * This file is part of the Symfony package.
  5.  *
  6.  * (c) Fabien Potencier <fabien@symfony.com>
  7.  *
  8.  * For the full copyright and license information, please view the LICENSE
  9.  * file that was distributed with this source code.
  10.  */
  12. /*
  13.  * This code is partially based on the Rack-Cache library by Ryan Tomayko,
  14.  * which is released under the MIT license.
  15.  * (based on commit 02d2b48d75bcb63cf1c0c7149c077ad256542801)
  16.  */
  18. namespace Symfony\Component\HttpKernel\HttpCache;
  20. use Symfony\Component\HttpFoundation\Request;
  21. use Symfony\Component\HttpFoundation\Response;
  22. use Symfony\Component\HttpKernel\HttpKernelInterface;
  23. use Symfony\Component\HttpKernel\TerminableInterface;
  25. /**
  26.  * Cache provides HTTP caching.
  27.  *
  28.  * @author Fabien Potencier <fabien@symfony.com>
  29.  */
  30. class HttpCache implements HttpKernelInterface, TerminableInterface
  31. {
  32.     public const BODY_EVAL_BOUNDARY_LENGTH = 24;
  34.     private HttpKernelInterface $kernel;
  35.     private StoreInterface $store;
  36.     private Request $request;
  37.     private ?SurrogateInterface $surrogate;
  38.     private ?ResponseCacheStrategyInterface $surrogateCacheStrategy = null;
  39.     private array $options = [];
  40.     private array $traces = [];
  42.     /**
  43.      * Constructor.
  44.      *
  45.      * The available options are:
  46.      *
  47.      *   * debug                  If true, exceptions are thrown when things go wrong. Otherwise, the cache
  48.      *                            will try to carry on and deliver a meaningful response.
  49.      *
  50.      *   * trace_level            May be one of 'none', 'short' and 'full'. For 'short', a concise trace of the
  51.      *                            main request will be added as an HTTP header. 'full' will add traces for all
  52.      *                            requests (including ESI subrequests). (default: 'full' if in debug; 'none' otherwise)
  53.      *
  54.      *   * trace_header           Header name to use for traces. (default: X-Symfony-Cache)
  55.      *
  56.      *   * default_ttl            The number of seconds that a cache entry should be considered
  57.      *                            fresh when no explicit freshness information is provided in
  58.      *                            a response. Explicit Cache-Control or Expires headers
  59.      *                            override this value. (default: 0)
  60.      *
  61.      *   * private_headers        Set of request headers that trigger "private" cache-control behavior
  62.      *                            on responses that don't explicitly state whether the response is
  63.      *                            public or private via a Cache-Control directive. (default: Authorization and Cookie)
  64.      *
  65.      *   * allow_reload           Specifies whether the client can force a cache reload by including a
  66.      *                            Cache-Control "no-cache" directive in the request. Set it to ``true``
  67.      *                            for compliance with RFC 2616. (default: false)
  68.      *
  69.      *   * allow_revalidate       Specifies whether the client can force a cache revalidate by including
  70.      *                            a Cache-Control "max-age=0" directive in the request. Set it to ``true``
  71.      *                            for compliance with RFC 2616. (default: false)
  72.      *
  73.      *   * stale_while_revalidate Specifies the default number of seconds (the granularity is the second as the
  74.      *                            Response TTL precision is a second) during which the cache can immediately return
  75.      *                            a stale response while it revalidates it in the background (default: 2).
  76.      *                            This setting is overridden by the stale-while-revalidate HTTP Cache-Control
  77.      *                            extension (see RFC 5861).
  78.      *
  79.      *   * stale_if_error         Specifies the default number of seconds (the granularity is the second) during which
  80.      *                            the cache can serve a stale response when an error is encountered (default: 60).
  81.      *                            This setting is overridden by the stale-if-error HTTP Cache-Control extension
  82.      *                            (see RFC 5861).
  83.      *
  84.      *   * terminate_on_cache_hit Specifies if the kernel.terminate event should be dispatched even when the cache
  85.      *                            was hit (default: true).
  86.      *                            Unless your application needs to process events on cache hits, it is recommended
  87.      *                            to set this to false to avoid having to bootstrap the Symfony framework on a cache hit.
  88.      */
  89.     public function __construct(HttpKernelInterface $kernel, StoreInterface $store, SurrogateInterface $surrogate = null, array $options = [])
  90.     {
  91.         $this->store = $store;
  92.         $this->kernel = $kernel;
  93.         $this->surrogate = $surrogate;
  95.         // needed in case there is a fatal error because the backend is too slow to respond
  96.         register_shutdown_function($this->store->cleanup(...));
  98.         $this->options = array_merge([
  99.             'debug' => false,
  100.             'default_ttl' => 0,
  101.             'private_headers' => ['Authorization', 'Cookie'],
  102.             'allow_reload' => false,
  103.             'allow_revalidate' => false,
  104.             'stale_while_revalidate' => 2,
  105.             'stale_if_error' => 60,
  106.             'trace_level' => 'none',
  107.             'trace_header' => 'X-Symfony-Cache',
  108.             'terminate_on_cache_hit' => true,
  109.         ], $options);
  111.         if (!isset($options['trace_level'])) {
  112.             $this->options['trace_level'] = $this->options['debug'] ? 'full' : 'none';
  113.         }
  114.     }
  116.     /**
  117.      * Gets the current store.
  118.      */
  119.     public function getStore(): StoreInterface
  120.     {
  121.         return $this->store;
  122.     }
  124.     /**
  125.      * Returns an array of events that took place during processing of the last request.
  126.      */
  127.     public function getTraces(): array
  128.     {
  129.         return $this->traces;
  130.     }
  132.     private function addTraces(Response $response)
  133.     {
  134.         $traceString = null;
  136.         if ('full' === $this->options['trace_level']) {
  137.             $traceString = $this->getLog();
  138.         }
  140.         if ('short' === $this->options['trace_level'] && $masterId = array_key_first($this->traces)) {
  141.             $traceString = implode('/', $this->traces[$masterId]);
  142.         }
  144.         if (null !== $traceString) {
  145.             $response->headers->add([$this->options['trace_header'] => $traceString]);
  146.         }
  147.     }
  149.     /**
  150.      * Returns a log message for the events of the last request processing.
  151.      */
  152.     public function getLog(): string
  153.     {
  154.         $log = [];
  155.         foreach ($this->traces as $request => $traces) {
  156.             $log[] = sprintf('%s: %s', $request, implode(', ', $traces));
  157.         }
  159.         return implode('; ', $log);
  160.     }
  162.     /**
  163.      * Gets the Request instance associated with the main request.
  164.      */
  165.     public function getRequest(): Request
  166.     {
  167.         return $this->request;
  168.     }
  170.     /**
  171.      * Gets the Kernel instance.
  172.      */
  173.     public function getKernel(): HttpKernelInterface
  174.     {
  175.         return $this->kernel;
  176.     }
  178.     /**
  179.      * Gets the Surrogate instance.
  180.      *
  181.      * @throws \LogicException
  182.      */
  183.     public function getSurrogate(): SurrogateInterface
  184.     {
  185.         return $this->surrogate;
  186.     }
  188.     public function handle(Request $request, int $type = HttpKernelInterface::MAIN_REQUEST, bool $catch = true): Response
  189.     {
  190.         // FIXME: catch exceptions and implement a 500 error page here? -> in Varnish, there is a built-in error page mechanism
  191.         if (HttpKernelInterface::MAIN_REQUEST === $type) {
  192.             $this->traces = [];
  193.             // Keep a clone of the original request for surrogates so they can access it.
  194.             // We must clone here to get a separate instance because the application will modify the request during
  195.             // the application flow (we know it always does because we do ourselves by setting REMOTE_ADDR to 127.0.0.1
  196.             // and adding the X-Forwarded-For header, see HttpCache::forward()).
  197.             $this->request = clone $request;
  198.             if (null !== $this->surrogate) {
  199.                 $this->surrogateCacheStrategy = $this->surrogate->createCacheStrategy();
  200.             }
  201.         }
  203.         $this->traces[$this->getTraceKey($request)] = [];
  205.         if (!$request->isMethodSafe()) {
  206.             $response = $this->invalidate($request, $catch);
  207.         } elseif ($request->headers->has('expect') || !$request->isMethodCacheable()) {
  208.             $response = $this->pass($request, $catch);
  209.         } elseif ($this->options['allow_reload'] && $request->isNoCache()) {
  210.             /*
  211.                 If allow_reload is configured and the client requests "Cache-Control: no-cache",
  212.                 reload the cache by fetching a fresh response and caching it (if possible).
  213.             */
  214.             $this->record($request, 'reload');
  215.             $response = $this->fetch($request, $catch);
  216.         } else {
  217.             $response = $this->lookup($request, $catch);
  218.         }
  220.         $this->restoreResponseBody($request, $response);
  222.         if (HttpKernelInterface::MAIN_REQUEST === $type) {
  223.             $this->addTraces($response);
  224.         }
  226.         if (null !== $this->surrogate) {
  227.             if (HttpKernelInterface::MAIN_REQUEST === $type) {
  228.                 $this->surrogateCacheStrategy->update($response);
  229.             } else {
  230.                 $this->surrogateCacheStrategy->add($response);
  231.             }
  232.         }
  234.         $response->prepare($request);
  236.         $response->isNotModified($request);
  238.         return $response;
  239.     }
  241.     public function terminate(Request $request, Response $response)
  242.     {
  243.         // Do not call any listeners in case of a cache hit.
  244.         // This ensures identical behavior as if you had a separate
  245.         // reverse caching proxy such as Varnish and the like.
  246.         if ($this->options['terminate_on_cache_hit']) {
  247.             trigger_deprecation('symfony/http-kernel', '6.2', 'Setting "terminate_on_cache_hit" to "true" is deprecated and will be changed to "false" in Symfony 7.0.');
  248.         } elseif (\in_array('fresh', $this->traces[$this->getTraceKey($request)] ?? [], true)) {
  249.             return;
  250.         }
  252.         if ($this->getKernel() instanceof TerminableInterface) {
  253.             $this->getKernel()->terminate($request, $response);
  254.         }
  255.     }
  257.     /**
  258.      * Forwards the Request to the backend without storing the Response in the cache.
  259.      *
  260.      * @param bool $catch Whether to process exceptions
  261.      */
  262.     protected function pass(Request $request, bool $catch = false): Response
  263.     {
  264.         $this->record($request, 'pass');
  266.         return $this->forward($request, $catch);
  267.     }
  269.     /**
  270.      * Invalidates non-safe methods (like POST, PUT, and DELETE).
  271.      *
  272.      * @param bool $catch Whether to process exceptions
  273.      *
  274.      * @throws \Exception
  275.      *
  276.      * @see RFC2616 13.10
  277.      */
  278.     protected function invalidate(Request $request, bool $catch = false): Response
  279.     {
  280.         $response = $this->pass($request, $catch);
  282.         // invalidate only when the response is successful
  283.         if ($response->isSuccessful() || $response->isRedirect()) {
  284.             try {
  285.                 $this->store->invalidate($request);
  287.                 // As per the RFC, invalidate Location and Content-Location URLs if present
  288.                 foreach (['Location', 'Content-Location'] as $header) {
  289.                     if ($uri = $response->headers->get($header)) {
  290.                         $subRequest = Request::create($uri, 'get', [], [], [], $request->server->all());
  292.                         $this->store->invalidate($subRequest);
  293.                     }
  294.                 }
  296.                 $this->record($request, 'invalidate');
  297.             } catch (\Exception $e) {
  298.                 $this->record($request, 'invalidate-failed');
  300.                 if ($this->options['debug']) {
  301.                     throw $e;
  302.                 }
  303.             }
  304.         }
  306.         return $response;
  307.     }
  309.     /**
  310.      * Lookups a Response from the cache for the given Request.
  311.      *
  312.      * When a matching cache entry is found and is fresh, it uses it as the
  313.      * response without forwarding any request to the backend. When a matching
  314.      * cache entry is found but is stale, it attempts to "validate" the entry with
  315.      * the backend using conditional GET. When no matching cache entry is found,
  316.      * it triggers "miss" processing.
  317.      *
  318.      * @param bool $catch Whether to process exceptions
  319.      *
  320.      * @throws \Exception
  321.      */
  322.     protected function lookup(Request $request, bool $catch = false): Response
  323.     {
  324.         try {
  325.             $entry = $this->store->lookup($request);
  326.         } catch (\Exception $e) {
  327.             $this->record($request, 'lookup-failed');
  329.             if ($this->options['debug']) {
  330.                 throw $e;
  331.             }
  333.             return $this->pass($request, $catch);
  334.         }
  336.         if (null === $entry) {
  337.             $this->record($request, 'miss');
  339.             return $this->fetch($request, $catch);
  340.         }
  342.         if (!$this->isFreshEnough($request, $entry)) {
  343.             $this->record($request, 'stale');
  345.             return $this->validate($request, $entry, $catch);
  346.         }
  348.         if ($entry->headers->hasCacheControlDirective('no-cache')) {
  349.             return $this->validate($request, $entry, $catch);
  350.         }
  352.         $this->record($request, 'fresh');
  354.         $entry->headers->set('Age', $entry->getAge());
  356.         return $entry;
  357.     }
  359.     /**
  360.      * Validates that a cache entry is fresh.
  361.      *
  362.      * The original request is used as a template for a conditional
  363.      * GET request with the backend.
  364.      *
  365.      * @param bool $catch Whether to process exceptions
  366.      */
  367.     protected function validate(Request $request, Response $entry, bool $catch = false): Response
  368.     {
  369.         $subRequest = clone $request;
  371.         // send no head requests because we want content
  372.         if ('HEAD' === $request->getMethod()) {
  373.             $subRequest->setMethod('GET');
  374.         }
  376.         // add our cached last-modified validator
  377.         if ($entry->headers->has('Last-Modified')) {
  378.             $subRequest->headers->set('If-Modified-Since', $entry->headers->get('Last-Modified'));
  379.         }
  381.         // Add our cached etag validator to the environment.
  382.         // We keep the etags from the client to handle the case when the client
  383.         // has a different private valid entry which is not cached here.
  384.         $cachedEtags = $entry->getEtag() ? [$entry->getEtag()] : [];
  385.         $requestEtags = $request->getETags();
  386.         if ($etags = array_unique(array_merge($cachedEtags, $requestEtags))) {
  387.             $subRequest->headers->set('If-None-Match', implode(', ', $etags));
  388.         }
  390.         $response = $this->forward($subRequest, $catch, $entry);
  392.         if (304 == $response->getStatusCode()) {
  393.             $this->record($request, 'valid');
  395.             // return the response and not the cache entry if the response is valid but not cached
  396.             $etag = $response->getEtag();
  397.             if ($etag && \in_array($etag, $requestEtags) && !\in_array($etag, $cachedEtags)) {
  398.                 return $response;
  399.             }
  401.             $entry = clone $entry;
  402.             $entry->headers->remove('Date');
  404.             foreach (['Date', 'Expires', 'Cache-Control', 'ETag', 'Last-Modified'] as $name) {
  405.                 if ($response->headers->has($name)) {
  406.                     $entry->headers->set($name, $response->headers->get($name));
  407.                 }
  408.             }
  410.             $response = $entry;
  411.         } else {
  412.             $this->record($request, 'invalid');
  413.         }
  415.         if ($response->isCacheable()) {
  416.             $this->store($request, $response);
  417.         }
  419.         return $response;
  420.     }
  422.     /**
  423.      * Unconditionally fetches a fresh response from the backend and
  424.      * stores it in the cache if is cacheable.
  425.      *
  426.      * @param bool $catch Whether to process exceptions
  427.      */
  428.     protected function fetch(Request $request, bool $catch = false): Response
  429.     {
  430.         $subRequest = clone $request;
  432.         // send no head requests because we want content
  433.         if ('HEAD' === $request->getMethod()) {
  434.             $subRequest->setMethod('GET');
  435.         }
  437.         // avoid that the backend sends no content
  438.         $subRequest->headers->remove('If-Modified-Since');
  439.         $subRequest->headers->remove('If-None-Match');
  441.         $response = $this->forward($subRequest, $catch);
  443.         if ($response->isCacheable()) {
  444.             $this->store($request, $response);
  445.         }
  447.         return $response;
  448.     }
  450.     /**
  451.      * Forwards the Request to the backend and returns the Response.
  452.      *
  453.      * All backend requests (cache passes, fetches, cache validations)
  454.      * run through this method.
  455.      *
  456.      * @param bool          $catch Whether to catch exceptions or not
  457.      * @param Response|null $entry A Response instance (the stale entry if present, null otherwise)
  458.      *
  459.      * @return Response
  460.      */
  461.     protected function forward(Request $request, bool $catch = false, Response $entry = null)
  462.     {
  463.         $this->surrogate?->addSurrogateCapability($request);
  465.         // always a "master" request (as the real master request can be in cache)
  466.         $response = SubRequestHandler::handle($this->kernel, $request, HttpKernelInterface::MAIN_REQUEST, $catch);
  468.         /*
  469.          * Support stale-if-error given on Responses or as a config option.
  470.          * RFC 7234 summarizes in Section 4.2.4 (but also mentions with the individual
  471.          * Cache-Control directives) that
  472.          *
  473.          *      A cache MUST NOT generate a stale response if it is prohibited by an
  474.          *      explicit in-protocol directive (e.g., by a "no-store" or "no-cache"
  475.          *      cache directive, a "must-revalidate" cache-response-directive, or an
  476.          *      applicable "s-maxage" or "proxy-revalidate" cache-response-directive;
  477.          *      see Section 5.2.2).
  478.          *
  479.          * https://tools.ietf.org/html/rfc7234#section-4.2.4
  480.          *
  481.          * We deviate from this in one detail, namely that we *do* serve entries in the
  482.          * stale-if-error case even if they have a `s-maxage` Cache-Control directive.
  483.          */
  484.         if (null !== $entry
  485.             && \in_array($response->getStatusCode(), [500, 502, 503, 504])
  486.             && !$entry->headers->hasCacheControlDirective('no-cache')
  487.             && !$entry->mustRevalidate()
  488.         ) {
  489.             if (null === $age = $entry->headers->getCacheControlDirective('stale-if-error')) {
  490.                 $age = $this->options['stale_if_error'];
  491.             }
  493.             /*
  494.              * stale-if-error gives the (extra) time that the Response may be used *after* it has become stale.
  495.              * So we compare the time the $entry has been sitting in the cache already with the
  496.              * time it was fresh plus the allowed grace period.
  497.              */
  498.             if ($entry->getAge() <= $entry->getMaxAge() + $age) {
  499.                 $this->record($request, 'stale-if-error');
  501.                 return $entry;
  502.             }
  503.         }
  505.         /*
  506.             RFC 7231 Sect. 7.1.1.2 says that a server that does not have a reasonably accurate
  507.             clock MUST NOT send a "Date" header, although it MUST send one in most other cases
  508.             except for 1xx or 5xx responses where it MAY do so.
  510.             Anyway, a client that received a message without a "Date" header MUST add it.
  511.         */
  512.         if (!$response->headers->has('Date')) {
  513.             $response->setDate(\DateTimeImmutable::createFromFormat('U', time()));
  514.         }
  516.         $this->processResponseBody($request, $response);
  518.         if ($this->isPrivateRequest($request) && !$response->headers->hasCacheControlDirective('public')) {
  519.             $response->setPrivate();
  520.         } elseif ($this->options['default_ttl'] > 0 && null === $response->getTtl() && !$response->headers->getCacheControlDirective('must-revalidate')) {
  521.             $response->setTtl($this->options['default_ttl']);
  522.         }
  524.         return $response;
  525.     }
  527.     /**
  528.      * Checks whether the cache entry is "fresh enough" to satisfy the Request.
  529.      */
  530.     protected function isFreshEnough(Request $request, Response $entry): bool
  531.     {
  532.         if (!$entry->isFresh()) {
  533.             return $this->lock($request, $entry);
  534.         }
  536.         if ($this->options['allow_revalidate'] && null !== $maxAge = $request->headers->getCacheControlDirective('max-age')) {
  537.             return $maxAge > 0 && $maxAge >= $entry->getAge();
  538.         }
  540.         return true;
  541.     }
  543.     /**
  544.      * Locks a Request during the call to the backend.
  545.      *
  546.      * @return bool true if the cache entry can be returned even if it is staled, false otherwise
  547.      */
  548.     protected function lock(Request $request, Response $entry): bool
  549.     {
  550.         // try to acquire a lock to call the backend
  551.         $lock = $this->store->lock($request);
  553.         if (true === $lock) {
  554.             // we have the lock, call the backend
  555.             return false;
  556.         }
  558.         // there is already another process calling the backend
  560.         // May we serve a stale response?
  561.         if ($this->mayServeStaleWhileRevalidate($entry)) {
  562.             $this->record($request, 'stale-while-revalidate');
  564.             return true;
  565.         }
  567.         // wait for the lock to be released
  568.         if ($this->waitForLock($request)) {
  569.             // replace the current entry with the fresh one
  570.             $new = $this->lookup($request);
  571.             $entry->headers = $new->headers;
  572.             $entry->setContent($new->getContent());
  573.             $entry->setStatusCode($new->getStatusCode());
  574.             $entry->setProtocolVersion($new->getProtocolVersion());
  575.             foreach ($new->headers->getCookies() as $cookie) {
  576.                 $entry->headers->setCookie($cookie);
  577.             }
  578.         } else {
  579.             // backend is slow as hell, send a 503 response (to avoid the dog pile effect)
  580.             $entry->setStatusCode(503);
  581.             $entry->setContent('503 Service Unavailable');
  582.             $entry->headers->set('Retry-After', 10);
  583.         }
  585.         return true;
  586.     }
  588.     /**
  589.      * Writes the Response to the cache.
  590.      *
  591.      * @throws \Exception
  592.      */
  593.     protected function store(Request $request, Response $response)
  594.     {
  595.         try {
  596.             $this->store->write($request, $response);
  598.             $this->record($request, 'store');
  600.             $response->headers->set('Age', $response->getAge());
  601.         } catch (\Exception $e) {
  602.             $this->record($request, 'store-failed');
  604.             if ($this->options['debug']) {
  605.                 throw $e;
  606.             }
  607.         }
  609.         // now that the response is cached, release the lock
  610.         $this->store->unlock($request);
  611.     }
  613.     /**
  614.      * Restores the Response body.
  615.      */
  616.     private function restoreResponseBody(Request $request, Response $response)
  617.     {
  618.         if ($response->headers->has('X-Body-Eval')) {
  619.             \assert(self::BODY_EVAL_BOUNDARY_LENGTH === 24);
  621.             ob_start();
  623.             $content = $response->getContent();
  624.             $boundary = substr($content, 0, 24);
  625.             $j = strpos($content, $boundary, 24);
  626.             echo substr($content, 24, $j - 24);
  627.             $i = $j + 24;
  629.             while (false !== $j = strpos($content, $boundary, $i)) {
  630.                 [$uri, $alt, $ignoreErrors, $part] = explode("\n", substr($content, $i, $j - $i), 4);
  631.                 $i = $j + 24;
  633.                 echo $this->surrogate->handle($this, $uri, $alt, $ignoreErrors);
  634.                 echo $part;
  635.             }
  637.             $response->setContent(ob_get_clean());
  638.             $response->headers->remove('X-Body-Eval');
  639.             if (!$response->headers->has('Transfer-Encoding')) {
  640.                 $response->headers->set('Content-Length', \strlen($response->getContent()));
  641.             }
  642.         } elseif ($response->headers->has('X-Body-File')) {
  643.             // Response does not include possibly dynamic content (ESI, SSI), so we need
  644.             // not handle the content for HEAD requests
  645.             if (!$request->isMethod('HEAD')) {
  646.                 $response->setContent(file_get_contents($response->headers->get('X-Body-File')));
  647.             }
  648.         } else {
  649.             return;
  650.         }
  652.         $response->headers->remove('X-Body-File');
  653.     }
  655.     protected function processResponseBody(Request $request, Response $response)
  656.     {
  657.         if ($this->surrogate?->needsParsing($response)) {
  658.             $this->surrogate->process($request, $response);
  659.         }
  660.     }
  662.     /**
  663.      * Checks if the Request includes authorization or other sensitive information
  664.      * that should cause the Response to be considered private by default.
  665.      */
  666.     private function isPrivateRequest(Request $request): bool
  667.     {
  668.         foreach ($this->options['private_headers'] as $key) {
  669.             $key = strtolower(str_replace('HTTP_', '', $key));
  671.             if ('cookie' === $key) {
  672.                 if (\count($request->cookies->all())) {
  673.                     return true;
  674.                 }
  675.             } elseif ($request->headers->has($key)) {
  676.                 return true;
  677.             }
  678.         }
  680.         return false;
  681.     }
  683.     /**
  684.      * Records that an event took place.
  685.      */
  686.     private function record(Request $request, string $event)
  687.     {
  688.         $this->traces[$this->getTraceKey($request)][] = $event;
  689.     }
  691.     /**
  692.      * Calculates the key we use in the "trace" array for a given request.
  693.      */
  694.     private function getTraceKey(Request $request): string
  695.     {
  696.         $path = $request->getPathInfo();
  697.         if ($qs = $request->getQueryString()) {
  698.             $path .= '?'.$qs;
  699.         }
  701.         return $request->getMethod().' '.$path;
  702.     }
  704.     /**
  705.      * Checks whether the given (cached) response may be served as "stale" when a revalidation
  706.      * is currently in progress.
  707.      */
  708.     private function mayServeStaleWhileRevalidate(Response $entry): bool
  709.     {
  710.         $timeout = $entry->headers->getCacheControlDirective('stale-while-revalidate');
  711.         $timeout ??= $this->options['stale_while_revalidate'];
  713.         $age = $entry->getAge();
  714.         $maxAge = $entry->getMaxAge() ?? 0;
  715.         $ttl = $maxAge - $age;
  717.         return abs($ttl) < $timeout;
  718.     }
  720.     /**
  721.      * Waits for the store to release a locked entry.
  722.      */
  723.     private function waitForLock(Request $request): bool
  724.     {
  725.         $wait = 0;
  726.         while ($this->store->isLocked($request) && $wait < 100) {
  727.             usleep(50000);
  728.             ++$wait;
  729.         }
  731.         return $wait < 100;
  732.     }
  733. }