ChannelWrapper.webidl (17328B)
1 /* This Source Code Form is subject to the terms of the Mozilla Public 2 * License, v. 2.0. If a copy of the MPL was not distributed with this 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 4 5 interface LoadInfo; 6 interface MozChannel; 7 interface RemoteTab; 8 interface URI; 9 interface nsISupports; 10 11 /** 12 * Load types that correspond to the external types in nsIContentPolicy.idl. 13 * Please also update that IDL when updating this list. 14 */ 15 enum MozContentPolicyType { 16 "main_frame", 17 "sub_frame", 18 "stylesheet", 19 "script", 20 "image", 21 "object", 22 "xmlhttprequest", 23 "xslt", 24 "ping", 25 "beacon", 26 "xml_dtd", 27 "font", 28 "media", 29 "websocket", 30 "csp_report", 31 "imageset", 32 "web_manifest", 33 "speculative", 34 "json", 35 "other" 36 }; 37 38 /** 39 * String versions of CLASSIFIED_* tracking flags from nsIClassifiedChannel.idl 40 */ 41 enum MozUrlClassificationFlags { 42 "fingerprinting", 43 "fingerprinting_content", 44 "cryptomining", 45 "cryptomining_content", 46 "emailtracking", 47 "emailtracking_content", 48 "tracking", 49 "tracking_ad", 50 "tracking_analytics", 51 "tracking_social", 52 "tracking_content", 53 "socialtracking", 54 "socialtracking_facebook", 55 "socialtracking_linkedin", 56 "socialtracking_twitter", 57 "any_basic_tracking", 58 "any_strict_tracking", 59 "any_social_tracking", 60 "consentmanager", 61 "antifraud" 62 }; 63 64 /** 65 * A thin wrapper around nsIChannel and nsIHttpChannel that allows JS 66 * callers to access them without XPConnect overhead. 67 */ 68 [ChromeOnly, Exposed=Window] 69 interface ChannelWrapper : EventTarget { 70 /** 71 * Returns the wrapper instance for the given channel. The same wrapper is 72 * always returned for a given channel. 73 */ 74 static ChannelWrapper get(MozChannel channel); 75 76 /** 77 * Returns the wrapper instance for the given channel. The same wrapper is 78 * always returned for a given channel. 79 */ 80 static ChannelWrapper? getRegisteredChannel(unsigned long long aChannelId, 81 WebExtensionPolicy extension, 82 RemoteTab? remoteTab); 83 84 /** 85 * A unique ID for for the requests which remains constant throughout the 86 * redirect chain. 87 */ 88 [Constant, StoreInSlot] 89 readonly attribute unsigned long long id; 90 91 // Not technically pure, since it's backed by a weak reference, but if JS 92 // has a reference to the previous value, we can depend on it not being 93 // collected. 94 [Pure] 95 attribute MozChannel? channel; 96 97 98 /** 99 * Cancels the request with the given nsresult status code. 100 * 101 * The optional reason parameter should be one of the BLOCKING_REASON 102 * constants from nsILoadInfo.idl 103 */ 104 [Throws] 105 undefined cancel(unsigned long result, optional unsigned long reason = 0); 106 107 /** 108 * Redirects the wrapped HTTP channel to the given URI. For other channel 109 * types, this method will throw. The redirect is an internal redirect, and 110 * the behavior is the same as nsIHttpChannel.redirectTo. 111 */ 112 [Throws] 113 undefined redirectTo(URI url); 114 115 /** 116 * Requests an upgrade of the HTTP channel to a secure request. For other channel 117 * types, this method will throw. The redirect is an internal redirect, and 118 * the behavior is the same as nsIHttpChannel.upgradeToSecure. Setting this 119 * flag is only effective during the WebRequest.onBeforeRequest in 120 * Web Extensions, calling this at any other point during the request will 121 * have no effect. Setting this flag in addition to calling redirectTo 122 * results in the redirect happening rather than the upgrade request. 123 */ 124 [Throws] 125 undefined upgradeToSecure(); 126 127 /** 128 * Suspends the underlying channel. The profilerText parameter is only used 129 * to annotate profiles. 130 */ 131 [Throws] 132 undefined suspend(ByteString profileMarkerText); 133 134 /** 135 * Resumes (un-suspends) the underlying channel. 136 */ 137 [Throws] 138 undefined resume(); 139 140 /** 141 * The content type of the request, usually as read from the Content-Type 142 * header. This should be used in preference to the header to determine the 143 * content type of the channel. 144 */ 145 [Pure] 146 attribute ByteString contentType; 147 148 149 /** 150 * For HTTP requests, the request method (e.g., GET, POST, HEAD). For other 151 * request types, returns an empty string. 152 */ 153 [Cached, Pure] 154 readonly attribute ByteString method; 155 156 /** 157 * For requests with LoadInfo, the content policy type that corresponds to 158 * the request. For requests without LoadInfo, returns "other". 159 */ 160 [Cached, Pure] 161 readonly attribute MozContentPolicyType type; 162 163 164 /** 165 * When true, the request is currently suspended by the wrapper. When false, 166 * the request is not suspended by the wrapper, but may still be suspended 167 * by another caller. 168 */ 169 [Pure] 170 readonly attribute boolean suspended; 171 172 173 /** 174 * The final URI of the channel (as returned by NS_GetFinalChannelURI) after 175 * any redirects have been processed. 176 * 177 * Never null, unless the underlying channel is null. 178 */ 179 [Cached, Pure] 180 readonly attribute URI? finalURI; 181 182 /** 183 * The string version of finalURI (but cheaper to access than finalURI.spec). 184 */ 185 [Cached, Pure] 186 readonly attribute DOMString finalURL; 187 188 189 /** 190 * Returns true if the request matches the given request filter, and the 191 * given extension has permission to access it. 192 */ 193 boolean matches(optional MozRequestFilter filter = {}, 194 optional WebExtensionPolicy? extension = null, 195 optional MozRequestMatchOptions options = {}); 196 197 198 /** 199 * Register's this channel as traceable by the given add-on when accessed 200 * via the process of the given RemoteTab. 201 */ 202 undefined registerTraceableChannel(WebExtensionPolicy extension, RemoteTab? remoteTab); 203 204 /** 205 * The current HTTP status code of the request. This will be 0 if a response 206 * has not yet been received, or if the request is not an HTTP request. 207 */ 208 [Cached, Pure] 209 readonly attribute unsigned long statusCode; 210 211 /** 212 * The HTTP status line for the request (e.g., "HTTP/1.0 200 Success"). This 213 * will be an empty string if a response has not yet been received, or if 214 * the request is not an HTTP request. 215 */ 216 [Cached, Pure] 217 readonly attribute ByteString statusLine; 218 219 220 /** 221 * If the request has failed or been canceled, an opaque string representing 222 * the error. For requests that failed at the NSS layer, this is an NSS 223 * error message. For requests that failed for any other reason, it is the 224 * name of an nsresult error code. For requests which haven't failed, this 225 * is null. 226 * 227 * This string is used in the error message when notifying extension 228 * webRequest listeners of failure. The documentation specifically states 229 * that this value MUST NOT be parsed, and is only meant to be displayed to 230 * humans, but we all know how that works in real life. 231 */ 232 [Cached, Pure] 233 readonly attribute DOMString? errorString; 234 235 /** 236 * Dispatched when the channel is closed with an error status. Check 237 * errorString for the error details. 238 */ 239 attribute EventHandler onerror; 240 241 /** 242 * Checks the request's current status and dispatches an error event if the 243 * request has failed and one has not already been dispatched. 244 */ 245 undefined errorCheck(); 246 247 248 /** 249 * Dispatched when the channel begins receiving data. 250 */ 251 attribute EventHandler onstart; 252 253 /** 254 * Dispatched when the channel has finished receiving data. 255 */ 256 attribute EventHandler onstop; 257 258 259 /** 260 * Information about the proxy server which is handling this request, or 261 * null if the request is not proxied. 262 */ 263 [Cached, Frozen, GetterThrows, Pure] 264 readonly attribute MozProxyInfo? proxyInfo; 265 266 /** 267 * For HTTP requests, the IP address of the remote server handling the 268 * request. For other request types, returns null. 269 */ 270 [Cached, Pure] 271 readonly attribute ByteString? remoteAddress; 272 273 274 /** 275 * The LoadInfo object for this channel, if available. Null only if the 276 * channel is no longer alive. 277 */ 278 [Cached, Pure] 279 readonly attribute LoadInfo? loadInfo; 280 281 /** 282 * True if this load for a service worker script (either a main script or import scripts). 283 */ 284 [Cached, Pure] 285 readonly attribute boolean isServiceWorkerScript; 286 287 /** 288 * The URL of the principal that triggered this load. This is equivalent to 289 * the LoadInfo's triggeringPrincipal, and will only ever be null for 290 * requests without LoadInfo. 291 */ 292 [Cached, Pure] 293 readonly attribute ByteString? originURL; 294 295 /** 296 * The URL of the document loading the content for this request. This is 297 * equivalent to the LoadInfo's loadingPrincipal. This may only ever be null 298 * for top-level requests and requests without LoadInfo. 299 */ 300 [Cached, Pure] 301 readonly attribute ByteString? documentURL; 302 303 /** 304 * The URI version of originURL. Will be null only when originURL is null. 305 */ 306 [Pure] 307 readonly attribute URI? originURI; 308 309 /** 310 * The URI version of documentURL. Will be null only when documentURL is 311 * null. 312 */ 313 [Pure] 314 readonly attribute URI? documentURI; 315 316 317 /** 318 * True if extensions may modify this request. This is currently false only 319 * if this load was triggered by a system caller, from a restricted domain 320 * and/or a document that has access to the mozAddonManager API. 321 */ 322 [Cached, GetterThrows, Pure] 323 readonly attribute boolean canModify; 324 325 326 /** 327 * The BrowsingContext ID of the frame that the request belongs to, or 0 if it 328 * is a top-level load or does not belong to a document. 329 */ 330 [Cached, Constant] 331 readonly attribute long long frameId; 332 333 /** 334 * The BrowsingContext ID of the parent frame of the window that the request 335 * belongs to, 0 if that parent frame is the top-level frame, and -1 if the 336 * request belongs to a top-level frame. 337 */ 338 [Cached, Constant] 339 readonly attribute long long parentFrameId; 340 341 /** 342 * For cross-process requests, the <browser> or <iframe> element to which the 343 * content loading this request belongs. For requests that don't originate 344 * from a remote browser, this is null. 345 * 346 * This is not an Element because those are by default only exposed in 347 * Window, but we're exposed in System. 348 */ 349 [Cached, Pure] 350 readonly attribute nsISupports? browserElement; 351 352 /** 353 * Returns an array of objects that combine the url and frameId from the 354 * ancestorPrincipals and ancestorBrowsingContextIDs on loadInfo. 355 * The immediate parent is the first entry, the last entry is always the top 356 * level frame. It will be an empty list for toplevel window loads and 357 * non-subdocument resource loads within a toplevel window. For the latter, 358 * originURL will provide information on what window is doing the load. It 359 * will be null if the request is not associated with a window (e.g. XHR with 360 * mozBackgroundRequest = true). 361 */ 362 [Cached, Frozen, GetterThrows, Pure] 363 readonly attribute sequence<MozFrameAncestorInfo>? frameAncestors; 364 365 /** 366 * For HTTP requests, returns an array of request headers which will be, or 367 * have been, sent with this request. 368 * 369 * For non-HTTP requests, throws NS_ERROR_UNEXPECTED. 370 */ 371 [Throws] 372 sequence<MozHTTPHeader> getRequestHeaders(); 373 374 /** 375 * For HTTP requests: returns the value of the request header, null if not set. 376 * 377 * For non-HTTP requests, throws NS_ERROR_UNEXPECTED. 378 */ 379 [Throws] 380 ByteString? getRequestHeader(ByteString header); 381 382 /** 383 * For HTTP requests, returns an array of response headers which were 384 * received for this request, in the same format as returned by 385 * getRequestHeaders. 386 387 * Throws NS_ERROR_NOT_AVAILABLE if a response has not yet been received, or 388 * NS_ERROR_UNEXPECTED if the channel is not an HTTP channel. 389 * 390 * Note: The Content-Type header is handled specially. That header is 391 * usually not mutable after the request has been received, and the content 392 * type must instead be changed via the contentType attribute. If a caller 393 * attempts to set the Content-Type header via setRequestHeader, however, 394 * that value is assigned to the contentType attribute and its original 395 * string value is cached. That original value is returned in place of the 396 * actual Content-Type header. 397 */ 398 [Throws] 399 sequence<MozHTTPHeader> getResponseHeaders(); 400 401 /** 402 * Sets the given request header to the given value, overwriting any 403 * previous value. Setting a header to a null string has the effect of 404 * removing it. If merge is true, then the passed value will be merged 405 * to any existing value that exists for the header. Otherwise, any prior 406 * value for the header will be overwritten. Merge is ignored for headers 407 * that cannot be merged. 408 * 409 * For non-HTTP requests, throws NS_ERROR_UNEXPECTED. 410 */ 411 [Throws] 412 undefined setRequestHeader(ByteString header, 413 ByteString value, 414 optional boolean merge = false); 415 416 /** 417 * Sets the given response header to the given value, overwriting any 418 * previous value. Setting a header to a null string has the effect of 419 * removing it. If merge is true, then the passed value will be merged 420 * to any existing value that exists for the header (e.g. handling multiple 421 * Set-Cookie headers). Otherwise, any prior value for the header will be 422 * overwritten. Merge is ignored for headers that cannot be merged. 423 * 424 * For non-HTTP requests, throws NS_ERROR_UNEXPECTED. 425 * 426 * Note: The content type header is handled specially by this function. See 427 * getResponseHeaders() for details. 428 */ 429 [Throws] 430 undefined setResponseHeader(ByteString header, 431 ByteString value, 432 optional boolean merge = false); 433 434 /** 435 * Provides the tracking classification data when it is available. 436 */ 437 [Cached, Frozen, GetterThrows, Pure] 438 readonly attribute MozUrlClassification? urlClassification; 439 440 /** 441 * Indicates if this response and its content window hierarchy is third 442 * party. 443 */ 444 [Cached, Pure] 445 readonly attribute boolean thirdParty; 446 447 /** 448 * The current bytes sent of the request. This will be 0 if a request has not 449 * sent yet, or if the request is not an HTTP request. 450 */ 451 [Cached, Pure] 452 readonly attribute unsigned long long requestSize; 453 454 /** 455 * The current bytes received of the response. This will be 0 if a response 456 * has not recieved yet, or if the request is not an HTTP response. 457 */ 458 [Cached, Pure] 459 readonly attribute unsigned long long responseSize; 460 }; 461 462 /** 463 * Wrapper for first and third party tracking classification data. 464 */ 465 dictionary MozUrlClassification { 466 required sequence<MozUrlClassificationFlags> firstParty; 467 required sequence<MozUrlClassificationFlags> thirdParty; 468 }; 469 470 /** 471 * Information about the proxy server handing a request. This is approximately 472 * equivalent to nsIProxyInfo. 473 */ 474 dictionary MozProxyInfo { 475 /** 476 * The hostname of the server. 477 */ 478 required ByteString host; 479 /** 480 * The TCP port of the server. 481 */ 482 required long port; 483 /** 484 * The type of proxy (e.g., HTTP, SOCKS). 485 */ 486 required ByteString type; 487 488 /** 489 * True if the proxy is responsible for DNS lookups. 490 */ 491 required boolean proxyDNS; 492 493 /** 494 * The authentication username for the proxy, if any. 495 */ 496 ByteString? username = null; 497 498 /** 499 * The timeout, in seconds, before the network stack will failover to the 500 * next candidate proxy server if it has not received a response. 501 */ 502 unsigned long failoverTimeout; 503 504 /** 505 * Any non-empty value will be passed directly as Proxy-Authorization header 506 * value for the CONNECT request attempt. However, this header set on the 507 * resource request itself takes precedence. 508 */ 509 ByteString? proxyAuthorizationHeader = null; 510 511 /** 512 * An optional key used for additional isolation of this proxy connection. 513 */ 514 ByteString? connectionIsolationKey = null; 515 }; 516 517 /** 518 * MozFrameAncestorInfo combines loadInfo::AncestorPrincipals with 519 * loadInfo::AncestorBrowsingContextIDs for easier access in the WebRequest API. 520 * 521 * url represents the parent of the loading window. 522 * frameId is the browsingContextId for the parent of the loading window. 523 * 524 * For further details see AncestorPrincipals in nsILoadInfo.idl. 525 */ 526 dictionary MozFrameAncestorInfo { 527 required ByteString url; 528 required unsigned long long frameId; 529 }; 530 531 /** 532 * Represents an HTTP request or response header. 533 */ 534 dictionary MozHTTPHeader { 535 /** 536 * The case-insensitive, non-case-normalized header name. 537 */ 538 required ByteString name; 539 /** 540 * The header value. 541 */ 542 required ByteString value; 543 }; 544 545 /** 546 * An object used for filtering requests. 547 */ 548 dictionary MozRequestFilter { 549 /** 550 * If present, the request only matches if its `type` attribute matches one 551 * of the given types. 552 */ 553 sequence<MozContentPolicyType>? types = null; 554 555 /** 556 * If present, the request only matches if its finalURI matches the given 557 * match pattern set. 558 */ 559 MatchPatternSet? urls = null; 560 561 /** 562 * If present, the request only matches if the loadInfo privateBrowsingId matches 563 * against the given incognito value. 564 */ 565 boolean? incognito = null; 566 }; 567 568 dictionary MozRequestMatchOptions { 569 /** 570 * True if we're matching for the proxy portion of a proxied request. 571 */ 572 boolean isProxy = false; 573 };