Skip to main content

net/
http_cache.rs

1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
4
5#![deny(missing_docs)]
6
7//! A memory cache implementing the logic specified in <http://tools.ietf.org/html/rfc7234>
8//! and <http://tools.ietf.org/html/rfc7232>.
9
10use std::ops::Bound;
11use std::sync::Arc as StdArc;
12use std::sync::atomic::{AtomicBool, Ordering};
13use std::time::{Duration, SystemTime};
14
15use headers::{
16    CacheControl, ContentRange, ContentType, Expires, HeaderMapExt, LastModified, Pragma, Range,
17    Vary,
18};
19use http::{HeaderMap, Method, StatusCode, header};
20use hyper_serde::Serde;
21use log::{debug, error, info};
22use malloc_size_of::{MallocSizeOf, MallocSizeOfOps};
23use malloc_size_of_derive::MallocSizeOf;
24use net_traits::http_status::HttpStatus;
25use net_traits::request::{CacheMode, Request};
26use net_traits::response::{Response, ResponseBody};
27use net_traits::{CacheEntryDescriptor, Metadata, ResourceFetchTiming};
28use parking_lot::{Mutex as ParkingLotMutex, RwLock as ParkingLotRwLock};
29use quick_cache::sync::{Cache, PlaceholderGuard};
30use quick_cache::{DefaultHashBuilder, Lifecycle, UnitWeighter};
31use serde::{Deserialize, Serialize};
32use servo_arc::Arc;
33use servo_config::pref;
34use servo_url::ServoUrl;
35use tokio::sync::mpsc::{UnboundedSender as TokioSender, unbounded_channel as unbounded};
36use tokio::sync::{OwnedRwLockWriteGuard, RwLock as TokioRwLock};
37
38use crate::disk_cache::DiskCache;
39use crate::fetch::methods::{Data, DoneChannel};
40
41/// A duration in seconds.
42///
43/// This is the same as std::time::Duration except that we do not care about nanosecond precision.
44#[derive(
45    Copy,
46    Clone,
47    Default,
48    Debug,
49    Deserialize,
50    MallocSizeOf,
51    Serialize,
52    PartialEq,
53    Eq,
54    PartialOrd,
55    Ord,
56)]
57struct ApproxDuration(u64);
58
59impl ApproxDuration {
60    const fn zero() -> Self {
61        Self(0)
62    }
63
64    fn is_zero(&self) -> bool {
65        self.0 == 0
66    }
67
68    fn saturating_sub(&self, rhs: ApproxDuration) -> Self {
69        Self(self.0.saturating_sub(rhs.0))
70    }
71
72    fn from_secs(seconds: u64) -> Self {
73        Self(seconds)
74    }
75}
76
77impl From<Duration> for ApproxDuration {
78    fn from(value: Duration) -> Self {
79        Self(value.as_secs())
80    }
81}
82
83impl std::ops::Add for ApproxDuration {
84    type Output = Self;
85
86    fn add(self, rhs: Self) -> Self::Output {
87        Self(self.0 + rhs.0)
88    }
89}
90
91impl std::ops::Sub for ApproxDuration {
92    type Output = Self;
93
94    fn sub(self, rhs: Self) -> Self::Output {
95        Self(self.0 - rhs.0)
96    }
97}
98
99impl std::ops::Div<u64> for ApproxDuration {
100    type Output = Self;
101
102    fn div(self, rhs: u64) -> Self::Output {
103        Self(self.0 / rhs)
104    }
105}
106
107/// The key used to differentiate requests in the cache.
108#[derive(Clone, Debug, Eq, Hash, MallocSizeOf, PartialEq)]
109pub struct CacheKey {
110    url: ServoUrl,
111}
112
113impl AsRef<str> for CacheKey {
114    fn as_ref(&self) -> &str {
115        self.url.as_str()
116    }
117}
118
119impl CacheKey {
120    /// Create a cache-key from a request.
121    pub fn new(request: &Request) -> CacheKey {
122        CacheKey {
123            url: request.current_url(),
124        }
125    }
126
127    /// Create a cache-key from a resolved URL.
128    pub fn from_url(url: ServoUrl) -> CacheKey {
129        CacheKey { url }
130    }
131}
132
133/// A complete cached resource.
134#[derive(Debug, Deserialize, MallocSizeOf, Serialize)]
135pub struct CachedResource {
136    request_headers: Serde<HeaderMap>,
137    #[conditional_malloc_size_of]
138    body: Arc<ParkingLotMutex<ResponseBody>>,
139    #[conditional_malloc_size_of]
140    aborted: Arc<AtomicBool>,
141    #[conditional_malloc_size_of]
142    #[serde(skip)]
143    awaiting_body: Arc<ParkingLotMutex<Vec<TokioSender<Data>>>>,
144    metadata: CachedMetadata,
145    location_url: Option<Result<ServoUrl, String>>,
146    status: HttpStatus,
147    url_list: Vec<ServoUrl>,
148    expires: ApproxDuration,
149    stale_while_revalidate: ApproxDuration,
150    #[conditional_malloc_size_of]
151    #[serde(skip)]
152    revalidating: StdArc<AtomicBool>,
153    last_validated: SystemTime,
154}
155
156impl CachedResource {
157    pub(crate) fn is_done(&self) -> bool {
158        self.body.lock().is_done()
159    }
160
161    /// Whether this [`CachedResource`] can be used to answer the given `Request`. This
162    /// is true if:
163    ///
164    /// 1. The resource is not for an aborted load.
165    /// 2. The fields named in the `Vary` header match those of the `Request`.
166    /// 3. It is not a partial (206) response or the request has a `Range` header. When the request
167    ///    has a `Range` header the caller is expected to decide which part of the resource to use.
168    fn can_be_used_to_answer(&self, request: &Request) -> bool {
169        if self.aborted.load(Ordering::Acquire) {
170            return false;
171        }
172        if !self.vary_header_matches(&request.headers) {
173            return false;
174        }
175        if request.headers.typed_get::<Range>().is_some() {
176            return true;
177        }
178
179        // From <https://httpwg.org/specs/rfc9111.html#incomplete.responses>
180        // > A cache MAY complete a stored incomplete response by making a subsequent range
181        // > request (Section 14.2 of [HTTP]) and combining the successful response with the
182        // > stored response, as defined in Section 3.4. A cache MUST NOT use an incomplete
183        // > response to answer requests unless the response has been made complete, or the
184        // > request is partial and specifies a range wholly within the incomplete response.
185        // > A cache MUST NOT send a partial response to a client without explicitly marking
186        // > it using the 206 (Partial Content) status code.
187        //
188        // TODO: Combining partial content to fulfill a non-Range request
189        // See <https://httpwg.org/specs/rfc9111.html#combining.responses>.
190        self.status
191            .try_code()
192            .is_some_and(|code| code != StatusCode::PARTIAL_CONTENT)
193    }
194
195    /// Whether the given request headers match the cached resource's request headers
196    /// on every field named in the `Vary` header according to the rules specified in
197    /// <https://httpwg.org/specs/rfc9111.html#caching.negotiated.responses>.
198    ///
199    /// > When a cache receives a request that can be satisfied by a stored response and
200    /// > that stored response contains a Vary header field (Section 12.5.5 of [HTTP]), the
201    /// > cache MUST NOT use that stored response without revalidation unless all the
202    /// > presented request header fields nominated by that Vary field value match those
203    /// > fields in the original request (i.e., the request that caused the cached response
204    /// > to be stored).
205    fn vary_header_matches(&self, request_headers: &HeaderMap) -> bool {
206        let cached_headers = self.metadata.headers.read();
207        let Some(vary_value) = cached_headers.typed_get::<Vary>() else {
208            return true;
209        };
210
211        if vary_value.is_any() {
212            return false;
213        }
214
215        for vary_header_field in vary_value.iter_strs() {
216            if request_headers.get(vary_header_field) != self.request_headers.get(vary_header_field)
217            {
218                return false;
219            }
220        }
221
222        true
223    }
224}
225
226/// Metadata about a loaded resource, such as is obtained from HTTP headers.
227#[derive(Clone, Debug, Deserialize, Serialize, MallocSizeOf)]
228struct CachedMetadata {
229    /// Headers
230    #[conditional_malloc_size_of]
231    pub headers: Arc<ParkingLotRwLock<Serde<HeaderMap>>>,
232    /// Final URL after redirects.
233    pub final_url: ServoUrl,
234    /// MIME type / subtype.
235    pub content_type: Option<Serde<ContentType>>,
236    /// Character set.
237    pub charset: Option<String>,
238    /// HTTP Status
239    pub status: HttpStatus,
240}
241
242/// Whether a cached response is fresh or requires validation before or after use.
243#[derive(Clone, Copy, Debug, Eq, PartialEq)]
244pub enum ValidationStatus {
245    /// The response is fresh and can be used without any revalidation.
246    Valid,
247    /// The response is stale.
248    Stale {
249        /// Whether the stale response can be served immediately, leaving the
250        /// caller responsible for revalidating it in the background.
251        revalidate_in_background: bool,
252    },
253}
254
255/// Wrapper around a cached response, including information on re-validation needs
256pub(crate) struct CachedResponse {
257    /// The response constructed from the cached resource
258    pub response: Response,
259    /// Whether the stored response is fresh or stale
260    pub validation_status: ValidationStatus,
261    /// Single-flight guard for the background revalidation.
262    pub revalidation_guard: StdArc<AtomicBool>,
263}
264
265pub(crate) type CacheEntry = std::sync::Arc<TokioRwLock<Vec<CachedResource>>>;
266type QuickCache =
267    Cache<CacheKey, CacheEntry, UnitWeighter, DefaultHashBuilder, MemoryCacheLifecycle>;
268type QuickCachePlaceholderGuard<'a> = PlaceholderGuard<
269    'a,
270    CacheKey,
271    CacheEntry,
272    UnitWeighter,
273    DefaultHashBuilder,
274    MemoryCacheLifecycle,
275>;
276
277/// Is this state assigned to the private or public side.
278#[derive(Debug, MallocSizeOf, PartialEq)]
279pub enum HttpCacheAssignment {
280    /// Public Cache State, possibly stored to disk.
281    Public,
282    /// Private Cache State, not stored to disk.
283    Private,
284}
285
286/// A simple memory cache.
287/// Elements will be evicted based on the cache heuristic. We weight elements
288/// by the number of entries per given url. We evict currently a whole url.
289/// The cache makes extensive use of `Arc::unwrap_or_clone or` and `Arc::into_inner`
290/// to modify the cached entries. This is ok because `CachedResource` are cheap to clone
291pub struct HttpCache {
292    /// cached responses.
293    entries: QuickCache,
294    disk_cache: Option<std::sync::Arc<DiskCache>>,
295}
296
297impl std::fmt::Debug for HttpCache {
298    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
299        f.debug_list().entries(self.entries.iter()).finish()
300    }
301}
302
303impl MallocSizeOf for HttpCache {
304    fn size_of(&self, ops: &mut MallocSizeOfOps) -> usize {
305        self.entries
306            .iter()
307            .map(|(_key, entry)| entry.blocking_read().size_of(ops))
308            .sum::<usize>() +
309            self.disk_cache
310                .as_ref()
311                .map(|data| data.size_of(ops))
312                .unwrap_or(0)
313    }
314}
315
316impl HttpCache {
317    /// Create a new HttpCache with [`HttpCacheAssignment`]
318    pub fn new(assignment: HttpCacheAssignment) -> Self {
319        let size = pref!(network_http_cache_size)
320            .try_into()
321            .expect("http_cache_size needs to fit into u64");
322        let (disk_cache, lifecycle) = DiskCache::new(assignment);
323        let memory_cache = Cache::with(
324            size,
325            size as u64,
326            UnitWeighter,
327            DefaultHashBuilder::default(),
328            lifecycle,
329        );
330
331        Self {
332            entries: memory_cache,
333            disk_cache,
334        }
335    }
336
337    #[expect(clippy::len_without_is_empty)]
338    /// The number of entries in the memory cache. This does not say anything about the disk cache.
339    pub fn len(&self) -> usize {
340        self.entries.len()
341    }
342
343    /// Saves removes all elements from the memory cache and stores them in the disk cache.
344    pub async fn drain_to_disk(&self) {
345        if let Some(disk_cache) = &self.disk_cache {
346            log::info!("Storing http cache to disk");
347            let entries: Vec<_> = self.entries.drain().collect();
348            for (key, entry) in entries {
349                disk_cache.store(key, entry).await;
350            }
351        }
352    }
353}
354
355#[derive(Clone)]
356/// The lifecycle hooks of the HttpCache.
357/// Responsible for moving data to the disk.
358pub struct MemoryCacheLifecycle {
359    pub(crate) disk_cache: Option<StdArc<DiskCache>>,
360}
361
362impl MemoryCacheLifecycle {
363    pub(crate) fn empty() -> MemoryCacheLifecycle {
364        MemoryCacheLifecycle { disk_cache: None }
365    }
366}
367
368impl Lifecycle<CacheKey, CacheEntry> for MemoryCacheLifecycle {
369    type RequestState = ();
370
371    // Cached Resources that are not complete could get evicted which means they cannot fill their body.
372    // We allow unfinished resources to stay in the cache.
373    fn is_pinned(&self, key: &CacheKey, val: &CacheEntry) -> bool {
374        let pinned = val
375            .try_read()
376            .map(|cached_resources| cached_resources.iter().any(|resource| !resource.is_done()))
377            .unwrap_or(true);
378        info!("Key {key:?} is pinned",);
379        pinned
380    }
381
382    fn on_evict(&self, _state: &mut Self::RequestState, key: CacheKey, value: CacheEntry) {
383        info!("Evicting {key:?} from memory cache");
384        if let Some(disk_cache_data) = &self.disk_cache {
385            let disk_cache_data = disk_cache_data.clone();
386            tokio::spawn(async move { disk_cache_data.store(key, value).await });
387        }
388    }
389}
390
391/// Determine if a response is cacheable by default <https://tools.ietf.org/html/rfc7231#section-6.1>
392fn is_cacheable_by_default(status_code: StatusCode) -> bool {
393    matches!(
394        status_code.as_u16(),
395        200 | 203 | 204 | 206 | 300 | 301 | 404 | 405 | 410 | 414 | 501
396    )
397}
398
399/// Determine if a given response is cacheable.
400/// Based on <https://tools.ietf.org/html/rfc7234#section-3>
401fn response_is_cacheable(metadata: &Metadata) -> bool {
402    // This kind of response does not have a body. It just freshens existing cached resources.
403    if metadata.status == StatusCode::NOT_MODIFIED {
404        return false;
405    }
406
407    // Resources with `Vary: '*'` can never be returned as cache results, so
408    // do not store them in the cache.
409    let headers = metadata.headers.as_ref().unwrap();
410    if headers
411        .typed_get::<Vary>()
412        .is_some_and(|vary| vary.is_any())
413    {
414        return false;
415    }
416
417    // TODO: if we determine that this cache should be considered shared:
418    // 1. check for absence of private response directive <https://tools.ietf.org/html/rfc7234#section-5.2.2.6>
419    // 2. check for absence of the Authorization header field.
420    let mut is_cacheable = false;
421    if headers.contains_key(header::EXPIRES) ||
422        headers.contains_key(header::LAST_MODIFIED) ||
423        headers.contains_key(header::ETAG)
424    {
425        is_cacheable = true;
426    }
427    if let Some(ref directive) = headers.typed_get::<CacheControl>() {
428        if directive.no_store() {
429            return false;
430        }
431        if directive.public() ||
432            directive.s_max_age().is_some() ||
433            directive.max_age().is_some() ||
434            directive.no_cache()
435        {
436            // If cache-control is understood, we can use it and ignore pragma.
437            return true;
438        }
439    }
440    if let Some(pragma) = headers.typed_get::<Pragma>() &&
441        pragma.is_no_cache()
442    {
443        return false;
444    }
445
446    is_cacheable
447}
448
449/// Calculating Age
450/// <https://tools.ietf.org/html/rfc7234#section-4.2.3>
451fn calculate_response_age(response: &Response) -> ApproxDuration {
452    // TODO: follow the spec more closely (Date headers, request/response lag, ...)
453    response
454        .headers
455        .get(header::AGE)
456        .and_then(|age_header| age_header.to_str().ok())
457        .and_then(|age_string| age_string.parse::<u64>().ok())
458        .map(ApproxDuration::from_secs)
459        .unwrap_or_default()
460}
461
462/// Determine the expiry date from relevant headers,
463/// or uses a heuristic if none are present.
464fn get_response_expiry(response: &Response) -> ApproxDuration {
465    // Calculating Freshness Lifetime <https://tools.ietf.org/html/rfc7234#section-4.2.1>
466    let age = calculate_response_age(response);
467    let now = SystemTime::now();
468    if let Some(directives) = response.headers.typed_get::<CacheControl>() {
469        if directives.no_cache() {
470            // Requires validation on first use.
471            return ApproxDuration::zero();
472        }
473        if let Some(max_age) = directives.max_age().or(directives.s_max_age()) {
474            let max_age: ApproxDuration = max_age.into();
475            return max_age.saturating_sub(age);
476        }
477    }
478    match response.headers.typed_get::<Expires>() {
479        Some(expiry) => {
480            // `duration_since` fails if `now` is later than `expiry_time` in which case,
481            // this whole thing return `Duration::ZERO`.
482            let expiry_time: SystemTime = expiry.into();
483            return expiry_time
484                .duration_since(now)
485                .map(|duration| duration.into())
486                .unwrap_or(ApproxDuration::zero());
487        },
488        // Malformed Expires header, shouldn't be used to construct a valid response.
489        None if response.headers.contains_key(header::EXPIRES) => return ApproxDuration::zero(),
490        _ => {},
491    }
492    // Calculating Heuristic Freshness
493    // <https://tools.ietf.org/html/rfc7234#section-4.2.2>
494    if let Some(ref code) = response.status.try_code() {
495        // <https://tools.ietf.org/html/rfc7234#section-5.5.4>
496        // Since presently we do not generate a Warning header field with a 113 warn-code,
497        // 24 hours minus response age is the max for heuristic calculation.
498        let max_heuristic = ApproxDuration::from_secs(24 * 60 * 60).saturating_sub(age);
499        let heuristic_freshness = if let Some(last_modified) =
500            // If the response has a Last-Modified header field,
501            // caches are encouraged to use a heuristic expiration value
502            // that is no more than some fraction of the interval since that time.
503            response.headers.typed_get::<LastModified>()
504        {
505            // `time_since_last_modified` will be `Duration::ZERO` if `last_modified` is
506            // after `now`.
507            let last_modified: SystemTime = last_modified.into();
508            let time_since_last_modified: ApproxDuration =
509                now.duration_since(last_modified).unwrap_or_default().into();
510
511            // A typical setting of this fraction might be 10%.
512            let raw_heuristic_calc = time_since_last_modified / 10;
513            if raw_heuristic_calc < max_heuristic {
514                raw_heuristic_calc
515            } else {
516                max_heuristic
517            }
518        } else {
519            // Compatible with other browsers.
520            ApproxDuration::zero()
521        };
522        if is_cacheable_by_default(*code) {
523            // Status codes that are cacheable by default can use heuristics to determine freshness.
524            return heuristic_freshness;
525        }
526        // Other status codes can only use heuristic freshness if the public cache directive is present.
527        if let Some(ref directives) = response.headers.typed_get::<CacheControl>() &&
528            directives.public()
529        {
530            return heuristic_freshness;
531        }
532    }
533    // Requires validation upon first use as default.
534    ApproxDuration::zero()
535}
536
537/// The `headers` crate's `CacheControl` does not understand `stale-while-revalidate` directive,
538/// so we need to parse the raw `Cache-Control` header values.
539/// <https://datatracker.ietf.org/doc/html/rfc5861#section-3>
540fn get_stale_while_revalidate(headers: &HeaderMap) -> ApproxDuration {
541    for value in headers.get_all(header::CACHE_CONTROL) {
542        let Ok(value) = value.to_str() else {
543            continue;
544        };
545        for directive in value.split(',') {
546            let directive = directive.trim();
547            let Some((name, argument)) = directive.split_once('=') else {
548                continue;
549            };
550            if !name.trim().eq_ignore_ascii_case("stale-while-revalidate") {
551                continue;
552            }
553            // The argument is a number of seconds, optionally quoted.
554            let argument = argument.trim().trim_matches('"');
555            if let Ok(seconds) = argument.parse::<u64>() {
556                return ApproxDuration::from_secs(seconds);
557            }
558        }
559    }
560    ApproxDuration::zero()
561}
562
563/// Determine whether the request itself demands revalidation.
564/// <https://www.rfc-editor.org/rfc/rfc9111.html#section-5.2.1>
565fn request_demands_revalidation(request: &Request) -> bool {
566    if matches!(
567        request.cache_mode,
568        CacheMode::NoCache | CacheMode::Reload | CacheMode::NoStore
569    ) {
570        return true;
571    }
572    if let Some(directive) = request.headers.typed_get::<CacheControl>() {
573        // The request's `no-store` directive is deliberately *not* treated as
574        // demanding revalidation: https://www.rfc-editor.org/rfc/rfc9111.html#section-5.2.1.5
575        // > "does not apply to the already stored response".
576        if directive.no_cache() {
577            return true;
578        }
579
580        if directive.max_age() == Some(Duration::ZERO) {
581            return true;
582        }
583    }
584    false
585}
586
587/// Request Cache-Control Directives
588/// <https://tools.ietf.org/html/rfc7234#section-5.2.1>
589fn get_expiry_adjustment_from_request_headers(
590    request: &Request,
591    expires: ApproxDuration,
592) -> ApproxDuration {
593    let Some(directive) = request.headers.typed_get::<CacheControl>() else {
594        return expires;
595    };
596
597    if let Some(max_age) = directive.max_stale() {
598        let max_age: ApproxDuration = max_age.into();
599        return expires + max_age;
600    };
601
602    let max_age: Option<ApproxDuration> = directive.max_age().map(|max_age| max_age.into());
603    match max_age {
604        Some(max_age) if expires > max_age => return ApproxDuration::zero(),
605        Some(max_age) => return expires - max_age,
606        None => {},
607    };
608
609    if let Some(min_fresh) = directive.min_fresh() {
610        let min_fresh: ApproxDuration = min_fresh.into();
611        if expires < min_fresh {
612            return ApproxDuration::zero();
613        };
614        return expires - min_fresh;
615    }
616
617    if directive.no_cache() || directive.no_store() {
618        return ApproxDuration::zero();
619    }
620
621    expires
622}
623
624/// Create a CachedResponse from a request and a CachedResource.
625fn create_cached_response(
626    request: &Request,
627    cached_resource: &CachedResource,
628    cached_headers: &HeaderMap,
629    done_chan: &mut DoneChannel,
630) -> Option<CachedResponse> {
631    debug!("creating a cached response for {:?}", request.url());
632    if cached_resource.aborted.load(Ordering::Acquire) {
633        return None;
634    }
635    let resource_timing = ResourceFetchTiming::new(request.timing_type());
636    let mut response = Response::new(cached_resource.metadata.final_url.clone(), resource_timing);
637    response.headers = cached_headers.clone();
638    response.body = cached_resource.body.clone();
639    if let ResponseBody::Receiving(_) = *cached_resource.body.lock() {
640        debug!("existing body is in progress");
641        let (done_sender, done_receiver) = unbounded();
642        *done_chan = Some((done_sender.clone(), done_receiver));
643        cached_resource.awaiting_body.lock().push(done_sender);
644    }
645    response
646        .location_url
647        .clone_from(&cached_resource.location_url);
648    response.status.clone_from(&cached_resource.status);
649    response.url_list.clone_from(&cached_resource.url_list);
650    response.referrer = request.referrer.to_url().cloned();
651    response.referrer_policy = request.referrer_policy;
652    response.aborted = cached_resource.aborted.clone();
653
654    let expires = cached_resource.expires;
655    let adjusted_expires = get_expiry_adjustment_from_request_headers(request, expires);
656    let Ok(time_since_validated) = SystemTime::now().duration_since(cached_resource.last_validated)
657    else {
658        return None;
659    };
660
661    let time_since_validated: ApproxDuration = time_since_validated.into();
662    // TODO: take must-revalidate into account <https://tools.ietf.org/html/rfc7234#section-5.2.2.1>
663    // TODO: if this cache is to be considered shared, take proxy-revalidate into account
664    // <https://tools.ietf.org/html/rfc7234#section-5.2.2.7>
665    let has_expired = adjusted_expires <= time_since_validated;
666
667    // - fresh: return immediately, no validation.
668    // - stale:
669    //    - within the stale-while-revalidate window: return immediately + revalidate in the background
670    //    - beyond the stale-while-revalidate window: synchronous validation is required.
671    let stale_for = time_since_validated.saturating_sub(adjusted_expires);
672    let within_stale_while_revalidate_window = stale_for <= cached_resource.stale_while_revalidate;
673    let validation_status = if !has_expired {
674        ValidationStatus::Valid
675    } else {
676        ValidationStatus::Stale {
677            revalidate_in_background: within_stale_while_revalidate_window &&
678                !cached_resource.stale_while_revalidate.is_zero() &&
679                !request_demands_revalidation(request),
680        }
681    };
682
683    let cached_response = CachedResponse {
684        response,
685        validation_status,
686        revalidation_guard: cached_resource.revalidating.clone(),
687    };
688    Some(cached_response)
689}
690
691/// Create a new resource, based on the bytes requested, and an existing resource,
692/// with a status-code of 206.
693fn create_resource_with_bytes_from_resource(
694    bytes: &[u8],
695    resource: &CachedResource,
696) -> CachedResource {
697    CachedResource {
698        request_headers: resource.request_headers.clone(),
699        body: Arc::new(ParkingLotMutex::new(ResponseBody::Done(bytes.to_owned()))),
700        aborted: Arc::new(AtomicBool::new(false)),
701        awaiting_body: Arc::new(ParkingLotMutex::new(vec![])),
702        metadata: resource.metadata.clone(),
703        location_url: resource.location_url.clone(),
704        status: StatusCode::PARTIAL_CONTENT.into(),
705        url_list: resource.url_list.clone(),
706        expires: resource.expires,
707        stale_while_revalidate: resource.stale_while_revalidate,
708        revalidating: resource.revalidating.clone(),
709        last_validated: resource.last_validated,
710    }
711}
712
713/// Support for range requests <https://tools.ietf.org/html/rfc7233>.
714fn handle_range_request(
715    request: &Request,
716    candidates: &[&CachedResource],
717    range_spec: &Range,
718    done_chan: &mut DoneChannel,
719) -> Option<CachedResponse> {
720    let mut complete_cached_resources = candidates
721        .iter()
722        .filter(|resource| resource.status == StatusCode::OK);
723    let partial_cached_resources = candidates
724        .iter()
725        .filter(|resource| resource.status == StatusCode::PARTIAL_CONTENT);
726    if let Some(complete_resource) = complete_cached_resources.next() {
727        // TODO: take the full range spec into account.
728        // If we have a complete resource, take the request range from the body.
729        // When there isn't a complete resource available, we loop over cached partials,
730        // and see if any individual partial response can fulfill the current request for a bytes range.
731        // TODO: combine partials that in combination could satisfy the requested range?
732        // see <https://tools.ietf.org/html/rfc7233#section-4.3>.
733        // TODO: add support for complete and partial resources,
734        // whose body is in the ResponseBody::Receiving state.
735        let body_len = match *complete_resource.body.lock() {
736            ResponseBody::Done(ref body) => body.len(),
737            _ => 0,
738        };
739        let bound = range_spec
740            .satisfiable_ranges(body_len.try_into().unwrap())
741            .next()
742            .unwrap();
743        match bound {
744            (Bound::Included(beginning), Bound::Included(end)) => {
745                if let ResponseBody::Done(ref body) = *complete_resource.body.lock() {
746                    if end == u64::MAX {
747                        // Prevent overflow on the addition below.
748                        return None;
749                    }
750                    let b = beginning as usize;
751                    let e = end as usize + 1;
752                    let requested = body.get(b..e);
753                    if let Some(bytes) = requested {
754                        let new_resource =
755                            create_resource_with_bytes_from_resource(bytes, complete_resource);
756                        let cached_headers = new_resource.metadata.headers.read();
757                        let cached_response = create_cached_response(
758                            request,
759                            &new_resource,
760                            &cached_headers,
761                            done_chan,
762                        );
763                        if let Some(cached_response) = cached_response {
764                            return Some(cached_response);
765                        }
766                    }
767                }
768            },
769            (Bound::Included(beginning), Bound::Unbounded) => {
770                if let ResponseBody::Done(ref body) = *complete_resource.body.lock() {
771                    let b = beginning as usize;
772                    let requested = body.get(b..);
773                    if let Some(bytes) = requested {
774                        let new_resource =
775                            create_resource_with_bytes_from_resource(bytes, complete_resource);
776                        let cached_headers = new_resource.metadata.headers.read();
777                        let cached_response = create_cached_response(
778                            request,
779                            &new_resource,
780                            &cached_headers,
781                            done_chan,
782                        );
783                        if let Some(cached_response) = cached_response {
784                            return Some(cached_response);
785                        }
786                    }
787                }
788            },
789            _ => return None,
790        }
791    } else {
792        for partial_resource in partial_cached_resources {
793            let headers = partial_resource.metadata.headers.read();
794            let content_range = headers.typed_get::<ContentRange>();
795
796            let Some(body_len) = content_range.as_ref().and_then(|range| range.bytes_len()) else {
797                continue;
798            };
799            match range_spec.satisfiable_ranges(body_len - 1).next().unwrap() {
800                (Bound::Included(beginning), Bound::Included(end)) => {
801                    let (res_beginning, res_end) = match content_range {
802                        Some(range) => {
803                            if let Some(bytes_range) = range.bytes_range() {
804                                bytes_range
805                            } else {
806                                continue;
807                            }
808                        },
809                        _ => continue,
810                    };
811                    if res_beginning <= beginning && res_end >= end {
812                        let resource_body = &*partial_resource.body.lock();
813                        let requested = match resource_body {
814                            ResponseBody::Done(body) => {
815                                let b = beginning as usize - res_beginning as usize;
816                                let e = end as usize - res_beginning as usize + 1;
817                                body.get(b..e)
818                            },
819                            _ => continue,
820                        };
821                        if let Some(bytes) = requested {
822                            let new_resource =
823                                create_resource_with_bytes_from_resource(bytes, partial_resource);
824                            let cached_response =
825                                create_cached_response(request, &new_resource, &headers, done_chan);
826                            if let Some(cached_response) = cached_response {
827                                return Some(cached_response);
828                            }
829                        }
830                    }
831                },
832
833                (Bound::Included(beginning), Bound::Unbounded) => {
834                    let (res_beginning, res_end, total) = if let Some(range) = content_range {
835                        match (range.bytes_range(), range.bytes_len()) {
836                            (Some(bytes_range), Some(total)) => {
837                                (bytes_range.0, bytes_range.1, total)
838                            },
839                            _ => continue,
840                        }
841                    } else {
842                        continue;
843                    };
844                    if total == 0 {
845                        // Prevent overflow in the below operations from occuring.
846                        continue;
847                    };
848                    if res_beginning <= beginning && res_end == total - 1 {
849                        let resource_body = &*partial_resource.body.lock();
850                        let requested = match resource_body {
851                            ResponseBody::Done(body) => {
852                                let from_byte = beginning as usize - res_beginning as usize;
853                                body.get(from_byte..)
854                            },
855                            _ => continue,
856                        };
857                        if let Some(bytes) = requested {
858                            if bytes.len() as u64 + beginning < total - 1 {
859                                // Requested range goes beyond the available range.
860                                continue;
861                            }
862                            let new_resource =
863                                create_resource_with_bytes_from_resource(bytes, partial_resource);
864                            let cached_response =
865                                create_cached_response(request, &new_resource, &headers, done_chan);
866                            if let Some(cached_response) = cached_response {
867                                return Some(cached_response);
868                            }
869                        }
870                    }
871                },
872
873                _ => continue,
874            }
875        }
876    }
877
878    None
879}
880
881/// Constructing Responses from Caches.
882/// <https://tools.ietf.org/html/rfc7234#section-4>
883pub(crate) fn construct_response(
884    request: &Request,
885    done_chan: &mut DoneChannel,
886    cache_result: &[CachedResource],
887) -> Option<CachedResponse> {
888    if pref!(network_http_cache_disabled) {
889        return None;
890    }
891
892    // TODO: generate warning headers as appropriate <https://tools.ietf.org/html/rfc7234#section-5.5>
893    debug!("trying to construct cache response for {:?}", request.url());
894    if request.method != Method::GET {
895        // Only Get requests are cached, avoid a url based match for others.
896        debug!("non-GET method, not caching");
897        return None;
898    }
899
900    let mut candidates: Vec<_> = cache_result
901        .iter()
902        .filter(|resource| resource.can_be_used_to_answer(request))
903        .collect();
904
905    // Support for range requests
906    if let Some(range_spec) = request.headers.typed_get::<Range>() {
907        return handle_range_request(request, candidates.as_slice(), &range_spec, done_chan);
908    }
909
910    while let Some(cached_resource) = candidates.pop() {
911        // Returning a response that can be constructed
912        // TODO: select the most appropriate one, using a known mechanism from a selecting header field,
913        // or using the Date header to return the most recent one.
914        let cached_headers = cached_resource.metadata.headers.read();
915        let cached_response =
916            create_cached_response(request, cached_resource, &cached_headers, done_chan);
917        if let Some(cached_response) = cached_response {
918            return Some(cached_response);
919        }
920    }
921    debug!("couldn't find an appropriate response, not caching");
922    // The cache wasn't able to construct anything.
923    None
924}
925
926/// Freshening Stored Responses upon Validation.
927/// <https://httpwg.org/specs/rfc9111.html#freshening.responses>
928pub fn refresh(
929    request: &Request,
930    response: Response,
931    done_chan: &mut DoneChannel,
932    cached_resources: &mut [CachedResource],
933) -> Option<Response> {
934    assert_eq!(response.status, StatusCode::NOT_MODIFIED);
935
936    // Refresh the last cached resource that can be used to answer the request.
937    // TODO: This should follow the rules specified in
938    // <https://httpwg.org/specs/rfc9111.html#freshening.responses> more closely.
939    let cached_resource_index = cached_resources
940        .iter()
941        .rposition(|resource| resource.can_be_used_to_answer(request))?;
942
943    let mut constructed_response = if let Some(range_spec) = request.headers.typed_get::<Range>() {
944        let cached_resources: Vec<_> = cached_resources
945            .iter()
946            .filter(|resource| resource.can_be_used_to_answer(request))
947            .collect();
948        handle_range_request(request, &cached_resources, &range_spec, done_chan)
949            .map(|cached_response| cached_response.response)
950    } else {
951        // done_chan will have been set to Some(..) by http_network_fetch.
952        // If the body is not receiving data, set the done_chan back to None.
953        // Otherwise, create a new dedicated channel to update the consumer.
954        // The response constructed here will replace the 304 one from the network.
955        let cached_resource = &mut cached_resources[cached_resource_index];
956        let in_progress_channel = match &*cached_resource.body.lock() {
957            ResponseBody::Receiving(..) => Some(unbounded()),
958            ResponseBody::Empty | ResponseBody::Done(..) => None,
959        };
960        match in_progress_channel {
961            Some((done_sender, done_receiver)) => {
962                *done_chan = Some((done_sender.clone(), done_receiver));
963                cached_resource.awaiting_body.lock().push(done_sender);
964            },
965            None => *done_chan = None,
966        }
967        // Received a response with 304 status code, in response to a request that matches a cached resource.
968        // 1. update the headers of the cached resource.
969        // 2. return a response, constructed from the cached resource.
970        let resource_timing = ResourceFetchTiming::new(request.timing_type());
971        let mut constructed_response =
972            Response::new(cached_resource.metadata.final_url.clone(), resource_timing);
973
974        constructed_response.body = cached_resource.body.clone();
975
976        constructed_response
977            .status
978            .clone_from(&cached_resource.status);
979        constructed_response.referrer = request.referrer.to_url().cloned();
980        constructed_response.referrer_policy = request.referrer_policy;
981        constructed_response
982            .status
983            .clone_from(&cached_resource.status);
984        constructed_response
985            .url_list
986            .clone_from(&cached_resource.url_list);
987        Some(constructed_response)
988    };
989
990    // Update cached Resource with response and constructed response.
991    if let Some(constructed_response) = constructed_response.as_mut() {
992        let cached_resource = &mut cached_resources[cached_resource_index];
993
994        // Bracket is to minimize lock duration.
995        {
996            let mut stored_headers = cached_resource.metadata.headers.write();
997            stored_headers.extend(response.headers);
998            constructed_response.headers = stored_headers.clone().into_inner();
999        }
1000        cached_resource.expires = get_response_expiry(constructed_response);
1001        cached_resource.stale_while_revalidate =
1002            get_stale_while_revalidate(&constructed_response.headers);
1003        cached_resource.last_validated = SystemTime::now();
1004    }
1005
1006    constructed_response
1007}
1008
1009pub(crate) fn invalidate_cached_resources(cached_resources: &mut [CachedResource]) {
1010    for cached_resource in cached_resources.iter_mut() {
1011        cached_resource.expires = ApproxDuration::zero();
1012    }
1013}
1014
1015fn resolve_location_url(
1016    request: &Request,
1017    response: &Response,
1018    header_name: header::HeaderName,
1019) -> Option<ServoUrl> {
1020    response
1021        .headers
1022        .get(header_name)
1023        .and_then(|value| value.to_str().ok())
1024        .and_then(|location| request.current_url().join(location).ok())
1025}
1026
1027impl HttpCache {
1028    /// Wake-up consumers of cached resources
1029    /// whose response body was still receiving data when the resource was constructed,
1030    /// and whose response has now either been completed or cancelled.
1031    pub(crate) async fn update_awaiting_consumers(&self, request: &Request, response: &Response) {
1032        let entry_key = CacheKey::new(request);
1033
1034        let cached_resources = match self.entries.get(&entry_key) {
1035            None => return,
1036            Some(resources) => resources,
1037        };
1038
1039        let actual_response = response.actual_response();
1040
1041        // Ensure we only wake-up consumers of relevant resources,
1042        // ie we don't want to wake-up 200 awaiting consumers with a 206.
1043        let lock = cached_resources.read().await;
1044        let relevant_cached_resources = lock.iter().filter(|resource| {
1045            if actual_response.is_network_error() {
1046                return *resource.body.lock() == ResponseBody::Empty;
1047            }
1048            resource.status == actual_response.status
1049        });
1050
1051        for cached_resource in relevant_cached_resources {
1052            let mut awaiting_consumers = cached_resource.awaiting_body.lock();
1053            if awaiting_consumers.is_empty() {
1054                continue;
1055            }
1056            let to_send = if cached_resource.aborted.load(Ordering::Acquire) {
1057                // In the case of an aborted fetch,
1058                // wake-up all awaiting consumers.
1059                // Each will then start a new network request.
1060                // TODO: Wake-up only one consumer, and make it the producer on which others wait.
1061                Data::Cancelled
1062            } else {
1063                match *cached_resource.body.lock() {
1064                    ResponseBody::Done(_) | ResponseBody::Empty => Data::Done,
1065                    ResponseBody::Receiving(_) => {
1066                        continue;
1067                    },
1068                }
1069            };
1070            for done_sender in awaiting_consumers.drain(..) {
1071                let _ = done_sender.send(to_send.clone());
1072            }
1073        }
1074    }
1075
1076    /// Returns descriptors for cache entries currently stored in this cache.
1077    pub(crate) fn cache_entry_descriptors(&self) -> Vec<CacheEntryDescriptor> {
1078        self.entries
1079            .iter()
1080            .map(|(key, _)| CacheEntryDescriptor::new(key.url.to_string()))
1081            .collect()
1082    }
1083
1084    /// Clear the contents of this cache.
1085    pub(crate) fn clear(&self) {
1086        self.entries.clear();
1087        if let Some(disk_cache) = &self.disk_cache {
1088            disk_cache.clear();
1089        }
1090    }
1091
1092    /// Insert a response for `request` into the cache (used by tests that need direct access).
1093    pub async fn store(&self, request: &Request, response: &Response) {
1094        let guard = self.get_or_guard(CacheKey::new(request)).await;
1095        guard.insert(request, response);
1096    }
1097
1098    /// Try to construct a cached response for `request`.
1099    pub async fn construct_response(
1100        &self,
1101        request: &Request,
1102        done_chan: &mut DoneChannel,
1103    ) -> Option<Response> {
1104        let entry = self.entries.get(&CacheKey::new(request))?;
1105        let cached_resources = entry.read().await;
1106        construct_response(request, done_chan, cached_resources.as_slice())
1107            .map(|cached| cached.response)
1108    }
1109
1110    /// Like [`construct_response`](Self::construct_response), but additionally
1111    /// reports the [`ValidationStatus`] of the constructed response.
1112    #[cfg(feature = "test-util")]
1113    pub async fn construct_response_freshness(
1114        &self,
1115        request: &Request,
1116        done_chan: &mut DoneChannel,
1117    ) -> Option<ValidationStatus> {
1118        let entry = self.entries.get(&CacheKey::new(request))?;
1119        let cached_resources = entry.read().await;
1120        construct_response(request, done_chan, cached_resources.as_slice())
1121            .map(|cached| cached.validation_status)
1122    }
1123
1124    /// Invalidate cache entries referenced by Location/Content-Location headers.
1125    pub(crate) async fn invalidate_related_urls(
1126        &self,
1127        request: &Request,
1128        response: &Response,
1129        skip_key: &CacheKey,
1130    ) {
1131        for header_name in &[header::LOCATION, header::CONTENT_LOCATION] {
1132            if let Some(location_url) = resolve_location_url(request, response, header_name.clone())
1133            {
1134                let location_key = CacheKey::from_url(location_url);
1135                if &location_key != skip_key {
1136                    self.invalidate_entry(&location_key).await;
1137                }
1138            }
1139        }
1140    }
1141
1142    async fn invalidate_entry(&self, key: &CacheKey) {
1143        if let Some(entry) = self.entries.get(key) {
1144            let mut guarded_resources = entry.write().await;
1145            invalidate_cached_resources(guarded_resources.as_mut_slice());
1146        }
1147    }
1148
1149    /// If the value exist in the cache, return it. If the value does not exist, return a guard you can use to insert values in the cache.
1150    /// If the guard is alive, all other accesses to this function will block.
1151    #[servo_tracing::instrument(skip(self))]
1152    pub async fn get_or_guard(&self, entry_key: CacheKey) -> CachedResourcesOrGuard<'_> {
1153        let guard_or_value = self.entries.get_value_or_guard_async(&entry_key).await;
1154        if let Ok(value) = guard_or_value {
1155            return CachedResourcesOrGuard::Value(value.write_owned().await);
1156        }
1157        let guard = guard_or_value.unwrap_err();
1158
1159        if let Some(disk_cache) = &self.disk_cache {
1160            if let Some(response) = disk_cache.get(entry_key).await {
1161                if guard.insert(response.clone()).is_err() {
1162                    error!(
1163                        "Cache guard is invalid. This should not happen. Cache will be in inconsistent state."
1164                    );
1165                }
1166                let response = response.write_owned().await;
1167                CachedResourcesOrGuard::Value(response)
1168            } else {
1169                CachedResourcesOrGuard::Guard(guard)
1170            }
1171        } else {
1172            CachedResourcesOrGuard::Guard(guard)
1173        }
1174    }
1175}
1176
1177/// Returns an writeable entry into the cache or a guard for insertint an entry
1178/// The guard will block other queries to the cache entry in both cases.
1179pub enum CachedResourcesOrGuard<'a> {
1180    /// The value of the resource in the cache.
1181    Value(OwnedRwLockWriteGuard<Vec<CachedResource>>),
1182    /// A guard that blocks requests to the cache entry this guard is for.
1183    Guard(QuickCachePlaceholderGuard<'a>),
1184}
1185
1186impl<'a> CachedResourcesOrGuard<'a> {
1187    /// Insert into the cache according to http spec
1188    pub fn insert(self, request: &Request, response: &Response) {
1189        if pref!(network_http_cache_disabled) {
1190            return;
1191        }
1192
1193        if request.method != Method::GET {
1194            // Only Get requests are cached.
1195            return;
1196        }
1197        if request.headers.contains_key(header::AUTHORIZATION) {
1198            // https://tools.ietf.org/html/rfc7234#section-3.1
1199            // A shared cache MUST NOT use a cached response
1200            // to a request with an Authorization header field
1201            //
1202            // TODO: unless a cache directive that allows such
1203            // responses to be stored is present in the response.
1204            return;
1205        };
1206        let Ok(metadata): Result<Metadata, _> = response.metadata().map(Into::into) else {
1207            return;
1208        };
1209        if !response_is_cacheable(&metadata) {
1210            return;
1211        }
1212        let expiry = get_response_expiry(response);
1213        let stale_while_revalidate = get_stale_while_revalidate(&response.headers);
1214        let cacheable_metadata = CachedMetadata {
1215            headers: Arc::new(ParkingLotRwLock::new(Serde(response.headers.clone()))),
1216            final_url: metadata.final_url,
1217            content_type: metadata.content_type,
1218            charset: metadata.charset,
1219            status: metadata.status,
1220        };
1221        let entry_resource = CachedResource {
1222            request_headers: Serde(request.headers.clone()),
1223            body: response.body.clone(),
1224            aborted: response.aborted.clone(),
1225            awaiting_body: Arc::new(ParkingLotMutex::new(vec![])),
1226            metadata: cacheable_metadata,
1227            location_url: response.location_url.clone(),
1228            status: response.status.clone(),
1229            url_list: response.url_list.clone(),
1230            expires: expiry,
1231            stale_while_revalidate,
1232            revalidating: StdArc::new(AtomicBool::new(false)),
1233            last_validated: SystemTime::now(),
1234        };
1235
1236        match self {
1237            CachedResourcesOrGuard::Value(mut cached_resources) => {
1238                // Ensure that any existing complete response is replaced by the new
1239                // complete response if the two responses match according to the fields
1240                // named in the `Vary` header.
1241                if response.status == StatusCode::OK {
1242                    cached_resources.retain(|cached_resource| {
1243                        cached_resource.status != StatusCode::OK ||
1244                            !cached_resource.is_done() ||
1245                            !cached_resource.vary_header_matches(&request.headers)
1246                    });
1247                }
1248
1249                cached_resources.push(entry_resource);
1250            },
1251            CachedResourcesOrGuard::Guard(placeholder_guard) => {
1252                if placeholder_guard
1253                    .insert(std::sync::Arc::new(TokioRwLock::new(vec![entry_resource])))
1254                    .is_err()
1255                {
1256                    error!("Could not insert into cache");
1257                }
1258            },
1259        }
1260    }
1261
1262    /// If the guard is a value, return it as a mut reference. If the guard is a guard, return None
1263    pub fn try_as_mut(&mut self) -> Option<&mut Vec<CachedResource>> {
1264        match self {
1265            CachedResourcesOrGuard::Value(owned_rw_lock_write_guard) => {
1266                Some(owned_rw_lock_write_guard.as_mut())
1267            },
1268            CachedResourcesOrGuard::Guard(_) => None,
1269        }
1270    }
1271}