|
| 1 | +# Content-Encoding in Resource Timing |
| 2 | + |
| 3 | +## Authors |
| 4 | +<guohuideng@microsoft.com> or [guohuideng2024](https://github.com/guohuideng2024) |
| 5 | + |
| 6 | +## Participate |
| 7 | + |
| 8 | +Please join the discussion at: https://github.com/w3c/resource-timing/issues/381 |
| 9 | + |
| 10 | +## Introduction |
| 11 | +Proposal to add a new field `contentEncoding` to `PerformanceResourceTiming`. `contentEncoding` holds a string corresponding to [Content-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) header of the fetched resource. |
| 12 | + |
| 13 | +Background information about `PerformanceResourceTiming` can be found [here](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming). |
| 14 | + |
| 15 | +## Goal |
| 16 | +- Provide access to Content-Encoding values to enable developers to effectively experiment with new content encodings, monitor performance, and debug issues using Real User Monitoring (RUM). |
| 17 | + |
| 18 | +## User Research |
| 19 | + |
| 20 | +Increasing the speed of content delivery significantly enhances user experience by minimizing delays and frustrations associated with slow-loading |
| 21 | +websites; and data compression plays a vital role in increasing content delivery speed. For the purpose of implementing data compression, |
| 22 | + [Content-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Encoding) has been a very popular tool. It's widely |
| 23 | + supported and it's a foundation of some advanced compression mechanisms like [Compression Dictionary Transport](https://www.ietf.org/archive/id/draft-ietf-httpbis-compression-dictionary-19.html). |
| 24 | + |
| 25 | +When web sites use `Content-Encoding` to optimize content delivery, often they rely on `PerformanceResourceTiming` to collect and analyze the performance data of different compression strategies |
| 26 | +to find out the optimal solution. Often, it's very helpful or necessary to determine what `Content-Encoding` is used for a `PerformanceEntry` reported by `PerformanceResourceTiming`. In the past, |
| 27 | +web sites have been inferring the `Content-Encoding` based on other information like encoded/decoded body size. |
| 28 | + |
| 29 | +Inferring the `Content-Encoding` value has became harder and even impractical, as a larger set of new `Content-Encoding`, such as `zstd` and `Compression Dictionary Transport` are being experimented with and deployed. |
| 30 | +Therefore, we need an explicit exposure of `Content-Encoding` in `PerformanceResourceTiming`. |
| 31 | + |
| 32 | +This incremental proposal is brought up by [this discussion](https://github.com/w3c/resource-timing/issues/381). Example use cases may be found there as well. |
| 33 | + |
| 34 | +## API Changes and Example Code |
| 35 | + |
| 36 | +A new field `contentEncoding` will be added to the `PerformanceEntry` returned by `PerformanceResourceTiming`. A web developer can use this entry to retrieve the value of the `Content-Encoding` header for a specific resource in the following way: |
| 37 | + |
| 38 | +```javascript |
| 39 | +const entry_list = performance.getEntriesByType("resource"); |
| 40 | +console.log(entry_list[0].contentEncoding); |
| 41 | +/* |
| 42 | +Possible values are: "br", "dcb", "dcz", "deflate", "gzip", "identity", "zstd" etc. |
| 43 | +*/ |
| 44 | +``` |
| 45 | + |
| 46 | +## Pending Spec changes |
| 47 | + |
| 48 | +### Resource timing spec |
| 49 | +https://github.com/w3c/resource-timing/pull/411 |
| 50 | + |
| 51 | +### Fetch spec |
| 52 | + |
| 53 | +https://github.com/whatwg/fetch/pull/1796 |
| 54 | + |
| 55 | +## Design details |
| 56 | + |
| 57 | +- At `fetch` stage, an arbitrary `contentEncoding` value in the response header is allowed. This is needed for the case where a service worker is getting resources in a proprietary encoding. |
| 58 | + |
| 59 | +- The `contentEncoding` value to be exposed to `resourceTiming`(in the [response body info](https://fetch.spec.whatwg.org/#response-body-info)) is subject to filtering. The value |
| 60 | + is exposed only if it is a registered value at the [HTTP Content Coding Registry](https://www.iana.org/assignments/http-parameters/http-parameters.xhtml) and it is an encoding |
| 61 | + supported by the browser. Otherwise, `@unknown` is exposed instead. |
| 62 | + |
| 63 | + As in 2024/12, allowed values are the following: `br`, `dcb`, `dcz`, `deflate`, `gzip`, `identity`, `zstd`. |
| 64 | + |
| 65 | +## Considered alternatives |
| 66 | +None. |
| 67 | + |
| 68 | +## Stakeholder Feedback/Opposition |
| 69 | + |
| 70 | +According to https://github.com/whatwg/fetch/pull/1742, at least two implementers are interested and none opposed, citing W3C WebPerf call on Feb 29, 2024. But according to the [WebPerf WG minutes](https://docs.google.com/document/d/1qPPCtpg1MyVw3GGmd6VKZCdCyqoDub6Xgc8ANnq8SRI/edit#heading=h.wkdzwqaypyq6), only Chromium is known to have approved this feature at that time. |
| 71 | + |
| 72 | +As on 08/11/2025, Webkit is [supportive](https://github.com/WebKit/standards-positions/issues/467). There is [no signal](https://github.com/mozilla/standards-positions/issues/1189) from Mozilla. |
| 73 | + |
| 74 | + |
| 75 | +## References & acknowledgements |
| 76 | +`jxck@chromium.org` did a significant amount of work toward this change, below is the link where a number of prototype CL/PR/bug filings can be found at the first comment: |
| 77 | + |
| 78 | +https://github.com/whatwg/fetch/pull/1742 |
| 79 | + |
| 80 | +## Security/Privacy Considerations |
| 81 | +- The information is already discoverable indirectly through the sizing information. Therefore, there is no effective privacy loss. |
| 82 | +- The content-encoding is behind CORS check and hence the server has to opt in to make the information available. |
| 83 | + |
| 84 | + |
| 85 | +### [Self-Review Questionnaire: Security and Privacy](https://w3ctag.github.io/security-questionnaire/) |
| 86 | + |
| 87 | +>1. What information does this feature expose, and for what purposes? |
| 88 | +
|
| 89 | +It exposes the Content-Encoding header value set by the server when the resource was fetched. It is only available when the CORS check passes. It clarifies the content encoding methods used by the resources and help developers understand the performance implications of them. |
| 90 | +>2. Do features in your specification expose the minimum amount of information necessary to implement the intended functionality? |
| 91 | +
|
| 92 | +Yes |
| 93 | +>3. Do the features in your specification expose personal information, personally-identifiable information (PII), or information derived from either? |
| 94 | +
|
| 95 | +No. |
| 96 | +>4. How do the features in your specification deal with sensitive information? |
| 97 | +
|
| 98 | +It does not deal with sensitive information. |
| 99 | +>5. Does data exposed by your specification carry related but distinct information that may not be obvious to users?? |
| 100 | +
|
| 101 | +No. |
| 102 | +>6. Do the features in your specification introduce state that persists across browsing sessions? |
| 103 | +
|
| 104 | +No. |
| 105 | +>7. Do the features in your specification expose information about the underlying platform to origins? |
| 106 | +
|
| 107 | +Yes. Due to the filtering, this feature can expose the encoding capability of the browser. |
| 108 | +>8. Does this specification allow an origin to send data to the underlying platform? |
| 109 | +
|
| 110 | +No. |
| 111 | +>9. Do features in this specification enable access to device sensors? |
| 112 | +
|
| 113 | +No. |
| 114 | +>10. Do features in this specification enable new script execution/loading mechanisms? |
| 115 | +
|
| 116 | +No. |
| 117 | +>11. Do features in this specification allow an origin to access other devices? |
| 118 | +
|
| 119 | +No. |
| 120 | +>12. Do features in this specification allow an origin some measure of control over a user agent’s native UI? |
| 121 | +
|
| 122 | +No. |
| 123 | +>13. What temporary identifiers do the features in this specification create or expose to the web? |
| 124 | +
|
| 125 | +None. |
| 126 | +>14. How does this specification distinguish between behavior in first-party and third-party contexts? |
| 127 | +
|
| 128 | +No distinction. |
| 129 | +>15. How do the features in this specification work in the context of a browser’s Private Browsing or Incognito mode? |
| 130 | +
|
| 131 | +No difference. |
| 132 | +>16. Does this specification have both "Security Considerations" and "Privacy Considerations" sections? |
| 133 | +
|
| 134 | +Yes. |
| 135 | +>17. Do features in your specification enable origins to downgrade default security protections? |
| 136 | +
|
| 137 | +No. |
| 138 | +>18. What happens when a document that uses your feature is kept alive in BFCache (instead of getting destroyed) after navigation, and potentially gets reused on future navigations back to the document? |
| 139 | +
|
| 140 | +No difference. |
| 141 | +>19. What happens when a document that uses your feature gets disconnected? |
| 142 | +
|
| 143 | +No difference. |
| 144 | +>20. Does your spec define when and how new kinds of errors should be raised? |
| 145 | +
|
| 146 | +No new errors should be raised. |
| 147 | +>21. Does your feature allow sites to learn about the users use of assistive technology? |
| 148 | +
|
| 149 | +No. |
| 150 | +>22. What should this questionnaire have asked? |
| 151 | +
|
| 152 | +Nothing else. |
| 153 | + |
0 commit comments