tor-browser

nsIHttpChannel.idl (20033B)

---

/* -*- 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;
interface nsIReferrerInfo;

%{C++
#include "GeckoProfiler.h"
namespace mozilla::net {
class DictionaryCacheEntry;
}
%}

[ptr] native DictionaryCacheEntry(mozilla::net::DictionaryCacheEntry);

native UniqueProfileChunkedBuffer(mozilla::UniquePtr<mozilla::ProfileChunkedBuffer>);

/**
* 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 : nsIIdentChannel
{
   /**************************************************************************
    * 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 referrer information.  This contains the referrer (URI) of the
    * resource from which this channel's URI was obtained (see RFC2616 section
    * 14.36) and the referrer policy applied to the referrer.
    *
    * This attribute may only be set before the channel is opened.
    *
    * Setting this attribute will clone new referrerInfo object by default.
    *
    * 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, infallible] attribute nsIReferrerInfo referrerInfo;

   /**
    * Set referrer Info without clone new object.
    * Use this api only when you are passing a referrerInfo to the channel with
    * 1-1 relationship. Don't use this api if you will reuse the referrer info
    * object later. For example when to use:
    * channel.setReferrerInfoWithoutClone(new ReferrerInfo());
    *
    */
   [must_use, noscript]
   void setReferrerInfoWithoutClone(in nsIReferrerInfo aReferrerInfo);

   /**
    * 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;

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

   /**
    * 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);

   /**
    * Creates and sets new ReferrerInfo object
    * @param aUrl          referrer url
    * @param aPolicy       referrer policy of the created object
    * @param aSendReferrer indicates if the referrer should not be sent or not
    *                      even when it's available.
    */
   [must_use] void setNewReferrerInfo(in ACString aUrl,
                                      in nsIReferrerInfo_ReferrerPolicyIDL aPolicy,
                                      in boolean aSendReferrer);

   /**
    * 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);

   /**
    * Call this method to see if we need to strip the request body headers
    * for the new http channel. This should be called during redirection.
    */
   [must_use] boolean ShouldStripRequestBodyHeader(in ACString aMethod);

   /**
    * 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();

   /**
    * 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);

   /**
    * 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;

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

   /**
    * ID of the browser for this channel.
    *
    * NOTE: The setter of this attribute is currently for xpcshell test only.
    *       Don't alter it otherwise.
    */
   [must_use] attribute uint64_t browserId;

   /**
    * 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.
    *
    * @param aIsWarning
    *        When true, this is a warning message.
    */
   void logBlockedCORSRequest(in AString aMessage,
                              in ACString aCategory,
                              in boolean aIsWarning);

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

   [notxpcom, nostdcall] void setSource(in UniqueProfileChunkedBuffer aSource);

   [must_use] attribute AString classicScriptHintCharset;

   [must_use] attribute AString documentCharacterSet;

   /**
    * Update the requestObserversCalled boolean flag.
    *
    * Used by WebDriver BiDi network interception to modify properties of the
    * request such as `method` or `body` as late as possible.
    */
   [must_use] attribute boolean requestObserversCalled;

   /**
    * Used to indicate that user agent was overridden or override was reset
    * and user agent on the channel is outdated.
    */
   [noscript, must_use] attribute boolean isUserAgentHeaderOutdated;
   /**
    * Dictionary for decompression, if any
    */
   [noscript] attribute DictionaryCacheEntry decompressDictionary;
};