dom/chrome-webidl/ChannelWrapper.webidl

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