Skip to content

Added support for link rel=compression-dictionary #11620

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pmeenan wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Added support for link rel=compression-dictionary #11620

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
05bf299
Added support for link rel=compression-dictionary
pmeenan Feb 11, 2026
868e03c
Fixed CORS mode processing and http link processing
pmeenan Feb 11, 2026
25c321f
Fixed No CORS
pmeenan Feb 11, 2026
763cdd8
Fixed link header processing
pmeenan Feb 11, 2026
c5ca086
Fixed algorithm scoping
pmeenan Feb 11, 2026
c9b3eed
Cleanup unnecessary language
pmeenan Feb 11, 2026
64d7121
Set the destination instead of initiator
pmeenan Feb 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 100 additions & 0 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16166,6 +16166,7 @@ interface <dfn interface>HTMLLinkElement</dfn> : <span>HTMLElement</span> {
the processing model, and are supported by the user agent. The possible <span
data-x="concept-supported-tokens">supported tokens</span> are
<code data-x="rel-alternate">alternate</code>,
<code data-x="rel-compression-dictionary">compression-dictionary</code>,
<code data-x="rel-dns-prefetch">dns-prefetch</code>,
<code data-x="rel-expect">expect</code>,
<code data-x="rel-icon">icon</code>,
Expand Down Expand Up @@ -27256,6 +27257,7 @@ document.body.appendChild(wbr);</code></pre>

<p>Keywords that are <dfn>body-ok</dfn> affect whether <code>link</code> elements are
<span>allowed in the body</span>. The <span>body-ok</span> keywords are
<code data-x="rel-compression-dictionary">compression-dictionary</code>,
<code data-x="rel-dns-prefetch">dns-prefetch</code>,
<code data-x="rel-modulepreload">modulepreload</code>,
<code data-x="rel-pingback">pingback</code>,
Expand Down Expand Up @@ -27321,6 +27323,17 @@ document.body.appendChild(wbr);</code></pre>
<td>Gives the permalink for the nearest ancestor section.</td>
</tr>

<tr>
<td><code data-x="rel-compression-dictionary">compression-dictionary</code></td>
<td><span data-x="external resource link">External Resource</span></td>
<td colspan="2"><em>not allowed</em></td>
<td class="yes"> Yes </td>
<td class="yes"> Yes </td>
<td>Specifies that the user agent should preemptively <span data-x="concept-fetch">fetch</span> and cache the
target resource as it is likely to be useful as a compression dictionary for future
<span data-x="concept-fetch">fetches</span>. <ref>RFC9842</ref></td>
</tr>

<tr>
<td><code data-x="rel-dns-prefetch">dns-prefetch</code></td>
<td><span data-x="external resource link">External Resource</span></td>
Expand Down Expand Up @@ -27742,6 +27755,90 @@ document.body.appendChild(wbr);</code></pre>
Link Relation</cite>. <ref>RFC6596</ref></p>


<h5>Link type "<dfn attr-value for="link/rel"><code
data-x="rel-compression-dictionary">compression-dictionary</code></dfn>"</h5>

<p>The <code data-x="rel-compression-dictionary">compression-dictionary</code> keyword may be used
with <code>link</code> elements. This keyword creates an <span data-x="external resource link">external
resource link</span>. This keyword is <span>body-ok</span>.</p>
Comment thread
pmeenan marked this conversation as resolved.

<p>The <code data-x="rel-compression-dictionary">compression-dictionary</code> keyword indicates
that preemptively <span data-x="concept-fetch">fetching</span> and caching the specified resource
or same-site document is likely to be beneficial, as it is highly likely that the user will
be able to this resource as a compression dictionary for future

@fred-wang fred-wang Jun 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"the user will be able to this resource" => I think some verb is missing here?

<span data-x="concept-fetch">fetches</span>. <ref>RFC9842</ref></p>

@domfarolino domfarolino Nov 18, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this ref required? We're not referencing any definition from that spec, right? (Maybe I don't understand all the ref rules and Anne can correct me).

@pmeenan pmeenan Dec 16, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are 2 <ref>RFC9842</ref> references in the PR (both around similar language for link) and they are the only references to the compression dictionary RFC. I'm fine with removing both of them but then people would likely have to go through the fetch spec and from there to the RFC to see what compression dictionaries are.

The closest analog I could see in the code is from the img src text when it references the various bitmap formats without explicitly relying on anything in their specifications (around line 30710):

  <p class="note">The requirements above imply that images can be static bitmaps (e.g. PNGs, GIFs,
  JPEGs), single-page vector documents (single-page PDFs, XML files with an SVG document element),
  animated bitmaps (APNGs, animated GIFs), animated vector graphics (XML files with an SVG
  <span>document element</span> that use declarative SMIL animation), and so forth. However, these
  definitions preclude SVG files with script, multipage PDF files, interactive MNG files, HTML
  documents, plain text documents, and the like. <ref>PNG</ref> <ref>GIF</ref> <ref>JPEG</ref>
  <ref>PDF</ref> <ref>XML</ref> <ref>APNG</ref> <ref>SVG</ref> <ref>MNG</ref></p>


<p>There is no default type for resources given by the
<code data-x="rel-compression-dictionary">compression-dictionary</code> keyword.</p>

<p>The appropriate times to <span data-x="fetch and process the linked resource">fetch and
process</span> this type of link are:</p>

@fred-wang fred-wang Jun 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AFAIK, we only have one test fetch/compression-dictionary/dictionary-fetch-with-link-element.tentative.https.html for <link rel=compression-dictionary> and it only covers a simple case: a link element is created, inserted it in the doc and we check that the dictionary becomes available at some point in the future.

We should also tests that dictionary does not become available after some timeout if not all conditions are fulfilled (e.g. that if we create a link but without inserting it in the document).

It would also be interesting to check load cancellation or update (e.g. the attribute href attribute is removed or modified before the fetch started) but I suspect that will require a way to be sure a load hasn't started.


<ul>
<li><p>When the <span>external resource link</span> is created on a <code>link</code> element
that is already <span>browsing-context connected</span>.</p></li>

@fred-wang fred-wang Jun 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does that correspond to a <link rel="compression-dictionary"> that is already present in the doc (not dynamically inserted)? If so it does not seem to be covered by the tests.


<li><p>When the <span>external resource link</span>'s <code>link</code> element <span>becomes
browsing-context connected</span>.</p></li>

@fred-wang fred-wang Jun 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the case covered by the test, but maybe we should also check that, before the insertion, dictionary does not become available.


<li><p>When the <code data-x="attr-link-href">href</code> attribute of the <code>link</code>
element of an <span>external resource link</span> that is already <span>browsing-context
connected</span> is changed.</p></li>

@fred-wang fred-wang Jun 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This does not seem to be covered by existing tests.


<li><p>When the <code data-x="attr-link-crossorigin">crossorigin</code> attribute of the
<code>link</code> element of an <span>external resource link</span> that is already
<span>browsing-context connected</span> is set, changed, or removed.</p></li>

@fred-wang fred-wang Jun 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This does not seem to be covered by existing tests.

</ul>

<div algorithm>
<p>The <span>fetch and process the linked resource</span> steps for this type of linked resource,
given a <code>link</code> element <var>el</var>, are to <span
data-x="create link options from element">create link options</span> from <var>el</var> and

@fred-wang fred-wang Jun 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So I guess there is a bunch of options to be tested here: https://html.spec.whatwg.org/#create-link-options-from-element ; dictionary-fetch-with-link-element.tentative.https.html seems quite limited with only a test for crossorigin=anonymous (which is also default).

to <span>load a compression dictionary</span> given the result and <var>el</var>.</p>

<p>The <span>process a link header</span> step for this type of linked resource given a <span

@domfarolino domfarolino Nov 18, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My understanding from TPAC is that compression dictionary responses are intended to be processed almost primarily on subresource requests. But this header-processing algorithm does not run in those cases, and in fact we do not have a spec'ed processing model for subresource Link header requests. Is my understanding correct, and do we have tests for this behavior?

We haven't really had a pressing need to spec the Link header processing model on subresource requests, but if that's one of the main and expected ways of engaging with this new feature, and we have tests for it, perhaps it's important enough to invest in.

@pmeenan pmeenan Dec 16, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Link header is independent from the use of the dictionaries for compression and is used to trigger the loading of a stand-alone dictionary (instead of the subresource delta-compression model where a response is a dictionary itself).

The main use case envisioned is for a HTML document to trigger the loading of a dictionary that would be used in future document requests (compressing away the common HTML templates).

That said, I am sure someone would have a use case for triggering a separate dictionary request from subresources and that might be something Chrome currently allows (along with preload and preconnect) though there are ongoing discussions about how those should be handled to avoid tracking concerns.

The dictionary use case for subresource link headers should probably be included in whatever spec work we do to specify the behavior for preconnect and preload.

Right now the only WPT tests that use the Link header are for the document itself.

@fred-wang fred-wang Jun 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that this is also used by https://html.spec.whatwg.org/#process-link-headers

(I guess the use case is even less important, but technically we should have WPT test for that too)

data-x="link processing options">link processing options</span> <var>options</var> are to
<span>load a compression dictionary</span> given <var>options</var>.</p>

@fred-wang fred-wang Jun 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here, I don't see a lot of options tested for dictionary-fetch-with-link-header.tentative.https.html


<p>To <dfn>load a compression dictionary</dfn> given a <span>link processing options</span>
<var>options</var> and optional <code>link</code> element <var>el</var>:</p>

<ol>
<li><p>If <var>options</var>'s <span data-x="link options crossorigin">crossorigin</span>
is <span data-x="attr-crossorigin-none">No CORS</span>, set <var>options</var>'s
<span data-x="link options crossorigin">crossorigin</span> to
<span data-x="attr-crossorigin-anonymous">Anonymous</span>.</p></li>
Comment thread
domfarolino marked this conversation as resolved.

<li><p>Let <var>request</var> be the result of <span data-x="create a link request">creating a
link request</span> given <var>options</var>.</p></li>

<li><p>If <var>request</var> is null, then return.</p></li>

<li><p>Set <var>request</var>'s <span data-x="concept-request-destination">destination</span> to
"<code data-x="">compression-dictionary</code>".</p></li>

<li>
<p>Let <var>processCompressionDictionaryResponse</var> be the following steps given a <span
data-x="concept-response">response</span> <var>response</var> and null, failure, or a
<span>byte sequence</span> <var>bytesOrNull</var>:</p>

<ol>
<li><p>If <var>response</var> is a <span>network error</span> and <var>el</var> is set, <span
data-x="concept-event-fire">fire an event</span> named <code
data-x="event-error">error</code> at <var>el</var>.</p></li>

<li><p>Otherwise, if <var>el</var> is set, <span data-x="concept-event-fire">fire an event</span>
named <code data-x="event-load">load</code> at <var>el</var>.</p></li>

@fred-wang fred-wang Jun 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we please add WPT tests for these two events? (for both Link header and element).

</ol>
</li>

<li><p>The user agent should <span data-x="concept-fetch">fetch</span> <var>request</var>, with
<i data-x="processResponseConsumeBody">processResponseConsumeBody</i> set to
<var>processCompressionDictionaryResponse</var>. User agents may delay the fetching of
<var>request</var> to prioritize other requests that are necessary for the current document.</p></li>

@fred-wang fred-wang Jun 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand this is based on "prefetch", but I believe the spec should clarify the timing for <link rel=compression-dictionary>.

From whatwg/fetch#1854 (comment) I understand we need to wait a browser's idle period (which I guess can be verified with https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback for browsers that support it, or otherwise a double requestAnimationFrame) and (maybe) until the document load event was already dispatched.

Again, it would be nice to have some tests that verify we don't trigger the load before these conditions are met. Perhaps the events from the previous sections would be useful for that purpose.

Regarding Link header, I understand these conditions do not apply. I suspect we'd prefer to handle preconnect and preload before, but https://html.spec.whatwg.org/#process-link-headers does not seem to indicate a preferred order.

@fred-wang fred-wang Jun 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pmeenan shared info privately based on Chromium's code, basically:

  • For Link header handling of compressed-dictionary is deferred after the document load completes.
  • For Link element, this is done asap as described here (when browsing-context connected etc).
  • For both Link header and element, this is done by pushing the fetches into a task queue, which are executed only when the browser's main thread becomes idle.

In one comment above, the case of subresources was mentioned. It seems Chromium handles them a bit differently, as Link header for them is allowed before the load completes when they are not coming from the memory cache: https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/core/loader/preload_helper.cc;l=252;drc=88330e24edafaacd0d2f012282526e096a90b33a

</ol>
</div>

<h5>Link type "<dfn attr-value for="link/rel"><code
data-x="rel-dns-prefetch">dns-prefetch</code></dfn>"</h5>

Expand Down Expand Up @@ -156173,6 +156270,9 @@ INSERT INTERFACES HERE
<dt id="refsRFC8297">[RFC8297]</dt>
<dd><cite><a href="https://httpwg.org/specs/rfc8297.html">An HTTP Status Code for Indicating Hints</a></cite>, K. Oku. IETF.</dd>

<dt id="refsRFC9842">[RFC9842]</dt>
<dd><cite><a href="https://www.rfc-editor.org/rfc/rfc9842">Compression Dictionary Transport</a></cite>, P. Meenan, Y. Weiss. IETF.</dd>

<dt id="refsSCREENORIENTATION">[SCREENORIENTATION]</dt>
<dd><cite><a href="https://w3c.github.io/screen-orientation/">Screen Orientation</a></cite>, M. Cáceres. W3C.</dd>

Expand Down