Skip to content

Commit 32892f3

Browse files
sadym-chromiumsadym-chromium
authored
browser.setDownloadBehavior (#970)
In puppeteer, [there is a way](https://pptr.dev/api/puppeteer.browsercontextoptions) to [deny all the downloads](https://pptr.dev/api/puppeteer.downloadpolicy), or allow for [downloading to a custom folder](https://pptr.dev/api/puppeteer.downloadbehavior#downloadpath). This PR is intended to provide a way to customize the download behavior per user context or globally. 1. Should be followed up with [HTML PR](whatwg/html#11474) invoking new hooks. 1. Add a new hook "WebDriver BiDi download will begin" which is intended to replace "WebDriver BiDi download started". 1. "WebDriver BiDi download will begin" returns "download behavior struct", which instructs the user agent how to handle downloads.
1 parent e40ee59 commit 32892f3

File tree

1 file changed

+164
-11
lines changed

1 file changed

+164
-11
lines changed

‎index.bs‎

Lines changed: 164 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2293,7 +2293,8 @@ BrowserCommand = (
22932293
browser.GetClientWindows //
22942294
browser.GetUserContexts //
22952295
browser.RemoveUserContext //
2296-
browser.SetClientWindowState
2296+
browser.SetClientWindowState //
2297+
browser.SetDownloadBehavior
22972298
)
22982299
</pre>
22992300

@@ -2949,6 +2950,116 @@ those after the window has reached its new state.
29492950

29502951
</div>
29512952

2953+
#### The browser.setDownloadBehavior Command #### {#command-browser-setDownloadBehavior}
2954+
2955+
A <dfn>download behavior struct</dfn> is a [=struct=] with:
2956+
* [=struct/item=] named <dfn id="download-behavior-struct-allowed" for="download-behavior-struct">allowed</dfn> which is a boolean;
2957+
* [=struct/item=] named <dfn id="download-behavior-struct-destination-folder" for="download-behavior-struct">destinationFolder</dfn> which is a string or null.
2958+
2959+
A [=remote end=] has a <dfn>download behavior</dfn> which is a [=struct=] with an [=struct/item=]
2960+
named <dfn for="download behavior">default download behavior</dfn>, which is a
2961+
[=download behavior struct=] or null, and an [=struct/item=] named <dfn
2962+
for="download behavior">user context download behavior</dfn>, which is a weak map between
2963+
[=user contexts=] and [=download behavior struct=].
2964+
2965+
<dl>
2966+
<dt>Command Type</dt>
2967+
<dd>
2968+
<pre class="cddl" data-cddl-module="remote-cddl">
2969+
browser.SetDownloadBehavior = (
2970+
method: "browser.setDownloadBehavior",
2971+
params: browser.SetDownloadBehaviorParameters
2972+
)
2973+
2974+
browser.SetDownloadBehaviorParameters = {
2975+
downloadBehavior: browser.DownloadBehavior / null,
2976+
? userContexts: [+browser.UserContext]
2977+
}
2978+
2979+
browser.DownloadBehavior = {
2980+
(
2981+
browser.DownloadBehaviorAllowed //
2982+
browser.DownloadBehaviorDenied
2983+
)
2984+
}
2985+
2986+
browser.DownloadBehaviorAllowed = (
2987+
type: "allowed",
2988+
? destinationFolder: text
2989+
)
2990+
2991+
browser.DownloadBehaviorDenied = (
2992+
type: "denied"
2993+
)
2994+
</pre>
2995+
</dd>
2996+
<dt>Return Type</dt>
2997+
<dd>
2998+
<code>
2999+
EmptyResult
3000+
</code>
3001+
</dd>
3002+
</dl>
3003+
3004+
<div algorithm>
3005+
To <dfn export>get download behavior</dfn> given |navigable|:
3006+
3007+
1. Let |user context| be |navigable|'s [=associated user context=].
3008+
3009+
1. If [=download behavior=]'s [=download behavior/user context download behavior=] [=map/contains=]
3010+
|user context|, return [=download behavior=]'s
3011+
[=download behavior/user context download behavior=][|user context|].
3012+
3013+
1. Return [=download behavior=]'s [=download behavior/default download behavior=].
3014+
3015+
</div>
3016+
3017+
<div algorithm="remote end steps for browser.setDownloadBehavior">
3018+
3019+
The [=remote end steps=] with <var ignore>session</var> and |command parameters| are:
3020+
3021+
1. If |command parameters|["<code>downloadBehavior</code>"] is null, let
3022+
|download behavior| be null.
3023+
3024+
1. Otherwise:
3025+
3026+
1. If |command parameters|["<code>downloadBehavior</code>"]["<code>type</code>"]
3027+
is "<code>allowed</code>", let |allowed| be true, otherwise let |allowed| be
3028+
false.
3029+
3030+
1. If |command parameters|["<code>downloadBehavior</code>"] [=map/contains=]
3031+
"<code>destinationFolder</code>", let |destinationFolder| be
3032+
|command parameters|["<code>downloadBehavior</code>"]["<code>destinationFolder</code>"],
3033+
otherwise let |destinationFolder| be null.
3034+
3035+
1. Let |download behavior| be a [=download behavior struct=] with
3036+
[=download-behavior-struct/allowed=] set to |allowed| and
3037+
[=download-behavior-struct/destinationFolder=] set to |destinationFolder|.
3038+
3039+
1. If the implementation does not support required |download behavior|, then return
3040+
[=error=] with [=error code=] [=unsupported operation=].
3041+
3042+
1. If the <code>userContexts</code> field of |command parameters| is present:
3043+
3044+
1. Let |user contexts| be the result of [=trying=] to [=get valid user contexts=]
3045+
with |command parameters|["<code>userContexts</code>"].
3046+
3047+
1. For each |user context| of |user contexts|:
3048+
3049+
1. If |download behavior| is null, [=map/remove=] |user context| from [=download behavior=]'s
3050+
[=download behavior/user context download behavior=].
3051+
3052+
1. Otherwise, [=map/set=] [=download behavior=]'s
3053+
[=download behavior/user context download behavior=][|user context|] to
3054+
|download behavior|.
3055+
3056+
1. Otherwise, set [=download behavior=]'s [=download behavior/default download behavior=] to
3057+
|download behavior|.
3058+
3059+
1. Return [=success=] with data null.
3060+
3061+
</div>
3062+
29523063
## The browsingContext Module ## {#module-browsingContext}
29533064

29543065
The <dfn export for=modules>browsingContext</dfn> module contains commands and
@@ -5384,11 +5495,53 @@ complete</dfn> steps given |navigable| and |navigation status|:
53845495
</dd>
53855496
</dl>
53865497

5498+
<div algorithm>
5499+
The [=remote end event trigger=] is the
5500+
<dfn export>WebDriver BiDi download will begin</dfn> steps given |navigable| and
5501+
|navigation status|:
5502+
5503+
1. Let |navigation info| be the result of [=get the navigation info=] given
5504+
|navigable| and |navigation status|.
5505+
5506+
1. Let |params| be a [=/map=] matching the
5507+
<code>browsingContext.DownloadWillBeginParams</code> production, with the
5508+
<code>context</code> field set to |navigation info|["<code>context</code>"], the
5509+
<code>navigation</code> field set to |navigation info|["<code>navigation</code>"],
5510+
the <code>timestamp</code> field set to
5511+
|navigation info|["<code>timestamp</code>"], the <code>url</code> field set to
5512+
|navigation info|["<code>url</code>"] and <code>suggestedFilename</code> field set
5513+
to |navigation status|'s <code>suggestedFilename</code>.
5514+
5515+
1. Let |body| be a [=/map=] matching the
5516+
<code>browsingContext.DownloadWillBegin</code> production, with the
5517+
<code>params</code> field set to |params|.
5518+
5519+
1. Let |navigation id| be |navigation status|'s id.
5520+
5521+
1. Let |related navigables| be a [=/set=] containing |navigable|.
5522+
5523+
1. [=Resume=] with "<code>download started</code>", |navigation id|, and
5524+
|navigation status|.
5525+
5526+
1. For each |session| in the [=set of sessions for which an event is enabled=]
5527+
given "<code>browsingContext.downloadWillBegin</code>" and |related navigables|:
5528+
5529+
1. [=Emit an event=] with |session| and |body|.
5530+
5531+
1. Let |download behavior| be [=get download behavior=] with |navigable|.
5532+
5533+
1. Return |download behavior|.
5534+
5535+
</div>
5536+
53875537
<div algorithm>
53885538
The [=remote end event trigger=] is the <dfn export>WebDriver BiDi download
53895539
started</dfn> steps given |navigable| and |navigation status|:
53905540

5391-
1. Let |navigation info| be the result of [=get the navigation info=] given |navigable| and
5541+
Issue: Remove after HTML spec switched to [=WebDriver BiDi download will begin=]
5542+
(https://github.com/whatwg/html/pull/11474).
5543+
5544+
1. Let |navigation info| be the result of [=get the navigation info=] given |navigable| and
53925545
|navigation status|.
53935546

53945547
1. Let |params| be a [=/map=] matching the <code>browsingContext.DownloadWillBeginParams</code>
@@ -5399,20 +5552,20 @@ started</dfn> steps given |navigable| and |navigation status|:
53995552
<code>suggestedFilename</code> field set to |navigation status|'s
54005553
<code>suggestedFilename</code>.
54015554

5402-
1. Let |body| be a [=/map=] matching the
5403-
<code>browsingContext.DownloadWillBegin</code> production, with the
5404-
<code>params</code> field set to |params|.
5555+
1. Let |body| be a [=/map=] matching the
5556+
<code>browsingContext.DownloadWillBegin</code> production, with the
5557+
<code>params</code> field set to |params|.
54055558

5406-
1. Let |navigation id| be |navigation status|'s id.
5559+
1. Let |navigation id| be |navigation status|'s id.
54075560

5408-
1. Let |related navigables| be a [=/set=] containing |navigable|.
5561+
1. Let |related navigables| be a [=/set=] containing |navigable|.
54095562

5410-
1. [=Resume=] with "<code>download started</code>", |navigation id|, and |navigation status|.
5563+
1. [=Resume=] with "<code>download started</code>", |navigation id|, and |navigation status|.
54115564

5412-
1. For each |session| in the [=set of sessions for which an event is enabled=]
5413-
given "<code>browsingContext.downloadWillBegin</code>" and |related navigables|:
5565+
1. For each |session| in the [=set of sessions for which an event is enabled=]
5566+
given "<code>browsingContext.downloadWillBegin</code>" and |related navigables|:
54145567

5415-
1. [=Emit an event=] with |session| and |body|.
5568+
1. [=Emit an event=] with |session| and |body|.
54165569

54175570
</div>
54185571

0 commit comments

Comments
 (0)