github/puppeteer
0
0
Fork 0
mirror of https://github.com/puppeteer/puppeteer synced 2024-06-14 14:02:48 +00:00
Code Issues Packages Projects Releases Wiki Activity
7ad76a12e5
puppeteer/guides/request-interception/index.html

154 lines
198 KiB
HTML
Raw Normal View History

deploy: a5f1078feb4930e3204279acaad18a2d8e64a326
2022-08-16 12:43:00 +00:00
<!doctype html>
deploy: f6e7cbcadef6c6af6ed3a62206c85d690a6004f0
2024-02-17 11:48:34 +00:00
<html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-22.1.0 docs-doc-page docs-doc-id-guides/request-interception" data-has-hydrated="false">
deploy: a5f1078feb4930e3204279acaad18a2d8e64a326
2022-08-16 12:43:00 +00:00
<head>
<meta charset="UTF-8">
deploy: e8b501de6ffad4ea9512810b51d23c32346f9223
2024-01-05 08:33:29 +00:00
<meta name="generator" content="Docusaurus v3.0.1">
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
<title data-rh="true">Request Interception | Puppeteer</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://pptr.dev/guides/request-interception"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docsearch:counter" content="2"><meta data-rh="true" property="og:title" content="Request Interception | Puppeteer"><meta data-rh="true" name="description" content="Once request interception is enabled, every request will stall unless it&#x27;s"><meta data-rh="true" property="og:description" content="Once request interception is enabled, every request will stall unless it&#x27;s"><link data-rh="true" rel="icon" href="/img/favicon.ico"><link data-rh="true" rel="canonical" href="https://pptr.dev/guides/request-interception"><link data-rh="true" rel="alternate" href="https://pptr.dev/guides/request-interception" hreflang="en"><link data-rh="true" rel="alternate" href="https://pptr.dev/guides/request-interception" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://DVKY664LG7-dsn.algolia.net" crossorigin="anonymous"><link rel="search" type="application/opensearchdescription+xml" title="Puppeteer" href="/opensearch.xml">
deploy: 29b948197d5222e900817f201cb29abc65027343
2023-01-11 15:09:01 +00:00
deploy: e8b501de6ffad4ea9512810b51d23c32346f9223
2024-01-05 08:33:29 +00:00
<script src="/fix-location.js"></script><link rel="stylesheet" href="/assets/css/styles.10908b84.css">
deploy: ceab7a9042fe5fc3f71875e75327bb370f1c43a5
2024-02-21 12:57:53 +00:00
<script src="/assets/js/runtime~main.91c38e52.js" defer="defer"></script>
deploy: 561e4cd6ee79b19ac43f2c2fceaa1fce51052c02
2024-02-20 18:14:15 +00:00
<script src="/assets/js/main.d27e11a0.js" defer="defer"></script>
deploy: a5f1078feb4930e3204279acaad18a2d8e64a326
2022-08-16 12:43:00 +00:00
</head>
<body class="navigation-with-keyboard">
deploy: f6e7cbcadef6c6af6ed3a62206c85d690a6004f0
2024-02-17 11:48:34 +00:00
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return localStorage.getItem("theme")}catch(t){}}();t(null!==e?e:"light")}(),function(){try{const c=new URLSearchParams(window.location.search).entries();for(var[t,e]of c)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id="__docusaurus"><div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png" alt="Puppeteer Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png" alt="Puppeteer Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"></div><b class="navbar__title text--truncate">Puppeteer</b></a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/">Docs</a><a class="navbar__item navbar__link" href="/api/puppeteer.puppeteernode">Puppeteer API</a><a class="navbar__item navbar__link" href="/browsers-api/">@puppeteer/browsers API</a></div><div class="navbar__items navbar__items--right"><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a class="navbar__link" aria-haspopup="true" aria-expanded="false" role="button" href="/">22.1.0</a><ul class="dropdown__menu"><li><a class="dropdown__link" href="/next/guides/request-interception">Next</a></li><li><a aria-current="page" class="dropdown__link dropdown__link--active" href="/guides/request-interception">22.1.0</a></li><li><hr class="dropdown-separator"></li><li class="dropdown-archived-versions"><b>Archived versions</b></li><li><a href="https://github.com/puppeteer/puppeteer/blob/puppeteer-v22.0.0/docs/api/index.md" target="_blank" rel="noopener noreferrer" class="dropdown__link">22.0.0<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://github.com/puppeteer/puppeteer/blob/puppeteer-v21.11.0/docs/api/index.md" target="_blank" rel="noopener noreferrer" class="dropdown__link">21.11.0<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://github.com/puppeteer/puppeteer/blob/puppeteer-v21.10.0/docs/api/index.md" target="_blank" rel="noopener noreferrer" class="dropdown__link">21.10.0<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://github.com/puppeteer/puppeteer/blob/puppeteer-v21.9.0/docs/api/index.md" target="_blank" rel="noopener noreferrer" class="dropdown__link">21.9.0<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
<p>Once request interception is enabled, every request will stall unless it&#x27;s
continued, responded or aborted.</p>
<p>An example of a naïve request interceptor that aborts all image requests:</p>
<div class="language-ts codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-ts codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> puppeteer </span><span class="token keyword" style="color:#00009f">from</span><span class="token plain"> </span><span class="token string" style="color:#e3116c">&#x27;puppeteer&#x27;</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">(</span><span class="token keyword" style="color:#00009f">async</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">const</span><span class="token plain"> browser </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">await</span><span class="token plain"> puppeteer</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">launch</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">const</span><span class="token plain"> page </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">await</span><span class="token plain"> browser</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">newPage</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">await</span><span class="token plain"> page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">setRequestInterception</span><span class="token punctuation" style="color:#393A34">(</span><span class="token boolean" style="color:#36acaa">true</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;request&#x27;</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> interceptedRequest </span><span class="token operator" style="color:#393A34">=&gt;</span><span
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="multiple-intercept-handlers-and-asynchronous-resolutions">Multiple Intercept Handlers and Asynchronous Resolutions<a href="#multiple-intercept-handlers-and-asynchronous-resolutions" class="hash-link" aria-label="Direct link to Multiple Intercept Handlers and Asynchronous Resolutions" title="Direct link to Multiple Intercept Handlers and Asynchronous Resolutions">​</a></h2>
<p>By default Puppeteer will raise a <code>Request is already handled!</code> exception if
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
<code>request.abort</code>, <code>request.continue</code>, or <code>request.respond</code> are called after any
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
of them have already been called.</p>
<p>Always assume that an unknown handler may have already called
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
<code>abort/continue/respond</code>. Even if your handler is the only one you registered,
3rd party packages may register their own handlers. It is therefore important to
always check the resolution status using
<a href="#httprequestisinterceptresolutionhandled">request.isInterceptResolutionHandled</a>
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
before calling <code>abort/continue/respond</code>.</p>
<p>Importantly, the intercept resolution may get handled by another listener while
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
your handler is awaiting an asynchronous operation. Therefore, the return value
of <code>request.isInterceptResolutionHandled</code> is only safe in a synchronous code
block. Always execute <code>request.isInterceptResolutionHandled</code> and
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
<code>abort/continue/respond</code> <strong>synchronously</strong> together.</p>
<p>This example demonstrates two synchronous handlers working together:</p>
<div class="language-ts codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-ts codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">/*</span><br></span><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">This first handler will succeed in calling request.continue because the request interception has never been resolved.</span><br></span><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">*/</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;request&#x27;</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> interceptedRequest </span><span class="token operator" style="color:#393A34">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">interceptedRequest</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">isInterceptResolutionHandled</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">return</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> interceptedRequest</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">continue</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic">/*</span><br></span><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">This second handler will return before calling request.abort because request.continue was already</span><br></span><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">called by the first handler.</span><br></span><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">*/</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" s
<p>This example demonstrates asynchronous handlers working together:</p>
<div class="language-ts codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-ts codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">/*</span><br></span><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">This first handler will succeed in calling request.continue because the request interception has never been resolved.</span><br></span><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">*/</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;request&#x27;</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> interceptedRequest </span><span class="token operator" style="color:#393A34">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic">// The interception has not been handled yet. Control will pass through this guard.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">interceptedRequest</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">isInterceptResolutionHandled</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">return</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic">// It is not strictly necessary to return a promise, but doing so will allow Puppeteer to await this handler.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">new</span><span class="token plain"> </span><span class="token class-name builtin">Promise</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">resolve </span><span class="token operator" style="color:#393A34">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic">// Continue after 500ms</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token function" style="color:#d73a49">setTimeout</span><span cl
<p>For finer-grained introspection (see Cooperative Intercept Mode below), you may
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
also call
<a href="#httprequestinterceptresolutionstate">request.interceptResolutionState</a>
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
synchronously before using <code>abort/continue/respond</code>.</p>
<p>Here is the example above rewritten using <code>request.interceptResolutionState</code></p>
<div class="language-ts codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-ts codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">/*</span><br></span><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">This first handler will succeed in calling request.continue because the request interception has never been resolved.</span><br></span><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">*/</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;request&#x27;</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> interceptedRequest </span><span class="token operator" style="color:#393A34">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic">// The interception has not been handled yet. Control will pass through this guard.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">const</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain">action</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> interceptedRequest</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">interceptResolutionState</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">action </span><span class="token operator" style="color:#393A34">===</span><span class="token plain"> InterceptResolutionAction</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">AlreadyHandled</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">return</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic">// It is not strictly necessary to return a promise, but doing so will allow Puppeteer to await this handler.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> </span><span class="token keyword" style
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="cooperative-intercept-mode">Cooperative Intercept Mode<a href="#cooperative-intercept-mode" class="hash-link" aria-label="Direct link to Cooperative Intercept Mode" title="Direct link to Cooperative Intercept Mode">​</a></h2>
<p><code>request.abort</code>, <code>request.continue</code>, and <code>request.respond</code> can accept an
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
optional <code>priority</code> to work in Cooperative Intercept Mode. When all handlers are
using Cooperative Intercept Mode, Puppeteer guarantees that all intercept
handlers will run and be awaited in order of registration. The interception is
resolved to the highest-priority resolution. Here are the rules of Cooperative
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
Intercept Mode:</p>
<ul>
<li>All resolutions must supply a numeric <code>priority</code> argument to
<code>abort/continue/respond</code>.</li>
<li>If any resolution does not supply a numeric <code>priority</code>, Legacy Mode is active
and Cooperative Intercept Mode is inactive.</li>
<li>Async handlers finish before intercept resolution is finalized.</li>
<li>The highest priority interception resolution &quot;wins&quot;, i.e. the interception is
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
ultimately aborted/responded/continued according to which resolution was given
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
the highest priority.</li>
<li>In the event of a tie, <code>abort</code> &gt; <code>respond</code> &gt; <code>continue</code>.</li>
</ul>
<p>For standardization, when specifying a Cooperative Intercept Mode priority use
deploy: 931d4fced52aefbefdc8b21edfe3d1528e4e448b
2022-12-07 19:10:56 +00:00
<code>0</code> or <code>DEFAULT_INTERCEPT_RESOLUTION_PRIORITY</code> (exported from <code>HTTPRequest</code>)
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
unless you have a clear reason to use a higher priority. This gracefully prefers
<code>respond</code> over <code>continue</code> and <code>abort</code> over <code>respond</code> and allows other handlers
to work cooperatively. If you do intentionally want to use a different priority,
higher priorities win over lower priorities. Negative priorities are allowed.
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
For example, <code>continue({}, 4)</code> would win over <code>continue({}, -2)</code>.</p>
<p>To preserve backward compatibility, any handler resolving the intercept without
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
specifying <code>priority</code> (Legacy Mode) causes immediate resolution. For Cooperative
Intercept Mode to work, all resolutions must use a <code>priority</code>. In practice, this
means you must still test for <code>request.isInterceptResolutionHandled</code> because a
handler beyond your control may have called <code>abort/continue/respond</code> without a
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
priority (Legacy Mode).</p>
<p>In this example, Legacy Mode prevails and the request is aborted immediately
because at least one handler omits <code>priority</code> when resolving the intercept:</p>
<div class="language-ts codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-ts codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">// Final outcome: immediate abort()</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">setRequestInterception</span><span class="token punctuation" style="color:#393A34">(</span><span class="token boolean" style="color:#36acaa">true</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;request&#x27;</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> request </span><span class="token operator" style="color:#393A34">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">isInterceptResolutionHandled</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">return</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic">// Legacy Mode: interception is aborted immediately.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">abort</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;failed&#x27;</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;request&#x27;</span><span class="token punctuation" style="color:
<p>In this example, Legacy Mode prevails and the request is continued because at
least one handler does not specify a <code>priority</code>:</p>
<div class="language-ts codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-ts codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">// Final outcome: immediate continue()</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">setRequestInterception</span><span class="token punctuation" style="color:#393A34">(</span><span class="token boolean" style="color:#36acaa">true</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;request&#x27;</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> request </span><span class="token operator" style="color:#393A34">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">isInterceptResolutionHandled</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">return</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic">// Cooperative Intercept Mode: votes to abort at priority 0.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">abort</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;failed&#x27;</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">0</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class="token
<p>In this example, Cooperative Intercept Mode is active because all handlers
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
specify a <code>priority</code>. <code>continue()</code> wins because it has a higher priority than
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
<code>abort()</code>.</p>
<div class="language-ts codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-ts codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">// Final outcome: cooperative continue() @ 5</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">setRequestInterception</span><span class="token punctuation" style="color:#393A34">(</span><span class="token boolean" style="color:#36acaa">true</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;request&#x27;</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> request </span><span class="token operator" style="color:#393A34">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">isInterceptResolutionHandled</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">return</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic">// Cooperative Intercept Mode: votes to abort at priority 10</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">abort</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;failed&#x27;</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">0</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class=
<p>In this example, Cooperative Intercept Mode is active because all handlers
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
specify <code>priority</code>. <code>respond()</code> wins because its priority ties with
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
<code>continue()</code>, but <code>respond()</code> beats <code>continue()</code>.</p>
<div class="language-ts codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-ts codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">// Final outcome: cooperative respond() @ 15</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">setRequestInterception</span><span class="token punctuation" style="color:#393A34">(</span><span class="token boolean" style="color:#36acaa">true</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;request&#x27;</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> request </span><span class="token operator" style="color:#393A34">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">isInterceptResolutionHandled</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">return</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic">// Cooperative Intercept Mode: votes to abort at priority 10</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">abort</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;failed&#x27;</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">10</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="cooperative-request-continuation">Cooperative Request Continuation<a href="#cooperative-request-continuation" class="hash-link" aria-label="Direct link to Cooperative Request Continuation" title="Direct link to Cooperative Request Continuation">​</a></h2>
<p>Puppeteer requires <code>request.continue()</code> to be called explicitly or the request
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
will hang. Even if your handler means to take no special action, or &#x27;opt out&#x27;,
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
<code>request.continue()</code> must still be called.</p>
<p>With the introduction of Cooperative Intercept Mode, two use cases arise for
cooperative request continuations: Unopinionated and Opinionated.</p>
<p>The first case (common) is that your handler means to opt out of doing anything
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
special the request. It has no opinion on further action and simply intends to
continue by default and/or defer to other handlers that might have an opinion.
But in case there are no other handlers, we must call <code>request.continue()</code> to
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
ensure that the request doesn&#x27;t hang.</p>
<p>We call this an <strong>Unopinionated continuation</strong> because the intent is to continue
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
the request if nobody else has a better idea. Use
<code>request.continue({...}, DEFAULT_INTERCEPT_RESOLUTION_PRIORITY)</code> (or <code>0</code>) for
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
this type of continuation.</p>
<p>The second case (uncommon) is that your handler actually does have an opinion
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
and means to force continuation by overriding a lower-priority <code>abort()</code> or
<code>respond()</code> issued elsewhere. We call this an <strong>Opinionated continuation</strong>. In
these rare cases where you mean to specify an overriding continuation priority,
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
use a custom priority.</p>
<p>To summarize, reason through whether your use of <code>request.continue</code> is just
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
meant to be default/bypass behavior vs falling within the intended use case of
your handler. Consider using a custom priority for in-scope use cases, and a
default priority otherwise. Be aware that your handler may have both Opinionated
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
and Unopinionated cases.</p>
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="upgrading-to-cooperative-intercept-mode-for-package-maintainers">Upgrading to Cooperative Intercept Mode for package maintainers<a href="#upgrading-to-cooperative-intercept-mode-for-package-maintainers" class="hash-link" aria-label="Direct link to Upgrading to Cooperative Intercept Mode for package maintainers" title="Direct link to Upgrading to Cooperative Intercept Mode for package maintainers">​</a></h2>
<p>If you are package maintainer and your package uses intercept handlers, you can
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
update your intercept handlers to use Cooperative Intercept Mode. Suppose you
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
have the following existing handler:</p>
<div class="language-ts codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-ts codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;request&#x27;</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> interceptedRequest </span><span class="token operator" style="color:#393A34">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">isInterceptResolutionHandled</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">return</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> interceptedRequest</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">url</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">endsWith</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;.png&#x27;</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">||</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> interceptedRequest</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">url</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">endsWith</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;.jpg&#x27;</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> interceptedRequest</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">abort</span><span class="token punctuation" style="color:#393A34">(</span><span clas
<p>To use Cooperative Intercept Mode, upgrade <code>continue()</code> and <code>abort()</code>:</p>
<div class="language-ts codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-ts codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;request&#x27;</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> interceptedRequest </span><span class="token operator" style="color:#393A34">=&gt;</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">request</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">isInterceptResolutionHandled</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">return</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">if</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> interceptedRequest</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">url</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">endsWith</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;.png&#x27;</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">||</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> interceptedRequest</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">url</span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">endsWith</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">&#x27;.jpg&#x27;</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> interceptedRequest</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">abort</span><span class="token punctuation" style="color:#393A34">(</span><span clas
<p>With those simple upgrades, your handler now uses Cooperative Intercept Mode
instead.</p>
<p>However, we recommend a slightly more robust solution because the above
introduces several subtle issues:</p>
<ol>
<li><strong>Backward compatibility.</strong> If any handler still uses a Legacy Mode
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
resolution (ie, does not specify a priority), that handler will resolve the
interception immediately even if your handler runs first. This could cause
disconcerting behavior for your users because suddenly your handler is not
resolving the interception and a different handler is taking priority when
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
all the user did was upgrade your package.</li>
<li><strong>Hard-coded priority.</strong> Your package user has no ability to specify the
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
default resolution priority for your handlers. This can become important when
the user wishes to manipulate the priorities based on use case. For example,
one user might want your package to take a high priority while another user
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
might want it to take a low priority.</li>
</ol>
<p>To resolve both of these issues, our recommended approach is to export a
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
<code>setInterceptResolutionConfig()</code> from your package. The user can then call
<code>setInterceptResolutionConfig()</code> to explicitly activate Cooperative Intercept
Mode in your package so they aren&#x27;t surprised by changes in how the interception
is resolved. They can also optionally specify a custom priority using
deploy: 1014abc087e8bc549697fbc688dd332af4ec6959
2023-11-29 13:34:30 +00:00
<code>setInterceptResolutionConfig(priority)</code> that works for their use case:</p>
<div class="language-ts codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-ts codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token comment" style="color:#999988;font-style:italic">// Defaults to undefined which preserves Legacy Mode behavior</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">let</span><span class="token plain"> _priority </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">undefined</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic">// Export a module configuration function</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">export</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">const</span><span class="token plain"> </span><span class="token function-variable function" style="color:#d73a49">setInterceptResolutionConfig</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">priority </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token number" style="color:#36acaa">0</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">=&gt;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">_priority </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> priority</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token doc-comment comment" style="color:#999988;font-style:italic">/**</span><br></span><span class="token-line" style="color:#393A34"><span class="token doc-comment comment" style="color:#999988;font-style:italic"> * Note that this handler uses `DEFAULT_INTERCEPT_RESOLUTION_PRIORITY` to &quot;pass&quot; on this request. It is important to use</span><br></span><span class="token-line" style="color:#393A34"><span class="token doc-comment comment" style="color:#999988;font-style:italic"> * the default priority when your handler has no opinion on the request and the intent is to continue() by default.</span><br></span><span class="token-line" style="color:#393A34"><span class="token doc-comment comment" style="color:#999988;font-style:italic"> */</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">page</span><span class="token punctuation" style="color:#393A34">.</span><span class="token function" style="color:#d73a49">on</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style=
<p>If your package calls for more fine-grained control over resolution priorities,
use a config pattern like this:</p>
<div class="language-ts codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-ts codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">interface</span><span class="token plain"> </span><span class="token class-name">InterceptResolutionConfig</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> abortPriority</span><span class="token operator" style="color:#393A34">?</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">number</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> continuePriority</span><span class="token operator" style="color:#393A34">?</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token builtin">number</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic">// This approach supports multiple priorities based on situational</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic">// differences. You could, for example, create a config that</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#999988;font-style:italic">// allowed separate priorities for PNG vs JPG.</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">const</span><span class="token plain"> </span><span class="token constant" style="color:#36acaa">DEFAULT_CONFIG</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> InterceptResolutionConfig </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> abortPriority</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">undefined</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic">// Default to Legacy Mode</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> continuePriority</span><span class="token operator" style="color:#393A34">:</span><span class="token plain"> </span><span class="token keyword" style="color:#00009f">undefined</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token comment" style="color:#999988;font-style:italic">// Default to Legacy Mode</span><span class="token plain"></span><br></spa
<p>The above solutions ensure backward compatibility while also allowing the user
deploy: 4bf338b26d6cceae2dc718074ed9839e905905f2
2022-10-21 14:20:31 +00:00
to adjust the importance of your package in the resolution chain when
Cooperative Intercept Mode is being used. Your package continues to work as
expected until the user has fully upgraded their code and all third party
packages to use Cooperative Intercept Mode. If any handler or package still uses
deploy: c660d4001d610854399d7ecb551c4eb56a7f840a
2024-01-02 10:04:58 +00:00
Legacy Mode, your package can still operate in Legacy Mode too.</p></div></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/guides/docker"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Docker</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/guides/chrome-extensions"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Chrome Extensions</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#multiple-intercept-handlers-and-asynchronous-resolutions" class="table-of-contents__link toc-highlight">Multiple Intercept Handlers and Asynchronous Resolutions</a></li><li><a href="#cooperative-intercept-mode" class="table-of-contents__link toc-highlight">Cooperative Intercept Mode</a></li><li><a href="#cooperative-request-continuation" class="table-of-contents__link toc-highlight">Cooperative Request Continuation</a></li><li><a href="#upgrading-to-cooperative-intercept-mode-for-package-maintainers" class="table-of-contents__link toc-highlight">Upgrading to Cooperative Intercept Mode for package maintainers</a></li></ul></div></div></div></div></main></div></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://stackoverflow.com/questions/tagged/puppeteer" target="_blank" rel="noopener noreferrer" class="footer__link-item">Stack Overflow<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://twitter.com/chromedevtools" target="_blank" rel="noopener noreferrer" class="footer__link-item">Twitter<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://goo.gle/devtools-youtube" target="_blank" rel="noopener noreferrer" class="footer__link-item">YouTube<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div></div><div class="footer__bottom text--center"><div class="footer__copyright">Copyright © 2024 Google, Inc.</div></div></div></footer></div>
deploy: a5f1078feb4930e3204279acaad18a2d8e64a326
2022-08-16 12:43:00 +00:00
</body>
</html>
Reference in New Issue Copy Permalink