Chromium Docs

Compression Dictionary Transport

Introduction

This document provides an overview of the current implementation status of the Compression Dictionary Transport feature in Chrome and instructions on how to enable it.

Starting from version 117, Chrome experimentally supports Compression Dictionary Transport feature. This feature adds support for using designated previous responses, as an external dictionary for Brotli- or Zstandard-compressed HTTP responses.

Activation

This API can be enabled by chrome://flags or via Origin Trial.

chrome://flags

If you want to try Compression Dictionary Transport feature, you have to enable both chrome://flags/#enable-compression-dictionary-transport and chrome://flags/#enable-compression-dictionary-transport-backend. The details about each flag are described here.

Origin Trial

Origin Trial token can be obtained from the Origin Trial console. You can enable this feature by setting Origin-Trials HTTP response header in the page's HTML,

Origin-Trial: YOUR_ORIGIN_TRIAL_TOKEN

or adding a meta tag in the <header> element.

<meta http-equiv="origin-trial" content="YOUR_ORIGIN_TRIAL_TOKEN">

Third-Party Origin Trial

This feature supports third-party Origin Trial. If you are serving third-party scripts, you can enable this feature by adding a meta tag.

(() => {
  const meta = document.createElement('meta');
  meta.httpEquiv = 'origin-trial';
  meta.content = 'YOUR_THIRD_PARTY_ORIGIN_TRIAL_TOKEN';
  document.head.appendChild(meta);
})()

Currently third-party Origin Trial doesn't support Origin-Trial HTTP response header. See this doc for more details.

Origin Trial and the backend feature

The origin trial token works only when the backend of this feature is enabled. Currently, the backend is gradually being rolled out. So the backend may not be enabled in your Chrome yet. If you want to try this feature using an Origin Trial token, please enable the backend at chrome://flags/#enable-compression-dictionary-transport-backend.

Why the backend is not enabled for all Chrome yet?

When the backend is enabled, Chrome will check the dictionary database while fetching resources. This may negatively affect Chrome's loading performance. Therefore, we are conducting experiments to ensure that this does not cause regressions before rolling it out to all users.

TODO(crbug.com/1413922): When we enable the backend for all Chrome, remove this section.

Feature detection

If you want to check whether the Compression Dictionary Transport feature is enabled or not, you can try the following code:

document.createElement('link').relList.supports('dictionary')

If the code above returns true, the Compression Dictionary Transport feature is enabled.

Registering dictionaries

When Chrome receives a HTTP response with use-as-dictionary: <options> header, and if the the response type is not opaque, Chrome registers the response as a dictionary.

Chrome supports following options (see the explainer for more details):

  • match
    • URL-matching pattern for the dictionary to apply to.
    • In the explainer, this field only supports the asterisk * wildcard. But currently Chrome supports both the asterisk * wildcard expansion and the question ?.
    • In the explainer, this field supports relative URLs (eg: ./js/*). But currently Chrome only supports absolute paths (eg: /map/js/*).
  • expires
    • Expiration time in seconds for the dictionary.
    • This field is optional and defaults to 31536000 (1 year).
    • While running the Origin Trial experiment, the max expiration time is limited to 30 days. This limitation can be removed by enabling chrome://flags/#enable-compression-dictionary-transport.
  • algorithms
    • List of supported hash algorithms in order of server preference.
    • This field is optional and defaults to (sha-256).
    • Currently Chrome only supports sha-256. So if this field is set but it doesn‘t contain sha-256, Chrome doesn’t register the response as a dictionary.
  • type
    • Dictionary format.
    • This field is optional and defaults to raw.
    • Currently Chrome only supports raw. So if this field is set but it is not raw, Chrome doesn't register the response as a dictionary. This logic of checking type was introduced at M118.

Note: These options fields are expected to change when we officially launch this feature, depending on the outcome of the spec discussion.

Fetching dedicated dictionaries

Chrome fetches a dedicated dictionary when it detects <link rel="dictionary" href="DICTIONARY_URL"> in the page, or Link: <DICTIONARY_URL>; rel="dictionary" HTTP response header is set in the response of the page's HTML file.

Using dictionaries

While fetching a HTTP request, Chrome match the request against the available dictionary match URL patterns. If there are multiple matching dictionaries, Chrome currently uses the dictionary with the longest match URL pattern.

If a dictionary is available for the request, Chrome will add sbr the Accept-Encoding request header, as well as a sec-available-dictionary: <SHA-256> header with the hash of the dictionary.

Supported compression scheme

Chrome 117.0.5857.0 introduced support for Shared Brotli, and Chrome 118.0.5952.0 adds support for Shared Zstandard.

Shared Zstandard can be enabled/disabled from chrome://flags/#enable-shared-zstd.

Debugging

Managing registered dictionaries

Developers can manage the registered dictionaries in chrome://net-internals/#sharedDictionary.

DevTools

Developers can check the related HTTP request and response headers (Use-As-Dictionary, Sec-Available-Dictionary, Accept-Encoding and Content-Encoding) using DevTools' Network tab.

Known issues

  • crbug.com/1468156: encodedBodySize property and transferSize property of PerformanceResourceTiming for shared dictionary compressed response are wrong. Currently it returns as if the response is not compressed.
  • crbug.com/1479465: Can't store large (>40 MB) dictionaries. Fixed in M118, by setting a 100 MB size limit if there is enough disk space.
  • cbrbug.com/1479809: Can't use large (>8MB) dictionaries for Shared Zstd. Fixed in M118.

Demo sites

There are a few demo sites that you can use to test the feature: