Source code
Revision control
Copy as Markdown
Other Tools
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
#ifndef mozilla_net_NoVarySearchUtils_h
#define mozilla_net_NoVarySearchUtils_h
#include "nsString.h"
#include "nsTArray.h"
class nsIURI;
namespace mozilla::net {
/**
* Parsed representation of a No-Vary-Search response header, corresponding
* to the "URL variation config" defined in the No-Vary-Search spec:
*
* Used by the HTTP cache to determine whether two URLs with differing query
* strings can share a single cache entry, and by the Speculation Rules
* prefetch matching algorithms to find equivalent prefetch records.
*/
struct NoVarySearchData {
/**
* Controls how query parameters are filtered before URL comparison.
*
* ExactMatch — no No-Vary-Search header, or header failed to parse;
* URLs must match exactly (default).
* IgnoreAll — params=?1; all query parameters are ignored.
* Blocklist — params=("a" "b"); listed parameters are ignored.
* Allowlist — params=?1, except=("a"); all parameters except the
* listed ones are ignored.
*/
enum class ParamsRule : uint8_t {
ExactMatch,
IgnoreAll,
Blocklist,
Allowlist
};
ParamsRule paramsRule = ParamsRule::ExactMatch;
// For Blocklist: names of params to ignore.
// For Allowlist: names of params to keep.
nsTArray<nsCString> paramNames;
// When false, query parameter order does not affect equivalence
// (key-order=?1 was present in the header).
bool varyOnKeyOrder = true;
};
/**
* Parses a No-Vary-Search header value into a NoVarySearchData struct.
* Implements the "parse a URL variation config" algorithm from
*
* Falls back to a default-constructed NoVarySearchData (ExactMatch,
* varyOnKeyOrder=true) on any parse error, per spec §5.1.
*
* @param aHeader Raw header value, e.g. |params=("a" "b"), key-order|.
* @return Parsed NoVarySearchData.
*
* Examples:
* "params" → IgnoreAll
* "params=(\"a\")" → Blocklist, paramNames=["a"]
* "params, except=(\"a\")" → Allowlist, paramNames=["a"]
* "key-order" → ExactMatch, varyOnKeyOrder=false
*/
NoVarySearchData ParseNoVarySearchHeader(const nsACString& aHeader);
/**
* Determines whether two URIs are equivalent under a URL variation config.
* Implements the "equivalent modulo variation config" algorithm from
*
* Two URIs are equivalent if they have the same scheme, host, port, and path,
* and their query parameters are equivalent after applying the filtering and
* key-order normalisation defined by aData.
*
* @param aURIA First URI.
* @param aURIB Second URI.
* @param aData Parsed URL variation config from ParseNoVarySearchHeader().
* @return true if the URIs are equivalent under aData.
*
* Example (Blocklist, paramNames=["utm_source"]):
* /page?q=hello&utm_source=email vs /page?q=hello → true
* /page?q=hello vs /page?q=world → false
*/
bool URLsAreEquivalentModuloVariationConfig(nsIURI* aURIA, nsIURI* aURIB,
const NoVarySearchData& aData);
/**
* query string and fragment. Used as the secondary cache index key for
* No-Vary-Search lookups.
*
* @param aURI URI to extract the base path from. Must not be null.
* @param aBasePath [out] Receives the base path,
* @return NS_OK on success; an error code if URI methods fail.
*
* Example:
*/
nsresult ExtractNoVarySearchBasePath(nsIURI* aURI, nsACString& aBasePath);
} // namespace mozilla::net
#endif