netwerk/base/nsBaseChannel.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   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 #ifndef nsBaseChannel_h__
   7 #define nsBaseChannel_h__
   8
   9 #include "mozilla/dom/MimeType.h"
  10 #include "mozilla/Maybe.h"
  11 #include "mozilla/MozPromise.h"
  12 #include "mozilla/UniquePtr.h"
  13 #include "mozilla/net/ContentRange.h"
  14 #include "mozilla/net/NeckoTargetHolder.h"
  15 #include "mozilla/net/PrivateBrowsingChannel.h"
  16 #include "nsHashPropertyBag.h"
  17 #include "nsIAsyncVerifyRedirectCallback.h"
  18 #include "nsIBaseChannel.h"
  19 #include "nsIChannel.h"
  20 #include "nsIInterfaceRequestor.h"
  21 #include "nsILoadGroup.h"
  22 #include "nsILoadInfo.h"
  23 #include "nsIProgressEventSink.h"
  24 #include "nsIStreamListener.h"
  25 #include "nsIThreadRetargetableRequest.h"
  26 #include "nsIThreadRetargetableStreamListener.h"
  27 #include "nsITransport.h"
  28 #include "nsITransportSecurityInfo.h"
  29 #include "nsIURI.h"
  30 #include "nsInputStreamPump.h"
  31 #include "nsString.h"
  32 #include "nsThreadUtils.h"
  33 #include "nsCOMPtr.h"
  34
  35 class nsIInputStream;
  36 class nsICancelable;
  37
  38 //-----------------------------------------------------------------------------
  39 // nsBaseChannel is designed to be subclassed.  The subclass is responsible for
  40 // implementing the OpenContentStream method, which will be called by the
  41 // nsIChannel::AsyncOpen and nsIChannel::Open implementations.
  42 //
  43 // nsBaseChannel implements nsIInterfaceRequestor to provide a convenient way
  44 // for subclasses to query both the nsIChannel::notificationCallbacks and
  45 // nsILoadGroup::notificationCallbacks for supported interfaces.
  46 //
  47 // nsBaseChannel implements nsITransportEventSink to support progress & status
  48 // notifications generated by the transport layer.
  49
  50 class nsBaseChannel
  51     : public nsHashPropertyBag,
  52       public nsIBaseChannel,
  53       public nsIChannel,
  54       public nsIThreadRetargetableRequest,
  55       public nsIInterfaceRequestor,
  56       public nsITransportEventSink,
  57       public nsIAsyncVerifyRedirectCallback,
  58       public mozilla::net::PrivateBrowsingChannel<nsBaseChannel>,
  59       public mozilla::net::NeckoTargetHolder,
  60       protected nsIThreadRetargetableStreamListener {
  61  public:
  62   NS_DECL_ISUPPORTS_INHERITED
  63   NS_DECL_NSIREQUEST
  64   NS_DECL_NSICHANNEL
  65   NS_DECL_NSIBASECHANNEL
  66   NS_DECL_NSIINTERFACEREQUESTOR
  67   NS_DECL_NSITRANSPORTEVENTSINK
  68   NS_DECL_NSIASYNCVERIFYREDIRECTCALLBACK
  69   NS_DECL_NSITHREADRETARGETABLEREQUEST
  70   NS_DECL_NSITHREADRETARGETABLESTREAMLISTENER
  71
  72   nsBaseChannel();
  73
  74  protected:
  75   // -----------------------------------------------
  76   // Methods to be implemented by the derived class:
  77
  78   virtual ~nsBaseChannel();
  79
  80   using BlockingPromise = mozilla::MozPromise<nsresult, nsresult, true>;
  81
  82  private:
  83   // Implemented by subclass to supply data stream.  The parameter, async, is
  84   // true when called from nsIChannel::AsyncOpen and false otherwise.  When
  85   // async is true, the resulting stream will be used with a nsIInputStreamPump
  86   // instance.  This means that if it is a non-blocking stream that supports
  87   // nsIAsyncInputStream that it will be read entirely on the main application
  88   // thread, and its AsyncWait method will be called whenever ReadSegments
  89   // returns NS_BASE_STREAM_WOULD_BLOCK.  Otherwise, if the stream is blocking,
  90   // then it will be read on one of the background I/O threads, and it does not
  91   // need to implement ReadSegments.  If async is false, this method may return
  92   // NS_ERROR_NOT_IMPLEMENTED to cause the basechannel to implement Open in
  93   // terms of AsyncOpen (see NS_ImplementChannelOpen).
  94   // A callee is allowed to return an nsIChannel instead of an nsIInputStream.
  95   // That case will be treated as a redirect to the new channel.  By default
  96   // *channel will be set to null by the caller, so callees who don't want to
  97   // return one an just not touch it.
  98   virtual nsresult OpenContentStream(bool async, nsIInputStream** stream,
  99                                      nsIChannel** channel) = 0;
 100
 101   // Implemented by subclass to begin pumping data for an async channel, in
 102   // lieu of returning a stream. If implemented, OpenContentStream will never
 103   // be called for async channels. If not implemented, AsyncOpen will fall
 104   // back to OpenContentStream.
 105   //
 106   // On success, the callee must begin pumping data to the stream listener,
 107   // and at some point call OnStartRequest followed by OnStopRequest.
 108   //
 109   // Additionally, when a successful nsresult is returned, then the subclass
 110   // should be setting  through its two out params either:
 111   // - a request object, which may be used to suspend, resume, and cancel
 112   //   the underlying request.
 113   // - or a cancelable object (e.g. when a request can't be returned right away
 114   //   due to some async work needed to retrieve it). which may be used to
 115   //   cancel the underlying request (e.g. because the channel has been
 116   //   canceled)
 117   //
 118   // Not returning a request or cancelable leads to potentially leaking the
 119   // an underling stream pump (which would keep to be pumping data even after
 120   // the channel has been canceled and nothing is going to handle the data
 121   // available, e.g. see Bug 1706594).
 122   virtual nsresult BeginAsyncRead(nsIStreamListener* listener,
 123                                   nsIRequest** request,
 124                                   nsICancelable** cancelableRequest) {
 125     return NS_ERROR_NOT_IMPLEMENTED;
 126   }
 127
 128   // This method may return a promise that will keep the input stream pump
 129   // suspended until the promise is resolved or rejected.  On resolution the
 130   // pump is resumed.  On rejection the channel is canceled with the resulting
 131   // error and then the pump is also resumed to propagate the error to the
 132   // channel listener.  Use it to do any asynchronous/background tasks you need
 133   // to finish prior calling OnStartRequest of the listener.  This method is
 134   // called right after OpenContentStream() with async == true, after the input
 135   // stream pump has already been called asyncRead().
 136   virtual nsresult ListenerBlockingPromise(BlockingPromise** aPromise) {
 137     NS_ENSURE_ARG(aPromise);
 138     *aPromise = nullptr;
 139     return NS_OK;
 140   }
 141
 142   // The basechannel calls this method from its OnTransportStatus method to
 143   // determine whether to call nsIProgressEventSink::OnStatus in addition to
 144   // nsIProgressEventSink::OnProgress.  This method may be overriden by the
 145   // subclass to enable nsIProgressEventSink::OnStatus events.  If this method
 146   // returns true, then the statusArg out param specifies the "statusArg" value
 147   // to pass to the OnStatus method.  By default, OnStatus messages are
 148   // suppressed.  The status parameter passed to this method is the status value
 149   // from the OnTransportStatus method.
 150   virtual bool GetStatusArg(nsresult status, nsString& statusArg) {
 151     return false;
 152   }
 153
 154   // Called when the callbacks available to this channel may have changed.
 155   virtual void OnCallbacksChanged() {}
 156
 157   // Called when our channel is done, to allow subclasses to drop resources.
 158   virtual void OnChannelDone() {}
 159
 160  public:
 161   // ----------------------------------------------
 162   // Methods provided for use by the derived class:
 163
 164   // Redirect to another channel.  This method takes care of notifying
 165   // observers of this redirect as well as of opening the new channel, if asked
 166   // to do so.  It also cancels |this| with the status code
 167   // NS_BINDING_REDIRECTED.  A failure return from this method means that the
 168   // redirect could not be performed (no channel was opened; this channel
 169   // wasn't canceled.)  The redirectFlags parameter consists of the flag values
 170   // defined on nsIChannelEventSink.
 171   nsresult Redirect(nsIChannel* newChannel, uint32_t redirectFlags,
 172                     bool openNewChannel);
 173
 174   // Tests whether a type hint was set. Subclasses can use this to decide
 175   // whether to call SetContentType.
 176   // NOTE: This is only reliable if the subclass didn't itself call
 177   // SetContentType, and should also not be called after OpenContentStream.
 178   bool HasContentTypeHint() const;
 179
 180   // The URI member should be initialized before the channel is used, and then
 181   // it should never be changed again until the channel is destroyed.
 182   nsIURI* URI() { return mURI; }
 183   void SetURI(nsIURI* uri) {
 184     NS_ASSERTION(uri, "must specify a non-null URI");
 185     NS_ASSERTION(!mURI, "must not modify URI");
 186     NS_ASSERTION(!mOriginalURI, "how did that get set so early?");
 187     mURI = uri;
 188     mOriginalURI = uri;
 189   }
 190   nsIURI* OriginalURI() { return mOriginalURI; }
 191
 192   // The security info is a property of the transport-layer, which should be
 193   // assigned by the subclass.
 194   nsITransportSecurityInfo* SecurityInfo() { return mSecurityInfo; }
 195   void SetSecurityInfo(nsITransportSecurityInfo* info) { mSecurityInfo = info; }
 196
 197   // Test the load flags
 198   bool HasLoadFlag(uint32_t flag) { return (mLoadFlags & flag) != 0; }
 199
 200   // This is a short-cut to calling nsIRequest::IsPending()
 201   virtual bool Pending() const {
 202     return mPumpingData || mWaitingOnAsyncRedirect;
 203   }
 204
 205   // Helper function for querying the channel's notification callbacks.
 206   template <class T>
 207   void GetCallback(nsCOMPtr<T>& result) {
 208     GetInterface(NS_GET_TEMPLATE_IID(T), getter_AddRefs(result));
 209   }
 210
 211   // If a subclass does not want to feed transport-layer progress events to the
 212   // base channel via nsITransportEventSink, then it may set this flag to cause
 213   // the base channel to synthesize progress events when it receives data from
 214   // the content stream.  By default, progress events are not synthesized.
 215   void EnableSynthesizedProgressEvents(bool enable) {
 216     mSynthProgressEvents = enable;
 217   }
 218
 219   // Some subclasses may wish to manually insert a stream listener between this
 220   // and the channel's listener.  The following methods make that possible.
 221   void SetStreamListener(nsIStreamListener* listener) { mListener = listener; }
 222   nsIStreamListener* StreamListener() { return mListener; }
 223
 224  protected:
 225   void DisallowThreadRetargeting() { mAllowThreadRetargeting = false; }
 226
 227   virtual void SetupNeckoTarget();
 228
 229  private:
 230   NS_DECL_NSISTREAMLISTENER
 231   NS_DECL_NSIREQUESTOBSERVER
 232
 233   // Called to setup mPump and call AsyncRead on it.
 234   nsresult BeginPumpingData();
 235
 236   // Called when the callbacks available to this channel may have changed.
 237   void CallbacksChanged() {
 238     mProgressSink = nullptr;
 239     mQueriedProgressSink = false;
 240     OnCallbacksChanged();
 241   }
 242
 243   // Called when our channel is done.  This should drop no-longer-needed
 244   // pointers.
 245   void ChannelDone() {
 246     mListener = nullptr;
 247     OnChannelDone();
 248   }
 249
 250   // Handle an async redirect callback.  This will only be called if we
 251   // returned success from AsyncOpen while posting a redirect runnable.
 252   void HandleAsyncRedirect(nsIChannel* newChannel);
 253   void ContinueHandleAsyncRedirect(nsresult result);
 254   nsresult ContinueRedirect();
 255
 256   // start URI classifier if requested
 257   void ClassifyURI();
 258
 259   class RedirectRunnable : public mozilla::Runnable {
 260    public:
 261     RedirectRunnable(nsBaseChannel* chan, nsIChannel* newChannel)
 262         : mozilla::Runnable("nsBaseChannel::RedirectRunnable"),
 263           mChannel(chan),
 264           mNewChannel(newChannel) {
 265       MOZ_ASSERT(newChannel, "Must have channel to redirect to");
 266     }
 267
 268     NS_IMETHOD Run() override {
 269       mChannel->HandleAsyncRedirect(mNewChannel);
 270       return NS_OK;
 271     }
 272
 273    private:
 274     RefPtr<nsBaseChannel> mChannel;
 275     nsCOMPtr<nsIChannel> mNewChannel;
 276   };
 277   friend class RedirectRunnable;
 278
 279   RefPtr<nsInputStreamPump> mPump;
 280   RefPtr<nsIRequest> mRequest;
 281   nsCOMPtr<nsICancelable> mCancelableAsyncRequest;
 282   bool mPumpingData{false};
 283   nsCOMPtr<nsIProgressEventSink> mProgressSink;
 284   nsCOMPtr<nsIURI> mOriginalURI;
 285   nsCOMPtr<nsISupports> mOwner;
 286   nsCOMPtr<nsITransportSecurityInfo> mSecurityInfo;
 287   nsCOMPtr<nsIChannel> mRedirectChannel;
 288   uint32_t mLoadFlags{LOAD_NORMAL};
 289   bool mQueriedProgressSink{true};
 290   bool mSynthProgressEvents{false};
 291   bool mAllowThreadRetargeting{true};
 292   bool mWaitingOnAsyncRedirect{false};
 293   bool mOpenRedirectChannel{false};
 294   uint32_t mRedirectFlags{0};
 295   RefPtr<mozilla::net::ContentRange> mContentRange;
 296   RefPtr<CMimeType> mFullMimeType;
 297
 298  protected:
 299   nsCString mContentType;
 300   nsCString mContentCharset;
 301   nsCOMPtr<nsIURI> mURI;
 302   nsCOMPtr<nsILoadGroup> mLoadGroup;
 303   nsCOMPtr<nsILoadInfo> mLoadInfo;
 304   nsCOMPtr<nsIInterfaceRequestor> mCallbacks;
 305   nsCOMPtr<nsIStreamListener> mListener;
 306   nsresult mStatus{NS_OK};
 307   uint32_t mContentDispositionHint{UINT32_MAX};
 308   mozilla::UniquePtr<nsString> mContentDispositionFilename;
 309   int64_t mContentLength{-1};
 310   bool mWasOpened{false};
 311   bool mCanceled{false};
 312
 313   friend class mozilla::net::PrivateBrowsingChannel<nsBaseChannel>;
 314 };
 315
 316 #endif  // !nsBaseChannel_h__