Compression Dictionary Transport

2.1.1. match

The "match" value of the Use-As-Dictionary header is a sf-string value that provides an URL-matching pattern for requests where the dictionary can be used.¶

The sf-string is parsed as a URL [RFC3986], and supports absolute URLs as well as relative URLs. When stored, any relative URLs MUST be expanded so that only absolute URL patterns are used for matching against requests.¶

The match URL supports using * as a wildcard within the match string for pattern-matching multiple URLs. URLs with a natural * in them are not directly supported unless they can rely on the behavior of * matching an arbitrary string.¶

The [Origin] of the URL in the "match" pattern MUST be the same as the origin of the request that specifies the "Use-As-Dictionary" response and MUST not include a * wildcard.¶

The "match" value is required and MUST be included in the Use-As-Dictionary sf-dictionary for the dictionary to be considered valid.¶

2.1.2. ttl

The "ttl" value of the Use-As-Dictionary header is a sf-integer value that provides the time in seconds that the dictionary is valid for (time to live).¶

The "ttl" is independent of the cache lifetime of the resource being used for the dictionary. If the underlying resource is evicted from cache then it is also removed but this allows for setting an explicit time to live for use as a dictionary independent of the underlying resource in cache. Expired resources can still be useful as dictionaries while they are in cache and can be used for fetching updates of the expired resource. It can also be useful to artificially limit the life of a dictionary in cases where the dictionary is updated frequently which can help limit the number of possible incoming dictionary variations.¶

The "ttl" value is optional and defaults to 31536000 (1 year).¶

2.1.3. hashes

The "hashes" value of the Use-As-Dictionary header is a inner-list value that provides a list of supported hash algorithms in order of server preference.¶

The dictionaries are identified by the hash of their contents and this value allows for negotiation of the algorithm to use.¶

The "hashes" value is optional and defaults to (sha-256).¶

2.1.4. Examples

NOTE: '\' line wrapping per RFC 8792

Use-As-Dictionary: \
  match="/product/*", ttl=604800, hashes=(sha-256 sha-512)

Use-As-Dictionary: match="/app/*/main.js"

2.2.1. Dictionary freshness requirement

To be considered as a match, the dictionary must not yet be expired as a dictionary. When iterating through dictionaries looking for a match, the expiration time of the dictionary is calculated by taking the last time the dictionary was written and adding the "ttl" seconds from the "Use-As-Dictionary" response. If the current time is beyond the expiration time of the dictionary, it MUST be ignored.¶

2.2.2. Dictionary URL matching

When a dictionary is stored as a result of a "Use-As-Dictionary" directive, it includes a "match" string with the URL pattern of request URLs that the dictionary can be used for.¶

When comparing request URLs to the available dictionary match patterns, the comparison should account for the * wildcard when matching against request URLs. This can be accomplished with the following algorithm which returns TRUE for a successful match and FALSE for no-match:¶

1. Let MATCH represent the absolute URL pattern from the "match" value for the given dictionary.¶
2. LET URL represent the request URL being checked.¶

3. If there are no * characters in MATCH:¶

   • If the MATCH and URL strings are identical, return TRUE.¶
   • Else, return FALSE.¶

4. If there is a single * character in MATCH and it is at the end of the string:¶

   • If the MATCH string is identical to the start of the URL string, return TRUE.¶
   • Else, return FALSE.¶
5. Split the MATCH string by the * character into an array of MATCHES (excluding the * deliminator from the individual entries).¶

6. If there is not a * character at the end of MATCH:¶

   • Pop the last entry in MATCHES from the end of the array into PATTERN.¶
   • If PATTERN is identical to the end of the URL string, remove the end of the URL string to the beginning of the match to PATTERN.¶
   • Else, return FALSE.¶

7. Pop the first entry in MATCHES from the front of the array into PATTERN.¶

   • If PATTERN is not identical to the start of the URL string, return FALSE.¶

8. Pop each entry off of the front of the MATCHES array into PATTERN. For each PATTERN, in order:¶

   • Search for the first match of PATTERN in URL, starting from the position of the end of the previous match.¶
   • If no match is found, return FALSE.¶
9. Return TRUE.¶

2.2.3. Multiple matching dictionaries

When there are multiple dictionaries that match a given request URL, the client MUST pick the dictionary with the longest match pattern string length.¶

6.3.1. Cross-origin protection

To make sure that a dictionary can only impact content from the same origin where the dictionary was served, the "match" pattern used for matching a dictionary to requests MUST be for the same origin that the dictionary is served from.¶

6.3.2. Response readability

For clients, like web browsers, that provide additional protection against the readability of the payload of a response and against user tracking, additional protections MUST be taken to make sure that the use of dictionary-based compression does not reveal information that would not otherwise be available.¶

In these cases, dictionary compression MUST only be used when both the dictionary and the compressed response are fully readable by the client.¶

In browser terms, that means that both are either same-origin to the context they are being fetched from or that both include an "Access-Control-Allow-Origin" response header that matches the "Origin" request header they are fetched from.¶