Re: [whatwg/fetch] Describe filtered responses better (PR #1513)

@domenic commented on this pull request.



> -be used, which is only "accessible" to internal specification algorithms and is never a
-<a>filtered response</a> itself.
+<p>A <dfn export id=concept-filtered-response>filtered response</dfn> is a <a for=/>response</a>
+that offers a limited view on an associated <a for=/>response</a>. This associated
+<a for=/>response</a> can be accessed through <a>filtered response</a>'s associated
+<dfn export id=concept-internal-response for="filtered response">internal response</dfn> (a
+<a for=/>response</a> that is neither a <a for=/>network error</a> nor a
+<a for=/>filtered response</a>).
+
+<p>Unless stated otherwise a <a for=/>filtered response</a>'s associated concepts (such as its
+<a for=response>body</a>) refer to the associated concepts of its
+<a for="filtered response">internal response</a>. (The exceptions to this are listed below as part
+of defining the concrete types of <a for=/>filtered responses</a>.)
+
+<div class=note>
+ <p>The <a for=/>fetch</a> algorithm returns such a view to ensure APIs do not accidentally leak

Fetch no longer "returns" responses, so maybe tweak this?

> +that offers a limited view on an associated <a for=/>response</a>. This associated
+<a for=/>response</a> can be accessed through <a>filtered response</a>'s associated
+<dfn export id=concept-internal-response for="filtered response">internal response</dfn> (a
+<a for=/>response</a> that is neither a <a for=/>network error</a> nor a
+<a for=/>filtered response</a>).
+
+<p>Unless stated otherwise a <a for=/>filtered response</a>'s associated concepts (such as its
+<a for=response>body</a>) refer to the associated concepts of its
+<a for="filtered response">internal response</a>. (The exceptions to this are listed below as part
+of defining the concrete types of <a for=/>filtered responses</a>.)
+
+<div class=note>
+ <p>The <a for=/>fetch</a> algorithm returns such a view to ensure APIs do not accidentally leak
+ information. If the information needs to be exposed for legacy reasons, e.g., to feed image data to
+ a decoder, the associated <a for="filtered response">internal response</a> can be used, which is
+ only "accessible" to internal specification algorithms.

What internal specification algorithms is it accessible to?

> +
+<p>Unless stated otherwise a <a for=/>filtered response</a>'s associated concepts (such as its
+<a for=response>body</a>) refer to the associated concepts of its
+<a for="filtered response">internal response</a>. (The exceptions to this are listed below as part
+of defining the concrete types of <a for=/>filtered responses</a>.)
+
+<div class=note>
+ <p>The <a for=/>fetch</a> algorithm returns such a view to ensure APIs do not accidentally leak
+ information. If the information needs to be exposed for legacy reasons, e.g., to feed image data to
+ a decoder, the associated <a for="filtered response">internal response</a> can be used, which is
+ only "accessible" to internal specification algorithms.
+
+ <p>New specifications ought not to build further on <a>opaque filtered responses</a> or
+ <a>opaque-redirect filtered responses</a>. Those are legacy constructs and cannot always be
+ adequately protected given contemporary computer architecture.
+</div>
 
 <p>A <dfn export id=concept-filtered-response-basic>basic filtered response</dfn> is a

Maybe out of scope / better as a followup, but I don't know what each of these types are used for. Especially "basic filtered response", and why there are two types of responses that sound similar ("basic" vs. "default"). Examples would be helpful.

-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/fetch/pull/1513#pullrequestreview-1152986811
You are receiving this because you are subscribed to this thread.

Message ID: <whatwg/fetch/pull/1513/review/1152986811@github.com>