netwerk/base/nsINetworkInterceptController.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7 #include "nsIContentPolicy.idl"
   8
   9 interface nsICacheInfoChannel;
  10 interface nsIChannel;
  11 interface nsIConsoleReportCollector;
  12 interface nsIInputStream;
  13 interface nsIOutputStream;
  14 interface nsIURI;
  15
  16 %{C++
  17 #include "nsContentUtils.h"
  18 #include "nsIChannel.h"
  19 #include "nsIConsoleReportCollector.h"
  20 #include "nsILoadInfo.h"
  21 namespace mozilla {
  22 class TimeStamp;
  23
  24 namespace dom {
  25 class ChannelInfo;
  26 }
  27 }
  28 %}
  29
  30 native TimeStamp(mozilla::TimeStamp);
  31
  32 [ptr] native ChannelInfo(mozilla::dom::ChannelInfo);
  33
  34 /**
  35  * Interface allowing the nsIInterceptedChannel to callback when it is
  36  * done reading from the body stream.
  37  */
  38 [scriptable, uuid(51039eb6-bea0-40c7-b523-ccab56cc4fde)]
  39 interface nsIInterceptedBodyCallback : nsISupports
  40 {
  41   void bodyComplete(in nsresult aRv);
  42 };
  43
  44 /**
  45  * Interface to allow implementors of nsINetworkInterceptController to control the behaviour
  46  * of intercepted channels without tying implementation details of the interception to
  47  * the actual channel. nsIInterceptedChannel is expected to be implemented by objects
  48  * which do not implement nsIChannel.
  49  */
  50
  51 [scriptable, uuid(f4b82975-6a86-4cc4-87fe-9a1fd430c86d)]
  52 interface nsIInterceptedChannel : nsISupports
  53 {
  54     /**
  55      * Instruct a channel that has been intercepted to continue with the original
  56      * network request.
  57      */
  58     void resetInterception();
  59
  60     /**
  61      * Set the status and reason for the forthcoming synthesized response.
  62      * Multiple calls overwrite existing values.
  63      */
  64     void synthesizeStatus(in uint16_t status, in ACString reason);
  65
  66     /**
  67      * Attach a header name/value pair to the forthcoming synthesized response.
  68      * Overwrites any existing header value.
  69      */
  70     void synthesizeHeader(in ACString name, in ACString value);
  71
  72     /**
  73      * Instruct a channel that has been intercepted that a response is
  74      * starting to be synthesized.  No further header modification is allowed
  75      * after this point.  There are a few parameters:
  76      * - A body stream may be optionally passed.  If nullptr, then an
  77      *   empty body is assumed.
  78      * - A callback may be optionally passed.  It will be invoked
  79      *   when the body is complete.  For a nullptr body this may be
  80      *   synchronously on the current thread.  Otherwise it will be invoked
  81      *   asynchronously on the current thread.
  82      * - A cacheInfoChannel may be optionally passed. If the body stream is
  83      *   from alternative data cache, this cacheInfoChannel provides needed
  84      *   cache information.
  85      * - The caller may optionally pass a spec for a URL that this response
  86      *   originates from; an empty string will cause the original
  87      *   intercepted request's URL to be used instead.
  88      * - The responseRedirected flag is false will cause the channel do an
  89      *   internal redirect when the original intercepted reauest's URL is
  90      *   different from the response's URL. The flag is true will cause the
  91      *   chaanel do a non-internal redirect when the URLs are different.
  92      */
  93     void startSynthesizedResponse(in nsIInputStream body,
  94                                   in nsIInterceptedBodyCallback callback,
  95                                   in nsICacheInfoChannel channel,
  96                                   in ACString finalURLSpec,
  97                                   in bool responseRedirected);
  98
  99     /**
 100      * Instruct a channel that has been intercepted that response synthesis
 101      * has completed and all outstanding resources can be closed.
 102      */
 103     void finishSynthesizedResponse();
 104
 105     /**
 106      * Cancel the pending intercepted request.
 107      * @return NS_ERROR_FAILURE if the response has already been synthesized or
 108      *         the original request has been instructed to continue.
 109      */
 110     void cancelInterception(in nsresult status);
 111
 112     /**
 113      * The underlying channel object that was intercepted.
 114      */
 115     readonly attribute nsIChannel channel;
 116
 117     /**
 118      * The URL of the underlying channel object, corrected for a potential
 119      * secure upgrade.
 120      */
 121     readonly attribute nsIURI secureUpgradedChannelURI;
 122
 123     /**
 124      * This method allows to override the channel info for the channel.
 125      */
 126     [noscript]
 127     void setChannelInfo(in ChannelInfo channelInfo);
 128
 129     /**
 130      * Get the internal load type from the underlying channel.
 131      */
 132     [noscript]
 133     readonly attribute nsContentPolicyType internalContentPolicyType;
 134
 135     [noscript]
 136     readonly attribute nsIConsoleReportCollector consoleReportCollector;
 137
 138     /**
 139      * Save the timestamps of various service worker interception phases.
 140      */
 141     [noscript]
 142     void SetLaunchServiceWorkerStart(in TimeStamp aTimeStamp);
 143
 144     // A hack to get sw launch start time for telemetry.
 145     [noscript]
 146     void GetLaunchServiceWorkerStart(out TimeStamp aTimeStamp);
 147
 148     [noscript]
 149     void SetLaunchServiceWorkerEnd(in TimeStamp aTimeStamp);
 150
 151     // A hack to get sw launch end time for telemetry.
 152     [noscript]
 153     void GetLaunchServiceWorkerEnd(out TimeStamp aTimeStamp);
 154
 155     [noscript]
 156     void SetDispatchFetchEventStart(in TimeStamp aTimeStamp);
 157
 158     [noscript]
 159     void SetDispatchFetchEventEnd(in TimeStamp aTimeStamp);
 160
 161     [noscript]
 162     void SetHandleFetchEventStart(in TimeStamp aTimeStamp);
 163
 164     [noscript]
 165     void SetHandleFetchEventEnd(in TimeStamp aTimeStamp);
 166
 167     // Depending on the outcome we measure the time difference between
 168     // |FinishResponseStart| and either |FinishSynthesizedResponseEnd| or
 169     // |ChannelResetEnd|.
 170     [noscript]
 171     void SetFinishResponseStart(in TimeStamp aTimeStamp);
 172
 173     [noscript]
 174     void SetFinishSynthesizedResponseEnd(in TimeStamp aTimeStamp);
 175
 176     [noscript]
 177     void SetChannelResetEnd(in TimeStamp aTimeStamp);
 178
 179     [noscript]
 180     void SaveTimeStamps();
 181
 182 %{C++
 183     already_AddRefed<nsIConsoleReportCollector>
 184     GetConsoleReportCollector()
 185     {
 186       nsCOMPtr<nsIConsoleReportCollector> reporter;
 187       GetConsoleReportCollector(getter_AddRefs(reporter));
 188       return reporter.forget();
 189     }
 190
 191     void
 192     GetSubresourceTimeStampKey(nsIChannel* aChannel, nsACString& aKey)
 193     {
 194       if (!nsContentUtils::IsNonSubresourceRequest(aChannel)) {
 195         nsCOMPtr<nsILoadInfo> loadInfo = aChannel->GetLoadInfo();
 196         if (loadInfo) {
 197           switch(loadInfo->InternalContentPolicyType()) {
 198             case nsIContentPolicy::TYPE_SCRIPT:
 199             case nsIContentPolicy::TYPE_INTERNAL_SCRIPT:
 200             case nsIContentPolicy::TYPE_INTERNAL_SCRIPT_PRELOAD:
 201             case nsIContentPolicy::TYPE_INTERNAL_WORKER_IMPORT_SCRIPTS: {
 202               aKey = NS_LITERAL_CSTRING("subresource-script");
 203               break;
 204             }
 205             case nsIContentPolicy::TYPE_IMAGE:
 206             case nsIContentPolicy::TYPE_INTERNAL_IMAGE:
 207             case nsIContentPolicy::TYPE_INTERNAL_IMAGE_PRELOAD:
 208             case nsIContentPolicy::TYPE_INTERNAL_IMAGE_FAVICON: {
 209               aKey = NS_LITERAL_CSTRING("subresource-image");
 210               break;
 211             }
 212             case nsIContentPolicy::TYPE_STYLESHEET:
 213             case nsIContentPolicy::TYPE_INTERNAL_STYLESHEET:
 214             case nsIContentPolicy::TYPE_INTERNAL_STYLESHEET_PRELOAD: {
 215               aKey = NS_LITERAL_CSTRING("subresource-stylesheet");
 216               break;
 217             }
 218             default: {
 219               aKey = NS_LITERAL_CSTRING("subresource-other");
 220               break;
 221             }
 222           }
 223         }
 224       }
 225     }
 226 %}
 227
 228     /**
 229      * Allow the ServiceWorkerManager to set an RAII-style object on the
 230      * intercepted channel that should be released once the channel is
 231      * torn down.
 232      */
 233     [noscript]
 234     void setReleaseHandle(in nsISupports aHandle);
 235 };
 236
 237 /**
 238  * Interface to allow consumers to attach themselves to a channel's
 239  * notification callbacks/loadgroup and determine if a given channel
 240  * request should be intercepted before any network request is initiated.
 241  */
 242
 243 [scriptable, uuid(70d2b4fe-a552-48cd-8d93-1d8437a56b53)]
 244 interface nsINetworkInterceptController : nsISupports
 245 {
 246     /**
 247      * Returns true if a channel should avoid initiating any network
 248      * requests until specifically instructed to do so.
 249      *
 250      * @param aURI The URI to be loaded.  Note, this may differ from
 251      *             the channel's current URL in some cases.
 252      * @param aChannel The channel that may be intercepted.  It will
 253      *                 be in the state prior to calling OnStartRequest().
 254      */
 255     bool shouldPrepareForIntercept(in nsIURI aURI, in nsIChannel aChannel);
 256
 257     /**
 258      * Notification when a given intercepted channel is prepared to accept a synthesized
 259      * response via the provided stream.
 260      *
 261      * @param aChannel the controlling interface for a channel that has been intercepted
 262      */
 263     void channelIntercepted(in nsIInterceptedChannel aChannel);
 264 };