Update PerformanceResourceTiming pages, part 2 (mdn#22577)

* Update PerformanceResourceTiming pages, part 2 * Tweak TAO wording * Review feedback * Apply suggestions from code review Co-authored-by: Joe Medley <jmedley@google.com> Co-authored-by: Joe Medley <jmedley@google.com>
hamishwillee · Dec 9, 2022 · 9e9184c · 9e9184c
1 parent 057abe2
commit 9e9184c
Show file tree

Hide file tree

Showing 3 changed files with 141 additions and 75 deletions.
diff --git a/files/en-us/web/api/performanceresourcetiming/decodedbodysize/index.md b/files/en-us/web/api/performanceresourcetiming/decodedbodysize/index.md
@@ -12,38 +12,58 @@ browser-compat: api.PerformanceResourceTiming.decodedBodySize
 
 {{APIRef("Performance API")}}
 
-The **`decodedBodySize`** read-only property returns the size
-(in octets) received from the fetch (HTTP or cache) of the message body, after removing
-any applied content-codings. If the resource is retrieved from an application cache or
-local resources, it returns the size of the payload after removing any applied
-content-codings.
-
-{{AvailableInWorkers}}
+The **`decodedBodySize`** read-only property returns the size (in octets) received from the fetch (HTTP or cache) of the message body after removing any applied content encoding (like gzip or Brotli). If the resource is retrieved from an application cache or local resources, it returns the size of the payload after removing any applied content encoding.
 
 ## Value
 
-The size (in octets) received from the fetch (HTTP or cache) of the message body, after
-removing any applied content-codings.
+The `decodedBodySize` property can have the following values:
+
+- A number representing the size (in octets) received from the fetch (HTTP or cache) of the message body, after removing any applied content encoding.
+- `0` if the resource is a cross-origin request and no {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header is used.
 
 ## Examples
 
-The following example, the value of the size properties of all "`resource`"
-{{domxref("PerformanceEntry.entryType","type")}} events are logged.
+### Checking if content was compressed
+
+If the `decodedBodySize` and {{domxref("PerformanceResourceTiming.encodedBodySize", "encodedBodySize")}} properties are non-null and differ, the content was compressed (for example, gzip or Brotli).
+
+Example using a {{domxref("PerformanceObserver")}}, which notifies of new `resource` performance entries as they are recorded in the browser's performance timeline:
+
+```js
+const observer = new PerformanceObserver((list) => {
+  list.getEntries().forEach((entry) => {
+    const uncompressed =
+      entry.decodedBodySize && entry.decodedBodySize === entry.encodedBodySize;
+    if (uncompressed) {
+      console.log(`${entry.name} was not compressed!`);
+    }
+  });
+});
+
+observer.observe({ type: "resource", buffered: true });
+```
+
+Here's an example using {{domxref("Performance.getEntriesByType()")}}, which only shows `resource` performance entries present in the browser's performance timeline at the time you call this method:
 
 ```js
-function logSizes(entry) {
-  // Check for support of the *size properties and print their values
-  // if supported.
-  console.log(`decodedBodySize = ${perfEntry.decodedBodySize ?? "NOT supported"}`);
-  console.log(`encodedBodySize = ${perfEntry.encodedBodySize ?? "NOT supported"}`);
-  console.log(`transferSize = ${perfEntry.transferSize ?? "NOT supported"}`);
-}
-function checkPerformanceEntries() {
-  // Use getEntriesByType() to just get the "resource" events
-  for (const entry of performance.getEntriesByType("resource")) {
-    logSizes(entry);
+const resources = performance.getEntriesByType("resource");
+resources.forEach((entry) => {
+  const uncompressed =
+    entry.decodedBodySize && entry.decodedBodySize === entry.encodedBodySize;
+  if (uncompressed) {
+    console.log(`${entry.name} was not compressed!`);
   }
-}
+});
+```
+
+### Cross-origin content size information
+
+If the value of the `decodedBodySize` property is `0`, the resource might be a cross-origin request. To expose cross-origin content size information, the {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header needs to be set.
+
+For example, to allow `https://developer.mozilla.org` to see content sizes, the cross-origin resource should send:
+
+```http
+Timing-Allow-Origin: https://developer.mozilla.org
 ```
 
 ## Specifications
@@ -53,3 +73,7 @@ function checkPerformanceEntries() {
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- {{HTTPHeader("Timing-Allow-Origin")}}
diff --git a/files/en-us/web/api/performanceresourcetiming/encodedbodysize/index.md b/files/en-us/web/api/performanceresourcetiming/encodedbodysize/index.md
@@ -12,41 +12,59 @@ browser-compat: api.PerformanceResourceTiming.encodedBodySize
 
 {{APIRef("Performance API")}}
 
-The **`encodedBodySize`** read-only property represents the
-size (in octets) received from the fetch (HTTP or cache), of the _payload body_,
-before removing any applied content-codings.
-
-{{AvailableInWorkers}}
-
-If the resource is retrieved from an application cache or a local resource, it must
-return the size of the payload body before removing any applied content-codings.
+The **`encodedBodySize`** read-only property represents the size (in octets) received from the fetch (HTTP or cache) of the payload body before removing any applied content encodings (like gzip or Brotli). If the resource is retrieved from an application cache or a local resource, it must
+return the size of the payload body before removing any applied content encoding.
 
 ## Value
 
-A `number` representing the size (in octets) received from the fetch (HTTP
-or cache), of the _payload body_, before removing any applied content-codings.
+The `encodedBodySize` property can have the following values:
+
+- A number representing the size (in octets) received from the fetch (HTTP or cache), of the payload body, before removing any applied content encoding.
+- `0` if the resource is a cross-origin request and no {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header is used.
 
 ## Examples
 
-The following example, the value of the size properties of all "`resource`"
-{{domxref("PerformanceEntry.entryType","type")}} events are logged.
+### Checking if content was compressed
+
+If the `encodedBodySize` and {{domxref("PerformanceResourceTiming.decodedBodySize", "decodedBodySize")}} properties are non-null and differ, the content was compressed (for example, gzip or Brotli).
+
+Here's an example using a {{domxref("PerformanceObserver")}}, which notifies of new `resource` performance entries as they are recorded in the browser's performance timeline:
 
 ```js
-function logSizes(entry) {
-  // Check for support of the PerformanceEntry.*size properties and print their values
-  // if supported.
-  console.log(`decodedBodySize = ${perfEntry.decodedBodySize ?? "NOT supported"}`);
-  console.log(`encodedBodySize = ${perfEntry.encodedBodySize ?? "NOT supported"}`);
-  console.log(`transferSize = ${perfEntry.transferSize ?? "NOT supported"}`);
-}
-
-function checkPerformanceEntries() {
-  // Use getEntriesByType() to just get the "resource" events
-  const entries = performance.getEntriesByType("resource");
-  for (const entry of entries) {
-    logSizes(entry);
+const observer = new PerformanceObserver((list) => {
+  list.getEntries().forEach((entry) => {
+    const uncompressed =
+      entry.decodedBodySize && entry.decodedBodySize === entry.encodedBodySize;
+    if (uncompressed) {
+      console.log(`${entry.name} was not compressed!`);
+    }
+  });
+});
+
+observer.observe({ type: "resource", buffered: true });
+```
+
+Example using {{domxref("Performance.getEntriesByType()")}}, which only shows `resource` performance entries present in the browser's performance timeline at the time you call this method:
+
+```js
+const resources = performance.getEntriesByType("resource");
+resources.forEach((entry) => {
+  const uncompressed =
+    entry.decodedBodySize && entry.decodedBodySize === entry.encodedBodySize;
+  if (uncompressed) {
+    console.log(`${entry.name} was not compressed!`);
   }
-}
+});
+```
+
+### Cross-origin content size information
+
+If the value of the `encodedBodySize` property is `0`, the resource might be a cross-origin request. To expose cross-origin content size information, the {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header needs to be set.
+
+For example, to allow `https://developer.mozilla.org` to see content sizes, the cross-origin resource should send:
+
+```http
+Timing-Allow-Origin: https://developer.mozilla.org
 ```
 
 ## Specifications
@@ -56,3 +74,7 @@ function checkPerformanceEntries() {
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- {{HTTPHeader("Timing-Allow-Origin")}}
diff --git a/files/en-us/web/api/performanceresourcetiming/transfersize/index.md b/files/en-us/web/api/performanceresourcetiming/transfersize/index.md
@@ -12,41 +12,57 @@ browser-compat: api.PerformanceResourceTiming.transferSize
 
 {{APIRef("Performance API")}}
 
-The **`transferSize`** read-only property represents the size
-(in octets) of the fetched resource. The size includes the response header fields plus
-the response payload body (as defined by [RFC7230](https://httpwg.org/specs/rfc7230.html#message.body)).
+The **`transferSize`** read-only property represents the size (in octets) of the fetched resource. The size includes the response header fields plus the response payload body (as defined by [RFC7230](https://httpwg.org/specs/rfc7230.html#message.body)).
 
-{{AvailableInWorkers}}
-
-If the resource is fetched from a local cache, or if it is a cross-origin resource,
-this property returns zero.
+If the resource is fetched from a local cache, or if it is a cross-origin resource, this property returns zero.
 
 ## Value
 
-A `number` representing the size (in octets) of the fetched resource. The
-size includes the response header fields plus the [response payload body](https://httpwg.org/specs/rfc7230.html#message.body) (RFC7230).
+The `transferSize` property can have the following values:
+
+- A number representing the size (in octets) of the fetched resource. The size includes the response header fields plus the [response payload body](https://httpwg.org/specs/rfc7230.html#message.body) (RFC7230).
+- `0` if the resource was instantaneously retrieved from a cache.
+- `0` if the resource is a cross-origin request and no {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header is used.
 
 ## Examples
 
-The following example, the value of size properties of all "`resource`"
-{{domxref("PerformanceEntry.entryType","type")}} events are logged.
+### Checking if a cache was hit
+
+For environments not supporting the {{domxref("PerformanceResourceTiming.responseStatus", "responseStatus")}} property, the `transferSize` property can be used to determine cache hits. If `transferSize` is zero and the resource has a non-zero decoded body size (meaning the resource is same-origin or has {{HTTPHeader("Timing-Allow-Origin")}}), the resource was fetched from a local cache.
+
+Here's an example using a {{domxref("PerformanceObserver")}}, which notifies of new `resource` performance entries as they are recorded in the browser's performance timeline:
+
+```js
+const observer = new PerformanceObserver((list) => {
+  list.getEntries().forEach((entry) => {
+    if (entry.transferSize === 0 && entry.decodedBodySize > 0) {
+      console.log(`${entry.name} was loaded from cache`);
+    }
+  });
+});
+
+observer.observe({ type: "resource", buffered: true });
+```
+
+Here's an example using {{domxref("Performance.getEntriesByType()")}}, which only shows `resource` performance entries present in the browser's performance timeline at the time you call this method:
 
 ```js
-function logSizes(perfEntry) {
-  // Check for support of the PerformanceEntry.*size properties and print their values
-  // if supported.
-  console.log(`decodedBodySize = ${perfEntry.decodedBodySize ?? "NOT supported"}`);
-  console.log(`encodedBodySize = ${perfEntry.encodedBodySize ?? "NOT supported"}`);
-  console.log(`transferSize = ${perfEntry.transferSize ?? "NOT supported"}`);
-}
-
-function checkPerformanceEntries() {
-  // Use getEntriesByType() to just get the "resource" events
-  performance.getEntriesByType("resource")
-    .forEach((entry) => {
-      logSizes(entry[i]);
-    });
-}
+const resources = performance.getEntriesByType("resource");
+resources.forEach((entry) => {
+  if (entry.transferSize === 0 && entry.decodedBodySize > 0) {
+    console.log(`${entry.name} was loaded from cache`);
+  }
+});
+```
+
+### Cross-origin content size information
+
+If the value of the `transferSize` property is `0` and wasn't loaded from a local cache, the resource might be a cross-origin request. To expose cross-origin content size information, the {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header needs to be set.
+
+For example, to allow `https://developer.mozilla.org` to see content sizes, the cross-origin resource should send:
+
+```http
+Timing-Allow-Origin: https://developer.mozilla.org
 ```
 
 ## Specifications
@@ -56,3 +72,7 @@ function checkPerformanceEntries() {
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- {{HTTPHeader("Timing-Allow-Origin")}}