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