uriloader/preload/PreloaderBase.h

   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 #ifndef PreloaderBase_h__
   6 #define PreloaderBase_h__
   7
   8 #include "mozilla/Maybe.h"
   9 #include "mozilla/PreloadHashKey.h"
  10 #include "mozilla/WeakPtr.h"
  11 #include "nsCOMPtr.h"
  12 #include "nsISupports.h"
  13 #include "nsITimer.h"
  14 #include "nsIURI.h"
  15 #include "nsIWeakReferenceUtils.h"
  16 #include "nsTArray.h"
  17
  18 class nsIChannel;
  19 class nsINode;
  20 class nsIRequest;
  21 class nsIStreamListener;
  22
  23 namespace mozilla {
  24
  25 namespace dom {
  26
  27 class Document;
  28
  29 }  // namespace dom
  30
  31 /**
  32  * A half-abstract base class that resource loaders' respective
  33  * channel-listening classes should derive from.  Provides a unified API to
  34  * register the load or preload in a document scoped service, links <link
  35  * rel="preload"> DOM nodes with the load progress and provides API to possibly
  36  * consume the data by later, dynamically discovered consumers.
  37  *
  38  * This class is designed to be used only on the main thread.
  39  */
  40 class PreloaderBase : public SupportsWeakPtr, public nsISupports {
  41  public:
  42   PreloaderBase() = default;
  43
  44   // Called by resource loaders to register this preload in the document's
  45   // preload service to provide coalescing, and access to the preload when it
  46   // should be used for an actual load.
  47   void NotifyOpen(const PreloadHashKey& aKey, dom::Document* aDocument,
  48                   bool aIsPreload, bool aIsModule = false);
  49   void NotifyOpen(const PreloadHashKey& aKey, nsIChannel* aChannel,
  50                   dom::Document* aDocument, bool aIsPreload,
  51                   bool aIsModule = false);
  52
  53   // Called when the load is about to be started all over again and thus this
  54   // PreloaderBase will be registered again with the same key.  This method
  55   // taks care to deregister this preload prior to that.
  56   // @param aNewPreloader: If there is a new request and loader created for the
  57   // restarted load, we will pass any necessary information into it.
  58   void NotifyRestart(dom::Document* aDocument,
  59                      PreloaderBase* aNewPreloader = nullptr);
  60
  61   // Called by the loading object when the channel started to load
  62   // (OnStartRequest or equal) and when it finished (OnStopRequest or equal)
  63   void NotifyStart(nsIRequest* aRequest);
  64   void NotifyStop(nsIRequest* aRequest, nsresult aStatus);
  65   // Use this variant only in complement to NotifyOpen without providing a
  66   // channel.
  67   void NotifyStop(nsresult aStatus);
  68
  69   // Called by resource loaders or any suitable component to notify the preload
  70   // has been used for an actual load.  This is intended to stop any usage
  71   // timers.
  72   // @param aDropLoadBackground: If `Keep` then the loading channel, if still in
  73   // progress, will not be removed the LOAD_BACKGROUND flag, for instance XHR is
  74   // the user here.
  75   enum class LoadBackground { Keep, Drop };
  76   void NotifyUsage(dom::Document* aDocument,
  77                    LoadBackground aLoadBackground = LoadBackground::Drop);
  78   // Whether this preloader has been used for a regular/actual load or not.
  79   bool IsUsed() const { return mIsUsed; }
  80
  81   // Removes itself from the document's preloads hashtable
  82   void RemoveSelf(dom::Document* aDocument);
  83
  84   // When a loader starting an actual load finds a preload, the data can be
  85   // delivered using this method.  It will deliver stream listener notifications
  86   // as if it were coming from the resource loading channel.  The |request|
  87   // argument will be the channel that loaded/loads the resource.
  88   // This method must keep to the nsIChannel.AsyncOpen contract.  A loader is
  89   // not obligated to re-implement this method when not necessarily needed.
  90   virtual nsresult AsyncConsume(nsIStreamListener* aListener);
  91
  92   // Accessor to the resource loading channel.
  93   nsIChannel* Channel() const { return mChannel; }
  94
  95   // Helper function to set the LOAD_BACKGROUND flag on channel initiated by
  96   // <link rel=preload>.  This MUST be used before the channel is AsyncOpen'ed.
  97   static void AddLoadBackgroundFlag(nsIChannel* aChannel);
  98
  99   // These are linking this preload to <link rel="preload"> DOM nodes.  If we
 100   // are already loaded, immediately notify events on the node, otherwise wait
 101   // for NotifyStop() call.
 102   void AddLinkPreloadNode(nsINode* aNode);
 103   void RemoveLinkPreloadNode(nsINode* aNode);
 104
 105   // A collection of redirects, the main consumer is fetch.
 106   class RedirectRecord {
 107    public:
 108     RedirectRecord(uint32_t aFlags, already_AddRefed<nsIURI> aURI)
 109         : mFlags(aFlags), mURI(aURI) {}
 110
 111     uint32_t Flags() const { return mFlags; }
 112     nsCString Spec() const;
 113     nsCString Fragment() const;
 114
 115    private:
 116     uint32_t mFlags;
 117     nsCOMPtr<nsIURI> mURI;
 118   };
 119
 120   const nsTArray<RedirectRecord>& Redirects() { return mRedirectRecords; }
 121
 122   void SetForEarlyHints() { mIsEarlyHintsPreload = true; }
 123
 124  protected:
 125   virtual ~PreloaderBase();
 126
 127   // The loading channel.  This will update when a redirect occurs.
 128   nsCOMPtr<nsIChannel> mChannel;
 129
 130  private:
 131   void NotifyNodeEvent(nsINode* aNode);
 132   void CancelUsageTimer();
 133
 134   void ReportUsageTelemetry();
 135
 136   // A helper class that will update the PreloaderBase.mChannel member when a
 137   // redirect happens, so that we can reprioritize or cancel when needed.
 138   // Having a separate class instead of implementing this on PreloaderBase
 139   // directly is to keep PreloaderBase as simple as possible so that derived
 140   // classes don't have to deal with calling super when implementing these
 141   // interfaces from some reason as well.
 142   class RedirectSink;
 143
 144   // A timer callback to trigger the unuse warning for this preload
 145   class UsageTimer final : public nsITimerCallback, public nsINamed {
 146     NS_DECL_ISUPPORTS
 147     NS_DECL_NSITIMERCALLBACK
 148     NS_DECL_NSINAMED
 149
 150     UsageTimer(PreloaderBase* aPreload, dom::Document* aDocument);
 151
 152    private:
 153     ~UsageTimer() = default;
 154
 155     WeakPtr<dom::Document> mDocument;
 156     WeakPtr<PreloaderBase> mPreload;
 157   };
 158
 159  private:
 160   // Reference to HTMLLinkElement DOM nodes to deliver onload and onerror
 161   // notifications to.
 162   nsTArray<nsWeakPtr> mNodes;
 163
 164   // History of redirects.
 165   nsTArray<RedirectRecord> mRedirectRecords;
 166
 167   // Usage timer, emits warning when the preload is not used in time.  Started
 168   // in NotifyOpen and stopped in NotifyUsage.
 169   nsCOMPtr<nsITimer> mUsageTimer;
 170
 171   // The key this preload has been registered under.  We want to remember it to
 172   // be able to deregister itself from the document's preloads.
 173   PreloadHashKey mKey;
 174
 175   // This overrides the final event we send to DOM nodes to be always 'load'.
 176   // Modified in NotifyStart based on LoadInfo data of the loading channel.
 177   bool mShouldFireLoadEvent = false;
 178
 179   // True after call to NotifyUsage.
 180   bool mIsUsed = false;
 181
 182   // True after we have reported the usage telemetry.  Prevent duplicates.
 183   bool mUsageTelementryReported = false;
 184
 185   // True when this is used to Early Hints preload.
 186   bool mIsEarlyHintsPreload = false;
 187
 188   // Emplaced when the data delivery has finished, in NotifyStop, holds the
 189   // result of the load.
 190   Maybe<nsresult> mOnStopStatus;
 191 };
 192
 193 }  // namespace mozilla
 194
 195 #endif  // !PreloaderBase_h__