http-cache-semantics-2.1.0/.cargo_vcs_info.json0000644000000001360000000000100150400ustar { "git": { "sha1": "812484632b17fbeb36e9b6427cfc4a97eff5d3c1" }, "path_in_vcs": "" }http-cache-semantics-2.1.0/Cargo.toml0000644000000036700000000000100130440ustar # THIS FILE IS AUTOMATICALLY GENERATED BY CARGO # # When uploading crates to the registry Cargo will automatically # "normalize" Cargo.toml files for maximal compatibility # with all versions of Cargo and also rewrite `path` dependencies # to registry (e.g., crates.io) dependencies. # # If you are reading this file be aware that the original Cargo.toml # will likely look very different (and much more reasonable). # See Cargo.toml.orig for the original contents. [package] edition = "2021" rust-version = "1.64" name = "http-cache-semantics" version = "2.1.0" authors = [ "Kornel ", "Luna Graysen ", "Douglas Greenshields ", "Kat Marchán ", ] include = [ "Cargo.toml", "README.md", "src/*.rs", "LICENSE", ] description = "RFC 7234. Parses HTTP headers to correctly compute cacheability of responses, even in complex cases" homepage = "https://lib.rs/http-cache-semantics" documentation = "https://docs.rs/http-cache-semantics" readme = "README.md" keywords = [ "http", "cache", "headers", "cache-control", "proxy", ] categories = [ "caching", "web-programming::http-client", ] license = "BSD-2-Clause" repository = "https://github.com/kornelski/rusty-http-cache-semantics" [package.metadata.docs.rs] rustdoc-args = ["--generate-link-to-definition"] targets = ["x86_64-unknown-linux-gnu"] [dependencies.http] version = "1.0.0" [dependencies.http-serde] version = "2.0.0" optional = true [dependencies.reqwest] version = "0.12" optional = true default-features = false [dependencies.serde] version = "1.0.193" features = ["derive"] optional = true [dependencies.time] version = "0.3.20" features = [ "parsing", "formatting", ] [dev-dependencies.serde_json] version = "1.0.108" [features] default = ["serde"] serde = [ "dep:serde", "dep:http-serde", ] [badges.maintenance] status = "passively-maintained" http-cache-semantics-2.1.0/Cargo.toml.orig000064400000000000000000000025331046102023000165220ustar 00000000000000[package] name = "http-cache-semantics" version = "2.1.0" description = "RFC 7234. Parses HTTP headers to correctly compute cacheability of responses, even in complex cases" homepage = "https://lib.rs/http-cache-semantics" repository = "https://github.com/kornelski/rusty-http-cache-semantics" documentation = "https://docs.rs/http-cache-semantics" license = "BSD-2-Clause" authors = ["Kornel ", "Luna Graysen ", "Douglas Greenshields ", "Kat Marchán "] edition = "2021" categories = ["caching", "web-programming::http-client"] keywords = ["http", "cache", "headers", "cache-control", "proxy"] include = ["Cargo.toml", "README.md", "src/*.rs", "LICENSE"] readme = "README.md" rust-version = "1.64" [dependencies] http = "1.0.0" http-serde = { version = "2.0.0", optional = true } serde = { version = "1.0.193", optional = true, features = ["derive"] } reqwest = { version = "0.12", default-features = false, optional = true } time = { version = "0.3.20", features = ["parsing", "formatting"] } [dev-dependencies] serde_json = "1.0.108" [features] default = ["serde"] serde = ["dep:serde", "dep:http-serde"] [package.metadata.docs.rs] targets = ["x86_64-unknown-linux-gnu"] rustdoc-args = ["--generate-link-to-definition"] [badges] maintenance = { status = "passively-maintained" } http-cache-semantics-2.1.0/LICENSE000064400000000000000000000023721046102023000146410ustar 00000000000000Copyright 2016-2020 Kornel Lesiński Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. http-cache-semantics-2.1.0/README.md000064400000000000000000000115621046102023000151140ustar 00000000000000# Can I cache this? `CachePolicy` tells when responses can be reused from a cache, taking into account [HTTP RFC 7234/9111](http://httpwg.org/specs/rfc9111.html) rules for user agents and shared caches. It's aware of many tricky details such as the `Vary` header, age updates, proxy revalidation, and authenticated responses. ## Usage Cacheability of an HTTP response depends on how it was requested, so both `request` and `response` are required to create the policy. It may be surprising, but it's not enough for an HTTP response to be [fresh](#yo-fresh) to satisfy a request. It may need to match request headers specified in `Vary`. Even a matching fresh response may still not be usable if the new request restricted cacheability, etc. The key method is `before_request(new_request)`, which checks whether the `new_request` is compatible with the original request and whether all caching conditions are met. ### Options If `options.shared` is `true` (default), then the response is evaluated from a perspective of a shared cache (i.e. `private` is not cacheable and `s-maxage` is respected). If `options.shared` is `false`, then the response is evaluated from a perspective of a single-user cache (i.e. `private` is cacheable and `s-maxage` is ignored). `shared: true` is recommended for HTTP proxies, and `false` for single-user clients. `options.cache_heuristic` is a fraction of response's age that is used as a fallback cache duration. The default is 0.1 (10%), e.g. if a file hasn't been modified for 100 days, it'll be cached for 100×0.1 = 10 days. `options.immutable_min_time_to_live` is a duration to assume as the default time to cache responses with `Cache-Control: immutable`. Note that [per RFC](http://httpwg.org/http-extensions/immutable.html) these can become stale, so `max-age` still overrides the default. If `options.ignore_cargo_cult` is true, common anti-cache directives will be completely ignored if the non-standard `pre-check` and `post-check` directives are present. These two useless directives are most commonly found in bad StackOverflow answers and PHP's "session limiter" defaults. ### `is_storable()` Returns `true` if the response can be stored in a cache. If it's `false` then you MUST NOT store either the request or the response. ### `before_request(new_request)` This is the most important method. Use this method to check whether the cached response is still fresh in the context of the new request. If it returns `Fresh`, then the given `request` matches the original response this cache policy has been created with, and the response can be reused without contacting the server. This will contain an updated, filtered set of response headers to return to clients receiving the cached response. This processing is necessary, because proxies MUST always remove hop-by-hop headers (such as `TE` and `Connection`) and update response's `Age` to avoid doubling cache time. If it returns `Stale`, then the response may not be matching at all (e.g. it's for a different URL or method), or may require to be refreshed first. The variant will contain HTTP headers for making a revalidation request to the server. ### `time_to_live()` Returns approximate time until the response becomes stale (i.e. not fresh). This is equivalent of `max-age`, but with appropriate time correction applied. After that time (when `time_to_live() == Duration::ZERO`) the response might not be usable without revalidation. However, there are exceptions, e.g. a client can explicitly allow stale responses, so always check with `before_request()`. ### Refreshing stale cache (revalidation) When a cached response has expired, it can be made fresh again by making a request to the origin server. The server may respond with status 304 (Not Modified) without sending the response body again, saving bandwidth. #### `after_response(revalidation_request, revalidation_response)` Use this method to update the cache after receiving a new response from the origin server. It returns `Modified`/`NotModified` object with a new `CachePolicy` with HTTP headers updated from `revalidation_response`. You can always replace the old cached `CachePolicy` with the new one. - If `NotModified`, then a valid 304 Not Modified response has been received, and you can reuse the old cached response body. - If `Modified`, you should replace the old cached body with the new response's body. # Yo, FRESH ![satisfies_without_revalidation](fresh.jpg) ## Implemented - `Cache-Control` response header with all the quirks. - `Expires` with check for bad clocks. - `Pragma` response header. - `Age` response header. - `Vary` response header. - Default cacheability of statuses and methods. - Requests for stale data. - Filtering of hop-by-hop headers. - Basic revalidation request ## Unimplemented - Merging of range requests, If-Range (but correctly supports them as non-cacheable) - Revalidation of multiple representations http-cache-semantics-2.1.0/src/lib.rs000064400000000000000000001070001046102023000155310ustar 00000000000000#![warn(missing_docs)] #![deny(unconditional_recursion)] //! Tells when responses can be reused from a cache, taking into account [HTTP RFC 7234](http://httpwg.org/specs/rfc7234.html) rules for user agents and shared caches. //! It's aware of many tricky details such as the `Vary` header, proxy revalidation, and authenticated responses. use http::HeaderMap; use http::HeaderValue; use http::Method; use http::Request; use http::Response; use http::StatusCode; use http::Uri; use std::collections::hash_map::Entry; use std::collections::HashMap; use std::time::Duration; use std::time::SystemTime; use time::format_description::well_known::Rfc2822; use time::OffsetDateTime; // rfc7231 6.1 const STATUS_CODE_CACHEABLE_BY_DEFAULT: &[u16] = &[200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 501]; // This implementation does not understand partial responses (206) const UNDERSTOOD_STATUSES: &[u16] = &[ 200, 203, 204, 300, 301, 302, 303, 307, 308, 404, 405, 410, 414, 501, ]; const HOP_BY_HOP_HEADERS: &[&str] = &[ "date", // included, because we add Age update Date "connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "transfer-encoding", "upgrade", ]; const EXCLUDED_FROM_REVALIDATION_UPDATE: &[&str] = &[ // Since the old body is reused, it doesn't make sense to change properties of the body "content-length", "content-encoding", "transfer-encoding", "content-range", ]; type CacheControl = HashMap, Option>>; fn parse_cache_control<'a>(headers: impl IntoIterator) -> CacheControl { let mut cc = CacheControl::new(); let mut is_valid = true; for h in headers.into_iter().filter_map(|v| v.to_str().ok()) { for part in h.split(',') { // TODO: lame parsing if part.trim().is_empty() { continue; } let mut kv = part.splitn(2, '='); let k = kv.next().unwrap().trim(); if k.is_empty() { continue; } let v = kv.next().map(str::trim); match cc.entry(k.into()) { Entry::Occupied(e) => { // When there is more than one value present for a given directive (e.g., two Expires header fields, multiple Cache-Control: max-age directives), // the directive's value is considered invalid. Caches are encouraged to consider responses that have invalid freshness information to be stale if e.get().as_deref() != v { is_valid = false; } } Entry::Vacant(e) => { e.insert(v.map(|v| v.trim_matches('"')).map(From::from)); // TODO: bad unquoting } } } } if !is_valid { cc.insert("must-revalidate".into(), None); } cc } fn format_cache_control(cc: &CacheControl) -> String { let mut out = String::new(); for (k, v) in cc { if !out.is_empty() { out.push_str(", "); } out.push_str(k); if let Some(v) = v { out.push('='); let needs_quote = v.is_empty() || v.as_bytes().iter().any(|b| !b.is_ascii_alphanumeric()); if needs_quote { out.push('"'); } out.push_str(v); if needs_quote { out.push('"'); } } } out } /// Configuration options which control behavior of the cache. Use with `CachePolicy::new_options()`. #[derive(Debug, Copy, Clone)] #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] pub struct CacheOptions { /// If `true` (default), then the response is evaluated from a /// perspective of a shared cache (i.e. `private` is not cacheable and /// `s-maxage` is respected). If `shared` is `false`, then the response is /// evaluated from a perspective of a single-user cache (i.e. `private` is /// cacheable and `s-maxage` is ignored). `shared: true` is required /// for proxies and multi-user caches. pub shared: bool, /// `cache_heuristic` is a fraction of response's age that is used as a /// fallback cache duration. The default is 0.1 (10%), e.g. if a file /// hasn't been modified for 100 days, it'll be cached for 100×0.1 = 10 /// days. pub cache_heuristic: f32, /// `immutable_min_time_to_live` is a duration to assume as the /// default time to cache responses with `Cache-Control: immutable`. Note /// that per RFC these can become stale, so `max-age` still overrides the /// default. pub immutable_min_time_to_live: Duration, /// If `ignore_cargo_cult` is `true`, common anti-cache directives will be /// completely ignored if the non-standard `pre-check` and `post-check` /// directives are present. These two useless directives are most commonly /// found in bad StackOverflow answers and PHP's "session limiter" /// defaults. pub ignore_cargo_cult: bool, } impl Default for CacheOptions { fn default() -> Self { Self { shared: true, cache_heuristic: 0.1, // 10% matches IE immutable_min_time_to_live: Duration::from_secs(24 * 3600), ignore_cargo_cult: false, } } } /// Identifies when responses can be reused from a cache, taking into account /// HTTP RFC 7234 rules for user agents and shared caches. It's aware of many /// tricky details such as the Vary header, proxy revalidation, and /// authenticated responses. #[derive(Debug, Clone)] #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] pub struct CachePolicy { #[cfg_attr(feature = "serde", serde(with = "http_serde::header_map"))] req: HeaderMap, #[cfg_attr(feature = "serde", serde(with = "http_serde::header_map"))] res: HeaderMap, #[cfg_attr(feature = "serde", serde(with = "http_serde::uri"))] uri: Uri, #[cfg_attr(feature = "serde", serde(with = "http_serde::status_code"))] status: StatusCode, #[cfg_attr(feature = "serde", serde(with = "http_serde::method"))] method: Method, opts: CacheOptions, res_cc: CacheControl, req_cc: CacheControl, response_time: SystemTime, } impl CachePolicy { /// Cacheability of an HTTP response depends on how it was requested, so /// both request and response are required to create the policy. #[inline] pub fn new(req: &Req, res: &Res) -> Self { let uri = req.uri(); let status = res.status(); let method = req.method().clone(); let res = res.headers().clone(); let req = req.headers().clone(); Self::from_details( uri, method, status, req, res, SystemTime::now(), Default::default(), ) } /// Caching with customized behavior. See `CacheOptions` for details. /// /// `response_time` is a timestamp when the response has been received, usually `SystemTime::now()`. #[inline] pub fn new_options( req: &Req, res: &Res, response_time: SystemTime, opts: CacheOptions, ) -> Self { let uri = req.uri(); let status = res.status(); let method = req.method().clone(); let res = res.headers().clone(); let req = req.headers().clone(); Self::from_details(uri, method, status, req, res, response_time, opts) } fn from_details( uri: Uri, method: Method, status: StatusCode, req: HeaderMap, mut res: HeaderMap, response_time: SystemTime, opts: CacheOptions, ) -> Self { let mut res_cc = parse_cache_control(res.get_all("cache-control")); let req_cc = parse_cache_control(req.get_all("cache-control")); // Assume that if someone uses legacy, non-standard uncecessary options they don't understand caching, // so there's no point stricly adhering to the blindly copy&pasted directives. if opts.ignore_cargo_cult && res_cc.get("pre-check").is_some() && res_cc.get("post-check").is_some() { res_cc.remove("pre-check"); res_cc.remove("post-check"); res_cc.remove("no-cache"); res_cc.remove("no-store"); res_cc.remove("must-revalidate"); res.insert( "cache-control", HeaderValue::from_str(&format_cache_control(&res_cc)).unwrap(), ); res.remove("expires"); res.remove("pragma"); } // When the Cache-Control header field is not present in a request, caches MUST consider the no-cache request pragma-directive // as having the same effect as if "Cache-Control: no-cache" were present (see Section 5.2.1). if !res.contains_key("cache-control") && res .get_str("pragma") .map_or(false, |p| p.contains("no-cache")) { res_cc.insert("no-cache".into(), None); } Self { req, res, uri, status, method, opts, res_cc, req_cc, response_time } } /// Returns `true` if the response can be stored in a cache. If it's /// `false` then you MUST NOT store either the request or the response. pub fn is_storable(&self) -> bool { // The "no-store" request directive indicates that a cache MUST NOT store any part of either this request or any response to it. !self.req_cc.contains_key("no-store") && // A cache MUST NOT store a response to any request, unless: // The request method is understood by the cache and defined as being cacheable, and (Method::GET == self.method || Method::HEAD == self.method || (Method::POST == self.method && self.has_explicit_expiration())) && // the response status code is understood by the cache, and UNDERSTOOD_STATUSES.contains(&self.status.as_u16()) && // the "no-store" cache directive does not appear in request or response header fields, and !self.res_cc.contains_key("no-store") && // the "private" response directive does not appear in the response, if the cache is shared, and (!self.opts.shared || !self.res_cc.contains_key("private")) && // the Authorization header field does not appear in the request, if the cache is shared, (!self.opts.shared || !self.req.contains_key("authorization") || self.allows_storing_authenticated()) && // the response either: // contains an Expires header field, or (self.res.contains_key("expires") || // contains a max-age response directive, or // contains a s-maxage response directive and the cache is shared, or // contains a public response directive. self.res_cc.contains_key("max-age") || (self.opts.shared && self.res_cc.contains_key("s-maxage")) || self.res_cc.contains_key("public") || // has a status code that is defined as cacheable by default STATUS_CODE_CACHEABLE_BY_DEFAULT.contains(&self.status.as_u16())) } fn has_explicit_expiration(&self) -> bool { // 4.2.1 Calculating Freshness Lifetime (self.opts.shared && self.res_cc.contains_key("s-maxage")) || self.res_cc.contains_key("max-age") || self.res.contains_key("expires") } /// Returns whether the cached response is still fresh in the context of /// the new request. /// /// If it returns `Fresh`, then the given request matches the original /// response this cache policy has been created with, and the response can /// be reused without contacting the server. /// /// If it returns `Stale`, then the response may not be matching at all /// (e.g. it's for a different URL or method), or may require to be /// refreshed first. Either way, the new request's headers will have been /// updated for sending it to the origin server. pub fn before_request(&self, req: &Req, now: SystemTime) -> BeforeRequest { let req_headers = req.headers(); // revalidation allowed via HEAD let (matches, may_revalidate) = self.request_matches(req); if matches && self.satisfies_without_revalidation(req_headers, now) { BeforeRequest::Fresh(self.cached_response(now)) } else if may_revalidate { BeforeRequest::Stale { request: self.revalidation_request(req), matches, } } else { BeforeRequest::Stale { request: self.request_from_headers(req_headers.clone()), matches, } } } fn satisfies_without_revalidation(&self, req_headers: &HeaderMap, now: SystemTime) -> bool { // When presented with a request, a cache MUST NOT reuse a stored response, unless: // the presented request does not contain the no-cache pragma (Section 5.4), nor the no-cache cache directive, // unless the stored response is successfully validated (Section 4.3), and let req_cc = parse_cache_control(req_headers.get_all("cache-control")); if req_cc.contains_key("no-cache") || req_headers .get_str("pragma") .map_or(false, |v| v.contains("no-cache")) { return false; } if let Some(max_age) = req_cc .get("max-age") .and_then(|v| v.as_ref()) .and_then(|p| p.parse().ok()) { if self.age(now) > Duration::from_secs(max_age) { return false; } } if let Some(min_fresh) = req_cc .get("min-fresh") .and_then(|v| v.as_ref()) .and_then(|p| p.parse().ok()) { if self.time_to_live(now) < Duration::from_secs(min_fresh) { return false; } } // the stored response is either: // fresh, or allowed to be served stale if self.is_stale(now) { // If no value is assigned to max-stale, then the client is willing to accept a stale response of any age. let max_stale = req_cc.get("max-stale"); let has_max_stale = max_stale.is_some(); let max_stale = max_stale .and_then(|m| m.as_ref()) .and_then(|s| s.parse().ok()); let allows_stale = !self.res_cc.contains_key("must-revalidate") && has_max_stale && max_stale.map_or(true, |val| { Duration::from_secs(val) > self.age(now) - self.max_age() }); if !allows_stale { return false; } } true } /// returns: matches including method, matches allowing head fn request_matches(&self, req: &Req) -> (bool, bool) { // The presented effective request URI and that of the stored response match, and let matches = req.is_same_uri(&self.uri) && (self.req.get("host") == req.headers().get("host")) && // selecting header fields nominated by the stored response (if any) match those presented, and self.vary_matches(req); let exact_match = matches && self.method == req.method(); // the request method associated with the stored response allows it to be used for the presented request, and (exact_match, exact_match || Method::HEAD == req.method()) } fn allows_storing_authenticated(&self) -> bool { // following Cache-Control response directives (Section 5.2.2) have such an effect: must-revalidate, public, and s-maxage. self.res_cc.contains_key("must-revalidate") || self.res_cc.contains_key("public") || self.res_cc.contains_key("s-maxage") } fn vary_matches(&self, req: &Req) -> bool { for name in get_all_comma(self.res.get_all("vary")) { // A Vary header field-value of "*" always fails to match if name == "*" { return false; } let name = name.trim().to_ascii_lowercase(); if req.headers().get(&name) != self.req.get(&name) { return false; } } true } fn copy_without_hop_by_hop_headers(in_headers: &HeaderMap) -> HeaderMap { let mut headers = HeaderMap::with_capacity(in_headers.len()); for (h, v) in in_headers .iter() .filter(|(h, _)| !HOP_BY_HOP_HEADERS.contains(&h.as_str())) { headers.insert(h.clone(), v.clone()); } // 9.1. Connection for name in get_all_comma(in_headers.get_all("connection")) { headers.remove(name); } let new_warnings = join( get_all_comma(in_headers.get_all("warning")).filter(|warning| { !warning.trim_start().starts_with('1') // FIXME: match 100-199, not 1 or 1000 }), ); if new_warnings.is_empty() { headers.remove("warning"); } else { headers.insert("warning", HeaderValue::from_str(&new_warnings).unwrap()); } headers } /// Updates and filters the response headers for a cached response before /// returning it to a client. This function is necessary, because proxies /// MUST always remove hop-by-hop headers (such as TE and Connection) and /// update response's Age to avoid doubling cache time. /// /// It returns response "parts" without a body. You can upgrade it to a full /// response with `Response::from_parts(parts, BYOB)` fn cached_response(&self, now: SystemTime) -> http::response::Parts { let mut headers = Self::copy_without_hop_by_hop_headers(&self.res); let age = self.age(now); let day = Duration::from_secs(3600 * 24); // A cache SHOULD generate 113 warning if it heuristically chose a freshness // lifetime greater than 24 hours and the response's age is greater than 24 hours. if age > day && !self.has_explicit_expiration() && self.max_age() > day { headers.append( "warning", HeaderValue::from_static(r#"113 - "rfc7234 5.5.4""#), ); } let date = OffsetDateTime::from(now); headers.insert( "age", HeaderValue::from_str(&age.as_secs().to_string()).unwrap(), ); headers.insert( "date", HeaderValue::from_str(&date.format(&Rfc2822).unwrap()).unwrap(), ); let mut parts = Response::builder() .status(self.status) .body(()) .unwrap() .into_parts().0; parts.headers = headers; parts } fn raw_server_date(&self) -> SystemTime { let date = self .res .get_str("date") .and_then(|d| OffsetDateTime::parse(d, &Rfc2822).ok()) .and_then(|d| { SystemTime::UNIX_EPOCH.checked_add(Duration::from_secs(d.unix_timestamp() as u64)) }); date.unwrap_or(self.response_time) } /// Tells how long the response has been sitting in cache(s). /// /// Value of the `Age` header, updated for the current time. pub fn age(&self, now: SystemTime) -> Duration { let mut age = self.age_header_value(); if let Ok(resident_time) = now.duration_since(self.response_time) { age += resident_time; } age } fn age_header_value(&self) -> Duration { Duration::from_secs( self.res .get_str("age") .and_then(|v| v.parse().ok()) .unwrap_or(0), ) } /// Value of applicable max-age (or heuristic equivalent) in seconds. /// /// This counts since response's `Date` - `Age`. /// /// For an up-to-date value, see `time_to_live()`. fn max_age(&self) -> Duration { if !self.is_storable() || self.res_cc.contains_key("no-cache") { return Duration::from_secs(0); } // Shared responses with cookies are cacheable according to the RFC, but IMHO it'd be unwise to do so by default // so this implementation requires explicit opt-in via public header if self.opts.shared && (self.res.contains_key("set-cookie") && !self.res_cc.contains_key("public") && !self.res_cc.contains_key("immutable")) { return Duration::from_secs(0); } if self.res.get_str("vary").map(str::trim) == Some("*") { return Duration::from_secs(0); } if self.opts.shared { if self.res_cc.contains_key("proxy-revalidate") { return Duration::from_secs(0); } // if a response includes the s-maxage directive, a shared cache recipient MUST ignore the Expires field. if let Some(s_max) = self.res_cc.get("s-maxage").and_then(|v| v.as_ref()) { return Duration::from_secs(s_max.parse().unwrap_or(0)); } } // If a response includes a Cache-Control field with the max-age directive, a recipient MUST ignore the Expires field. if let Some(max_age) = self.res_cc.get("max-age").and_then(|v| v.as_ref()) { return Duration::from_secs(max_age.parse().unwrap_or(0)); } let default_min_ttl = if self.res_cc.contains_key("immutable") { self.opts.immutable_min_time_to_live } else { Duration::from_secs(0) }; let server_date = self.raw_server_date(); if let Some(expires) = self.res.get_str("expires") { return match OffsetDateTime::parse(expires, &Rfc2822) { // A cache recipient MUST interpret invalid date formats, especially the value "0", as representing a time in the past (i.e., "already expired"). Err(_) => Duration::from_secs(0), Ok(expires) => { let expires = SystemTime::UNIX_EPOCH + Duration::from_secs(expires.unix_timestamp().max(0) as _); return default_min_ttl .max(expires.duration_since(server_date).unwrap_or_default()); } }; } if let Some(last_modified) = self.res.get_str("last-modified") { if let Ok(last_modified) = OffsetDateTime::parse(last_modified, &Rfc2822) { let last_modified = SystemTime::UNIX_EPOCH + Duration::from_secs(last_modified.unix_timestamp().max(0) as _); if let Ok(diff) = server_date.duration_since(last_modified) { let secs_left = diff.as_secs() as f64 * f64::from(self.opts.cache_heuristic); return default_min_ttl.max(Duration::from_secs(secs_left as _)); } } } default_min_ttl } /// Returns approximate time until the response becomes /// stale (i.e. not fresh). This is the correct way of getting the current `max-age` value. /// /// After that time (when `time_to_live() == Duration::ZERO`) the response might not be /// usable without revalidation. However, there are exceptions, e.g. a /// client can explicitly allow stale responses, so always check with /// `before_request()`. /// /// If you're storing responses in a cache/database, keep them approximately for /// the `time_to_live` duration plus some extra time to allow for revalidation /// (an expired response is still useful). pub fn time_to_live(&self, now: SystemTime) -> Duration { self.max_age() .checked_sub(self.age(now)) .unwrap_or_default() } /// Stale responses shouldn't be used without contacting the server (revalidation) pub fn is_stale(&self, now: SystemTime) -> bool { self.max_age() <= self.age(now) } /// Headers for sending to the origin server to revalidate stale response. /// Allows server to return 304 to allow reuse of the previous response. /// /// Hop by hop headers are always stripped. /// Revalidation headers may be added or removed, depending on request. /// /// It returns request "parts" without a body. You can upgrade it to a full /// response with `Request::from_parts(parts, BYOB)` (the body is usually `()`). /// /// You don't need this if you use [`before_request()`] fn revalidation_request(&self, incoming_req: &Req) -> http::request::Parts { let mut headers = Self::copy_without_hop_by_hop_headers(incoming_req.headers()); // This implementation does not understand range requests headers.remove("if-range"); if !self.is_storable() { // not for the same resource, or wasn't allowed to be cached anyway headers.remove("if-none-match"); headers.remove("if-modified-since"); return self.request_from_headers(headers); } /* MUST send that entity-tag in any cache validation request (using If-Match or If-None-Match) if an entity-tag has been provided by the origin server. */ if let Some(etag) = self.res.get_str("etag") { let if_none = join(get_all_comma(headers.get_all("if-none-match")).chain(Some(etag))); headers.insert("if-none-match", HeaderValue::from_str(&if_none).unwrap()); } // Clients MAY issue simple (non-subrange) GET requests with either weak validators or strong validators. Clients MUST NOT use weak validators in other forms of request. let forbids_weak_validators = self.method != Method::GET || headers.contains_key("accept-ranges") || headers.contains_key("if-match") || headers.contains_key("if-unmodified-since"); /* SHOULD send the Last-Modified value in non-subrange cache validation requests (using If-Modified-Since) if only a Last-Modified value has been provided by the origin server. Note: This implementation does not understand partial responses (206) */ if forbids_weak_validators { headers.remove("if-modified-since"); let etags = join( get_all_comma(headers.get_all("if-none-match")) .filter(|etag| !etag.trim_start().starts_with("W/")), ); if etags.is_empty() { headers.remove("if-none-match"); } else { headers.insert("if-none-match", HeaderValue::from_str(&etags).unwrap()); } } else if !headers.contains_key("if-modified-since") { if let Some(last_modified) = self.res.get_str("last-modified") { headers.insert( "if-modified-since", HeaderValue::from_str(last_modified).unwrap(), ); } } self.request_from_headers(headers) } fn request_from_headers(&self, headers: HeaderMap) -> http::request::Parts { let mut parts = Request::builder() .method(self.method.clone()) .uri(self.uri.clone()) .body(()) .unwrap() .into_parts().0; parts.headers = headers; parts } /// Creates `CachePolicy` with information combined from the previews response, /// and the new revalidation response. /// /// Returns `{policy, modified}` where modified is a boolean indicating /// whether the response body has been modified, and old cached body can't be used. pub fn after_response( &self, request: &Req, response: &Res, response_time: SystemTime, ) -> AfterResponse { let response_headers = response.headers(); let mut response_status = response.status(); let old_etag = &self.res.get_str("etag").map(str::trim); let old_last_modified = response_headers.get_str("last-modified").map(str::trim); let new_etag = response_headers.get_str("etag").map(str::trim); let new_last_modified = response_headers.get_str("last-modified").map(str::trim); // These aren't going to be supported exactly, since one CachePolicy object // doesn't know about all the other cached objects. let mut matches = false; if response.status() != StatusCode::NOT_MODIFIED { matches = false; } else if new_etag.map_or(false, |etag| !etag.starts_with("W/")) { // "All of the stored responses with the same strong validator are selected. // If none of the stored responses contain the same strong validator, // then the cache MUST NOT use the new response to update any stored responses." matches = old_etag.map(|e| e.trim_start_matches("W/")) == new_etag; } else if let (Some(old), Some(new)) = (old_etag, new_etag) { // "If the new response contains a weak validator and that validator corresponds // to one of the cache's stored responses, // then the most recent of those matching stored responses is selected for update." matches = old.trim_start_matches("W/") == new.trim_start_matches("W/"); } else if old_last_modified.is_some() { matches = old_last_modified == new_last_modified; } else { // If the new response does not include any form of validator (such as in the case where // a client generates an If-Modified-Since request from a source other than the Last-Modified // response header field), and there is only one stored response, and that stored response also // lacks a validator, then that stored response is selected for update. if old_etag.is_none() && new_etag.is_none() && old_last_modified.is_none() && new_last_modified.is_none() { matches = true; } } let new_response_headers = if matches { let mut new_response_headers = HeaderMap::with_capacity(self.res.keys_len()); // use other header fields provided in the 304 (Not Modified) response to replace all instances // of the corresponding header fields in the stored response. for (header, old_value) in &self.res { let header = header.clone(); if let Some(new_value) = response_headers.get(&header) { if !EXCLUDED_FROM_REVALIDATION_UPDATE.contains(&header.as_str()) { new_response_headers.insert(header, new_value.clone()); continue; } } new_response_headers.insert(header, old_value.clone()); } response_status = self.status; new_response_headers } else { response_headers.clone() }; let new_policy = CachePolicy::from_details( request.uri(), request.method().clone(), response_status, request.headers().clone(), new_response_headers, response_time, self.opts, ); let new_response = new_policy.cached_response(response_time); if matches && response.status() == StatusCode::NOT_MODIFIED { AfterResponse::NotModified(new_policy, new_response) } else { AfterResponse::Modified(new_policy, new_response) } } } /// New policy and flags to act on `after_response()` pub enum AfterResponse { /// You can use the cached body! Make sure to use these updated headers NotModified(CachePolicy, http::response::Parts), /// You need to update the body in the cache Modified(CachePolicy, http::response::Parts), } fn get_all_comma<'a>( all: impl IntoIterator, ) -> impl Iterator { all.into_iter() .filter_map(|v| v.to_str().ok()) .flat_map(|s| s.split(',').map(str::trim)) } trait GetHeaderStr { fn get_str(&self, k: &str) -> Option<&str>; } impl GetHeaderStr for HeaderMap { #[inline] fn get_str(&self, k: &str) -> Option<&str> { self.get(k).and_then(|v| v.to_str().ok()) } } fn join<'a>(parts: impl Iterator) -> String { let mut out = String::new(); for part in parts { out.reserve(2 + part.len()); if !out.is_empty() { out.push_str(", "); } out.push_str(part); } out } /// Next action suggested after `before_request()` pub enum BeforeRequest { /// Good news! You can use it with body from the cache. No need to contact the server. Fresh(http::response::Parts), /// You must send the request to the server first. Stale { /// Send this request to the server (it has added revalidation headers when appropriate) request: http::request::Parts, /// If `false`, request was for some other resource that isn't /// semantically the same as previously cached request+response matches: bool, }, } impl BeforeRequest { /// For backwards compatibility only. /// Don't forget to use request headers from `BeforeRequest::Fresh` pub fn satisfies_without_revalidation(&self) -> bool { matches!(self, Self::Fresh(_)) } } /// Allows using either `Request` or `request::Parts`, or your own newtype. pub trait RequestLike { /// Same as `req.uri().clone()` fn uri(&self) -> Uri; /// Whether the effective request URI matches the other URI /// /// It can be naive string comparison, nothing fancy fn is_same_uri(&self, other: &Uri) -> bool; /// Same as `req.method()` fn method(&self) -> &Method; /// Same as `req.headers()` fn headers(&self) -> &HeaderMap; } /// Allows using either `Response` or `response::Parts`, or your own newtype. pub trait ResponseLike { /// Same as `res.status()` fn status(&self) -> StatusCode; /// Same as `res.headers()` fn headers(&self) -> &HeaderMap; } impl RequestLike for Request { fn uri(&self) -> Uri { self.uri().clone() } fn is_same_uri(&self, other: &Uri) -> bool { self.uri() == other } fn method(&self) -> &Method { self.method() } fn headers(&self) -> &HeaderMap { self.headers() } } impl RequestLike for http::request::Parts { fn uri(&self) -> Uri { self.uri.clone() } fn is_same_uri(&self, other: &Uri) -> bool { &self.uri == other } fn method(&self) -> &Method { &self.method } fn headers(&self) -> &HeaderMap { &self.headers } } impl ResponseLike for Response { fn status(&self) -> StatusCode { self.status() } fn headers(&self) -> &HeaderMap { self.headers() } } impl ResponseLike for http::response::Parts { fn status(&self) -> StatusCode { self.status } fn headers(&self) -> &HeaderMap { &self.headers } } #[cfg(feature = "reqwest")] impl RequestLike for reqwest::Request { fn uri(&self) -> Uri { self.url().as_str().parse().expect("Uri and Url are incompatible!?") } fn is_same_uri(&self, other: &Uri) -> bool { self.url().as_str() == other } fn method(&self) -> &Method { self.method() } fn headers(&self) -> &HeaderMap { self.headers() } } #[cfg(feature = "reqwest")] impl ResponseLike for reqwest::Response { fn status(&self) -> StatusCode { self.status() } fn headers(&self) -> &HeaderMap { self.headers() } }