Skip to content

Provide "suggestedFilename" in "WebDriver BiDi download started" hook #11139

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

Merged
merged 9 commits into from
Mar 28, 2025
Merged

Provide "suggestedFilename" in "WebDriver BiDi download started" hook #11139

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
51047dc
Provide "suggestedFilename" in "WebDriver BiDi download started" hook
sadym-chromium Mar 17, 2025
3a203e2
fix references
sadym-chromium Mar 26, 2025
263a252
resource -> response
sadym-chromium Mar 27, 2025
b920b9f
suggestedFilename, "get the suggested filename"
sadym-chromium Mar 27, 2025
aa5b50f
"handled as a download"
sadym-chromium Mar 27, 2025
c900c47
remove "the"
sadym-chromium Mar 27, 2025
a934eca
don't use var outside algo
sadym-chromium Mar 27, 2025
44b811c
Nits
domenic Mar 28, 2025
57a4bef
specfmt
domenic Mar 28, 2025
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
135 changes: 76 additions & 59 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4597,6 +4597,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<li><dfn data-x="navigation-status-pending" data-x-href="https://w3c.github.io/webdriver-bidi/#navigation-status-pending">navigation status pending</dfn></li>
<li><dfn data-x="navigation-status-complete" data-x-href="https://w3c.github.io/webdriver-bidi/#navigation-status-complete">navigation status complete</dfn></li>
<li><dfn data-x="navigation-status-url" data-x-href="https://w3c.github.io/webdriver-bidi/#navigation-status-url">navigation status url</dfn></li>
<li><dfn data-x="navigation-status-suggested-filename" data-x-href="https://w3c.github.io/webdriver-bidi/#navigation-status-suggested-filename">navigation status suggested filename</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-navigation-aborted">WebDriver BiDi navigation aborted</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-navigation-committed">WebDriver BiDi navigation committed</dfn></li>
<li><dfn data-x-href="https://w3c.github.io/webdriver-bidi/#webdriver-bidi-navigation-failed">WebDriver BiDi navigation failed</dfn></li>
Expand Down Expand Up @@ -25756,19 +25757,28 @@ document.body.appendChild(wbr);</code></pre>
data-x="concept-request-destination">destination</span> is the empty string, and whose
<span>synchronous flag</span> and <span>use-URL-credentials flag</span> are set.</p></li>

<!--FETCH--><li><p>Handle the result of <span data-x="concept-fetch">fetching</span>
<var>request</var> <span>as a download</span>.</p></li>
<!--FETCH--><li><p><span>Handle as a download</span> the result of <span
data-x="concept-fetch">fetching</span> <var>request</var>.</p></li>
</ol>
</li>
</ol>

<p>When a user agent is to handle a resource obtained from a fetch <dfn>as a download</dfn>, it
should provide the user with a way to save the resource for later use, if a resource is
successfully obtained. Otherwise, it should report any problems downloading the file to the
user.</p>
<p>To <dfn>handle as a download</dfn> a <span data-x="concept-response">response</span>
<var>response</var>:</p>

<ol>
<li><p>Let <var>suggestedFilename</var> be the result of <span>getting the suggested
filename</span> for <var>response</var>.</p></li>

<li><p>Provide the user with a way to save <var>response</var> for later use. If the user agent
needs a filename, it should use <var>suggestedFilename</var>. Report any problems downloading the
file to the user.</p></li>

<li><p>Return <var>suggestedFilename</var>.</p></li>
</ol>

<p>If the user agent needs a filename for a resource being handled <span>as a download</span>, it
should select one using the following algorithm.</p>
<p>To <dfn data-x="getting the suggested filename">get the suggested filename</dfn> for a <span
data-x="concept-response">response</span> <var>response</var>:</p>

<p class="warning">This algorithm is intended to mitigate security dangers involved in downloading
files from untrusted sites, and user agents are strongly urged to follow it.</p> <!-- but it's
Expand All @@ -25778,27 +25788,28 @@ document.body.appendChild(wbr);</code></pre>
<li><p>Let <var>filename</var> be the undefined value.</p></li>

Copy link
Member

Choose a reason for hiding this comment

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

Nice job adding the explicit resource variable. However, here and below, it's better to use just "resource" instead of "the resource". (Or I guess response, once we make the update I suggest above.)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

done

<!-- Content-Disposition: attachment; filename="" is always honoured, even cross-origin -->
<li><p>If the resource has a `<code data-x="http-content-disposition">Content-Disposition</code>`
header, that header specifies the <code data-x="">attachment</code> disposition type, and the
header includes filename information, then let <var>filename</var> have the value specified by
the header, and jump to the step labeled <i>sanitize</i> below. <ref>RFC6266</ref></p></li>
<li><p>If <var>response</var> has a `<code
data-x="http-content-disposition">Content-Disposition</code>` header, that header specifies the
<code data-x="">attachment</code> disposition type, and the header includes filename information,
then let <var>filename</var> have the value specified by the header, and jump to the step labeled
<i>sanitize</i> below. <ref>RFC6266</ref></p></li>

<li><p>Let <var>interface origin</var> be the <span
data-x="concept-document-origin">origin</span> of the <code>Document</code> in which the <span
data-x="downloading hyperlinks">download</span> or <span>navigate</span> action resulting in the
download was initiated, if any.</p></li>

<li><p>Let <var>resource origin</var> be the <span>origin</span> of the URL of the
resource being downloaded, unless that URL's <span data-x="concept-url-scheme">scheme</span>
component is <code data-x="">data</code>, in which case let <var>resource origin</var> be
the same as the <var>interface origin</var>, if any.</p></li>
<li><p>Let <var>response origin</var> be the <span>origin</span> of the URL of
<var>response</var>, unless that URL's <span data-x="concept-url-scheme">scheme</span> component
is <code data-x="">data</code>, in which case let <var>response origin</var> be the same as the
<var>interface origin</var>, if any.</p></li>

<li><p>If there is no <var>interface origin</var>, then let <var>trusted
operation</var> be true. Otherwise, let <var>trusted operation</var> be true if <var>resource origin</var> is the <span>same origin</span> as <var>interface
origin</var>, and false otherwise.</p></li>
<li><p>If there is no <var>interface origin</var>, then let <var>trusted operation</var> be true.
Otherwise, let <var>trusted operation</var> be true if <var>response origin</var> is the
<span>same origin</span> as <var>interface origin</var>, and false otherwise.</p></li>

<!-- Content-Disposition: *; filename="" overrides download="" for same-origin -->
<li><p>If <var>trusted operation</var> is true and the resource has a `<code
<li><p>If <var>trusted operation</var> is true and <var>response</var> has a `<code
data-x="http-content-disposition">Content-Disposition</code>` header and that header includes
filename information, then let <var>filename</var> have the value specified by the header, and
jump to the step labeled <i>sanitize</i> below. <ref>RFC6266</ref></p></li>
Expand All @@ -25823,16 +25834,18 @@ document.body.appendChild(wbr);</code></pre>
below.</p></li>

<!-- Content-Disposition: attachment with no filename="" allows download="" cross-origin -->
<li><p>If the resource has a `<code data-x="http-content-disposition">Content-Disposition</code>`
header and that header specifies the <code data-x="">attachment</code> disposition type, let
<var>filename</var> have the value of <var>proposed filename</var>, and jump to the step labeled
<i>sanitize</i> below. <ref>RFC6266</ref></p></li>

<!-- fallback for same-origin resources or explicit downloads: use the resource's filename -->
<li><p><i>No proposed filename</i>: If <var>trusted operation</var> is true, or if the
user indicated a preference for having the resource in question downloaded, let
<var>filename</var> have a value derived from the <span>URL</span> of the resource in an
<span>implementation-defined</span> manner, and jump to the step labeled <i>sanitize</i> below.</p></li>
<li><p>If <var>response</var> has a `<code
data-x="http-content-disposition">Content-Disposition</code>` header and that header specifies
the <code data-x="">attachment</code> disposition type, let <var>filename</var> have the value of
<var>proposed filename</var>, and jump to the step labeled <i>sanitize</i> below.
<ref>RFC6266</ref></p></li>

<!-- fallback for same-origin resources or explicit downloads: use the response's filename -->
<li><p><i>No proposed filename</i>: If <var>trusted operation</var> is true, or if the user
indicated a preference for having the response in question downloaded, let <var>filename</var>
have a value derived from the <span>URL</span> of <var>response</var> in an
<span>implementation-defined</span> manner, and jump to the step labeled <i>sanitize</i>
below.</p></li>

<!-- no C-D: a header on cross-origin raises red flags -->
<li>
Expand All @@ -25842,18 +25855,19 @@ document.body.appendChild(wbr);</code></pre>
<div class="warning">

<p>If the algorithm reaches this step, then a download was begun from a different origin than
the resource being downloaded, and the origin did not mark the file as suitable for
downloading, and the download was not initiated by the user. This could be because a <code
<var>response</var>, and the origin did not mark the file as suitable for downloading, and the
download was not initiated by the user. This could be because a <code
data-x="attr-hyperlink-download">download</code> attribute was used to trigger the download, or
because the resource in question is not of a type that the user agent supports.</p>
because <var>response</var> is not of a type that the user agent supports.</p>

<p>This could be dangerous, because, for instance, a hostile server could be trying to get a
user to unknowingly download private information and then re-upload it to the hostile server,
by tricking the user into thinking the data is from the hostile server.</p>

<p>Thus, it is in the user's interests that the user be somehow notified that the resource in
question comes from quite a different source, and to prevent confusion, any suggested filename
from the potentially hostile <var>interface origin</var> should be ignored.</p>
<p>Thus, it is in the user's interests that the user be somehow notified that
<var>response</var> comes from quite a different source, and to prevent confusion, any
suggested filename from the potentially hostile <var>interface origin</var> should be
ignored.</p>

</div>
</li>
Expand All @@ -25873,21 +25887,21 @@ document.body.appendChild(wbr);</code></pre>
data-x="concept-extension">extensions</span> to determine the types of file on the file system,
then return <var>filename</var> as the filename.</p></li>

<li><p>Let <var>claimed type</var> be the type given by the resource's <span
data-x="Content-Type">Content-Type metadata</span>, if any is known. Let <var>named
type</var> be the type given by <var>filename</var>'s <span
data-x="concept-extension">extension</span>, if any is known. For the purposes of this step, a
<i>type</i> is a mapping of a <span>MIME type</span> to an <span
data-x="concept-extension">extension</span>.</p></li>
<li><p>Let <var>claimed type</var> be the type given by <var>response</var>'s <span
data-x="Content-Type">Content-Type metadata</span>, if any is known. Let <var>named type</var> be
the type given by <var>filename</var>'s <span data-x="concept-extension">extension</span>, if any
is known. For the purposes of this step, a <i>type</i> is a mapping of a <span>MIME type</span>
to an <span data-x="concept-extension">extension</span>.</p></li>

<li><p>If <var>named type</var> is consistent with the user's preferences (e.g., because the
value of <var>filename</var> was determined by prompting the user), then return
<var>filename</var> as the filename.</p></li>

<li><p>If <var>claimed type</var> and <var>named type</var> are the same type (i.e., the type
given by the resource's <span data-x="Content-Type">Content-Type metadata</span> is consistent
with the type given by <var>filename</var>'s <span data-x="concept-extension">extension</span>),
then return <var>filename</var> as the filename.</p></li>
given by <var>response</var>'s <span data-x="Content-Type">Content-Type metadata</span> is
consistent with the type given by <var>filename</var>'s <span
data-x="concept-extension">extension</span>), then return <var>filename</var> as the
filename.</p></li>

<li>
<p>If the <var>claimed type</var> is known, then alter <var>filename</var> to
Expand All @@ -25913,7 +25927,7 @@ document.body.appendChild(wbr);</code></pre>
following the last dot ("<code data-x="">.</code>") in the filename to determine the type of the
file, and from that the manner in which the file is to be opened or executed.</p>

<p>User agents should ignore any directory or path information provided by the resource itself,
<p>User agents should ignore any directory or path information provided by the response itself,
its <span>URL</span>, and any <code data-x="attr-hyperlink-download">download</code> attribute, in
deciding where to store the resulting file in the user's file system.</p>

Expand Down Expand Up @@ -90383,8 +90397,8 @@ dictionary <dfn dictionary>DragEventInit</dfn> : <span>MouseEventInit</span> {
<dd>
<p>This flag prevents content from initiating or instantiating downloads, whether through <span
data-x="downloading hyperlinks">downloading hyperlinks</span> or through <a
href="#navigation-as-a-download">navigation</a> that gets handled <span>as a
download</span>.</p>
href="#navigation-as-a-download">navigation</a> that gets <span data-x="handle as a
download">handled as a download</span>.</p>
</dd>

<dt>The <dfn export>sandboxed custom protocols navigation browsing context flag</dfn></dt>
Expand Down Expand Up @@ -103127,17 +103141,20 @@ location.href = '#foo';</code></pre>
<var>uaAllowsDownloading</var> are true, then:</p>

<ol>
<li><p>Handle <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span> <span>as a download</span>.</p></li>
<li><p>Let <var>suggestedFilename</var> be the result of <span data-x="handle as a
download">handling as a download</span> <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>.</p></li>

<li><p>Invoke <span>WebDriver BiDi download started</span> with <var>navigable</var> and a
new <span>WebDriver BiDi navigation status</span> whose <span
data-x="navigation-status-id">id</span> is <var>navigationId</var>, <span
data-x="navigation-status-status">status</span> is "<code
data-x="navigation-status-complete">complete</code>", and <span
data-x="navigation-status-complete">complete</code>", <span
data-x="navigation-status-url">url</span> is <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>'s <span
data-x="concept-response-url">URL</span>.</p></li>
data-x="concept-response-url">URL</span>, and <span
data-x="navigation-status-suggested-filename">suggestedFilename</span> is
<var>suggestedFilename</var>.</p></li>
</ol>
</li>
</ol>
Expand Down Expand Up @@ -104088,13 +104105,13 @@ location.href = '#foo';</code></pre>
<li><p>Otherwise, the document's <var>type</var> is such that the resource will not affect
<var>navigationParams</var>'s <span data-x="navigation-params-navigable">navigable</span>, e.g.,
because the resource is to be handed to an external application or because it is an unknown type
that will be processed <span>as a download</span>. <span>Hand-off to external software</span>
given <var>navigationParams</var>'s <span data-x="navigation-params-response">response</span>,
<var>navigationParams</var>'s <span data-x="navigation-params-navigable">navigable</span>,
<var>navigationParams</var>'s <span data-x="navigation-params-sandboxing">final sandboxing flag
set</span>, <var>sourceSnapshotParams</var>'s <span
data-x="source-snapshot-params-activation">has transient activation</span>, and
<var>initiatorOrigin</var>.</p></li>
that will be processed by <span>handle as a download</span>. <span>Hand-off to external
software</span> given <var>navigationParams</var>'s <span
data-x="navigation-params-response">response</span>, <var>navigationParams</var>'s <span
data-x="navigation-params-navigable">navigable</span>, <var>navigationParams</var>'s <span
data-x="navigation-params-sandboxing">final sandboxing flag set</span>,
<var>sourceSnapshotParams</var>'s <span data-x="source-snapshot-params-activation">has transient
activation</span>, and <var>initiatorOrigin</var>.</p></li>

<li><p>Return null.</p></li>
</ol>
Expand Down