netwerk/protocol/http/nsIHttpChannel.idl
author Andrea Marchesini <amarchesini@mozilla.com>
Sun, 17 Mar 2019 06:55:50 +0000
changeset 464493 8ee97c045359ecd958e1032b0d6617741f20cf00
parent 464434 fbb0b16293f0ecf46837f473e4b02235d13b3db5
child 466347 597f8780f0739773985dead402389283cda61fb8
permissions -rw-r--r--
Bug 1535799 - nsIHttpChannel.isTrackingResource should be a method, r=Ehsan Differential Revision: https://phabricator.services.mozilla.com/D23765

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsIChannel.idl"

interface nsIHttpHeaderVisitor;

/**
 * nsIHttpChannel
 *
 * This interface allows for the modification of HTTP request parameters and
 * the inspection of the resulting HTTP response status and headers when they
 * become available.
 */
[builtinclass, scriptable, uuid(c5a4a073-4539-49c7-a3f2-cec3f0619c6c)]
interface nsIHttpChannel : nsIChannel
{
    /**************************************************************************
     * REQUEST CONFIGURATION
     *
     * Modifying request parameters after asyncOpen has been called is an error.
     */

    /**
     * Set/get the HTTP request method (default is "GET").  Both setter and
     * getter are case sensitive.
     *
     * This attribute may only be set before the channel is opened.
     *
     * NOTE: The data for a "POST" or "PUT" request can be configured via
     * nsIUploadChannel; however, after setting the upload data, it may be
     * necessary to set the request method explicitly.  The documentation
     * for nsIUploadChannel has further details.
     *
     * @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened.
     */
    [must_use] attribute ACString requestMethod;

    /**
     * Get/set the HTTP referrer URI.  This is the address (URI) of the
     * resource from which this channel's URI was obtained (see RFC2616 section
     * 14.36).
     *
     * This attribute may only be set before the channel is opened.
     *
     * NOTE: The channel may silently refuse to set the Referer header if the
     * URI does not pass certain security checks (e.g., a "https://" URL will
     * never be sent as the referrer for a plaintext HTTP request).  The
     * implementation is not required to throw an exception when the referrer
     * URI is rejected.
     *
     * @throws NS_ERROR_IN_PROGRESS if set after the channel has been opened.
     * @throws NS_ERROR_FAILURE if used for setting referrer during
     *         visitRequestHeaders. Getting the value will not throw.
     */
    [must_use] attribute nsIURI referrer;

    /**
     * Referrer policies. See ReferrerPolicy.h for more details.
     */


    /*   The undefined state, or no referrer policy, usually causing a fallback
         to a referrer policy definded elsewhere */
    const unsigned long REFERRER_POLICY_UNSET                      = 0;

    /*   default state, doesn't send referrer from https->http          */
    const unsigned long REFERRER_POLICY_NO_REFERRER_WHEN_DOWNGRADE = 1;
    /*   sends no referrer                                              */
    const unsigned long REFERRER_POLICY_NO_REFERRER                = 2;
    /*   only sends the origin of the referring URL                     */
    const unsigned long REFERRER_POLICY_ORIGIN                     = 3;
    /*   same as default, but reduced to ORIGIN when cross-origin.      */
    const unsigned long REFERRER_POLICY_ORIGIN_WHEN_XORIGIN        = 4;
    /*   always sends the referrer, even on downgrade.                  */
    const unsigned long REFERRER_POLICY_UNSAFE_URL                 = 5;
    /*   send referrer when same-origin, no referrer when cross-origin  */
    const unsigned long REFERRER_POLICY_SAME_ORIGIN                = 6;
    /*   send origin when request from https->https or http->http(s)
         No referrer when request from https->http. */
    const unsigned long REFERRER_POLICY_STRICT_ORIGIN              = 7;
    /*   send referrer when same-origin,
         Send origin when cross-origin from https->https or http->http(s)
         No referrer when request from https->http. */
    const unsigned long REFERRER_POLICY_STRICT_ORIGIN_WHEN_XORIGIN = 8;

    /**
     * Get the HTTP referrer policy.  The policy is retrieved from the meta
     * referrer tag, which can be one of many values (see ReferrerPolicy.h for
     * more details).
     */
    [must_use] readonly attribute unsigned long referrerPolicy;

    /**
     * Set the HTTP referrer URI with a referrer policy.
     * @throws NS_ERROR_FAILURE if called during visitRequestHeaders.
     */
    [must_use]
    void setReferrerWithPolicy(in nsIURI referrer, in unsigned long referrerPolicy);

    /**
     * Returns the network protocol used to fetch the resource as identified
     * by the ALPN Protocol ID.
     *
     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
     *         has been received (before onStartRequest).
     */
    [must_use] readonly attribute ACString protocolVersion;

    /**
     * size consumed by the response header fields and the response payload body
     */
    [must_use] readonly attribute uint64_t transferSize;

    /**
     * The size of the message body received by the client,
     * after removing any applied content-codings
     */
    [must_use] readonly attribute uint64_t decodedBodySize;

    /**
     * The size in octets of the payload body, prior to removing content-codings
     */
    [must_use] readonly attribute uint64_t encodedBodySize;

    /**
     * Get the value of a particular request header.
     *
     * @param aHeader
     *        The case-insensitive name of the request header to query (e.g.,
     *        "Cache-Control").
     *
     * @return the value of the request header.
     * @throws NS_ERROR_NOT_AVAILABLE if the header is not set.
     */
    [must_use] ACString getRequestHeader(in ACString aHeader);

    /**
     * Set the value of a particular request header.
     *
     * This method allows, for example, the cookies module to add "Cookie"
     * headers to the outgoing HTTP request.
     *
     * This method may only be called before the channel is opened.
     *
     * @param aHeader
     *        The case-insensitive name of the request header to set (e.g.,
     *        "Cookie").
     * @param aValue
     *        The request header value to set (e.g., "X=1").
     * @param aMerge
     *        If true, the new header value will be merged with any existing
     *        values for the specified header.  This flag is ignored if the
     *        specified header does not support merging (e.g., the "Content-
     *        Type" header can only have one value).  The list of headers for
     *        which this flag is ignored is an implementation detail.  If this
     *        flag is false, then the header value will be replaced with the
     *        contents of |aValue|.
     *
     * If aValue is empty and aMerge is false, the header will be cleared.
     *
     * @throws NS_ERROR_IN_PROGRESS if called after the channel has been
     *         opened.
     * @throws NS_ERROR_FAILURE if called during visitRequestHeaders.
     */
    [must_use] void setRequestHeader(in ACString aHeader,
                                     in ACString aValue,
                                     in boolean aMerge);

    /**
     * Set a request header with empty value.
     *
     * This should be used with caution in the cases where the behavior of
     * setRequestHeader ignoring empty header values is undesirable.
     *
     * This method may only be called before the channel is opened.
     *
     * @param aHeader
     *        The case-insensitive name of the request header to set (e.g.,
     *        "Cookie").
     *
     * @throws NS_ERROR_IN_PROGRESS if called after the channel has been
     *         opened.
     * @throws NS_ERROR_FAILURE if called during visitRequestHeaders.
     */
    [must_use] void setEmptyRequestHeader(in ACString aHeader);

    /**
     * Call this method to visit all request headers.  Calling setRequestHeader
     * while visiting request headers has undefined behavior.  Don't do it!
     *
     * @param aVisitor
     *        the header visitor instance.
     */
    [must_use] void visitRequestHeaders(in nsIHttpHeaderVisitor aVisitor);

    /**
     * Call this method to visit all non-default (UA-provided) request headers.
     * Calling setRequestHeader while visiting request headers has undefined
     * behavior. Don't do it!
     *
     * @param aVisitor
     *        the header visitor instance.
     */
    [must_use]
    void visitNonDefaultRequestHeaders(in nsIHttpHeaderVisitor aVisitor);

    /**
     * This attribute no longer has any effect, it remains for backwards compat
     *
     * @throws NS_ERROR_FAILURE if set after the channel has been opened.
     */
    [must_use] attribute boolean allowPipelining;

    /**
     * This attribute of the channel indicates whether or not
     * the underlying HTTP transaction should be honor stored Strict Transport
     * Security directives for its principal. It defaults to true. Using
     * OCSP to bootstrap the HTTPs is the likely use case for setting it to
     * false.
     *
     * This attribute may only be set before the channel is opened.
     *
     * @throws NS_ERROR_IN_PROGRESS or NS_ERROR_ALREADY_OPENED
     *         if called after the channel has been opened.
     */
    [must_use] attribute boolean allowSTS;

    /**
     * This attribute specifies the number of redirects this channel is allowed
     * to make.  If zero, the channel will fail to redirect and will generate
     * a NS_ERROR_REDIRECT_LOOP failure status.
     *
     * NOTE: An HTTP redirect results in a new channel being created.  If the
     * new channel supports nsIHttpChannel, then it will be assigned a value
     * to its |redirectionLimit| attribute one less than the value of the
     * redirected channel's |redirectionLimit| attribute.  The initial value
     * for this attribute may be a configurable preference (depending on the
     * implementation).
     */
    [must_use] attribute unsigned long redirectionLimit;


    /**************************************************************************
     * RESPONSE INFO
     *
     * Accessing response info before the onStartRequest event is an error.
     */

    /**
     * Get the HTTP response code (e.g., 200).
     *
     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
     *         has been received (before onStartRequest).
     */
    [must_use] readonly attribute unsigned long responseStatus;

    /**
     * Get the HTTP response status text (e.g., "OK").
     *
     * NOTE: This returns the raw (possibly 8-bit) text from the server.  There
     * are no assumptions made about the charset of the returned text.  You
     * have been warned!
     *
     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
     *         has been received (before onStartRequest).
     */
    [must_use] readonly attribute ACString responseStatusText;

    /**
     * Returns true if the HTTP response code indicates success.  The value of
     * nsIRequest::status will be NS_OK even when processing a 404 response
     * because a 404 response may include a message body that (in some cases)
     * should be shown to the user.
     *
     * Use this attribute to distinguish server error pages from normal pages,
     * instead of comparing the response status manually against the set of
     * valid response codes, if that is required by your application.
     *
     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
     *         has been received (before onStartRequest).
     */
    [must_use] readonly attribute boolean requestSucceeded;

   /** Indicates whether channel should be treated as the main one for the
    *  current document.  If manually set to true, will always remain true.  Otherwise,
    *  will be true if LOAD_DOCUMENT_URI is set in the channel's loadflags.
    */
    [must_use] attribute boolean isMainDocumentChannel;

    /**
     * Get the value of a particular response header.
     *
     * @param aHeader
     *        The case-insensitive name of the response header to query (e.g.,
     *        "Set-Cookie").
     *
     * @return the value of the response header.
     *
     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
     *         has been received (before onStartRequest) or if the header is
     *         not set in the response.
     */
    [must_use] ACString getResponseHeader(in ACString header);

    /**
     * Set the value of a particular response header.
     *
     * This method allows, for example, the HTML content sink to inform the HTTP
     * channel about HTTP-EQUIV headers found in HTML <META> tags.
     *
     * @param aHeader
     *        The case-insensitive name of the response header to set (e.g.,
     *        "Cache-control").
     * @param aValue
     *        The response header value to set (e.g., "no-cache").
     * @param aMerge
     *        If true, the new header value will be merged with any existing
     *        values for the specified header.  This flag is ignored if the
     *        specified header does not support merging (e.g., the "Content-
     *        Type" header can only have one value).  The list of headers for
     *        which this flag is ignored is an implementation detail.  If this
     *        flag is false, then the header value will be replaced with the
     *        contents of |aValue|.
     *
     * If aValue is empty and aMerge is false, the header will be cleared.
     *
     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
     *         has been received (before onStartRequest).
     * @throws NS_ERROR_ILLEGAL_VALUE if changing the value of this response
     *         header is not allowed.
     * @throws NS_ERROR_FAILURE if called during visitResponseHeaders,
     *         VisitOriginalResponseHeaders or getOriginalResponseHeader.
     */
    [must_use] void setResponseHeader(in ACString header,
                                      in ACString value,
                                      in boolean merge);

    /**
     * Call this method to visit all response headers.  Calling
     * setResponseHeader while visiting response headers has undefined
     * behavior.  Don't do it!
     *
     * @param aVisitor
     *        the header visitor instance.
     *
     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
     *         has been received (before onStartRequest).
     */
    [must_use] void visitResponseHeaders(in nsIHttpHeaderVisitor aVisitor);

     /**
     * Get the value(s) of a particular response header in the form and order
     * it has been received from the remote peer. There can be multiple headers
     * with the same name.
     *
     * @param aHeader
     *        The case-insensitive name of the response header to query (e.g.,
     *        "Set-Cookie").
     *
     * @param aVisitor
     *        the header visitor instance.
     *
     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
     *         has been received (before onStartRequest) or if the header is
     *         not set in the response.
     */
    [must_use] void getOriginalResponseHeader(in ACString aHeader,
                                              in nsIHttpHeaderVisitor aVisitor);

    /**
     * Call this method to visit all response headers in the form and order as
     * they have been received from the remote peer.
     * Calling setResponseHeader while visiting response headers has undefined
     * behavior.  Don't do it!
     *
     * @param aVisitor
     *        the header visitor instance.
     *
     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
     *         has been received (before onStartRequest).
     */
    [must_use]
    void visitOriginalResponseHeaders(in nsIHttpHeaderVisitor aVisitor);

    /**
     * Returns true if the server sent a "Cache-Control: no-store" response
     * header.
     *
     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
     *         has been received (before onStartRequest).
     */
    [must_use] boolean isNoStoreResponse();

    /**
     * Returns true if the server sent the equivalent of a "Cache-control:
     * no-cache" response header.  Equivalent response headers include:
     * "Pragma: no-cache", "Expires: 0", and "Expires" with a date value
     * in the past relative to the value of the "Date" header.
     *
     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
     *         has been received (before onStartRequest).
     */
    [must_use] boolean isNoCacheResponse();

    /**
     * Returns true if the server sent a "Cache-Control: private" response
     * header.
     *
     * @throws NS_ERROR_NOT_AVAILABLE if called before the response
     *         has been received (before onStartRequest).
     */
    [must_use] boolean isPrivateResponse();

    /**
     * Instructs the channel to immediately redirect to a new destination.
     * Can only be called on channels that have not yet called their
     * listener's OnStartRequest(). Generally that means the latest time
     * this can be used is one of:
     *    "http-on-examine-response"
     *    "http-on-examine-merged-response"
     *    "http-on-examine-cached-response"
     *
     * When non-null URL is set before AsyncOpen:
     *  we attempt to redirect to the targetURI before we even start building
     *  and sending the request to the cache or the origin server.
     *  If the redirect is vetoed, we fail the channel.
     *
     * When set between AsyncOpen and first call to OnStartRequest being called:
     *  we attempt to redirect before we start delivery of network or cached
     *  response to the listener.  If vetoed, we continue with delivery of
     *  the original content to the channel listener.
     *
     * When passed aTargetURI is null the channel behaves normally (can be
     * rewritten).
     *
     * This method provides no explicit conflict resolution. The last
     * caller to call it wins.
     *
     * @throws NS_ERROR_NOT_AVAILABLE if called after the channel has already
     *         started to deliver the content to its listener.
     */
    [must_use] void redirectTo(in nsIURI aTargetURI);

    /**
     * Instructs the channel to be loaded in a new process. Like 'redirectTo'
     * this can only be used on channels that have not yet called their
     * listener's OnStartRequest().
     *
     * @param aTabPromise   a promise which resolves to a nsITabParent object
     *                      which the load will proceed in.
     * @param aIdentifier   a 64-bit ID which will be provided to the
     *                      ChildProcessChannelListener.
     */
    [must_use] void switchProcessTo(in Promise aTabPromise,
                                    in unsigned long long aIdentifier);

    /**
     * Used to determine if there is a Cross-Origin-Opener-Policy mismatch
     * that would require switching the channel to another process.
     * @throws NS_ERROR_NOT_AVAILABLE if we don't have a responseHead
     */
    [must_use] boolean hasCrossOriginOpenerPolicyMismatch();

    /**
     * Flags a channel to be upgraded to HTTPS.
     *
     * Upgrading to a secure channel must happen before or during
     * "http-on-modify-request". If redirectTo is called early as well, it
     * will win and upgradeToSecure will be a no-op.
     *
     * @throws NS_ERROR_NOT_AVAILABLE if called after the channel has already
     *         started to deliver the content to its listener.
     */
    [must_use] void upgradeToSecure();

    /**
     * Identifies the request context for this load.
     */
    [noscript, must_use] attribute uint64_t requestContextID;

    /**
     * Unique ID of the channel, shared between parent and child. Needed if
     * the channel activity needs to be monitored across process boundaries,
     * like in devtools net monitor. See bug 1274556.
     */
    [must_use] attribute uint64_t channelId;

    /**
     * ID of the top-level document's inner window.  Identifies the content
     * this channels is being load in.
     */
    [must_use] attribute uint64_t topLevelContentWindowId;

    /**
     * Returns the classification flags if the channel has been processed by
     * URL-Classifier features and is considered first-party.
     */
    [infallible] readonly attribute unsigned long firstPartyClassificationFlags;

    /**
     * Returns the classification flags if the channel has been processed by
     * URL-Classifier features and is considered third-party with the top
     * window URI.
     */
    [infallible] readonly attribute unsigned long thirdPartyClassificationFlags;

    /*
     * Returns the classification flags if the channel has been processed by
     * URL-Classifier features. This value is equal to
     * "firstPartyClassificationFlags || thirdPartyClassificationFlags".
     *
     * Note that top-level channels could be classified as well.
     * In order to identify third-party resources specifically, use
     * classificationThirdPartyFlags;
     */
    [infallible] readonly attribute unsigned long classificationFlags;

    cenum ClassificationFlags : 32 {
      /**
       * The resource is on the fingerprinting list. This is only available if
       * the privacy.trackingprotection.fingerprinting_annotate_enabled pref.
       */
      CLASSIFIED_FINGERPRINTING = 0x01,

      /**
       * The resource is on the cryptomining list. This is only available if
       * the privacy.trackingprotection.cryptomining_annotate_enabled pref is set.
       */
      CLASSIFIED_CRYPTOMINING = 0x02,

      /**
       * The following are about tracking annotation and are available only
       * if the privacy.trackingprotection.annotate_channels pref.
       * CLASSIFIED_TRACKING is set if we are not able to identify the
       * type of classification.
       */
      CLASSIFIED_TRACKING = 0x04,
      CLASSIFIED_TRACKING_AD = 0x08,
      CLASSIFIED_TRACKING_ANALYTICS = 0x10,
      CLASSIFIED_TRACKING_SOCIAL = 0x20,
      CLASSIFIED_TRACKING_CONTENT = 0x40,

      /**
       * This is exposed to help to identify tracking classification
       */
      CLASSIFIED_ANY_TRACKING = CLASSIFIED_TRACKING |
        CLASSIFIED_TRACKING_AD | CLASSIFIED_TRACKING_ANALYTICS |
        CLASSIFIED_TRACKING_SOCIAL | CLASSIFIED_TRACKING_CONTENT |
        CLASSIFIED_FINGERPRINTING,
    };

    /**
     * Returns true if the channel has loaded a resource that is classified as
     * tracker.
     * This is a helper attribute which returns the same value of
     * (classificationFlags & CLASSIFIED_ANY_TRACKING)
     *
     * Note that top-level channels could be marked as tracking
     * resource. In order to identify third-party tracking resources
     * specifically, use isThirdPartyTrackingResource().
     */
    boolean isTrackingResource();

%{ C++
  inline bool IsTrackingResource()
  {
    bool value = false;
    if (NS_SUCCEEDED(IsTrackingResource(&value)) && value) {
      return true;
    }
    return false;
  }
%}

    /**
     * Returns the classification flags if the channel has been processed by
     * URL-Classifier features and is considered third-party with the top
     * window URI.
     *
     * This is a helper attribute which returns the same value of
     * (thirdPartyClassificationFlags & CLASSIFIED_ANY_TRACKING)
     */
    boolean isThirdPartyTrackingResource();

%{ C++
  inline bool IsThirdPartyTrackingResource()
  {
    bool value = false;
    if (NS_SUCCEEDED(IsThirdPartyTrackingResource(&value)) && value) {
      return true;
    }
    return false;
  }
%}

    /**
     * Returns the allowing status for flash plugin for this channel.
     */
    cenum FlashPluginState : 8 {
      FlashPluginUnknown = 0,
      FlashPluginAllowed = 1,
      FlashPluginDenied = 2,
      FlashPluginDeniedInSubdocuments = 3,

      // Keep this equal to the last value.
      FlashPluginLastValue = 3,
    };
    [infallible] readonly attribute nsIHttpChannel_FlashPluginState flashPluginState;

    /**
     * This method is used by the document.cookie call site in order
     * to override the tracking status of an HTTP channel. This should
     * only be called by Gecko under certain circumstances when Gecko
     * can guarantee that the channel classifier service will not be
     * determining the tracking status of the channel.
     *
     * @param aDocumentChannel
     *        The document channel from which to copy the tracking flags
     *
     * Please avoid calling this API if you're unsure whether you
     * should be using it.
     */
    [noscript] void overrideTrackingFlagsForDocumentCookieAccessor(in nsIHttpChannel aDocumentChannel);

    /**
     * ID of the top-level outer content window. Identifies this channel's
     * top-level window it comes from.
     *
     * NOTE: The setter of this attribute is currently for xpcshell test only.
     *       Don't alter it otherwise.
     */
    [must_use] attribute uint64_t topLevelOuterContentWindowId;

    /**
     * In e10s, the information that the CORS response blocks the load is in the
     * parent, which doesn't know the true window id of the request, so we may
     * need to proxy the request to the child.
     *
     * @param aMessage
     *        The message to print in the console.
     *
     * @param aCategory
     *        The category under which the message should be displayed.
     */
    void logBlockedCORSRequest(in AString aMessage, in ACString aCategory);

    void logMimeTypeMismatch(in ACString aMessageName,
                             in boolean aWarning,
                             in AString aURL,
                             in AString aContentType);
};