| OLD | NEW |
|---|
| (Empty) | |
| 1 <!-- BEGIN AUTHORED CONTENT --> |
| 2 <p id="classSummary"> |
| 3 Use the <code>chrome.webRequest</code> module to intercept, block, |
| 4 or modify requests in-flight and to observe and analyze traffic. |
| 5 </p> |
| 6 <h2 id="manifest">Manifest</h2> |
| 7 <p>You must declare the "webRequest" permission in the <a |
| 8 href="manifest.html">extension manifest</a> to use the web request |
| 9 API, along with <a href="manifest.html#permissions">host permissions</a> |
| 10 for any hosts whose network requests you want to access. If you want to |
| 11 use the web request API in a blocking fashion, you need to request |
| 12 the "webRequestBlocking" permission in addition. |
| 13 For example:</p> |
| 14 <pre>{ |
| 15 "name": "My extension", |
| 16 ... |
| 17 <b>"permissions": [ |
| 18 "webRequest", |
| 19 "*://*.google.com" |
| 20 ]</b>, |
| 21 ... |
| 22 }</pre> |
| 23 <p class="note"> |
| 24 <b>Node:</b> If you request the "webRequestBlocking" permission, web requests |
| 25 are delayed until the background page of your extension has been loaded. This |
| 26 allows you to register event listeners before any web requests are processed. |
| 27 In order to avoid deadlocks, you must not start synchronous XmlHttpRequests or |
| 28 include scripts from the internet via <code><script src="..."></code> tags |
| 29 in your background page. |
| 30 </p> |
| 31 <h2 id="life_cycle">Life cycle of requests</h2> |
| 32 <p> |
| 33 The web request API defines a set of events that follow the life cycle of a web |
| 34 request. You can use these events to observe and analyze traffic. Certain |
| 35 synchronous events will allow you to intercept, block, or modify a request. |
| 36 </p> |
| 37 <p> |
| 38 The event life cycle for successful requests is illustrated here, followed by |
| 39 event definitions:<br/> |
| 40 <img src="/static/images/webrequestapi.png" |
| 41 width="385" height="503" |
| 42 alt="Life cycle of a web request from the perspective of the webrequest API" |
| 43 style="margin-left: auto; margin-right: auto; display: block"/> |
| 44 </p> |
| 45 <p> |
| 46 <dl> |
| 47 <dt><code>onBeforeRequest</code> (optionally synchronous)</dt> |
| 48 <dd>Fires when a request is about to occur. This event is sent before any TCP |
| 49 connection is made and can be used to cancel or redirect requests.</dd> |
| 50 <dt><code>onBeforeSendHeaders</code> (optionally synchronous)</dt> |
| 51 <dd>Fires when a request is about to occur and the initial headers have been |
| 52 prepared. The event is intended to allow extensions to add, modify, and delete |
| 53 request headers <a href="#life_cycle_footnote">(*)</a>. The |
| 54 <code>onBeforeSendHeaders</code> event is passed to all subscribers, so |
| 55 different subscribers may attempt to modify the request; see the <a |
| 56 href="#implementation">Implementation details</a> section for how this is |
| 57 handled. This event can be used to cancel the request.</dd> |
| 58 <dt><code>onSendHeaders</code></dt> |
| 59 <dd>Fires after all extensions have had a chance to modify the request |
| 60 headers, and presents the final <a href="#life_cycle_footnote">(*)</a> |
| 61 version. The event is triggered before the headers are sent to the network. |
| 62 This event is informational and handled asynchronously. It does not allow |
| 63 modifying or cancelling the request.</dd> |
| 64 <dt><code>onHeadersReceived</code> (optionally synchronous)</dt> |
| 65 <dd>Fires each time that an HTTP(S) response header is received. Due |
| 66 to redirects and authentication requests this can happen multiple times per |
| 67 request. This event is intended to allow extensions to add, modify, and delete |
| 68 response headers, such as incoming Set-Cookie headers.</dd> |
| 69 <dt><code>onAuthRequired</code> (optionally synchronous)</dt> |
| 70 <dd>Fires when a request requires authentication of the user. This event can |
| 71 be handled synchronously to provide authentication credentials. Note that |
| 72 extensions may provide invalid credentials. Take care not to enter an infinite |
| 73 loop by repeatedly providing invalid credentials.</dd> |
| 74 <dt><code>onBeforeRedirect</code></dt> |
| 75 <dd>Fires when a redirect is about to be executed. A redirection can be |
| 76 triggered by an HTTP response code or by an extension. This event is |
| 77 informational and handled asynchronously. It does not allow you to modify or |
| 78 cancel the request. </dd> |
| 79 <dt><code>onResponseStarted</code></dt> |
| 80 <dd>Fires when the first byte of the response body is received. For HTTP |
| 81 requests, this means that the status line and response headers are |
| 82 available. This event is informational and handled asynchronously. It does not |
| 83 allow modifying or cancelling the request.</dd> |
| 84 <dt><code>onCompleted</code></dt> |
| 85 <dd>Fires when a request has been processed successfully.</dd> |
| 86 <dt><code>onErrorOccurred</code></dt> |
| 87 <dd>Fires when a request could not be processed successfully.</dd> |
| 88 </dl> |
| 89 The web request API guarantees that for each request either |
| 90 <code>onCompleted</code> or <code>onErrorOccurred</code> is fired as the final |
| 91 event with one exception: If a request is redirected to a <code>data://</code> |
| 92 URL, <code>onBeforeRedirect</code> is the last reported event. |
| 93 </p> |
| 94 <p id="life_cycle_footnote">(*) Note that the web request API presents an |
| 95 abstraction of the network stack to the extension. Internally, one URL request |
| 96 can be split into several HTTP requests (for example to fetch individual byte |
| 97 ranges from a large file) or can be handled by the network stack without |
| 98 communicating with the network. For this reason, the API does not provide the |
| 99 final HTTP headers that are sent to the network. For example, all headers that |
| 100 are related to caching are invisible to the extension.</p> |
| 101 <p>The following headers are currently <b>not provided</b> to the |
| 102 <code>onBeforeSendHeaders</code> event. This list is not guaranteed to be |
| 103 complete nor stable. |
| 104 <ul> |
| 105 <li>Authorization</li> |
| 106 <li>Cache-Control</li> |
| 107 <li>Connection</li> |
| 108 <li>Content-Length</li> |
| 109 <li>Host</li> |
| 110 <li>If-Modified-Since</li> |
| 111 <li>If-None-Match</li> |
| 112 <li>If-Range</li> |
| 113 <li>Partial-Data</li> |
| 114 <li>Pragma</li> |
| 115 <li>Proxy-Authorization</li> |
| 116 <li>Proxy-Connection</li> |
| 117 <li>Transfer-Encoding</li> |
| 118 </ul> |
| 119 </p> |
| 120 <p> |
| 121 The webRequest API only exposes requests that the extension has |
| 122 permission to see, given its |
| 123 <a href="manifest.html#permissions">host permissions</a>. |
| 124 Moreover, only the following schemes are accessible: |
| 125 <code>http://</code>, |
| 126 <code>https://</code>, |
| 127 <code>ftp://</code>, |
| 128 <code>file://</code>, or |
| 129 <code>chrome-extension://</code>. |
| 130 In addition, even certain requests with URLs using one of the above schemes |
| 131 are hidden, e.g., |
| 132 <code>chrome-extension://other_extension_id</code> where |
| 133 <code>other_extension_id</code> is not the ID of the extension to handle |
| 134 the request, |
| 135 <code>https://www.google.com/chrome</code>, |
| 136 and others (this list is not complete). |
| 137 </p> |
| 138 <h2 id="concepts">Concepts</h2> |
| 139 <p>As the following sections explain, events in the web request API use request |
| 140 IDs, and you can optionally specify filters and extra information when you |
| 141 register event listeners.</p> |
| 142 <h3 id="Request IDs">Request IDs</h3> |
| 143 <p>Each request is identified by a request ID. This ID is unique within a |
| 144 browser session and the context of an extension. It remains constant during the |
| 145 the life cycle of a request and can be used to match events for the same |
| 146 request. Note that several HTTP requests are mapped to one web request in case |
| 147 of HTTP redirection or HTTP authentication.</p> |
| 148 <h3 id="subscription">Registering event listeners</h3> |
| 149 <p>To register an event listener for a web request, you use a variation on the |
| 150 <a href="events.html">usual <code>addListener()</code> function</a>. |
| 151 In addition to specifying a callback function, |
| 152 you have to specify a filter argument and you may specify an optional extra info |
| 153 argument.</p> |
| 154 <p>The three arguments to the web request API's <code>addListener()</code> have |
| 155 the following definitions:</p> |
| 156 <pre> |
| 157 var callback = function(details) {...}; |
| 158 var filter = {...}; |
| 159 var opt_extraInfoSpec = [...]; |
| 160 </pre> |
| 161 <p>Here's an example of listening for the <code>onBeforeRequest</code> |
| 162 event:</p> |
| 163 <pre> |
| 164 chrome.webRequest.onBeforeRequest.addListener( |
| 165 callback, filter, opt_extraInfoSpec); |
| 166 </pre> |
| 167 <p>Each <code>addListener()</code> call takes a mandatory callback function as |
| 168 the first parameter. This callback function is passed a dictionary containing |
| 169 information about the current URL request. The information in this dictionary |
| 170 depends on the specific event type as well as the content of |
| 171 <code>opt_extraInfoSpec</code>.</p> |
| 172 <p>If the optional <code>opt_extraInfoSpec</code> array contains the string |
| 173 <code>'blocking'</code> (only allowed for specific events), the callback |
| 174 function is handled synchronously. That means that the request is blocked until |
| 175 the callback function returns. In this case, the callback can return a <a |
| 176 href="#type-webRequest.BlockingResponse">BlockingResponse</a> that determines
the further |
| 177 life cycle of the request. Depending on the context, this response allows |
| 178 cancelling or redirecting a request (<code>onBeforeRequest</code>), cancelling a |
| 179 request or modifying headers (<code>onBeforeSendHeaders</code>, |
| 180 <code>onHeadersReceived</code>), or providing authentication credentials |
| 181 (<code>onAuthRequired</code>).</p> |
| 182 <p>The <a href="#type-webRequest.RequestFilter">RequestFilter</a> |
| 183 <code>filter</code> allows limiting the requests for which events are |
| 184 triggered in various dimensions: |
| 185 <dl> |
| 186 <dt>URLs</dt> |
| 187 <dd><a href="match_patterns.html">URL patterns</a> such as |
| 188 <code>*://www.google.com/foo*bar</code>.</dd> |
| 189 <dt>Types</dt> |
| 190 <dd>Request types such as <code>main_frame</code> (a document that is loaded |
| 191 for a top-level frame), <code>sub_frame</code> (a document that is loaded for |
| 192 an embedded frame), and <code>image</code> (an image on a web site). |
| 193 See <a href="#type-webRequest.RequestFilter">RequestFilter</a>.</dd> |
| 194 <dt>Tab ID</dt> |
| 195 <dd>The identifier for one tab.</dd> |
| 196 <dt>Window ID</dt> |
| 197 <dd>The identifier for a window.</dd> |
| 198 </p> |
| 199 <p>Depending on the event type, you can specify strings in |
| 200 <code>opt_extraInfoSpec</code> to ask for additional information about the |
| 201 request. This is used to provide detailed information on request's data only |
| 202 if explicitly requested.</p> |
| 203 <h2 id="implementation">Implementation details</h2> |
| 204 <p>Several implementation details can be important to understand when developing |
| 205 an extension that uses the web request API:</p> |
| 206 <h3>Conflict resolution</h3> |
| 207 <p>In the current implementation of the web request API, a request is considered |
| 208 as cancelled if at least one extension instructs to cancel the request. If |
| 209 an extension cancels a request, all extensions are notified by an |
| 210 <code>onErrorOccurred</code> event. Only one extension is allowed to redirect a |
| 211 request or modify a header at a time. If more than one extension attempts to |
| 212 modify the request, the most recently installed extension wins and all others |
| 213 are ignored. An extension is not notified if its instruction to modify or |
| 214 redirect has been ignored.</p> |
| 215 <h3>Caching</h3> |
| 216 <p> |
| 217 Chrome employs two caches — an on-disk cache and a very fast in-memory |
| 218 cache. The lifetime of an in-memory cache is attached to the lifetime of a |
| 219 render process, which roughly corresponds to a tab. Requests that are answered |
| 220 from the in-memory cache are invisible to the web request API. If a request |
| 221 handler changes its behavior (for example, the behavior according to which |
| 222 requests are blocked), a simple page refresh might not respect this changed |
| 223 behavior. To make sure the behavior change goes through, call |
| 224 <code>handlerBehaviorChanged()</code> to flush the in-memory cache. But don't do |
| 225 it often; flushing the cache is a very expensive operation. You don't need to |
| 226 call <code>handlerBehaviorChanged()</code> after registering or unregistering an |
| 227 event listener.</p> |
| 228 <h3>Timestamps</h3> |
| 229 <p> |
| 230 The <code>timestamp</code> property of web request events is only guaranteed to |
| 231 be <i>internally</i> consistent. Comparing one event to another event will give |
| 232 you the correct offset between them, but comparing them to the current time |
| 233 inside the extension (via <code>(new Date()).getTime()</code>, for instance) |
| 234 might give unexpected results. |
| 235 </p> |
| 236 <h2 id="examples">Examples</h2> |
| 237 <p>The following example illustrates how to block all requests to |
| 238 <code>www.evil.com</code>:</p> |
| 239 <pre> |
| 240 chrome.webRequest.onBeforeRequest.addListener( |
| 241 function(details) { |
| 242 return {cancel: details.url.indexOf("://www.evil.com/") != -1}; |
| 243 }, |
| 244 {urls: ["<all_urls>"]}, |
| 245 ["blocking"]); |
| 246 </pre> |
| 247 <p>As this function uses a blocking event handler, it requires the "webRequest" |
| 248 as well as the "webRequestBlocking" permission in the manifest file.</p> |
| 249 <p>The following example achieves the same goal in a more efficient way because |
| 250 requests that are not targeted to <code>www.evil.com</code> do not need to be |
| 251 passed to the extension:</p> |
| 252 <pre> |
| 253 chrome.webRequest.onBeforeRequest.addListener( |
| 254 function(details) { return {cancel: true}; }, |
| 255 {urls: ["*://www.evil.com/*"]}, |
| 256 ["blocking"]); |
| 257 </pre> |
| 258 <p>The following example illustrates how to delete the User-Agent header from |
| 259 all requests:</p> |
| 260 <pre> |
| 261 chrome.webRequest.onBeforeSendHeaders.addListener( |
| 262 function(details) { |
| 263 for (var i = 0; i < details.requestHeaders.length; ++i) { |
| 264 if (details.requestHeaders[i].name === 'User-Agent') { |
| 265 details.requestHeaders.splice(i, 1); |
| 266 break; |
| 267 } |
| 268 } |
| 269 return {requestHeaders: details.requestHeaders}; |
| 270 }, |
| 271 {urls: ["<all_urls>"]}, |
| 272 ["blocking", "requestHeaders"]); |
| 273 </pre> |
| 274 <p> For more example code, see the <a href="samples.html#webrequest">web request |
| 275 samples</a>.</p> |
| 276 <!-- END AUTHORED CONTENT --> |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 10700118:
Extensions Docs Server: First doc conversions (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src