Merge pull request #41 from w3c/clarify-size

clarify {transfer,encodedBody,decodedBody}size

index.html

@@ -563,26 +563,36 @@ <h3>The <code>PerformanceResourceTiming</code> Interface</h3>
 
 <dt>readonly attribute unsigned long long transferSize</dt>
 <dd>
-<p>This attribute MUST return the size, in octets received by the client, consumed by the response header fields and the response <a href="http://httpwg.github.io/specs/rfc7230.html#message.body">payload body</a> [[!RFC7230]].</p>
-<p>This attribute SHOULD include HTTP overhead (such as HTTP/1.1 chunked encoding and whitespace around header fields, including newlines, and <a href='https://tools.ietf.org/html/draft-ietf-httpbis-http2-16'>HTTP/2</a> frame overhead, along with other server-to-client frames on the same stream), but SHOULD NOT include lower-layer protocol overhead (such as TLS or TCP). If there are HTTP redirects or <a href="http://www.w3.org/TR/html5/infrastructure.html#concept-http-equivalent-codes" title='HTTP response codes equivalence'>equivalent</a> when navigating and if all the redirects or equivalent are from the same <a href="https://tools.ietf.org/html/rfc6454#section-4">origin</a> [[!RFC6454]], this attribute SHOULD include the HTTP overhead of incurred redirects.</p>
-<p>If the last non-redirected <a href="http://www.w3.org/TR/html5/infrastructure.html#fetch">fetch</a> of the resource is not the same origin as the <a>current document</a>, <a href="#widl-PerformanceResourceTiming-transferSize">transferSize</a> MUST return zero unless the <a href="#timing-allow-check">timing allow check</a> algorithm passes.</p>
+<p>This attribute MUST return the size, in octets received from a [HTTP-network fetch](https://fetch.spec.whatwg.org/#http-network-fetch), consumed by the response header fields and the response <a href="http://httpwg.github.io/specs/rfc7230.html#message.body">payload body</a> [[!RFC7230]]:</p>
+<ul>
+  <li>If the resource is retrieved from <a href="http://www.w3.org/TR/html5/browsers.html#relevant-application-cache" title='relevant application cache'>relevant application caches</a> or from local resources, it must return zero.</li>
+  <li>If there are HTTP redirects or <a href="http://www.w3.org/TR/html5/infrastructure.html#concept-http-equivalent-codes" title='HTTP response codes equivalence'>equivalent</a> when navigating and if all the redirects or equivalent are from the same <a href="https://tools.ietf.org/html/rfc6454#section-4">origin</a> [[!RFC6454]], this attribute SHOULD include the HTTP overhead of incurred redirects.</li>
+  <li>If the last non-redirected <a href="http://www.w3.org/TR/html5/infrastructure.html#fetch">fetch</a> of the resource is not the same origin as the <a>current document</a>, <a href="#widl-PerformanceResourceTiming-transferSize">transferSize</a> MUST return zero unless the <a href="#timing-allow-check">timing allow check</a> algorithm passes.</li>
+</ul>
+<p>This attribute SHOULD include HTTP overhead (such as HTTP/1.1 chunked encoding and whitespace around header fields, including newlines, and <a href='https://tools.ietf.org/html/draft-ietf-httpbis-http2-16'>HTTP/2</a> frame overhead, along with other server-to-client frames on the same stream), but SHOULD NOT include lower-layer protocol overhead (such as TLS or TCP).</p>
+<p class="note">It is possible for <code>transferSize</code> value to be lower than <code>encodedBodySize</code>: when a cached response is successfully revalidated the <code>transferSize</code> reports the size of the response HTTP headers incurred during the revalidation, and <code>encodedBodySize</code> reports the size of the previously retrieved payload body.</p>
 </dd>
 
 <dt>readonly attribute unsigned long long encodedBodySize</dt>
 <dd>
-<p>This attribute MUST return the size, in octets received by the client, of the <a href="http://httpwg.github.io/specs/rfc7230.html#message.body">payload body</a> [[!RFC7230]], prior to removing any applied <a href="http://httpwg.github.io/specs/rfc7231.html#data.encoding">content-codings</a> [[!RFC7231]].</p>
-<p>If the last non-redirected <a href="http://www.w3.org/TR/html5/infrastructure.html#fetch">fetch</a> of the resource is not the same origin as the <a>current document</a>, <a href="#widl-PerformanceResourceTiming-encodedBodySize">encodedBodySize</a> MUST return zero unless the <a href="#timing-allow-check">timing allow check</a> algorithm passes.</p>
+<p>This attribute MUST return the size, in octets received from a <a href="https://fetch.spec.whatwg.org/#http-network-or-cache-fetch">HTTP-network-or-cache</a> fetch, of the <a href="http://httpwg.github.io/specs/rfc7230.html#message.body">payload body</a> [[!RFC7230]], prior to removing any applied <a href="http://httpwg.github.io/specs/rfc7231.html#data.encoding">content-codings</a> [[!RFC7231]]:</p>
+<ul>
+  <li>If the resource is retrieved from <a href="http://www.w3.org/TR/html5/browsers.html#relevant-application-cache" title='relevant application cache'>relevant application caches</a> or from local resources, it must return the size of the payload body prior to removing any applied content-codings.</li>
+  <li>If the last non-redirected <a href="http://www.w3.org/TR/html5/infrastructure.html#fetch">fetch</a> of the resource is not the same origin as the <a>current document</a>, <a href="#widl-PerformanceResourceTiming-encodedBodySize">encodedBodySize</a> MUST return zero unless the <a href="#timing-allow-check">timing allow check</a> algorithm passes.</li>
+</ul>
+<p class="note">The <code>encodedBodySize</code> may be zero depending on the response code - e.g. HTTP 204 (No Content), 3XX, etc.</p>
 </dd>
 
 <dt>readonly attribute unsigned long long decodedBodySize</dt>
 <dd>
-<p>This attribute MUST return the size, in octets received by the client, of the <a href="http://httpwg.github.io/specs/rfc7230.html#message.body">message body</a> [[!RFC7230]], after removing any applied <a href="http://httpwg.github.io/specs/rfc7231.html#data.encoding">content-codings</a> [[!RFC7231]].</p>
-<p>If the last non-redirected <a href="http://www.w3.org/TR/html5/infrastructure.html#fetch">fetch</a> of the resource is not the same origin as the <a>current document</a>, <a href="#widl-PerformanceResourceTiming-decodedBodySize">decodedBodySize</a> MUST return zero unless the <a href="#timing-allow-check">timing allow check</a> algorithm passes.</p>
+<p>This attribute MUST return the size, in octets received from a <a href="https://fetch.spec.whatwg.org/#http-network-or-cache-fetch">HTTP-network-or-cache</a> fetch, of the <a href="http://httpwg.github.io/specs/rfc7230.html#message.body">message body</a> [[!RFC7230]], after removing any applied <a href="http://httpwg.github.io/specs/rfc7231.html#data.encoding">content-codings</a> [[!RFC7231]]:</p>
+<ul>
+  <li>If the resource is retrieved from <a href="http://www.w3.org/TR/html5/browsers.html#relevant-application-cache" title='relevant application cache'>relevant application caches</a> or from local resources, it must return the size of the payload after removing any applied content-codings.</li>
+  <li>If the last non-redirected <a href="http://www.w3.org/TR/html5/infrastructure.html#fetch">fetch</a> of the resource is not the same origin as the <a>current document</a>, <a href="#widl-PerformanceResourceTiming-decodedBodySize">decodedBodySize</a> MUST return zero unless the <a href="#timing-allow-check">timing allow check</a> algorithm passes.</li>
+</ul>
 </dd>
 
 <dt>serializer = { inherit, attribute }</dt>
-
-
 </dl>
 
 </section>