puppeteer/next/guides/request-interception/index.html

25 lines
174 KiB
HTML
Raw Normal View History

<!doctype html>
<html lang="en" dir="ltr" class="docs-wrapper docs-doc-page docs-version-current plugin-docs plugin-id-default docs-doc-id-guides/request-interception">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="generator" content="Docusaurus v2.0.1">
<title data-rh="true">Request interception | Puppeteer</title><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://pptr.dev/next/guides/request-interception"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><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 continued, responded or aborted."><meta data-rh="true" property="og:description" content="Once request interception is enabled, every request will stall unless it&#x27;s continued, responded or aborted."><link data-rh="true" rel="icon" href="/img/favicon.ico"><link data-rh="true" rel="canonical" href="https://pptr.dev/next/guides/request-interception"><link data-rh="true" rel="alternate" href="https://pptr.dev/next/guides/request-interception" hreflang="en"><link data-rh="true" rel="alternate" href="https://pptr.dev/next/guides/request-interception" hreflang="x-default"><link rel="stylesheet" href="/assets/css/styles.121c39a6.css">
<link rel="preload" href="/assets/js/runtime~main.cf17787e.js" as="script">
<link rel="preload" href="/assets/js/main.f0d4bc94.js" as="script">
</head>
<body class="navigation-with-keyboard">
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}()</script><div id="__docusaurus">
<div role="region"><a href="#" class="skipToContent_fXgn">Skip to main content</a></div><nav class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Navigation bar toggle" class="navbar__toggle clean-btn" type="button" tabindex="0"><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="themedImage_ToTc themedImage--light_HNdA"><img src="https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png" alt="Puppeteer Logo" class="themedImage_ToTc themedImage--dark_i4oU"></div><b class="navbar__title text--truncate">Puppeteer</b></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="/next/">Next</a><ul class="dropdown__menu"><li><a aria-current="page" class="dropdown__link dropdown__link--active" href="/next/guides/request-interception">Next</a></li><li><a class="dropdown__link" href="/guides/request-interception">19.0.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/v18.2.1/docs/api/index.md" target="_blank" rel="noopener noreferrer" class="dropdown__link">18.2.1<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/v18.2.0/docs/api/index.md" target="_blank" rel="noopener noreferrer" class="dropdown__link">18.2.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/v18.1.0/docs/api/index.md" target="_blank" rel="noopener noreferrer" class="dropdown__link">18.1.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/v18.0.5/docs/api/index.md" target="_blank" rel="noopener noreferrer" class="dropdown__link">18.0.5<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/v18.0.4/docs/api/index.md" target="_blank" rel="noopener noreferrer" class="dropdown__link">18.0.4<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/v18.0.3/docs/api/index.md" target="_blank" rel="noopener noreferrer" class="dropdown__link">18.0.3<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/
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>
before calling <code>abort/continue/respond</code>.</p><p>Importantly, the intercept resolution may get handled by another listener while 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 <code>abort/continue/respond</code> <strong>synchronously</strong> together.</p><p>This example demonstrates two synchronous handlers working together:</p><div class="language-js codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-js codeBlock_bY9V thin-scrollbar"><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 method function property-access" 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"> </span><span class="token parameter">interceptedRequest</span><span class="token plain"> </span><span class="token arrow 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 control-flow" 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 method function property-access" 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 control-flow" 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 keyword control-flow" style="color:#00009f">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" s
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 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 ultimately aborted/responded/continued according to which resolution was given 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 <code>0</code> or <code>DEFAULT_INTERCEPT_RESOLUTION_PRIORITY</code> (exported from <code>HTTPRequest</code>) 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. 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 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
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"><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"
your handler means to take no special action, or &#x27;opt out&#x27;, <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 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 ensure that the request doesn&#x27;t hang.</p><p>We call this an <strong>Unopinionated continuation</strong> because the intent is to continue the request if nobody else has a better idea. Use <code>request.continue({...}, DEFAULT_INTERCEPT_RESOLUTION_PRIORITY)</code> (or <code>0</code>) for this type of continuation.</p><p>The second case (uncommon) is that your handler actually does have an opinion 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, use a custom priority.</p><p>To summarize, reason through whether your use of <code>request.continue</code> is just 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 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 class="hash-link" href="#upgrading-to-cooperative-intercept-mode-for-package-maintainers" title="Direct link to heading"></a></h2><p>If you are package maintainer and your package uses intercept handlers, you can update your intercept handlers to use Cooperative Intercept Mode. Suppose you 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"><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 punctu
<script src="/assets/js/runtime~main.cf17787e.js"></script>
<script src="/assets/js/main.f0d4bc94.js"></script>
</body>
</html>